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: trueFlux 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.
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 artifactand 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 exampleproject_path: acme/shop,ref: main,ref_protected: "true", andsub: 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 asassertion.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.signerVerifieron the one signing key and write access to the Artifact Registry repository, nothing else. The federated principal foracme/shophasroles/iam.workloadIdentityUseron 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/productiondirectory, packed byflux push artifactwith Flux's media types and the Git source and revision as annotations. The tagproductionpoints at it. Because CI rankustomize edit set imagefirst, 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
productiontag.provider: gcpmakes source-controller pull with its GKE Workload Identity instead of a registry secret.verifymakes it check the cosign signature with the public key before it produces an artifact. - Flux controller source-controller
- Every interval, resolves
productionto 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
ImageValidatingPolicywith 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_pathandref_protected, and protect the branches and tags that release. - Grant
roles/cloudkms.signerVerifieron 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
kubectlor another tool still runs. - Removing the old public key from
cosign-pubright 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.
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
- Cosign: keyless image signing, attestations and verification with Kyverno
- 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