# 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](https://docs.cloud.google.com/artifact-registry).

## Before you begin

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

- [Create a cluster](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/how-to/create-cluster.md.txt).
- [Create a node pool](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/how-to/create-node-pool.md.txt).
- [Configure cluster access for kubectl](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/how-to/configure-cluster-access-for-kubectl.md.txt).

- 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](https://docs.cloud.google.com/kubernetes-engine/docs/tutorials/hello-app#building_the_container_image)
  and
  [Push the Docker image to Artifact Registry](https://docs.cloud.google.com/kubernetes-engine/docs/tutorials/hello-app#pushing_the_docker_image_to),
  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](https://docs.cloud.google.com/artifact-registry/docs.md.txt) with Google Cloud SDK:

   ```bash
   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.

   ```bash
   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](https://docs.cloud.google.com/kubernetes-engine/docs/tutorials/hello-app).

### Create a Service Account

> [!NOTE]
> **Note:** The following service account will have access to all images in your project. For more information about restricting access, see [Granting permissions](https://docs.cloud.google.com/artifact-registry/docs/access-control.md.txt#grant) in the Artifact Registry documentation.

Your clusters authenticate using an Identity and Access Management (IAM)
[service account](https://docs.cloud.google.com/iam/docs/service-accounts).

To create a new service account, follow these steps:

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

   ```bash
   gcloud iam service-accounts create ACCOUNT_NAME
   ```

   Replace <var translate="no">ACCOUNT_NAME</var> with the name of the new Google Cloud
   service account.
2. Grant the service account
   [Artifact Registry permissions](https://docs.cloud.google.com/artifact-registry/docs/access-control.md.txt#roles).

   ```bash
   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.

   ```bash
   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]
   > **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](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure)
with these steps:

1. Use `kubectl` to create the Secret.

   ```bash
     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](https://docs.cloud.google.com/artifact-registry/docs/repo-locations) of the repository.
   - `PROJECT_NAME`
   - `ACCOUNT_NAME`
2. Delete the local copy of your service account key.

   ```bash
   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](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/how-to/private-registry.md.txt#creating_a_pod) and
[Deployments](https://docs.cloud.google.com/kubernetes-engine/multi-cloud/docs/azure/how-to/private-registry.md.txt#creating_a_deployment).

### 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`.

   ```yaml
   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`.

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

   ```bash
   kubectl apply -f hello-pod.yaml
   ```
3. Confirm the pod is running with `kubectl get`.

   ```bash
   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](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)
   that uses the `hello-app` image, create a file named `hello-deployment.yaml`
   with the following contents:

   ```yaml
   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
   ```

   > [!NOTE]
   > **Note:** `imagePullSecrets` must have the same level of indentation as `containers`.

   Replace the following:
   - `LOCATION`
   - `PROJECT_NAME`
2. Apply the configuration to your cluster with `kubectl`.

   ```bash
   kubectl apply -f hello-deployment.yaml
   ```
3. Confirm that your Deployment is running with `kubectl pods`.

   ```bash
   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](https://docs.cloud.google.com/artifact-registry/docs/overview.md.txt).