Docker Image Management

If you have are planning to use a publicly accessible registry like Docker Hub (hub.docker.com), Quay (quay.io), GCR (gcr.io), K8S (k8s.gcr.io). You don't need to configure anything special. This document talks specifically about how to manage images in an air-gapped environment.

Two modes of operations

Platform9 Edge Stack can operate in one of the 2 modes of operation, each of these are useful in different situations.

  1. Using a private registry to host images for various components. This is useful when numerous clusters are designed to be managed by one single management plane and a registry is available along with management plane is always up. This may be the case with deploying IMS or Core.
  2. Using 'image-cached' images on each node: This option is useful in a small environment where registry may not be accessible or may be intermittently available.

For both these modes, Platform9 ships offline image bundles for all the Kubernetes and the associated addon images. For more details, see the reference on the artifacts page.

Private Registry

Platform9 Managed Kubernetes uses public docker registries to access images for various components like etcd, kubernetes-api server etc. In the Platform9 Edge Stack, PES.uses a local registry running as part of the Platform9 Edge Stack Management Plane (DU). This registry is only accessible through the Management DU or through the hosts connected to the Management Plane. This local registry can be used to host various images. In addition to using Platform9 DUs local registry, you can configure your docker registry to host various images, this section outlines how the two configurations can be accomplished.

Platform9 DU Local registry

Step 1: Configure registry on the DU

You can turn on and configure the local registry on the DU with the following options set in your airctl config file, typically in the user's home directory (~/airctl-config.yaml) or /opt/pf9/airctl/conf/airctl-config.yamlon the DU host.

YAML
Copy

Please make these configuration prior to starting the DU, while changes are possible post start, some configuration may need to restart some DU services.

Once this is set, please start and configure the DU using the following command.

Bash
Copy

This brings up a registry within the DU that's listening on localhost:5100 as well as configures the DU to create clusters pointing to this registry by default.

Step 2: Push images to the local registry

The registry does not host any images by default. We can push the offline image bundle to the registry by using the following command.

Bash
Copy

Step 3: Configure hosts

The configure hosts command will still copy the image tars over to the hosts to warm the local cache. You can skip this step by adding the following flag to the configure-hosts command.

This will be the default in the next release.
Bash
Copy

The hosts are configured to pull the container images from the DU using the tunnel created between the host and the DU.

Step 4: Create Cluster

At this point, you should be good to create clusters as usual. The nodes will be configured to pull container images from the local registry by default for all images required to stand the cluster up.

You will note the name of the images to be of the pattern, localhost:5001/<image-name>for example localhost:5001/calico-node:3.15

If you want to leverage the same registry, simply put the exported tar file in the /opt/pf9/airctl/imgs

Older existing clusters (≤5.2) do not work with the local registry: These changes only work for clusters created from versions ≥5.2.

Airctl-config.yaml registry options

The following configuration values determine the configuration for private registry.

  • privateRegistryType: This has the following possible values: DU, None, or custom.

    • du: Platform9 DU will host the registry, and all Platform9 components will be configured to use DU as the registry. Make sure to import the offline image bundle to the DU
    • none: (default value) used when either the public registries (docker, quay, gcr) are accessible or the user has decided to use the 'image-cache' option
    • custom: this option is an advanced option when the image registry is configured to be another private registry. This private registry value can be set in the privateRegistryBase

  • privateRegistryBase:Only used when the privateRegistryType is custom

See auto$ for a recipe on changing the registry configuration post DU start.

Image Cached Option

Image cache option is meant for "small" deployments where a registry may not be practical and Platform9 Managed DU and associated registry may be turned off for a longer duration. This option uses a simple technique and installs docker and pre-warms the docker cache on each node with the images. Platform9 components (and others) will use the pre-warm cache when the node comes up.

The following command\ is used to configure docker and cache. Remember to correctly configure the following configuration items

  • dockerRepo: The location of the offline bundle for docker installation example: /opt/pf9/airctl/docker-v-5.2.0-1549281.tar.gz
  • imagesDir: The location of the directory containing the offline image bundles: /opt/pf9/airctl/imgs
Bash
Copy

Backup and Restore of Local Registry

Images are immutable, and hence there is little to back up regularly. The offline image bundles are available as part of the installer and can always be applied again as described in the section above.

The following two commands are available as helper function for further backup or restore.

To Back Up

Bash
Copy

To Restore:

Bash
Copy
Type to search, ESC to discard
Type to search, ESC to discard
Type to search, ESC to discard
Next to read:
Airctl Reference

© 2023 Platform9. All Rights Reserved

On This Page
Docker Image ManagementTwo modes of operationsPrivate RegistryPlatform9 DU Local registryStep 1: Configure registry on the DUStep 2: Push images to the local registryStep 3: Configure hostsStep 4: Create ClusterImage Cached OptionBackup and Restore of Local RegistryTo Back UpTo Restore: