Get started using the Google Cloud CLI (GKE)

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 << EOM
   {
     "name": "projects/${PROJECT_ID}/notes/${NOTE_ID}",
     "attestation": {
       "hint": {
         "human_readable_name": "Attestor Note"
       }
     }
   }
   EOM
   

3. Create the note by sending an HTTP request to the Artifact Analysis REST API:

   curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
       --data-binary @/tmp/note_payload.json  \
       "https://containeranalysis.googleapis.com/v1/projects/${PROJECT_ID}/notes/?noteId=${NOTE_ID}"
   

4. Verify that the note was created:

   curl \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://containeranalysis.googleapis.com/v1/projects/${PROJECT_ID}/notes/${NOTE_ID}"
   

Create the attestor

You can create the attestor by following these steps:

1. Create the attestor in Binary Authorization:

   gcloud container binauthz attestors create ${ATTESTOR_NAME} \
   --attestation-authority-note=${NOTE_ID} \
   --attestation-authority-note-project=${PROJECT_ID}
   

2. Verify that the attestor was created:

   gcloud container binauthz attestors list
   

The attestor you created is not yet usable without an associated key pair, which you create later in this guide.

Generate a key pair

Binary Authorization uses cryptographic keys to securely verify the identity of signers. This ensures that only authorized container images can be deployed. The key pair consists of a private key and a public key. The signer uses the private key to sign the container image digest, producing a signature that is then stored in an attestation. The public key is stored in the attestor. At deploy time, the Binary Authorization enforcer uses the attestor's public key to verify the signature in the attestation before allowing the container to deploy.

In this tutorial, you use Public-Key Infrastructure (X.509) (PKIX) format for cryptographic keys. This tutorial uses the recommended Elliptic Curve Digital Signature Algorithm (ECDSA) to generate a PKIX key pair. You can also use RSA or PGP keys for signing images.

For more information about signing algorithms, see Key purposes and algorithms.

The keys generated and stored by Cloud Key Management Service (Cloud KMS) are PKIX-compliant. For more information about using PKIX keys and Cloud KMS, see Creating attestors using the gcloud CLI.