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

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 (*).

The following example adds required GCP resources, 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: 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 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 blocked by policy enforcement. The global policy is evaluated prior to and in addition to user policy evaluation.

To exempt all Google-provided system images, set the globalPolicyEvaluationMode property to ENABLE:

globalPolicyEvaluationMode: ENABLE

To disable global policy evaluation mode:

globalPolicyEvaluationMode: DISABLE

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
Was this page helpful? Let us know how we did:

Send feedback about...

Binary Authorization Documentation