Clean up docs around local registry

* Remove duplicated info between the 'image-building' and 'multinode'
  guides regarding deploying a local insecure registry.

* Add a helper script to easily start a local registry in a consistent
  way.

* Remove warnings around bugs in older registries, 2.3+ is now the
  default

* Remove references to running the local registry on port 4000, this
  causes confusion as Docker expects port 5000 by default unless
  specified, and registries are not required for all-in-one deployments
  anyhow.

TrivialFix

Change-Id: I89f231df09102e3f1d5f21c8a8ca938ea60ae95b

5 files changed, 24 insertions, 86 deletions

diff --git a/doc/image-building.rst b/doc/image-building.rst
index 8794b120f..a42e7dfad 100644
--- a/doc/image-building.rst
+++ b/doc/image-building.rst
@@ -55,10 +55,6 @@ There are following distros available for building images:
    Fedora images are deprecated since Newton and will be removed
    in the future.
 
-To push the image after building, add ``--push``::
-
-    kolla-build --push
-
 It is possible to build only a subset of images by specifying them on the
 command line::
 
@@ -77,12 +73,10 @@ repository named ``mykollarepo``::
 
     kolla-build -n mykollarepo --push
 
-To push images to a local registry, use ``--registry`` flag::
-
-    kolla-build --registry 172.22.2.81:4000 --push
+To push images to a :ref:`local registry<deploy_a_registry>`, use
+``--registry`` flag::
 
-To trigger the build script to pull images from a local registry, the Docker
-configuration needs to be modified. See `Docker Insecure Registry Config`_.
+    kolla-build --registry 172.22.2.81:5000 --push
 
 The build configuration can be customized using a config file, the default
 location being one of ``/etc/kolla/kolla-build.conf`` or
@@ -342,59 +336,14 @@ Known issues
    will automatically attempt three retries of a build operation if the first
    one fails. The retry count is modified with the ``--retries`` option.
 
-Docker Local Registry
-=====================
-
-It is recommended to set up local registry for Kolla developers or deploying
-*multinode*. The reason using a local registry is deployment performance will
-operate at local network speeds, typically gigabit networking. Beyond
-performance considerations, the Operator would have full control over images
-that are deployed. If there is no local registry, nodes pull images from Docker
-Hub when images are not found in local caches.
-
-Setting up Docker Local Registry
---------------------------------
-
-Running Docker registry is easy. Just use the following command::
-
-   docker run -d -p 4000:5000 --restart=always --name registry \
-   -v <local_data_path>:/var/lib/registry registry
-
-.. note:: ``<local_data_path>`` points to the folder where Docker registry
-          will store Docker images on the local host.
-
-The default port of Docker registry is 5000. But the 5000 port is also the port
-of keystone-api. To avoid conflict, use 4000 port as Docker registry port.
-
-Now the Docker registry service is running.
-
-Docker Insecure Registry Config
--------------------------------
-
-For docker to pull images, it is necessary to modify the Docker configuration.
-The guide assumes that the IP of the machine running Docker registry is
-172.22.2.81.
-
-In Ubuntu, add ``--insecure-registry 172.22.2.81:4000``
-to ``DOCKER_OPTS`` in ``/etc/default/docker``.
-
-In CentOS, uncomment ``INSECURE_REGISTRY`` and set ``INSECURE_REGISTRY``
-to ``--insecure-registry 172.22.2.81:4000`` in ``/etc/sysconfig/docker``.
-
-And restart the docker service.
-
-To build and push images to local registry, use the following command::
-
-    kolla-build --registry 172.22.2.81:4000 --push
-
 Kolla-ansible with Local Registry
 ---------------------------------
 
-To make kolla-ansible pull images from local registry, set
-``"docker_registry"`` to ``"172.22.2.81:4000"`` in
+To make kolla-ansible pull images from a local registry, set
+``"docker_registry"`` to ``"172.22.2.81:5000"`` in
 ``"/etc/kolla/globals.yml"``. Make sure Docker is allowed to pull images from
-insecure registry. See `Docker Insecure Registry Config`_.
-
+insecure registry. See
+:ref:`Docker Insecure Registry Config <deploy_a_registry>`.
 
 Building behind a proxy
 -----------------------
diff --git a/doc/multinode.rst b/doc/multinode.rst
index 46de3f252..98c8fa48f 100644
--- a/doc/multinode.rst
+++ b/doc/multinode.rst
@@ -4,28 +4,21 @@
 Multinode Deployment of Kolla
 =============================
 
