Maximo Application Suite Ansible collection examples

You can use Ansible collections to install Maximo® Application Suite, its applications and prerequisites, and complete other related tasks. Review the examples to learn how to run the ansible roles and playbooks.

For more information, see Ansible DevOps documentation.

You can run Ansible playbooks and roles in two ways:
  • Install prerequisite software and ensure it is available on your workstation. For more information, see MAS DevOps Ansible Collection.
  • Use a Docker container that contains everything you need. For more information, see Docker container.

    Ensure that Docker is installed on your workstation.

The following examples use the Maximo Application Suite DevOps Docker container to run roles and playbooks. You set values for environment variables, then run the corresponding role or playbook.

Running the role to install the IBM Certificate Manager

  1. In your local machine with Docker installed, run this command to pull the image and initiate the Docker container:
    
docker run -ti --rm --pull always quay.io/ibmmas/cli
    Tip: Use the --pull always command to pull the newest image.
    Note: The --rm command ensures that the container is removed after you run the command. However, running the --rm command is optional.

    For more information, see ibmmas/cli.

  1. In the command line inside the container, you can run the following commands:
    1. Run the oc login command. You can access your Red Hat® OpenShift® cluster by using the oc command directly from a terminal in the client machine oc was installed to.
      1. Go to the Red Hat OpenShift web console.
      2. Click your login name and select the option: Copy login command.
      3. Click View token.
      4. Copy the entire command line under the Log in section with this token and paste in the command line, running it from inside the docker container.
    2. Export the environment variable used by the script. In the example, IBM® Certificate Manager is installed.
      
export MAS_CHANNEL=8.8.x
    3. Run the cert_manager role.
      
ROLE_NAME=cert_manager ansible-playbook ibm.mas_devops.run_role

After several minutes, IBM Certificate Manager is installed.

Running a playbook to provision an IBM Cloud Red Hat OpenShift cluster

This example shows how to run a playbook to provision an IBM Cloud® Red Hat OpenShift cluster.

Note: This example shows a playbook that just runs one role. The playbook sets the environment variables and the specific role. You might do the same using the steps that are shown in the previous example. But an advantage of playbooks is that you can run more than one role and also set the variables for all them as needed in the same file. In other words, the playbook is usually used to orchestrate an execution of a set of roles.

For example, a playbook can install Maximo Application Suite and perform more configurations after it is installed. For more information, see suite_install.

  1. In your local machine with Docker installed, run this command to pull the image and initiate the Docker container:
    
docker run -ti --rm --pull always quay.io/ibmmas/cli
  2. In the command line inside the Docker container, run the following commands:
    1. Update ibmcloud cli, including plug-ins, to the newest version.
      
curl -sL https://raw.githubusercontent.com/IBM-Cloud/ibm-cloud-developer-tools/master/linux-installer/idt-installer | bash 
    2. Now, export environment variables necessary to provision your IBM Cloud Red Hat OpenShift cluster.
      Note: For more information about variables to customize your IBM Cloud Red Hat OpenShift cluster, see Role Variables - ROKS.
    3. Export your IBM Cloud API Key. 
      
export IBMCLOUD_APIKEY=<your IBM Cloud API Key>
      Note: To create a key, see Creating your IBM Cloud API key
    4. Export the name of your cluster.
      
export CLUSTER_NAME=<my own cluster>
    5. Run the command to run the playbook:
      
ansible-playbook ibm.mas_devops.ocp_roks_provision.yml
  3. The IBM Cloud cluster is provisioned after some time.

Customizing a playbook to run existent roles

In this example, customize a playbook to run a set of roles. The playbook installs IBM catalog, IBM Cloud Pak® for Data, and IBM User Data Services, which is a Maximo Application Suite prerequisite.

To perform the task, the playbook sets the variables and runs the specific roles to install each one of them.

  1. In your local machine with Docker installed, run this command to pull the image and initiate the Docker container:
    
docker run -ti --rm --pull always quay.io/ibmmas/cli
  2. In the command line inside the container, you can run the following commands:
    1. Run the oc login command. You can access your Red Hat OpenShift cluster by using the oc command directly from a terminal in the client machine oc was installed to.
      1. Go to the Red Hat OpenShift web console.
      2. Click your login name and select the option: Copy login command.
      3. Click View token.
      4. Copy the entire command line under the Log in section with this token and paste in the command line, running it from inside the docker container.
  3. Create a custom_dro_playbook.yaml file with the following content. (You can use an editor such as vi and insert the following sample code.) 
    
...
    - hosts: localhost
      any_errors_fatal: true
      vars:
        dro_contact:
          email: "{{ lookup('env', 'DRO_CONTACT_EMAIL') }}"
          first_name: "{{ lookup('env', 'DRO_CONTACT_FIRSTNAME') }}"
          last_name: "{{ lookup('env', 'DRO_CONTACT_LASTNAME') }}"
      roles:
        # 1. Install DRO
        — ibm.mas_devops.ibm_catalogs
        — ibm.mas_devops.common_services
        — ibm.mas_devops.dro
  4. Export the required environment variables to install Data Reporter Operator .
    
export DRO_CONTACT_EMAIL=john.doe@test.com

    
export DRO_CONTACT_FIRSTNAME=John

    
export DRO_CONTACT_LASTNAME=Doe
  5. Run the playbook with the following command:
    
ansible-playbook custom_dro_playbook.yaml
  6. Data Reporter Operator was installed along with its prerequisites.

Installing on nonproduction environment

This example describes how to install the IBM Maximo Application Suite in production or nonproduction environment by using the mas_annotations role. The mas_annotations is an optional variable, which accepts a comma separated list of annotations that need to be added to the Maximo Application Suite CR.

  1. In your local machine with Docker installed, run a command to pull the image and initiate the Docker container:
    
docker run -ti --rm --pull always quay.io/ibmmas/cli
  2. In the command line, inside the Docker container, run the following command to deploy the Maximo Application Suite in nonproduction mode for development and testing deployment.

    Set environment variable MAS_ANNOTATIONS for nonproduction mode:

    export MAS_ANNOTATIONS=mas.ibm.com/operationalMode=nonproduction
  3. Run the following command to install the Maximo Application Suite: 
    ...
- hosts: localhost
  any_errors_fatal: true
  vars:
    mas_instance_id: "inst1"
    mas_config_dir: "/home/david/masconfig"
    mas_entitlement_key: "{{ lookup('env', 'IBM_ENTITLEMENT_KEY') }}"
    mas_annotations: "mas.ibm.com/operationalMode=nonproduction"

  roles:
    — ibm.mas_devops.suite_install
    — ibm.mas_devops.suite_config
    — ibm.mas_devops.suite_verify