Accessing a Docker registry from your Kubernetes cluster

Allowing Kubernetes to pull Docker images from your registry

Kubernetes deployments are based on a “pull” approach. When you deploy your application to a Kubernetes cluster you don’t upload the application itself (which usually happens with traditional deployments). Instead, Kubernetes will pull the Docker images to its nodes on its own.

Kubernetes deployments

Kubernetes deployments

If your Docker images are in a public repository such as DockerHub, Kubernetes can pull them right away. In most cases however your images are in a private Docker registry and Kubernetes must be given explicit access to it.

This happens by using Docker registry secrets. This way each Kubernetes pod can pull Docker images directly when a deployment takes place.

Giving access to a Docker Registry via the GUI

Codefresh allows you to create easily pull secrets for your cluster. The first step is to define your Docker registry inside Codefresh. It is important to know that Codefresh can work with any compliant Docker registry either on the cloud or behing the firewall.

Once your Registry is connected to Codefresh, select Kubernetes from the left sidebar to view your Kubernetes Dashboard. Then click the Add Service Button.

At the screen that will appear select your cluster and your namespace at the top. Then at the bottom select the Image Pull secret dropdown.

Create Pull Secret

Create Pull Secret

This dropdown shows all the existing pull secrets for that namespace. You can select the Create Registry Pull secret Option to create a new one.

You will get a list of all the connected Docker registries in Codefresh. Select the one that you like and Codefresh will automatically create a secret for you.

The creation of the secret is instant and will happen as soon as you select your Docker registry from the drop down. There is no need to actually deploy anything from this screen for the changes to take effect.

Docker Registry Access

Docker Registry Access

From now on, this cluster on this namespace will be able to deploy Docker images from the selected Registry.

From this screen you don’t really need to finish the deployment in order to apply the secrets changes. Feel free to close the screen and go to another Codefresh page.

Note that Codefresh will automatically use the secret you defined in all deployments that are performed via the GUI (Codefresh is dynamically creating the correct manifests for you behind the scenes in that case). If you wish to use your own manifests, you need to include the secret yourself, as explained in the next section.

Giving access to a Docker Registry with kubectl

You can also use the kubectl command directly to give access to a Docker registry. This way is not specific to Codefresh so read the official kubernetes documentation.

Creating the Docker registry secret

The credentials depend upon the type or registry you use.

  • The Docker server to use is a domain such, etc
  • The username is your account username.
  • The password is a speficic docker registry password or any other kind of token. You need to check the documentation of your registry provider for the exact details.

Be sure to create the Secret in the namespace in which your application will run. Pull secrets are specific to a namespace. If you want to deploy to multiple namespaces you need to create a secret for each one of them.

This is an example of creating a pull secret to Azure registry. You can use the same command to any other private registry.


export DOCKER_USER=myregistryname
export DOCKER_PASSWORD=myregistrytoken

kubectl create secret docker-registry cfcr\

Using the Docker registry secret

To use the secret you just created, you need to either

There is nothing specific to Codefresh regarding the usage of Docker registry secrets, and therefore following the official Kubernetes documentation is the recommended approach.

Giving access to a Docker Registry via the Codefresh CLI

The Codefresh CLI can also create pull secrets in an automated manner.

See the Image pull Secret documentation.