Mirroring prerequisites

Complete the following perquisites before you mirror images of IBM Fusion and its services.

Prepare your mirroring host

The mirror host must have access to the internet and enterprise registry.
Ensure that you install the following tools on your system from where you can connect to Red Hat® registry and enterprise registry:
- Install Docker or Podman to create, run, and maintain images.
  If you are using self-signed certificate registry, then ensure that you have updated the container tools configuration with insecure registries to skip certificate validation. For more information about how to update, see Update container tools configuration.
- Install skopeo for Global Data Platform storage image copy operation. For more information to install skopeo, see https://github.com/containers/skopeo.
- Install OC command tool from any of the Red Hat OpenShift® Container Platform cluster:
  1. Log in to the system from where you want to run commands.
  2. Log in to OpenShift Container Platform.
  3. Click bell icon and select Command line tools.
  4. Click the appropriate oc download option based on your operating system.
  Alternatively, you can also download the platform based oc client.
  Note: For example, if the latest version is 4.18.10, then use the following link to download oc client for Linux platform: https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/ocp/4.18.10/openshift-client-linux-4.18.10.tar.gz.
Download and install ibm-pak OC plugin tool. For more information about the procedure, see https://github.com/IBM/ibm-pak.
Download pull-secret.txt.
To download the pull-secret, see https://console.redhat.com/openshift/install/pull-secret and follow the instructions.
You can either use podman command to add private registry credentials to downloaded pull-secret.json or manually edit the downloaded pull-secret with registry credentials. For example:
```
podman login registryhost.com:443 --authfile=pull-secret.json "
```
Add a new section of key-value pair under auths. For example,
```
"<Your enterprise registry>:<port>": {
"auth": "<base64 encoded 'user_name:password'>",
email: "<your email>" }
```
As a prerequisite to run base64, you must install base64 or jq.
See the following sample values:
```
{ 
"auths": { 
   "cloud.openshift.com": { 
      .... 
   "registryhost.com:443": { 
       "auth": "dXNlcl9uYW1lOnBhc3N3b3Jk",   
        "email": "user_name@ibm.com" 
    }
  }
}
```
Here, user_name and password are credentials to connect to enterprise registry.
Note: If you want to use multiple repositories, add an auth section for both repositories.
To authenticate to quay.io by using the username and password from the pull-secret, do the following steps:
1. Look for quay.io in the json and copy auth. Example:
```
  "auths": {
    "quay.io": {
      "auth": "b3BlbnNoaWZ0LXJTczOGY2YzNjNDM2ZWI0JRSDdUQU45RFBWVUNXM0VZQUlVVDBOQTU3VFM2RE1JMg==",
      "email": <email-id>
    }
  }
}
```
  It is a base64 encoded value of username:password.
2. Get the username/password.
```
echo <auth-content> | base64 –decode 
```
  Example echo command:
```
echo "b3BlbnNoaWZ0LXJTczOGY2YzNjNDM2ZWI0JRSDdUQU45RFBWVUNXM0VZQUlVVDBOQTU3VFM2RE1JMg==" | base64 –decode
```
  Example output:
```
openshift-release+ocmaccess0ab5738f6c3c42:CXKR2TSBQH7TAN9
```
  Here, openshift-release+ocmaccess0ab5738f6c3c42 is the user name and CXKR2TSBQH7TAN9 is the password.
Command line to get the username/password :echo <auth-content> | base64 –decode
Ensure that you have entitlement key to access IBM Fusion HCI appliance images. For more information about entitlement key, see Activating IBM Fusion HCI Software to be downloaded.

General prerequisites

Before you proceed with mirroring, be aware of key considerations, known issues, and troubleshooting information. See Troubleshooting and known issues in offline mirroring.
Provide the port number as follows:
For installation
If you want to use the default port (443), then make sure you provide the port number.
For example, <Your enterprise registry>:9443.

If you want to use custom port, then provide the custom details.
To verify, log in to your registry:port by using docker or podman. Use the following podman command:
```
"podman login registryhost:registryport" 
```

The registry must have at least one directory path specified.

For example:

https://<enterprise registry host>:<enterprise registry port>/<mandatory root path>

