Kubernetes Docker Registry Management (Local)

This guide describes how to use and manage the local Docker registry.

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 system certificate-install command and the 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:

1. 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
   

2. 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
   

3. 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

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.

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.

Note

The registry-garbage-collect command executes background tasks that may affect access to the docker registry. It is recommended to wait a few minutes before executing other registry related commands.

registry-image-delete

Remove the specified Docker image from the local registry.

The image should be specified in the form 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.