Provisioning an instance of OpenPages by using the command line

Before you can use OpenPages®, you must provision an instance.

Before you begin

Ensure that the cluster has been configured and the service has been installed.
If your deployment is using an external database, ensure that the database is ready.
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.

About this task

You can provision instances by using the command line or the Cloud Pak for Data web client. For information about using the web client, see Provisioning an instance of OpenPages.

If you are using an external database, you need a separate database for each OpenPages instance. The databases can be on the same database server.

When you create the yaml file for an instance, you specify the storage classes to use for the OpenPages application and the database. For more information, see Recommended storage classes for services.

Procedure

Log in to your Red Hat® OpenShift® cluster as a project administrator:
```
oc login OpenShift_URL:port
```
Change to the project (namespace) where Cloud Pak for Data is installed.
Create a yaml file, for example openpages-instance1.yaml.

Copy the following text into the yaml file, and then update it for your environment.

apiVersion: openpages.cpd.ibm.com/v1 
kind: OpenPagesInstance 
metadata: 
  name: <instance_name> 
  namespace: <openpages_namespace> 
  annotations: 
    "ansible.sdk.operatorframework.io/verbosity": "3" 
  labels: 
    app.kubernetes.io/name: openpages 
    app.kubernetes.io/instance: openpagesinstance1 
    app.kubernetes.io/version: "8.302.1" 
    app.kubernetes.io/managed-by: ibm-cpd-openpages-operator 
spec: 
  zenControlPlaneNamespace: <cpd_namespace> 
  description: "<instance_description>" 
  version: "8.302.1"
  autoScaleConfig: <true|false>
  shutdown: <false|true|force>
  metadata: 
    databaseType: <internal|external> 
    storageVendor:  
    blockStorageClass: 
    fileStorageClass: 
    appStorageClass: 
    dbBackupStorageClass: 
    dbDataStorageClass: 
    dbMetaStorageClass:
    dbSecretName: "<db_secret>"
    dedicatedDbNodes: <true|false> 
    dbNodeLabelValue: "<node_label>"  
    scaleConfig: <size> 
    enableIntegrationWithCognos: <true|false>
  license: 
    accept: true

Table 1. Parameters for OpenPages instances
Parameter	Description
`name`	The name of the instance (maximum of 19 characters)
`namespace`	Use one of the following values: If you're using a tethered project for OpenPages, use the name of the tethered project. Important: You can use a tethered project only if your deployment is using an external database. Otherwise, use the project where Cloud Pak for Data is installed.
`zenControlPlaneNamespace`	The project where Cloud Pak for Data is installed.
`description`	A description of the instance
`version`	The version of OpenPages that you want to install. For Refresh 3 of Version 4.6, use `8.302.1`.
`autoScaleConfig`	Use one of the following values: To use automatic scaling, type `true`. With this option, the number of application server replicas increases or decreases based on utilization. Otherwise, type `false`.
`shutdown`	Use one of the following values: `true`: When the instance shuts down, it waits for all OpenPages background processes on the application server to complete, and then shuts down. `force`: When the instance shuts down, it forces a shutdown of the application server – it does not wait for background processes in OpenPages to complete. `false`: Ensures that the application server is up and running. If the application server shuts down, the system restarts it automatically. Note: When an instance is shut down, it is not reachable. Users won't be able to log in to OpenPages. The `shutdown` parameter applies only to the application server, not the database server.
`databaseType`	Use one of the following values: If you're using a database that is outside of OpenPages on Cloud Pak for Data, type `external`. Otherwise, type `internal`.
`dbSecretName`	Required if `databaseType` is `external` Type the name of the Kubernetes secret that contains the database connection information.
`storageVendor` `blockStorageClass` `fileStorageClass` `appStorageClass` `db*StorageClass`	Use these parameters to define the storage classes for the instance. For more information, see About this task. Tip: You can remove the storage parameters that you don't need.
`dedicatedDbNodes`	Use one of the following values: If your cluster administrator configured dedicated nodes for the database, type `true`. Otherwise, type `false`.
`dbNodeLabelValue`	If `dedicatedDbNodes` is set to `true`, type the label of the dedicated nodes.
`scaleConfig`	Use one of the following values: `xsmall` `small` `medium` `large` For more information, see Scaling options for OpenPages instances.
`enableIntegrationWithCognos`	If you want to integrate Cognos Analytics with OpenPages, set this parameter to `true`.

To customize the database resources, add the following lines under spec:

  customScaleConfig:
    opdb:
      resources:
        cpu: <number of CPUs>
        memory: <memory in GB>

