Installing IBM Transformation Advisor in a Disconnected/Air-gapped Environment

The Container Application Software for Enterprises (CASE) specification defines metadata and structure for packaging a containerized application. For more details please see CASE Specification.

The CASE installer provides the commands needed to install/uninstall Transformation Advisor using the CLI. The CASE install action will install both the operator and instance with a single command.

Installing using the CASE installer supports the same two install modes as installing using the OpenShift UI:

• All namespaces on the cluster (default)

  Operator will be available in all Namespaces.

• A specific namespace on the cluster (specify the --namespaceScoped true in the --args)

  Operator will be available in a single Namespace only.

For both installation modes, you are required to perform some steps as a cluster administrator as described in the Cluster Administration Tasks section in the installation instructions.

The Transformation Advisor CASE contains three inventory items:

• v2InstallProduct - Provides the CASE actions to install/uninstall the Transformation Advisor product. It will first install the operator - optionally installing catalogs as required - and then install the instance.
• v2TransAdvOperator - Provides the CASE actions to install/uninstall the Transformation Advisor operator.
• v2TransAdv - Provides the CASE actions to install/uninstall the Transformation Advisor instance.

Each inventory has a README.md with details on the install actions and options available in that inventory.

The ibm-pak-plugin is a plugin for the oc CLI tool that streamlines the deployment of IBM CloudPaks in a disconnected environment which was done earlier using cloudctl.

Please read the ibm-pak-plugin documentation.

Starting with ibm-pak v1.8.0, the plug-in lays the foundation for eventual support for catalog-based mirroring. Information about catalog-based mirroring is described in the documentation. At this time, catalog-based mirroring and oc-mirror tool usage is a Tech Preview feature, which may not be supported by all products. Transformation Advisor is enabled for catalog-based mirroring starting from version 3.8.0. oc mirror tool usage is enabled in Transformation Advisor as a Tech Preview. The recommended install path continues to leverage oc image mirror as described in the steps here.

A consequence of enabling catalog-based mirroring in Transformation Advisor is that the images-mapping.txt file generated by oc ibm-pak generate mirror-manifests ... command now contains all the versions necessary to install or to upgrade from any allowed upgrade path.

KNOWN ISSUE: In Transformation Advisor 3.8.0 and 3.8.1 there is a known issue whereby more images than are necessary are populated in the ~/.ibm-pak/data/mirror/ibm-transadv/VERSION/images-mapping.txt after running oc ibm-pak generate mirror-manifests .... Additionally, some of the image references are incorrect and cause the subsequent oc image mirror ... command to fail. You can manually edit the ~/.ibm-pak/data/mirror/ibm-transadv/VERSION/images-mapping.txt file before running oc image mirror ... to remove unwanted images. See the following note for instructions on removing all but the current version images.

If installing Transformation Advisor for the first time, or if upgrading from Version 3.0.1+, you can use the following command to reduce the number of images to mirror.

Replace MAJOR, MINOR and PATCH with the MAJOR, MINOR and PATCH numbers that correspond to the version of Transformation Advisor that you are installing.

cd ~/.ibm-pak/data/mirror/ibm-transadv/MAJOR.MINOR.PATCH/
mv images-mapping.txt images-mapping.txt.orig
grep ":MAJOR\.MINOR\.PATCH" images-mapping.txt.orig > images-mapping.txt
grep ":vMAJOR\.MINOR" images-mapping.txt.orig >> images-mapping.txt
 

