MAS DevOps Ansible Collection Ansible CLI
Home Ansible Automation Platform OCP Install Cloud Pak For Data Install Core Add AIBroker Add IoT Add Manage Add Monitor Add Optimizer Add Predict Add Visual Inspection Update Upgrade Uninstall Core Backup & Restore ocp_cluster_monitoring ocp_config ocp_deprovision ocp_efs ocp_github_oauth ocp_login ocp_node_config ocp_provision ocp_roks_upgrade_registry_storage ocp_upgrade ocp_verify appconnect aws_bucket_access_point aws_documentdb_user aws_policy aws_route53 aws_user_creation aws_vpc cert_manager cis common-services configure_manage_eventstreams cos cos_bucket cp4d_admin_pwd_update cp4d cp4d_service db2 dro eck grafana ibm_catalogs kafka nvidia_gpu mongodb ocs sls turbonomic uds mirror_case_prepare mirror_extras_prepare mirror_images mirror_ocp ocp_idms ocp_simulate_disconnected_network registry suite_app_config suite_app_install suite_app_uninstall suite_app_upgrade suite_app_rollback suite_app_backup_restore suite_certs suite_config suite_db2_setup_for_manage suite_dns suite_install suite_manage_attachments_config suite_manage_birt_report_config suite_manage_bim_config suite_manage_customer_files_config suite_manage_imagestitching_config suite_manage_import_certs_config suite_manage_load_dbc_scripts suite_manage_logging_config suite_manage_pvc_config suite_uninstall suite_upgrade suite_rollback suite_verify suite_backup_restore ansible_version_check entitlement_key_rotation gencfg_jdbc gencfg_watsonstudio gencfg_workspace gencfg_mongo
Home Roles: Dependency Mgmt mongodb Prerequisites Role Variables - Common Role Variables - CE Operator Role Variables - IBM Cloud Role Variables - AWS DocumentDB AWS DocumentDB Secret Rotate role Variables AWS DocumentDB destroy-data action Variables Example Playbooks Troubleshooting License

mongodb¤

This role currently supports provisioning of mongodb in three different providers: - community - aws (documentdb) - ibm

If the selected provider is community then the MongoDB Community Kubernetes Operator will be configured and deployed into the specified namespace. By default a three member MongoDB replica set will be created. The cluster will bind six PVCs, these provide persistence for the data and system logs across the three nodes. Currently there is no support built-in for customizing the cluster beyond this configuration.

Tip

The role will generate a yaml file containing the definition of a Secret and MongoCfg resource that can be used to configure the deployed instance as the MAS system MongoDb.

This file can be directly applied using oc apply -f $MAS_CONFIG_DIR/mongocfg-mongoce-system.yaml or used in conjunction with the suite_config role.

Prerequisites¤

To run this role with providers as ibm or aws you must have already installed the AWS CLI. Also, you need to have AWS user credentials configured via aws configure command or simply export AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables with your corresponding AWS username credentials prior running this role when provider is either ibm or aws.

To run the docdb_secret_rotate MONGODB_ACTION when the provider is aws you must have already installed the Mongo Shell.

This role will install a GrafanaDashboard used for monitoring the MongoDB instance when the provided is community and you have run the grafana role previously. If you did not run the grafana role then the GrafanaDashboard won't be installed.

Role Variables - Common¤

mas_instance_id¤

The instance ID of Maximo Application Suite that the MongoCfg configuration will target. If this or mas_config_dir are not set then the role will not generate a MongoCfg template.

mas_config_dir¤

Local directory to save the generated MongoCfg resource definition. This can be used to manually configure a MAS instance to connect to the Mongo cluster, or used as an input to the suite_config role. If this or mas_instance_id are not set then the role will not generate a MongoCfg template.

mongodb_provider¤

MongoDB provider, choose whether to use the MongoDb Community Edition Operator (community), IBM Cloud Database for MongoDb (ibm), or AWS DocumentDb (aws).

mongodb_action¤

Determines which action to perform w.r.t mongodb for a specified provider:

Each provider supports a different set of actions: - community: install, uninstall, backup, restore - aws: install, uninstall, docdb_secret_rotate, destroy-data - ibm: install, uninstall, backup, restore, create-mongo-service-credentials

