Add operation doc for Docker Reg Mgmt

This operation guide describes Docker registry tasks to be completed on
controller nodes.

Patchset 3: Updates and additional content per feedback. Replaced
CLI descriptions with link to CLI ref (and update CLI ref with additional info)
Patchset 4: Fix typo and move general info link to overview.

Story: 2006881
Tasks: 37490, 37509, 37510

Includes reviewer comment and removes possible upstream urls.

Change-Id: I5d167adbd7c4141cd765e4dc5a962fbc45a2e13e
Signed-off-by: MCamp859 <maryx.camp@intel.com>
Signed-off-by: Kristal Dale <kristal.dale@intel.com>

doc/source/cli_ref/system.rst

@@ -76,6 +76,8 @@ for a variety of StarlingX use cases. For example:
 Local Docker registry management
 ********************************
 
+.. incl-cli-local-docker-reg-start:
+
 Local Docker registry management commands enable you to remove images and
 free disk resources consumed by the local Docker registry. This is required if
 the local Docker registry's file system (`docker-distribution`) becomes full.
@@ -83,15 +85,38 @@ the local Docker registry's file system (`docker-distribution`) becomes full.
 ``registry-garbage-collect``
     Run the registry garbage collector.
 
+    This frees up the space on the file system used by deleted images. In rare
+    cases, the system may trigger a `swact` in the small time window when
+    garbage-collect is running. This may cause the registry to get stuck in
+    read-only mode. If this occurs, run garbage-collect again to take the
+    registry out of read-only mode.
+
 ``registry-image-delete``
     Remove the specified Docker image from the local registry.
 
+    The image should be specified in the form :command:`name:tag`. This command
+    only removes the image from the local Docker registry. It does not free
+    space on the file system.
+
+    .. note::
+
+       Any stx-openstack images in a system with stx-openstack applied should
+       not be deleted. If space is needed, you can delete the older tags of
+       stx-openstack images, but do not delete the most recent one. Deleting
+       both the registry stx-openstack images and the one from the Docker
+       cache will prevent failed pods from recovering. If this happens,
+       manually download the deleted images from the same source as
+       application-apply and push it to the local registry under the same
+       name and tag.
+
 ``registry-image-list``
     List all images in local docker registry.
 
 ``registry-image-tags``
     List all tags for a Docker image from the local registry.
 
+.. incl-cli-local-docker-reg-end:
+
 *****************************************
 Host/controller file system configuration
 *****************************************

doc/source/operations/k8s_docker_reg_management.rst

@@ -2,15 +2,137 @@
 Kubernetes Docker Registry Management (Local)
 =============================================
 
-This is a stub page for the topic: Kubernetes Docker Registry Management (Local). You
-can help StarlingX by expanding the content.
-
-See the story for additional information about what is needed:
-`Add Kubernetes Docker Registry Management (Local) Guide <https://storyboard.openstack.org/#!/story/2006881>`_
-
-For information about contributing to the StarlingX documentation, see the
-:doc:`/contributor/doc_contribute_guide`.
+This guide describes how to use and manage the local Docker registry.
 
 .. contents::
    :local:
    :depth: 1
+
+--------
+Overview
+--------
+
+A local Docker registry is deployed by default on the controller/master nodes,
+as part of the StarlingX Kubernetes deployment. It can be accessed at
+`registry.local:9001`.
+
+StarlingX stores container images in the local Docker registry, which is also
+available for end users to store hosted application container images.
+
+For more information about Docker Registry, refer to the upstream
+`Docker Registry documentation <https://docs.docker.com/registry/>`_.
+
+----------------------------
+Configure custom certificate
+----------------------------
+
+By default, the local Docker registry uses a self-signed certificate. It is
+highly recommended to replace the self-signed certificate with a CA-signed
+certificate.
+
+Use the :command:`system certificate-install` command and the :command:`docker_registry`
+option to update the certificate used by all Docker registry communication, as
+shown below:
+
+::
+
+   $ system certificate-install -m/--mode docker_registry path_to_cert
+
+---------------------------------
+Authentication and authentication
+---------------------------------
+
+Authentication is enabled for the local Docker registry. When logging in, users
+are authenticated using platform keystone credentials.
+
+For example, if using the local Docker to log in, use the following command:
+
+::
+
+  docker login registry.local:9001 -u <keystoneUserName> -p <keystonePassword>
+
+The `admin` platform keystone user is authorized to perform all actions on all
+repositories. Any other platform keystone user can perform all actions but only
+on their own repositories.
+
+For example, the non-admin keystone user `testuser` can only push or pull images
+located under `registry.local:9001/testuser/...`.
+
+.. note::
+
+   A keystone user name must be all lowercase, because the Docker registry does
+   not allow repository names to use capital letters. For example, the following
+   repository is invalid: `registry.local:9001/TESTUSER/busybox:latest`.
+
+-------------------------------------------------------------
+Use local Docker registry images in Kubernetes container spec
+-------------------------------------------------------------
+
+When creating a pod spec or deployment spec that uses an image from the local
+Docker registry you must:
+
+* Use the full image name, including the registry.
+* Specify an imagePullSecret with your keystone credentials.
+
+This example procedure assumes that the `testuser/busybox:latest` container
+image has been pushed to the local Docker registry.
+
+Example procedure:
+
+#. Create a secret with platform keystone credentials for the local Docker registry:
+
+   ::
+
+     kubectl create secret docker-registry testuser-registry-secret \
+     --docker-server=registry.local:9001 --docker-username=testuser \
+     --docker-password=<testuserPassword> --docker-email=noreply@windriver.com
+
+#. Create a Kubernetes deployment YAML file using the busybox container image
+   stored in the local Docker registry. Note that `imagePullSecret` must be
+   specified in the YAML file, providing the secret created in the previous step.
+
+   ::
+
+     cat <<EOF > busybox.yaml apiVersion: apps/v1
+     kind: Deployment metadata:
+       name: busybox
+       namespace: default
+     spec:
+       progressDeadlineSeconds: 600
+       replicas: 1
+       selector:
+         matchLabels:
+           run: busybox
+       template:
+         metadata:
+           labels:
+             run: busybox
+         spec:
+           containers:
+           - args:
+             - sh
+             image: registry.local:9001/testuser/busybox:latest
+             imagePullPolicy: Always
+             name: busybox
+             stdin: true
+             tty: true
+           restartPolicy: Always
+           imagePullSecrets:
+           - name: testuser-registry-secret
+     EOF
+
+#. Apply the ``busybox.yaml`` manifest that will pull the image from the
+   authenticated local Docker registry using the keystone credentials in the
+   `imagePullSecret`.
+
+   ::
+
+     kubectl apply -f busybox.yaml
+
+----------------------------
+Free space in local registry
+----------------------------
+
+.. include:: /cli_ref/system.rst
+   :start-after: incl-cli-local-docker-reg-start:
+   :end-before: incl-cli-local-docker-reg-end: