Troubleshooting installation problems for Amazon Web Services

An unsuccessful Maximo® Application Suite installation has many possible causes, such as missing or invalid installation parameters, Bootnode creation failures, or cluster creation problems.

Failure points

When you start a Maximo Application Suite installation on Amazon Web Services, the CloudFormation stack template that you configured is used to create the stack. During this process, a Bootnode is created. The Bootnode completes the rest of the Maximo Application Suite installation.

To create the Red Hat® OpenShift® cluster, the Bootnode starts a bootstrap process. This process creates a bootstrap node that uses the Red Hat OpenShift installer to create master and worker nodes.

A Maximo Application Suite installation can fail at the following points:

  • The stack creation process. If the installation failed during this process, the following indicators apply:
    • The stack is not created.
    • The Bootnode is not created.
    • In the CloudFormation->Stacks page, the stack status is ROLLBACK_COMPLETE.
  • The bootstrap process. If the installation failed during this process, the following indicators apply:
    • The stack is created.
    • The Bootnode is created.
    • In the CloudFormation->Stacks page, the stack status is CREATE_COMPLETE.
    • In the Output tab, the DeploymentStatus parameter displays an installation failure message that indicates the cause of the failure, for example: ID-aws-small-NA:FAILURE#The provided ER key is not valid. It does not have access to download the MAS images

Common causes of failure

The installation might fail for one of the following reasons:

  • Mandatory installation parameters are missing or invalid optional parameters are specified.
  • An unsupported AWS region is selected.
  • The Red Hat OpenShift cluster installer times out after it waits for virtual infrastructure resources to be created.

Missing or invalid installation parameters

If you do not enter all of the mandatory parameters, the installation fails. In addition, for groups of optional parameters, such as the Maximo Manage database configuration parameters, you must either enter all of the group's parameters or leave all of them empty.

The following table indicates the failure points for missing mandatory parameters and invalid optional parameters.

Parameter/Group Mandatory/optional Failure point Further information
SSHKey Mandatory Stack creation process  
BootnodeSGIngressCidrIp Mandatory Stack creation process  
EntitledRegistryKey Mandatory Bootstrap process  
OpenShiftPullSecret Mandatory Bootstrap process  
MASLicenseUrl Mandatory Bootstrap process  
PublicHostedZone Optional Bootstrap process If you want to create a new Red Hat OpenShift cluster, you must provide this parameter.
Existing OCP cluster details Optional Bootstrap process If you want to reuse an existing Red Hat OpenShift cluster, you must provide the following parameters:
  • OpenshiftClusterApiUrl
  • OpenShiftUser
  • OpenShiftPassword
Maximo Manage database configuration details Optional Bootstrap process If you want the Maximo Manage application to use a preconfigured database, you must provide the following parameters: -
  • MASLicenseUrl
  • MASManageDBUser
  • MASManageDBPassword
  • MASManageDBJdbcUrl
  • MASManageDBCertificateUrl
Existing SLS details Optional Bootstrap process If you want to reuse an existing Suite License Service instance, you must provide the following parameters:
  • SLSEndpointUrl
  • SLSRegistrationKey
  • SLSPublicCertificateUrl
Existing IBM User Data Services details Optional Bootstrap process If you want to reuse an existing User Data Services instance, you must provide all three parameters. If only few are provided, the deployment will fail.
Important: Maximo Application Suite is configured with existing Suite License Service and consumes licenses configured with Suite License Service because the licensing is managed by Suite License Service.
Note: MASLicenseUrl is applicable for BYOL AWS product only.

Unsupported AWS region

If you chose an unsupported region when you subscribed to the Maximo Application Suite in Amazon Web Services Marketplace, the installation fails in the stack creation process. An error message is displayed in the CloudFormation template, such as the following message: Template error: Unable to get mapping for RegionMap::us-west-1::HVM64

Cluster installer timeout

If the Maximo Application Suite installation process takes too long to create the network resources that the Red Hat OpenShift cluster installer waits for, the cluster installer might time out. In this case, the Maximo Application Suite installation fails in the bootstrap process and the following error message is displayed in the CloudFormation stack console: Failure in creating OCP cluster.

Failure messages

If an installation fails in the bootstrap process, the failure message that is displayed in the CloudFormation->Stacks->Output page indicates the cause of the failure. Further details on failures and causes are available in the installation log file, which is mas-provisioning.log. You can retrieve this file in the following ways:

  • Connect to the Bootnode by using Secure Shell (SSH) and retrieve the file from the /root/mas-on-aws directory.
  • In the Amazon S3 service, connect to the <cluster-name>-bucket-<region> bucket and retrieve the file from the ocp-cluster-provisioning-deployment-context directory. For more information, see Buckets overview in the AWS documentation.

For information on installation failures, their possible causes, and the recommended next steps, see the following table:

Failure message Cause of failure Next steps
Failure in creating OCP cluster. The AWS resources that the cluster requires, such as subnets or NAT gateways, are not created. This issue is intermittent. Uninstall and then reinstall the Maximo Application Suite.
  A resource quota is reached. For example, no more EIPs or NAT gateways can be created because their resource quotas are reached. - Delete the Maximo Application Suite stack. - Increase the service quotas that apply to the resources or clean up the existing resources. For more information, see AWS service quotas in the AWS documentation. - In your AWS account, verify that similar resources are not used by an existing failed installation. - reinstall the Maximo Application Suite.
  The user has insufficient permissions to install the Maximo Application Suite. - Delete the Maximo Application Suite stack. - Ensure that the IAM user who installs the Maximo Application Suite has the correct permissions. - reinstall the Maximo Application Suite.
