Quickstart: Exempt images

This document describes how to exempt images in Binary Authorization policies.

In this document, you update the policy to exempt container images from Container Registry and Artifact Registry. At deploy time, the Binary Authorization enforcer allows exempt images to be deployed on a Google Kubernetes Engine (GKE) cluster. The enforcer allows exempt images before it enforces other policy rules.

To learn how to configure a policy to require attestations for an image, see the following end-to-end tutorials:

Before you begin

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

  4. Enable the Artifact Registry, Binary Authorization APIs.

    Enable the APIs

  5. Install and initialize the Cloud SDK.
  6. If you are not using Cloud Shell, install kubectl.

Create a cluster with Binary Authorization enabled

Create a GKE cluster with Binary Authorization enabled. This is the cluster where you want your deployed container images to run.

Google Cloud Console

  1. Go to the GKE Clusters page in the Cloud Console.

    Go to the GKE page

    The console displays a list of GKE clusters in your Google Cloud project.

  2. Click Create Cluster.

  3. Enter test-cluster in the Name field.

    Name field in the standard cluster template

  4. Select Zonal in the Location Type options.

  5. Select us-central1-a from the Zone drop-down list.

  6. Click the Security link to reveal the Security panel.

  7. In the Security panel, select the Enable Binary Authorization checkbox.

    Enable Binary Authorization option

  8. Click Create.

gcloud

Run gcloud container clusters create with the --enable-binauthz flag enabled.

gcloud container clusters create \
    --enable-binauthz \
    --zone us-central1-a \
    test-cluster

View the Default policy

By default, your Binary Authorization policy is configured to allow all container images to be deployed.

Cloud Console

To view the default policy:

  1. Go to the Binary Authorization page in the Cloud Console.

    Go to the Binary Authorization page

    The console displays details about the policy.

  2. Click Configure Policy or, if a policy exists, Edit Policy.

  3. In Project Default Rule, the option Allow All Images is selected.

gcloud

To view the default policy, export the policy YAML file:

gcloud container binauthz policy export

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

REST API

To view the default policy, retrieve it in JSON format:

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"

The REST API returns the following:

{
  "name": "projects/PROJECT_ID/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/*"
    }
  ],
  "globalPolicyEvaluationMode": "ENABLE",
  "defaultAdmissionRule": {
    "evaluationMode": "ALWAYS_ALLOW",
    "enforcementMode": "ENFORCED_BLOCK_AND_AUDIT_LOG"
  }
}

Allow only exempt images

Modify the policy to disallow all images, except those in listed as Exempt images, from being deployed.

Cloud Console

To modify the policy:

  1. Return to the Binary Authorization page in the Cloud Console.

    Go to the Binary Authorization page

  2. Click Edit Policy.

  3. Select Disallow All Images.

  4. Under Images exempt from deployment rules, expand Image paths.

  5. Click Add Image Paths.

    Container Registry

    In New image path, paste the following path from an Container Registry repository:

    gcr.io/google-samples/hello-app:1.0
    

    Artifact Registry

    In New image path, paste the following path from an Artifact Registry repository:

    us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0
    
  6. Click Done to save the image path.

  7. Click Save Policy.

gcloud

To modify the policy to allow example images from Container Registry and Artifact Registry:

  1. Export the policy YAML file:

    gcloud container binauthz policy export  > /tmp/policy.yaml
    
  2. In a text editor, change the evaluationMode from ALWAYS_ALLOW to ALWAYS_DENY and add exempt images to admissionWhitelistPatterns.

    To exempt the following example images from Container Registry and Artifact Registry, modify your policy YAML file as follows:

    admissionWhitelistPatterns:
    - namePattern: gcr.io/google-samples/hello-app:1.0
    - namePattern: us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0
    globalPolicyEvaluationMode: ENABLE
    defaultAdmissionRule:
      evaluationMode: ALWAYS_DENY
      enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG
    name: projects/<var>PROJECT_ID</var>/policy
    
  3. Import the policy YAML file back into Binary Authorization:

    gcloud container binauthz policy import /tmp/policy.yaml
    

REST API

To modify the policy:

  1. Create a text file with the updated policy in JSON format:

    cat > /tmp/policy.json << EOM
    {
      "name": "projects/${PROJECT_ID}/policy",
      "admissionWhitelistPatterns": [
        {
          "namePattern": "gcr.io/google-samples/hello-app:1.0"
        },
        {
          "namePattern": "us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0"
        }
      ],
      "globalPolicyEvaluationMode": "ENABLE",
      "defaultAdmissionRule": {
        "evaluationMode": "ALWAYS_DENY",
        "enforcementMode": "ENFORCED_BLOCK_AND_AUDIT_LOG"
      }
    }
    EOM
    
  2. Send the updated policy to the REST API:

    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"
    

Test the policy

To test the policy by deploying image you added to the Exempt image allowlist, do the following:

  1. Deploy an exempt image to the cluster.

    Cloud Console

    Deploy an exempt image:

    1. Go to the GKE Clusters page in the Cloud Console.

      Go to the GKE page

    2. Click Deploy.

      The console prompts you to enter details about the deployment.

    3. Select Existing Container Image.

    4. Enter the container image path.

      Container Registry

      To deploy an image from Container Registry enter the following:

      gcr.io/google-samples/hello-app:1.0
      

      Artifact Registry

      To deploy an image from Artifact Registry enter the following:

      us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0
      
    5. Click Continue.

    6. Enter hello-server in the Application Name field.

    7. Click Deploy.

    kubectl

    Container Registry

    Deploy the image from Container Registry:

    kubectl run hello-server --image gcr.io/google-samples/hello-app:1.0 --port 8080
    

    Artifact Registry

    Deploy the image from Artifact Registry:

    kubectl run hello-server --image us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0 --port 8080
    
  2. Verify that the image was allowed to deploy:

    Cloud Console

    To verify that the image was deployed:

    1. Go to the GKE page.

    Go to the GKE page

    1. Go to the Workloads page.

    The hello-server workload appears with a green icon, indicating it is running.

    kubectl

    To verify that the image was allowed to deploy:

    kubectl get pods
    

    You see the image running.

  3. Delete the pod.

    Cloud Console

    In the GKE Workloads page:

    1. Select the hello-server workload.

    2. Click Delete.

    3. When prompted to delete resources, click Delete.

    kubectl

    kubectl delete pod hello-server
    

Clean up

To avoid incurring charges to your Google Cloud account for the resources used in this quickstart, follow these steps.

Delete the cluster you created in GKE:

Cloud Console

To delete the cluster:

  1. Go to the GKE Clusters page in the Cloud Console.

    Go to the GKE page

  2. Select the test-cluster cluster and click Delete.

gcloud

To delete the cluster:

gcloud container clusters delete \
    --zone=us-central1-a \
    test-cluster

What's next