Installer Life becomes easier — Maximo Application Suite
Installation guide
Before understanding the installation of Maximo Application Suite (MAS), it is necessary to mention what this product does, the underlying architecture of this product and installation skills.
MAS is like a toolbox organization platform for me, which contains a variety of application tools, such as asset management application tools, AI model application and management tools, IoT applications, scheduling application management, etc.
Maximo Application Suite is offered as a customer-managed product on Red Hat® OpenShift®, and also as an IBM Managed service. For more information, see IBM Maximo Application Suite on IBM.com
And we need to understand the underlying architecture of the MAS, which consists of several different components, such as MongoDB, Certificate Management, Behaviour Analytics Services, Suite License Service, etc.
Then let’s go to join the installer’s life journey:
I assume that your OCP cluster has already been created. And I suggest that you read this tab first, then proceed through the other tabs from left to right, skipping over any pre-requisite that you do not need, finishing with the core MAS install.
Apply Cluster on IBM cloud
Install MongoDB
Install Cert Management
Install Behaviour Analytics Services
Install Suite License Service
Install MAS CoreApply cluster on IBM cloud
The installation procedures vary a little between the different pre-requisites. I try to build an OpenShift cluster using IBM cloud services.
For some of the pre-requisites, the Operator you need is available via the OpenShift OpereratorHub catalog that is built into OpenShift.
The installation process starts with you installing the Operator from this catalog.
Before you can install MAS Core or some of its pre-requisites, you need an Entitlement key. Log in to the IBM Container Library with a user ID that has software download rights for your company’s Passport Advantage entitlement. Your entitlement key should be displayed on that page.
Install MongoDB
MAS uses MongoDB for configuration data and local user management. Your MongoDB instance can run in the OpenShift cluster or external to it.
The Community Edition operator is not currently available in the OperatorHub catalog, so you have to install it by running a script outside the cluster. Once you have installed the operator you need to create a cluster of MongoDB servers. We recommend a cluster of 3 servers.
The install script in those notes assumes that you have set a default the Storage Class, as it uses that when configuring MongoDB. Run this command before starting the install to make sure that you have an appropriate default Storage Class defined.
If you want to use a different storage provider replace ocs-storagecluster-ceph-rbd with an appropriate alternative.
You will need to choose an admin password of between 15 and 20 characters to be used when accessing the MongoDB database. Keep a note of this password as you will need it later. It needs to go at the end of the mas_v1_mongodbcommunity_openshift_cr.yaml file.
You will need to follow the workaround mentioned in the notes. The notes give instructions on how to do this using the OC command line, but you might find it easier to do some of them using the OCP console. For example, you can read and write the mas-mongo-ce-config secret in the UI without having to do base64 decode and encode.
#### Login openshift cluster
$ oc login xxxxxx#### install github-files-fetcher
$ sudo npm install -g github-files-fetcher#### fetch mongodb community edition
$ fetcher --url="https://github.com/ibm-watson-iot/iot-docs/tree/master/mongodb" .#### generate certs
$ cd mongodb && chmod -R +x * && cd certs
./generateSelfSignedCert.sh#### Prepare variables.
$ export MONGO_PASSWORD=<between 15 and 20 characters>
$ export MONGO_NAMESPACE=mongo
$ export MONGO_VERSION=4.2.6
$ export MONGODB_STORAGE_CLASS=<ocs-storagecluster-ceph-rbd>
$ cd .. && ./install-mongo-ce.sh
Install Certificate Management
Managing SSL certificates can be one of the more challenging aspects of operating a MAS cluster. In this section of the guide, we explain what these certificates are and what they are used for in MAS.
We explain how certificates are validated and how Trust Stores are used in MAS. We also look at how you can use the IBM Certificate Manager to create and renew the certificates that you need.
#### Create a new namespace called cert-manager
$ oc new-project cert-manager --display-name="CM" --description="Cert Manager"#### Install cert-manager
$ oc apply -f https://github.com/jetstack/cert-manager/releases/download/v1.2.0/cert-manager.yaml
Install Behaviour Analytics Services
The Behavior Analytics Services operator collects and processes Maximo Application Suite license and usage information.
It is required by MAS Core, so you need to install it regardless of which applications you intend to run.
Create a new OCP project called ibm-bas. You can do this by selecting “Home / Projects” from the navigation bar at the left and pressing the blue “Create Project” button at the top right.
Navigate to Operators / OperatorHub and search for the operator by typing Behavior into the search box:
#### "remember to replace your password"#### create database credential
$ oc create secret generic database-credentials -n ibm-bas --from-literal=db_username=basuser --from-literal=db_password=passw0rd#### create grafana credential
$ oc create secret generic grafana-credentials -n ibm-bas --from-literal=grafana_username=basuser --from-literal=grafana_password=passw0rd
Create a YAML file containing configuration for an AnalyticsProxy Custom Resource instance. Start with the values given here
cat <<EOF | oc create -f -
apiVersion: bas.ibm.com/v1
kind: AnalyticsProxy
metadata:
name: analyticsproxy
spec:
allowed_domains: "*"
db_archive:
frequency: '@monthly'
retention_age: 6
persistent_storage:
storage_class: ibmc-file-bronze
storage_size: 10G
airgapped:
enabled: 'false'
backup_deletion_frequency: '@daily'
backup_retention_period: 7
event_scheduler_frequency: '@hourly'
ibmproxyurl: 'https://iaps.ibm.com'
image_pull_secret: bas-images-pull-secret
postgres:
storage_class: ibmc-block-bronze
storage_size: 10G
kafka:
storage_class: ibmc-block-bronze
storage_size: 5G
zookeeper_storage_class: ibmc-block-bronze
zookeeper_storage_size: 5G
env_type: lite
EOFIf you are using a different storage provider you need to edit this YAML file to replace ocs-storagecluster-cephfs with a File System storage class from your storage provider and replace the three instances of ocs-storagecluster-ceph-rbd with a Block storage class.
$ oc create -f analytics-proxy.yaml -n ibm-bas
And then to create an API key use the OCP console as follows,
Press the blue“Create” button on the panel that displays next. That will create a new GenerateKey resource for you, with the default name (bas-api-key). This may take some time to complete.
Install Suite License Service
The Suite License Service (SLS) stores and manages the Maximo Application Suite license.
Each SLS instance has its own license key file, which gives it a pool of AppPoints that can be used for MAS. Each Maximo Application Suite instance can be connected to a unique SLS instance in which case each MAS instance has its own pool of AppPoints. Alternatively, you can configure two or more Maximo Application Suite instances so that they share an SLS and its corresponding license file. In the latter case, the AppPoints in that SLS instance can be checked out by either instance (but not both at the same time).
Navigate to the Operator from Operators/OperatorHub by typing Suite License Service into the search box and clicking on the relevant Operator tile:
Install the Operator by pressing the blue Install button. You can do this before you create the secrets mentioned in the instructions in the install panel. Make the following choices, including using the namespace ibm-sls, when prompted: Then press the blue Install button to start installing the operator.
Then some points to note while following these instructions:
- You should already have installed cert-manager by this point.
- You will need to get your IBM Entitlement key.
- You will need the MongoDB host names and credentials.
- There is no need to set the domain name or create a ca-keypair secret unless you want to access SLS from another OCP cluster.
#### export environment parameter
$ export ER_KEY=<your-er-key>
$ export MONGO_PASSWORD=<your-mongodb-password>#### create secret docker registry
$ oc -n ibm-sls create secret docker-registry ibm-entitlement \
--docker-server=cp.icr.io \
--docker-username=cp \
--docker-password=$ER_KEY
Create a YAML file sls-mongo-credentials.yaml containing the configuration for the MongoDB credential secret as described in the operator instructions.
apiVersion: v1
kind: Secret
type: Opaque
metadata:
name: sls-mongo-credentials
namespace: ibm-sls
stringData:
username: 'admin'
password: '${MONGO_PASSWORD}'Install MAS CoreApply sls-mongo-credentials.yaml
$ envsubst < sls-mongo-credentials.yaml | oc create -f -Create a local file called sls.yaml based on the CR template given in the operator instructions. You can use the simplified version given below, but you will need to update the mongo host names and you might need to change the storage class. If you are creating more than one SLS instance, you need to give them different names.
Identify your ROKS’ Ingress subdomain from the IBM Cloud dashboard.
Copy CA.pem from MongoDB’s cert’s directory.
Using VS Code’s File editor, open to edit sls.yaml file and insert the above-mentioned two values. Ensure columns are aligned for the certificate and the file is properly formatted. Create SLS CR.
Then apply the YAML file
$ oc create -f sls.yamlWait and watch for the License service to come up. Identify your LICENSED, REGISTRATION KEY and Identify SLS URL.
#### varifily licenses registration key
$ oc get -n ibm-sls licenseservice sls#### varifily licenses service url
$ oc get -n ibm-sls cm sls-suite-registration -o jsonpath=’{.data.url}’
Install MAS Core
Once you have installed the pre-requisites that you need, you can proceed to install and set up MAS. This is split into four stages:
- Installing the core MAS code for your instance
- Initial setup of your core MAS instance
- Additional configuration of your core MAS instance, including creating administrative users
- Installing and configuring the MAS applications that you wish to run.
The first stage, installing core MAS, is relatively straightforward.
Before you start you should make sure you have collected the connection details for the pre-requisites.
You will also need:
- The names that you have chosen for your MAS instance and your MAS domain.
- The Entitlement Key that you collected earlier.
- To run the installation script you will need a Linux or MacOS system on which to run the installation program.
- As with the pre-requisite installs this system needs to be running the OCP client and have access to the OCP cluster, but it also needs to have a Java Runtime available.
Unzip mas-core installer (downloaded via Passport Advantage)
https://www.ibm.com/software/passportadvantage/pao_customer.html
$ gunzip -c mas-installer-8.6.0.tgz | tar zxvf -$ cd ibm-mas
We include a summary of the installation steps here for convenience. Log in to the OpenShift CLI (oc login) in the usual way, and create an environment variable containing your Entitlement key using this command:
export ENTITLEMENT_KEY=<your_entitlement_key>./install-mas.sh -i mas-inst — domain mas-domain MyIngressSubDomain — accept-license
mas-inst must be replaced by the name you chose for the instance.
mas-domain must be replaced by the actual domain you wish to use.
The install process creates an OCP project (namespace) called mas-xxx-core where xxx is the instance name.
It may take several minutes for the installation to complete. If you want to see what is happening you can watch pods starting up in that project. The first one to appear should be the operator pod and this will start up the additional pods that makeup core MAS. Here is an example when two pods have initialized and a third is just starting.
You should see more pods appear over time, and the majority of them move to either Running or Completed state. However, there are seven that should remain in a pending state as shown here.
If the installation process is completed successfully you should see something like this
Note that in the actual output that you see mas-domain is replaced by the domain that you provided to the MAS install script.
Keep a safe and secure copy of the superuser credentials. You should never have to use them once you have configured a proper admin userid but they are your method of last resort to logging in to MAS should something go wrong.
The next topic I will cover is about setting up and configuring MAS core.
