Quickstart

This Quickstart shows how to configure and test a simple policy in Binary Authorization.

In this Quickstart, you view and test the default policy, and then configure the policy to deny the deployment of all container images from Container Registry to a Google Kubernetes Engine (GKE) cluster. This is not a real-world policy. In a real-world policy, you typically require attestations by attestors in your environment before a container image can be deployed.

See Getting Started Using the CLI or Getting Started Using the Console for a longer tutorial that describes how to configure a policy with required attestations.

Before you begin

  1. Sign in to your Google Account.

    If you don't already have one, sign up for a new account.

  2. In the GCP Console, go to the Manage resources page and select or create a project.

    Go to the Manage resources page

  3. Make sure that billing is enabled for your Google Cloud Platform project.

    Learn how to enable billing

  4. Install and initialize the Cloud SDK.
  5. Install kubectl.

Set the default project

The first step is to set the default Google Cloud Platform project used by the gcloud command.

gcloud

To set the default project:

gcloud config set project PROJECT_ID

where PROJECT_ID is the name of your project.

Enable required APIs

Enable the APIs for GKE, Container Analysis and Binary Authorization:

gcloud

Enabled the required APIs:

gcloud services enable \
    container.googleapis.com \
    containeranalysis.googleapis.com \
    binaryauthorization.googleapis.com

console

Enable the required APIs:

Enable the APIs

It can take a few minutes for this operation to complete.

Create a cluster with Binary Authorization enabled

Now you can create a GKE cluster with Binary Authorization enabled. This is the cluster where you want your deployed container images to run. When you create the cluster, you pass the --enable-binauthz flag to the gcloud beta container clusters create command.

gcloud

To create the cluster:

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

console

  1. Visit the GKE menu in GCP Console.

    Visit the GKE menu

  2. Click Create Cluster.

  3. Enter test-cluster in the Name field.

  4. Select Zonal in the Location Type options.

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

  6. Click Advanced Options.

  7. In the Security section, select Enable Binary Authorization.

    Enable Binary Authorization option

  8. Click Create.

Configure kubectl

You must also update the local kubeconfig file for your kubectl installation. This provides the credentials and endpoint information required to access the cluster in GKE.

gcloud

To update the local kubeconfig file:

gcloud container clusters get-credentials \
    --zone us-central1-a \
    test-cluster

Default policy

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

gcloud

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

gcloud beta 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: gcr.io/stackdriver-agents/*
defaultAdmissionRule:
  evaluationMode: ALWAYS_ALLOW
  enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG
name: projects/PROJECT_ID/policy

console

To view the default policy:

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

    Go to the Binary Authorization page

  2. In the Policy tab, click Edit Policy.

    Screenshot of policy tab showing default rule

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

    Screenshot of the option to choose a default rule type

Test the policy

You can test the policy by trying to deploy a sample container image to the cluster.

For this Quickstart, you use the sample container image located at the path gcr.io/google-samples/hello-app in Container Registry. This is a public container image created by Google that contains a Hello, World! sample application.

kubectl

To deploy the image:

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

Now, verify that the deployment was allowed by Binary Authorization.

kubectl

To verify that the image was deployed:

kubectl get pods

The command prints a message similar to the following, which indicates that deployment was successful:

NAME                            READY     STATUS    RESTARTS   AGE
hello-server-579859fb5b-h2k8s   1/1       Running   0          1m

console

To verify that the image was deployed:

Go to the GKE Workloads page in Google Cloud Platform Console.

Go to the GKE page

A workload for the deployment appears with a green icon that indicates that the image was deployed successfully.

Screenshot of a successful deployment message

Make sure to delete the deployment so you can continue to the next step:

kubectl

To delete the deployment:

kubectl delete deployment hello-server

console

To delete the deployment:

  1. Click the name of the workload where it appears in Google Cloud Platform Console.

  2. Click Delete from the menu items at the top of the page that appears.

Configure the policy to disallow all images

Now, modify the policy to block instead of allow all images to be deployed.

gcloud

To modify the policy:

  1. Export the policy YAML file:

    gcloud beta container binauthz policy export  > /tmp/policy.yaml
    
  2. In a text editor, change the evaluationMode from ALWAYS_ALLOW to ALWAYS_DENY.

    The policy YAML file should appear as follows:

    admissionWhitelistPatterns:
    - namePattern: gcr.io/google_containers/*
    - namePattern: gcr.io/google-containers/*
    - namePattern: k8s.gcr.io/*
    - namePattern: gcr.io/stackdriver-agents/*
    defaultAdmissionRule:
      evaluationMode: ALWAYS_DENY
      enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG
    name: projects/PROJECT_ID/policy
    
  3. Import the policy YAML file back into Binary Authorization:

    gcloud beta container binauthz policy import /tmp/policy.yaml
    

console

To modify the policy:

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

    Go to the Binary Authorization page

  2. In the Policy tab, click Edit Policy.

  3. Select Disallow All Images.

    Screenshot of the option to choose a default rule type

  4. Click Save Policy.

Retest the policy

Again, test the policy by deploying a sample container image to the cluster. This time, Binary Authorization blocks the image from being deployed.

kubectl

To deploy the image:

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

You can now verify that the policy was blocked:

kubectl

To verify that the image was not deployed:

kubectl get pods

The command prints the following message, which indicates that the image was not deployed:

No resources found.

You can get further details about the deployment:

kubectl get event --template \
'{{range.items}}{{"\033[0;36m"}}{{.reason}}:{{"\033[0m"}}{{.message}}{{"\n"}}{{end}}'

which shows that the deployment was disallowed by the policy:

FailedCreate:Error creating: pods "hello-server-579859fb5b-lvfgd" is forbidden:
image policy webhook backend denied one or more images: Denied by default admission
rule. Overridden by evaluation mode

console

To verify that the image was not deployed:

Return to the GKE Workloads page in Google Cloud Platform Console.

Go to the GKE page

A workload for the container image appears with a red icon that indicates that the image failed to be deployed.

Screenshot of a failed deployment message

Clean up

To avoid incurring charges to your GCP account for the resources used in this quickstart:

Delete the cluster you created in GKE:

gcloud

To delete the cluster:

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

console

To delete the cluster:

  1. Return to the GKE page in Google Cloud Platform Console.

  2. Select Clusters in the left-hand navigation panel.

  3. Select the checkbox next to the name of your cluster and click Delete.

What's next

Send feedback about...

Binary Authorization