docker registry #65

Description

Service for hosting docker images


Introduction

This charm provides 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 ~containers/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 ~containers/docker-registry
juju deploy ~containers/easyrsa

juju relate 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

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
relating to a proxy provider, such as haproxy:

juju deploy ~containers/docker-registry
juju deploy haproxy

juju relate haproxy docker-registry
juju expose haproxy

Nagios Monitoring

This charm supports monitoring with nagios:

juju deploy ~containers/docker-registry
juju deploy nrpe --series bionic

juju relate docker-registry nrpe

Kubernetes Integration

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

Actions

Hosting 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.

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

Configuration

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'

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 swift config options are set, they must all be set.

Contact

The docker-registry charm is free and open source software created by the
containers team at Canonical.

Configuration

storage-swift-username
(string) The username to use to access swift.
storage-swift-authurl
(string) The URL of the keystone used to authenticate to swift.
tls-cert-path
(string) Path to the TLS certificate.
/etc/docker/registry/registry.crt
install_from_upstream
(boolean) Toggle installation from ubuntu archive vs the docker PPA (DEPRECATED; please use docker_runtime instead)
http_proxy
(string) URL to use for HTTP_PROXY to be used by Docker. Useful in egress-filtered environments where a proxy is the only option for accessing the registry to pull images.
registry-name
(string) Name of the registry container.
registry
auth-token-issuer
(string) The name on the certificate that authentication tokens must me signed by.
docker-opts
(string) Extra options to pass to the docker daemon. e.g. --insecure-registry
install_keys
(string) List of signing keys for install_sources package sources, per charmhelpers standard format (a yaml list of strings encoded as a string). The keys should be the full ASCII armoured GPG public keys. While GPG key ids are also supported and looked up on a keyserver, operators should be aware that this mechanism is insecure. null can be used if a standard package signing key is used that will already be installed on the machine, and for PPA sources where the package signing key is securely retrieved from Launchpad.
registry-image
(string) Registry image.
registry:2
storage-swift-tenant
(string) The tenant containing the swift service.
no_proxy
(string) Comma-separated list of destinations (either domain names or IP addresses) which should be accessed directly, rather than through the proxy defined in http_proxy or https_proxy. Must be less than 2023 characters long.
auth-basic-password
(string) Password for basic (htpasswd) authentication. Set this to something other than an empty string to configure basic auth for the registry.
tls-key-blob
(string) Base64 encoded TLS certificate private key (overwrites tls-key-path file).
https_proxy
(string) URL to use for HTTPS_PROXY to be used by Docker. Useful in egress-filtered environments where a proxy is the only option for accessing the registry to pull images.
tls-key-path
(string) Path the the TLS certificate private key.
/etc/docker/registry/registry.key
storage-read-only
(boolean) Controls the storage maintenance option "readonly".
enable-cgroups
(boolean) Enable GRUB cgroup overrides cgroup_enable=memory swapaccount=1. WARNING changing this option will reboot the host - use with caution on production services
registry-port
(int) The external port on which the docker registry listens.
5000
apt-key-server
(string) APT Key Server
hkp://keyserver.ubuntu.com:80
nagios_servicegroups
(string) A comma-separated list of nagios servicegroups. If left empty, the nagios_context will be used as the servicegroup
http-host
(string) The external URL where the docker registry is hosted. This URL will be prepended to all locations generated by the docker registry to ensure that those URLs are reachable by the client. For example "https://example.com/docker-registry/". Any path component must include a trailing "/". If this is not configured then the docker registry will derive its location from the incoming requests.
auth-token-realm
(string) The location from which clients should fetch authentication tokens.
storage-swift-password
(string) The password to use to access swift.
package_status
(string) The status of service-affecting packages will be set to this value in the dpkg database. Valid values are "install" and "hold".
install
auth-basic-user
(string) Username for basic (htpasswd) authentication.
admin
storage-swift-region
(string) The region containing the swift service.
storage-swift-container
(string) The name of the swift container that will hold the images.
docker-registry
docker-ce-package
(string) The pinned version of docker-ce package installed with nvidia-docker.
docker-ce
tls-ca-blob
(string) Base64 encoded TLS CA certificate (overwrites tls-cert-path file).
cuda_repo
(string) The cuda-repo package version to install.
10.0.130-1
nagios_context
(string) Used by the nrpe subordinate charms. A string that will be prepended to instance name to set the host name in nagios. So for instance the hostname would be something like: juju-myservice-0 If you're running multiple environments with the same services in them this allows you to differentiate between them.
juju
log-level
(string) Logging output level ('error', 'warn', 'info', or 'debug').
info
tls-cert-blob
(string) Base64 encoded TLS certificate (overwrites tls-cert-path file).
auth-token-root-certs
(string) The root certificate bundle (base64 encoded) for the authentication tokens.
docker_runtime
(string) docker runtime to install valid values are "upstream" (docker PPA), "nvidia" (nvidia PPA), "apt" (ubuntu archive), or "auto" (nvidia PPA or ubuntu archive, based on your hardware)
auto
extra_packages
(string) Space separated list of extra deb packages to install.
nvidia-docker-package
(string) The pinned version of nvidia-docker2 package.
nvidia-docker2
auth-token-service
(string) The name of the server which authentication tokens will be addressed to.
tls-ca-path
(string) Path to the TLS CA certificate.
/etc/docker/registry/ca.crt
install_sources
(string) List of extra apt sources, per charm-helpers standard format (a yaml list of strings encoded as a string). Each source may be either a line that can be added directly to sources.list(5), or in the form ppa:<user>/<ppa-name> for adding Personal Package Archives, or a distribution component to enable.
nvidia-container-runtime-package
(string) The pinned version of nvidia-container-runtime package.
nvidia-container-runtime