Docker Registry

  • By Canonical Kubernetes
Channel Revision Published Runs on
latest/stable 78 21 Apr 2024
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
latest/stable 45 17 Apr 2024
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
latest/stable 6 17 Apr 2024
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
latest/candidate 78 21 Apr 2024
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
latest/candidate 45 25 Feb 2023
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
latest/candidate 24 01 Aug 2022
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
latest/candidate 6 11 Mar 2022
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
latest/beta 79 21 Apr 2024
Ubuntu jammy Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
latest/beta 38 21 Apr 2024
Ubuntu jammy Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
latest/beta 17 17 Apr 2024
Ubuntu jammy Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
latest/edge 81 01 May 2024
Ubuntu jammy Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
latest/edge 38 07 Dec 2022
Ubuntu jammy Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
latest/edge 20 14 Jul 2022
Ubuntu jammy Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
latest/edge 17 14 Jul 2022
Ubuntu jammy Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.30/beta 79 21 Apr 2024
Ubuntu jammy Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.30/beta 38 19 Apr 2024
Ubuntu jammy Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.30/beta 17 19 Apr 2024
Ubuntu jammy Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.30/edge 81 01 May 2024
Ubuntu jammy Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.30/edge 38 13 Mar 2024
Ubuntu jammy Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.30/edge 17 13 Mar 2024
Ubuntu jammy Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.29/stable 78 21 Apr 2024
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.29/stable 45 17 Apr 2024
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.29/stable 6 17 Apr 2024
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.29/candidate 78 21 Apr 2024
Ubuntu 22.04 Ubuntu 20.04
1.29/beta 77 17 Apr 2024
Ubuntu jammy Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.29/beta 38 17 Apr 2024
Ubuntu jammy Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.29/beta 17 17 Apr 2024
Ubuntu jammy Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.29/edge 70 01 Nov 2023
Ubuntu 22.04 Ubuntu 20.04
1.28/stable 61 22 Aug 2023
Ubuntu 22.04 Ubuntu 20.04
1.28/candidate 55 07 Jun 2023
Ubuntu 22.04 Ubuntu 20.04
1.28/beta 61 07 Aug 2023
Ubuntu 22.04 Ubuntu 20.04
1.28/edge 62 09 Aug 2023
Ubuntu 22.04 Ubuntu 20.04
1.27/stable 55 12 Jun 2023
Ubuntu 22.04 Ubuntu 20.04
1.27/candidate 55 12 Jun 2023
Ubuntu 22.04 Ubuntu 20.04
1.27/beta 51 10 Apr 2023
Ubuntu 22.04 Ubuntu 20.04
1.27/edge 52 10 Apr 2023
Ubuntu 22.04 Ubuntu 20.04
1.26/stable 45 27 Feb 2023
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04
1.26/candidate 45 25 Feb 2023
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04
1.26/beta 39 09 Apr 2023
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04
1.26/beta 42 09 Dec 2022
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04
1.26/edge 39 07 Dec 2022
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04
1.26/edge 38 07 Dec 2022
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04
1.25/stable 36 30 Sep 2022
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04
1.25/candidate 36 28 Sep 2022
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04
1.25/beta 37 01 Dec 2022
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04
1.25/edge 32 09 Sep 2022
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04
1.24/stable 24 04 Aug 2022
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.24/stable 11 05 May 2022
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.24/candidate 24 01 Aug 2022
Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.24/beta 11 21 Apr 2022
Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.24/edge 23 30 Jul 2022
Ubuntu jammy Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.24/edge 20 14 Jul 2022
Ubuntu jammy Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.24/edge 17 14 Jul 2022
Ubuntu jammy Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.23/beta 7 22 Mar 2022
Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
1.23/edge 5 24 Feb 2022
Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
juju deploy docker-registry
Show information

Platform:

Ubuntu
jammy 22.04 20.04 18.04 16.04

This charm provides a registry for storage and distribution of docker images. See https://docs.docker.com/registry/ for details.

Deployment

The registry is deployed as a stand alone application and supports integration with clients that implement the docker-registry interface.

Standalone Registry

For testing purposes, a simple, insecure registry can be deployed with:

juju deploy docker-registry

Secure Registry with TLS

This charm supports TLS via the tls-certificates relation. This can be enabled by deploying and relating to a TLS provider, such as easyrsa:

juju deploy docker-registry
juju deploy easyrsa

juju add-relation easyrsa docker-registry

This charm also supports configuration-based TLS, which does not require a relation to a TLS provider. Instead, transfer required files and configure this charm as follows:

juju scp /my/local/ca.pem docker-registry/0:/home/ubuntu/ca.pem
juju scp /my/local/cert.crt docker-registry/0:/home/ubuntu/cert.crt
juju scp /my/local/cert.key docker-registry/0:/home/ubuntu/cert.key

juju config docker-registry \
  tls-ca-path=/home/ubuntu/ca.pem \
  tls-cert-path=/home/ubuntu/cert.crt \
  tls-key-path=/home/ubuntu/cert.key

Finally, custom TLS data may be provided as base64-encoded config options to the charm. The configured tls-*-blob data will be written to corresponding configured tls-*-path files:

juju config docker-registry \
  tls-ca-blob=$(base64 /path/to/ca) \
  tls-cert-blob=$(base64 /path/to/cert) \
  tls-key-blob=$(base64 /path/to/key)

Proxied Registry