+.. _deploy_a_registry:
+
 Deploy a registry (required for multinode)
 ==========================================
 
 A Docker registry is a locally hosted registry that replaces the need to pull
-from the Docker Hub to get images. Kolla can function with or without a local
-registry, however for a multinode deployment a registry is required.
-
-The Docker registry prior to version 2.3 has extremely bad performance because
-all container data is pushed for every image rather than taking advantage of
-Docker layering to optimize push operations. For more information reference
-`pokey registry <https://github.com/docker/docker/issues/14018>`__.
-
+from the Docker Hub to get images. A local registry is required for a multinode
+Kolla deployment.
 
 The Kolla community recommends using registry 2.3 or later. To deploy registry
 with version greater than 2.3, do the following:
 
 ::
 
-    docker run -d -p 4000:5000 --restart=always --name registry registry:2
-
-.. note:: Kolla looks for the Docker registry to use port 4000. (Docker default is
-          port 5000)
+    tools/start-registry
 
 After starting the registry, it is necessary to instruct Docker that it will
 be communicating with an insecure registry. To enable insecure registry
@@ -36,7 +29,7 @@ registry is currently running:
 ::
 
     # CentOS
-    INSECURE_REGISTRY="--insecure-registry 192.168.1.100:4000"
+    INSECURE_REGISTRY="--insecure-registry 192.168.1.100:5000"
 
 For Ubuntu, check whether its using upstart or systemd.
 
@@ -50,7 +43,7 @@ Edit ``/etc/default/docker`` and add:
 ::
 
     # Ubuntu
-    DOCKER_OPTS="--insecure-registry 192.168.1.100:4000"
+    DOCKER_OPTS="--insecure-registry 192.168.1.100:5000"
 
 If Ubuntu is using systemd, additional settings needs to be configured.
 Copy docker's systemd unit file to ``/etc/systemd/system/`` directory:
diff --git a/doc/quickstart.rst b/doc/quickstart.rst
index 569dd3802..e349eaca1 100644
--- a/doc/quickstart.rst
+++ b/doc/quickstart.rst
@@ -383,7 +383,7 @@ Local Registry
 A local registry is not required for an ``all-in-one`` installation. Check out
 the :doc:`multinode` for more information on using a local registry. Otherwise,
 the `Docker Hub Image Registry`_ contains all images from each of Kolla's major
-releases. The latest release tag is 2.0.0 for Mitaka.
+releases. The latest release tag is 3.0.0 for Newton.
 
 Additional Environments
 =======================
@@ -420,12 +420,6 @@ behavior, please use the following parameters with ``kolla-build``:
 --base [ubuntu|centos|fedora|oraclelinux]
 --type [binary|source]
 
-If pushing to a local registry (recommended) use the flags:
-
-::
-
-    kolla-build --registry registry_ip_address:registry_ip_port --push
-
 Note ``--base`` and ``--type`` can be added to the above ``kolla-build``
 command if different distributions or types are desired.
 
@@ -508,13 +502,6 @@ veth pair is listed here and the other end is in a bridge on the system. ::
 
     neutron_external_interface: "eth1"
 
-If using a local docker registry, set the ``docker_registry`` information where
-the local registry is operating on IP address 192.168.1.100 and the port 4000.
-
-::
-
-    docker_registry: "192.168.1.100:4000"
-
 For *all-in-one* deploys, the following commands can be run. These will
 setup all of the containers on the localhost. These commands will be
 wrapped in the kolla-script in the future.
diff --git a/setup.cfg b/setup.cfg
index 3203f44bd..f0deb075b 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -29,6 +29,7 @@ data_files =
     share/kolla/tools = tools/cleanup-containers
     share/kolla/tools = tools/cleanup-host
     share/kolla/tools = tools/cleanup-images
+    share/kolla/tools = tools/start-registry
     share/kolla/doc = doc/*
     share/kolla/etc_examples = etc/*
     share/kolla = tools/init-runonce
diff --git a/tools/start-registry b/tools/start-registry
new file mode 100755
index 000000000..7c29e13a1
--- /dev/null
+++ b/tools/start-registry
@@ -0,0 +1,8 @@
+#!/bin/bash
+
+docker run -d \
+    --name registry \
+    --restart=always \
+    -p 5000:5000 \
+    -v registry:/var/lib/registry \
+    registry:2