Creating a service instance for MongoDB 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 uses a different version number from Cloud Pak for Data. This topic includes a table that shows the MongoDB 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:

Procedure

Complete the following tasks to create a service instance:

1. Creating a service instance
2. Validating that the service instance was created
3. What to do next

Creating a service instance

To create a service instance:

1. Change to the directory on your workstation where you want to create the JSON file that defines the service instance payload.
2. Set the environment variables that are used to populate the JSON payload for the service instance:
   1. Set the INSTANCE_NAME environment variable to the unique name that you want to use as the display name for the service instance:

      export INSTANCE_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 INSTANCE_DESCRIPTION environment variable to the description that you want to use for the service instance:

      export INSTANCE_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 INSTANCE_VERSION environment variable to a version that corresponds to the version of Cloud Pak for Data on your cluster:

      export INSTANCE_VERSION=<version>

      Use the following table to determine the available options:

      Cloud Pak for Data version	Service instance versions (Pick one)
      5.0.3	6.0.16-ent, 7.0.12-ent
      5.0.2	6.0.15-ent, 7.0.11-ent
      5.0.1	6.0.15-ent, 7.0.11-ent
      5.0.0	5.0.23-ent, 6.0.12-ent

   4. Set the OPS_MGR_NAME environment variable to the name of an existing MongoDB Ops Manager instance that will manage the database.
      Tip: If you created the Ops Manager instance prior to creating the service instance, you might already have this environment variable set. Run the following command to see if the variable is set in your current command-line session:

      echo ${OPS_MANAGER_NAME}

      export OPS_MGR_NAME=<name>

   5. Set the OPS_MGR_VERSION environment variable to the version of the MongoDB Ops Manager instance that will manage the database.
      Tip: If you created the Ops Manager instance prior to creating the service instance, you might already have this environment variable set. Run the following command to see if the variable is set in your current command-line session:

      echo ${OPS_MANAGER_VERSION}

      export OPS_MGR_VERSION=<version>

   6. Set the AUTO_DELETE_RESOURCES environment variable based on whether the Ops Manager will automatically delete the resources associated with this instance when you delete a MongoDB service 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.
   7. Set the INSTANCE_REPLICAS environment variable to the number of replicas of the database to create:

      export INSTANCE_REPLICAS=<integer>

      Specify an integer between 1 and 50. Specify 2 or more replicas for high availability. The recommended value is 3.

   8. Set the REPLICA_CPU environment variable based on the number of CPU you want to allocate to each replica:

      export REPLICA_CPU=<integer>

      Specify an integer between 1 and 16.

   9. Set the REPLICA_MEMORY environment variable based on the amount of memory you want to allocate to each replica:

      export REPLICA_MEMORY=<integer>

      Specify an integer between 1 and 64.

   10. Set the STORAGE_SIZE environment variable based on the amount of data you plan to store in the database:

       export STORAGE_SIZE=<integer>

       Specify an integer between 1 and 1000.

   11. Set the STORAGE_UNIT environment variable:

       export STORAGE_UNIT=<unit>

       Specify Gi for gibibytes, Ti for tebibytes, or Pi for pebibytes.

3. Create the mongodb-cpd-instance.json payload file:

   cat << EOF > ./mongodb-cpd-instance.jsoncat << EOF > ./mongodb-cp4d-instance.json
   {
       "addon_type": "mongodb",
       "display_name": "${INSTANCE_NAME}",
       "namespace": "${PROJECT_CPD_INST_OPERANDS}",
       "addon_version": "${INSTANCE_VERSION}",
       "create_arguments": {
           "description": "${INSTANCE_DESCRIPTION}",
           "parameters": {
               "opsmanager": "${OPS_MGR_NAME}",
               "opsmgrversion": "${OPS_MGR_VERSION}",
               "mgrforcedeleteresources": "${AUTO_DELETE_RESOURCES}",
               "mdbversion": "${INSTANCE_VERSION}",
               "numberofnodes": "${INSTANCE_REPLICAS}",
               "corespernode": "${REPLICA_CPU}",
               "memorypernode": "${REPLICA_MEMORY}",
               "sstorageclass": "${STG_CLASS_FILE}",
               "ssize": "${STORAGE_SIZE}",
               "sunit": "${STORAGE_UNIT}"
           }
       }
   }
   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}
4. 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>

5. Create the service instance from the payload file:

   cpd-cli service-instance create \
   --profile=${CPD_PROFILE_NAME} \
   --from-source=${PAYLOAD_FILE}

Validating that the service instance was created

To validate that the service instance was created, run the following command:

cpd-cli service-instance status ${INSTANCE_NAME} \
--profile=${CPD_PROFILE_NAME} \
--output=json

• If the command returns PROVISIONED, the service instance was successfully created.
• If the command returns PROVISION_IN_PROGRESS, wait a few minutes and run the command again.
• If the command returns FAILED, review the pod logs for the zen-core-api and zen-watcher pods for possible causes.

What to do next

MongoDB is ready to use. To get started with MongoDB, see Administering the MongoDB service and Working with MongoDB databases.