How to Make Kubernetes Pull Images from an Authenticated Registry

When deploying applications in Kubernetes, you might need to use container images stored in a private or authenticated registry. By default, Kubernetes cannot pull images from registries that require authentication. To solve this, you must provide the registry credentials to Kubernetes in a secure way.

In this blog post, we’ll explain how to configure Kubernetes to pull images from an authenticated registry using both command-line options and a dockerconfigjson Secret. Let’s start!

1. Using the Command Line to Create a Docker Registry Secret

The simplest way to let Kubernetes access your private registry is by creating a Docker registry Secret using the kubectl command. Here’s how you can do it:

Command

kubectl create secret docker-registry my-registry-secret \
  --docker-server=dockerhub.example.com \
  --docker-username=your-username \
  --docker-password=your-password \
  --docker-email=your-email@example.com

Explanation

• my-registry-secret: The name of the Secret you are creating.
• --docker-server: The URL of your private container registry (e.g., dockerhub.example.com).
• --docker-username: Your registry username.
• --docker-password: Your registry password or access token.
• --docker-email: Your email address.

Check if the Secret is Created

kubectl get secret my-registry-secret

2. Using a YAML File to Create a Docker Registry Secret

If you prefer a declarative approach, you can create a Secret using a YAML file. This method is useful for version-controlling your configurations.

Steps

1. Generate a .dockerconfigjson File

            Create the Docker credentials file manually:

        {
          "auths": {
                "dockerhub.example.com": {
                  "username": "your-username",
                  "password": "your-password",
                  "email": "your-email@example.com",
                  "auth": "base64_encoded_username_and_password"
                }
          }
        }

        To get the value for auth (which is username:password encoded in Base64), run:

        echo -n "your-username:your-password" | base64

2. Encode the .dockerconfigjson

        Base64-encode the entire .dockerconfigjson file:

        cat .dockerconfigjson | base64

3. Write the YAML File

        Here’s an example YAML file (docker-registry-secret.yaml):

        apiVersion: v1
        kind: Secret
        metadata:
          name: my-registry-secret
          namespace: default
        type: kubernetes.io/dockerconfigjson
        data:
          .dockerconfigjson: eyJhdXRocyI6eyJkb2NrZXJodWIuZXhhbXBsZS5jb20iOnsidXNlcm5hbWUiOiJ5b3VyLXVzZXJuYW1lIiwicGFzc3dvcmQiOiJ5b3VyLXBhc3N3b3JkIiwiZW1haWwiOiJ5b3VyLWVtYWlsQGV4YW1wbGUuY29tIiwiYXV0aCI6ImJhc2U2NF9lbmNvZGVkX3VzZXJuYW1lX2FuZF9wYXNzd29yZCJ9fX0=

4. Apply the YAML File

            Run the following command to create the Secret:

        kubectl apply -f docker-registry-secret.yaml

3. Using the Secret in a Deployment

Once the Secret is created, you need to tell Kubernetes to use it when pulling images. This is done by adding the imagePullSecrets field to your Pod or Deployment specification.

Here’s an example Deployment YAML file:

Deployment YAML

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-container
          image: dockerhub.example.com/my-private-image:latest
      imagePullSecrets:
        - name: my-registry-secret

Apply the Deployment:

    kubectl apply -f deployment.yaml

4. Verifying the Setup

1. Check Pod Status After applying the Deployment, verify the Pod status:

   kubectl get pods

2. Inspect Events for Errors If the Pod is not starting, describe it to check for errors:

   kubectl describe pod <pod-name>