Help to setup Google Cloud's Artifact Registry (GAR) with RunPod

This guide details setting up and authenticating Google Artifact Registry (GAR) with RunPod, including service account creation, authentication, image tagging, pushing images to GAR, and deploying them on RunPod via custom templates.

1. Setting Up Authentication

To create a service account using Cloud Shell, navigate to the Google Cloud Console → go to the "IAM & Admin" section → select "Service Accounts" → click on "Activate Cloud Shell" to launch the Cloud Shell environment → use the Cloud Shell to create a service account with the appropriate permissions → use this service account to connect with RunPod.

 

2. Enable Artifact Registry API

First, ensure that the Artifact Registry API is enabled in your Google Cloud project:

gcloud services enable artifactregistry.googleapis.com

 

3. Configure Authentication

You need to authenticate your Docker or another container runtime to access GAR. Here we are using a Service Account (For CI/CD and Automation)

gcloud iam service-accounts create gar-access \
    --display-name "GAR Access Service Account"

 

4. Grant IAM Roles

Assign the necessary permissions to the service account:

gcloud projects add-iam-policy-binding <PROJECT_ID> \
    --member="serviceAccount:gar-access@<PROJECT_ID>.iam.gserviceaccount.com" \
    --role="roles/artifactregistry.reader"  # Use roles/artifactregistry.writer for pushing images

Replace <PROJECT_ID> with your Google Cloud project ID.

For example for me PROJECT_ID = lunar-outlet-453522-m3, then the command will be -

gcloud projects add-iam-policy-binding lunar-outlet-453522-m3 \
    --member="serviceAccount:gar-access@lunar-outlet-453522-m3.iam.gserviceaccount.com" \
    --role="roles/artifactregistry.reader"

5. Create an Artifact Registry Repository
Now, create a repository in Artifact Registry to store your container image:

gcloud artifacts repositories create my-container-repo \
    --repository-format=docker \
    --location=<REGION> \
    --description="My container image repository"

Replace <REGION> with your chosen region.
For example,

gcloud artifacts repositories create my-container-repo \
    --repository-format=docker \
    --location=us-west1 \
    --description="My container image repository"

 

6. Generate a JSON key:

gcloud iam service-accounts keys create key.json \
    --iam-account=gar-access@<PROJECT_ID>.iam.gserviceaccount.com

Replace <PROJECT_ID> with your Google Cloud project ID mentioned above. For example,

gcloud iam service-accounts keys create key.json \
    --iam-account=gar-access@lunar-outlet-453522-m3.iam.gserviceaccount.com

7.  Authenticate Docker with the Service Account

cat key.json | docker login -u _json_key --password-stdin https://us-west1-docker.pkg.dev

 

8. Pull a Small Sample Container Image

For this demo, let's use the official hello-world image, which is lightweight:

docker pull hello-world

Or  an Image with a version:

docker pull ubuntu:20.04

9.  Tag the Image for Your GCP Registry

Tag the image so it points to your Artifact Registry repository:

docker tag hello-world <REGION>-docker.pkg.dev/<PROJECT_ID>/my-container-repo/hello-world

Replace: <REGION> with your region  and  <PROJECT_ID> with your Google Cloud project ID.

For example:

docker tag hello-world us-west1-docker.pkg.dev/lunar-outlet-453522-m3/my-container-repo/hello-world

For ubuntu:20.04 -

docker tag ubuntu:20.04 us-west1-docker.pkg.dev/lunar-outlet-453522-m3/my-container-repo/ubuntu:20.04

 

10. Push the Image to Artifact Registry
Now, push the image to GAR:

docker push <REGION>-docker.pkg.dev/<PROJECT_ID>/my-container-repo/hello-world

Replace: <REGION> with your region  and  <PROJECT_ID> with your Google Cloud project ID.

For example:

docker push us-west1-docker.pkg.dev/lunar-outlet-453522-m3/my-container-repo/hello-world

For ubuntu:20.04 -

docker push us-west1-docker.pkg.dev/lunar-outlet-453522-m3/my-container-repo/ubuntu:20.04

 

11. Verify the Image in Artifact Registry
Check if the image was successfully uploaded

gcloud artifacts docker images list <REGION>-docker.pkg.dev/<PROJECT_ID>/my-container-repo

Replace: <REGION> with your region and  <PROJECT_ID> with your Google Cloud project ID.

For example,

gcloud artifacts docker images list us-west1-docker.pkg.dev/lunar-outlet-453522-m3/my-container-repo

12. Encode the JSON Key in Base64
Run the following command to encode the JSON key file which we created before

cat key.json | base64 -w 0

 

13. RunPod Authentication with Google Artifact Registry (GAR)
  - Go to RunPod's settings page and navigate to "Container Registry Auth"
  - Create a new registry credential
  - For the username, use _json_key_base64
  - For the password, paste the base64-encoded version of your JSON key file (which we created in the previous step). While copying the base64-encoded version, make sure to copy until *****== to ensure it works.

14. Creating a New Template in RunPod Using Google Artifact Registry (GAR)

- Log in to RunPod account. Navigate to "Templates" and click "Create New Template".

- Retrieve Image Details from Google Artifact Registry. Open Google Cloud Shell and run the following command to list your container images

- While creating a template take the image details from Cloud Shell environment using the below command:

gcloud artifacts docker images list <REGION>-docker.pkg.dev/<PROJECT_ID>/my-container-repo

Replace: <REGION> with your region  and  <PROJECT_ID> with your Google Cloud project ID.

For example,

gcloud artifacts docker images list us-west1-docker.pkg.dev/lunar-outlet-453522-m3/my-container-repo

This will display available images with their full paths.
For hello world:

IMAGE: us-west1-docker.pkg.dev/lunar-outlet-453522-m3/my-container-repo/hello-world

For ubuntu:20.04 -

IMAGE: us-west1-docker.pkg.dev/lunar-outlet-453522-m3/my-container-repo/ubuntu

- Copy the image path to create the template.  When specifying the image in the template, use the Correct Image Tag

For example, for hello-world, since no version is mentioned, use :latest while creating the template to ensure it fetches the latest image.

us-west1-docker.pkg.dev/lunar-outlet-453522-m3/my-container-repo/hello-world:latest

For ubuntu:20.04(Version specific) -

us-west1-docker.pkg.dev/lunar-outlet-453522-m3/my-container-repo/ubuntu:20.04

- Select the registry credentials that were added earlier in the Container Registry Auth section and save the template.

 

15. Deploy a New Pod Using the Custom Template

- Navigate to "Pods" and click "Deploy New Pod".
- Deploy a New Pod Using the Custom Template we created before. 
- Select the custom template created in the previous step. Configure resources as needed and start the pod.

Your RunPod instance should now be successfully pulling and running the container from Google Artifact Registry.