k8s-digester

README

Digester

Digester resolves tags to digests for container and init container images in Kubernetes Pod and Pod template specs.

It replaces container image references that use tags:

spec:
  containers:
  - image: gcr.io/google-containers/echoserver:1.10

With references that use the image digest:

spec:
  containers:
  - image: gcr.io/google-containers/echoserver:1.10@sha256:cb5c1bddd1b5665e1867a7fa1b5fa843a47ee433bbb75d4293888b71def53229

Digester can run either as a mutating admission webhook in a Kubernetes cluster, or as a client-side Kubernetes Resource Model (KRM) function with the kpt or kustomize command-line tools.

If a tag points to an image index or manifest list, digester resolves the tag to the digest of the image index or manifest list.

The webhook is opt-in at the namespace level by label, see Deploying the webhook.

If you use Binary Authorization, digester can help to ensure that only verified container images can be deployed to your clusters. A Binary Authorization attestation is valid for a particular container image digest. You must deploy container images by digest so that Binary Authorization can verify the attestations for the container image. You can use digester to deploy container images by digest.

Running the KRM function

1. Download the digester binary for your platform from the Releases page.

   Alternatively, you can download the latest version using these commands:

   VERSION=v0.1.8
   curl -Lo digester "https://github.com/google/k8s-digester/releases/download/${VERSION}/digester_$(uname -s)_$(uname -m)"
   chmod +x digester
   

2. Install kpt v1.0.0-beta.1 or later, and/or install kustomize v3.7.0 or later.

3. Run the digester KRM function:

   • Using kpt:

     kpt fn eval [manifest directory] --exec ./digester
     

   • Using kustomize:

     kustomize fn run [manifest directory] --enable-exec --exec-path ./digester
     

   By running as an executable, the digester KRM function has access to container image registry credentials in the current environment, such as the current user's Docker config file and credential helpers. For more information, see the digester documentation on Authenticating to container image registries.

Deploying the webhook

The digester webhook requires Kubernetes v1.16 or later.

1. If you use Google Kubernetes Engine (GKE), grant yourself the cluster-admin Kubernetes cluster role:

   kubectl create clusterrolebinding cluster-admin-binding \
       --clusterrole cluster-admin \
       --user "$(gcloud config get-value core/account)"
   

2. Install the digester webhook in your Kubernetes cluster:

   VERSION=v0.1.8
   kubectl apply -k "https://github.com/google/k8s-digester.git/manifests/?ref=${VERSION}"
   

3. Add the digest-resolution: enabled label to namespaces where you want the webhook to resolve tags to digests:

   kubectl label namespace [NAMESPACE] digest-resolution=enabled
   

To configure how the webhook authenticates to your container image registries, see the documentation on Authenticating to container image registries.

If you want to install the webhook using kpt, follow the steps in the package documentation.

If you want to apply a pre-rendered manifest, you can download an all-in-one manifest file for a released version from the Releases page.

Private clusters

If you install the webhook in a private Google Kubernetes Engine (GKE) cluster, you must add a firewall rule. In a private cluster, the nodes only have internal IP addresses. The firewall rule allows the API server to access the webhook running on port 8443 on the cluster nodes.

1. Create an environment variable called CLUSTER. The value is the name of your cluster that you see when you run gcloud container clusters list:

   CLUSTER=[your private GKE cluster name]
   

2. Look up the IP address range for the cluster API server and store it in an environment variable:

   API_SERVER_CIDR=$(gcloud container clusters describe $CLUSTER \
       --format 'value(privateClusterConfig.masterIpv4CidrBlock)')
   

3. Look up the network tags for your cluster nodes and store them comma-separated in an environment variable:

   TARGET_TAGS=$(gcloud compute firewall-rules list \
       --filter "name~^gke-$CLUSTER" \
       --format 'value(targetTags)' | uniq | paste -d, -s -)
   

4. Create a firewall rule that allow traffic from the API server to the cluster nodes on TCP port 8443:

   gcloud compute firewall-rules create allow-api-server-to-digester-webhook \
       --action ALLOW \
       --direction INGRESS \
       --source-ranges "$API_SERVER_CIDR" \
       --rules tcp:8443 \
       --target-tags "$TARGET_TAGS"
   

You can read more about private cluster firewall rules in the GKE private cluster documentation.

Documentation

• Tutorial

• Motivation

• Recommendations

• Authenticating to container image registries

• Configuring GKE Workload Identity for authenticating to Container Registry and Artifact Registry

• Resolving common issues

• Troubleshooting

• Building digester

• Developing digester

• Releasing digester

Disclaimer

This is not an officially supported Google product.