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.

Starting from version 1.28, GKE on AWS provides a way of pulling private images from Artifact Registry or Container Registry without having to use a Kubernetes Secret. For details, see Use a private image registry without Secrets.

Before you begin

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

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