What Is Binary Authorization in GCP? GKE and Cloud Run Explained

What Binary Authorization is

Binary Authorization is a Google Cloud service that enforces image trust at deploy time. You define a policy that specifies which attestors must have signed a container image before it is allowed to run. If the image does not carry the required signatures, the deployment is rejected before it ever starts.

It works with both Google Kubernetes Engine and Cloud Run. On GKE, the check happens at admission time when a pod is created. On Cloud Run, it happens when a service revision is deployed. In both cases, unsigned or improperly attested images are blocked before they can run.

Binary Authorization integrates directly with Artifact Registry and Container Analysis, so your attestation pipeline fits naturally into the rest of your Google Cloud toolchain.

Simple explanation

More technically: when an image is built, it goes through your CI pipeline. Tests run, security scans run, code review happens. At the end of that process, a trusted system (the attestor) signs the image with a cryptographic signature tied to the exact image content. Binary Authorization checks for that signature at deploy time.

The signature is tied to the image digest, not a mutable label like latest. You cannot bypass it by re-tagging an image. The signature is either valid for that exact image or it is not.

Why Binary Authorization matters

IAM tells GKE or Cloud Run who is allowed to deploy. It says nothing about what they deploy. A developer with deployment permissions could deploy:

• An image pulled directly from Docker Hub with no security review
• An image that failed your vulnerability scan but was pushed anyway
• A locally built image that bypassed CI entirely
• A typosquatted image from a registry that looks legitimate

Software supply chain attacks are increasingly common: malicious packages injected into dependencies, compromised build systems, and registries that host images designed to look trustworthy. Binary Authorization creates a cryptographic checkpoint. Only images signed by your own CI system, after all required checks pass, can be deployed to production clusters.

How Binary Authorization works

The full flow from image build to deployment looks like this:

1. Image is built — your CI pipeline (e.g. Cloud Build) builds the container image from source.

2. Image is pushed to Artifact Registry — the image is stored in your private registry, identified by its content digest (SHA-256 hash).

3. Checks run — vulnerability scanning, integration tests, and any other required checks execute in the pipeline.

4. Attestor signs the image digest — if all checks pass, the attestor signs the image digest using its Cloud KMS asymmetric key. This signature is the attestation, stored in Container Analysis.

5. Policy is evaluated at deploy time — when a deployment is attempted, GKE or Cloud Run checks the Binary Authorization policy, which specifies which attestors must have signed the image.

6. Deploy is allowed or blocked — if valid attestations from all required attestors are present, the deployment proceeds. If any are missing or invalid, the deployment is rejected with a policy violation error.

If any check in step 3 fails, the image is never attested. Step 6 will always block it from deploying to an enforcing cluster or service.

Core concepts

Policy

A Binary Authorization policy defines the trust requirements an image must meet before it can be deployed. The policy is attached to a GCP project and evaluated at deploy time. It has a default rule that applies to all images unless a more specific rule exists for a cluster, namespace, or resource.

Policy default rule options:

• ALLOW_ALL — any image can deploy. Useful for dev clusters, but provides no supply chain protection.
• REQUIRE_ATTESTATION — images must have a valid attestation from one or more specified attestors. Use this for all production-equivalent environments.
• ALWAYS_DENY — no images can deploy. Used to hard-lock a cluster except for explicit namespace or resource-level overrides.

Attestors

An attestor is an entity authorised to sign container image digests. Each attestor represents a specific checkpoint in your pipeline. Common examples:

• A vulnerability scanner that attests the image has no critical CVEs
• Your CI system that attests all integration tests passed
• A build attestor that certifies the image came from a known commit in a specific repo

Each attestor is backed by a Cloud KMS asymmetric signing key (or a PGP key). The private key signs the image digest; Binary Authorization verifies the signature using the public key at deploy time. Protecting the signing key is critical. It is effectively the gate key.

Attestations

An attestation is a cryptographic signature proving that a specific image digest has passed a specific check. It is created by the attestor and stored in Container Analysis as a Note/Occurrence pair. When Binary Authorization evaluates a policy, it looks up the attestations for the image digest being deployed and verifies their signatures.

Attestations are tied to image digests, not tags. A signed attestation for digest sha256:abc123… is not valid for any other image content, even if you retag it with the same name.

Image digests vs image tags

Binary Authorization enforces policy on image digests (SHA-256 hashes of the image content), not image tags. A tag like latest or v1.2.3 is mutable. Anyone with registry write access can overwrite it to point to a completely different image. A digest is immutable. The attestation is signed for a specific digest, so reassigning a tag cannot bypass the policy.

Dry-run mode vs enforcement mode

Binary Authorization has two operating modes. The distinction matters a lot in practice:

• Enforcement mode — images that do not meet the policy are blocked at deploy time with a policy violation error. Nothing runs until the policy is satisfied. This is the mode that provides actual security value.

• Dry-run mode — policy violations are logged in Cloud Audit Logs but deployments are not blocked. Images deploy regardless of whether they have valid attestations. Use dry-run to understand what your policy would block before switching to enforcement.

When to use Binary Authorization

Binary Authorization makes sense when you have:

• Production GKE clusters or Cloud Run services running real workloads that need protection against rogue or unreviewed images

• A working CI/CD pipeline that already builds, tests, and scans images. You need a pipeline to create attestations, so Binary Authorization is easiest to add once CI is already solid.

