Creating a service instance for Informix with the cpd-cli service-instance create command

After you install Informix, you must create at least one Informix service instance in the operands project. If you are a Cloud Pak for Data user, you can use the cpd-cli service-instance create command to script the process of creating service instances.

Who needs to complete this task?
To create a service instance by using the cpd-cli, 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 from the cpd-cli by using the cpd-cli service-instance create command.
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 Informix:

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

Important: Informix uses a different version number from Cloud Pak for Data. This topic includes a table that shows the Informix 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
Informix is installed. If this task is not complete, see Installing Informix.
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 created a Cloud Pak for Data user profile on the workstation from which you will create the service instance.

The profile 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 Creating a profile to use the cpd-cli management commands.

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_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 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 8.1.0
      5.0.2 8.1.0
      5.0.1 8.1.0
      5.0.0 8.0.0
    4. Set the INSTANCE_REPLICAS environment variable based on the number of replicas you want to create:
      export INSTANCE_REPLICAS=<integer>

      Specify an integer between 1 and 10.

      Specify 2 or more replicas for high availability. 2 replicas is sufficient for most use cases.

    5. Set the REPLICA_CPU environment variable based on the number of CPU you want to allocate to each replica that is associated with the service instance:
      export REPLICA_CPU=<integer>

      Specify an integer between 1 and 16.

      Size the instance based on your workload. For more information about the amount of memory to allocate to the service instance, see the component scaling guidance PDF, which you can download from the IBM Entitled Registry.

      Important: The total number of CPU used by the service instance is equal to the number or replicas multiplied by the number of CPU associated with each replica. (Total CPU=(INSTANCE_REPLICAS)*(REPLICA_CPU))
    6. Set the REPLICA_MEMORY environment variable based on the amount of memory you want to allocate to each replica that is associated with the service instance:
      export REPLICA_MEMORY=<integer>

      Specify an integer between 1 and 16.

      Size the instance based on your workload. For more information about the amount of memory to allocate to the service instance, see the component scaling guidance PDF, which you can download from the IBM Entitled Registry.

      Important: The total memory used by the service instance is equal to the number or replicas multiplied by the amount of memory associated with each replica. (Total Memory=(INSTANCE_REPLICAS)*(REPLICA_MEMORY))
    7. Specify the appropriate environment variables based on how you want to provision storage for the service instance.
      Important: Decide whether you plan to store all of the data for the service instance in a single persistent volume or use different volumes for logs, data, and backups.
      • If you use a single persistent volume, the shared storage volume must be large enough to accommodate the logs, transaction data, and backup data that is associated with the service instance.
      • If you use separate persistent volumes, the shared storage volume must be large enough to accommodate the log files, the data storage volume must be large enough to accommodate the transaction data, and the backup storage volume must be large enough to accommodate the backup of the transaction data.
      Use storage classes to automatically provision storage
      1. Set the SHARED_STORAGE_SIZE environment variable to the size of the volume that you want to create for the service instance:
        export SHARED_STORAGE_SIZE=<integer>

        Size the volume based on whether you plan to use a single storage volume or multiple storage volumes for the service instance.

      2. Set the SHARED_STORAGE_UNIT environment variable:
        export SHARED_STORAGE_UNIT=<unit>

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

      3. If you plan to use separate volumes for each type of data, set the DATA_STORAGE_SIZE environment variable to the size of the data storage volume that you want to create for the service instance:
        export DATA_STORAGE_SIZE=<integer>

        Size the volume based on the amount of transaction data that you plan to store.

      4. If you plan to use separate storage volumes for each type of data, set the DATA_STORAGE_UNIT environment variable:
        export DATA_STORAGE_UNIT=<unit>

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

      5. If you plan to use separate volumes for each type of data, set the BACKUP_STORAGE_SIZE environment variable to the size of the backup storage volume that you want to create for the service instance:
        export BACKUP_STORAGE_SIZE=<integer>

        Size the volume based on the amount of transaction data that your backups will contain.

      6. If you plan to use separate storage volumes for each type of data, set the BACKUP_STORAGE_UNIT environment variable:
        export BACKUP_STORAGE_UNIT=<unit>

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

      Use existing persistent volumes
      • Set the SHARED_STORAGE_PVC environment variable to the name of the persistent volume claim that you want to use to allocate storage to the service instance:
        export SHARED_STORAGE_PVC=<existing-pvc-name>

        Choose a persistent volume claim based on whether you plan to use a single storage volume or multiple storage volumes for the service instance.

      • If you plan to use separate storage volumes for each type of data, set the DATA_STORAGE_PVC environment variable:
        export DATA_STORAGE_PVC=<existing-pvc-name>

        Choose a persistent volume claim with sufficient storage for your transaction data.

      • If you plan to use separate storage volumes for each type of data, set the BACKUP_STORAGE_PVC environment variable:
        export DATA_STORAGE_PVC=<existing-pvc-name>

        Choose a persistent volume claim with sufficient storage to backup your transaction data.

  3. Create the informix-instance.json payload file.

    The command that you run depends on how you want to provision storage.

    Use storage classes to automatically provision storage
    Use a single persistent volume claim for all data 
    cat << EOF > ./informix-instance.json
{
    "display_name": "${INSTANCE_NAME}",
    "namespace": "${PROJECT_CPD_INST_OPERANDS}",
    "addon_type": "informix",
    "addon_version": "${INSTANCE_VERSION}",
    "create_arguments": {
        "description": "Informix DB",
        "metadata": {
            "ifxreplicas": ${INSTANCE_REPLICAS},
            "corespernode": ${REPLICA_CPU},
            "memorypernode": ${REPLICA_MEMORY},
            "singlepvcoption": true,
            "sharedstorageoptions": "new_claim",
            "sharedstorageclass": "${STG_CLASS_FILE}",
            "sharedsize": ${SHARED_STORAGE_SIZE},
            "sharedunit": "${SHARED_STORAGE_UNIT}", 
            "datastorageoptions": "new_claim",      
            "backupstorageoptions": "new_claim"
        }
    }
}
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}
    Use different persistent volume claims for each type of data 
    cat << EOF > ./informix-instance.json
{
    "display_name": "${INSTANCE_NAME}",
    "namespace": "${PROJECT_CPD_INST_OPERANDS}",
    "addon_type": "informix",
    "addon_version": "${INSTANCE_VERSION}",
    "create_arguments": {
         "description": "Informix DB",
         "metadata": {
             "ifxreplicas": ${INSTANCE_REPLICAS},
             "corespernode": ${REPLICA_CPU},
             "memorypernode": ${REPLICA_MEMORY},
             "singlepvcoption": false,
             "sharedstorageoptions": "new_claim",
             "sharedstorageclass": "${STG_CLASS_FILE}",
             "sharedsize": ${SHARED_STORAGE_SIZE},
             "sharedunit": "${SHARED_STORAGE_UNIT}",      
             "datastorageoptions": "new_claim",
             "datastorageclass": "${STG_CLASS_FILE}",
             "datasize": ${DATA_STORAGE_SIZE},
             "dataunit": "${DATA_STORAGE_UNIT}",
             "backupstorageoptions": "new_claim",
             "backupstorageclass": "${STG_CLASS_FILE}",
             "backupsize": ${BACKUP_STORAGE_SIZE},
             "backupunit": "${BACKUP_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}
    Use existing persistent volumes
    Use a single persistent volume claim for all data 
    cat << EOF > ./informix-instance.json
{
    "display_name": "${INSTANCE_NAME}",
    "namespace": "${PROJECT_CPD_INST_OPERANDS}",
    "addon_type": "informix",
    "addon_version": "${INSTANCE_VERSION}",
    "create_arguments": {
         "description": "Informix DB",
              "metadata": {
                "ifxreplicas": ${INSTANCE_REPLICAS},
                "corespernode": ${REPLICA_CPU},
                "memorypernode": ${REPLICA_MEMORY},
                "singlepvcoption": true,
                "sharedstorageoptions": "existing_claim",
                "sharedpvc": "${SHARED_STORAGE_PVC}",
                "datastorageoptions": "existing_claim",
                "backupstorageoptions": "existing_claim"
              }
        }
}
EOF
    The following environment variables use the values that are already defined in your installation environment variables script:
    • ${PROJECT_CPD_INST_OPERANDS}
    Use different persistent volume claims for each type of data 
    cat << EOF > ./informix-instance.json
{
    "display_name": "${INSTANCE_NAME}",
    "namespace": "${PROJECT_CPD_INST_OPERANDS}",
    "addon_type": "informix",
    "addon_version": "${INSTANCE_VERSION}",
    "create_arguments": {
         "description": "Informix DB",
              "metadata": {
                "ifxreplicas": ${INSTANCE_REPLICAS},
                "corespernode": ${REPLICA_CPU},
                "memorypernode": ${REPLICA_MEMORY},
                "singlepvcoption": false,
                "sharedstorageoptions": "existing_claim",
                "sharedpvc": "${SHARED_STORAGE_PVC}",
                "datastorageoptions": "existing_claim",
                "datapvc": "${DATA_STORAGE_PVC}",
                "backupstorageoptions": "existing_claim",
                "backuppvc": "${DATA_STORAGE_PVC}"
              }
        }
}
EOF
    The following environment variables use the values that are already defined in your installation environment variables script:
    • ${PROJECT_CPD_INST_OPERANDS}
  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

The service instance is ready to use. To get started with Informix, see Connecting to Informix.