e187ad7955
Adds a new flag, 'docker_registry_network_mode', which defaults to 'host'. This may be used to set the network mode of the Docker registry container. This is a follow up to I404dd52701426a10c2e92727bd52b7fd7112abf6, which changed the network mode from the default of bridge to host. It allows that change to be backported to stable branches, without modifying the default value. Change-Id: Ic8ec3bb98f8f016e1d089bf10bd0538264394241
139 lines
5.1 KiB
ReStructuredText
139 lines
5.1 KiB
ReStructuredText
.. _configuration-docker-registry:
|
|
|
|
===============
|
|
Docker registry
|
|
===============
|
|
|
|
This section covers configuration of the Docker registry that may be deployed,
|
|
by default on the seed host. Docker registry configuration is typically applied
|
|
in ``${KAYOBE_CONFIG_PATH}/docker-registry.yml``. Consult the `Docker registry
|
|
documentation <https://docs.docker.com/registry/>`__ for further details of
|
|
registry usage and configuration.
|
|
|
|
The registry is deployed during the ``kayobe seed host configure`` command.
|
|
|
|
Configuring the registry
|
|
========================
|
|
|
|
``docker_registry_enabled``
|
|
Whether a docker registry is enabled. Default is ``false``. When set to
|
|
``true``, the Docker registry is deployed on all hosts in the
|
|
``docker-registry`` group. By default this includes the seed host.
|
|
``docker_registry_env``
|
|
Dict of environment variables to provide to the docker registry container.
|
|
This allows to configure the registry by overriding specific configuration
|
|
options, as described at https://docs.docker.com/registry/configuration/
|
|
For example, the registry can be configured as a pull through cache to
|
|
Docker Hub by setting REGISTRY_PROXY_REMOTEURL to
|
|
"https://registry-1.docker.io". Note that it is not possible to push to a
|
|
registry configured as a pull through cache. Default is ``{}``.
|
|
``docker_registry_network_mode``
|
|
The network mode used for the docker registry container. Default is
|
|
``host``. When set to ``bridge``, port mapping is configured to expose the
|
|
registry through port ``docker_registry_port``.
|
|
``docker_registry_port``
|
|
The port on which the docker registry server should listen. Default is
|
|
4000. When ``docker_registry_network_mode`` is set to ``host``, configures
|
|
the port used by the registry server inside the container. When
|
|
``docker_registry_network_mode`` is set to ``bridge``, configures the
|
|
overlay network port.
|
|
``docker_registry_datadir_volume``
|
|
Name or path to use as the volume for the docker registry. Default is
|
|
``docker_registry``.
|
|
|
|
TLS
|
|
---
|
|
|
|
It is recommended to enable TLS for the registry.
|
|
|
|
``docker_registry_enable_tls``
|
|
Whether to enable TLS for the registry. Default is ``false``.
|
|
|
|
``docker_registry_cert_path``
|
|
Path to a TLS certificate to use when TLS is enabled. Default is none.
|
|
|
|
``docker_registry_key_path``
|
|
Path to a TLS key to use when TLS is enabled. Default is none.
|
|
|
|
For example, the certificate and key could be stored with the Kayobe
|
|
configuration, under ``${KAYOBE_CONFIG_PATH}/docker-registry/``. These files
|
|
may be encrypted via Ansible Vault.
|
|
|
|
.. code-block:: yaml
|
|
:caption: ``docker-registry.yml``
|
|
|
|
docker_registry_enable_tls: true
|
|
docker_registry_cert_path: "{{ kayobe_config_path }}/docker-registry/cert.pem
|
|
docker_registry_key_path: "{{ kayobe_config_path }}/docker-registry/key.pem
|
|
|
|
Basic authentication
|
|
--------------------
|
|
|
|
It is recommended to enable HTTP basic authentication for the registry. This
|
|
needs to be done in conjunction with enabling TLS for the registry: `using
|
|
basic authentication over unencrypted HTTP is not supported
|
|
<https://docs.docker.com/registry/deploying/#native-basic-auth>`__.
|
|
|
|
``docker_registry_enable_basic_auth``
|
|
Whether to enable basic authentication for the registry. Default is
|
|
``false``.
|
|
|
|
``docker_registry_basic_auth_htpasswd_path``
|
|
Path to a `htpasswd
|
|
<https://httpd.apache.org/docs/2.4/programs/htpasswd.html>`__ formatted
|
|
password store for the registry. Default is none.
|
|
|
|
The password store uses a ``htpasswd`` format. The following example shows how
|
|
to generate a password and add it to the ``kolla`` user in the password store.
|
|
The password store may be stored with the Kayobe configuration, under
|
|
``${KAYOBE_CONFIG_PATH}/docker-registry/``. The file may be encrypted via
|
|
Ansible Vault.
|
|
|
|
.. code-block:: console
|
|
|
|
uuidgen | tr -d '\n' > registry-password
|
|
cat registry-password | docker run --rm -i --entrypoint htpasswd httpd:latest -niB kolla > $KAYOBE_CONFIG_PATH/docker-registry/htpasswd
|
|
|
|
Next we configure Kayobe to enable basic authentication for the registry, and
|
|
specify the path to the password store.
|
|
|
|
.. code-block:: yaml
|
|
:caption: ``docker-registry.yml``
|
|
|
|
docker_registry_enable_basic_auth: true
|
|
docker_registry_basic_auth_htpasswd_path: "{{ kayobe_config_path }}/docker-registry/htpasswd"
|
|
|
|
Using the registry
|
|
==================
|
|
|
|
Enabling the registry does not automatically set the configuration for Docker
|
|
engine to use it. This should be done via the :ref:`docker_registry variable
|
|
<configuration-hosts-docker>`.
|
|
|
|
TLS
|
|
---
|
|
|
|
If the registry is using a privately signed TLS certificate, it is necessary to
|
|
:ref:`configure Docker engine with the CA certificate
|
|
<configuration-hosts-docker>`.
|
|
|
|
If TLS is enabled, Docker engine should be configured to use HTTPS to
|
|
communicate with it:
|
|
|
|
.. code-block:: yaml
|
|
:caption: ``kolla/globals.yml``
|
|
|
|
docker_registry_insecure: false
|
|
|
|
Basic authentication
|
|
--------------------
|
|
|
|
If basic authentication is enabled, Kolla Ansible needs to be configured with
|
|
the username and password.
|
|
|
|
.. code-block:: yaml
|
|
:caption: ``kolla.yml``
|
|
|
|
kolla_docker_registry_username: <registry username>
|
|
kolla_docker_registry_password: <registry password>
|