Failure in configuring OCP cluster. The Red Hat OpenShift cluster is not configured because of an error. For example, the cluster configuration fails because the IBM Operator Catalog cannot be accessed. - Connect to the Bootnode by using Secure Shell (SSH) and retrieve the `mas-provisioning.log` file from the `/root/mas-on-aws` directory. Or from the S3 bucket.-Contact IBM Support
Failure in creating Bastion host. The bastion host is not created in the Red Hat OpenShift cluster because of an error. For example, the bastion host creation fails because your AWS account reaches its service limits. - Connect to the Bootnode by using Secure Shell (SSH) and retrieve the `mas-provisioning.log` file from the `/root/mas-on-aws` directory. Or from the S3 bucket.- Contact IBM Maximo Application Suite support.
Failed in the Ansible playbook execution. An error occurs when the Bootnode uses Ansible automation to deploy Maximo Application Suite prerequisites or the Maximo Application Suite itself in the Red Hat OpenShift cluster. - Connect to the Bootnode by using Secure Shell (SSH) and retrieve the `mas-provisioning.log` file from the `/root/mas-on-aws` directory. Or from the S3 bucket. - Contact IBM Maximo Application Suite support
This region is not supported for MAS deployment. In the Maximo Application Suite configuration page on AWS, in the **Region** field, you selected an unsupported region. - Delete the Maximo Application Suite stack. - When you reinstall the Maximo Application Suite, in the configuration page, select a supported region. For the list of supported regions, see the Preparing to install Maximo Application Suite on Amazon Web Services topic.
The provided ER key is not valid. It does not have access to download the MAS images. The Maximo Application Suite images cannot be downloaded from the IBM Entitled Registry by using the key that was provided in the `EntitledRegistryKey` installation parameter. - Delete the Maximo Application Suite stack. - Ensure that your ER key has the entitlement to download the Maximo Application Suite images from the registry.

You can run a docker command to pull the image of the operator of the Maximo Application Suite version that you want to install to perform the testing.

For example, if you are willing to install Maximo Application Suite version 8.8.0, run the following docker commands:

docker login cp.icr.io -u cp - p <er-key>


docker pull icr.io/cpopen/ibm-mas:8.8.0
- Reinstall the Maximo Application Suite.
Please provide OCP pull secret. When you use the Red Hat OpenShift IPI or UPI option, if `OpenShiftPullSecret` installation parameter is not specified. - Delete the Maximo Application Suite stack. - When you reinstall the Maximo Application Suite, provide the pull secret in the `OpenShiftPullSecret` installation parameter.
Please provide a valid MAS license URL. In the MASLicenseUrl installation parameter, the HTTP or S3 location of the Maximo Application Suite license file is not provided. - Delete the Maximo Application Suite stack. - When you reinstall the Maximo Application Suite, provide the HTTP or S3 location of the Maximo Application Suite license file in the MASLicenseUrl installation parameter.
Please provide all the inputs to use existing SLS. Invalid parameters are provided for an existing SLS instance. - Delete the Maximo Application Suite stack. - When you reinstall the Maximo Application Suite, either provide all of the parameters for the `Existing SLS details` group or leave them all empty. If you leave all of these parameters empty, a new SLS instance is created in the cluster.
Please provide all the inputs to use existing OCP. Invalid parameters are provided for an existing Red Hat OpenShift cluster. - Delete the Maximo Application Suite stack. - When you reinstall the Maximo Application Suite, either provide all of the parameters for the Existing OCP cluster details group or leave them all empty. If you leave all of these parameters empty, a new Red Hat OpenShift cluster is created.
The provided Hosted zone is not a public hosted zone. Please provide a public hosted zone. When you use the Red Hat OpenShift IPI option, in the `PublicHostedZone` installation parameter, a private hosted zone is selected. - Delete the Maximo Application Suite stack. - When you reinstall the Maximo Application Suite, select a public hosted zone in the `PublicHostedZone` installation parameter.
The JDBC details for Maximo Manage are missing or invalid. The Maximo Manage database configuration parameters are not provided, or the provided parameters are invalid. - Delete the Maximo Application Suite stack. - Provide valid JDBC parameters to connect to the Maximo Manage database. By using a database connectivity tool, such as dbeaver, and your Maximo Manage database configuration credentials, verify that you can connect to the database. - reinstall the Maximo Application Suite.
Error occurs when running the uninstall script (cleanup-mas-deployment.sh), when ran using the following command:
./cleanup-mas-deployment -s <stack name> -r <region>
The error message displayed is:

...line 79: ${SUPPORTED_REGIONS,,}: bad substitution.
The installed bash version is shown after the required version. Update your bash version and try again.
Error occurs after shutting down the cluster within 24 hours of creation and then restarting after that time:Unable to connect to the server: EOF while oc login. Node certificate is expired on master nodes. Renew master node certificate. For more information, see https://access.redhat.com/solutions/5953441.
Note: The MAS License URL is applicable for BYOL AWS product only.