Chapter 3. Mirroring images for a disconnected installation

Procedure

1. If your mirror registry requires authentication, run the following command to log in to the registry:

   $ podman login <mirror_registry>

2. Run the following command to extract and mirror the content to the mirror registry:

   $ oc adm catalog mirror \
       <index_image> \ 1
       <mirror_registry>:<port>/<namespace> \ 2
       [-a ${REG_CREDS}] \ 3
       [--insecure] \ 4
       [--index-filter-by-os='<platform>/<arch>'] \ 5
       [--manifests-only] 6

   1

   Specify the index image for the catalog that you want to mirror. For example, this might be a pruned index image that you created previously, or one of the source index images for the default catalogs, such as registry.redhat.io/redhat/redhat-operator-index:v4.9.

   2

   Specify the fully qualified domain name (FQDN) for the target registry and namespace to mirror the Operator contents to, where <namespace> is any existing namespace on the registry. For example, you might create an olm-mirror namespace to push all mirrored content to.

   3

   Optional: If required, specify the location of your registry credentials file. {REG_CREDS} is required for registry.redhat.io.

   4

   Optional: If you do not want to configure trust for the target registry, add the --insecure flag.

   5

   Optional: Specify which platform and architecture of the index image to select when multiple variants are available. Images are passed as '<platform>/<arch>[/<variant>]'. This does not apply to images referenced by the index. Valid values are linux/amd64, linux/ppc64le, linux/s390x, and .*

   6

   Optional: Generate only the manifests required for mirroring, and do not actually mirror the image content to a registry. This option can be useful for reviewing what will be mirrored, and it allows you to make any changes to the mapping list if you require only a subset of packages. You can then use the mapping.txt file with the oc image mirror command to mirror the modified list of images in a later step. This flag is intended for only advanced selective mirroring of content from the catalog; the opm index prune command, if you used it previously to prune the index image, is suitable for most catalog management use cases.

   Example output

   src image has index label for database path: /database/index.db
   using database path mapping: /database/index.db:/tmp/153048078
   wrote database to /tmp/153048078 1
   ...
   wrote mirroring manifests to manifests-redhat-operator-index-1614211642 2

   1

   Directory for the temporary index.db database generated by the command.

   2

   Record the manifests directory name that is generated. This directory is referenced in subsequent procedures.

   Note

   Red Hat Quay does not support nested repositories. As a result, running the oc adm catalog mirror command will fail with a 401 unauthorized error. As a workaround, you can use the --max-components=2 option when running the oc adm catalog mirror command to disable the creation of nested repositories. For more information on this workaround, see the Unauthorized error thrown while using catalog mirror command with Quay registry Knowledgebase Solution.

Procedure

1. Run the following command on your workstation with unrestricted network access to mirror the content to local files:

   $ oc adm catalog mirror \
       <index_image> \ 1
       file:///local/index \ 2
       -a ${REG_CREDS} \ 3
       --insecure \ 4
       --index-filter-by-os='<platform>/<arch>' 5

   1

   Specify the index image for the catalog that you want to mirror. For example, this might be a pruned index image that you created previously, or one of the source index images for the default catalogs, such as registry.redhat.io/redhat/redhat-operator-index:v4.9.

   2

   Specify the content to mirror to local files in your current directory.

   3

   Optional: If required, specify the location of your registry credentials file.

   4

   Optional: If you do not want to configure trust for the target registry, add the --insecure flag.

   5

   Optional: Specify which platform and architecture of the index image to select when multiple variants are available. Images are specified as '<platform>/<arch>[/<variant>]'. This does not apply to images referenced by the index. Valid values are linux/amd64, linux/ppc64le, linux/s390x, and .*

   Example output

   ...
   info: Mirroring completed in 5.93s (5.915MB/s)
   wrote mirroring manifests to manifests-my-index-1614985528 1
   
   To upload local images to a registry, run:
   
   	oc adm catalog mirror file://local/index/myrepo/my-index:v1 REGISTRY/REPOSITORY 2

   1

   Record the manifests directory name that is generated. This directory is referenced in subsequent procedures.

   2

   Record the expanded file:// path that is based on your provided index image. This path is referenced in a subsequent step.

   This command creates a v2/ directory in your current directory.

2. Copy the v2/ directory to removable media.
3. Physically remove the media and attach it to a host in the disconnected environment that has access to the mirror registry.

4. If your mirror registry requires authentication, run the following command on your host in the disconnected environment to log in to the registry:

   $ podman login <mirror_registry>

5. Run the following command from the parent directory containing the v2/ directory to upload the images from local files to the mirror registry:

   $ oc adm catalog mirror \
       file://local/index/<repo>/<index_image>:<tag> \ 1
       <mirror_registry>:<port>/<namespace> \ 2
       -a ${REG_CREDS} \ 3
       --insecure \ 4
       --index-filter-by-os='<platform>/<arch>' 5

   1

   Specify the file:// path from the previous command output.

   2

   Specify the fully qualified domain name (FQDN) for the target registry and namespace to mirror the Operator contents to, where <namespace> is any existing namespace on the registry. For example, you might create an olm-mirror namespace to push all mirrored content to.

   3

   Optional: If required, specify the location of your registry credentials file.

   4

   Optional: If you do not want to configure trust for the target registry, add the --insecure flag.

   5

   Optional: Specify which platform and architecture of the index image to select when multiple variants are available. Images are specified as '<platform>/<arch>[/<variant>]'. This does not apply to images referenced by the index. Valid values are linux/amd64, linux/ppc64le, linux/s390x, and .*

   Note

   Red Hat Quay does not support nested repositories. As a result, running the oc adm catalog mirror command will fail with a 401 unauthorized error. As a workaround, you can use the --max-components=2 option when running the oc adm catalog mirror command to disable the creation of nested repositories. For more information on this workaround, see the Unauthorized error thrown while using catalog mirror command with Quay registry Knowledgebase Solution.

6. Run the oc adm catalog mirror command again. Use the newly mirrored index image as the source and the same mirror registry namespace used in the previous step as the target:

   $ oc adm catalog mirror \
       <mirror_registry>:<port>/<index_image> \
       <mirror_registry>:<port>/<namespace> \
       --manifests-only \1
       [-a ${REG_CREDS}] \
       [--insecure]

   1

   The --manifests-only flag is required for this step so that the command does not copy all of the mirrored content again.

   Important

   This step is required because the image mappings in the imageContentSourcePolicy.yaml file generated during the previous step must be updated from local paths to valid mirror locations. Failure to do so will cause errors when you create the ImageContentSourcePolicy object in a later step.