Installing IBM Application Modernization Accelerator 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 Application Modernization Accelerator 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 Application Modernization Accelerator CASE contains three inventory items:

• v2InstallProduct - Provides the CASE actions to install/uninstall the Application Modernization Accelerator product. It will first install the operator - optionally installing catalogs as required - and then install the instance.
• v2AppModOperator - Provides the CASE actions to install/uninstall the Application Modernization Accelerator operator.
• v2AppMod - Provides the CASE actions to install/uninstall the Application Modernization Accelerator 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.

A consequence of enabling catalog-based mirroring in Application Modernization Accelerator 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.

If installing Application Modernization Accelerator for the first time, or if upgrading, 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 Application Modernization Accelerator that you are installing.

cd ~/.ibm-pak/data/mirror/ibm-appmod/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 Application Modernization Accelerator CASE. You can find the required CASE name and version in the IBM Cloud Pak CASE repository.

   export CASE_NAME=ibm-appmod
   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. Create the namespace required for Application Modernization Accelerator:

    export NAMESPACE=<my_ama_namespace>
    oc new-project $NAMESPACE

13. Install Application Modernization Accelerator

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

    oc ibm-pak launch \
     $CASE_NAME \
     --version $CASE_VERSION \
     --action install \
     --inventory v2InstallProduct \
     --namespace $NAMESPACE \
     --args "--acceptLicense true --licenseType <X-XXXX-XXXXXX> --installAmaCatalog --persistence true --storageClass <your_storage_class>"

    For more information on the options accepted by Application Modernization Accelerator, 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:

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:

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: --amaHelp
• View the different license options available: --viewLicense
• Install the Application Modernization Accelerator private catalog if it does not already exist. Required for disconnected install: --installAmaCatalog
• Enable persistence and set the storage class: --persistence true --storageClass <your_storage_class>

For a full list of options, see Configuring Application Modernization Accelerator .

At the end of a successful install, you will be presented with a link in the console that will take you to the Application Modernization Accelerator UI. Alternatively, you can navigate to the Application Modernization Accelerator 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 Application Modernization Accelerator UI.