The product described by this documentation, GKE on Azure, is now in maintenance mode and will be shut down on March 17, 2027.

Use a private image registry

Your GKE on Azure installation can access public container images by default. This topic explains how to use GKE on Azure 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:

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.
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:

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.

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

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
Note: The service account key allows access to privileged resources. Protect the key file after downloading it.

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:

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

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.

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

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

Creating a Deployment

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

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

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 .