Generating mirror manifests

Procedure

Complete the following steps to generating mirror manifests.

Note: If you want to install subsequent updates to your air-gapped environment, you must run CASE get command to get the image list when performing those updates. A registry namespace suffix can optionally be specified on the target registry to group-mirrored images.

Define the environment variable $TARGET_REGISTRY by running the following command:
```
export TARGET_REGISTRY=<target-registry>
```
The <target-registry> refers to the registry (hostname and port) where your images will be mirrored to and accessed by the oc cluster. For example, setting <target-registry> to myregistry.com:5000/mynamespace will create manifests such that images will be mirrored to the top-level namespace mynamespace.

Run the following command to generate mirror manifests to be used when mirroring from a bastion host (connected mirroring):

oc ibm-pak generate mirror-manifests \
   $CASE_NAME \
   $TARGET_REGISTRY \
   --version $CASE_VERSION

For example, ~/.ibm-pak` directory structure for connected mirroring. The ~/.ibm-pak directory structure is built over time as you save CASEs and mirror. The following tree shows an example of the `~/.ibm-pak` directory structure for connected mirroring:


   tree ~/.ibm-pak
   ├── config
   │   └── config.yaml
   ├── data
   │   ├── cases
   │   │   └── ibm-oms-ent-case
   │   │       ├── 3.0.12
   │   │       │   ├── caseDependencyMapping.csv
   │   │       │   ├── charts
   │   │       │   ├── component-set-config.yaml
   │   │       │   ├── ibm-oms-ent-case-3.0.12-airgap-metadata.yaml
   │   │       │   ├── ibm-oms-ent-case-3.0.12-charts.csv
   │   │       │   ├── ibm-oms-ent-case-3.0.12-images.csv
   │   │       │   ├── ibm-oms-ent-case-3.0.12.tgz
   │   │       │   └── resourceIndexes
   │   │       │       └── ibm-oms-ent-case-resourcesIndex.yaml
   │   │       └── 3.0.15
   │   │           ├── caseDependencyMapping.csv
   │   │           ├── charts
   │   │           ├── component-set-config.yaml
   │   │           ├── ibm-oms-ent-case-3.0.15-airgap-metadata.yaml
   │   │           ├── ibm-oms-ent-case-3.0.15-charts.csv
   │   │           ├── ibm-oms-ent-case-3.0.15-images.csv
   │   │           ├── ibm-oms-ent-case-3.0.15.tgz
   │   │           └── resourceIndexes
   │   │               └── ibm-oms-ent-case-resourcesIndex.yaml
   │   ├── mirror
   │   │   └── ibm-oms-ent-case
   │   │       └── 3.0.15
   │   │           ├── catalog-sources-linux-amd64.yaml
   │   │           ├── image-content-source-policy.yaml
   │   │           └── images-mapping.txt
   │   ├── online
   │   └── publish
   ├── logs
   │   └── oc-ibm_pak.log
   └── oc-mirror-storage

A new directory ~/.ibm-pak/mirror is created when you issue the oc ibm-pak generate mirror-manifests command. This directory holds the image-content-source-policy.yaml, images-mapping.txt, and catalog-sources.yaml files.

If you are using a Red Hat® Quay.io registry and need to mirror images to a specific organization in the registry, you can target that organization by specifying the organization name:

export ORGANIZATION=<your-organization>
oc ibm-pak generate mirror-manifests \
   $CASE_NAME \
   $TARGET_REGISTRY/$ORGANIZATION \
   --version $CASE_VERSION

You can also generate manifests to mirror images to an intermediate registry server, then mirroring to a final registry server. This is done by passing the final registry server as an argument to --final-registry.

oc ibm-pak generate mirror-manifests \
   $CASE_NAME \
   $INTERMEDIATE_REGISTRY \
   --version $CASE_VERSION
   --final-registry $FINAL_REGISTRY

In this case, in place of a single mapping file (images-mapping.txt), two mapping files are created.

1. images-mapping-to-registry.txt
2. images-mapping-from-registry.txt

Run the following command to generate mirror manifests to be used when mirroring from a file system (disconnected mirroring):
```
oc ibm-pak generate mirror-manifests \
   $CASE_NAME \
   file://local \
   --final-registry $TARGET_REGISTRY
