Installing IBM Application Modernization Accelerator

Install Red Hat OpenShift Container Platform

Configure Storage

Add the IBM operator catalog

See the Adding the IBM operator catalog documentation.

Choose installation mode

Application Modernization Accelerator supports two installation modes:

• All namespaces on the cluster (default) Operator will be available in all Namespaces.

• A specific namespace on the cluster 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.

All-namespaces versus namespaced

An all-namespaces AMA operator installation allows for multiple AMA instances, each accessible through a unique URL. However, this approach might compromise security and make management more complex due to shared namespaces.

A namespaced installation, on the other hand, offers enhanced security and isolation by segregating AMA instances into individual namespaces. This can be especially beneficial in environments with restricted permissions to the openshift-operators namespace.

The optimal approach depends on your specific requirements and security considerations. If you need strict isolation and fine-grained control, a namespaced installation is recommended. For simpler setups with fewer security concerns, an all-namespaces installation might suffice.

In general, here are the benefits of the two approaches:

All-Namespaces Install:
Benefits of an All-Namespaces Install:

- Broader Cluster Integration: In an all-namespaces install, the OpenShift components are deployed across multiple namespaces, which can provide better integration with other applications and services running on the same cluster.
- Simplified Deployment: The all-namespaces approach can be simpler to set up, as it does not require the same level of namespace-specific configuration and resource management.
- Shared Resource Utilization: With an all-namespaces install, the OpenShift components can share resources more freely across the entire cluster, potentially resulting in more efficient resource utilization.
- Easier Cluster-wide Management: From an administrative perspective, managing the OpenShift components in an all-namespaces install may be more straightforward, as they are integrated into the broader cluster.

Namespaced Install:
Benefits of a Namespaced Install:

- Isolation and Scoping: In a namespaced install, the OpenShift components are installed within a specific namespace, which helps isolate them from other applications or services running on the same cluster. This provides better security and resource management, as the OpenShift components are confined to their own namespace.
- Reduced Resource Consumption: Since the OpenShift components are confined to a specific namespace, they only consume resources within that namespace, which can be more efficient compared to an all-namespaces installation.
- Customization and Flexibility: With a namespaced install, you have more flexibility to customize the installation, configure resources, and manage the OpenShift components independently from the rest of the cluster.
- Easier Maintenance and Upgrades: Performing upgrades or maintenance tasks on the OpenShift components is generally simpler and more manageable in a namespaced install, as the changes are scoped to a specific namespace.
 

Perform cluster administration tasks

Cluster Administration Tasks for an All Namespaces Operator 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 a file, replace NAMESPACE_PLACEHOLDER with the project you are installing to, and create the resources using the oc apply -f <filename> command.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: ibm-app-mod-accelerator-NAMESPACE_PLACEHOLDER
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",  "clusterversions"]
    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-app-mod-accelerator-NAMESPACE_PLACEHOLDER
subjects:
  - kind: ServiceAccount
    name: ama-operator-sa
    namespace: NAMESPACE_PLACEHOLDER
roleRef:
  kind: ClusterRole
  name: ibm-app-mod-accelerator-NAMESPACE_PLACEHOLDER
  apiGroup: rbac.authorization.k8s.io

Install Operator

Install the operator using the Red Hat OpenShift UI

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

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

