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 Console
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 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.
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 will require one or more digitally signed attestations. When the signature on each required attestation is verified - indicating that all required internal processes have completed - the container is allowed to be deployed. Rules can also allow or deny all deployments from specific Container Registry paths and/or to specific GKE clusters.
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
A policy can 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
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
property in the policy YAML file.
There are three evaluation modes:
- Allow all images
- Disallow all images
- Require attestations
A Require Attestations rule requires a signer to digitally sign the container image digest and create an attestation before deployment. At deploy time, the Binary Authorization enforcer uses an attestor to verify the signature in the attestation before deploying the associated container image.
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: Dry run mode is an enforcement mode in a policy that allows non-conformant images to be deployed, but writes details about the deployment to the Cloud Audit Logs. Dry run mode allows you to test a policy, for example in your production environment, before enforcement actually goes into effect.
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.
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
an allowlist of exempt images specified by registry path. Images in the path
k8s.gcr.io/*, 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 allowlist of exempt images is specified using the
property in the policy YAML file.
To allowlist all container images whose registry location matches the specified path:
To allowlist a specific image:
To allowlist a specific version of an image by tag:
To allowlist a specific version of an image by its digest:
Google-maintained system images
Trust all Google-maintained system images causes Binary Authorization to exempt a list of Google-maintained system images from further policy evaluation. When you have this setting enabled, images that are required by GKE are not blocked by policy enforcement. The system policy is evaluated prior to and in addition to user policy evaluation.
You can enable or disable this setting using the
property in the policy YAML file. You can view the contents of the system
policy using the following command:
gcloud container binauthz policy export --project=binauthz-global-policy
An attestation is a digital document that certifies that GKE is allowed to deploy the container image.
The process of creating an attestation is sometimes called "signing an image." An attestation is created after a container image is built. Each such container has a globally unique digest. A signer signs the container image digest using a private key from a key pair and uses the signature to create the attestation. At deploy time, the Binary Authorization enforcer uses the attestor's public key to verify the signature in the attestation. Typically one attestor corresponds to exactly one signer.
An attestation signifies that the associated container image was built by a successfully executing a specific, required process. For example, if the signer 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.
To enable attestations in Binary Authorization, your policy's
See the Binary Authorization overview for typical use cases.
To learn how to create an attestation, see Creating Attestations.
A signer is a person or automated process that creates an attestation by signing a unique container image descriptor with a private key. The attestation is verified at deploy time by the corresponding public key stored in an attestor before the associated container is deployed.
An attestor is a Google Cloud resource that Binary Authorization uses to verify the attestation at container image deploy time. Attestors contain the public key that corresponds to the private key used by a signer to sign the container image digest and create the attestation. The Binary Authorization enforcer uses the attestor at deploy time to limit which container images are allowed to be deployed to those with an accompanying, verifiable attestation created prior to deployment.
Attestors are often managed by security operations personnel who also manage the public and private key pairs, whereas signers are typically software engineers or DevOps QA or compliance personnel responsible for producing deployable container images, signing them with the private key and creating the attestations before attempting to deploy them.
- A corresponding Container Analysis note
- One or more cryptographic public keys that correspond to the private key the signer used to create an attestation.
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 using
the Google Cloud Console, the
gcloud interface, or the Binary Authorization REST
Binary Authorization uses digital signatures to verify images at deploy time when the policy contains a Require Attestations rule.
A key pair is generated. The private key is used by the signer to sign a container image descriptor. This creates an attestation.
Then, an attestor is created and stored in the policy. The public key that corresponds to the private key used for signing is uploaded and attached to the attestor.
At deploy time, GKE calls the Binary Authorization enforcer, which uses attestors in the policy to verify the validity of the associated attestations, guaranteeing that each digitally signed container image is allowed to be deployed.
Binary Authorization supports two types of keys:
PKIX keys can be stored locally, externally, or in Cloud Key Management Service.
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.