Creating a service instance for Planning Analytics programmatically

Information you need to complete this task

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

Version requirements

All of the components that are associated with an instance of IBM Software Hub must be installed or created at the same release. For example, if Planning Analytics is installed at Version 5.2.2, you must create the service instance at Version 5.2.2.

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:

You must have sufficient resources to provision and run the Planning Analytics service, as described by the following table.

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 IBM Software Hub web client.

      The display name is a string and can contain alphanumeric characters (a-z, A-Z, 0-9), dashes (-), and underscores (_).

   2. Set the INSTANCE_PROJECT to the project where you want to create the service instance:

      ---

      Create the service instance in the operands project

      export INSTANCE_PROJECT=${PROJECT_CPD_INST_OPERANDS}

      The command uses the PROJECT_CPD_INST_OPERANDS variable, which is already defined in your installation environment variables script.

      ---

      Create the service instance in a tethered project

      Important: If multiple tethered projects are associated with this instance of IBM Software Hub, make sure that the ${PROJECT_CPD_INSTANCE_TETHERED} environment variable is set to the correct project name before you run the export command:

      echo $PROJECT_CPD_INSTANCE_TETHERED

      export INSTANCE_PROJECT=${PROJECT_CPD_INSTANCE_TETHERED}

      ---

      Remember: You can create only one service instance in each project.
   3. Set the INSTANCE_VERSION environment variable to the version that corresponds to the version of IBM Software Hub on your cluster:

      export INSTANCE_VERSION=<version>

      Use the following table to determine the appropriate value:

      IBM Software Hub version	Service instance version
      5.2.2	5.2.2
      5.2.1	5.2.1
      5.2.0	5.2.0

   4. Set the INSTANCE_SIZE environment variable. The size determines the resources that are allocated to the service instance.

      export INSTANCE_SIZE=<size>

      Valid values are:

      • small_mincpureq
      • small
      • medium
      • large

      For more information about the resources associated with each size, see the component scaling guidance PDF, which you can download from the IBM Entitled Registry.

   5. Set the MYSQL_PV_SIZE environment variable.

      export MYSQL_PV_SIZE=<integer>

      Specify at least 5 GB. The recommended value is 20 GB. Specify the value as an integer. Omit the unit of measurement.
   6. Set the COUCHDB_PV_SIZE environment variable.

      export COUCHDB_PV_SIZE=<integer>

      Specify at least 5 GB. The recommended value is 20 GB. Specify the value as an integer. Omit the unit of measurement.
   7. Set the MONGODB_PV_SIZE environment variable.

      export MONGODB_PV_SIZE=<integer>

      Specify at least 5 GB. The recommended value is 20 GB. Specify the value as an integer. Omit the unit of measurement.
   8. Set the REDIS_PV_SIZE environment variable.

      export REDIS_PV_SIZE=<integer>

      Specify at least 5 GB. The recommended value is 20 GB. Specify the value as an integer. Omit the unit of measurement.
3. Create the planning-analytics-instance.json payload file.

   The command that you run depends on whether you want to use file storage for TM1 and Planning Analytics Workspace storage or whether you want to use block storage for Planning Analytics Workspace storage.

   ---

   Use only file storage

   cat << EOF > ./planning-analytics-instance.json
   {
       "addon_type":"pa",
       "addon_version":"${INSTANCE_VERSION}",
       "display_name":"${INSTANCE_NAME}",
       "namespace":"${INSTANCE_PROJECT}", 
       "create_arguments": {
           "description":"${INSTANCE_DESCRIPTION}",
           "metadata": {
               "addon_version":"${INSTANCE_VERSION}"
           },
           "resources":{},
           "parameters": {
               "paw_instance_name":"${INSTANCE_NAME}",
               "persistence.class":"${STG_CLASS_FILE}", 
               "persistence.mysqlSize":"${MYSQL_PV_SIZE}Gi",
               "persistence.couchdbSize":"${COUCHDB_PV_SIZE}Gi",
               "persistence.mongoSize":"${MONGODB_PV_SIZE}Gi",
               "persistence.redisSize":"${REDIS_PV_SIZE}Gi",
               "scaleConfig":"${INSTANCE_SIZE}",
               "common.tm1InternalType":true,
               "common.tm1Location":"http://pa-service-provider-api:1212",
               "tm1Service.storageClass":"${STG_CLASS_FILE}" 
           }
       },
       "transient_fields":{}
   }
   EOF

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

   • ${STG_CLASS_FILE}

   ---

   Use a combination of file and block storage

   cat << EOF > ./planning-analytics-instance.json
   {
       "addon_type":"pa",
       "addon_version":"${INSTANCE_VERSION}",
       "display_name":"${INSTANCE_NAME}",
       "namespace":"${INSTANCE_PROJECT}", 
       "create_arguments":{
           "description":"${INSTANCE_DESCRIPTION}",
           "metadata":{
               "addon_version":"${INSTANCE_VERSION}"
           },
           "resources":{},
           "parameters":{
               "paw_instance_name":"${INSTANCE_NAME}",
               "persistence.class":"${STG_CLASS_BLOCK}",
               "persistence.mysqlSize":"${MYSQL_PV_SIZE}Gi",
               "persistence.couchdbSize":"${COUCHDB_PV_SIZE}Gi",
               "persistence.mongoSize":"${MONGODB_PV_SIZE}Gi",
               "persistence.redisSize":"${REDIS_PV_SIZE}Gi",
               "scaleConfig":"${INSTANCE_SIZE}",
               "common.tm1InternalType":true,
               "common.tm1Location":"http://pa-service-provider-api:1212",
               "tm1Service.storageClass":"${STG_CLASS_FILE}"
           }
       },
       "transient_fields":{}
   }
   EOF

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

   • ${STG_CLASS_FILE}
   • ${STG_CLASS_BLOCK}

   ---

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. Set the environment variables that are used to connect to the instance of IBM Software Hub 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>

6. Create the service instance from the payload file.

   The command that you run depends on whether the instance of IBM Software Hub 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:

1. Set the INSTANCE_ID environment variable to the ID that was returned by the POST cURL command:

   export INSTANCE_ID=<ID-from-response>

2. Get the status of the service instance.

   The command that you run depends on whether the instance of IBM Software Hub 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

You must give users access to the service instance. For more information, see Adding users to Planning Analytics on IBM Software Hub.