How to Use Your Private DigitalOcean Container Registry with Docker and Kubernetes

The DigitalOcean Container Registry (DOCR) is a private Docker image registry that lets you store and manage private container images. DOCR integrates natively with Docker environments and DigitalOcean Kubernetes clusters.

Configure Docker to Push to and Pull from the Registry

To interact with your registry using the docker command-line interface (CLI), you need to configure docker using the DigitalOcean command-line tool, doctl. Install doctl and authenticate it with an API token.

Then, call the registry login command:

doctl registry login

This command adds credentials to docker so that pull and push commands to your DigitalOcean registry are authenticated.

Note

This command generates a DigitalOcean token that grants docker access to your account. You can revoke this token at any time by navigating to API in the DigitalOcean Control Panel. If you’re in an environment that doesn’t have doctl or if you want to use an existing API token, you can simulate what doctl registry login does by using your registered email as the username and API token string as password when calling docker login. For example:

docker login -u [email protected] -p ZDRhYzzzz registry.digitalocean.com

You can then use the docker tag command to tag your image with the fully qualified destination path, and docker push to upload it:

docker tag <my-image> registry.digitalocean.com/<my-registry>/<my-image>
docker push registry.digitalocean.com/<my-registry>/<my-image>

Integrate Your Registry with DigitalOcean Kubernetes Cluster

You can integrate DigitalOcean Container Registry with DigitalOcean Kubernetes using one of the following options:

• In the control panel: This is the recommended option. Provides 1-click integration of the registry with DigitalOcean Kubernetes clusters and allows you to use images from the registry in your Kubernetes workloads.

• Using kubectl: Manually create secrets using kubectl and then specify them as imagePullSecrets for your Kubernetes clusters.

Option 1: Adding Secret to All Namespaces in Kubernetes Clusters (Recommended)

In the control panel, you can select the Kubernetes clusters to use with your registry. This generates a secret, adds it to all the namespaces in the cluster and updates the default service account to include the secret, allowing you to pull images from the registry.

Note

You can only integrate the latest Kubernetes patch versions (1.19+) with the registry. For more information on upgrading your Kubernetes clusters, see How to Upgrade DOKS Clusters to Newer Versions.

Visit the registry page and click the Settings tab. In the DigitalOcean Kubernetes integration section, click Edit to display the available Kubernetes clusters. Select the clusters you wish to add and click Save.

The control panel displays an error message if the control plane of the cluster is unavailable or the version of the cluster is not compatible with the registry integration. Upgrade your cluster version to continue with the integration.

Once the secret is added to all the namespaces for the selected Kubernetes clusters, the control panel displays the namespaces which have the secret associated with them.

The default service account in each of those namespaces is updated to include the secret in its image pull secret. From then on, you only need to configure the container image name in your workloads. If you want to use the generated secrets as imagePullSecrets for a specific workload or other service accounts, see Using the Generated Secrets.

To add or remove secrets from the namespaces, click Edit.

Using the Generated Secrets

The secret is created in the kube-system namespace of the Kubernetes cluster.

    
        
            
apiVersion: v1
kind: Secret
metadata:
  name: <registry_name>
  namespace: kube-system
  annotations:
    digitalocean.com/dosecret-identifier: <registry_name>
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <docker_credentials>

        
    

Once this secret is created, DOKS internally copies the secret data to all other namespaces as shown below:

    
        
            
apiVersion: v1
kind: Secret
metadata:
  name: <registry_name>
  namespace: all namespaces other than kube-system
  labels:
    digitalocean.com/copy-identifier: <registry_name>
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <docker_credentials>

        
    

You can also use the generated secrets with the other service accounts or for a specific workload. To do so, add imagePullSecrets to the service account or workload. For more information, consult the Kubernetes documentation.

Option 2: Manually Create and Reference Secrets as imagePullSecrets

To create a secret using kubectl and specify it as an imagePullSecrets:

1. Upload the credentials of your registry to your DigitalOcean Kubernetes cluster. There are two ways to do this:

   • Use the registry kubernetes-manifest command to download the credentials for your registry and upload them to your cluster as a secret:

     doctl registry kubernetes-manifest | kubectl apply -f -
     

     The secret is named registry-<your-registry-name>.

   • Obtain credentials from the control panel and upload them manually to the cluster. To download credentials from the control panel, navigate to the registry page. Then, click Download Docker Credentials to download the credentials as a JSON file.

     Once you have the credentials on your machine, upload them to your cluster as a secret. Here, we’ve named the secret do-registry:

     kubectl create secret generic do-registry \
       --from-file=.dockerconfigjson=docker-config.json \
       --type=kubernetes.io/dockerconfigjson
     

2. Reference the secret you uploaded as an imagePullSecrets. There are two ways to do this:

   • Set an imagePullSecret on a per-Pod or per-Deployment basis.

     In the Deployment spec, provide the name of the imagePullSecrets. In the previous control panel-based example, the secret was named do-registry, so that name is also used here. If you used the doctl-based instructions, use registry-<my-registry> instead.

         
             
                 
           apiVersion: apps/v1
           kind: Deployment
           metadata:
             name: hello
             spec:
             replicas: 3
             template:
               metadata:
                 labels:
                   app: hello
                   spec:
                   containers:
                   - name: hello
                   image: registry.digitalocean.com/myregistry/myimage
                   imagePullSecrets:
                   - name: do-registry
                   
             
         
     

     For more information on configuring Pods to connect to private registries, consult the Kubernetes documentation.

   • Set an imagePullSecret as the default for all Pods and Deployments.

     You can modify the default service account to always use the secret as an imagePullSecret when creating Pods or Deployments.

     In the previous control panel-based example, the secret was named do-registry, so that name is also used here. If you used the doctl-based instructions, use registry-<my-registry> instead.

     kubectl patch serviceaccount default -p '{"imagePullSecrets": [{"name": "do-registry"}]}'
     

     From then on, any new Pods have this automatically added to their spec:

     spec:
         imagePullSecrets:
         - name: do-registry
     

     For more information on patching the default service account to use imagePullSecrets, consult the Kubernetes documentation.