Get started using the Google Cloud CLI (GKE) Stay organized with collections Save and categorize content based on your preferences.

Enable Binary Authorization

Before you use Binary Authorization, set your default project and enable the required Google Cloud APIs.

Set the default project

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

PROJECT_ID=PROJECT_ID
gcloud config set project ${PROJECT_ID}

Replace PROJECT_ID with the name of your project.

Enable required APIs

Enable the following APIs:

gcloud --project=${PROJECT_ID} \
    services enable\
    container.googleapis.com\
    artifactregistry.googleapis.com\
    binaryauthorization.googleapis.com

Create a cluster with Binary Authorization enabled

To set up your Kubernetes environment, create a cluster with Binary Authorization enabled and configure kubectl to interact with it.

Create the cluster

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 --binauthz-evaluation-mode=PROJECT_SINGLETON_POLICY_ENFORCE flag to the gcloud container clusters create command.

To create the cluster, follow these steps:

gcloud container clusters create \
    --binauthz-evaluation-mode=PROJECT_SINGLETON_POLICY_ENFORCE \
    --zone us-central1-a \
    test-cluster

Here, you create a cluster named test-cluster in the GKE zone us-central1-a.

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.

To update the local kubeconfig file, run the following command:

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

View the default policy

A policy in Binary Authorization is a set of rules that govern the deployment of container images. You can have one policy per project. By default, the policy is configured to allow all container images to be deployed.

Binary Authorization lets you export and import a policy file in YAML format. This format reflects the structure of a policy as it is stored by the service. When you configure a policy using gcloud commands, you edit this file.

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

gcloud container binauthz policy export

By default, the file has the following contents:

defaultAdmissionRule:
  enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG
  evaluationMode: ALWAYS_ALLOW
globalPolicyEvaluationMode: ENABLE
name: projects/PROJECT_ID/policy

The default rule is defined in the defaultAdmissionRule node. evaluationMode specifies that the policy allows all attempts at image deployment. In this tutorial, you update the default rule to require attestations.

globalPolicyEvaluationMode exempts Google-managed system images from Binary Authorization enforcement.

To add an exempt image to the allowlist, add the following to the policy file:

admissionWhitelistPatterns:
  - namePattern: EXEMPT_IMAGE_PATH

Replace EXEMPT_IMAGE_PATH with the path to am image to exempt. To exempt additional images, add additional - namePattern entries. Learn more about admissionWhitelistPatterns.

For more information on the structure of a policy, see the Policy YAML reference.

Create an attestor

An attestor is the verification authority that the Binary Authorization enforcer uses at deploy time to decide whether to allow GKE to deploy the corresponding signed container image. The attestor contains the public key and is typically managed by personnel in your organization who are responsible for software supply chain security.

To create an attestor, follow these steps:

• Create a note in Artifact Analysis to store trusted metadata used in the authorization process.
• Create the attestor itself in Binary Authorization and associate the note you created.

For this tutorial, you have one attestor named test-attestor and a Artifact Analysis note named test-attestor-note. In a real-world scenario, you can have any number of attestors, each one representing a party that participates in the authorization process for a container image.

Create the Artifact Analysis note

1. Set variables that store the name of your attestor and Artifact Analysis note:

   ATTESTOR_NAME=test-attestor
   NOTE_ID=test-attestor-note
   

   Replace the following:

   • test-attestor: attestor name of your choice.
   • attestor-note: attestor note name of your choice.

2. Create a JSON file in /tmp/note_payload.json that describes the Artifact Analysis note:

   cat > /tmp/note_payload.json  /tmp/policy.yaml  /tmp/generated_payload.json
   

   The payload JSON file has the following contents:

   {
   "critical": {
     "identity": {
       "docker-reference": "us-docker.pkg.dev/google-samples/containers/gke/hello-app"
     },
     "image": {
       "docker-manifest-digest": "sha256:c62ead5b8c15c231f9e786250b07909daf6c266d0fcddd93fea
   882eb722c3be4"
     },
     "type": "Google cloud binauthz container signature"
   }
   }
   

3. To sign the payload with your PKIX private key and generate a signature file, run the following command:

   openssl dgst -sha256 -sign ${PRIVATE_KEY_FILE} /tmp/generated_payload.json > /tmp/ec_signature
   

   The signature file is the signed version of the payload JSON file you created earlier in this guide.

4. Create and validate the attestation:

   gcloud container binauthz attestations create \
     --project="${PROJECT_ID}" \
     --artifact-url="${IMAGE_TO_ATTEST}" \
     --attestor="projects/${PROJECT_ID}/attestors/${ATTESTOR_NAME}" \
     --signature-file=/tmp/ec_signature \
     --public-key-id="${PUBLIC_KEY_ID}" \
     --validate
   

   Replace PUBLIC_KEY_ID with the public key ID that you found in Generate a key pair.

   The validate flag checks that the attestation can be verified by the attestor you configured in your policy.