Chapter 2. Mirroring container images for disconnected installations

Procedure

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

     $ 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:

     $ rpm2cpio microshift-release-info*.noarch.rpm | cpio -idmv

     Example output

     /usr/share/microshift/release/release-x86_64.json

2. Extract the list of container images into the microshift-container-refs.txt file by running the following commands:

   $ RELEASE_FILE=/usr/share/microshift/release/release-$(uname -m).json

   $ jq -r '.images | .[]' ${RELEASE_FILE} > microshift-container-refs.txt

Procedure

1. Install the skopeo tool used for copying the container images by running the following command:

   $ sudo dnf install -y skopeo

2. Set the environment variable that points to the pull secret file:

   $ PULL_SECRET_FILE=~/.pull-secret-mirror.json

3. Set the environment variable that points to the list of container images:

   $ IMAGE_LIST_FILE=~/microshift-container-refs.txt

4. Set the environment variable that points to the destination directory for storing the downloaded data:

   $ IMAGE_LOCAL_DIR=~/microshift-containers

5. Run the following script to download the container images to the ${IMAGE_LOCAL_DIR} directory:

   while read -r src_img ; do
      # Remove the source registry prefix
      dst_img=$(echo "${src_img}" | cut -d '/' -f 2-)
   
      # Run the image download command
      echo "Downloading '${src_img}' to '${IMAGE_LOCAL_DIR}'"
      mkdir -p "${IMAGE_LOCAL_DIR}/${dst_img}"
      skopeo copy --all --quiet \
         --preserve-digests \
         --authfile "${PULL_SECRET_FILE}" \
         docker://"${src_img}" dir://"${IMAGE_LOCAL_DIR}/${dst_img}"
   
   done < "${IMAGE_LIST_FILE}"

6. Transfer the image set to the target environment, such as air-gapped site. Then you can upload the image set into the mirror registry.

Procedure

1. Install the skopeo tool used for copying the container images by running the following command:

   $ sudo dnf install -y skopeo

2. Set the environment variables pointing to the pull secret file:

   $ IMAGE_PULL_FILE=~/.pull-secret-mirror.json

3. Set the environment variables pointing to the local container image directory:

   $ IMAGE_LOCAL_DIR=~/microshift-containers

4. Set the environment variables pointing to the mirror registry URL for uploading the container images:

   $ TARGET_REGISTRY=<registry_host>:<port> 1

   1

   Replace <registry_host>:<port> with the host name and port of your mirror registry server.

5. Run the following script to upload the container images to the ${TARGET_REGISTRY} mirror registry:

   image_tag=mirror-$(date +%y%m%d%H%M%S)
   image_cnt=1
      # Uses timestamp and counter as a tag on the target images to avoid
      # their overwrite by the 'latest' automatic tagging
   
   pushd "${IMAGE_LOCAL_DIR}" >/dev/null
   while read -r src_manifest ; do
      # Remove the manifest.json file name
      src_img=$(dirname "${src_manifest}")
      # Add the target registry prefix and remove SHA
      dst_img="${TARGET_REGISTRY}/${src_img}"
      dst_img=$(echo "${dst_img}" | awk -F'@' '{print $1}')
   
      # Run the image upload command
      echo "Uploading '${src_img}' to '${dst_img}'"
      skopeo copy --all --quiet \
         --preserve-digests \
         --authfile "${IMAGE_PULL_FILE}" \
         dir://"${IMAGE_LOCAL_DIR}/${src_img}" docker://"${dst_img}:${image_tag}-${image_cnt}"
      # Increment the counter
      (( image_cnt += 1 ))
   
   done < <(find . -type f -name manifest.json -printf '%P\n')
   popd >/dev/null

Procedure

1. Log into your MicroShift host.

2. Enable the SSL certificate trust on any host accessing the mirror registry by completing the following steps:

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

   2. Enable the certificate in the system-wide trust store configuration by running the following command:

      $ sudo update-ca-trust

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

4. Enable the MicroShift service by running the following command:

   $ sudo systemctl enable microshift

5. Reboot the host by running the following command:

   $ sudo reboot