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:
- tell Jenkins X, which Docker registry host to use.
- ensure
env/parameters.yaml
contains the required authentication parameters - ensure your secret store contains the necessary secret
- ensure
values.tmpl.yaml
for your Kubernetes provider contains the correct DockerConfig configuration
The following sections provide more details around these steps.
jx boot
locally or create a pull request.
For more information refer to Changing your installation in the Boot documentation.
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
.
enableDocker: true
and run jx boot
locally.
In this case, it will interactively ask for the required parameters again and persist them into env/parameters.yaml
and the underlying secret store.
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.
If you are running an old jx install
based cluster, changing your Docker registry credentials comes just down to changing the jenkins-docker-cfg
Secret.
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.