Configure a multi-project setup Stay organized with collections Save and categorize content based on your preferences.

Set up the deployer project

The deployer project manages the Google Kubernetes Engine (GKE) clusters, where you deploy images, and the Binary Authorization policy that Binary Authorization enforces at deploy time. You can have more than one deployer project, depending on the size, complexity, and other requirements of your environment.

To set up the deployer project:

1. Create the project and enable billing in Google Cloud console if you have not already done so.

2. Identity and Access Management note: The deployer project contains your GKE cluster. The Identity and Access Management configuration for this project should reflect that.

3. Set environment variables to store the Google Cloud project and number:

   DEPLOYER_PROJECT_ID=DEPLOYER_PROJECT_ID
   

   Replace DEPLOYER_PROJECT_ID with the Google Cloud project ID.

   DEPLOYER_PROJECT_NUMBER=$(gcloud projects describe "${DEPLOYER_PROJECT_ID}" \
       --format="value(projectNumber)")
   

4. Enable APIs:

   Artifact Registry

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

5. Get the deployer project service account name:

   DEPLOYER_SERVICE_ACCOUNT="service-${DEPLOYER_PROJECT_NUMBER}@gcp-sa-binaryauthorization.iam.gserviceaccount.com"
   

   You use the service account name in a later step when you configure permissions on the Artifact Analysis note associated with your attestor.

Set up the attestor project

An attestor project stores the attestors that can verify that an image is ready for deployment. Often, you have a single attestor project that acts as a centralized store for information about trusted parties in the authorization process. This allows you to centrally manage security keys required to verify the identity of attestors and to restrict access to only those parties who administer them.

To set up the attestor project:

1. Create the project and enable billing in Google Cloud console if you have not already done so.

2. Identity and Access Management note: Because the this project contains your attestors, only security personnel should have write access.

3. Set environment variables to store the project ID and number:

   ATTESTOR_PROJECT_ID=ATTESTOR_PROJECT_ID
   

   Replace ATTESTOR_PROJECT_ID with the attestor project ID.

   ATTESTOR_PROJECT_NUMBER=$(gcloud projects describe "${ATTESTOR_PROJECT_ID}" \
       --format="value(projectNumber)")
   

4. Enable the Artifact Analysis and Binary Authorization APIs:

   gcloud services --project=${ATTESTOR_PROJECT_ID} \
       enable containeranalysis.googleapis.com \
       binaryauthorization.googleapis.com
   

5. Get the attestor project service account name:

   ATTESTOR_SERVICE_ACCOUNT="service-${ATTESTOR_PROJECT_NUMBER}@gcp-sa-binaryauthorization.iam.gserviceaccount.com"
   

   You use the service account name in a later step when you configure permissions on the Artifact Analysis note associated with your attestor.

Set up the attestations project

An attestation project is one that stores attestations that attestors make when they verify an image. A separate attestation project allows you to organize and inspect statements about software readiness more easily.

1. Create the project and enable billing in Google Cloud console if you have not already done so.

2. Identity and Access Management note: All roles involved in binary authorization should have read access to the Artifact Analysis Notes and Occurrences in this project, however only attestation managers need to have write access.

3. Set an environment variable to store the project name:

   ATTESTATION_PROJECT_ID=ATTESTATION_PROJECT_ID
   

   Replace ATTESTATION_PROJECT_ID with the attestation project ID.

4. Enable the Artifact Analysis and Binary Authorization APIs:

   gcloud services --project=${ATTESTATION_PROJECT_ID} \
       enable containeranalysis.googleapis.com \
       binaryauthorization.googleapis.com
   

Create a cluster

Now you can create a GKE cluster in the deployer project. 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:

gcloud --project=${DEPLOYER_PROJECT_ID} \
    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.

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:

gcloud --project=${DEPLOYER_PROJECT_ID} \
    container clusters get-credentials \
    --zone us-central1-a \
    test-cluster

Create an attestor

An attestor is a party that is responsible for attesting that a required process has completed before a container image can be deployed. This party can be a human user or, more often, a machine process like a build and test system, or your continuous integration (CI) and deployment (CD) pipelines. You create attestors in your attestor project.

Creating an attestor requires you to:

• Create a note in Artifact Analysis to store trusted metadata used in the authorization process
• Create the attestor itself in the attestor project and associate the note you created
• Add an IAM role binding for the deployer project service account to the attestor
• Set permissions on the Artifact Analysis note

For this tutorial, you have one attestor named test-attestor and a Container 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 the 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:

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

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

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

   The payload JSON file has the following contents:

   Artifact Registry

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

3. Sign the payload.

   If using local PKIX files, sign the payload with your local PKIX private key and output a signature file:

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

   The output file is a signed version of the payload JSON file you created above.

4. Get the public key ID from the attestor.

   You can view your public key ID at any time using the command: gcloud container binauthz attestors describe ATTESTOR_NAME.

   To save your public key ID in an environment variable, enter this command:

   PUBLIC_KEY_ID=$(gcloud container binauthz attestors describe ${ATTESTOR_NAME} \
   --format='value(userOwnedGrafeasNote.publicKeys[0].id)' --project ${ATTESTOR_PROJECT_ID})
   

5. Create and validate the attestation:

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

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