Chapter 2. Mirroring container images for disconnected installations You can use a custom container registry when you deploy MicroShift in a disconnected network. Running your cluster in a restricted network without direct internet connectivity is possible by installing the cluster from a mirrored set of container images in a private registry. 2.1. Mirror container images into an existing registry Using a custom air-gapped container registry, or mirror, is necessary with certain user environments and workload requirements. Mirroring allows for the transfer of container images and updates to air-gapped environments where they can be installed on a MicroShift instance. To create an air-gapped mirror registry for MicroShift containers, you must complete the following steps: Get the container image list to be mirrored. Configure the mirroring prerequisites. Download images on a host with internet access. Copy the downloaded image directory to an air-gapped site. Upload images to a mirror registry in an air-gapped site. Configure your MicroShift hosts to use the mirror registry. Additional resources Creating a mirror registry with mirror registry for Red Hat OpenShift 2.2. Getting the mirror registry container image list To use a mirror registry, you must know which container image references are used by a specific version of MicroShift. These references are provided in the release-<arch>.json files that are part of the microshift-release-info RPM package. Note To mirror the Operator Lifecycle Manager (OLM) in disconnected environments, add the references provided in the release-olm-USDARCH.json that is included in the microshift-olm RPM and follow the same procedure. Use oc-mirror for mirroring Operator catalogs and Operators. Prerequisites You have installed jq. Procedure Access the list of container image references by using one of the following methods: If the package is installed on the MicroShift host, get the location of the files by running the following command: USD rpm -ql microshift-release-info Example output /usr/share/microshift/release/release-x86_64.json If the package is not installed on a MicroShift host, download and unpack the RPM package without installing it by running the following command: USD rpm2cpio microshift-release-info*.noarch.rpm | cpio -idmv Example output /usr/share/microshift/release/release-x86_64.json Extract the list of container images into the microshift-container-refs.txt file by running the following commands: USD RELEASE_FILE=/usr/share/microshift/release/release-USD(uname -m).json USD jq -r '.images | .[]' USD{RELEASE_FILE} > microshift-container-refs.txt Note After the microshift-container-refs.txt file is created with the MicroShift container image list, you can append the file with other user-specific image references before running the mirroring procedure. 2.3. Configuring mirroring prerequisites You must create a container image registry credentials file that allows the mirroring of images from your internet-connected mirror host to your air-gapped mirror. Follow the instructions in the "Configuring credentials that allow images to be mirrored" link provided in the "Additional resources" section. These instructions guide you to create a ~/.pull-secret-mirror.json file on the mirror registry host that includes the user credentials for accessing the mirror. 2.3.1. Example mirror registry pull secret entry For example, the following section is added to the pull secret file for the microshift_quay:8443 mirror registry using microshift:microshift as username and password. Example mirror registry section for pull secret file "<microshift_quay:8443>": { 1 "auth": "<microshift_auth>", 2 "email": "<microshift_quay@example.com>" 3 }, 1 Replace the <registry_host>:<port> value microshift_quay:8443 with the host name and port of your mirror registry server. 2 Replace the <microshift_auth> value with the user password. 3 Replace the </microshift_quay@example.com> value with the user email. Additional resources Configuring credentials that allow images to be mirrored 2.4. Downloading container images After you have located the container list and completed the mirroring prerequisites, download the container images to a host with internet access. Prerequisites You are logged into a host with access to the internet. The .pull-secret-mirror.json file and microshift-containers directory contents are available locally. Procedure Install the skopeo tool used for copying the container images by running the following command: USD sudo dnf install -y skopeo Set the environment variable that points to the pull secret file: USD PULL_SECRET_FILE=~/.pull-secret-mirror.json Set the environment variable that points to the list of container images: USD IMAGE_LIST_FILE=~/microshift-container-refs.txt Set the environment variable that points to the destination directory for storing the downloaded data: USD IMAGE_LOCAL_DIR=~/microshift-containers Run the following script to download the container images to the USD{IMAGE_LOCAL_DIR} directory: while read -r src_img ; do # Remove the source registry prefix dst_img=USD(echo "USD{src_img}" | cut -d '/' -f 2-) # Run the image download command echo "Downloading 'USD{src_img}' to 'USD{IMAGE_LOCAL_DIR}'" mkdir -p "USD{IMAGE_LOCAL_DIR}/USD{dst_img}" skopeo copy --all --quiet \ --preserve-digests \ --authfile "USD{PULL_SECRET_FILE}" \ docker://"USD{src_img}" dir://"USD{IMAGE_LOCAL_DIR}/USD{dst_img}" done < "USD{IMAGE_LIST_FILE}" 2.5. Uploading container images to a mirror registry To use your container images at an air-gapped site, upload them to the mirror registry using the following procedure. Prerequisites You are logged into a host with access to microshift-quay . The .pull-secret-mirror.json file is available locally. The microshift-containers directory contents are available locally. Procedure Install the skopeo tool used for copying the container images by running the following command: USD sudo dnf install -y skopeo Set the environment variables pointing to the pull secret file: USD IMAGE_PULL_FILE=~/.pull-secret-mirror.json Set the environment variables pointing to the local container image directory: USD IMAGE_LOCAL_DIR=~/microshift-containers Set the environment variables pointing to the mirror registry URL for uploading the container images: USD TARGET_REGISTRY= <registry_host>:<port> 1 1 Replace <registry_host>:<port> with the host name and port of your mirror registry server. Run the following script to upload the container images to the USD{TARGET_REGISTRY} mirror registry: pushd "USD{IMAGE_LOCAL_DIR}" >/dev/null while read -r src_manifest ; do local src_img src_img=USD(dirname "USD{src_manifest}") # Add the target registry prefix and remove SHA local -r dst_img="USD{TARGET_REGISTRY}/USD{src_img}" local -r dst_img_no_tag="USD{TARGET_REGISTRY}/USD{src_img%%[@:]*}" # Run the image upload echo "Uploading 'USD{src_img}' to 'USD{dst_img}'" skopeo copy --all --quiet \ --preserve-digests \ --authfile "USD{IMAGE_PULL_FILE}" \ dir://"USD{IMAGE_LOCAL_DIR}/USD{src_img}" docker://"USD{dst_img}" done < <(find . -type f -name manifest.json -printf '%P\n') popd >/dev/null 2.6. Configuring hosts for mirror registry access To configure a MicroShift host to use a mirror registry, you must give the MicroShift host access to the registry by creating a configuration file that maps the Red Hat registry host names to the mirror. Prerequisites Your mirror host has access to the internet. The mirror host can access the mirror registry. You configured the mirror registry for use in your restricted network. You downloaded the pull secret and modified it to include authentication to your mirror repository. Procedure Log into your MicroShift host. Enable the SSL certificate trust on any host accessing the mirror registry by completing the following steps: Copy the rootCA.pem file from the mirror registry, for example, <registry_path>/quay-rootCA , to the MicroShift host at the /etc/pki/ca-trust/source/anchors directory. Enable the certificate in the system-wide trust store configuration by running the following command: USD sudo update-ca-trust Create the /etc/containers/registries.conf.d/999-microshift-mirror.conf configuration file that maps the Red Hat registry host names to the mirror registry: Example mirror configuration file [[registry]] prefix = "" location = "<registry_host>:<port>" 1 mirror-by-digest-only = true insecure = false [[registry]] prefix = "" location = "quay.io" mirror-by-digest-only = true [[registry.mirror]] location = "<registry_host>:<port>" insecure = false [[registry]] prefix = "" location = "registry.redhat.io" mirror-by-digest-only = true [[registry.mirror]] location = "<registry_host>:<port>" insecure = false [[registry]] prefix = "" location = "registry.access.redhat.com" mirror-by-digest-only = true [[registry.mirror]] location = "<registry_host>:<port>" insecure = false 1 Replace <registry_host>:<port> with the host name and port of your mirror registry server, for example, <microshift-quay:8443> . Enable the MicroShift service by running the following command: USD sudo systemctl enable microshift Reboot the host by running the following command: USD sudo reboot

