From ec62ca3cdabef4d0d24aaf0e3613ea6b29dab045 Mon Sep 17 00:00:00 2001 From: MCamp859 Date: Mon, 9 Dec 2019 15:25:59 -0500 Subject: [PATCH] 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 Signed-off-by: Kristal Dale --- doc/source/cli_ref/system.rst | 25 ++++ .../operations/k8s_docker_reg_management.rst | 140 ++++++++++++++++-- 2 files changed, 156 insertions(+), 9 deletions(-) diff --git a/doc/source/cli_ref/system.rst b/doc/source/cli_ref/system.rst index 307635740..bfdbbdd94 100644 --- a/doc/source/cli_ref/system.rst +++ b/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 ***************************************** diff --git a/doc/source/operations/k8s_docker_reg_management.rst b/doc/source/operations/k8s_docker_reg_management.rst index d62b0a7ed..14832dada 100644 --- a/doc/source/operations/k8s_docker_reg_management.rst +++ b/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 `_ - -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 \ No newline at end of file + :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 `_. + +---------------------------- +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 -p + +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= --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 < 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: