Creating a service instance for Cognos Analytics programmatically

After you install Cognos Analytics, you must create at least one Cognos Analytics service instance. Each service instance must be in a different Red Hat® OpenShift® Container Platform project. You can create a service instance in the operands project or in a project that is tethered to 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

Information you need to complete this task

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

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 Cognos Analytics is installed at Version 5.0.3, you must create the service instance at Version 5.0.3.

Important: Cognos Analytics uses a different version number from Cloud Pak for Data. This topic includes a table that shows the Cognos Analytics 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
Cognos Analytics is installed. If this task is not complete, see Installing Cognos Analytics.
The cpd-cli command-line interface is installed on the workstation from which you will create the service instance. If this task is not complete, see Setting up a client workstation.
You generated an API key or authorization token

The API key or token 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 authorization token or API key.
The content store is configured. You can also use the content store for your audit content.
Important: When you provision your instance, you must use the same IAM mode as your content store.
If this task is not complete, see Configuring the content store for Cognos Analytics.

You must have sufficient resources for the plan size that you select. If you do not have sufficient resources, the instance cannot be created.

Use the following table to determine which size plan to use when you create the instance. The information in the table represents the total resources that are required by all of the pods that comprise the Cognos Analytics instance. The resources can be distributed across the nodes in your cluster. However, the nodes must have sufficient capacity to run the pods.
Note: The memory and storage requirements are provided in both Gi and GB. The values in GB are rounded up to the next whole number.
Plan size Minimum required resources Maximum required resources Largest pod
Fixed Minimum Across the cluster, you must have at least:
  • Cores: 10
  • Memory: 40 Gi (Approximately 42 GB)
  • Storage: 2.2 Gi (Approximately 2.4 GB)
  • Ephemeral Storage: 22 Gi (Approximately 24 GB)
At most, the instance uses:
  • Cores: 10
  • Memory: 40 Gi (Approximately 42 GB)
  • Storage: 2.2 Gi (Approximately 2.4 GB)
  • Ephemeral Storage: 22 Gi (Approximately 24 GB)
The largest pod requires up to:
  • Cores: 2.6
  • Memory: 13 Gi (Approximately 14 GB)
XSmall Across the cluster, you must have at least:
  • Cores: 9.4
  • Memory: 38.5 Gi (Approximately 41 GB)
  • Storage: 2.2 Gi (Approximately 2.4 GB)
  • Ephemeral Storage: 20.1 Gi (Approximately 21.6 GB)
At most, the instance uses:
  • Cores: 16
  • Memory: 72.9 Gi (Approximately 78 GB)
  • Storage: 2.2 Gi (Approximately 2.4 GB)
  • Ephemeral Storage: 37.2 Gi (Approximately 39.9 GB)
The largest pod requires up to:
  • Cores: 2.6
  • Memory: 13 Gi (Approximately 14 GB)
Small or Small with minimal reserved CPU resources Across the cluster, you must have at least:
  • Cores: 9.4
  • Memory: 40.5 Gi (Approximately 43 GB)
  • Storage: 2.2 Gi (Approximately 2.4 GB)
  • Ephemeral Storage: 21.6 Gi (Approximately 23 GB)
At most, the instance uses:
  • Cores: 16
  • Memory: 76.9 Gi (Approximately 82.5 GB)
  • Storage: 2.2 Gi (Approximately 2.4 GB)
  • Ephemeral Storage: 37.2 Gi (Approximately 39.9 GB)
The largest pod requires up to:
  • Cores: 2.6
  • Memory: 13 Gi (Approximately 14 GB)
Medium Across the cluster, you must have at least:
  • Cores: 24
  • Memory: 76.9 Gi (Approximately 82.5 GB)
  • Storage: 4.2 Gi (Approximately 4.5 GB)
  • Ephemeral Storage: 21.6 Gi (Approximately 23 GB)
At most, the instance uses:
  • Cores: 31.4
  • Memory: 101 Gi (Approximately 108 GB)
  • Storage: 4.2 Gi (Approximately 4.5 GB)
  • Ephemeral Storage: 47.6 Gi (Approximately 51 GB)
The largest pod requires up to:
  • Cores: 3.6
  • Memory: 13 Gi (Approximately 14 GB)