Role Variables - CE Operator¤

mongodb_namespace¤

The namespace where the operator and MongoDb cluster will be deployed.

mongodb_version¤

Defines the specific mongo version to be used. Best practice would be to use the version associated with the current Maximo Application Suite catalog. However, this value can currently be overridden to 4.4.21, 5.0.21, 5.0.23, 6.0.10, 6.0.12, 7.0.12

Important

It is advised to never attempt a downgrade a MongoDB instance managed by the MAS Devops Ansible Collection. Also best practices should include creating scheduled backups of any MongoDB instance.

mongodb_override_spec¤

This forces the deploy to use the environment variables instead of maintaining spec settings for the existing installed MongoDB. By default this is False and if you upgrade or reinstall Mongo your existing settings will be preserved.

Important

It is advised you check your existing Mongo installation before using this. If you do not set the environment variables to match what you have in the spec or you use defaults you may find your members, memory, and cpu reset to the default values specified in this README. Unknown settings are not preserved in the spec.

List of preserved settings

mongodb_storage_class¤

Required: The name of the storage class to configure the MongoDb operator to use for persistent storage in the MongoDb cluster. Storage class must support ReadWriteOnce(RWO) access mode.

mongodb_storage_capacity_data¤

The size of the PVC that will be created for data storage in the cluster.

mongodb_storage_capacity_logs¤

The size of the PVC that will be created for log storage in the cluster.

mongodb_cpu_limits¤

The CPU limits on the mongodb container.

mongodb_mem_limits¤

The Memory limits on the mongodb container.

mongodb_cpu_requests¤

The CPU requests on the mongodb container.

mongodb_mem_requests¤

The Memory requests on the mongodb container.

mongodb_replicas¤

The number of the mongodb replica set members. Default is 3. Set to 1 for SNO Cluster. - Environment Variable: MONGODB_REPLICAS - Default Value: 3

custom_labels¤

List of comma separated key=value pairs for setting custom labels on instance specific resources.

mongodb_v5_upgrade¤

Set this to true to confirm you want to upgrade your existing Mongo instance from version 4.2 or 4.4 to version 5.

mongodb_v6_upgrade¤

Set this to true to confirm you want to upgrade your existing Mongo instance from version 5 to version 6.

mongodb_v7_upgrade¤

Set this to true to confirm you want to upgrade your existing Mongo instance from version 6 to version 7.

masbr_confirm_cluster¤

Set true or false to indicate the role whether to confirm the currently connected cluster before running the backup or restore job.

masbr_copy_timeout_sec¤

Set the transfer files timeout in seconds.

masbr_job_timezone¤

Set the time zone for creating scheduled backup job. If not set a value for this variable, this role will use UTC time zone when creating a CronJob for running scheduled backup job.

masbr_storage_local_folder¤

Set local path to save the backup files.

masbr_backup_type¤

Set full or incr to indicate the role to create a full backup or incremental backup.

masbr_backup_from_version¤

Set the full backup version to use in the incremental backup, this will be in the format of a YYYMMDDHHMMSS timestamp (e.g. 20240621021316). This variable is only valid when MASBR_BACKUP_TYPE=incr. If not set a value for this variable, this role will try to find the latest full backup version from the specified storage location.

masbr_backup_schedule¤

Set Cron expression to create a scheduled backup. If not set a value for this varialbe, this role will create an on-demand backup.

masbr_restore_from_version¤

Set the backup version to use in the restore, this will be in the format of a YYYMMDDHHMMSS timestamp (e.g. 20240621021316)

Role Variables - IBM Cloud¤

ibm_mongo_name¤

Required. IBM Cloud Mongo database instance name.

ibm_mongo_admin_password¤

Optional. Sets IBM Cloud Mongo database administrator user password. If not set, an auto-generated 20 character length string will be used.

ibm_mongo_admin_credentials_secret_name¤

Secret for MongoDB Admin credentials.

ibm_mongo_service_credentials_secret_name¤

Secret for MongoDB Service credentials.

ibm_mongo_resourcegroup¤

Required.IBM Cloud Resource Group under which resource group will be created.

ibm_mongo_region¤

Required.IBM Cloud region where MongoDB resources will be created.