• Multiple developers or teams deploying to the same environment, where you want to guarantee that no one can bypass the standard process

• Regulated or security-sensitive workloads where you need evidence that only reviewed, scanned images were ever run in production

• Multiple environments (staging, production) and you want to enforce that only images which passed staging can reach production

If you are already building on secure CI/CD pipelines, Binary Authorization is a natural extension that enforces those pipelines at the runtime layer.

When Binary Authorization may be too much

Binary Authorization adds real operational overhead. It may not be worth the complexity if:

• You are in early experimentation. A single developer iterating on a proof of concept does not need attestation infrastructure. Save it for when the workload approaches production.

• Your CI pipeline does not exist yet. Binary Authorization requires a pipeline that produces attestations. Get CI working first.

• The environment is truly throwaway. Sandbox clusters created and destroyed for testing, with no access to production data, are reasonable candidates for an ALLOW_ALL policy.

Binary Authorization vs other controls

Binary Authorization is one control in a layered supply chain security posture. It is not a replacement for the controls below. They are all complementary.

The strongest posture combines all of these: org policies restrict the source registry, Artifact Registry scans the image, Binary Authorization requires a passing-scan attestation before deploy, IAM controls who can trigger a deploy, and cluster hardening limits what a running container can access.

Enabling and configuring Binary Authorization

Enabling the API and configuring GKE

# Enable the Binary Authorization API
gcloud services enable binaryauthorization.googleapis.com \
  --project=my-app-prod

# Start in dry-run mode first (strongly recommended)
gcloud container clusters update prod-cluster \
  --location=europe-west2 \
  --binauthz-evaluation-mode=POLICY_BINDINGS_AND_PROJECT_SINGLETON_POLICY_DRYRUN \
  --project=my-app-prod

# Switch to enforcement mode only after validating dry-run logs
gcloud container clusters update prod-cluster \
  --location=europe-west2 \
  --binauthz-evaluation-mode=PROJECT_SINGLETON_POLICY_ENFORCE \
  --project=my-app-prod

Creating an attestor backed by a Cloud KMS key

# Create the attestor (requires a Container Analysis note to exist first)
gcloud container binauthz attestors create vulnerability-scan-attestor \
  --attestation-authority-note=projects/my-app-prod/notes/vulnerability-scan \
  --project=my-app-prod

# Add the Cloud KMS signing key to the attestor
gcloud container binauthz attestors public-keys add \
  --attestor=vulnerability-scan-attestor \
  --keyversion-project=my-app-prod \
  --keyversion-location=europe-west2 \
  --keyversion-keyring=prod-binauthz-ring \
  --keyversion-key=attestor-signing-key \
  --keyversion=1 \
  --project=my-app-prod

Defining a policy

# policy.yaml
# Import with: gcloud container binauthz policy import policy.yaml --project=my-app-prod
defaultAdmissionRule:
  evaluationMode: REQUIRE_ATTESTATION
  enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG
  requireAttestationsBy:
  - projects/my-app-prod/attestors/vulnerability-scan-attestor
globalPolicyEvaluationMode: ENABLE

Enabling Binary Authorization on Cloud Run

# Deploy a Cloud Run service with Binary Authorization enforced
# Note: reference the image by digest, not tag
gcloud run deploy my-service \
  --image=europe-west2-docker.pkg.dev/my-app-prod/images/my-service@sha256:abc123... \
  --binary-authorization=default \
  --region=europe-west2 \
  --project=my-app-prod

The image is referenced by digest, not tag. This ensures the exact attested image is deployed, not whatever a tag happens to point to at deploy time.

Integrating attestation into CI/CD

The attestation step belongs in your Cloud Build pipeline after all required checks have passed. Using Cloud Build to build and push images makes it straightforward to add attestation as a subsequent build step.

1. Build the image and push to Artifact Registry. Capture the image digest.
2. Run vulnerability scanning via Container Analysis.
3. Run integration and security tests.
4. If all checks pass, sign the image digest using the attestor’s Cloud KMS key.
5. The attestation is stored in Container Analysis.
6. Binary Authorization verifies the attestation at deploy time.

If any step fails, the image is not attested. Binary Authorization will block any attempt to deploy it to an enforcing cluster or service.

For a broader look at encoding security rules directly in your pipeline, see Policy as Code in GCP.

Best practices

• Attest in CI after all checks pass, not before. The attestation is a statement that checks passed. Sign only after vulnerability scanning, tests, and any required reviews are complete.

• Protect signing keys with strong IAM. The Cloud KMS signing key is the gate key. Restrict who can use it to sign. Separate signing key access from deployment access. Rotate keys per your key management policy.

• Store images in Artifact Registry. Artifact Registry integrates with Container Analysis for scanning and supports repository-level IAM, giving you another layer of access control before Binary Authorization even runs.

• Reference images by digest in deployment manifests. Tags are mutable. Using a digest ensures the deployed image is exactly the one that was attested, with no possibility of tag substitution.

• Review exemptions and overrides regularly. Cluster-level overrides that allow all images in specific namespaces create gaps. Audit them periodically and remove any that are no longer justified.

• Apply consistent policy across production-equivalent environments. Staging clusters with access to production databases or APIs should have the same Binary Authorization policy as production. Gaps in coverage are gaps in protection.

• Combine with audit logging and alerting. Cloud Audit Logs records every Binary Authorization decision. Set up log-based alerts for policy violations so unexpected blocked deploys surface quickly rather than being discovered hours later.