Pull an Image from a Private Registry

    🛇 This item links to a third party project or product that is not part of Kubernetes itself. More information

    • You need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. It is recommended to run this tutorial on a cluster with at least two nodes that are not acting as control plane hosts. If you do not already have a cluster, you can create one by using or you can use one of these Kubernetes playgrounds:

    • To do this exercise, you need the docker command line tool, and a Docker ID for which you know the password.

    Log in to Docker Hub

    On your laptop, you must authenticate with a registry in order to pull a private image.

    Use the docker tool to log in to Docker Hub. See the log in section of Docker ID accounts for more information.

    When prompted, enter your Docker ID, and then the credential you want to use (access token, or the password for your Docker ID).

    The login process creates or updates a config.json file that holds an authorization token. Review .

    View the config.json file:

    1. cat ~/.docker/config.json

    The output contains a section similar to this:

    1. {
    2.     "auths": {
    3.         "https://index.docker.io/v1/": {
    4.             "auth": "c3R...zE2"
    5.         }
    6.     }
    7. }

    Note: If you use a Docker credentials store, you won’t see that auth entry but a credsStore entry with the name of the store as value.

    A Kubernetes cluster uses the Secret of kubernetes.io/dockerconfigjson type to authenticate with a container registry to pull a private image.

    1. kubectl create secret generic regcred \
    2.     --from-file=.dockerconfigjson=<path/to/.docker/config.json> \
    3.     --type=kubernetes.io/dockerconfigjson

    If you need more control (for example, to set a namespace or a label on the new secret) then you can customise the Secret before storing it. Be sure to:

    • base64 encode the docker file and paste that string, unbroken as the value for field data[".dockerconfigjson"]
    • set type to kubernetes.io/dockerconfigjson

    Example:

    1. apiVersion: v1
    2. kind: Secret
    3. metadata:
    5.   namespace: awesomeapps
    6. data:
    7.   .dockerconfigjson: UmVhbGx5IHJlYWxseSByZWVlZWVlZWVlZWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWxsbGxsbGxsbGxsbGxsbGxsbGxsbGxsbGxsbGxsbGx5eXl5eXl5eXl5eXl5eXl5eXl5eSBsbGxsbGxsbGxsbGxsbG9vb29vb29vb29vb29vb29vb29vb29vb29vb25ubm5ubm5ubm5ubm5ubm5ubm5ubm5ubmdnZ2dnZ2dnZ2dnZ2dnZ2dnZ2cgYXV0aCBrZXlzCg==
    8. type: kubernetes.io/dockerconfigjson

    If you get the error message error: no objects passed to create, it may mean the base64 encoded string is invalid. If you get an error message like Secret "myregistrykey" is invalid: data[.dockerconfigjson]: invalid value ..., it means the base64 encoded string in the data was successfully decoded, but could not be parsed as a .docker/config.json file.

    Create a Secret by providing credentials on the command line

    Create this Secret, naming it regcred:

    where:

    • <your-registry-server> is your Private Docker Registry FQDN. Use https://index.docker.io/v1/ for DockerHub.
    • <your-name> is your Docker username.
    • <your-pword> is your Docker password.
    • <your-email> is your Docker email.

    You have successfully set your Docker credentials in the cluster as a Secret called regcred.

    Note: Typing secrets on the command line may store them in your shell history unprotected, and those secrets might also be visible to other users on your PC during the time that kubectl is running.

    To understand the contents of the regcred Secret you created, start by viewing the Secret in YAML format:

    1. kubectl get secret regcred --output=yaml

    The output is similar to this:

    1. apiVersion: v1
    2. kind: Secret
    3. metadata:
    4.   ...
    5.   name: regcred
    6.   ...
    7. data:

    The value of the .dockerconfigjson field is a base64 representation of your Docker credentials.

    1. kubectl get secret regcred --output="jsonpath={.data.\.dockerconfigjson}" | base64 --decode

    The output is similar to this:

    1. {"auths":{"your.private.registry.example.com":{"username":"janedoe","password":"xxxxxxxxxxx","email":"jdoe@example.com","auth":"c3R...zE2"}}}

    To understand what is in the auth field, convert the base64-encoded data to a readable format:

    The output, username and password concatenated with a :, is similar to this:

    1. janedoe:xxxxxxxxxxx

    Notice that the Secret data contains the authorization token similar to your local ~/.docker/config.json file.

    You have successfully set your Docker credentials as a Secret called regcred in the cluster.

    Create a Pod that uses your Secret

    Here is a manifest for an example Pod that needs access to your Docker credentials in regcred:

    pods/private-reg-pod.yaml 

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: private-reg
    5. spec:
    6.   containers:
    7.   - name: private-reg-container
    8.     image: <your-private-image>
    9.   imagePullSecrets:
    10.   - name: regcred

    Download the above file onto your computer:

    1. curl -L -O my-private-reg-pod.yaml https://k8s.io/examples/pods/private-reg-pod.yaml

    In file my-private-reg-pod.yaml, replace <your-private-image> with the path to an image in a private registry such as:

    1. your.private.registry.example.com/janedoe/jdoe-private:v1

    To pull the image from the private registry, Kubernetes needs credentials. The imagePullSecrets field in the configuration file specifies that Kubernetes should get the credentials from a Secret named regcred.