Docker Registry

To be able to create and publish Docker images, we use a Docker Registry. If you want to change the default registry, you need to:

1. tell Jenkins X, which Docker registry host to use.
2. ensure env/parameters.yaml contains the required authentication parameters
3. ensure your secret store contains the necessary secret
4. ensure values.tmpl.yaml for your Kubernetes provider contains the correct DockerConfig configuration

The following sections provide more details around these steps.

Configure Docker registry

To change the default Docker registry, you need set the registry host in the registry property of your jx-requirements.yml file. In case you want to use Docker Hub, the configuration would look like this:

cluster:
  registry: docker.io

Ensure authentication parameters

Next, you have to check the file env/parameters.yaml in your checkout of the Boot repository. It needs to contain a docker configuration section, similar to this:

enableDocker: true
docker:
  email: <email>
  password: vault:<cluster-name>/docker:password
  url: <url>
  username: <username>

If you have been using the default registry your env/parameters.yaml might not contain a docker section at all. If so, add the required configuration and make sure to set enableDocker: true.

The password uses a special format which allows to reference secrets from your configured secret store. Injecting secrets into the parameters describes in more detail how secrets work in conjunction with env/parameters.yaml.

Update secret store

The next step is to make sure the password is stored in the secret store. Assuming you are using Vault as the secret store, you need to make sure the secret identified by the URI vault:<cluster-name>/docker:password exists. This can be achieved by running (you need the vault CLI installed for that):

eval $(jx get vault-config)
vault kv put /secret/<cluster-name>/docker password=<my-password>

You can find more information on how to interact with Vault secrets in the Manage your secrets section.

Update Kubernetes provider configuration

Finally, you need to make sure that the correct Docker authentication config.json gets generated and stored in the Kubernetes Secret jenkins-docker-cfg (within your development namespace). Ultimately, this secret is mounted into the Pod executing the docker push and is responsible for authenticating against the configured Docker registry.

kubectl delete secret jenkins-docker-cfg -n jx
kubectl create secret generic jenkins-docker-cfg -n jx --from-file=./config.json

With Jenkins X Boot, the jenkins-docker-cfg Secret is created in the Kubernetes provider-specific file values.tmpl.yaml. You can find this file in the kubeProviders subdirectory of your Boot configuration repository. The Docker specific configuration in values.tmpl.yaml for GKE looks like this:

jenkins-x-platform:
  PipelineSecrets:

{{- if eq .Parameters.enableDocker true }}
    DockerConfig: |-
      {
        "auths":{
          {{ .Parameters.docker.url | quote }}:
            {
              "auth": {{ printf "%s:%s" .Parameters.docker.username .Parameters.docker.password | b64enc | quote}},
              "email": {{ .Parameters.docker.email | quote}}
            }
        }
      }      
{{- else}}
    # lets enable GCR Docker builds
    DockerConfig: |-
      {
          "credHelpers": {
              "gcr.io": "gcr",
              "us.gcr.io": "gcr",
              "eu.gcr.io": "gcr",
              "asia.gcr.io": "gcr",
              "staging-k8s.gcr.io": "gcr"
          }
      }      
{{- end}}

You can see how the enableDocker parameter discussed in Ensure authentication parameters is used to switch between the different formats of config.json. You need to ensure that the enabled DockerConfig matches your requirements. If that is not the case adjust values.tmpl.yaml to match the format required by your registry.

The following sections describe some of the typical config.json formats used by various Docker registries.

Google Container Registry (GCR)

If you want to use GCR, you can create your config.json by running:

gcloud auth configure-docker

The above command will ask you to confirm writing a credHelpers section to your config.json in your home directory under .docker/config.json. It is sufficient to place the credHelpers section into a new config.json. The content should look similar to:

 {
  "credHelpers": {
    "gcr.io": "gcloud",
    "marketplace.gcr.io": "gcloud",
    "eu.gcr.io": "gcloud",
    "us.gcr.io": "gcloud",
    "staging-k8s.gcr.io": "gcloud",
    "asia.gcr.io": "gcloud"
  }
}

Elastic Container Registry (ECR)

For AWS and its Elastic Container Registry (ECR), the config.json looks like:

{
    "credsStore": "ecr-login"
}

Docker Hub

If you want to publish images to Docker Hub, then you need a config.json with and auth section containing your Docker Hub auth token. For example:

{
    "auths": {
        "https://index.docker.io/v1/": {
            "auth": "MyDockerHubToken"
        }
    }
}

Check .docker/config.json in your home directory to see whether it contains the required configuration.

If you don’t have a .docker/config.json, you can run:

docker login -u <username> -p <password>

On macOS you might find something like this:

"credsStore": "osxkeychain"

in .docker/config.json without an auths section. In this case, you can edit the credsStore line and set the value of this property to “”. Then run:

docker logout
docker login -u <username> -p <password>

jFrog BinTray (Artifactory)

It is also possible to use jFrog BinTray as a private registry. The content should look similar to:

{
    "auths": {
        "https://private-reg.bintray.io": {
            "auth": "username:password (base64 encoded)",
            "email": "myemail@acme.com"
        }
    }
}

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.