Troubleshooting installation problems

An unsuccessful Suite installation has many possible causes, such as missing or invalid installation parameters, boot node creation failures, or cluster creation problems.

Failure points

When you start a Suite installation on AWS, the CloudFormation stack template that you configured is used to create the stack. During this process, a boot node is created. The boot node completes the rest of the Suite installation.

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

A 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 boot node 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 boot node 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 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 OpenShift cluster, you must provide this parameter.
Existing OCP cluster details	Optional	Bootstrap process	If you want to reuse an existing 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 SLS instance, you must provide the following parameters: - `SLSEndpointUrl` - `SLSRegistrationKey` - `SLSPublicCertificateUrl`
Existing BAS details	Optional	Bootstrap process	If you want to reuse an existing BAS instance, you must provide the following parameters:: - `BASEndpointUrl` - `BASAPIKey` - `BASPublicCertificateUrl`

Unsupported AWS region

If you chose an unsupported region when you subscribed to the Suite in AWS 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 Suite installation process takes too long to create the network resources that the OpenShift cluster installer waits for, the cluster installer might time out. In this case, the 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 boot node 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 Suite.
	A resource quota is reached. For example, no more EIPs or NAT gateways can be created because their resource quotas are reached.	- Uninstall the Suite. - 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 Suite.
	The user has insufficient permissions to install the Suite.	- Uninstall the Suite. - Ensure that the IAM user who installs the Suite has the correct permissions. - Reinstall the Suite.
Failure in configuring OCP cluster.	The 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 boot node by using Secure Shell (SSH) and retrieve the `mas-provisioning.log` file from the `/root/mas-on-aws` directory. - Contact IBM Maximo Application Suite support.
Failure in creating Bastion host.	The bastion host is not created in the OpenShift cluster because of an error. For example, the bastion host creation fails because your AWS account reaches its service limits.	- Connect to the boot node by using Secure Shell (SSH) and retrieve the `mas-provisioning.log` file from the `/root/mas-on-aws` directory. - Contact IBM Maximo Application Suite support.
Failed in the Ansible playbook execution.	An error occurs when the boot node uses Ansible automation to deploy Suite prerequisites or the Suite itself in the OpenShift cluster.	- Connect to the boot node by using Secure Shell (SSH) and retrieve the `mas-provisioning.log` file from the `/root/mas-on-aws` directory. - Contact IBM Maximo Application Suite support.
This region is not supported for MAS deployment.	In the Suite's configuration page on AWS, in the Region field, you selected an unsupported region.	- Uninstall the Suite. - When you reinstall the Suite, in the configuration page, select a supported region. For the list of supported regions, see the installation considerations topic.
The provided ER key is not valid. It does not have access to download the MAS images.	The Suite images cannot be downloaded from the IBM Entitled Registry by using the key that was provided in the `EntitledRegistryKey` installation parameter.	- Uninstall the Suite. - Ensure that your ER key has the entitlement to download the Suite images from the registry. For example, in a Docker command shell, use the following commands to verify that you can manually download a Suite image: `docker login cp.icr.io -u cp -p <ER-key> docker pull cp.icr.io/cp/mas/admin-dashboard:5.1.27` - Reinstall the Suite.
Please provide OCP pull secret.	In the `OpenShiftPullSecret` installation parameter, the OpenShift pull secret is not provided.	- Uninstall the Suite. - When you reinstall the 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 Suite license file is not provided.	- Uninstall the Suite. - When you reinstall the Suite, provide the HTTP or S3 location of the 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.	- Uninstall the Suite. - When you reinstall the 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 BAS.	Invalid parameters are provided for an existing BAS instance.	- Uninstall the Suite. - When you reinstall the Suite, either provide all of the parameters for the `Existing BAS details` group or leave them all empty. If you leave all of these parameters empty, a new BAS instance is created in the cluster.
Please provide all the inputs to use existing OCP.	Invalid parameters are provided for an existing OpenShift cluster.	- Uninstall the Suite. - When you reinstall the 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 OpenShift cluster is created.
The provided Hosted zone is not a public hosted zone. Please provide a public hosted zone.	In the `PublicHostedZone` installation parameter, a private hosted zone is selected.	- Uninstall the Suite. - When you reinstall the Suite, select a public hosted zone in the `PublicHostedZone` installation parameter.
The JDBC details for MAS Manage are missing or invalid.	The Maximo Manage database configuration parameters are not provided, or the provided parameters are invalid.	- Uninstall the Suite. - 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 Suite.