Creating a service instance for MongoDB Ops Manager programmatically

After you install MongoDB, you must create at least one MongoDB Ops Manager service instance in the operands project. If you are a Cloud Pak for Data user, you can use the /v3/service_instances REST API call to programmatically create service instances.

Who needs to complete this task?: To create a service instance programmatically by using the /v3/service_instances REST API call, you must have the Create service instances (can_provision) permission in Cloud Pak for Data.

When do you need to complete this task?

Complete this task only if you want to create a service instance programmatically by using the /v3/service_instances REST API call.

Alternative methods for creating a service instance

From the web client. For more information, see Creating a service instance for MongoDB Ops Manager from the web client.
By using the cpd-cli service-instance create command. For more information, see Creating a service instance for MongoDB Ops Manager with the cpd-cli service-instance create command.

Information you need to complete this task

Review the following information before you create a service instance for MongoDB:

Version requirements: All of the components that are associated with an instance of Cloud Pak for Data must be installed or created at the same release. For example, if MongoDB is installed at Version 5.0.3, you must create the service instance at Version 5.0.3.

Important: MongoDB Ops Manager uses a different version number from Cloud Pak for Data. This topic includes a table that shows the MongoDB Ops Manager version for each refresh of Cloud Pak for Data. Use this table to find the correct version based on the version of Cloud Pak for Data that is installed.

Environment variables

The commands in this task use environment variables so that you can run the commands exactly as written.

If you don't have the script that defines the environment variables, see Setting up installation environment variables.
To use the environment variables from the script, you must source the environment variables before you run the commands in this task. For example, run:
```
source ./cpd_vars.sh
```

Before you begin

This task assumes that the following prerequisites are met:

Prerequisite	Where to find more information
MongoDB is installed.	If this task is not complete, see Installing MongoDB.
You generated an API key. The API key must be associated with a user who has the Create service instances (`can_provision`) permission in Cloud Pak for Data.	If this task is not complete, see Generating an API key.

Procedure

Complete the following tasks to create a service instance:

Creating a service instance

To create a service instance:

Change to the directory on your workstation where you want to create the JSON file that defines the service instance payload.
Set the environment variables that are used to populate the JSON payload for the MongoDB Ops Manager.
1. Set the OPS_MGR_NAME environment variable to the unique name that you want to use as the display name for the Ops Manager:
```
export OPS_MGR_NAME="<display-name>"
```
  This name is displayed on the Instances page of the Cloud Pak for Data web client.
  
  The display name is a string and can contain only lowercase alphanumeric characters (a-z, 0-9), dashes (-), and periods (.).
  
  The display name must start and end with an alphanumeric character.
2. Set the OPS_MGR_DESCRIPTION environment variable to the description that you want to use for the Ops Manager:
```
export OPS_MGR_DESCRIPTION="<description>"
```
  This description is displayed on the Instances page of the Cloud Pak for Data web client.
  
  The description is a string and can contain alphanumeric characters, spaces, dashes, underscores, and periods. Make sure that you surround the display name with quotation marks, as shown in the preceding export command.
3. Set the OPS_MGR_VERSION environment variable to the version that corresponds to the version of Cloud Pak for Data on your cluster:
```
export OPS_MGR_VERSION=<version>
```
  Use the following table to determine the appropriate value:
  
  Cloud Pak for Data version Ops Manager version
  
  5.0.3 7.0.9
  
  5.0.2 7.0.7
  
  5.0.1 7.0.7
  
  5.0.0 6.0.22
4. Set the OPS_MGR_USERNAME environment variable to the name that you want to use to access the Ops Manager:
```
export OPS_MGR_USERNAME=<username>
```
5. Set the OPS_MGR_PASSWORD environment variable to the password that you want to use to access the Ops Manager:
```
export OPS_MGR_PASSWORD=<password>
```
  The password must be at least 8 characters long and contain at least one letter, one number, and one special character.
6. Set the OPS_MGR_ON_DEDICATED environment variable based on whether you want to deploy the Ops Manager on a dedicated nodes:
```
export MGR_ON_DEDICATED=<boolean>
```
  - Specify true to run the Ops Manager on dedicated nodes.
  - Specify false to run the Ops Manager on nodes where other pods are running.
  For more information, see Setting up dedicated notes for your MongoDB deployment.
