This documentation is for the current version of GKE on AWS, released in November 2021. See the Release notes for more information.

Use a private image registry without Secrets

GKE on AWS provides a way of pulling private images from Artifact Registry or Container Registry without having to use a Kubernetes Secret. Previously, you had to perform the following steps:

Create a Google Identity and Access Management (IAM) service account.
Grant the service account permissions to access the private registry.
Download the service account key and save it as a Kubernetes Secret in your cluster.
Reference this Secret in your YAML manifest for Pods or Deployments so that they can access images from the private container repository.
Regularly rotate and manage the keys associated with the Google IAM service account.

GKE on AWS eliminates all of these manual steps, and automatically handles the authentication and authorization required for pulling private images.

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.
Upgrade to version 1.28 of GKE on AWS so that you can pull private images from Artifact Registry or Container Registry without having to use a Kubernetes Secret.

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:

Configure the Docker command-line tool to authenticate to Artifact Registry with Google Cloud SDK:
```
gcloud auth configure-docker
```
The Google Cloud CLI registers a credential helper for all Google-supported Docker registries.
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 following response 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 don't have a container image ready, create one by following the steps at Deploying a containerized application.

Create Pods with private images without image pull Secrets

To create a Pod that can access a private container image from a registry, you no longer need to provide the spec.imagePullSecrets field in your Pod specification. To set up your Pod, perform these steps:

Create a Pod definition without the spec.imagePullSecrets field:
```
apiVersion: v1
kind: Pod
metadata:
  name: POD_NAME
spec:
  containers:
  - name: CONTAINER_NAME
    image: LOCATION-docker.pkg.dev/PROJECT_NAME/REPOSITORY_NAME/IMAGE_NAME:IMAGE_VERSION
```
Replace the following:
- POD_NAME: the name of the Pod.
- CONTAINER_NAME: the name of the container inside the Pod.
- LOCATION: the Google Cloud region that contains your registry. For example, us-west1.
- PROJECT_NAME: the name of the Google Project hosting your Artifact Registry repository, which might be the same as your cluster's project. If the repository is in a different project, see Use Artifact Registry when it's not in the same project as your cluster for additional steps.
- REPOSITORY_NAME: the name of your repository.
- IMAGE_NAME: the name of the image.
- IMAGE_VERSION: the version of the image.
Apply the configuration to your cluster with kubectl:
```
kubectl apply -f YAML_FILE_NAME
```
Replace YAML_FILE_NAME with the name of your YAML file.

Example of creating Pods without image pull Secrets

Here's an example of creating a Kubernetes Pod without the need for image pull Secrets. The Pod pulls the hello-app image from Artifact Registry.

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

Apply the configuration to your cluster with kubectl:
```
kubectl apply -f hello-pod.yaml
```

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

Create Deployments with private images without image pull Secrets

To create a Deployment that can access a private container image from a registry, you no longer need to provide the spec.imagePullSecrets field in your Deployment specification. To set up your Deployment, perform these steps:

Create a Deployment definition without the spec.imagePullSecrets field:
```
apiVersion: apps/v1
kind: Deployment
metadata:
  name: DEPLOYMENT_NAME
spec:
  replicas: NUMBER_OF_REPLICAS
  template:
    spec:
      containers:
      - name: CONTAINER_NAME
        image: LOCATION-docker.pkg.dev/PROJECT_NAME/REPOSITORY_NAME/IMAGE_NAME:IMAGE_VERSION
```
Replace the following:
- DEPLOYMENT_NAME: the name of your Deployment.
- NUMBER_OF_REPLICAS: how many instances of the Pod defined in the Deployment should be running at any given time.
- CONTAINER_NAME: the name of the container inside the Pod.
- LOCATION: the Google Cloud region that contains your registry. For example, us-west1.
- PROJECT_NAME: the name of the Google Project hosting your Artifact Registry repository, which might not be the same as your cluster's project. If the repository is in a different project, see Use Artifact Registry when it's not in the same project as your cluster for additional steps.
- REPOSITORY_NAME: the name of your repository.
- IMAGE_NAME: the name of the image.
- IMAGE_VERSION: the version of the image.
Apply the configuration to your cluster with kubectl.
```
kubectl apply -f name-of-your-yaml-file.yaml
```

Example of creating a Deployment without image pull Secrets

Here's an example of creating a Deployment without image pull Secrets. The Deployment pulls a hello-app image from Artifact Registry.

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"

Replace the following:

LOCATION: the Google Cloud region that contains your registry. For example, us-west1.
PROJECT_NAME: the name of the Google Project hosting your Artifact Registry repository, which might not be the same as your cluster's project. If the repository is in a different project, see Use Artifact Registry when it's not in the same project as your cluster for additional steps.

Apply the configuration to your cluster with kubectl.
```
kubectl apply -f hello-deployment.yaml
```

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

Use Artifact Registry when it's not in the same project as your cluster

To use an Artifact Registry repository that's in a Google Project different from the one containing your cluster, perform the following steps:

Give the service account for your cluster's node pool virtual machine instances, known as the Node pool Machine Service Agent, the necessary permissions to access this registry.

gcloud projects add-iam-policy-binding AR_PROJECT_ID \
  --member=NODE_POOL_MACHINE_SERVICE_AGENT \
  --role=ROLE

This step ensures your cluster can retrieve artifacts from the registry in that separate project.

Replace the following:

AR_PROJECT_ID: the ID of the Google project hosting the Artifact Registry.
NODE_POOL_MACHINE_SERVICE_AGENT: the service account for your cluster's Node Pool, which has the following format: service-CLUSTER_RESOURCE_PROJECT_NUMBER@gcp-sa-gkemulticloudnpmachine.iam.gserviceaccount.com
ROLE: the role roles/artifactregistry.reader or a custom role that grants sufficient permissions for accessing images in the Artifact Registry repository.

Use private Google Container Registry

To integrate a private Google Container Registry with your GKE on AWS cluster, regardless of its Google project location, follow these steps:

Allow the Node Pool Machine Service Agent, the service account for your cluster's node pool virtual machine instances, to access the Container Registry:

gcloud projects add-iam-policy-binding GCR_PROJECT_ID \
  --member=NODE_POOL_MACHINE_SERVICE_AGENT \
  --role=ROLE

This step enables cluster service account access to the private container images.

Replace the following:

GCR_PROJECT_ID: the ID of the project hosting the Container Registry.
NODE_POOL_MACHINE_SERVICE_AGENT: the node pool service account, in the format service-CLUSTER_RESOURCE_PROJECT_NUMBER@gcp-sa-gkemulticloudnpmachine.iam.gserviceaccount.com.
ROLE: choose storage.objectViewer or a custom role for sufficient Container Registry access. Be cautious of broad access with storage.objectViewer.

Clean up

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

kubectl apply -f POD_YAML_FILE
kubectl delete -f DEPLOYMENT_YAML_FILE

Replace the following:

POD_YAML_FILE: the name of the YAML file in which you defined the Pod.
DEPLOYMENT_YAML_FILE: the name of the YAML file in which you defined the Deployment.

What's next

Read the Artifact Registry overview.