Configuring a policy using the REST API

This page provides instructions for configuring a Binary Authorization policy at the command line using the REST API. As an alternative, you can also perform these tasks using gcloud commands at the command line or using the Google Cloud Platform Console. 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 using the REST API, you populate values in a JSON format whose structure is identical to the YAML structure used in gcloud interactions with the service. For more information, see Policy YAML Reference.

Configuring a policy requires you to:

  • Export a policy JSON file
  • Add any additional exempt images (optional)
  • Set the default rule
  • Add any cluster-specific rules (optional)
  • Import the policy JSON 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}

where PROJECT_ID is the ID of your project.

Export the policy

Export the policy to a JSON file on your local system:

curl \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "x-goog-user-project: ${PROJECT_ID}" \
    "https://binaryauthorization.googleapis.com/v1/projects/${PROJECT_ID}/policy" \
    -o "/tmp/policy.json"

By default, the file has the following contents:

{
  "name": "projects/PROJECT_ID/policy",
  "admissionWhitelistPatterns": [
    {
      "namePattern": "gcr.io/google_containers/*"
    },
    {
      "namePattern": "gcr.io/google-containers/*"
    },
    {
      "namePattern": "k8s.gcr.io/*"
    },
    {
      "namePattern": "gcr.io/stackdriver-agents/*"
    }
  ],
  "defaultAdmissionRule": {
    "evaluationMode": "ALWAYS_ALLOW",
    "enforcementMode": "ENFORCED_BLOCK_AND_AUDIT_LOG"
  }
}

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. If enabled, this whitelist is in addition to those images exempted by global policy evaluation mode.

To add an exempt image, add a namePattern node to admissionWhitelistPatterns in the policy JSON file:

  "admissionWhitelistPatterns": [
    {
      "namePattern": "gcr.io/google_containers/*"
    },
    {
      "namePattern": "gcr.io/google-containers/*"
    },
    {
      "namePattern": "k8s.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 in addition to the user policy.

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

gcloud beta 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. This is disabled by default.

To enable global policy evaluation mode, add the following top-level node to the policy JSON 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. Every admission request has an associated GKE cluster. If a request doesn't match a cluster-specific rule, the default rule is used.

The default rule is defined in the defaultAdmissionRule node in the policy. 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 JSON 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 only to the specified GKE cluster. If a cluster has no rule of its own, the default rule is used. Cluster-specific rules are an optional part of a policy.

Cluster-specific rules are defined in clusterAdmissionRules nodes in the policy JSON 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 JSON file, add a clusterAdmissionRules node:

"clusterAdmissionRules": {
    "us-central1-a.test-cluster": {
      "evaluationMode": "REQUIRE_ATTESTATION",
      "requireAttestationsBy": [
        "ATTESTOR",
        ...
      ],
      "enforcementMode": "ENFORCED_BLOCK_AND_AUDIT_LOG"
    }
  },

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 JSON file

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

To import the file, enter the following:

curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "x-goog-user-project: ${PROJECT_ID}" \
    --data-binary @/tmp/policy.json  \
    "https://binaryauthorization.googleapis.com/v1/projects/${PROJECT_ID}/policy"

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Binary Authorization Documentation