This page explains how to deploy a container image to a GKE cluster (on
Google Cloud or Google Distributed Cloud) 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 don't 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](https://docs.cloud.google.com/binary-authorization/docs/setting-up) or
[setting up on Distributed Cloud](https://docs.cloud.google.com/binary-authorization/docs/setting-up-on-prem).

Install [`kubectl`](https://kubernetes.io/docs/tasks/tools/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 or Distributed Cloud.

To configure `kubectl`, run the following `gcloud` command:

### GKE

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

Replace the following:

- <var translate="no">ZONE</var>: the name of the GKE zone where the cluster is running, for example, `us-central1-a`
- <var translate="no">CLUSTER_NAME</var>: the name of the cluster

### Distributed Cloud

```
gcloud container fleet memberships get-credentials \
    --location LOCATION \
    MEMBERSHIP_NAME
```

Replace the following:

- <var translate="no">LOCATION</var>: the location of the fleet membership of the GKE cluster, for example, `global`
- <var translate="no">MEMBERSHIP_NAME</var>: the name of the fleet membership of the GKE 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:
   - <var translate="no">POD_NAME</var>: the name you want to use for the GKE workload
   - <var translate="no">IMAGE_PATH</var>: path of the image in [Artifact Registry](https://docs.cloud.google.com/artifact-registry/docs), or another registry.
   - <var translate="no">IMAGE_DIGEST</var>: the digest of the image manifest.
     Example is as follows:

     - Artifact Registry:
       - Path: `us-docker.pkg.dev/google-samples/containers/gke/hello-app`
       - Digest: `sha256:37e5287945774f27b418ce567cd77f4bbc9ef44a1bcd1a2312369f31f9cce567`

     To learn how to get the digest of an image in Artifact Registry, see
     [Managing images](https://docs.cloud.google.com/artifact-registry/docs/docker/manage-images#gcloud).
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 the digest to look up
   [attestations](https://docs.cloud.google.com/binary-authorization/docs/key-concepts#attestations).

   To deploy the image, run the following `kubectl` command:

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

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

   ```
   kubectl get pods
   ```

   You see your Pod listed.

## Limitations

At deployment time, Binary Authorization only scans images in the
`containers` and `ephemeralContainers` fields of the
[PodSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.36/#podspec-v1-core).
No other fields are scanned.
[Init containers](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/)
and [image volumes](https://kubernetes.io/docs/tasks/configure-pod-container/image-volumes/)
aren't scanned at deployment time.

## Fail open

<br />

If GKE is unable to reach the Binary Authorization
server for any reason, or if the server returns an error,
GKE cannot determine whether Binary Authorization
would allow or deny the image. In this case, GKE fails open: it defaults to allowing the image to be deployed, but creates a log entry in
Cloud Audit Logs to record why the image was allowed.

GKE enforcement fails open because of a tradeoff between
reliability and security. GKE sends a request to the
Binary Authorization whenever a Pod is created or updated. This includes
scenarios where Pods are automatically created or updated by higher level
Kubernetes workload controllers, like ReplicaSets and StatefulSets. If
GKE failed closed instead of open, any
Binary Authorization outage would stop these Pods from running. Moreover,
when Pods are denied, failover can lead to cascading failures as redirected
traffic overloads Pods that are still running. Any Binary Authorization
outage could trigger a complete outage for your cluster, even without
deploying any new images.

> [!NOTE]
> **Note:** Operations that send enough requests to Binary Authorization to exceed the per-project, per-user, per-minute [quota](https://docs.cloud.google.com/binary-authorization/quotas) will trigger fail open. For example, testing whether Binary Authorization denies an image by trying to rapidly deploy that image repeatedly will cause the image to be allowed when the quota is exceeded. It is possible to [request additional
> quota](https://docs.cloud.google.com/binary-authorization/quotas#quota_increases), if needed.

## Deploy images that violate the policy

Binary Authorization supports a feature known as *breakglass* that allows an image
to be deployed, even if it violates the policy.

For more information, see [Using breakglass](https://docs.cloud.google.com/binary-authorization/docs/using-breakglass)

## Clean up

To clean up, delete the Pod by executing the following command:

<br />

```
  kubectl delete pod ${POD_NAME}
  
```

<br />

## What's next

- Learn about [dry-run mode](https://docs.cloud.google.com/binary-authorization/docs/enabling-dry-run).
- Learn how to [use CV](https://docs.cloud.google.com/binary-authorization/docs/overview-cv).
- Learn how to [use legacy continuous validation](https://docs.cloud.google.com/binary-authorization/docs/using-cv) ([deprecated](https://docs.cloud.google.com/binary-authorization/docs/deprecations/cv-project-singleton-policy)).
- Learn how to [use image digests in Kubernetes manifests](https://docs.cloud.google.com/architecture/using-container-image-digests-in-kubernetes-manifests).