Create an 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 Application Modernization Accelerator instance in step 9. For more information, see Configuration.

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 Application Modernization Accelerator 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 Application Modernization Accelerator instance configuration (for more information, see Configuration. In this case, the value you use for the properties does not have to exist as a secret.

Perform Cluster Administration Tasks for Instance Installation

Before installing the Application Modernization Accelerator instance, as cluster administrator, you will need to create a project for the Application Modernization Accelerator installation.

Create a project to install the instance

If you have already chosen to install the Application Modernization Accelerator 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 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 Application Modernization Accelerator instance as a project admin user.

Create Application Modernization Accelerator instance

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

Find the Application Modernization Accelerator operator in the OpenShift UI in your created project to configure and create an instance of Application Modernization Accelerator.

• Click on Operators...Installed Operators
• From Projects drop-down select NAMESPACE_PLACEHOLDER
• Click on the Application Modernization Accelerator operator
• Click on the Create instance link in the Details tab, or click into the Application Modernization Accelerator tab and click Create AppMod.

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. 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 Application Modernization Accelerator images in the entitled registry. See Create entitlement key and Planning section for more details on accessing images in the entitled registry. Add 'imagePullSecret: ibm-entitlement-key' to all four Application Modernization Accelerator images, and click the Configuration page link.

For a full list of the configurations available in the custom resource YAML file, see the Configuration page.

When you are happy with your configuration, click Create.

Manually configuring the instance

When ClusterRole creation is not possible, the operator cannot preconfigure the product instance. Complete the following manual steps to configure the product instance.

Create AppMod Instance via YAML View

In the Create AppMod page, switch to YAML view and configure the following parameters:

• Set clusterScoped: enabled: false (required)
• Set license: accept: true (required)
• Set persistence: enabled: false (for simplicity)
• Set egress: enabled: false (for simplicity)

Placeholder Replacements

• Replace AMA_PLACEHOLDER_SERVER_PUBLIC_URL with: https://$ama_app_sub_domain

  Use the following logic to determine ama_app_sub_domain:

  cluster_domain=$(oc get ingresses.config.openshift.io cluster -o jsonpath='{.spec.domain}')
  if [[ $cluster_domain == apps.* ]]; then
    ama_app_sub_domain="ama.$cluster_domain"
  else
    ama_app_sub_domain="ama-apps.$cluster_domain"
  fi

• Replace AMA_PLACEHOLDER_HOST_NAME with: $ama_app_sub_domain
• Replace AMA_PLACEHOLDER_API_ENDPOINT with the output of:

  cluster_api_endpoint_url=$(oc get infrastructure.config.openshift.io cluster --output=jsonpath='{.status.apiServerURL}')

• Replace AMA_PLACEHOLDER_AUTH_ISSUER_ENDPOINT with the output of:

  $(wget -q -O- --no-check-certificate ${cluster_api_endpoint_url}/.well-known/oauth-authorization-server | jq '.issuer' | sed 's/"//g')

• Replace AMA_PLACEHOLDER_CLUSTER_ID with the output of:

  $(oc get clusterversion version -o jsonpath='{.spec.clusterID}')

• Set AMA_PLACEHOLDER_ROUTER_DESTINATION_CA_CERT to: "" (empty string)

Click Create to proceed with the instance installation.

Once the instance installation begins, create the OAuthClient. The OAuthClient uses keys from the app-mod-accelerator-secret that is created during instance installation, so the OAuthClient cannot be created earlier.

Set <NAMESPACE>, <RELEASE_NAME>, and <AMA_APP_SUB_DOMAIN>, then create the OAuthClient using the following script:

namespace=<NAMESPACE>
release_name=<RELEASE_NAME>
ama_app_sub_domain=<AMA_APP_SUB_DOMAIN>
secret_name=app-mod-accelerator-secret
route_enabled=true
route_hostname=$release_name-$namespace-$ama_app_sub_domain
nodeport_routernodeip=__AMA_PLACEHOLDER_ROUTER_IP__
nodeport_uiport=__AMA_PLACEHOLDER_UI_NODE_PORT__
tls_enabled=true
oauth_name=$release_name-oauth
chart_identifier=ibm-appmod-dev-5.0.0

oc project $namespace

secret_json=$(oc get secret $secret_name -o json)
CLIENT_ID=$(echo $secret_json | jq '.data | .["clientId"]' | tr -d '"' | base64 -d)
CLIENT_SECRET=$(echo $secret_json | jq '.data | .["clientSecret"]' | tr -d '"' | base64 -d)

echo CLIENT_ID: $CLIENT_ID
echo CLIENT_SECRET: $CLIENT_SECRET

redirect_uri=""
if [[ $route_enabled == "true" ]]; then
  redirect_uri="https://$route_hostname/auth/callback"
else
  if [[ $tls_enabled == "true" ]]; then
    redirect_uri="https://${nodeport_routernodeip}:${nodeport_uiport}"
  else
    redirect_uri="http://${nodeport_routernodeip}:${nodeport_uiport}"
  fi
fi

echo redirect_uri: $redirect_uri

cat <<EOF | oc apply -f -
apiVersion: oauth.openshift.io/v1
kind: OAuthClient
metadata:
  name: $CLIENT_ID
  labels:
    app.kubernetes.io/name: $oauth_name
    app.kubernetes.io/instance: "$release_name"
    app.kubernetes.io/managed-by: "ibm-app-mod-accelerator-manager"
    release: $release_name
    helm.sh/chart: $chart_identifier
secret: $CLIENT_SECRET
redirectURIs:
- "$redirect_uri"
grantMethod: auto
EOF

Access the Application Modernization Accelerator UI

By default, the Application Modernization Accelerator 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 Application Modernization Accelerator is installed. You should see the following four pods in a READY and Running state:

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

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

ama-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-app-mod-accelerator-manager-<ID>
 

For more information, see Access the Application Modernization Accelerator UI. Click on the kebab icon (⋮) on the Application Modernization Accelerator UI and then click on What's New. Confirm the Application Modernization Accelerator version in the What's New dialog.

Uninstalling Application Modernization Accelerator

If you have installed Application Modernization Accelerator 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 Application Modernization Accelerator instance is installed.

   3. Click on the operator, and then on the Application Modernization Accelerator tab.

   4. Click on the kebab button for the listed instance and select Delete AppMod.

   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 appmods.ama.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 Application Modernization Accelerator 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/appmods.ama.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 ama-operator-sa

      2. OperatorGroup called ama-ownnamespace-operator-group

      3. Role called ibm-app-mod-accelerator

      4. RoleBinding called ibm-app-mod-accelerator

      5. ClusterRole called ibm-app-mod-accelerator

      6. ClusterRoleBinding called ibm-app-mod-accelerator

   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 Application Modernization Accelerator.

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