This charm supports an http proxy relation that allows operators to control how the registry is exposed on the network. This is achieved by deploying and relating to a proxy provider, such as haproxy:

juju deploy docker-registry
juju deploy haproxy

juju add-relation haproxy docker-registry

When multiple docker-registry units are deployed, the proxy will be configured with one unit chosen as the primary proxied service with remaining units configured as backups. This provides a highly available deployment that will fail over to a backup if the primary service becomes unavailable.

Note: HA deployments require the proxy to be in active-passive peering mode, which is the default for haproxy.

TLS/SSL

TLS is supported between haproxy and docker-registry, though some manual configuration is required. You will need to transfer the registry CA certificate to the proxy so the registry certificate can be verified. The path to the CA must match on both registry and proxy units. For example:

juju run --unit haproxy/$UNIT_NUM 'mkdir -p /etc/docker/registry'
juju run --unit haproxy/$UNIT_NUM 'chown ubuntu:ubuntu /etc/docker/registry'
juju scp docker-registry/$UNIT_NUM:/etc/docker/registry/ca.crt ./ca.crt
juju scp ./ca.crt haproxy/$UNIT_NUM:/etc/docker/registry

Nagios Monitoring

This charm supports monitoring with nagios:

juju deploy docker-registry
juju deploy nrpe --series bionic

juju relate docker-registry nrpe

Kubernetes Integration

See the Private Docker Registry documentation for details on integrating this charm with Kubernetes.

Actions

Adding Images

To make an image available in the deployed registry, it must be tagged and pushed. This charm provides the push action to do this:

juju run-action --wait docker-registry/0 push \
  image=<image> pull=<True|False> tag=<optional-tag-name>

This action will always tag and push a local image to the registry. By specifying pull=True (the default), the action will first pull the given image and subsequently tag/push it.

The default image tag is ‘net_loc/name:version’, where ‘net_loc’ is the http-host config option or http[s]://[private-ip]:[port] if config is not set. The image tag can be overriden by specifying the tag action parameter.

Listing Images

List images known to the registry with the images action:

juju run-action --wait docker-registry/0 images \
  options=<extra-args> repository=<repository[:tag]>

This runs docker images on the registry machine. The optional options and repository parameters are passed through to the underlying command. For example, show non-truncated output with numeric image IDs:

juju run-action --wait docker-registry/0 images \
  options="--no-trunc --quiet"

Removing Images

Remove images from the registry with the rmi action:

juju run-action --wait docker-registry/0 rmi \
  options=<extra-args> image=<image [image...]>

This runs docker rmi on the registry machine. The image name (or space separated names) must be specified using the image parameter. The optional options parameter is passed through to the underlying command. For example, remove the ubuntu:18.04 image without deleting untagged parents:

juju run-action --wait docker-registry/0 rmi \
  options="--no-prune" image="ubuntu:18.04"

Starting/Stopping

The registry is configured to start automatically with the dockerd system service. It can also be started or stopped with charm actions as follows:

juju run-action --wait docker-registry/0 stop
juju run-action --wait docker-registry/0 start

Authentication

This charm supports basic (htpasswd) as well as token-based authentication. Configure either method as follows:

juju config docker-registry \
  auth-basic-user='admin' \
  auth-basic-password='redrum'

juju config docker-registry \
  auth-token-issuer='auth.example.com' \
  auth-token-realm='myorg' \
  auth-token-root-certs='$(base64 /path/to/file)' \
  auth-token-service='myapp'

Delete by digest

The recommended way to delete images from the registry is to use the rmi action. If necessary, this charm can be configured to allow deletion of blobs and manifests by digest by setting the storage-delete config option to true:

juju config docker-registry storage-delete=true

Read-Only Mode

The registry can be switched to read-only mode by setting the storage-read-only config option to true:

juju config docker-registry storage-read-only=true

This may be useful when performing maintenance or deploying an environment with complex authentication requirements.

As an example, consider a scenario that requires unauthenticated pull and authenticated push access to the registry. This can be achieved by deploying this charm twice with the same storage backend (for example, a Swift object storage cluster):

juju deploy docker-registry public --config <storage-swift-opts>
juju deploy docker-registry private --config <storage-swift-opts>

Configure the unauthenticated public registry to be read-only, and enable authentication for the private registry:

juju config public storage-read-only=true
juju config private <auth-opts>

With a common storage backend and appropriate configuration, unauthenticated public users have a read-only view of the images pushed by authenticated private users.

Swift Storage

The charm supports Swift configuration options that can be used to store images in a Swift backend:

juju config docker-registry \
  storage-swift-authurl=<url> \
  storage-swift-container=<container> \
  storage-swift-password=<pass> \
  storage-swift-region=<region> \
  storage-swift-tenant=<tenant> \
  storage-swift-username=<user>

Note: If any of the above config options are set, then they must all be set. Optional params are noted below.

It is possible to configure the swift backend with an OpenStack domain name for Identity v3. To enable this, set the following optional config parameter:

storage-swift-domain=<val>

Also note that if the swift container is empty, requests to the registry may return 503 errors like the following:

{"errors":[{"code":"UNAVAILABLE","message":"service unavailable","detail":"health check failed: please see /debug/health"}]}

Per https://github.com/docker/distribution/issues/2292, upload an empty file called “files” at the root of the container to workaround the issue.

For the swift driver configuration see here for more details.