ibmcloud_apikey¤

Required.IBM Cloud API Key.

ibm_mongo_plan¤

Plan name for this IBMCloud Service.

ibm_mongo_service¤

IBMCloud Offering name for MongoDB Database

ibm_mongo_service_endpoints¤

MongoDB Service Endpoints type can be either public or private

ibm_mongo_version¤

Specify MongoDB version to be deployed

ibm_mongo_memory¤

Specify MongoDB Memory size

ibm_mongo_disk¤

Specify MongoDB Disk size

ibm_mongo_cpu¤

Specify MongoDB CPU

ibm_mongo_name¤

Resource Name in IBMCloud for MongoDB

ibm_mongo_backup_id¤

Required only if is_restore is True CRN ID for backup resource

is_restore¤

Whether want to restore from an existing backup resource or not.

restored_mongodb_service_name¤

Required only If is_restore is True.MongoDB Service Name

Role Variables - AWS DocumentDB¤

aws_access_key_id¤

Required.AWS Account Access Key Id

aws_secret_access_key¤

Required.AWS Account Secret Access Key

aws_region¤

Required.AWS Region where DocumentDB and other resources will be created

vpc_id¤

Required.AWS VPC ID under which documentdb,subnets and security group will be created

docdb_cluster_name¤

Required.DocumentDB Cluster Name

docdb_subnet_group_name¤

DocumentDB Subnet Group Name

docdb_security_group_name¤

DocumentDB Security Group Name

docdb_admin_credentials_secret_name¤

DocumentDB Admin Credentials Secret Name

docdb_engine_version¤

DocumentDB Engine version

docdb_master_username¤

DocumentDB master username

docdb_instance_class¤

DocumentDB Instance Class

docdb_instance_number¤

Number of instances required for DocumentDB

docdb_instance_identifier_prefix¤

Required. Prefix for DocumentDB Instance name

docdb_ingress_cidr¤

Required. IPv4 Address from which incoming connection requests will be allowed to DocumentDB cluster e.g Provide IPv4 CIDR address of VPC where ROSA cluster is installed

docdb_egress_cidr¤

Required. IPv4 Address at which outgoing connection requests will be allowed to DocumentDB cluster e.g Provide IPv4 CIDR address of VPC where ROSA cluster is installed

docdb_cidr_az1:¤

Required. Provide IPv4 CIDR address for the subnet to be created in one of the 3 availabilty zones of your VPC. If the subnet exists already then it must contain the tag of Name: {{ docdb_cluster_name }}, if the subnet doesn't exist already then one is created.

docdb_cidr_az2:¤

Required. Provide IPv4 CIDR address for the subnet to be created in one of the 3 availabilty zones of your VPC. If the subnet exists already then it must contain the tag of Name: {{ docdb_cluster_name }}, if the subnet doesn't exist already then one is created.

docdb_cidr_az3:¤

Required. Provide IPv4 CIDR address for the subnet to be created in one of the 3 availabilty zones of your VPC. If the subnet exists already then it must contain the tag of Name: {{ docdb_cluster_name }}, if the subnet doesn't exist already then one is created.

AWS DocumentDB Secret Rotate role Variables¤

docdb_mongo_instance_name¤

Required. DocumentDB Instance Name

docdb_host¤

Required. Any one Host Address out of multiple documentDB Instances

docdb_port¤

Required. Corresponding port address of DocumentDB Instance Host

docdb_instance_username¤

Required. Specify username for which password is being changed

docdb_instance_password_old¤

Required. Specify the old user password

docdb_master_password¤

Required. DocumentDB Master Username

docdb_master_username¤

Required. DocumentDB Master Password

AWS DocumentDB destroy-data action Variables¤

mas_instance_id¤

The specified MAS instance ID

mongo_username¤

Mongo Username

mongo_password¤

Mongo password

config¤

Mongo Config, please refer to the below example playbook section for details

certificates¤

Mongo Certificates, please refer to the below example playbook section for details

Example Playbooks¤

Install (CE Operator)¤

- hosts: localhost
  any_errors_fatal: true
  vars:
    mongodb_storage_class: ibmc-block-gold
    mas_instance_id: masinst1
    mas_config_dir: ~/masconfig
  roles:
    - ibm.mas_devops.mongodb

