How to Use Your Private DigitalOcean Container Registry

DigitalOcean Kubernetes (DOKS) is a managed Kubernetes service that lets you deploy Kubernetes clusters without the complexities of handling the control plane and containerized infrastructure. Clusters are compatible with standard Kubernetes toolchains and integrate natively with DigitalOcean Load Balancers and block storage volumes.

Note
This feature is currently in Beta and is only available by invitation. For more information, see Product Release Lifecycle Stages. To request early access to the DigitalOcean Container Registry, see the Container Registry home page.

DigitalOcean provides each account with the ability to create one registry for storing container images. These registries are private, and co-located in the datacenters where DigitalOcean Kubernetes clusters are operated, ensuring secure, stable, and performant rollout of images to your clusters.

Your registry can have as many repositories as you wish, but it must be given a globally unique name that doesn't collide with other users.

Create a Registry

To create your registry, navigate to Images in the control panel and click on the Container Registry tab. Then, give your registry a name that is globally unique, and click Create Registry.

Screenshot showing registry creation
Note
The creation of a registry also creates a Space that will be given a UUID as a name. This Space will be visible in your control panel and is the mechanism that stores the container images themselves. This Space should not be touched. If the registry is deleted, the Space will be destroyed as well.

Configure Docker to Push to and Pull from the Registry

To interact with your registry using the docker command-line interface (CLI), you'll need to first configure docker using the DigitalOcean command-line tool, doctl. To install doctl, follow the installation instructions in the README for your operating system.

Note
doctl 1.34.0 or higher is required for access to doctl registry commands.

Then, call the following command:

doctl registry login

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

Note

Under the hood, this generates a DigitalOcean token that grants docker access to your account. This can be revoked at any time by navigating to API in the DigitalOcean control panel. If you're in an environment that doesn't have doctl or want to use an existing API token, you can simulate what doctl registry login does by using an API token string as the username and password when calling docker login. For example:

docker login -u ZDRhYzzzz -p ZDRhYzzzz registry.digitalocean.com

To push images to the registry, use the fully qualified registry name, registry.digitalocean.com:

docker tag myimage registry.digitalocean.com/myregistry/myimage
docker push registry.digitalocean.com/myregistry/myimage

Configure Your DigitalOcean Kubernetes cluster

To configure your DigitalOcean Kubernetes cluster to use your private registry, you will need to download a JSON file containing the proper credentials, then upload that file as a secret to your cluster.

Obtain Credentials from doctl

To download credentials using doctl, enter the following command, providing a name for the secret that will be uploaded to your cluster later. Here, we use the name do-registry:

doctl registry kubernetes-manifest --name do-registry > secret.yaml

Once you have the credentials on your machine, upload them to your cluster as a secret:

kubectl create -f secret.yaml

Obtain Credentials from the Control Panel

To download credentials from the control panel, navigate to Images and click on the Container Registry tab. Then, click Download Registry Config 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

Use Images from Your Registry in Your Cluster

From then on, you should be able to deploy any images you have stored on the registry by using the fully qualified registry name, registry.digitalocean.com, and referring to the secret you stored in the cluster using imagePullSecrets.

Setting an imagePullSecrets value for a Single Pod or Deployment

In the previous step, the secret was given the name do-registry, so that name is also specified here when telling a specific deployment to connect to your DigitalOcean registry.

  
    
apiVersion: extensions/v1beta1
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.

Setting imagePullSecrets as the Default for all Pods

You can modify the default service account to use imagePullSecrets, which eliminates the need to specify the secret for every Pod. Earlier, we named our secret do-registry, so that is used in the following examples:

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

From then on, any new Pods will 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.

Delete a Registry

To delete your registry, navigate to Images in the control panel and click on the Container Registry tab. Then, click the More link, and select Delete.

Screenshot showing registry deletion