This page contains reference information for Binary Authorization policies as specified in YAML format. When you configure a policy using the command-line interface, you edit a YAML-formatted file that complies with this specification. For examples of policies in YAML format, see Example Policies.
Policy YAML files have the following format:
name: projects/<PROJECT_ID>/policy admissionWhitelistPatterns: - namePattern: <MATCHING_PATTERN> - ... globalPolicyEvaluationMode: <GLOBAL_EVAL_MODE> defaultAdmissionRule: <ADMISSION_RULE> clusterAdmissionRules: <CLUSTER_SPECIFIER>: <ADMISSION_RULE> ...
The YAML format has the following top-level nodes:
||Name of the policy.||Yes|
||Specifies container images that are always allowed to be deployed.||No|
||Specifies whether to apply a system policy that exempts Google-owned system images.||No|
||Specifies rules that apply to all clusters for which there isn't a cluster-specific rule.||Yes|
||Specifies rules that apply to specific clusters.||No|
name node contains the name of the policy in the following format:
where PROJECT_ID is the name of your Google Cloud Platform (GCP) project where your policy is defined.
admissionWhitelistPatterns specifies an allowlist of container images that are
exempt from policy enforcement. You specify the
path to the images in Container Registry, another registry, or a local
reference in the
admissionWhitelistPatterns: - namePattern: MATCHING_PATTERN - ...
where MATCHING_PATTERN is the path to a single image by
exact match, or to any images matching a pattern using the wildcard symbol
**). Note that wildcards might only be present in the end, and not anywhere
else in the pattern, i.e.,
gcr.io/n*x is not allowed,
gcr.io/nginx* is allowed. The
* wildcard doesn't match
gcr.io/nginx@latest, but it doesn't match
gcr.io/nginx/image. However, using the
** wildcard allows matches to
images in subdirectories, i.e.,
gcr.io/nginx** matches with
The following example adds registries containing commonly used
Google Kubernetes Engine (GKE) images, an image located at
gcr.io/example-project/helloworld, and a local reference to an image, to the
list of exempt images for the policy:
admissionWhitelistPatterns: - namePattern: gcr.io/google_containers/* - namePattern: gcr.io/google-containers/* - namePattern: k8s.gcr.io/* - namePattern: gke.gcr.io/* - namePattern: gcr.io/stackdriver-agents/* - namePattern: gcr.io/example-project/helloworld - namePattern: loc-ref
To allowlist all container images whose registry location matches the specified path:
admissionWhitelistPatterns: ... - namePattern: gcr.io/example-project/*
To allowlist a specific image:
admissionWhitelistPatterns: ... - namePattern: gcr.io/example-project/helloworld
To allowlist a currently-tagged version:
admissionWhitelistPatterns: ... - namePattern: gcr.io/example-project/helloworld:latest - namePattern: gcr.io/example-project/helloworld:my-tag - namePattern: gcr.io/example-project/helloworld:v1.*
To allowlist a specific version of an image by its digest:
admissionWhitelistPatterns: ... - namePattern: gcr.io/example-project/helloworld@sha256:77b0b75136b9bd0fd36fb50f4c92ae0dbdbbe164ab67885e736fa4374e0cbb8c
To allowlist images in subdirectories of a given path:
admissionWhitelistPatterns: ... - namePattern: gcr.io/example-project/**
System policy evaluation mode
is a policy setting that causes Binary Authorization to evaluate a system policy
before evaluating the policy that you configure. The system policy is provided
by Google and exempts 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,
To allow all Google-maintained system images, set the
globalPolicyEvaluationMode property to
To disable system policy evaluation mode:
defaultAdmissionRule specifies the default rule
for the policy. The default rule defines the constraints that apply to all
non-exempt container images with the exception of those that have their own
cluster-specific rule. You specify the default rule using the
The following example shows a default rule that allows only those container images to be deployed which have been authorized by the specified attestor. In the case that all required attestors have not authorized the image, Binary Authorization blocks the deployment and writes to the audit log.
defaultAdmissionRule: evaluationMode: REQUIRE_ATTESTATION enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG requireAttestationsBy: - projects/example-project/attestors/secure-build
cluster-specific rules for the policy.
The constraints in these rules apply only to the specified cluster. If
Binary Authorization applies a cluster-specific rule to a deployment, the default
rule is not considered. As with default rules, you specify cluster-specific
rules using the
clusterAdmissionRules: CLUSTER_SPECIFIER: ADMISSION_RULE
where CLUSTER_SPECIFIER is the resource ID of the cluster to which
the rule applies in the format
location.name (for example,
The following examples shows a cluster-specific rule that only allows those container images to be deployed which have been authorized by the specified attestors:
clusterAdmissionRules: us-east1-a.prod-cluster: evaluationMode: REQUIRE_ATTESTATION enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG requireAttestationsBy: - projects/example-project/attestors/secure-build - projects/example-project/attestors/prod-qualified
ADMISSION_RULE is a collection of nodes that specify the constraints for the
rule in the following format:
evaluationMode: EVAL_MODE enforcementMode: ENFORCEMENT_MODE requireAttestationsBy: - ATTESTOR - ...
clusterAdmissionRule reference this
evaluationMode specifies the operation that Binary Authorization performs in
order to evaluate whether to deploy a container image. The possible values are:
ALWAYS_ALLOW: Always allow deployment of images evaluated by this rule
ALWAYS_DENY: Always deny deployment of images evaluated by this rule
REQUIRE_ATTESTATION: Require one or more attestors to authorize the release before deployment
REQUIRE_ATTESTATION, you must provide a reference
to the required attestors in
enforcementMode specifies the action that Binary Authorization takes if a
container image does not conform to the constraints defined in the rule. The
possible values are:
ENFORCED_BLOCK_AND_AUDIT_LOG: Blocks deployment and writes to the audit log.
DRYRUN_AUDIT_LOG_ONLY: Allows deployment of non-conformant images and writes details about the violation to the audit log.
Most production rules use the
ENFORCED_BLOCK_AND_AUDIT_LOG enforcement mode.
DRYRUN_AUDIT_LOG_ONLY is primarily used for testing a policy in your
environment before it goes into effect.
requireAttestationsBy specifies one or more attestors who must authorize the
release before a container image can be deployed. This is required for
REQUIRE_ATTESTATION rules only. The format for this node is:
requireAttestationsBy: - projects/PROJECT_ID/attestors/ATTESTOR_NAME - ...
where PROJECT_ID is the name of the project where your attestors are defined and ATTESTOR_NAME is the name of an attestor who is required to sign the release.
The following example shows how to specify attestors:
requireAttestationsBy: - projects/example-project/attestors/secure-build - projects/example-project/attestors/prod-qualified