7. Set the AUTO_DELETE_RESOURCES environment variable based on whether you want to automatically delete the persistent volume claims (PVCs) and secrets that are associated with the Ops Manager when you delete an Ops Manager instance.
```
export AUTO_DELETE_RESOURCES=<boolean>
```
  - Specify true to automatically delete the resources when you delete a service instance.
    Important: Deletion is permanent. The data in the PVCs and secrets cannot be recovered.
  - Specify false to preserve the resources when you delete a service instance.
8. Set the MD_INSTANCE_REPLICAS environment variable to the number of replicas of the Ops Manager metadata to create:
```
export MD_INSTANCE_REPLICAS=<integer>
```
  Specify an integer between 1 and 50. Specify 2 or more replicas for high availability. The recommended value is 3.
9. Set the MD_REPLICA_CPU environment variable based on the number of CPU you want to allocate to each Ops Manager metadata replica:
```
export MD_REPLICA_CPU=<integer>
```
  Specify an integer between 1 and 16.
10. Set the MD_REPLICA_MEMORY environment variable based on the amount of memory you want to allocate to each Ops Manager metadata replica:
```
export MD_REPLICA_MEMORY=<integer>
```
  Specify an integer between 1 and 64.
11. Set the MD_STORAGE_SIZE environment variable based on the amount of metadata you plan to store, including backups:
```
export MD_STORAGE_SIZE=<integer>
```
  Specify an integer between 1 and 300.
12. Set the MD_STORAGE_UNIT environment variable:
```
export MD_STORAGE_UNIT=<unit>
```
  Specify Gi for gibibytes, Ti for tebibytes, or Pi for pebibytes.
13. Set the MGR_INSTANCE_REPLICAS environment variable to the number of replicas of the Ops Manager to create:
```
export MGR_INSTANCE_REPLICAS=<integer>
```
  Specify an integer between 1 and 50. Specify 2 or more replicas for high availability. The recommended value is 3.
14. Set the MGR_REPLICA_CPU environment variable based on the number of CPU you want to allocate to each Ops Manager replica:
```
export MGR_REPLICA_CPU=<integer>
```
  Specify an integer between 1 and 16.
15. Set the MGR_REPLICA_MEMORY environment variable based on the amount of memory you want to allocate to each Ops Manager replica:
```
export MGR_REPLICA_MEMORY=<integer>
```
  Specify an integer between 1 and 64.
16. Set the MGR_STORAGE_SIZE environment variable based on the number of databases that you plan to manage from this instance of the Ops Manager:
```
export MGR_STORAGE_SIZE=<integer>
```
  Specify an integer between 1 and 1000.
17. Set the MGR_STORAGE_UNIT environment variable:
```
export MD_STORAGE_UNIT=<unit>
```
  Specify Gi for gibibytes, Ti for tebibytes, or Pi for pebibytes.

Cloud Pak for Data version	Ops Manager version
5.0.3	7.0.9
5.0.2	7.0.7
5.0.1	7.0.7
5.0.0	6.0.22

Create the mongodb-ops-mgr.json payload file:

cat << EOF > ./mongodb-ops-mgr.json
{
    "addon_type": "opsmanager",
    "display_name": "${OPS_MGR_NAME}",
    "namespace": "${PROJECT_CPD_INST_OPERANDS}",
    "addon_version": "${OPS_MGR_VERSION}",
    "create_arguments": {
        "description": "${OPS_MGR_DESCRIPTION}",
         "metadata":{
           "opsusername":"${OPS_MGR_USERNAME}",
           "opspassword":"${OPS_MGR_PASSWORD}"
         },
     "parameters": {
       "mgrapplyondedicated": "${OPS_MGR_ON_DEDICATED}",
       "mgrforcedeleteresources": "${AUTO_DELETE_RESOURCES}",
       "mdnumberofnodes": "${MD_INSTANCE_REPLICAS}",
       "mdcorespernode": "${MD_REPLICA_CPU}",
       "mdmemorypernode": "${MD_REPLICA_MEMORY}",
       "mdsize": "${MD_STORAGE_SIZE}",
       "mdunit": "${MD_STORAGE_UNIT}",
       "mdstorageclass": "${STG_CLASS_FILE}",
       "mgrnumberofnodes": "${MGR_INSTANCE_REPLICAS}",
       "mgrcorespernode": "${MGR_REPLICA_CPU}",
       "mgrmemorypernode": "${MGR_REPLICA_MEMORY}",
       "mgrsize": "${MGR_STORAGE_SIZE}",
       "mgrunit": "${MGR_STORAGE_UNIT}",
       "mgrstorageclass": "${STG_CLASS_FILE}"
       "mgrversion": "${OPS_MGR_VERSION}",
    }
  }
}
EOF

