Using a Local Docker Registry on Air-Gapped Systems

Using a Local Docker Registry on Air-Gapped Systems

PMK clusters rely on various docker container images to stand up and run clusters. These images are typically hosted on public registries like:

• Docker Hub (hub.docker.com)
• Quay (quay.io)
• GCR (gcr.io)
• K8S (k8s.gcr.io)

In airgapped environments, these image registries are unreachable. To address this concern, we ship a pre-built tar image along with airctl. This tar file is copied over to the hosts as they are configured, and then the local docker cache is pre-warmed. While this works well in small environments, this scales poorly when provisioning numerous nodes. To address this issue, airctl 5.2≥ supports installing and managing a local registry, that clusters can point to and retrieve images from.

Using a Local Registry

Step 1: Configure registry on the DU

You can enable and configure this preference in the local registry by enabling the following option in your airctl config file located at /opt/pf9/airctl/conf/airctl-config.yaml on the DU host:

privateRegistryType: DU

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

airctl start

This brings up a registry within the DU that listens on localhost:5100, and configures the DU to create clusters pointing to this registry by default.

Step 2: Push Images to the Local Registry

By default, the registry does not host any images. We push images downloaded from an online repository to this registry using the following command:

airctl advanced-du push-images --img-tar <path-to-docker-img-tar> --config /opt/pf9/airctl/conf/airctl-config.yaml

Step 3: Configure hosts

By default, the configure hosts command will still copy the image tars over to the hosts to warm the local cache. Users can skip this step by adding the --skip-docker-img-import flag to the configure-hosts command.

airctl configure-hosts --skip-docker-img-import --config /opt/pf9/airctl/conf/airctl-config.yaml

The hosts are then 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 can create the cluster using the normal process. Now, by default, the nodes will be configured to pull container images from the local registry for all images required to stand the cluster up.

Upgrading a DU to Begin Using a Local Registry

Running the DU upgrade with the following fields set in /opt/pf9/airctl/conf/airctl-config.yaml will turn on and configure the local registry.

privateRegistryType

privateRegistryBase

Alternatively, you can also configure the DU to use the local registry after an upgrade. Set the fields as above and then run the following commands.

airctl advanced-du update-du --config /opt/pf9/airctl/conf/airctl-config.yaml

airctl advanced-du configure-du --config /opt/pf9/airctl/conf/airctl-config.yaml

Upgrading Clusters to Begin Using the Local Registry

Only clusters running kubernetes version 1.20 can run on local registries. By default, once the DU has been upgraded to version 5.3≥ with the privateRegistry flags enabled as noted above, the DU is configured to run all clusters in local registry mode. To begin using a local registry, upgrade the cluster to the latest Kubernetes v1.20 available on the DU. Once the upgrade to v1.20 is complete, the cluster will begin running in local registry mode.

Backup and Restore of Local Registry

The images stored in the registry will NOT be retained after an upgrade. The following commands will enable the backup and restore function of the registry image data. To backup, run this command.

airctl advanced-du backup-images --out registry-backup.tar.gz --config /opt/pf9/airctl/conf/airctl-config.yaml

To restore the registry image data, run this command.

airctl advanced-du restore-images --in registry-backup.tar.gz --config /opt/pf9/airctl/conf/airctl-config.yaml

Host Configuration

With the introduction of local registries, there are many new flags available to utilize with the airctl configure-hostscommand. This section below provides a detailed description of these options.

• --skip-docker-img-import: By default, the cache of docker images required to stand up the cluster are copied over to the hosts to pre-warm the local docker cache. This option skips that step; the host will now rely on the local registry to serve these images.
• --skip-docker-install: By default, airctl installs docker as a part of the host configuration. With this option set, airctl skips this step and expects the host to come with a version of docker already installed. Note: Passing this option also skips installation of the docker images.
• --skip-image-renaming: If the airctl-config.yaml file has the private registry option enabled, (i.e, has the privateRegistryType field set to anything but none), the host configuration step will automatically rename images to point to the local registry instead of its upstream versions. Enable this option to continue copying over upstream versions of the images to the hosts. Note: This option is meaningless if the --skip-docker-img-import option is passed.
• --skip-yum-repo-install: Implement this option to prevent airctl from installing the local yum repos for pf9-hostagent and other associated packages. Instead, the host is expected to select these packages up from an external yum repo.