Merge "Document how to use private registry"

doc/source/admin/index.rst

@@ -15,3 +15,4 @@ the services.
   clear-containers
   keep-containers-alive
   security-groups
+  private_registry

doc/source/admin/private_registry.rst

@@ -0,0 +1,98 @@
+===========================================
+How to use private docker registry with Zun
+===========================================
+
+Zun by default pull container images from Docker Hub.
+However, it is possible to configure Zun to pull images from a
+private registry.
+
+This document provides an example to deploy and configure a
+docker registry for Zun. For a comprehensive guide about deploying
+a docker registry, see `here <https://docs.docker.com/registry/deploying/>`_
+
+Deploy Private Docker Registry
+==============================
+A straightforward approach to install a private docker registry is to
+deploy it as a Zun container::
+
+    $ openstack appcontainer create \
+        --restart always \
+        --expose-port 443 \
+        --name registry \
+        --environment REGISTRY_HTTP_ADDR=0.0.0.0:443 \
+        --environment REGISTRY_HTTP_TLS_CERTIFICATE=/domain.crt \
+        --environment REGISTRY_HTTP_TLS_KEY=/domain.key \
+        registry:2
+
+   .. note::
+
+     Depending on the configuration of your tenant network, you might need
+     to make sure the container is accessible from other tenants of your cloud.
+     For example, you might need to associate a floating IP to the container.
+
+In order to make your registry accessible to external hosts,
+you must use a TLS certificate (issued by a certificate issuer) or create
+self-signed certificates. This document shows you how to generate and use
+self-signed certificates::
+
+    $ mkdir -p certs
+    $ cat > certs/domain.conf <<EOF
+    [req]
+    distinguished_name = req_distinguished_name
+    req_extensions     = req_ext
+    prompt = no
+    [req_distinguished_name]
+    CN = zunregistry.com
+    [req_ext]
+    subjectAltName = IP:172.24.4.49
+    EOF
+    $ openssl req \
+        -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key \
+        -x509 -days 365 -out certs/domain.crt -config certs/domain.conf
+
+   .. note::
+
+     Replace ``zunregistry.com`` with the domain name of your registry.
+
+   .. note::
+
+     Replace ``172.24.4.49`` with the IP address of your registry.
+
+   .. note::
+
+     You need to make sure the domain name (i.e. ``zunregistry.com``)
+     will be resolved to the IP address (i.e. ``172.24.4.49``).
+     For example, you might need to edit ``/etc/hosts`` accordingly.
+
+Copy the certificates to registry::
+
+    $ openstack appcontainer cp certs/domain.key registry:/
+    $ openstack appcontainer cp certs/domain.crt registry:/
+
+Configure docker daemon to accept the certificates::
+
+    # mkdir -p /etc/docker/certs.d/zunregistry.com
+    # cp certs/domain.crt /etc/docker/certs.d/zunregistry.com/ca.crt
+
+   .. note::
+
+     Replace ``zunregistry.com`` with the domain name of your registry.
+
+   .. note::
+
+     Perform this steps in every compute nodes.
+
+Start the registry::
+
+    $ openstack appcontainer start registry
+
+Verify the registry is working::
+
+    $ docker pull ubuntu:16.04
+    $ docker tag ubuntu:16.04 zunregistry.com/my-ubuntu
+    $ docker push zunregistry.com/my-ubuntu
+    $ openstack appcontainer run --interactive zunregistry.com/my-ubuntu /bin/bash
+
+   .. note::
+
+     Replace ``zunregistry.com`` with the domain name of your registry.