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>
This commit is contained in:
MCamp859 2019-12-09 15:25:59 -05:00 committed by Kristal Dale
parent f54d6f00c6
commit ec62ca3cda
2 changed files with 156 additions and 9 deletions

View File

@ -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
*****************************************

View File

@ -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
: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: