Installation Guide for Image Verification

Table of Contents

  1. Steps for Image Verification
  2. Prerequisites
  3. Sign Image using cosign
  4. Configure Kyverno to use a custom certificate for ImageRegistry (Optional)
  5. Verify Image using Kyverno

Steps for Image Verification

Below are the steps to verify images before deployment to Kubernetes runtime environments:

  1. Deploy Enterprise Kyverno to the Workload cluster
  2. (Optional) If your local image registry uses a custom CA, configure Kyverno to use this custom CA for verifying locally hosted images
  3. Leverage cosign cli to sign the images. Ensure that the node where cosign is installed has the private CA added to its keystore
  4. Deploy the image verification Kyverno policy
  5. Confirm image verification based on policy pass/fail

Prerequisites

  • Install cosign: Installation Guide
  • Keep the full chain certs handy for the configurations

Sign Image using cosign

To sign your container images, you’ll need to generate a key pair and use it to sign your images. This process ensures the authenticity and integrity of your container images.

Generate key pair

cosign generate-key-pair

This command creates two files: cosign.key (private key) and cosign.pub (public key).

Sign the image

cosign sign --key cosign.key harbor.nirmata.co/test/nginx:1.18

Replace harbor.nirmata.co/test/nginx:1.18 with your actual image reference in the format <registry>/<repository>/<image>:<tag>

Confirm the image signature by logging in to the image registry.

Configure Kyverno to use a custom certificate for ImageRegistry

Note: This step is only required if you are using a private registry with custom certificates. If you are using a public registry or a private registry with standard certificates, you can skip this section and proceed to Verify Image using Kyverno.

To enable Kyverno to verify images from a registry with a custom CA, you need to provide the CA certificates to Kyverno.

  1. Create a configMap with all root and intermediate certificates (full chain) of the private CA:
kubectl create cm kyverno-certs --from-file=ca-certificates=harbor-ca.crt -n kyverno
  1. Mount the configmap as volume in Kyverno admission controller deployment:
apiVersion: apps/v1
kind: Deployment
metadata:
  name: kyverno
  namespace: kyverno
spec:
  template:
    spec:
      containers:
      - args:
        - --autogenInternals=true
        - -v=4
        image: ghcr.io/kyverno/kyverno:v1.7.0-rc1
        name: kyverno
        volumeMounts:
        - mountPath: /.sigstore
          name: sigstore
        - name: ca-certificates
          mountPath: /usr/local/share/ca-certificates/ca-certificates.crt
          subPath: ca-certificates.crt
      volumes:
      - name: sigstore
      - name: ca-certificates
        configMap:
          name: kyverno-certs
          items:
          - key: ca-certificates
            path: ca-certificates.crt

Important Note: The certificate mount path (/usr/local/share/ca-certificates/ca-certificates.crt) may vary depending on your node’s operating system. Adjust this path according to your environment.

Verify Image using Kyverno

  1. Create a Kyverno image verify policy (Note: change the key in the policy yaml with the one created in the above step)

    You can find example image verification policies in the Nirmata Kyverno Policies repository under the VerifyImage directory. These policies provide templates for implementing image verification in your cluster.

  2. Test the image verification by attempting to deploy pods with different images:

# This should succeed if the image is properly signed
kubectl run pod --image=harbor.nirmata.co/test/nginx:1.18 -n demo

# This should fail if the image is not signed or signed with a different key
kubectl run pod --image=harbor.nirmata.co/test1/nginx:1.15 -n demo

The first command should succeed if the image is properly signed with your cosign key. The second command should fail if the image is either unsigned or signed with a different key, demonstrating that the image verification policy is working as expected.

Navigate to Monitor –> Events in Nirmata to check the blocked pod events and view the policy reference details.