Managing service instances with the command line

Use the cpd-cli service-instance command-line interface to manage service instances.

Important: Not all services have service instances. Refer to the service documentation for explicit guidance on using the cpd-cli service-instance commands with the service.

Before you begin

Required role: The service-instance command requires cluster administrator or similar roles.

Before you run any cpd-cli service-instance commands, complete the following prerequisites.

Note: The following examples use the recommended installation environment variables.

It is strongly recommended that you use a script to create environment variables with the correct values for your environment. For more information, see Setting up installation environment variables.

Creating a service instance

The following example creates a service instance on the IBM Software Hub instance associated with your profile.

cpd-cli service-instance create \
--profile=${CPD_PROFILE_NAME} \
--from-source=<json-template>

For --from-source, you can specify a JSON template path and file name. The JSON template file is used to create the service instance.

Important: The contents of the JSON file in the --from-source argument are service-specific. Review the service documentation to:
  • Confirm that the service supports service instances
  • Confirm that the service supports using the cpd-cli to create service instances
  • Determine the content of the JSON file

Retrieving service instance information

The following example lists the service instances in the IBM Software Hub instance associated with your profile.

cpd-cli service-instance list \
--profile=${CPD_PROFILE_NAME} \
--output=json|yaml|text

For the output type, you can specify json, text, or yaml. The default output type is text.

Example of the service instance list.

 Namespace           Service type        Version             ID                  Name                  Provision status    Upgrade version option 
 ---------           ------------        -------             --                  ----                  ----------------    ---------------------- 
 CPD_PROFILE_NAME        volumes             -                   1600820045121846    vol1                  PROVISIONED         [] 
 CPD_PROFILE_NAME        dv                  2.0.2.0             1600736770511387    watson-query          PROVISIONED         []

Retrieving the status of a specific service instance

The following example retrieves the status of a specific service instance.

cpd-cli service-instance status <cpd-service-instance-name> \
--profile=${CPD_PROFILE_NAME} \
--output=json|yaml|text

For the output type, you can specify json, text, or yaml. The default output type is text.

Example of the service instance status.

 Namespace           Service type        Version             ID                  Name                  Provision status    Service status 
 ---------           ------------        -------             --                  ----                  ----------------    -------------- 
 CPD_PROFILE_NAME        dv                  2.0.2.0             1600736770511387    watson-query          PROVISIONED         RUNNING

Retrieving details of a specific service instance

The following example retrieves details of a specific service instance.

cpd-cli service-instance get <cpd-service-instance-name> \
--profile=${CPD_PROFILE_NAME} \
--output=json|yaml|text

For the output type, you can specify json or yaml. The default output type is json.

Example of a service instance JSON file.

{
  "service_instance": {
    "addon_type": "dv",
    "addon_version": "2.0.2.0",
    "connection_info": {
      "jdbc": "jdbc:db2://dv-server.default.svc.cluster.local:32051/bigsql"
    },
    "created_at": "2023-01-22T01:06:28.432179Z",
    "description": "Watson Query",
    "display_name": "watson-query",
    "id": "1600736770511387",
    "instance_identifiers": [
      "dv-0-1600736770511387",
      "dv-1-1600736770511387",
      "dv-2-1600736770511387",
      "dv-3-1600736770511387"
    ],
    "metadata": {},
    "misc_data": {},
    "namespace": "${CPD_PROFILE_NAME}",
    "owner_uid": "1000000999",
    "owner_username": "user123",
    "parameters": {
      "enableHostIPC": "true",
      "image.pullPolicy": "IfNotPresent",
      "persistence.cachingpv.size": "100Gi",
      "persistence.cachingpv.storageClass": "managed-nfs-storage",
      "persistence.size": "50Gi",
      "persistence.storageClass": "managed-nfs-storage",
      "persistence.workerpv.size": "25Gi",
      "persistence.workerpv.storageClass": "managed-nfs-storage",
      "resources.dv.requests.cpu": "4",
      "resources.dv.requests.memory": "16Gi",
      "workerCount": "1"
    },
    "provision_status": "PROVISIONED",
    "resources": {
      "cpu": "4",
      "memory": "16"
    },
    "roles": [
      "Admin"
    ],
    "updated_at": "2023-1-07T00:51:51.842894Z",
    "zen_service_instance_info": {
      "docker_registry_prefix": "image-registry.openshift-image-registry.svc:5000/profile"
    }
  }
}

Retrieving details of all services instances with the same service type

The following example retrieves details of all service instances with the same service type.

cpd-cli service-instance get \
--service-type=<cpd-service-type> \
--all \
--profile=${CPD_PROFILE_NAME} \
--output=json|yaml|text \
--output-dir=<output-directory>

For the output type, you can specify json or yaml. The default output type is json.

Upgrading service instances

Remember: If a service uses the cpd-cli to manage service instances, refer to your specific service documentation for upgrade information.

The following example upgrades a specific service instance in the IBM Software Hub instance associated with your profile.

cpd-cli service-instance upgrade \
--instance-name=<cpd-service-instance-name> \
--service-type=<cpd-service-type> \
--profile=${CPD_PROFILE_NAME}

Append --version if you need to upgrade to a specific version. Append --watch to continuously monitor the upgrade progress.

The following example upgrades all service instances of the same service type.

cpd-cli service-instance upgrade \
--service-type=<cpd-service-type> \
--all \
--profile=${CPD_PROFILE_NAME}

Append --watch to continuously monitor the upgrade progress.

Deleting service instances

The following example deletes a specific service instance.

cpd-cli service-instance delete <cpd-service-instance-name> \
--service-type=<cpd-service-type> \
--profile=${CPD_PROFILE_NAME}

The command submits a request to deprovision the service instance. Use the cpd-cli service-instance status command to monitor the status.