Creating a service instance for OpenPages programmatically

After you install OpenPages, you must create at least one OpenPages 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 IBM® Software Hub 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 IBM Software Hub.

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 OpenPages from the web client.
By using the cpd-cli service-instance create command. For more information, see Creating a service instance for OpenPages 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 OpenPages:

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

Important: OpenPages uses a different version number from IBM Software Hub. This topic includes a table that shows the OpenPages version for each refresh of IBM Software Hub. Use this table to find the correct version based on the version of IBM Software Hub 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
OpenPages is installed.	If this task is not complete, see Installing OpenPages.
You generated an API key. The API key must be associated with a user who has the Create service instances (`can_provision`) permission in IBM Software Hub.	If this task is not complete, see Generating an API authorization token.
If you're using an embedded Db2 database and you want to run Db2 with limited privileges, configure Db2.	See Specifying the privileges that Db2U runs with.
If your deployment is using an external database, ensure that the database is ready.	See the following tasks. Setting up an external Db2 database for OpenPages Setting up an external Oracle database for OpenPages
Ensure that you have the information that you need from your cluster administrator.	See Preparing to provision an OpenPages instance.
If you want to integrate OpenPages with Cognos Analytics, ensure that the Cognos Analytics instance is provisioned and running. Note: During the provisioning process for OpenPages, Cognos Analytics will be restarted.	Creating a service instance for Cognos Analytics

Procedure

Complete the following tasks to create a service instance:

Creating a service instance
Validating that the service instance was created
What to do next

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 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), 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 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 9.5.2
  
  5.2.1 9.5.1
  
  5.2.0 9.5.0
3. 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
  - 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.
4. Set the GLOBAL_SEARCH environment variable based on whether you want to integrate the service instance with global search.
  Global search uses advanced text processing techniques and analysis to search across all object types to find records relevant to your search terms.
```
export GLOBAL_SEARCH=<boolean>
```
  - Specify true to integrate the service instance with global search.
  - Specify false if you don't want to integrate the service instance global search.
5. Set the COGNOS_INTEGRATION environment variable based on whether you want to integrate the service instance with the Cognos Analytics service:
```
export COGNOS_INTEGRATION=<boolean>
```
  - Specify true to integrate the service instance with Cognos Analytics.
  - Specify false if you don't want to integrate the service instance with Cognos Analytics.
6. Specify the appropriate environment variables based on whether you will use an external database or an automatically provisioned database:
  Use an external database
  1. Set the DATABASE_PROVIDER environment variable to the appropriate value based on the type of database you are connecting to:
    
    Db2
    
    export DATABASE_PROVIDER=Db2
    
    Oracle
    
    export DATABASE_PROVIDER=Oracle
  2. Set the DATABASE_SECRET_NAME environment variable to the name of the secret that contains the database credentials:
    export DATABASE_SECRET_NAME=<secret_name>
  3. Set the INSTANCE_PROJECT environment variable 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}
    
    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.
  Use an automatically provisioned database
  1. Set the DEDICATED_NODE environment variable based on whether you want to run the database on a dedicated node.
    export DEDICATED_NODE=<boolean>
    
    Specify true to run the database on a dedicated node.
    
    Specify false to run the database on a node where other pods are running.
  2. Set the NODE_LABEL environment variable with the appropriate value for your environment:
    
    If you set the NODE_LABEL environment variable to false, set:
    export NODE_LABEL=""
    
    If you set the NODE_LABEL environment variable to true but you don't use node labels, set:
    export NODE_LABEL=""
    The database will run on any available node.
    
    If you set the NODE_LABEL environment variable to true and you want to run the database on a specific node, set:
    export NODE_LABEL=<node-label>
    If there are multiple nodes with the same label, the database will run on one of the nodes with the specified label.
  3. Set the RESTRICTED_V2_SCC environment variable based on whether you want to run the automatically provisioned database with the restricted-v2 security context constraint (SCC).
    
    To use the restricted-v2 SCC, set:
    export RESTRICTED_V2_SCC=true
    Important: This option is available only if you are creating the service instance in a tethered project and the cluster administrator added the required annotations to the project.
    If you have access to the cluster, you can check the annotations on the tethered project by running:
    oc describe project ${INSTANCE_PROJECT}
    
    The project must have the following annotations:
    
    openshift.io/sa.scc.supplemental-groups=1001000000/10000 openshift.io/sa.scc.uid-range=1001000000/10000 openshift.io/sa.scc.mcs=s0:c27,c512
    
    To use the default SCC, set:
    export RESTRICTED_V2_SCC=false