Commands:
rpm -ql microshift-release-info
/usr/share/microshift/release/release-x86_64.json
rpm2cpio microshift-release-info*.noarch.rpm | cpio -idmv
/usr/share/microshift/release/release-x86_64.json
RELEASE_FILE=/usr/share/microshift/release/release-USD(uname -m).json
jq -r '.images | .[]' USD{RELEASE_FILE} > microshift-container-refs.txt
"<microshift_quay:8443>": { 1 "auth": "<microshift_auth>", 2 "email": "<microshift_quay@example.com>" 3 },
sudo dnf install -y skopeo
PULL_SECRET_FILE=~/.pull-secret-mirror.json
IMAGE_LIST_FILE=~/microshift-container-refs.txt
IMAGE_LOCAL_DIR=~/microshift-containers
while read -r src_img ; do # Remove the source registry prefix dst_img=USD(echo "USD{src_img}" | cut -d '/' -f 2-) # Run the image download command echo "Downloading 'USD{src_img}' to 'USD{IMAGE_LOCAL_DIR}'" mkdir -p "USD{IMAGE_LOCAL_DIR}/USD{dst_img}" skopeo copy --all --quiet --preserve-digests --authfile "USD{PULL_SECRET_FILE}" docker://"USD{src_img}" dir://"USD{IMAGE_LOCAL_DIR}/USD{dst_img}" done < "USD{IMAGE_LIST_FILE}"
sudo dnf install -y skopeo
IMAGE_PULL_FILE=~/.pull-secret-mirror.json
IMAGE_LOCAL_DIR=~/microshift-containers
TARGET_REGISTRY= <registry_host>:<port> 1
pushd "USD{IMAGE_LOCAL_DIR}" >/dev/null while read -r src_manifest ; do local src_img src_img=USD(dirname "USD{src_manifest}") # Add the target registry prefix and remove SHA local -r dst_img="USD{TARGET_REGISTRY}/USD{src_img}" local -r dst_img_no_tag="USD{TARGET_REGISTRY}/USD{src_img%%[@:]*}" # Run the image upload echo "Uploading 'USD{src_img}' to 'USD{dst_img}'" skopeo copy --all --quiet --preserve-digests --authfile "USD{IMAGE_PULL_FILE}" dir://"USD{IMAGE_LOCAL_DIR}/USD{src_img}" docker://"USD{dst_img}" done < <(find . -type f -name manifest.json -printf '%P\n') popd >/dev/null
sudo update-ca-trust
[[registry]] prefix = "" location = "<registry_host>:<port>" 1 mirror-by-digest-only = true insecure = false [[registry]] prefix = "" location = "quay.io" mirror-by-digest-only = true [[registry.mirror]] location = "<registry_host>:<port>" insecure = false [[registry]] prefix = "" location = "registry.redhat.io" mirror-by-digest-only = true [[registry.mirror]] location = "<registry_host>:<port>" insecure = false [[registry]] prefix = "" location = "registry.access.redhat.com" mirror-by-digest-only = true [[registry.mirror]] location = "<registry_host>:<port>" insecure = false
sudo systemctl enable microshift
sudo reboot