Backup (CE Operator)¤

- hosts: localhost
  any_errors_fatal: true
  vars:
    mongodb_action: backup
    mas_instance_id: masinst1
    masbr_storage_local_folder: /tmp/masbr
  roles:
    - ibm.mas_devops.mongodb

Restore (CE Operator)¤

- hosts: localhost
  any_errors_fatal: true
  vars:
    mongodb_action: restore
    mas_instance_id: masinst1
    masbr_restore_from_version: 20240621021316
    masbr_storage_local_folder: /tmp/masbr
  roles:
    - ibm.mas_devops.mongodb

Install (IBM Cloud)¤

- hosts: localhost
  any_errors_fatal: true
  vars:
    mas_instance_id: masinst1
    mas_config_dir: ~/masconfig
    mongodb_provider: ibm
    ibmcloud_apikey: apikey****
    ibmcloud_resource_group: mas-test
  roles:
    - ibm.mas_devops.mongodb

Install (AWS DocumentDB)¤

- hosts: localhost
  any_errors_fatal: true
  vars:
    mas_instance_id: masinst1
    mas_config_dir: ~/masconfig
    mongodb_provider: aws
    mongodb_action: provision
    docdb_size: ~/docdb-config.yml
    docdb_cluster_name: test-db
    docdb_ingress_cidr: 10.0.0.0/16
    docdb_egress_cidr: 10.0.0.0/16
    docdb_cidr_az1: 10.0.0.0/26
    docdb_cidr_az2: 10.0.0.64/26
    docdb_cidr_az3: 10.0.0.128/26
    docdb_instance_identifier_prefix: test-db-instance
    vpc_id: test-vpc-id
    aws_access_key_id: aws-key
    aws_secret_access_key: aws-access-key

  roles:
    - ibm.mas_devops.mongodb

AWS DocumentDb Secret Rotation¤

- hosts: localhost
  any_errors_fatal: true
  vars:
    mas_instance_id: masinst1
    mas_config_dir: ~/masconfig
    mongodb_provider: aws
    mongodb_action: docdb_secret_rotate
    docdb_mongo_instance_name: test-db-instance
    db_host: aws.test1.host7283-*****
    db_port: 27017
    docdb_master_username: admin
    docdb_master_password: pass***
    docdb_instance_password_old: oldpass****
    docdb_instance_username: testuser
    aws_access_key_id: aws-key
    aws_secret_access_key: aws-access-key

  roles:
    - ibm.mas_devops.mongodb

AWS DocumentDb destroy-data action¤

- hosts: localhost
  any_errors_fatal: true
  vars:
    mas_instance_id: masinst1
    mongodb_provider: aws
    mongodb_action: destroy-data
    mongo_username: pqradmin
    mongo_password: xyzabc
    config:
      configDb: admin
      authMechanism: DEFAULT
      retryWrites: false
      hosts:
        - host: abc-0.pqr.databases.appdomain.cloud
          port: 32250
        - host: abc-1.pqr.databases.appdomain.cloud
          port: 32250
        - host: abc-2.pqr.databases.appdomain.cloud
          port: 32250
    certificates:
      - alias: ca
        crt: |
          -----BEGIN CERTIFICATE-----
          MIIDDzCCAfegAwIBAgIJANEH58y2/kzHMA0GCSqGSIb3DQEBCwUAMB4xHDAaBgNV
          BAMME0lCTSBDbG91ZCBEYXRhYmFzZXMwHhcNMTgwNjI1MTQyOTAwWhcNMjgwNjIy
          MTQyOTAwWjAeMRwwGgYDVQQDDBNJQk0gQ2xvdWQgRGF0YWJhc2VzMIIBIjANBgkq
          1eKI2FLzYKpoKBe5rcnrM7nHgNc/nCdEs5JecHb1dHv1QfPm6pzIxwIDAQABo1Aw
          TjAdBgNVHQ4EFgQUK3+XZo1wyKs+DEoYXbHruwSpXjgwHwYDVR0jBBgwFoAUK3+X
          Zo1wyKs+DEoYXbHruwSpXjgwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQsFAAOC
          doqqgGIZ2nxCkp5/FXxF/TMb55vteTQwfgBy60jVVkbF7eVOWCv0KaNHPF5hrqbN
          i+3XjJ7/peF3xMvTMoy35DcT3E2ZeSVjouZs15O90kI3k2daS2OHJABW0vSj4nLz
          +PQzp/B9cQmOO8dCe049Q3oaUA==
          -----END CERTIFICATE-----
  roles:
    - ibm.mas_devops.mongodb

