IBM Cloud API Docs

Introduction

Last updated: 2024-07-12

The Cloud Pak for Data Instance Management API allows users to set up and manage an instance of Cloud Pak for Data.

You can perform the following tasks by using this API:

Install and upgrade an instance of Cloud Pak for Data
A cluster admin can install and upgrade an instance of Cloud Pak for Data.
Shut down and restart an instance of Cloud Pak for Data
A cluster admin can shut down and restart installed components in an instance of Cloud Pak for Data.
Get the status of an instance of Cloud Pak for Data
A cluster admin can get the status of installed components in an instance of Cloud Pak for Data.

Authentication

To authenticate to the API, pass an access token in an Authorization header.

Generating a Red Hat OpenShift access token through the Red Hat OpenShift console:

  1. Log in to the Red Hat OpenShift web console.
  2. Click your profile.
  3. Click Copy Login Command.
  4. Click Display Token.
  5. Copy and save your API token.

Generate a Red Hat OpenShift access token by using the command-line interface.

  1. Log in to the Red Hat OpenShift cluster and get the host.
host=$(oc get route -n openshift-authentication oauth-openshift -o jsonpath='{.spec.host}')
  1. Get the access token for the user. Replace {openshift_username} and {openshift_password} with your Red Hat OpenShift credentials. Replace {host} with the result that you got from previous step.
curl -u {openshift_username}:{openshift_password} -kv '{host}/oauth/authorize?client_id=openshift-challenging-client&response_type=token'
  1. Copy and save the API token.

Authenticating to the API by using an access token. Replace {token} with your details.

  1. Get the cpd-mgmt-api-host cpd-mgmt from the server namespace.
  2. Call a method, replacing the {cpd-mgmt-api-host} with the result that you got from previous step.
curl -H "Authorization: Bearer {token}" "https://{cpd-mgmt-api-host}/v1/{method}"

Service endpoint

The service endpoint is based on your cpd-mgmt deployment URL.

https://{cpd-mgmt-api-host}/v1/{method}

Example

curl -H "Authorization: Bearer {token}" -X {request_method} "https://{cpd-mgmt-api-host}/v1/{method}"

Disabling SSL verification

All Cloud Pak for Data services use Secure Sockets Layer (SSL) or Transport Layer Security (TLS) for secure connections between the client and server. The connection is verified against the local certificate store to ensure authentication, integrity, and confidentiality.

If you use a self-signed certificate, you need to disable SSL verification to make a successful connection.

Enabling SSL verification is highly recommended. Disabling SSL jeopardizes the security of the connection and data. Disable SSL only if necessary, and take steps to enable SSL as soon as possible.

To disable SSL verification for a curl request, use the --insecure (-k) option with the request.

Example that disables SSL verification

curl -k -X {request_method} -H "Authorization: Bearer {token}" "{url}/v1/{method}"

Error handling

OLM-UTILS uses standard HTTP response codes to indicate whether a method was successful. HTTP response codes in the 2xx range indicate success. A response in the 4xx range is a failure, and a response in the 5xx range usually indicates an internal system error that cannot be resolved by the user. Response codes are listed with the method.

ErrorResponse

Name Description
code
Integer		 A simple string code that should convey the general sense of the error.
message
String		 The message that describes the error.
more_info
String		 A reference to a more detailed explanation when available.

Methods

Configure shared cluster components

Install, upgrade, or configure the shared cluster components.

Prerequisite: To use this endpoint, you must install the management service on your cluster.

You can use one of the following methods to specify the settings that you want to use for the shared cluster components:

  • ConfigMap Use the mgmt_cluster_configmap configmap if you want to have a traceable history of changes to the shared cluster components.

    Important: To use this option, the mgmt_cluster_configmap configmap must exist in the project where the management service is installed.

  • JSON: Use this option if you don't have sufficient privileges to create the mgmt_cluster_configmap configmap in the project where the management service is installed.

POST /v1/cluster/configs

Request

Request Body

cluster_config_body

Response

Status Code

  • 200

    Success. Nothing to be configured.

  • 202

    Accepted. A job will start in the background.

  • 400

    The mgmt_cluster_configmap configmap is missing or invalid.

  • 401

    Unauthorized. The Red Hat OpenShift token is missing or invalid.

  • 403

    Forbidden. User does not have the required permissions to access the resource.

  • 500

    Internal server error.

No Sample Response

This method does not specify any sample responses.