1. Download the ibm-pak plugin, and oc tools. Downloading the tools is described in the ibm-pak documentation.
2. Configure the ibm-pak plugin to point to the CASE repository. You can choose to point to the IBM GitHub repo (https://github.com/IBM/cloud-pak/raw/master/repo/case/) OR (as of ibm-pak version 1.2.0) to the IBM Cloud Container Registry and download the CASE as OCI artifacts.

   oc ibm-pak config repo 'IBM Cloud-Pak Github Production Repo' --url https://github.com/IBM/cloud-pak/raw/master/repo/case/ --enable
    

   OR

   oc ibm-pak config repo 'IBM Cloud-Pak OCI registry' -r oci:cp.icr.io/cpopen --enable
    

3. Choose one of the supported paths for the disconnected installation. The IBM Cloud Pak documentation describes the two supported paths: Bastion host and Filesystem.
4. Download the Transformation Advisor CASE - substituting the desired version:

   export CASE_NAME=ibm-transadv
   export CASE_VERSION=X.Y.Z
   oc ibm-pak get $CASE_NAME --version $CASE_VERSION
    

5. Verify you have downloaded the correct version:

   oc ibm-pak list --downloaded
    

6. Generate the mirror manifests - substituting the actual target registry:

   1. For Bastion host path:

      export TARGET_REGISTRY=mytargetregistry.com
      oc ibm-pak generate mirror-manifests $CASE_NAME $TARGET_REGISTRY --version $CASE_VERSION
       

   2. For Filesystem path:

      export TARGET_REGISTRY=mytargetregistry.com
      oc ibm-pak generate mirror-manifests \
       $CASE_NAME \
       file://local \
       --version $CASE_VERSION \
       --final-registry $TARGET_REGISTRY
       

7. Authenticate to all registries. Follow the instructions here to authenticate to all registries using either podman or docker. Set the REGISTRY_AUTH_FILE environment variable appropriately.

8. (Bastion) Mirror images - Bastion host path: By default, TARGET_REGISTRY is assumed to be secure. To use the insecure option for mirroring images, refer to the details here.

   1. Set the SSL_CERT_FILE environment variable correctly - substituting the actual ssl certificate file:

      export SSL_CERT_FILE=path_to_crt_file
       

   2. Download images:

      oc image mirror \
      -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping.txt \
      --filter-by-os '.*'  \
      -a $REGISTRY_AUTH_FILE \
      --skip-multiple-scopes \
      --max-per-registry=1
       

9. (Filesystem) Mirror images - Filesystem path:

   1. Set the SSL_CERT_FILE environment variable correctly - substituting the actual ssl certificate file:

      export SSL_CERT_FILE=path_to_crt_file
       

   2. Download images to file system:

      oc image mirror \
      -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping-to-filesystem.txt \
      --filter-by-os '.*' \
      -a $REGISTRY_AUTH_FILE \
      --skip-multiple-scopes \
      --max-per-registry=1
       

   3. Move the generated items to a machine inside the firewall which has access to the TARGET_REGISTRY. The items to move are:

      1. v2 directory
      2. The auth file referred by $REGISTRY_AUTH_FILE
      3. ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping-from-filesystem.txt

   4. Move images to final destination:

      oc image mirror \
      -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping-from-filesystem.txt \
      -a $REGISTRY_AUTH_FILE \
      --from-dir=${v2_dir} \
      --filter-by-os '.*' \
      --skip-multiple-scopes \
      --max-per-registry=1
       

      ${v2_dir} refers to the parent directory on the file system where the v2 directory was copied to.

10. Update the global image pull secret for your Red Hat OpenShift cluster. Add in the secret to allow your cluster to pull from your mirror registry - if you have not already set that up. Follow the steps in Updating the global cluster pull secret.

11. Create ImageContentSourcePolicy

    oc apply -f  ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/image-content-source-policy.yaml
     

    Wait until all nodes are ready. You can monitor the nodes with the following command:

    oc get nodes -w
     

    Alternatively, monitor the MachineConfigPool - and ensure the UPDATED column reads True for the relevant worker pool:

    oc get MachineConfigPool -w
     

12. Install Transformation Advisor

    • The following command will perform a full installation of Transformation Advisor. It will first install the private catalog, then the Transformation Advisor operator, and finally the instance. Substitute your desired namespace, a valid license type and set other options as required.

    export NAMESPACE=<my_ta_namespace>
    oc ibm-pak launch \
     $CASE_NAME \
     --version $CASE_VERSION \
     --action install \
     --inventory v2InstallProduct \
     --namespace $NAMESPACE \
     --args "--acceptLicense true --licenseType <X-XXXX-XXXXXX> --installTaCatalog --persistence true --storageClass ibmc-block-gold" 
     

    For more information on the options accepted by Transformation Advisor, see install options.

If you prefer not to configure trust for the target registry, you can add the --insecure flag.

(Bastion) Mirror images - Bastion host path:

oc image mirror \
 -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping.txt \
 --filter-by-os '.*'  \
 -a $REGISTRY_AUTH_FILE \
 --insecure  \
 --skip-multiple-scopes \
 --max-per-registry=1
 

(Filesystem) Mirror images - Filesystem path: 1. Download images to file system:

     ```bash {: codeblock}
     oc image mirror \
     -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping-to-filesystem.txt \
     --filter-by-os '.*' \
     -a $REGISTRY_AUTH_FILE \
     --insecure \
     --skip-multiple-scopes \
     --max-per-registry=1
     ```
  2. Move the generated items to a machine inside the firewall which has access to the TARGET_REGISTRY. The items to move are:
     1. v2 directory
     2. The auth file referred by `$REGISTRY_AUTH_FILE`
     3. `~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping-from-filesystem.txt`
  3. Move images to final destination:

     ```bash {: codeblock}
     oc image mirror \
     -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping-from-filesystem.txt \
     -a $REGISTRY_AUTH_FILE \
     --from-dir=${v2_dir} \
     --filter-by-os '.*' \
     --insecure \
     --skip-multiple-scopes \
     --max-per-registry=1
     ```
     `${v2_dir}` refers to the parent directory on the file system where the v2 directory was copied to.
 

1. Configure cluster for insecure registry

   • If your TARGET_REGISTRY is insecure, you must add it to the cluster insecureRegistries list.

     oc patch image.config.openshift.io/cluster --type=merge \
     -p '{"spec":{"registrySources":{"insecureRegistries":["'${TARGET_REGISTRY}'"]}}}'
      

The following options can be provided in the --args parameter to customize the installation.

• View the full set of options: --taHelp
• View the different license options available: --viewLicense
• Install the Transformation Advisor private catalog if it does not already exist. Required for disconnected install: --installTaCatalog
• Enable persistence and set the storage class: --persistence true --storageClass ibmc-block-gold

For a full list of options, see Configuring Transformation Advisor .

At the end of a successful install, you will be presented with a link in the console that will take you to the Transformation Advisor UI. Alternatively, you can navigate to the Transformation Advisor route in the OpenShift UI by going to Networking - Routes and click the location of the ui-route. You will need to have a valid login to the cluster to access Transformation Advisor UI.