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

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 generates a personal access token that grants docker access to your team to authenticate push and pull commands. You can revoke this token at any time.

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 with docker login by using your registered email as the username (-u) and API token string as password (-p), as in docker login -u [email protected] -p example-api-token-string 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 The Registry with a 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 the Secret to All Cluster Namespaces (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.

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.

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

apiVersion: v1
kind: Secret
metadata:
  name: <use_your_registry_name>
  namespace: kube-system
  annotations:
    digitalocean.com/dosecret-identifier: <use_your_registry_name>
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <use_your_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: <use_your_registry_name>
  namespace: all namespaces other than kube-system
  labels:
    digitalocean.com/copy-identifier: <use_your_registry_name>
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <use_your_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, first 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. This example names the secret do-registry:

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

Finally, 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.