Get the status of the shared cluster components

Get information about the status and configuration of the shared cluster components.

Prerequisite: To use this method, you must install the management service on your cluster.

GET /v1/cluster

Request

Query Parameters

  • useConfigMap
    boolean

    Specify whether to read the desired state for the cluster components from the mgmt_cluster_configmap configmap, which enables you to see the expected versions based on the release that is specified in the configmap compared to the actual versions running on the cluster.

    Default: false

Response

Response Body

shared_component_status_array_items[]

Status Code

  • 200

    Success. Returns a JSON representation that describes the current state of the shared cluster components.

  • 401

    Unauthorized. The Red Hat OpenShift token is missing or invalid.

  • 403

    Forbidden. User does not have the required permissions to access the resource.

  • 404

    Not found.

  • 500

    Internal server error.

No Sample Response

This method does not specify any sample responses.

Configure an instance

Install, upgrade, or configure the components associated with an instance of Cloud Pak for Data by applying the contents of the specified configmap.

Important: You must be an instance administrator or cluster administrator to use this method.

  • If you are an instance administrator, a cluster administrator must install the shared cluster components before you install an instance of Cloud Pak for Data.
  • If you are a cluster administrator, the management service automatically installs the shared cluster components if it can find the mgmt_cluster_configmap configmap.
POST /v1/instance/configs

Request

Request Body

Required*
instance_config_body

Response

Status Code

  • 200

    Success. There are no changes to the instance.

  • 202

    Accepted. Started an asynchronous job to configure the instance.

  • 400

    Bad Request.

  • 401

    Unauthorized. The Red Hat OpenShift token is missing or invalid.

  • 403

    Forbidden. User does not have the required permissions to access the resource.

  • 500

    Internal server error.

No Sample Response

This method does not specify any sample responses.

Get the status of an instance of Cloud Pak for Data

Get information about the status and configuration of the components associated with an instance of Cloud Pak for Data.

Prerequisite: To use this endpoint, you must install the management service on your cluster.

GET /v1/instance

Request

Query Parameters

  • instanceNS
    Required*
    string

    The project where the operands for the instance are installed.

  • operatorNS
    string

    The project where the operators for the instance are installed.

  • components
    string[]

    The list of components to query. If not set, return everything.

  • ignoreNotFound
    boolean

    Do not return error if one or more components are not found in the instance.

    Default: true

Response

Response Body

instance_status_array_items[]

Status Code

  • 200

    Success. Returns a JSON representation that describes the current state of all the installed components or the components that are queried.

  • 400

    Bad Request. One of the request components does not found in the instance.

  • 401

    Unauthorized. The Red Hat OpenShift token is missing or invalid.

  • 403

    Forbidden. User does not have the required permissions to access the resource.

  • 500

    Internal server error.

No Sample Response

This method does not specify any sample responses.

Shut down services installed in an instance of Cloud Pak for Data

This method shuts down one or more services that are installed in an instance of Cloud Pak for Data.

POST /v1/instance/shutdown

Request

Request Body

Required*
shutdown_body
Examples: 
{
  "namespace": "cpd-instance",
  "components": [
    "ws",
    "wkc"
  ]
}

Response

Status Code

  • 200

    Success. Nothing to shut down.

  • 202

    Accepted. Return a job ID that is created by the server.

  • 400

    Bad Request. One of the request components is not valid.

  • 401

    Unauthorized. The Red Hat OpenShift token is missing or invalid.

  • 403

    Forbidden. User does not have the required permissions to access the resource.

  • 500

    Internal server error.

Example responses
  • {
  "job_id": "job_id",
  "logs": "logs",
  "status": "status"
}

Restart services installed in an instance of Cloud Pak for Data

This method restarts one or more services and all of their dependencies that are installed on an instance of Cloud Pak for Data.

POST /v1/instance/restart

Request

Request Body

Required*
shutdown_body
Examples: 
{
  "namespace": "cpd-instance",
  "components": [
    "ws",
    "wkc"
  ]
}

Response

Status Code

  • 200

    Success. Nothing to restart.

  • 202

    Accepted. Return a job ID that is created by the server.

  • 400

    Bad Request. One of the request components is not valid.

  • 401

    Unauthorized. The Red Hat OpenShift token is missing or invalid.

  • 403

    Forbidden. User does not have the required permissions to access the resource.

  • 500

    Internal server error.

