DEV Community

Suave Bajaj
Suave Bajaj

Posted on

Authenticate Docker with Google Artifact Registry (Private Repo) Using a Service Account


⚑ TL;DR: Want to push/pull private Docker images from Google Artifact Registry? Use a Google Cloud service account with docker login -u _json_key, then use the .docker/config.json for Kubernetes integration.


🧰 Prerequisites

Make sure you have the following:

  • Docker installed locally or in your CI/CD agent
  • Google Cloud SDK (gcloud)
  • A private Artifact Registry (e.g. us-central1-docker.pkg.dev/<project>/<repo>)
  • A service account with Artifact Registry Reader or Writer permissions

βš™οΈ Step 1: Create a Service Account Key

Create a key file to authenticate Docker later:

# Create a new key for your artifact registry service account
gcloud iam service-accounts keys create key.json \
  --iam-account=gar-access@<PROJECT_ID>.iam.gserviceaccount.com
Enter fullscreen mode Exit fullscreen mode

This will download a key.json file locally.


πŸ” Step 2: Authenticate Docker with the Key

Use the service account to log in to your private Artifact Registry:

# Replace the region with your registry's location
cat key.json | docker login -u _json_key --password-stdin https://us-central1-docker.pkg.dev
Enter fullscreen mode Exit fullscreen mode

This command updates your ~/.docker/config.json to include authentication for the private registry.


πŸ“ What the Docker Config File Looks Like

After successful login, your ~/.docker/config.json will look like this:

{
  "auths": {
    "https://us-central1-docker.pkg.dev": {
      "auth": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."  // Base64 token
    }
  },
"currentContext": "colima" // As per your docker client
}
Enter fullscreen mode Exit fullscreen mode

You can use this file:

  • As a Kubernetes image pull secret
  • In CI/CD pipelines
  • For temporary access without gcloud

πŸš€ Use in CI/CD and Kubernetes

πŸ§ͺ In CI/CD (GitHub Actions, GitLab, Jenkins, etc.)

You can use the same docker login step using the service account key during your pipeline execution.

πŸ“¦ In Kubernetes

To use this config as a Kubernetes secret:

kubectl create secret generic regcred \
  --from-file=.dockerconfigjson=$HOME/.docker/config.json \
  --type=kubernetes.io/dockerconfigjson
Enter fullscreen mode Exit fullscreen mode

Reference it in your Deployment:

apiVersion: v1
kind: Pod
metadata:
  name: private-reg
spec:
  containers:
  - name: private-reg-container
    image: <your-private-image>
  imagePullSecrets:
  - name: regcred
Enter fullscreen mode Exit fullscreen mode

πŸ” Verify the Setup

Once authenticated, verify the setup by building, tagging, and pushing an image to your private Artifact Registry.

πŸ› οΈ Build the Docker Image

docker build -t myapp:latest .
#Replace myapp with your actual app name, and ensure your Dockerfile is in the current directory.
Enter fullscreen mode Exit fullscreen mode
🏷️ Tag the Image
docker tag myapp:latest us-central1-docker.pkg.dev/<project>/<repo>/myapp:latest
#Replace <project> and <repo> with your actual GCP project ID and Artifact Registry repository.
Enter fullscreen mode Exit fullscreen mode
πŸ“€ Push the Image
docker push us-central1-docker.pkg.dev/<project>/<repo>/myapp:latest
Enter fullscreen mode Exit fullscreen mode
πŸ“₯ Optionally, Pull to Confirm
docker pull us-central1-docker.pkg.dev/<project>/<repo>/myapp:latest
Enter fullscreen mode Exit fullscreen mode

If these steps complete without errors, your service account authentication and private registry access are working perfectly!


βœ… Summary and References

  • Use a Google Cloud service account with _json_key to securely access private Artifact Registry images.
  • docker login will generate a valid config.json.
  • Use that config for Kubernetes and CI/CD integration.
  • No need for gcloud runtime dependencies in CI.

Top comments (0)