apiVersion: policies.kyverno.io/v1
kind: ImageValidatingPolicy
metadata:
name: require-signed-shop
spec:
validationActions: [Deny]
matchConstraints:
resourceRules:
- apiGroups: [""]
apiVersions: ["v1"]
operations: ["CREATE", "UPDATE"]
resources: ["pods"]
matchImageReferences:
- glob: "ghcr.io/acme/*"
attestors:
- name: release
cosign:
keyless:
identities:
- issuer: https://token.actions.githubusercontent.com
subject: https://github.com/acme/shop/.github/workflows/release.yaml@refs/heads/main
validationConfigurations:
mutateDigest: true
verifyDigest: true
required: true
validations:
- expression: >-
images.containers.map(image, verifyImageSignatures(image, [attestors.release])).all(e, e > 0)
message: shop images must be signed by the release workflow on main
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: shop
namespace: shop
spec:
replicas: 2
selector:
matchLabels:
app: shop
template:
metadata:
labels:
app: shop
spec:
containers:
- name: shop
image: ghcr.io/acme/shop:4f2c8e1Kyverno graph
Cosign: keyless image signing, attestations and verification with Kyverno
How a CI job signs an image with cosign and no long-lived key: an OIDC token, a 10-minute Fulcio certificate, a Rekor log entry and a Sigstore bundle attached to the image. Kyverno checks all of it before a Pod may run.
Cosign signs container images and other OCI artifacts. In keyless mode, the usual one in CI, there is no private key to store or rotate. The job proves who it is with an OIDC token, Sigstore's Fulcio CA turns that identity into a certificate that is valid for 10 minutes, and the Rekor transparency log records that the signature existed while the certificate was valid.
Cosign 3 stores the signature, the certificate and the log proof together in one Sigstore bundle, attached to the image through the OCI referrers API, so the image digest never changes. A Kyverno ImageValidatingPolicy reads those referrers at admission and admits a Pod only if a trusted identity signed its image.
Interactive graph
Click a resource to see what it does, or follow the setup step by step.
How it works
All 12 resources and what they do
- CI job release workflow
- Builds and pushes the image, then signs the digest it pushed with
cosign sign --yes.id-token: writelets the job request an OIDC token from GitHub. The job's identity is the workflow file and the ref it ran from. - OIDC provider token.actions.githubusercontent.com
- Issues the job a short-lived ID token. Its
subandjob_workflow_refclaims name the repository, workflow and ref, which become the identity in the certificate. The issuer URL is the second half of every keyless trust rule. - Certificate authority Fulcio
- Checks the ID token, then issues a code-signing certificate for the public half of a key pair cosign generated in memory. The certificate binds that key to the workflow identity and the issuer, and it expires after 10 minutes. The private key is thrown away after signing.
- Transparency log Rekor
- An append-only public log. Cosign records the signature and certificate there and gets back a signed entry with a timestamp. That entry proves the signature was made while the 10-minute certificate was valid, so it still verifies years later. Anyone can search the log for signatures made with their identity.
- Trust root Sigstore TUF root
- Distributes, through TUF, the Fulcio root certificates and the Rekor public keys that verifiers trust, plus the service URLs cosign 3 uses when signing. cosign and Kyverno fetch and cache it, so a key rotation doesn't need a new release.
- Image index ghcr.io/acme/shop@sha256:5e1a…
- What gets signed: the digest, not the tag. A tag can be moved to other content after signing; the digest is the hash of the exact bytes. Signing never changes this manifest, so the digest stays the same.
- Signature Sigstore bundle
- Pushed by
cosign sign. One manifest whose single layer is the bundle: the signature over the image digest, the Fulcio certificate and the Rekor entry with its inclusion proof. Itssubjectpoints at the image, soGET /v2/acme/shop/referrers/sha256:5e1a…lists it. - Attestation SBOM (SPDX)
- Pushed by
cosign attest --type spdxjson --predicate sbom.spdx.json. An in-toto statement says "this SBOM describes image sha256:5e1a…" and is signed the same keyless way. It's another referrer of the image, so it travels with the image to every registry that copies it with its referrers. - ImageValidatingPolicy require-signed-shoppolicies.kyverno.io/v1
- Matches images under
ghcr.io/acme/*and trusts exactly one identity: the release workflow onmain, as vouched for by GitHub's issuer.mutateDigestrewrites tags to the verified digest, so the node runs what was checked. - Admission controller kyverno-admission-controller
- Kyverno's webhook. For each matching image it resolves the tag to a digest, lists the image's referrers, and checks each bundle: the certificate chains to Fulcio, the identity and issuer match an attestor, the Rekor entry is valid, and the signature covers this digest. It needs registry credentials for private images.
- Deployment shopapps/v1
- Refers to the image by tag, as most manifests do. The policy checks the Pods its ReplicaSet creates.
- Pod shop-7d9c…v1
- Admitted only after verification. With
mutateDigest, its image readsghcr.io/acme/shop:4f2c8e1@sha256:5e1a…, so a tag moved after admission can't change what the kubelet pulls.
Common mistakes
- Trusting any identity from an issuer, such as
subject: "*"with GitHub's issuer, trusts every repository on GitHub. Pin the repository, the workflow file and the ref. - Signing a tag (
cosign sign ghcr.io/acme/shop:latest) signs whatever the tag points at when cosign resolves it. Use the digest from the build step's output. - Cosign 3 attaches bundles through the referrers API. A verifier, mirror or registry-copying tool that only knows the old
sha256-….sigtags won't find them. Copy referrers along with images, and check that every verifier in the path reads bundles. - Private registries: Kyverno needs pull credentials to read referrers. Without them verification fails even though the kubelet, which has its own pull secret, could pull the image.
- A policy that matches only Pods lets an unsigned Deployment through, and its ReplicaSet then fails to create Pods.
kubectl describe rsshows the denial inFailedCreateevents. - Kyverno's webhook only checks new requests. Pods that were running before the policy existed keep running until they are recreated; policy reports list them.
The manifests you write
Everything above that is marked "You write it", in one file. The rest comes from add-ons and controllers.
Keep going
More graphs
- Deployment, Service and Ingress: how a request reaches your Pods
- Gateway API: GatewayClass, Gateway and HTTPRoute with a canary split
- PVC, StorageClass and CSI: how a cloud disk ends up in your Pod
- RBAC: how a ServiceAccount gets its permissions
- cert-manager with Let's Encrypt: Certificate, CertificateRequest, Order and Challenge
- A private CA with cert-manager and trust-manager
- Istio traffic management: Gateway, VirtualService, DestinationRule and policies
- Flux dependencies: Git and OCI sources, Kustomizations and HelmReleases
- Argo CD: ApplicationSet, AppProject and the Applications it generates
- Inside an OCI image: tag, index, manifests, config and layers
- OCI artifacts: Helm charts, Flux artifacts and image volumes
- A Helm release: chart, values, revisions and the objects Helm owns
- Kustomize: a base, two overlays, a component and generated ConfigMaps
- A StatefulSet database: headless Service, per-Pod volumes, snapshots and restore
- Autoscaling end to end: KEDA, the HPA it creates and Karpenter adding nodes
- Prometheus Operator: ServiceMonitor, PrometheusRule and the path to an alert
- External Secrets Operator: from a cloud secret manager to a Pod, with rotation
- Kyverno CEL policies: ValidatingPolicy, MutatingPolicy, GeneratingPolicy and exceptions
- Cilium egress to a domain: CiliumNetworkPolicy, the DNS proxy and toFQDNs
- Istio ambient mode: ztunnel, waypoint proxies and authorization without sidecars
- Argo Rollouts canary: traffic weights on an HTTPRoute and analysis from Prometheus
- Agent Substrate: actors, warm workers and snapshots on Kubernetes