Large Across the cluster, you must have at least:
  • Cores: 30
  • Memory: 77 Gi (Approximately 82.6 GB)
  • Storage: 8.2 Gi (Approximately 8.8 GB)
  • Ephemeral Storage: 57 Gi (Approximately 61 GB)
At most, the instance uses:
  • Cores: 53
  • Memory: 137.6 Gi (Approximately 147 GB)
  • Storage: 8.2 Gi (Approximately 8.8 GB)
  • Ephemeral Storage: 103 Gi (Approximately 110 GB)
The largest pod requires up to:
  • Cores: 4.6
  • Memory: 13 Gi (Approximately 14 GB)

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 alphanumeric characters (a-z, A-Z, 0-9), spaces ( ), dashes (-), underscores (_), and periods (.). Make sure that you surround the display name with quotation marks, as shown in the preceding export command.

    2. Set the INSTANCE_VERSION environment variable to the 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 appropriate value:

      Cloud Pak for Data version Service instance version
      5.0.3 26.3.0
      5.0.2 26.2.0
      5.0.1 26.1.0
      5.0.0 26.0.0
    3. 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 Cloud Pak for Data, 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.
    4. 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.

    5. Set the CONTENT_STORE_CONNECTION_NAME environment variable to the name of the platform connection that you created to connect to the content store for the service instance.
      export CONTENT_STORE_CONNECTION_NAME=<connection-display-name>
    6. Set the AUDIT_DB_CONNECTION_NAME environment variable to the name of the platform connection that you created to connect to the audit database for the service instance.
      export AUDIT_DB_CONNECTION_NAME=<connection-display-name>
    7. 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
      • fixedminimum
      • xsmall
      • 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.

    8. Set the FIPS_MODE and FIPS_MODE_LABEL environment variables based on whether FIPS is enabled on the cluster:
      • If FIPS is not enabled on the cluster, set:
        export FIPS_MODE=""
        export FIPS_MODE_LABEL=""
      • If FIPS is enabled on the cluster, set:
        export FIPS_MODE=FIPS_140
        export FIPS_MODE_LABEL="FIPS 140-2"
  3. Create the cognos-analytics-instance.json payload file:
    cat << EOF > ./cognos-analytics-instance.json
    {
        "addon_type": "cognos-analytics-app",
        "display_name": "${INSTANCE_NAME}",
        "addon_version": "${INSTANCE_VERSION}",
        "namespace": "${INSTANCE_PROJECT}", 
        "create_arguments": {
            "deployment_id": "",
            "parameters": {
                "global.cp4dWebUrlBase": "https://${CPD_ROUTE}", 
                "global.icp4Data": "true",
                "global.tls.enabled": "false", 
                "global.icp4DataVersion": "${INSTANCE_VERSION}",
                "global.cs.databaseExternal": "true",
                "global.cs.databaseConnectionName": "${CONTENT_STORE_CONNECTION_NAME}",
                "global.audit.databaseExternal": "true", 
                "global.audit.databaseConnectionName": "${AUDIT_DB_CONNECTION_NAME}",
                "pvc.pvProvisioning": "NamedStorageClass",
                "pvc.storageClassName": "${STG_CLASS_FILE}",
                "pvc.blockStorageClassName": "${STG_CLASS_BLOCK}",
                "metadata.planSize": "${INSTANCE_SIZE}",
                "metadata.storageType": "storage-class",
                "metadata.storageClass": "${STG_CLASS_FILE}",
                "metadata.cryptoConformanceLabel": "${FIPS_MODE_LABEL}",
                "metadata.cryptoConformance": "${FIPS_MODE}",
                "metadata.autoScaleConfig": "true"
            }
        }
    }
    EOF
    The following environment variables use the values that are already defined in your installation environment variables script:
    • ${STG_CLASS_BLOCK}
    • ${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. 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 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 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:

  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. Run the following command to get the status of the service instance:
    curl --request GET \ 
      --url "https://${CPD_ROUTE}/zen-data/v3/service_instances/${INSTANCE_ID}" \ 
      --header "Authorization: ZenApiKey ${AUTH_TOKEN}" \ 
      --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 RUNNING, 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 ibm-cognos-addon-sp-deployment-*, ibm-ca-operator-controller-manager-*, 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

Important: Limit user access to the content store. See Updating the security settings.
You must give users access to the service instance. For more information, see Managing users (Cognos Analytics).