Key concepts

This page contains information on key concepts related to Binary Authorization.


A policy in Binary Authorization is a set of rules that govern the deployment of container images to Google Kubernetes Engine (GKE). A policy has the following parts:

You can configure a policy using one of the following:

  • Google Cloud Platform Console
  • gcloud commands

When you use gcloud commands, you export and modify a definition of the policy in YAML format before importing it back to your project. The YAML format reflects the internal structure of a policy in Binary Authorization storage. For more information on this format, see Policy YAML Reference.

Each Google Cloud Platform (GCP) project can have exactly one policy. In a single project configuration, this policy governs the deployment to GKE where all resources in the deployment pipeline are part of the same project. For a multi-project configuration, it's possible for single policy to govern the deployment of images from Container Registry in one project to a GKE cluster running in still another project.

For more information, see Configuring a Policy Using the CLI and Configuring a Policy Using the Console.


A rule is the part of a policy that defines constraints that container images must pass before they can be deployed. Most often, a rule specifies which attestors must verify that all required internal processes have completed before deployment. A rule can also allow or deny all deployments from specific Container Registry paths and/or to specific GKE clusters.

You define rules when you configure a policy. A policy has one default rule and any number of cluster-specific rules.

Default rules

Each policy has a default rule. This rule applies to any deployment request that doesn't match a cluster-specific rule. If the policy has no cluster-specific rule, the default rule always applies. In a policy YAML file, the default rule is specified in the defaultAdmissionRule node.

Cluster-specific rules

A policy may also have one or more cluster-specific rules. This type of rule applies to container images that are to be deployed to specific GKE clusters only. In a policy YAML file, each cluster-specific rule is specified in a clusterAdmissionRule node.

Evaluation modes

Each rule has an evaluation mode that specifies the type of constraint that Binary Authorization enforces for the rule. The evaluation mode for a rule is specified using the evaluationMode property in the policy YAML file.

There are three evaluation modes:

  • Allow All Images
  • Deny All Images
  • Require Attestations

A Require Attestations rule requires one or more attestors to digitally sign the image before deployment.

Enforcement modes

Each rule also has an enforcement mode, which specifies the action that is taken by GKE when an image does not conform to the rule. A rule can have the following enforcement modes:

  • Block and Audit Log: Blocks the deployment of images that do not conform to the rule and writes a message to the audit log to indicate why the image was not deployed.

  • Dry Run: Audit Log Only: Allows deployment of non-conformant images, but and writes details about the violation to the audit log.

Most production rules use the Block and Audit Log enforcement mode. Dry Run: Audit Log Only is primarily used for testing a policy in your environment before it goes into effect.

The enforcement mode for a rule is specified using the enforcementMode property in the policy YAML file.

See Viewing audit logs for more information information on messages written to Stackdriver Logging.

Exempt images

An exempt image is a container image that is exempt from policy rules. Binary Authorization always allows exempt images to be deployed. Each project has a whitelist of exempt images specified by registry path. Images in the path*,*, and additional paths are exempt by default, as these contain resources required so that GKE can start a cluster successfully with the default policy active.

The whitelist of exempt images is specified using the admissionWhitelistPatterns property in the policy YAML file.

Whitelist patterns

To whitelist all container images whose registry location matches the specified path:*

To whitelist a specific image:

To whitelist a specific version of an image by tag:

To whitelist a specific version of an image by its digest:

Global policy evaluation mode

Global policy evaluation mode is a policy setting that causes Binary Authorization to evaluate a global policy before evaluating the policy that you configure as a user. The global policy is provided by Google and exempts a list of Google-provided system images from further policy evaluation. When you have this setting enabled, images that are required by GKE are not not blocked by policy enforcement. The global policy is evaluated prior to and in addition to user policy evaluation.

You can enable or disable this setting using the globalPolicyEvaluationMode property in the policy YAML file. You can view the contents of the global policy using the following command:

gcloud beta container binauthz policy export --project=binauthz-global-policy


An attestor is a party that is responsible for verifying or attesting that a container image is ready for deployment. This party can be machine process or a human. For example, when an image is generated by your build system or continuous integration (CI) pipeline and uploaded to your registry, the automation can verify the image to indicate that the image was successfully built and that all required tests have passed. A human user might also verify the image for deployment when it has passed manual quality or release auditing processes.

Attestors have:

When you set up a policy that contains a Require Attestations rule, you must add an attestor for each person or process who is required to verify that the container image is ready for deployment. You can add attestors in the Google Cloud Platform Console, using the gcloud interface or via one of the Binary Authorization APIs.

For more information see, Creating attestors using the CLI or Creating attestors using the Console.

Cryptographic keys

Binary Authorization uses cryptographic keys to verify the identity of attestors. When you add an attestor to your project, you create one or more key pairs that can be used to verify that any attestations by this party are authentic and authorized.

In the key pair, the private key resides on the system from which the attesting process or person verifies or "attests" that a container image is ready for deployment. The public key is uploaded to the Binary Authorization service and attached to the attestor.

When a process or person attests to an image, they create an attestation, which consists of a signature over the image digest that was created using the private key in the pair. Binary Authorization uses the signed image digest and the stored public key to verify the attestor's identity and authority.

Binary Authorization supports two types of keys:

Container Analysis notes

Binary Authorization uses Container Analysis to store trusted metadata used in the authorization process. For each attestor you create, you must create one Container Analysis note. Each attestation is stored as an occurrence of this note.

When Binary Authorization evaluates a rule that requires that attestors have verified an image, it checks Container Analysis storage to see whether the required attestations are present.


An attestation is a statement by an attestor that a container image is ready for deployment. This is sometimes called "signing an image." When an attestor verifies that a container image is ready, the person or process triggers a gcloud or Binary Authorization API interaction that creates an attestation entity in Container Analysis storage.

For example, if the attestor is a build system, the attestation might indicate that the container image has been built successfully and that all required tests have passed. In the same way, if the attestor is a representative of your quality assurance (QA) function, the attestation might indicate that the container image has passed all required end-to-end functional testing in a staging environment.

For more information, see Creating Attestations.

Was this page helpful? Let us know how we did:

Send feedback about...

Binary Authorization Documentation