To customize the application resources, see Scaling the OpenPages application server pod.
Change to the project where Cloud Pak for Data is installed and run the following command:
```
oc create -f <your instance yml file>
```
The provisioning process can take some time to complete. Wait for the process to complete before you log in to OpenPages.

Verify the installation by running the following command:

oc get OpenPagesInstance --namespace  <openpages_namespace> <instance_name> -o jsonpath="{.status.openpagesStatus} {'\n'}"

Verify that the command returns Completed.

4.6.3 only: When you are using an internal Db2 database with IBM® OpenPages for IBM Cloud Pak for Data, custom database configurations that were specified while deploying the Db2 instance are not being applied. To be able to use the internal database, you must make script modifications.
For more information, see Troubleshooting a Db2 instance not applying custom database configurations.

Results

The following example shows the configuration for an instance that uses an internal database, NFS storage, and does not use Cognos Analytics:

apiVersion: openpages.cpd.ibm.com/v1 
kind: OpenPagesInstance 
metadata: 
  name: openpagesinstance1  
  namespace: zen 
  annotations: 
    "ansible.sdk.operatorframework.io/verbosity": "3" 
  labels: 
    app.kubernetes.io/name: openpages 
    app.kubernetes.io/instance: openpagesinstance1 
    app.kubernetes.io/version: "8.302.1" 
    app.kubernetes.io/managed-by: ibm-cpd-openpages-operator 
spec: 
  zenControlPlaneNamespace: zen 
  description: "OpenPages instance"  
  version: "8.302.1"
  autoScaleConfig: true
  shutdown: false
  metadata: 
    databaseType: internal
    blockStorageClass: nfs-client
    fileStorageClass: nfs-client
    dbSecretName: ""
    dedicatedDbNodes: false 
    dbNodeLabelValue: ""  
    scaleConfig: xsmall 
    enableIntegrationWithCognos: false
  license: 
    accept: true

The following example shows the configuration for an instance that uses an internal database, uses the storageVendor parameter to specify OpenShift Data Foundation, and uses Cognos Analytics:

apiVersion: openpages.cpd.ibm.com/v1 
kind: OpenPagesInstance 
metadata: 
  name: openpagesinstance1  
  namespace: zen 
  annotations: 
    "ansible.sdk.operatorframework.io/verbosity": "3" 
  labels: 
    app.kubernetes.io/name: openpages 
    app.kubernetes.io/instance: openpagesinstance1 
    app.kubernetes.io/version: "8.302.1" 
    app.kubernetes.io/managed-by: ibm-cpd-openpages-operator 
spec: 
  zenControlPlaneNamespace: zen 
  description: "OpenPages instance"  
  version: "8.302.1"
  autoScaleConfig: true
  shutdown: false
  metadata: 
    databaseType: internal
    storageVendor: ocs 
    dbSecretName: ""
    dedicatedDbNodes: false 
    dbNodeLabelValue: ""  
    scaleConfig: xsmall 
    enableIntegrationWithCognos: true
  license: 
    accept: true

The following example shows the configuration for an instance that uses an internal database, Portworx storage, and Cognos Analytics. The configuration also includes the parameters for custom scaling:

apiVersion: openpages.cpd.ibm.com/v1 
kind: OpenPagesInstance 
metadata: 
  name: openpagesinstance1  
  namespace: zen 
  annotations: 
    "ansible.sdk.operatorframework.io/verbosity": "3" 
  labels: 
    app.kubernetes.io/name: openpages 
    app.kubernetes.io/instance: openpagesinstance1 
    app.kubernetes.io/version: "8.302.1" 
    app.kubernetes.io/managed-by: ibm-cpd-openpages-operator 
spec: 
  zenControlPlaneNamespace: zen 
  description: "OpenPages instance"  
  version: "8.302.1"
  autoScaleConfig: false
  shutdown: false
  metadata: 
    databaseType: internal  
    appStorageClass: portworx-shared-gp3 
    dbBackupStorageClass: portworx-db2-rwx-sc 
    dbDataStorageClass: portworx-db2-rwo-sc 
    dbMetaStorageClass: portworx-db2-rwx-sc
    dbSecretName: ""
    dedicatedDbNodes: false 
    dbNodeLabelValue: ""  
    scaleConfig: xsmall 
    enableIntegrationWithCognos: true
  customScaleConfig:
    opdb:
      resources:
        cpu: 4
        memory: 12 Gi
    opapp:
        replicas: 2
        resources:
          limits:
              cpu: 4
              memory: 6Gi
          requests:
              cpu: 4
              memory: 6Gi
  license: 
    accept: true

What to do next

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