Cloud Pak for Data instance management API

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:

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

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

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}')

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'

Copy and save the API token.

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

Get the cpd-mgmt-api-host cpd-mgmt from the server namespace.
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.

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

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

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:

View

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

Status 202

{
  "job_id": "job_id",
  "logs": "logs",
  "status": "status"
}

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:

View

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

Status 202

{
  "job_id": "job_id",
  "logs": "logs",
  "status": "status"
}

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.

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

Introduction

Authentication

Service endpoint

Disabling SSL verification

Error handling

ErrorResponse

Methods

Configure shared cluster components

Request

Request Body

config

Response

Status Code

200

202

400

401

403

500

No Sample Response

Get the status of the shared cluster components

Request

Query Parameters

useConfigMap

Response

Response Body

name

namespace

operator_version

cr_list

Status Code

200

401

403

404

500

No Sample Response

Configure an instance

Request

Request Body

config_name

config

Response

Status Code

200

202

400

401

403

500

No Sample Response

Get the status of an instance of Cloud Pak for Data

Request

Query Parameters

instanceNS

operatorNS

components

ignoreNotFound

Response

Response Body

cpd_release

instance

cpd_instance_ns

cpd_operator_ns

tethered_instance_ns

components

name

addon_id

operator_not_found

expect_operand_version

expect_operator_version

operator_version

cr_not_found

cr_list

Status Code

200

400

401

403

500