Configuring a policy using the CLI

This page provides instructions for configuring a Binary Authorization policy at the command line using gcloud commands. As an alternative, you can also perform these tasks using Google Cloud Console or using the REST API. This step is part of setting up Binary Authorization.

Overview

A policy is a set of rules that govern the deployment of one or more container images.

When you configure a policy at the command line, you manually edit it in YAML format in a text editor. The YAML format reflects the internal structure of a policy as stored by Binary Authorization. For more information on this format, see Policy YAML Reference.

Configuring a policy requires you to:

• Export the policy YAML file
• Add any additional exempt images (optional)
• Set the default rule
• Add any cluster-specific rules (optional)
• Import the policy YAML file

Most real-world policies check to see whether all required attestors have verified that a container image is ready to be deployed. In this case, you must also create attestors when you configure the policy.

Set the default project

Set the default Google Cloud project if you have not already done so:

PROJECT_ID=PROJECT_ID
gcloud config set project ${PROJECT_ID}

Export the policy YAML file

Export the policy YAML file to your local system:

gcloud container binauthz policy export  > /tmp/policy.yaml

By default, the file has the following contents:

admissionWhitelistPatterns:
- namePattern: gcr.io/google_containers/*
- namePattern: gcr.io/google-containers/*
- namePattern: k8s.gcr.io/*
- namePattern: gke.gcr.io/*
- namePattern: gcr.io/stackdriver-agents/*
globalPolicyEvaluationMode: ENABLE
defaultAdmissionRule:
  evaluationMode: ALWAYS_ALLOW
  enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG
name: projects/PROJECT_ID/policy

The admissionWhitelistPatterns list may contain additional recommended image paths by default.

Note: We no longer recommend using admissionWhitelistPatterns to allowlist Google-managed system images, as shown above. To allowlist Google-managed system images, set globalPolicyEvaluationMode to ENABLE. Doing so allows Google to manage the allowlist of system images that GKE uses. Google updates this allowlist with each GKE release. If you do not enable the setting, you must manage the allowlist yourself. See globalPolicyEvaluationMode for details.

Manage 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 policy can have an allowlist of exempt images specified by their registry path. This path can be a location either in Container Registry or another container image registry. This allowlist is in addition to those images exempted by global policy evaluation mode, if enabled.

To add an exempt image, add a namePattern node under an admissionWhitelistPatterns list in the policy.yaml file:

admissionWhitelistPatterns:
- namePattern: MATCHING_PATTERN

where MATCHING_PATTERN is the path to a single image in your registry by exact match, or to any images matching a pattern using the wildcard symbol (*).

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-maintained system images from further policy evaluation. When you have this setting enabled, images that are required by Google Kubernetes Engine (GKE) are not blocked by policy enforcement. The global policy is evaluated prior to and in addition to the user policy.

You can view the contents of the global policy using the following command:

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

Global policy evaluation mode makes it unnecessary to explicitly specify paths to Google-maintained system images under an admissionWhitelistPatterns list:

admissionWhitelistPatterns:
- namePattern: gcr.io/google_containers/*
- namePattern: gcr.io/google-containers/*
- namePattern: k8s.gcr.io/*
- namePattern: gke.gcr.io/*
- namePattern: gcr.io/stackdriver-agents/*

To enable global policy evaluation mode, add the following line to the policy.yaml file:

globalPolicyEvaluationMode: ENABLE

To disable global policy evaluation mode, add the following:

globalPolicyEvaluationMode: DISABLE

Set the default rule

A rule is the part of a policy that defines constraints that container images must pass before they can be deployed. The default rule defines constraints that apply to all non-exempt container images, with the exception of those that have their own cluster-specific rule. Every policy must have a default rule.

The default rule is defined in the defaultAdmissionRule node in the policy YAML file. For more information on the parts of this rule, see ADMISSION_RULE in the Policy YAML Reference. For examples of default rules, see Example Policies.

To set the default rule, edit the defaultAdmissionRule node in the policy.yaml file as required:

defaultAdmissionRule:
  evaluationMode: EVAL_MODE
  enforcementMode: ENFORCEMENT_MODE
  requireAttestationsBy:
  - ATTESTOR
  - ...

where:

• EVAL_MODE specifies the type of constraint that Binary Authorization evaluates before allowing a container image to be deployed.
• ENFORCEMENT_MODE specifies the action that is taken if a container image does not conform to the constraints defined in the rule.
• ATTESTOR specifies the attestors (if required) that must sign a container image before it can be deployed. Use the fully-qualified path to the attestor in the format projects/PROJECT_ID/attestors/ATTESTOR_NAME.

If your rule checks to see whether all required attestors have signed a container image, you must create attestors before completing this step.

Set cluster-specific rules (optional)

A cluster 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. Cluster-specific rules are an optional part of a policy.

Cluster-specific rules are defined in clusterAdmissionRules nodes in the policy YAML file. For more information on the parts of this rule, see ADMISSION_RULE in the Policy YAML Reference. For an example, see Use a cluster-specific rule in Example Policies.

To add a cluster-specific rule:

In the policy.yaml file, add a clusterAdmissionRules node:

clusterAdmissionRules:
  CLUSTER_SPECIFIER:
    evaluationMode: EVAL_MODE
    enforcementMode: ENFORCEMENT_MODE
    requireAttestationsBy:
    - ATTESTOR
    - ...

where CLUSTER_SPECIFIER is the resource ID of the cluster to which the rule applies in the format location.name and the other properties are as described in Set the default rule above. See Example Policies for an example of a cluster-specific rule.

If your rule checks to see whether all required attestors have signed a container image, you must create attestors before completing this step.

Import the policy YAML file

The final step is to import the policy YAML file back into Binary Authorization.

To import the file, enter the following:

gcloud container binauthz policy import /tmp/policy.yaml

What's next

• Create an attestor
• Create an attestation
• Deploy a container image