Policy YAML reference

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>
  ...

Nodes

The YAML format has the following top-level nodes:

Node	Description	Required
name	Name of the policy.	Yes
admissionWhitelistPatterns	Specifies container images that are always allowed to be deployed.	No
globalPolicyEvaluationMode	Specifies whether to apply a global policy that exempts Google-owned system images.	No
defaultAdmissionRule	Specifies rules that apply to all clusters for which there isn't a cluster-specific rule.	Yes
clusterAdmissionRules	Specifies rules that apply to specific clusters.	No

name

The name node contains the name of the policy in the following format:

name: projects/PROJECT_ID/policy

where PROJECT_ID is the name of your Google Cloud Platform (GCP) project where your policy is defined.

For example:

name: projects/example-project/policy

admissionWhitelistPatterns

Note: Using admissionWhitelistPatterns to whitelist Google-managed system images is not recommended. To whitelist Google-managed system images, globalPolicyEvaluationMode should be set to ENABLE. See globalPolicyEvaluationMode for details.

admissionWhitelistPatterns specifies a whitelist of container images that are exempt from policy enforcement. You specify the path to the images in Container Registry or another registry in the namePattern subnode:

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 may only be present in the end, and not anywhere else in the pattern, i.e., gcr.io/n*x is not allowed, but gcr.io/nginx* is allowed. Also wildcards do not match /, i.e., gcr.io/nginx* matches gcr.io/nginx@latest, but it does not match gcr.io/nginx/image.

The following example adds registries containing commonly used Google Kubernetes Engine (GKE) images as well as an image located at gcr.io/example-project/helloworld, 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

Whitelist patterns

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

admissionWhitelistPatterns:
  ...
  - namePattern: gcr.io/example-project/*

To whitelist a specific image:

admissionWhitelistPatterns:
  ...
  - namePattern: gcr.io/example-project/helloworld

To whitelist 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 whitelist a specific version of an image by its digest:

admissionWhitelistPatterns:
  ...
  - namePattern: gcr.io/example-project/helloworld@sha256:77b0b75136b9bd0fd36fb50f4c92ae0dbdbbe164ab67885e736fa4374e0cbb8c

globalPolicyEvaluationMode

Global policy evaluation mode is a policy setting that causes Binary Authorization to evaluate a system policy before evaluating the policy that you configure as a user. 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 global policy is evaluated prior to and in addition to user policy evaluation, including admissionWhitelistPatterns.

To allow all Google-maintained system images, set the globalPolicyEvaluationMode property to ENABLE:

globalPolicyEvaluationMode: ENABLE

To disable global policy evaluation mode:

globalPolicyEvaluationMode: DISABLE

Note: It is recommended that you set globalPolicyEvaluationMode to ENABLE. For GKE to work properly, it needs to run a number of system images in your cluster. When you enable globalPolicyEvaluationMode, the Google-maintained whitelist of system images is automatically updated with every GKE release. While you can manage system images yourself by listing them in the admissionWhitelistPatterns whitelist, updated system images may not be allowed to run if the whitelist is not kept up to date.

Note: The default value for globalPolicyEvaluationMode is currently DISABLE but will change to ENABLE in the future. Therefore, it is recommended to explicitly set the value to the behavior you prefer.

Note: If you disable globalPolicyEvaluationMode, the paths gcr.io/google_containers/*, gcr.io/google-containers/*, k8s.gcr.io/*, gke.gcr.io/*, and gcr.io/stackdriver-agents/* must be included in the admissionWhitelistPatterns whitelist, as they contain Google Cloud resources required by GKE to start a cluster successfully. Additional image paths may be required in the future. Those paths would also need to be included in the admissionWhitelistPatterns whitelist for GKE clusters to run as expected.

defaultAdmissionRule

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 ADMISSION_RULE collection:

defaultAdmissionRule:
  ADMISSION_RULE

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

clusterAdmissionRules

clusterAdmissionRules declare 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 ADMISSION_RULE collection:

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, us-east1-a.prod-cluster).

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

Node collections

ADMISSION_RULE

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
- ...

Both defaultAdmissionRule and clusterAdmissionRule reference this collection.

evaluationMode

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

If the evaluationMode is REQUIRE_ATTESTATION, you must provide a reference to the required attestors in requireAttestationsBy.

enforcementMode

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

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