Example responses
  • {
  "job_id": "job_id",
  "logs": "logs",
  "status": "status"
}

Scale one or more Cloud Pak for Data services or components

This method scales one or more services that are installed on an instance of Cloud Pak for Data.

POST /v1/instance/scale

Request

Request Body

Required*
scale_body

Response

Status Code

  • 200

    Success. Nothing to scale.

  • 202

    Accepted. Return a job ID that is created by the server.

  • 400

    Bad Request. One of the request components is not valid.

  • 401

    Unauthorized. The Red Hat OpenShift token is missing or invalid.

  • 403

    Forbidden. User does not have the required permissions to access the resource.

  • 500

    Internal server error.

Example responses
  • {
  "job_id": "job_id",
  "logs": "logs",
  "status": "status"
}

Apply horizontal pod autoscaling (HPA) for one or more Cloud Pak for Data services or components

This method applies horizontal pod autoscaling (HPA) to one or more services that are installed on an instance of Cloud Pak for Data.

POST /v1/instance/hpa

Request

Request Body

Required*
hpa_body
Examples: 
{
  "namespace": "cpd-instance",
  "components": [
    "ws",
    "wkc"
  ],
  "hpa_enabled": true
}

Response

Status Code

  • 200

    Success. Nothing to scale.

  • 202

    Accepted. Return a job ID that is created by the server.

  • 400

    Bad Request. One of the request components is not valid.

  • 401

    Unauthorized. The Red Hat OpenShift token is missing or invalid.

  • 403

    Forbidden. User does not have the required permissions to access the resource.

  • 500

    Internal server error.

Example responses
  • {
  "job_id": "job_id",
  "logs": "logs",
  "status": "status"
}

Get the list of jobs generated by the cpd-mgmt server

Display all jobs that are generated by the server and associated with the user. The search can be narrowed by operator namespace and instance namespace. Additionally, jobs that are related to cluster components are not displayed by default.

GET /v1/jobs

Request

Query Parameters

  • showClusterJob
    boolean

    Default: false

  • operatorNS
    string
  • instanceNS
    string

Response

Response Body

job_detail[]

Status Code

  • 200

    Return a list of jobs that were created by the user.

  • 401

    Unauthorized. The Red Hat OpenShift token is missing or invalid.

  • 403

    Forbidden. User does not have the required permissions to access the resource.

No Sample Response

This method does not specify any sample responses.

Get the status and log of a specific job

Query a specific job and get its status and log.

GET /v1/jobs/{jobId}

Request

Path Parameters

  • jobId
    Required*
    string

Query Parameters

  • includeLog
    boolean

    Set to true if you want to display the log of the job.

Response

Response Body

job_detail[]

Status Code

  • 200

    Success. Return details about a job.

  • 401

    Unauthorized. The Red Hat OpenShift token is missing or invalid.

  • 403

    Forbidden. User does not have the required permissions to access the resource.

  • 404

    Job not found.

  • 500

    Internal server error.

No Sample Response

This method does not specify any sample responses.

Delete an existing job

Delete a specific job associated with the user and force the job to stop.

DELETE /v1/jobs/{jobId}

Request

Path Parameters

  • jobId
    Required*
    string

Response

Status Code

  • 202

    Accepted. Job will be deleted.

  • 400

    Bad Request. User attempted to delete a job that they do not own.

  • 401

    Unauthorized. The Red Hat OpenShift token is missing or invalid.

  • 403

    Forbidden. User does not have the required permissions to access the resource.

  • 404

    Job not found.

No Sample Response

This method does not specify any sample responses.

Query the metadata of Cloud Pak for Data components

Query the ansible-play config-var metadata from olm utils for information on a single component of a Cloud Pak for Data release.

GET /v1/metadata

Request

Query Parameters

  • cpdVersion
    Required*
    string
  • components
    string

    Comma-separated list of component names.

  • addonIds
    string

    Comma-separated list of addon IDs.

  • ignoreNotFound
    boolean

    If set to true, do not return error when invalid component name or addon IDs are detected.

Response

Response Body

component_metadata[]

Status Code

  • 200

    Success. Return metadata of the request component name or addon ID."

  • 400

    Bad Request.

No Sample Response

This method does not specify any sample responses.

Check liveness and readiness of the management server pod.

GET /v1/health

Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • 200

    Success. Pod is healthy.

No Sample Response

This method does not specify any sample responses.

id=curlclassName=tab-item-selected