Troubleshooting¤

Important

Please be cautious while performing any of the troubleshooting steps outlined below. It is important to understand that the MongoDB Community operator persists data within Persistent Volume Claims. These claims should not be removed inadvertent deletion of the mongoce namespace could result in data loss.

MongoDB Replica Set Pods Will Not Start¤

MongoDB 5 has introduced new platform specific requirements. Please consult the Platform Support Notes for detailed information.

It is of particular importance to confirm that the AVX instruction set is exposed or available to the MongoDB workloads. This can easily be determined by entering any running pod on the same OpenShift cluster where MongoDB replica set members are failing to start. Once inside of a running pod the following command can be executed to confirm if the AVX instruction set is available:

cat /proc/cpuinfo | grep flags | grep avx

If avx is not found in the available flags then either the physical processor hosting the OpenShift cluster does not provide the AVX instruction set or the virtual host configuration is not exposing the AVX instruction set. If the latter is suspected the virtual hosting documentation should be referenced for details on how to expose the AVX instruction set.

LDAP Authentication¤

If authenticating via LDAP with PLAIN specified for authMechanism then configDb must be set to $external in the MongoCfg. The field configDb in the MongoCfg refers to the authentication database.

CA Certificate Renewal¤

Warning

If the MongoDB CA Certificate expires the MongoDB replica set will become unusable. Replica set members will not be able to communicate with each other and client applications (i.e. Maximo Application Suite components) will not be to connect.

In order to renew the CA Certificate used by the MongoDB replica set the following steps must be taken:

The following steps illustrate the process required to renew the CA Certificate, sever certificate and reconfigure the MongoDB replica set with the new CA and server certificates.

The first step is to stop the Mongo replica set and MongoDb CE Operator pod.

oc project mongoce
oc delete deployment mongodb-kubernetes-operator

Important

Make sure the MongoDB Community operator pod has terminated before proceeding.

oc delete statefulset mas-mongo-ce

Important

Make sure all pods in the mongoce namespace have terminated before proceeding

Remove expired CA Certificate and Server Certificate resources. Clean up MongoDB Community configuration and then run the mongodb role.

oc delete certificate mongo-ca-crt
oc delete certificate mongo-server
oc delete secret mongo-ca-secret
oc delete secret mongo-server-cert

oc delete secret mas-mongo-ce-config
oc delete configmap  mas-mongo-ce-cert-map
oc delete secret mas-mongo-ce-server-certificate-key

export ROLE_NAME=mongodb
ansible-playbook ibm.mas_devops.run_role

Once the mongodb role has completed the MongoDb CE Operator pod and Mongo replica set should be configured.

After the CA and server Certificates have been renewed you must ensure that that MongoCfg Suite CR is updated with the new CA Certificate. First obtain the CA Certificate from the Secret resource mongo-ca-secret. Then edit the Suite MongoCfg CR in the Maximo Application Suite core namespace. This is done by updating the appropriate certificate under .spec.certificates in the MongoCfg CR:

  spec:
    certificates:
    - alias: ca
      crt: |
        -----BEGIN CERTIFICATE-----

        -----END CERTIFICATE-----

If an IBM Suite Licensing Service (SLS) is also connecting to the MongoDB replica set the LicenseService CR must also be updated to reflect the new MongoDB CA. This can be added to the .spec.mongo.certificates section of the LicenseService CR.

    mongo:
      certificates:
      - alias: mongoca
        crt: |
          -----BEGIN CERTIFICATE-----

          -----END CERTIFICATE-----

Once the CA certificate has been updated for the MongoCfg and LicenseService CRs several pods in the core and SLS namespaces might need to be restarted to pick up the changes. This would include but is not limited to coreidp, coreapi, api-licensing.

License¤

EPL-2.0