Deploying containers (GKE)

This page explains how to deploy a container image to a Google Kubernetes Engine (GKE) cluster where Binary Authorization is enabled. The kubectl commands you use to deploy the image are the same as the ones you use to deploy images to clusters that do not use Binary Authorization.

Before you begin

Make sure you have the Binary Authorization API enabled in your project and a GKE cluster with Binary Authorization enabled. See setting up on Google Kubernetes Engine or Setting up on Anthos clusters on VMware.

Install kubectl for interacting with GKE.

Configure kubectl

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

To configure kubectl, run the following gcloud command:

gcloud container clusters get-credentials \
    --zone ZONE \
    CLUSTER_NAME

Replace the following:

  • ZONE: the name of the GKE zone where the cluster is running, for example, us-central1-a
  • CLUSTER_NAME: the name of the cluster

Deploy the container image

Deploy your container image as follows:

  1. Configure environment variables:

    POD_NAME=POD_NAME
    IMAGE_PATH=IMAGE_PATH
    IMAGE_DIGEST=IMAGE_DIGEST
    

    Replace the following:

    • POD_NAME: the name you want to use for the GKE workload
    • IMAGE_PATH: path of the image in Artifact Registry, Container Registry, or another registry.
    • IMAGE_DIGEST: the digest of the image manifest. Examples are as follows:

      • Artifact Registry:
        • Path: us-docker.pkg.dev/google-samples/containers/gke/hello-app
        • Digest: sha256:37e5287945774f27b418ce567cd77f4bbc9ef44a1bcd1a2312369f31f9cce567
      • Container Registry:
        • Path: gcr.io/google-samples/hello-app
        • Digest: sha256:c62ead5b8c15c231f9e786250b07909daf6c266d0fcddd93fea882eb722c3be4

      To learn how to get the digest of an image in Artifact Registry, see Managing images; for an image in Container Registry, see Listing the versions of an image.

  2. Deploy your image using the kubectl run command.

    You must deploy the image using the digest rather than a tag like 1.0 or latest, as Binary Authorization uses both the image path and digest to look up attestations.

    To deploy the image, run the following kubectl command:

    kubectl run ${POD_NAME} \
        --image ${IMAGE_PATH}@${IMAGE_DIGEST} --port 8080
    

    Now, verify that the deployment was blocked by Binary Authorization:

    kubectl get pods
    

    You see your Pod listed.

Fail open

GKE users: The enforcement process fails open if GKE is unable to reach the Binary Authorization server for any reason. For example, if you deploy a container image and the Binary Authorization enforcer is unreachable due to a network outage, the image is deployed, even though the enforcer would have blocked it. If Cloud Audit Logs is enabled, the log entry indicates the image deployed with a fail open condition.

Override a policy

Binary Authorization supports a feature known as break-glass that lets you override the policy when you deploy a container image. This feature is implemented in way consistent with recommendations in the Kubernetes admission controller specification.

The following example shows how to create a GKE pod using break-glass to override a policy:

  1. Create a configuration file in YAML format. This file contains the break-glass label as well as other information required to create the pod:

    cat > /tmp/create_pod.yaml << EOM
    apiVersion: v1
    kind: Pod
    metadata:
      name: pod-name
      labels:
        image-policy.k8s.io/break-glass: "true"
    spec:
      containers:
      - name: container-name
        image: gcr.io/google-samples/hello-app@sha256:c62ead5b8c15c231f9e786250b07909daf6c266d0fcddd93fea882eb722c3be4
    EOM
    

    For all earlier Kubernetes master versions, you enable breakglass by adding alpha.image-policy.k8s.io/break-glass to the annotations node, as follows:

    cat > /tmp/create_pod.yaml << EOM
    apiVersion: v1
    kind: Pod
    metadata:
      name: pod-name
      annotations:
        alpha.image-policy.k8s.io/break-glass: "true"
    spec:
      containers:
      - name: container-name
        image: gcr.io/google-samples/hello-app@sha256:c62ead5b8c15c231f9e786250b07909daf6c266d0fcddd93fea882eb722c3be4
    EOM
    
  2. Create the pod using kubectl:

    kubectl create -f YAML_PATH
    

    Replace YAML_PATH with the path to your podspec.

Verify that an image is running

To verify that the image is running, enter the following:

kubectl get pods

The command prints a list of running Pods, like the example below. This indicates that the image was successfully deployed.

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

View audit logs

For more information on viewing enforcement status and deployment messages in Cloud Logging, see Viewing audit logs.

What's next