Use a private image registry

Your GKE on AWS installation can access public container images by default. This topic explains how to use GKE on AWS with a private container image repository, such as Artifact Registry.

Before you begin

To perform the steps on this page, first complete the following:

• Create a cluster.
• Create a node pool.

• Configure cluster access for kubectl.

• Build a Docker image and push it to Artifact Registry. The examples in this page use the hello-app container. To build this container, follow the steps to Build a container image and Push the Docker image to Artifact Registry, part of the GKE on Google Cloud documentation.

Check for images on Artifact Registry

To complete the rest of these steps, you need a container image. Get the name of your container images by performing the following steps:

1. Configure the Docker command-line tool to authenticate to Artifact Registry with Google Cloud SDK:

   gcloud auth configure-docker 

   The gcloud command-line tool registers a credential helper for all Google-supported Docker registries.

2. Confirm that your Artifact Registry includes an image with the docker images command.

   docker images 

   Docker connects to Artifact Registry and returns the images available in your repository. For example, the response below shows a container image named hello-app in the PROJECT_NAME repository on us-west1-docker.pkg.dev.

   REPOSITORY TAG IMAGE ID CREATED SIZE us-west1-docker.pkg.dev/PROJECT_NAME/hello-repo/hello-app v1 f7cfe0d58569 21 minutes ago 11.5MB 

If you do not have a container image ready, create one by following the steps at Deploying a containerized application.

Create a Service Account

Your clusters authenticate using an Identity and Access Management (IAM) service account.

To create a new service account, follow these steps:

1. Create an IAM service account with the Google Cloud CLI.

   gcloud iam service-accounts create ACCOUNT_NAME 

   Replace ACCOUNT_NAME with the name of the new Google Cloud service account.

2. Grant the service account Artifact Registry permissions.

   gcloud projects add-iam-policy-binding PROJECT_NAME \  --member serviceAccount:ACCOUNT_NAME@PROJECT_NAME.iam.gserviceaccount.com \  --role roles/artifactregistry.reader 

   Replace the following:

   • PROJECT_NAME with your Google Cloud project
   • ACCOUNT_NAME with your Google Cloud service account name

3. Download the account's service account key.

   gcloud iam service-accounts keys create registry-access-key.json \  --iam-account ACCOUNT_NAME@PROJECT_NAME.iam.gserviceaccount.com 

   Replace the following:

   • PROJECT_NAME
   • ACCOUNT_NAME

You are now ready to configure your user cluster to connect to Artifact Registry.

Save the key to your cluster

To provide the key to authenticate to Artifact Registry, save the service account key as a Kubernetes Secret with these steps:

1. Use kubectl to create the Secret.

    kubectl create secret docker-registry registry-secret \  --docker-server=LOCATION-docker.pkg.dev \  --docker-username=_json_key \  --docker-email=ACCOUNT_NAME@PROJECT_NAME.iam.gserviceaccount.com \  --docker-password="$(cat registry-access-key.json)" 

   Replace the following:

   • LOCATION: the regional or multi-regional location of the repository.
   • PROJECT_NAME
   • ACCOUNT_NAME

2. Delete the local copy of your service account key.

   rm registry-access-key.json 

You can now reference this Secret in your workloads.

Create a workload with a private image

To use an image from a private container repository with a workload, set the field spec.imagePullSecrets to your Secret name. This field is in different locations for Pods and Deployments.

Creating a Pod

To create a Pod that can access the container registry, you set the field spec.imagePullSecrets to your Secret name.

1. Create a Pod that specifies spec.imagePullSecrets.

   apiVersion: v1 kind: Pod metadata:  name: POD_NAME spec:  containers:  - name: CONTAINER_NAME  image: LOCATION-docker.pkg.dev/PROJECT_NAME/hello-repo/hello-app:v1  imagePullSecrets:  - name: registry-secret 

   Replace the following:

   • POD_NAME: your Pod's name
   • CONTAINER_NAME: the name of the container inside the Pod
   • LOCATION
   • PROJECT_NAME

   For example, to pull the image hello-app, copy the following YAML into a file named hello-pod.yaml.

   apiVersion: v1 kind: Pod metadata:  name: hello-pod spec:  containers:  - name: hello-container  image: us-west1-docker.pkg.dev/example-project/hello-repo/hello-app:v1  imagePullSecrets:  - name: registry-secret 

2. Apply the configuration to your cluster with kubectl.

   kubectl apply -f hello-pod.yaml 

3. Confirm the pod is running with kubectl get.

   kubectl get pod/hello-pod 

   The response includes one Pod with a status of Running.

   NAME READY STATUS RESTARTS AGE hello-pod 1/1 Running 0 15s 

Creating a Deployment

1. To use a private repository in a Deployment, you specify the imagePullSecret inside the template.

   For example, to configure a Deployment that uses the hello-app image, create a file named hello-deployment.yaml with the following contents:

   apiVersion: apps/v1 kind: Deployment metadata:  name: hello-app-deployment spec:  selector:  matchLabels:  app: products  department: sales  replicas: 3  template:  metadata:  labels:  app: products  department: sales  spec:  containers:  - name: hello  image: LOCATION-docker.pkg.dev/PROJECT_NAME/hello-repo/hello-app:v1  env:  - name: "PORT"  value: "50001"  imagePullSecrets:  - name: registry-secret 

   Replace the following:

   • LOCATION
   • PROJECT_NAME

2. Apply the configuration to your cluster with kubectl.

   kubectl apply -f hello-deployment.yaml 

3. Confirm that your Deployment is running with kubectl pods.

   kubectl get pods --selector=app=products 

   The output displays three Running pods.

   NAME READY STATUS RESTARTS AGE hello-app-deployment-67d9c6d98c-b69f2 1/1 Running 0 14m hello-app-deployment-67d9c6d98c-d6k5c 1/1 Running 0 14m hello-app-deployment-67d9c6d98c-p2md5 1/1 Running 0 14m 

Clean up

To remove the resources you created on this page, run these commands:

kubectl apply -f hello-pod.yaml kubectl delete -f hello-deployment.yaml 

What's next

• Read the Artifact Registry overview.