k8wiz
All graphs

Flux CD graph

Cosign with GitLab CI, Cloud KMS and Flux

A GitLab pipeline signs an image and a Flux OCI artifact of Kustomize manifests with a Cloud KMS key it reaches through Workload Identity Federation. Flux verifies the artifact with the public key before it applies anything.

Two things get signed here: the container image, and the Kustomize manifests that deploy it, pushed to Artifact Registry as a Flux OCI artifact. Both are OCI digests, so cosign signs them the same way, with one asymmetric key in Cloud KMS.

The private key never leaves KMS. GitLab doesn't hold a secret either: the job trades its own OIDC token for short-lived Google credentials through Workload Identity Federation, and only pipelines on protected refs of one project may use the key. The cluster gets the public key only. Flux checks the manifests with it, and an admission controller checks the images.

Interactive graph

Click a resource to see what it does, or follow the setup step by step.

Outside the clusterMade by a toolYou write itComes with an add-onCreated by a controllertrafficreferencescreates

How it works

All 15 resources and what they do

CI job release (.gitlab-ci.yml)
Runs on protected refs only. It exchanges its GitLab ID token for Google credentials, builds and signs the image, pins the image digest in the Kustomize overlay, pushes the manifests with flux push artifact and signs that digest too. It holds no key and no service account JSON.
OIDC provider gitlab.com
Issues the job an ID token for the audience named in id_tokens. Its claims say which project, ref and pipeline the job belongs to, for example project_path: acme/shop, ref: main, ref_protected: "true", and sub: project_path:acme/shop:ref_type:branch:ref:main.
Workload Identity pool gitlab provider
Trusts tokens from https://gitlab.com, maps claims to attributes and rejects tokens that fail the attribute condition, such as assertion.project_path == "acme/shop" && assertion.ref_protected == "true". This condition decides who can sign. Google's STS then trades the token for a short-lived federated token.
Service account cosign-signer@acme.iam
The identity the job impersonates. It has roles/cloudkms.signerVerifier on the one signing key and write access to the Artifact Registry repository, nothing else. The federated principal for acme/shop has roles/iam.workloadIdentityUser on it.
KMS key release/cosign (EC P-256)
An asymmetric signing key, ec-sign-p256-sha256. cosign sends it a digest to sign and gets a signature back; the private key can't be exported. Audit logs record every signing call. Rotation adds a key version; old versions can be disabled to stop new signatures.
Image shop@sha256:aaa…
The container image, built and pushed by the job. Its digest is what gets signed and what the manifests pin.
Signature image signature
Pushed by cosign sign --key gcpkms://…. With cosign 3 it's a Sigstore bundle attached to the image through the referrers API. It holds a signature that only the KMS key's public half verifies.
Flux artifact shop-manifests@sha256:bbb…
The built deploy/production directory, packed by flux push artifact with Flux's media types and the Git source and revision as annotations. The tag production points at it. Because CI ran kustomize edit set image first, the Deployment inside names the image by digest.
Signature manifests signature
The same kind of signature, over the manifests artifact's digest. It's what Flux checks before any YAML reaches the cluster.
Secret cosign-pubv1
The public half of the KMS key, exported with cosign public-key --key gcpkms://…. Flux accepts a signature from any key in the Secret whose name ends in .pub, so during a rotation you list both versions.
OCIRepository shop-manifestssource.toolkit.fluxcd.io/v1
Follows the production tag. provider: gcp makes source-controller pull with its GKE Workload Identity instead of a registry secret. verify makes it check the cosign signature with the public key before it produces an artifact.
Flux controller source-controller
Every interval, resolves production to a digest. When it changes, it verifies the signature for that digest, then downloads and unpacks the layer. A failed check leaves the OCIRepository not ready with the verification error, and the last good artifact stays in use.
Kustomization shopkustomize.toolkit.fluxcd.io/v1
Applies the verified artifact. It only ever sees manifests that passed the signature check.
Deployment shopapps/v1
Applied by the Kustomization from the artifact. Its image is the digest CI signed, so a tag moved in the registry can't change what runs.
Admission check Kyverno or Binary Authorization
Flux verified the YAML, not the images it names. An admission controller checks the image signatures when Pods are created: a Kyverno ImageValidatingPolicy with a cosign key attestor holding the same public key, or GKE Binary Authorization with an attestor backed by the same Cloud KMS key.

Common mistakes

  • A Workload Identity attribute condition that only checks the GitLab group, or no condition at all, lets any project in it, or any GitLab user, sign with your key. Check project_path and ref_protected, and protect the branches and tags that release.
  • Grant roles/cloudkms.signerVerifier on the key, not the project. A project-level grant lets the signer use every key in the project.
  • cosign records key-based signatures in Sigstore's public Rekor log by default, which exposes registry paths and digests. Decide whether that's acceptable, and check your cosign version's flags if it isn't.
  • Cosign 3 attaches signatures as Sigstore bundles through referrers. Sign one test artifact and confirm the OCIRepository verifies it with your Flux version before you switch production.
  • Flux verifies the manifests artifact, not the images it references. Without an admission check, an unsigned image deployed with kubectl or another tool still runs.
  • Removing the old public key from cosign-pub right after a rotation breaks the next reconcile of every artifact still signed with it. Keep both keys until all current artifacts are re-signed or replaced.

The manifests you write

Everything above that is marked "You write it", in one file. The rest comes from add-ons and controllers.

apiVersion: v1
kind: Secret
metadata:
  name: cosign-pub
  namespace: flux-system
stringData:
  cosign.pub: |
    -----BEGIN PUBLIC KEY-----
    MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE…
    -----END PUBLIC KEY-----
---
apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
  name: shop-manifests
  namespace: flux-system
spec:
  interval: 5m
  url: oci://europe-west1-docker.pkg.dev/acme/apps/shop-manifests
  ref:
    tag: production
  provider: gcp
  verify:
    provider: cosign
    secretRef:
      name: cosign-pub
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: shop
  namespace: flux-system
spec:
  interval: 10m
  sourceRef:
    kind: OCIRepository
    name: shop-manifests
  path: ./
  prune: true

Keep going

More graphs