IBM Software Hub version	Service instance version
5.2.2	9.5.2
5.2.1	9.5.1
5.2.0	9.5.0

Create the openpages-instance.json payload file.

The command that you run depends on whether you want to use an external database or an internal database.

Use an external database

cat << EOF > ./openpages-instance.json
{
    "display_name": "${INSTANCE_NAME}",
    "namespace": "${INSTANCE_PROJECT}",
    "addon_version": "${INSTANCE_VERSION}",
    "addon_type": "openpages",
    "create_arguments": {
        "metadata": {
            "databaseType": "external",
            "database": "${DATABASE_PROVIDER}",
            "dbSecretName": "${DATABASE_SECRET_NAME}",
            "blockStorageClass": "",
            "fileStorageClass": "${STG_CLASS_FILE}",
            "enableGlobalSearch": ${GLOBAL_SEARCH},
            "enableIntegrationWithCognos": ${COGNOS_INTEGRATION}, 
            "scaleConfig": "${INSTANCE_SIZE}"
        }
    },
}
EOF

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

${STG_CLASS_FILE}

Use an automatically provisioned, integrated database

Run the appropriate command based on the type of storage on your cluster.

All storage except Portworx

cat << EOF > ./openpages-instance.json
{
    "display_name": "${INSTANCE_NAME}",
    "namespace": "${PROJECT_CPD_INST_OPERANDS}",
    "addon_version": "${INSTANCE_VERSION}",
    "addon_type": "openpages",
    "create_arguments": {
        "metadata": {
            "databaseType": "internal",
            "database": "Db2",
            "enableRestrictedV2SCCForDb2": ${RESTRICTED_V2_SCC},
            "dedicatedDbNodes": ${DEDICATED_NODE},
            "dbNodeLabelValue": "${NODE_LABEL}",
            "dbDataStorageClass": "${STG_CLASS_BLOCK}",
            "dbMetaStorageClass": "${STG_CLASS_FILE}",
            "dbBackupStorageClass": "${STG_CLASS_FILE}",
            "appStorageClass": "${STG_CLASS_FILE}",,
            "enableGlobalSearch": ${GLOBAL_SEARCH},
            "enableIntegrationWithCognos": ${COGNOS_INTEGRATION},
            "scaleConfig": "${INSTANCE_SIZE}"
        }
    }
}
EOF

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

${PROJECT_CPD_INST_OPERANDS}
${STG_CLASS_BLOCK}
${STG_CLASS_FILE}

Portworx storage

cat << EOF > ./openpages-instance.json
{
    "display_name": "${INSTANCE_NAME}",
    "namespace": "${PROJECT_CPD_INST_OPERANDS}",
    "addon_version": "${INSTANCE_VERSION}",
    "addon_type": "openpages",
    "create_arguments": {
        "metadata": {
            "databaseType": "internal",
            "database": "Db2",
            "enableRestrictedV2SCCForDb2": ${RESTRICTED_V2_SCC},
            "dedicatedDbNodes": ${DEDICATED_NODE},
            "dbNodeLabelValue": "${NODE_LABEL}",
            "dbDataStorageClass": "portworx-db2-rwo-sc",
            "dbMetaStorageClass": "portworx-db2-rwx-sc",
            "dbBackupStorageClass": "portworx-db2-rwx-sc",
            "appStorageClass": "portworx-shared-gp3",,
            "enableGlobalSearch": ${GLOBAL_SEARCH},
            "enableIntegrationWithCognos": ${COGNOS_INTEGRATION},
            "scaleConfig": "${INSTANCE_SIZE}"
        }
    }
}
EOF

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

${PROJECT_CPD_INST_OPERANDS}

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 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>
```
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:

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 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

After you provision the instance, you need to do some post-installation tasks before users use OpenPages.