Ensure that your secure enterprise registry is already setup and ready for use. Support is available for Quay and registries with self signed certificate.
Important: Always mirror the most recent images at any point in time to your registry before installation.
Run a pull command in your network to test the network speed. If that time is more than 2 to 5 minutes, there may be an overall reduction in network speed that can cause installation failure. Example command:
```
time podman pull cp.icr.io/cp/isf/isf-compute-operator@sha256:414275e851972db2b7172642f7f7827c42da14914061bd5d82ea0584e6ce7fc8
```

Single or multiple repositories

You can either host your images in a single repository or host your OpenShift and IBM Fusion images separately. Choose the latter option if you want to manage their OpenShift images separately from other software.

Single repository: If you want to use Single repository, mirror all the images to IBM Fusion images repository, so your $LOCAL_OCP_REGISTRY remains same as $LOCAL_ISF_REGISTRY.

Multiple repositories: If you want to use Multiple repositories, mirror the OpenShift images to the OpenShift images repository ($LOCAL_OCP_REGISTRY) and all other images to the IBM Fusion images repository ($LOCAL_ISF_REGISTRY).

Considerations for your enterprise registry

There must not be a huge latency between cluster nodes and your enterprise registry. Slow image pull can cause OpenShift Container Platform installation to fail.
You must have a container image registry that supports Docker v2-2 in the location that hosts the Red Hat OpenShift Container Platform cluster. For more information about image manifest, see opm CLI reference .
Important: Artifactory is the recommended registry because it supports the following must have capabilities:
- Import and export
- Untagged images
JFrog Artifactory version 7.55.8 is tested on IBM Fusion HCI. The port that is specified in the URL is used to login and pull the images from the enterprise repository. For a secured enterprise registry, specify 443. If you do not provide the port value, then no default port is considered in its absence. The API key is the only supported authentication method.
For disconnected installation, you need a firewall type proxy server and for an air break installation, the registry must have import and export capabilities.
If you are using self-signed certificate registry, then ensure that you have updated the container tools configuration with insecure registries to skip certificate validation.
- For Podman, see https://docs.podman.io/en/stable/markdown/podman-login.1.html.
- For Docker, follow the steps to skip certificate validation:
  - To trust the certificate in the Docker daemon:
    For Linux, copy the domain.crt file to /etc/docker/certs.d/myregistrydomain.com:5000/ca.crt on your mirroring host, Where domain.crt is a self-signed generated certificate and myregistrydomain.com is your Docker registry and 5000 is port for registry.
  - For configuring an insecure registry:
    Note: It is insecure and not recommended.
    
    Edit the daemon.json file that present in the default location of /etc/docker/daemon.json on the Linux Server.
    If the daemon.json file does not exist, then create it. Ensure it contains the following contents:
```
{
  "insecure-registries" : ["myregistrydomain.com:5000"]
}
```
Offline upgrade cons
The offline mirroring process includes applying ImageDigestMirrorSet or ImageContentSourcePolicy files to your cluster. Any changes to the IDMS or ICSP on clusters triggers a MachineConfigPool rollout, which can cause nodes to reboot. This includes adding, updating, or deleting IDMS or ICSP files.
There are two options for offline upgrade mirroring:

Mirroring images to the same location as the previous offline installation

This gives the IDMS or ICSP files that are identical to your previous installation, and you can choose to not apply the IDMS or ICSP files or oc apply the file and OpenShift recognizes there is no change in content and exit gracefully.

Mirror images to a different location as the previous offline installation

Because the generated IDMS or ICSP is tailored specifically to the target offline registry, mirroring to a new location every time gives a different IDMS or ICSP every time. Applying a new IDMS or ICSP triggers the MCP rollout and contains the potential to reboot nodes, which can be disruptive to the health of the OpenShift cluster.

Additionally, if you have done multiple offline upgrades using this method, then your cluster likely have multiple ICSP or IDMS files, some of which are old and unused. Again, deleting a IDMS or ICSP can trigger a disruptive MCP rollout. It is recommended to not delete any IDMS or ICSP files from the cluster until you have completed your upgrade to your target version of IBM Fusion HCI.
However, the ibm-pak plugin generates an IDMS with the same name every time, if you use this method, it is recommended you to edit the generated IDMS and change the metadata.name to unique name to avoid overwriting an existing IDMS on your cluster.