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 Platform 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 Platform 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/* defaultAdmissionRule: evaluationMode: ALWAYS_ALLOW enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG name: projects/PROJECT_ID/policy
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 a whitelist of exempt images specified by their registry path. This path can be a location either in Container Registry or another container image registry. This whitelist is in addition to those images exempted by global policy evaluation mode, if enabled.
To add an exempt image, add a
namePattern node to
admissionWhitelistPatterns
in the policy.yaml file:
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: 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-provided 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-provided system images in the whitelist:
- 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
