Installing IBM Cloud Transformation Advisor

IBM Transformation Advisor can be installed from IBM Operator Catalog in the OperatorHub in the Red Hat OpenShift UI.

For a disconnected or air-gap install, Transformation Advisor can be installed using the ibm-pak-plugin and the CASE package. See airgap install for more details.

As part of the installation procedure for Transformation Advisor (for both UI install and air-gap install), cluster administration tasks are required to be performed by a cluster administrator. See Cluster Admin Tasks for more details.

  1. Install Red Hat OpenShift Container Platform
  2. Configure Storage
  3. Add the IBM Operator Catalog
  4. Choose Installation Mode
  5. Perform Cluster Administration Tasks for Operator Installation
  6. Install Operator
  7. Create entitlement key
  8. Perform Cluster Administration Tasks for Instance Installation
  9. Create Transformation Advisor instance

Uninstall Transformation Advisor

1. Install Red Hat OpenShift Container Platform

Please see [Installing Red Hat OpenShift Container Platform] (https://www.ibm.com/docs/en/cloud-paks/1.0?topic=installing-openshift-container-platform-clusters)

2. Configure Storage

It is highly recommended to configure storage for Transformation Advisor. You may explore the product functionality without storage configured (and setting persistence enabled to false), however you will lose your data when the Transformation Advisor database container restarts. For a full description of storage considerations, please see Storage Considerations.

3. Add the IBM Operator Catalog

Note: Transformation Advisor 2.3.x was delivered in the Red Hat Certified catalog and has now been removed from that catalog. Transformation Advisor 2.4+ is only be available in the IBM Operator Catalog. See Upgrading for more on how to upgrade from 2.3 to 2.4.

Please follow the Adding the IBM operator catalog documentation.

4. Choose Installation Mode

Transformation Advisor supports two installation modes:

  • All namespaces on the cluster (default)

    Operator will be available in all Namespaces.

  • A specific namespace on the cluster

    Operator will be available in a single Namespace only.

Depending on the installation mode chosen, you will need to perform different installation tasks as a cluster administrator. See Cluster Admin Tasks.

5. Perform Cluster Administration Tasks

As part of the installation, the cluster administrator will be required to perform some tasks. Depending on your installation mode, you will need to complete different cluster administration tasks, see subsequent sections for details. For more information on configuring operators with OperatorGroups please see: https://olm.operatorframework.io/docs/advanced-tasks/operator-scoping-with-operatorgroups.

Cluster Administration Tasks for an All Namespaces Operator Installation

The cluster administrator must perform the operator installation for both the Red Hat OpenShift UI installation and the CASE installation.

Cluster Administration Tasks for a Single Namespace Operator Installation

The cluster administrator must perform the following tasks:

  1. Create a project for the operator and instance.

    This can be done from the OpenShift UI as follows:

    a. Click the hamburger icon of the Red Hat OpenShift Container Platform dashboard.
    b. Expand the Home menu and select Projects.
    c. Click Create Project.
    d. Name the project and click Create.

    Alternatively, you can use the oc new-project NAMESPACE_PLACEHOLDER command from the command line, where NAMESPACE_PLACEHOLDER is substituted for the actual name of the project you want to create.

  2. Set up Role Based Access Control (RBAC) for Operator.

    The YAML in this section creates a ServiceAccount, OperatorGroup, Role, RoleBinding, ClusterRole and ClusterRoleBinding resource which together configure RBAC for the operator. Apply the YAML to your cluster:

a. Copy the YAML and replace all occurrences of NAMESPACE_PLACEHOLDER with the project that you are installing into.
b. Click the + button in the OpenShift UI and paste the YAML into the Import YAML window.
c. Click Create.

Alternatively, you can save the YAML to file, replace NAMESPACE_PLACEHOLDER with the project you are installing to, and create the resources using the oc apply -f <filename> command.

apiVersion: v1
kind: ServiceAccount
metadata:
  name: ta-operator-sa
  namespace: NAMESPACE_PLACEHOLDER

---

apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: ta-ownnamespace-operator-group
  namespace: NAMESPACE_PLACEHOLDER
spec:
  targetNamespaces:
    - NAMESPACE_PLACEHOLDER

---

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: ibm-transformation-advisor
  namespace: NAMESPACE_PLACEHOLDER
rules:
  - apiGroups: ["networking.k8s.io"]
    resources: ["networkpolicies"]
    verbs: ["get", "list", "watch", "create", "delete", "patch"]
  - apiGroups: ["config.openshift.io"]
    resources: ["ingresses", "infrastructures", "dnses"]
    verbs: ["get"]
  - apiGroups: ["oauth.openshift.io"]
    resources: ["oauthclients", "oauthclients/finalizers"]
    verbs: ["get", "list", "create", "delete"]
  - apiGroups: ["operators.coreos.com"]
    resources: ["clusterserviceversions"]
    verbs: ["get", "list", "watch", "create", "delete", "patch"]
  - apiGroups: ["apiextensions.k8s.io"]
    resources: ["customresourcedefinitions", "customresourcedefinitions/finalizers"]
    verbs: ["get", "list", "watch", "create", "update", "delete", "patch"]
  - apiGroups: [""]
    resources: ["namespaces"]
    verbs: ["get"]
  - apiGroups: ["batch"]
    resources: ["jobs"]
    verbs: ["get", "list", "watch", "create", "update", "delete", "patch"]
  - apiGroups: [""]
    resources: ["configmaps", "persistentvolumeclaims", "pods", "services", "secrets", "serviceaccounts", "events"]
    verbs: ["*"]
  - apiGroups: ["apps"]
    resources: ["deployments", "statefulsets"]
    verbs: ["get", "list", "watch", "create", "update", "delete", "patch"]
  - apiGroups: ["monitoring.coreos.com"]
    resources: ["servicemonitors"]
    verbs: ["get", "create"]
  - apiGroups: ["apps"]
    resourceNames: ["ta-operator"]
    resources: ["deployments/finalizers", "statefulsets/finalizers"]
    verbs: ["update"]
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get"]
  - apiGroups: ["apps"]
    resources: ["replicasets"]
    verbs: ["get", "list", "watch", "create", "update", "delete", "patch"]
  - apiGroups: ["ta.ibm.com"]
    resources: ["*"]
    verbs: ["get", "list", "watch", "create", "update", "delete", "patch"]
  - apiGroups: ["route.openshift.io"]
    resources: ["routes", "routes/custom-host"]
    verbs: ["get", "list", "watch", "create", "update", "delete", "patch"]


---

kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: ibm-transformation-advisor
  namespace: NAMESPACE_PLACEHOLDER
subjects:
  - kind: ServiceAccount
    name: ta-operator-sa
roleRef:
  kind: Role
  name: ibm-transformation-advisor
  apiGroup: rbac.authorization.k8s.io

---

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: ibm-transformation-advisor
rules:
  - apiGroups: ["oauth.openshift.io"]
    resources: ["oauthclients", "oauthclients/finalizers", "consoleyamlsamples"]
    verbs: ["get", "list", "watch", "create", "update", "delete", "patch"]
  - apiGroups: ["console.openshift.io"]
    resources: ["consoleyamlsamples"]
    verbs: ["get", "list", "watch", "create", "update", "delete", "patch"]
  - apiGroups: ["config.openshift.io"]
    resources: ["ingresses", "infrastructures", "dnses"]
    verbs: ["get"]
  - apiGroups: ["rbac.authorization.k8s.io"]
    resources: ["clusterrolebindings", "clusterroles", "clusterroles/finalizers", "roles", "rolebindings", "roles/finalizers", "rolebindings/finalizers"]
    verbs: ["*"]
  - apiGroups: [""]
    resources: ["endpoints", "events"]
    verbs: ["get", "list", "watch", "create", "delete", "patch"]
  - apiGroups: ["discovery.k8s.io/v1"]
    resources: ["endpointslices"]
    verbs: ["get", "list", "watch", "create", "delete", "patch"]
  - apiGroups: ["network.openshift.io"]
    resources: ["netnamespaces", "clusternetworks", "egressnetworkpolicies"]
    verbs: ["get", "list", "watch", "create", "delete", "patch"]
---

kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: ibm-transformation-advisor-NAMESPACE_PLACEHOLDER
subjects:
  - kind: ServiceAccount
    name: ta-operator-sa
    namespace: NAMESPACE_PLACEHOLDER
roleRef:
  kind: ClusterRole
  name: ibm-transformation-advisor
  apiGroup: rbac.authorization.k8s.io

6. Install Operator

NOTE: For a disconnected install, install the operator using the ibm-pak-plugin for a disconnected/air-gap installation.

Install the operator using the Red Hat OpenShift UI

  • Navigate the to Operators...OperatorHub in OpenShift navigation.
  • Select the IBM Operator Catalog in the Source filter.
  • Select the Transformation Advisor tile, filtering as necessary. Read the installation instructions and action as necessary.
  • Click Install
  • Choose the desired options and click Install

After a few minutes you should see confirmation that the operator has installed successfully. The Transformation Advisor operator is now available in the chosen namespace or all namespaces, depending on the install mode selected.

7. Create Entitlement Key

Complete the following steps to create a docker-registry secret to enable your deployment to pull operand images from the IBM® Entitled Registry.

This secret must be specified when installing the Transformation Advisor instance in step 9. See Configuration for more details.

Option 1: Create the entitlement key secret with the OpenShift console

  1. Obtain the entitlement key that is assigned to your IBMid. Log in to MyIBM Container Software Library with the IBMid and password details that are associated with the entitled software.
  2. In the OpenShift console, ensure that you are in the Project (for example, my-project) that you installed the operator into.
  3. Click Workloads > Secrets > Create, then select Image pull secret.
  4. In the Secret name field, enter ibm-entitlement-key.
  5. In the Registry server address field, enter cp.icr.io.
  6. In the Username field, enter cp.
  7. In the Password field, enter the credential that you received from entitlement.
  8. (Optional) In the Email field, enter a contact email address.

Option 2: Create the entitlement key secret with the CLI

Obtain the entitlement key that is assigned to your IBMid. Log in to MyIBM Container Software Library Opens in a new tab with the IBMid and password details that are associated with the entitled software. In the Entitlement keys section, select Copy key to copy the entitlement key to the clipboard. From the Red Hat OpenShift CLI, run the following command to create an image pull secret called ibm-entitlement-key.

oc create secret docker-registry ibm-entitlement-key \
--docker-username=cp\
--docker-password=<entitlement-key> \
--docker-server=cp.icr.io \
--namespace=<namespace>

Where:

- `<entitlement-key>` is the entitlement key that you copied in step 2.
- `<namespace>` is the namespace that you want to install the Transformation Advisor instance in.

As an alternative to creating the ibm-entitlement-key secret, you may update the cluster's global pull secret using your entitlement key credentials. See https://docs.openshift.com/container-platform/4.9/openshift_images/managing_images/using-image-pull-secrets.html#images-update-global-pull-secret_using-image-pull-secrets for how to update the global pull secret. Due to a limitation in the product, if you use the global pull secret, you still need to add the imagePullSecret properties to the Transformation Advisor instance configuration (See Configuration for more details). In this case, the value you use for the properties does not have to exist as a secret.

8. Perform Cluster Administration Tasks for Instance Installation

Before installing the Transformation Advisor instance, as cluster administrator, you will need to create a project for the Transformation Advisor installation.

Create a project to install the instance

If you have already chosen to install the Transformation Advisor Operator to a specific namespace, then you will have already created the project, otherwise create it now as follows:

Creating the project can be done from the OpenShift UI:

  • Click the hamburger icon in the top left of the Red Hat OpenShift Container Platform dashboard.
  • Expand Home menu and select Projects.
  • Click Create Project button.
  • Name the project and click Create.

Alternatively, you can use the oc new-project NAMESPACE_PLACEHOLDER command from the command line.

You will need the name of the project during the installation.

You can now install the Transformation Advisor instance as a project admin user.

9. Create Transformation Advisor instance

IMPORTANT: Please read the Cluster Admin Tasks section carefully before proceeding to install.

Please substitute NAMESPACE_PLACEHOLDER for the actual name of the project you are working with.

Find the Transformation Advisor operator in the OpenShift UI in your created project to configure and create an instance of Transformation Advisor.

  • Click on Operators...Installed Operators
  • From Projects drop-down select NAMESPACE_PLACEHOLDER
  • Click on the Transformation Advisor operator
  • Click on the Create instance link in the Details tab, or click into the Transformation Advisor tab and click Create TransAdv.

Configuring the instance

  • You will need to read and accept the license terms on the create instance page before you will be allowed to proceed with the install of the instance.

  • The default configuration gives you most of what you need to install the product. Click the YAML View radio button to access the custom resource YAML. Update values in that YAML as required.

  • You will need to configure the persistence before proceeding with the install. This can be done from the UI form view, or the YAML view. Please see the Configure Storage document for full details, including examples, of the persistence configuration.

  • You may also need to add image pull secrets to access Transformation Advisor images in the entitled registry. See Create Entitlement Key and Planning section for more details on accessing images in the entitled registry.

See Configuration page for a full list of the configurations available in the custom resource YAML file.

  • When you are happy with your configuration, click Create.

Access the Transformation Advisor UI

By default, the Transformation Advisor operator exposes the UI as a Route on OpenShift. Go to Networking - Routes and click the location of the ui-route.

Validating a successful install

To validate the installation, on the OpenShift UI navigate to the pods for the projects where Transformation Advisor is installed. You should see the following fours pods in a READY and Running state:

ta-couchdb-0
ta-neo4j-0
ta-server-<ID>
ta-ui-<ID>

Additionally, you should see the instance pre-install job in a "Completed" state:

ta-operator-instance-preinstall-<ID>

If you have performed a single namespace install, then you will also see the operator pod in a READY and Running state:

ibm-transformation-advisor-manager-<ID>

Navigate to the Transformation Advisor UI as described here. Click on the kebab icon on the top right of the Transformation Advisor UI and then click on "What's New". Confirm the Transformation Advisor version in the What's New dialog.

Uninstalling Transformation Advisor

If you have installed Transformation Advisor using the Red Hat OpenShift UI, perform the following steps to completely remove the operator and instance. It is important not to attempt to delete the project before deleting the resources in the project.

  1. Uninstall the instance:

    1. Click on Operators...Installed Operators in the left navigation.
    2. In the main panel, select the project dropdown and choose the project where Transformation Advisor instance is installed
    3. Click on the operator, and then on the Transformation Advisor tab
    4. Click on the kebab button for the listed instance and select Delete Transadv
    5. In less than 2 minutes, the instance should disappear (the associated pods may take longer to terminate). If the instance is still visible after two minutes, first try refreshing the browser. If the instance is still shown, please perform the following oc command (replace the NAMESPACE_PLACEHOLDER with the name of the project the instance is installed into):
    oc patch transadvs.ta.ibm.com/ta -p '{"metadata":{"finalizers":[]}}' --type=merge -n NAMESPACE_PLACEHOLDER
    
  2. Uninstall the operator:

    1. Click on Operators...Installed Operators in the left navigation.
    2. In the main panel, select the project dropdown and choose the project where Transformation Advisor instance is installed
    3. Click on the kebab button for the listed operator and select Uninstall operator
    4. In less than 2 minutes, the operator should disappear (the associated pods may take longer to terminate). If the operator is still visible after two minutes, first try refreshing the browser. If the operator is still shown, please perform the following oc command:
    oc patch crd/transadvs.ta.ibm.com -p '{"metadata":{"finalizers":[]}}' --type=merge
    
  3. For a single namespace operator install, remove the manually created resources.

    1. Use the OpenShift UI (Click on Home...Search in the left navigation) to find and delete the following resources:
      1. ServiceAccount called ta-operator-sa
      2. OperatorGroup called ta-ownnamespace-operator-group
      3. Role called ibm-transformation-advisor
      4. RoleBinding called ibm-transformation-advisor
      5. ClusterRole called ibm-transformation-advisor
      6. ClusterRoleBinding called ibm-transformation-advisor
    2. Alternatively, you can delete these resources from the command line using the oc delete... command.
  4. Delete the project. It is recommended that you delete the project before attempting another install of Transformation Advisor

    1. Use the OpenShift UI (Click on Home...Projects) to delete the created Project

.