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:
parent
f54d6f00c6
commit
ec62ca3cda
@ -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
|
||||
*****************************************
|
||||
|
@ -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:
|
||||
|
Loading…
Reference in New Issue
Block a user