```
The following tree shows an example of the ~/.ibm-pak directory structure for disconnected mirroring:
```
   
   tree ~/.ibm-pak
   ├── config
   │   └── config.yaml
   ├── data
   │   ├── cases
   │   │   └── ibm-oms-ent-case
   │   │       ├── 3.0.12
   │   │       │   ├── caseDependencyMapping.csv
   │   │       │   ├── charts
   │   │       │   ├── component-set-config.yaml
   │   │       │   ├── ibm-oms-ent-case-3.0.12-airgap-metadata.yaml
   │   │       │   ├── ibm-oms-ent-case-3.0.12-charts.csv
   │   │       │   ├── ibm-oms-ent-case-3.0.12-images.csv
   │   │       │   ├── ibm-oms-ent-case-3.0.12.tgz
   │   │       │   └── resourceIndexes
   │   │       │       └── ibm-oms-ent-case-resourcesIndex.yaml
   │   │       └── 3.0.15
   │   │           ├── caseDependencyMapping.csv
   │   │           ├── charts
   │   │           ├── component-set-config.yaml
   │   │           ├── ibm-oms-ent-case-3.0.15-airgap-metadata.yaml
   │   │           ├── ibm-oms-ent-case-3.0.15-charts.csv
   │   │           ├── ibm-oms-ent-case-3.0.15-images.csv
   │   │           ├── ibm-oms-ent-case-3.0.15.tgz
   │   │           └── resourceIndexes
   │   │               └── ibm-oms-ent-case-resourcesIndex.yaml
   │   ├── mirror
   │   │   └── ibm-oms-ent-case
   │   │       └── 3.0.15
   │   │           ├── catalog-sources-linux-amd64.yaml
   │   │           ├── image-content-source-policy.yaml
   │   │           └── images-mapping.txt
   │   ├── online
   │   └── publish
   ├── logs
   │   └── oc-ibm_pak.log
   └── oc-mirror-storage
```
Note: A new directory ~/.ibm-pak/mirror is created when you issue the oc ibm-pak generate mirror-manifests command. This directory holds the image-content-source-policy.yaml, images-mapping-to-filesystem.txt, images-mapping-from-filesystem.txt, and catalog-sources.yaml files.
Tip:
Some products support the ability to generate mirror manifests only for a subset of images by using the --filter argument and image grouping. The --filter argument provides the ability to customize which images are mirrored during an air-gapped installation. As an example for this function, ibm-cloud-native-postgresql CASE can be used, which contains groups that allow mirroring-specific variant of ibm-cloud-native-postgresql (Standard or Enterprise). Use the --filter argument to target a variant of ibm-cloud-native-postgresql to mirror rather than the entire library. The filtering can be applied for groups and architectures. Consider the following command:
```
oc ibm-pak generate mirror-manifests \
   ibm-cloud-native-postgresql \
   file://local \
   --final-registry $TARGET_REGISTRY \
   --filter $GROUPS
```
The command was updated with a --filter argument. For example, for $GROUPS equal to ibmEdbStandard the mirror manifests will be generated only for the images associated with ibm-cloud-native-postgresql in its Standard variant. The resulting image group consists of images in the ibm-cloud-native-postgresql image group in addition to any images that are not associated with any groups. This allows products to include common images and the ability to reduce the number of images that you need to mirror.
Note:
You can use the following command to list all the images that will be mirrored and the publicly accessible registries from where those images will be pulled from:
```
oc ibm-pak describe $CASE_NAME --version $CASE_VERSION --list-mirror-images
```
Tip: The output of the preceding command will have two sections:
- Mirroring Details from Source to Target Registry
- Mirroring Details from Target to Final Registry.
A connected mirroring path that does not involve an intermediate registry will only have the first section. Note down the Registries found sub-sections in the preceding command output. Authenticate against those registries so that the images can be pulled and mirrored to your local registry. See the next steps on authentication. The Top level namespaces found section shows the list of namespaces under which the images will be mirrored. These namespaces should be created manually in your registry (which appears in the Destination column in the above command output) root path if your registry does not allow automatic creation of namespaces.