The following environment variables use the values that are already defined in your installation environment variables script:

${PROJECT_CPD_INST_OPERANDS}
${STG_CLASS_FILE}

Set the PAYLOAD_FILE environment variable to the fully qualified name of the JSON payload file on your workstation:
```
export PAYLOAD_FILE=<fully-qualified-JSON-file-name>
```
Set the environment variables that are used to connect to the instance of Cloud Pak for Data where you want to create the service instance:
1. Set the CPD_ROUTE environment variable:
```
export CPD_ROUTE=$(oc get route cpd -n ${PROJECT_CPD_INST_OPERANDS} -o jsonpath={".spec.host"})
```
  The command uses the PROJECT_CPD_INST_OPERANDS variable, which is already defined in your installation environment variables script.
2. Set the API_KEY environment variable to the API key that you created:
```
export API_KEY=<your_api_key>
```
Create the service instance from the payload file.
The command that you run depends on whether the instance of Cloud Pak for Data where you want to create the service instance uses a self-signed certificate or a certificate signed by a trusted certificate authority.
The instance uses a certificate signed by a trusted certificate authority
```
curl --request POST \
--url "https://${CPD_ROUTE}/zen-data/v3/service_instances" \
--header "Authorization: ZenApiKey ${API_KEY}" \
--header 'Content-Type: application/json' \
--data @${PAYLOAD_FILE}
```
The instance uses a self-signed certificate (default)
```
curl -k --request POST \
--url "https://${CPD_ROUTE}/zen-data/v3/service_instances" \
--header "Authorization: ZenApiKey ${API_KEY}" \
--header 'Content-Type: application/json' \
--data @${PAYLOAD_FILE}
```
If the request was successful, the command returns one of the following HTTP response codes:
- 200 - The request was successfully completed and the service instance was provisioned.
- 202 - The request was successfully submitted. The service instance is being provisioned.
If the request was not successful, use the HTTP response code to determine the reason.

Validating that the service instance was created

To validate that the service instance was created:

Set the INSTANCE_ID environment variable to the ID that was returned by the POST cURL command:
```
export INSTANCE_ID=<ID-from-response>
```
Get the status of the service instance.
The command that you run depends on whether the instance of Cloud Pak for Data where you want to create the service instance uses a self-signed certificate or a certificate signed by a trusted certificate authority.
The instance uses a certificate signed by a trusted certificate authority
```
curl --request GET \
  --url "https://${CPD_ROUTE}/zen-data/v3/service_instances/${INSTANCE_ID}" \
  --header "Authorization: ZenApiKey ${API_KEY}" \
  --header 'Content-Type: application/json'
```
The instance uses a self-signed certificate (default)
```
curl -k --request GET \
  --url "https://${CPD_ROUTE}/zen-data/v3/service_instances/${INSTANCE_ID}" \
  --header "Authorization: ZenApiKey ${API_KEY}" \
  --header 'Content-Type: application/json'
```
- If the request was successful, the command returns the following HTTP response code: 200
  Find the provision_status parameter in the JSON response.
  - If the value is PROVISIONED, the service instance was successfully created.
  - If the value is PROVISION_IN_PROGRESS, wait a few minutes and run the command again.
  - If the value is FAILED, review the pod logs for the zen-core-api and zen-watcher pods for possible causes.
- If the request was not successful, use the HTTP response code to determine the reason.

What to do next

After you provision the MongoDB Ops Manager, you can deploy one or more MongoDB database instances. For more information, see Creating a service instance for MongoDB programmatically.