v1-v2 | IBM Cloud API Docs

Introduction

Last updated: 2026-03-27

Deploy highly available containerized apps in Kubernetes clusters and use the powerful tools of IBM Cloud Kubernetes Service to automate, isolate, secure, manage, and monitor your workloads across cloud locations. Use the IBM Cloud Kubernetes Service API to manage your Kubernetes cluster infrastructure in IBM Cloud. For example, you can create clusters; add capacity for your workloads by resizing worker pools; manage networking, storage, and logging resources that are attached to your cluster; and enable IBM Cloud add-ons to optimize your cluster management experience. To use the Kubernetes API to manage your application workloads within your cluster, see the product documentation.

Before you begin

Make sure that you have access to a paid IBM Cloud account.
Choose a strategy for setting up and maintaining a cluster. This process includes choosing worker node flavors, setting up networking, and selecting the highest available configuration as possible.

Charges

With IBM Cloud Kubernetes Service clusters, you can use IBM Cloud infrastructure compute, networking, and storage resources with platform services such as Watson AI or Compose Database-as-a-Service. Each resource might entail its own charges that can be fixed, metered, tiered, or reserved. For more information, see What am I charged for when I use IBM Cloud Kubernetes Service?

Authentication

The IBM Cloud Kubernetes Service API uses IBM Cloud Identity and Access Management (IAM) to authenticate requests. Pass a bearer token in an Authorization header or an apikey. Tokens support authenticated requests without embedding service credentials in every call.

Authorization

To use the IBM Cloud Kubernetes Service API, you must be authorized to work with the service in IBM Cloud Identity and Access Management (IAM). The service uses IAM platform and service access roles to determine your permissions and the actions that you can perform. Make sure that you are assigned Permissions to create a cluster.

Beginning with version 4.0.0, the Node SDK returns a Promise for all methods when a callback isn't specified.

The package location moved to ibm-watson. It's available at watson-developer-cloud but is not updated there. Use ibm-watson to stay up to date.

IAM and Activity Tracker actions by API method

For a list of the IBM Cloud Identity and Access Management (IAM) action and Activity Tracker events by API method, see the product documentation.

API endpoint

Use the following API endpoint for all API requests:

https://containers.cloud.ibm.com/global

Versioning

The API is versioned to support the different infrastructure providers that are available for you to create clusters. All /v1 APIs can be used to work only with IBM Cloud classic infrastructure. To work with a cluster that was provisioned on IBM Virtual Private Cloud (VPC) infrastructure, you must use the /v2 API.

For information about the API versions, see About the API.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

HTTP error code	Description	Recovery
`200`	Success	The request was successful.
`400`	Bad Request	The input parameters in the request body are either incomplete or in the wrong format. Include all required parameters in your request.
`401`	Unauthorized	You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
`403`	Forbidden	The supplied authentication is not authorized to access the cluster or an associated cluster resource. Check that you have the correct access credentials and permissions.
`404`	Not Found	The requested resource could not be found.
`408`	Request Timeout	The connection to the server timed out. Wait a few minutes, then try again.
`409`	Conflict	The cluster or an associated cluster resource with the same name or ID already exists.
`500`	Internal Server Error	IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Get the autoscaling configuration for an ALB. The autoscaling feature is enabled when there is a configuration set for the ALB. If the configuration is missing, the feature is disabled.

GET /ingress/v2/clusters/{id_or_name}/albs/{alb_id}/autoscale

Request

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
alb_id
Required*
string
The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the GET /clusters/{idOrName} API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.

Example request

curl -X GET "/global/ingress/v2/clusters/{id_or_name}/albs/{alb_id}/autoscale"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
Ok. The autoscaling configuration for your ALB is returned.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
404
Not found. No autoscale configuration set for this cluster and ALB, or the specified cluster or ALB could not be found.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Set an autoscaling configuration for an ALB. Setting a configuration enables the autoscaling feature. You can also use this endpoint to change the autoscaling configuration.

PUT /ingress/v2/clusters/{id_or_name}/albs/{alb_id}/autoscale

Request

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
alb_id
Required*
string
The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the GET /clusters/{idOrName} API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.

Request Body

Required*

AutoscaleDetails

New autoscale configuration to be set.

Example request

curl -X PUT "/global/ingress/v2/clusters/{id_or_name}/albs/{alb_id}/autoscale"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "config": {
    "cpuAverageUtilization": 1,
    "customMetrics": "example-value",
    "maxReplicas": 1,
    "minReplicas": 1
  }
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
Ok. The provided autoscaling configuration for your ALB is set.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
404
Not found. The the specified cluster or ALB could not be found.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Delete an autoscaling configuration for the ALB. Deleting the configuration disables autoscaling.

DELETE /ingress/v2/clusters/{id_or_name}/albs/{alb_id}/autoscale

Request

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
alb_id
Required*
string
The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the GET /clusters/{idOrName} API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.

Example request

curl -X DELETE "/global/ingress/v2/clusters/{id_or_name}/albs/{alb_id}/autoscale"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
Ok. Autoscale config was unset successfully.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
404
Not found. No autoscaling configuration set for this cluster and ALB, or the specified cluster or ALB could not be found.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create an Ingress domain for a cluster.

POST /ingress/v2/dns/createDomain

Request

Request Body

Required*

CreateDomainReq

Input parameter to create a domain.

Example request

curl -X POST "/global/ingress/v2/dns/createDomain"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "crn": "example-value",
  "hostname": "my-cluster",
  "ips": [
    "example-value"
  ],
  "isDefault": false,
  "provider": "vpc-gen2",
  "secretNamespace": "my-cluster",
  "zoneID": "example-id-123"
}'
Copy to clipboard

Response

Response Body

ExtendedNlbVPCConfig

ExtendedNlbVPCConfig is the response body for the get v2 vpc apis

Status Code

201
Created. The domain is created.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 201

{
  "certProvider": "vpc-gen2",
  "cluster": "example-value",
  "crn": "example-value",
  "dnsType": "example-value",
  "isDefault": false,
  "lbHostname": "my-cluster",
  "nlbIPArray": [
    "example-value"
  ],
  "nlbSubdomain": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Deprecated: Delete the registered external provider credential for a cluster.

POST /ingress/v2/dns/deleteCredential

Request

Query Parameters

cluster
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X POST "/global/ingress/v2/dns/deleteCredential?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
No Content. The credential was successfully fetched.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Delete a non-default Ingress domain for a cluster.

POST /ingress/v2/dns/deleteDomain

Request

Request Body

Required*

DeleteDomainReq

Input parameter to delete a domain.

Example request

curl -X POST "/global/ingress/v2/dns/deleteDomain"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "subdomain": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
Ok. The domain is deleted.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Deprecated: Get metadata for the registered external provider credential for a cluster.

GET /ingress/v2/dns/getCredential

Request

Query Parameters

cluster
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/ingress/v2/dns/getCredential?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetCredentials

GetCredentials is the return model for a get on a credential

Status Code

200
Ok. The credential was successfully fetched.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "cluster": "example-value",
  "credID": "example-id-123",
  "expiresOn": "2024-01-15T10:30:00Z",
  "lastUpdatedTimestamp": "2024-01-15T10:30:00Z",
  "provider": "vpc-gen2"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Replace the default Ingress domain for a cluster and refresh the related cluster components.

POST /ingress/v2/dns/replaceDefaultSubdomain

Request

Request Body

Required*

ReplaceDefaultSubdomainReq

Input parameter to replace default domain.

Example request

curl -X POST "/global/ingress/v2/dns/replaceDefaultSubdomain"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "subdomain": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
Ok. The default domain is replaced.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Deprecated: Register a credential for external domain provider for use in ingress domain commands.

POST /ingress/v2/dns/setCredential

Request

Request Body

Required*

CreateCredentialReq

Input parameter to register an external domain provider credential.

Example request

curl -X POST "/global/ingress/v2/dns/setCredential"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "akamai_credentials": {
    "access_token": "example-value",
    "client_secret": "example-value",
    "client_token": "example-value",
    "host": "example-value",
    "zone": "us-south-1"
  },
  "cloudflare_credentials": {
    "token": "example-value",
    "zone_id": "example-id-123"
  },
  "cluster": "example-value",
  "provider": "vpc-gen2"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

201
Created. The credential was successfully registered.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Update an Ingress domain with the specified IPs or hostnames.

POST /ingress/v2/dns/updateDomain

Request

Request Body

Required*

UpdateDomainReq

Input parameter to update a domain.

Example request

curl -X POST "/global/ingress/v2/dns/updateDomain"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "domain": "example-value",
  "hostname": "my-cluster",
  "ips": [
    "example-value"
  ]
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
Ok. The domain is updated.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get settings for load balancers that expose Ingress ALBs in your cluster.

GET /ingress/v2/load-balancer/configuration

Request

Query Parameters

cluster
Required*
string
The name or ID of the cluster.
type
Required*
string
Type of load balancer configuration to return. Possible options are public and private.

Example request

curl -X GET "/global/ingress/v2/load-balancer/configuration?cluster=example-value&type=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

LBConfig

LBConfig struct models load balancer configuration

Status Code

200
Ok. The load balancer configuration for the specified type is returned.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
404
Not found. The specified cluster could not be found.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "backend": {
    "private": "example-value",
    "public": "example-value"
  },
  "cluster": "example-value",
  "proxyProtocol": {
    "cidr": [
      "example-id-123"
    ],
    "enable": true,
    "headerTimeout": 1
  },
  "type": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Configure settings for load balancers that expose Ingress ALBs in your cluster. After you use this API to set load balancer options, the existing load balancers are deleted and recreated, which can cause service disruptions. Two unused IP addresses for each new load balancer must be available in each subnet during the load balancer recreation. To configure load balancers that expose only your public ALBs or only your private ALBs, specify public or private for the type field in the request body. If you leave the type field empty, the configuration is applied to all load balancers that expose ALBs in the cluster.

Available features:

proxyProtocol:
- Limitations:
  - This feature is supported only for VPC Gen 2 clusters that run Kubernetes version 1.18 or later.
  - This feature is cluster-level, therefore type field of the request must be empty.
- Configuration:
  - enable: Set to true to enable or false to disable the PROXY protocol for the ALB load balancers. The PROXY protocol enables load balancers to pass client connection information that is contained in headers on the client request, including the client IP address, the proxy server IP address, and both port numbers, to ALBs.
  - headerTimeout: The timeout value, in seconds, for the load balancer to receive the PROXY protocol headers that contain the client connection information. This option has effect only on ALBs running the Kubernetes Ingress image. Default: 5
  - cidr: Load balancer CIDRs from which ALBs process information in PROXY protocol headers. If requests that contain PROXY headers originate from load balancers in other IP ranges, the information in the headers is not process by the ALB. This option has effect only on ALBs running the Kubernetes Ingress image. Default: 0.0.0.0/0

PATCH /ingress/v2/load-balancer/configuration

Request

Custom Headers

Content-Type
string
Allowable values: [application/json,application/merge-patch+json]

Request Body

Required*

LBConfig

In the request body, specify the desired configuration of load balancer features you want to change.

Example request

curl -X PATCH "/global/ingress/v2/load-balancer/configuration"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "backend": {
    "private": "example-value",
    "public": "example-value"
  },
  "cluster": "example-value",
  "proxyProtocol": {
    "cidr": [
      "example-id-123"
    ],
    "enable": true,
    "headerTimeout": 1
  },
  "type": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

202
Load-balancer configuration submitted and update started.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
404
Not found. The specified cluster could not be found.
423
Locked. The previous load-balancer configuration is still in progress.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Add fields to an Ingress secret with a secret stored in IBM Cloud Secrets Manager.

POST /ingress/v2/secret/addField

Request

Request Body

Required*

UpdateConfig

Input parameter to add a secret field.

Example request

curl -X POST "/global/ingress/v2/secret/addField"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "add": [
    {
      "append_prefix": false,
      "crn": "example-value",
      "name": "my-cluster"
    }
  ],
  "cluster": "example-value",
  "crn": "example-value",
  "name": "my-cluster",
  "namespace": "my-cluster",
  "remove": [
    {
      "name": "my-cluster"
    }
  ]
}'
Copy to clipboard

Response

Response Body

Secret

Secret struct holding details for a single secret

Status Code

201
Updated. The fields were successfully added to the secret in the cluster.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 201

{
  "cluster": "example-value",
  "crn": "example-value",
  "domain": "example-value",
  "domains": [
    "example-value"
  ],
  "expiresOn": "2024-01-15T10:30:00Z",
  "fields": [
    {
      "crn": "example-value",
      "expiresOn": "2024-01-15T10:30:00Z",
      "lastUpdatedTimestamp": "2024-01-15T10:30:00Z",
      "name": "my-cluster",
      "secretType": "example-value"
    }
  ],
  "lastUpdatedTimestamp": "2024-01-15T10:30:00Z",
  "name": "my-cluster"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create an Ingress secret with a secret stored in IBM Cloud Secrets Manager.

POST /ingress/v2/secret/createSecret

Request

Request Body

Required*

CreateConfig

Input parameter to add a secret.

Example request

curl -X POST "/global/ingress/v2/secret/createSecret"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "add": [
    {
      "append_prefix": false,
      "crn": "example-value",
      "name": "my-cluster"
    }
  ],
  "cluster": "example-value",
  "crn": "example-value",
  "name": "my-cluster",
  "namespace": "my-cluster",
  "persistence": false,
  "type": "example-value"
}'
Copy to clipboard

Response

Response Body

Secret

Secret struct holding details for a single secret

Status Code

201
Created. The secret was successfully created in the cluster.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 201

{
  "cluster": "example-value",
  "crn": "example-value",
  "domain": "example-value",
  "domains": [
    "example-value"
  ],
  "expiresOn": "2024-01-15T10:30:00Z",
  "fields": [
    {
      "crn": "example-value",
      "expiresOn": "2024-01-15T10:30:00Z",
      "lastUpdatedTimestamp": "2024-01-15T10:30:00Z",
      "name": "my-cluster",
      "secretType": "example-value"
    }
  ],
  "lastUpdatedTimestamp": "2024-01-15T10:30:00Z",
  "name": "my-cluster"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Delete an Ingress secret from the cluster.

POST /ingress/v2/secret/deleteSecret

Request

Request Body

Required*

DeleteConfig

Input parameter to add a secret.

Example request

curl -X POST "/global/ingress/v2/secret/deleteSecret"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "name": "my-cluster"
}'
Copy to clipboard

Response

Status Code

204
Deleted. The secret was successfully deleted from the cluster.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View Ingress secret details.

GET /ingress/v2/secret/getSecret

Request

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
name
Required*
string
The name of the secret that you want information about. To list the secrets that you have access to, use the GET /ingress/v2/secret/getSecrets API or run ibmcloud ks ingress secret ls.
namespace
Required*
string
The namespace of the secret that you want information about. To list the secrets that you have access to, use the GET /ingress/v2/secret/getSecrets API or run ibmcloud ks ingress secret ls.

Example request

curl -X GET "/global/ingress/v2/secret/getSecret?cluster=example-value&name=my-cluster&namespace=my-cluster"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Secret

Secret struct holding details for a single secret

Status Code

200
Ok. Detailed information about the secret is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "cluster": "example-value",
  "crn": "example-value",
  "domain": "example-value",
  "domains": [
    "example-value"
  ],
  "expiresOn": "2024-01-15T10:30:00Z",
  "fields": [
    {
      "crn": "example-value",
      "expiresOn": "2024-01-15T10:30:00Z",
      "lastUpdatedTimestamp": "2024-01-15T10:30:00Z",
      "name": "my-cluster",
      "secretType": "example-value"
    }
  ],
  "lastUpdatedTimestamp": "2024-01-15T10:30:00Z",
  "name": "my-cluster"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View Ingress secrets for a cluster.

GET /ingress/v2/secret/getSecrets

Request

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
show_deleted
string
To view previously deleted secrets, pass true.

Example request

curl -X GET "/global/ingress/v2/secret/getSecrets?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Secret[]

Secrets struct for a secret array

Status Code

200
Ok. The list of available Ingress secrets is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "cluster": "example-value",
    "crn": "example-value",
    "domain": "example-value",
    "domains": [
      "example-value"
    ],
    "expiresOn": "2024-01-15T10:30:00Z",
    "fields": [
      {
        "crn": "example-value",
        "expiresOn": "2024-01-15T10:30:00Z",
        "lastUpdatedTimestamp": "2024-01-15T10:30:00Z",
        "name": "my-cluster",
        "secretType": "example-value"
      }
    ],
    "lastUpdatedTimestamp": "2024-01-15T10:30:00Z",
    "name": "my-cluster"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Remove fields from an Ingress secret with a secret stored in IBM Cloud Secrets Manager.

POST /ingress/v2/secret/removeField

Request

Request Body

Required*

UpdateConfig

Remove input parameter to remove a secret field.

Example request

curl -X POST "/global/ingress/v2/secret/removeField"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "add": [
    {
      "append_prefix": false,
      "crn": "example-value",
      "name": "my-cluster"
    }
  ],
  "cluster": "example-value",
  "crn": "example-value",
  "name": "my-cluster",
  "namespace": "my-cluster",
  "remove": [
    {
      "name": "my-cluster"
    }
  ]
}'
Copy to clipboard

Response

Response Body

Secret

Secret struct holding details for a single secret

Status Code

200
Updated. The fields were successfully removed from the secret in the cluster.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "cluster": "example-value",
  "crn": "example-value",
  "domain": "example-value",
  "domains": [
    "example-value"
  ],
  "expiresOn": "2024-01-15T10:30:00Z",
  "fields": [
    {
      "crn": "example-value",
      "expiresOn": "2024-01-15T10:30:00Z",
      "lastUpdatedTimestamp": "2024-01-15T10:30:00Z",
      "name": "my-cluster",
      "secretType": "example-value"
    }
  ],
  "lastUpdatedTimestamp": "2024-01-15T10:30:00Z",
  "name": "my-cluster"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Update an Ingress secret with a secret stored in IBM Cloud Secrets Manager.

POST /ingress/v2/secret/updateSecret

Request

Request Body

Required*

UpdateConfig

Input parameter to add a secret.

Example request

curl -X POST "/global/ingress/v2/secret/updateSecret"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "add": [
    {
      "append_prefix": false,
      "crn": "example-value",
      "name": "my-cluster"
    }
  ],
  "cluster": "example-value",
  "crn": "example-value",
  "name": "my-cluster",
  "namespace": "my-cluster",
  "remove": [
    {
      "name": "my-cluster"
    }
  ]
}'
Copy to clipboard

Response

Response Body

Secret

Secret struct holding details for a single secret

Status Code

201
Created. The secret was successfully created in the cluster.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 201

{
  "cluster": "example-value",
  "crn": "example-value",
  "domain": "example-value",
  "domains": [
    "example-value"
  ],
  "expiresOn": "2024-01-15T10:30:00Z",
  "fields": [
    {
      "crn": "example-value",
      "expiresOn": "2024-01-15T10:30:00Z",
      "lastUpdatedTimestamp": "2024-01-15T10:30:00Z",
      "name": "my-cluster",
      "secretType": "example-value"
    }
  ],
  "lastUpdatedTimestamp": "2024-01-15T10:30:00Z",
  "name": "my-cluster"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View an IBM Cloud Secrets Manager instance registered to the cluster.

GET /ingress/v2/secret/getInstance

Request

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
name
Required*
string
The name of the instance that you want information about. To list the instances that you have access to, use the GET /ingress/v2/secret/getInstances API or run ibmcloud ks ingress secret instance ls.

Example request

curl -X GET "/global/ingress/v2/secret/getInstance?cluster=example-value&name=my-cluster"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Instance

Instance struct holding details for a single instance

Status Code

200
Ok. Detailed information about the secret is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "callbackChannel": "example-value",
  "cluster": "example-value",
  "crn": "example-value",
  "isDefault": false,
  "name": "my-cluster",
  "secretGroupID": "example-id-123",
  "secretGroupName": "my-cluster",
  "status": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View IBM Cloud Secrets Manager instances registered to the cluster.

GET /ingress/v2/secret/getInstances

Request

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
show_deleted
string
To view previously deleted instances, pass true.

Example request

curl -X GET "/global/ingress/v2/secret/getInstances?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Instance[]

Instances struct for a secret array

Status Code

200
Ok. The list of available Ingress secrets is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "callbackChannel": "example-value",
    "cluster": "example-value",
    "crn": "example-value",
    "isDefault": false,
    "name": "my-cluster",
    "secretGroupID": "example-id-123",
    "secretGroupName": "my-cluster",
    "status": "example-value"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Register an IBM Cloud Secrets Manager instance to the cluster.

POST /ingress/v2/secret/registerInstance

Request

Request Body

Required*

RegisterConfig

Input parameter to register an instance.

Example request

curl -X POST "/global/ingress/v2/secret/registerInstance"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "crn": "example-value",
  "isDefault": false,
  "secretGroupID": "example-id-123"
}'
Copy to clipboard

Response

Response Body

Instance

Instance struct holding details for a single instance

Status Code

200
Created. The instance was successfully registered to the cluster.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "callbackChannel": "example-value",
  "cluster": "example-value",
  "crn": "example-value",
  "isDefault": false,
  "name": "my-cluster",
  "secretGroupID": "example-id-123",
  "secretGroupName": "my-cluster",
  "status": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Unregister an IBM Cloud Secrets Manager instance from the cluster.

POST /ingress/v2/secret/unregisterInstance

Request

Request Body

Required*

DeleteConfig

Input parameter to unregister an instance.

Example request

curl -X POST "/global/ingress/v2/secret/unregisterInstance"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "name": "my-cluster"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
Deleted. The secret was successfully deleted from the cluster.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Update an IBM Cloud Secrets Manager instance registration configuration to the cluster.

POST /ingress/v2/secret/updateInstance

Request

Request Body

Required*

InstanceUpdateConfig

Input parameter to update instance registration.

Example request

curl -X POST "/global/ingress/v2/secret/updateInstance"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "isDefault": false,
  "name": "my-cluster",
  "secretGroupID": "example-id-123"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
Update. The instance was successfully updated.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified instance could not be found. To list the registered instances that you have access to, use the GET /v2/secret/getInstances API or run ibmcloud ks ingress secret instance ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get the configuration of a cluster's port 80 security settings.

GET /ingress/v2/security/port80

Request

Query Parameters

cluster
Required*
string
The name or ID of the cluster.

Example request

curl -X GET "/global/ingress/v2/security/port80?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Port80Config

Port80Config struct models port 80 configuration

Status Code

200
Ok. The port 80 configuration for the specified cluster is returned.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
404
Not found. The specified cluster could not be found.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "cluster": "example-value",
  "state": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Enable port 80 on a Kubernetes or Red Hat OpenShift cluster. For clusters created after December 1, 2025, port 80 belonging to the default OpenShift router and Kubernetes ingress is disabled by default. Configure this setting to enable the port.

PATCH /ingress/v2/security/port80

Request

Custom Headers

Content-Type
string
Allowable values: [application/json,application/merge-patch+json]

Request Body

Required*

Port80Config

Specify the security setting for port 80.

Example request

curl -X PATCH "/global/ingress/v2/security/port80"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "state": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
Port 80 security configuration submitted and update started.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
404
Not found. The specified cluster could not be found.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get the OAuth access type for a VPC cluster.

GET /network/v2/oauth-access-type/{id_or_name}

Request

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/network/v2/oauth-access-type/my-cluster"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

OauthAccessTypeJSON

OauthAccessTypeJSON for request and response

Status Code

200
Ok. The OAuth access type for the specified cluster is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "oauth_access_type": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Set the OAuth access type for a VPC cluster.

POST /network/v2/oauth-access-type/{id_or_name}/set

Request

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

OauthAccessTypeJSON

Specify the OAuth access type that you want to use. Accepted values are vpegw or legacy.

Example request

curl -X POST "/global/network/v2/oauth-access-type/my-cluster/set"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "oauth_access_type": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

202
Accepted. The request to set the OAuth access type was successful.
400
The OAuth access type you specified is not supported.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Modify the outbound traffic protection policy for a VPC cluster using Secure .

POST /network/v2/outbound-traffic-protection

Request

Request Body

Required*

OutboundTrafficProtectionRequest

Specify the outbound traffic protection policy for your cluster. Available options are enable-outbound-protection and disable-outbound-protection.

Example request

curl -X POST "/global/network/v2/outbound-traffic-protection"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "operation": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

202
Accepted. The request to set the outbound traffic protection policy was successful.
400
Bad request. The query parameters are either incomplete or in the wrong format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List all subnets in the Satellite allowlist for a Satellite cluster's service endpoint. This list includes subnets that you manually added by using the PATCH /network/v2/satellite-acl/{idOrName}/add API and subnets that are automatically added and managed by IBM, such as worker node subnets.

GET /network/v2/satellite-acl/{id_or_name}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the Satellite cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the Satellite cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/network/v2/satellite-acl/{id_or_name}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

SatelliteACLResponse

SatelliteACLResponse response for GET request

Status Code

200
Ok. The allowlist for the Satellite cluster's service endpoint is returned.
400
Bad request. Satellite Service Endpoint Allowlist feature is disabled on the specified cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "actualCSEACLList": [
    "example-value"
  ],
  "desiredCSEACLList": [
    "example-value"
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Disable the subnet allowlist feature for a Satellite cluster's service endpoint. After you disable this feature, authorized requests to your Satellite cluster master through the Satellite cluster's service endpoint can originate from any subnet.

DELETE /network/v2/satellite-acl/{id_or_name}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the Satellite cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the Satellite cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X DELETE "/global/network/v2/satellite-acl/{id_or_name}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

202
Accepted. The request to disable the Satellite allowlist feature for your Satellite cluster's service endpoint was successfully processed.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

When you add a subnet to a disabled Satellite cluster's service endpoint allowlist, the Satellite allowlist is automatically enabled. Only authorized requests to your Satellite cluster master that originate from subnets in this allowlist are permitted through the Satellite cluster's service endpoint. The subnets for your Satellite cluster's worker nodes must be added to this allowlist for the worker nodes to communicate with the master through the Satellite service endpoint.

PATCH /network/v2/satellite-acl/{id_or_name}/add

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.
Content-Type
string
Allowable values: [application/json,application/merge-patch+json]

Path Parameters

id_or_name
Required*
string
The name or ID of the Satellite cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

CsePatchAcl

The list of subnets to add to the Satellite cluster's service endpoint allowlist.

Example request

curl -X PATCH "/global/network/v2/satellite-acl/my-cluster/add"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "aclList": [
    "example-value"
  ]
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

201
Created. The subnets are successfully added to the Satellite cluster's service endpoint allowlist.
204
No content. The subnets are successfully added to the Satellite cluster's service endpoint allowlist.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Enable the subnet allowlist feature for a Satellite cluster's service endpoint. After you enable this feature, you can use the PATCH /network/v2/satellite-acl/{idOrName}/add API to add subnets to the allowlist for this Satellite cluster's service endpoint. Only authorized requests to your Satellite cluster master that originate from subnets in the allowlist are permitted through the Satellite cluster's service endpoints.

POST /network/v2/satellite-acl/{id_or_name}/enable

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the Satellite cruiser. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X POST "/global/network/v2/satellite-acl/my-cluster/enable"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

202
Accepted. The request to enable the allowlist feature for your Satellite cluster's service endpoint was successfully processed.
400
Bad request. The Satellite service endpoint allowlist feature is already enabled on the specified cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Remove subnets that you previously added to the allowlist for a Satellite cluster's service endpoint. After a subnet is removed, any requests that originate from this subnet to the Satellite cluster master through the service endpoint are denied.

PATCH /network/v2/satellite-acl/{id_or_name}/rm

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the Satellite cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.
Content-Type
string
Allowable values: [application/json,application/merge-patch+json]

Path Parameters

id_or_name
Required*
string
The name or ID of the Satellite cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

CsePatchAcl

The list of subnets to remove from the Satellite cluster's service endpoint allowlist.

Example request

curl -X PATCH "/global/network/v2/satellite-acl/my-cluster/rm"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "aclList": [
    "example-value"
  ]
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

202
Accepted. The subnets are successfully removed from the Satellite cluster's service endpoint allowlist.
204
No content. The subnets are successfully removed from the Satellite cluster's service endpoint allowlist.
400
Bad request. Satellite Service Endpoint Allowlist feature is disabled on the specified cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get a cluster's private service endpoint allowlist.

List all subnets in the allowlist for a cluster's private service endpoint. This list includes subnets that you manually added by using the PATCH /v1/acl/{idOrName}/add API and subnets that are automatically added and managed by IBM, such as worker node subnets.

GET /v1/acl/{id_or_name}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v1/acl/{id_or_name}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ACLResponse

ACLResponse response for GET request

Status Code

200
Ok. The allowlist for the cluster's private service endpoint is returned.
400
Bad request. Private Service Endpoint Allowlist feature is disabled on the specified cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "actualCSEACLList": {
    "customAclEntries": [
      "example-value"
    ],
    "systemAclEntries": [
      "example-value"
    ]
  },
  "desiredCSEACLList": {
    "customAclEntries": [
      "example-value"
    ],
    "systemAclEntries": [
      "example-value"
    ]
  }
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Disable the subnet allowlist for a cluster's private service endpoint.

Disable the subnet allowlist feature for a cluster's private service endpoint. After you disable this feature, authorized requests to your cluster master through the cluster's private service endpoint can originate from any subnet.

DELETE /v1/acl/{id_or_name}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X DELETE "/global/v1/acl/{id_or_name}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

202
Accepted. The request to disable the allowlist feature for your cluster's private service endpoint was successfully processed.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Add subnets to a cluster's private service endpoint allowlist.

After you use the POST /v1/acl/{idOrName}/enable API to enable an allowlist for your cluster's private service endpoint, add subnets to the allowlist. Only authorized requests to your cluster master that originate from subnets in this allowlist are permitted through the cluster's private service endpoint. By default, subnets for your cluster's worker nodes are added to this allowlist so that worker nodes can communicate with the master through the private service endpoint.

PATCH /v1/acl/{id_or_name}/add

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.
Content-Type
string
Allowable values: [application/json,application/merge-patch+json]

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

CsePatchAcl

The list of subnets to add to the cluster's private service endpoint allowlist.

Example request

curl -X PATCH "/global/v1/acl/my-cluster/add"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "aclList": [
    "example-value"
  ]
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

201
Created. The subnets are successfully added to the cluster's private service endpoint allowlist.
204
No content. The subnets are successfully added to the cluster's private service endpoint allowlist.
400
Bad request. Private Service Endpoint Allowlist feature is disabled on the specified cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Enable a subnet allowlist for a cluster's private service endpoint.

Enable the subnet allowlist feature for a cluster's private service endpoint. After you enable this feature, you can use the PATCH /v1/acl/{idOrName}/add API to add subnets to the allowlist for this cluster's private service endpoint. Only authorized requests to your cluster master that originate from subnets in the allowlist are permitted through the cluster's private service endpoint. If the public service endpoint is enabled for your cluster, authorized requests are still permitted through the public service endpoint.

POST /v1/acl/{id_or_name}/enable

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X POST "/global/v1/acl/my-cluster/enable"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

202
Accepted. The request to enable the allowlist feature for your cluster's private service endpoint was successfully processed.
400
Bad request. The private service endpoint allowlist feature is already enabled on the specified cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Remove subnets from a cluster's private service endpoint allowlist.

Remove subnets that you previously added to the allowlist for a cluster's private service endpoint. After a subnet is removed, any requests that originate from this subnet to the cluster master through the private service endpoint are denied.

PATCH /v1/acl/{id_or_name}/rm

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.
Content-Type
string
Allowable values: [application/json,application/merge-patch+json]

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

CsePatchAcl

The list of subnets to remove from the cluster's private service endpoint allowlist.

Example request

curl -X PATCH "/global/v1/acl/my-cluster/rm"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "aclList": [
    "example-value"
  ]
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

202
Accepted. The subnets are successfully removed from the cluster's private service endpoint allowlist.
204
No content. The subnets are successfully removed from the cluster's private service endpoint allowlist.
400
Bad request. Private Service Endpoint Allowlist feature is disabled on the specified cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Enable VPC Secure by Default Networking on an existing VPC cluster.

POST /network/v2/secure-by-default/enable

Request

Request Body

Required*

EnableSecureByDefaultClusterRequest

Enable a one-way migration to Secure by Default Networking on an existing VPC cluster currently using legacy security groups. Available options for disableOutboundTrafficProtection are true or false.

Example request

curl -X POST "/global/network/v2/secure-by-default/enable"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "disableOutboundTrafficProtection": false
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

202
Accepted. The request to enable Secure by Default Networking was successful.
400
Bad request. The query parameters are either incomplete or in the wrong format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Perform operations against a VPC Security Group associated with a cluster.

POST /network/v2/security-group

Request

Request Body

Required*

SecurityGroupRequest

Perform an operation against a VPC security group associated with a cluster. Currently supported operations are reset or sync.

Example request

curl -X POST "/global/network/v2/security-group"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "operation": "example-value",
  "securityGroupID": "example-id-123"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

202
Accepted. The requested security group operation was successfully processed.
400
Bad request. The query parameters are either incomplete or in the wrong format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List all security groups associated with a cluster.

GET /network/v2/security-group/getSecurityGroups

Request

Query Parameters

cluster
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.
type
string
Filter security groups by type. Specify cluster, worker, vpc, vpegw, or lbaas.
shared
string
Specify true to return the security groups that are shared across the VPC. Or, specify false to return only the cluster specific security groups.
user_provided
string
Specify true to return the security groups created by user. Specify false to return only the IKS managed security groups.

Example request

curl -X GET "/global/network/v2/security-group/getSecurityGroups?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetSecurityGroupsResponse[]

GetSecurityGroupsResponse defines a response when getting list of security groups that are attached to the cluster

Status Code

200
Ok. A list of security groups associated with the cluster is returned.
400
Bad request. The query parameters are either incomplete or in the wrong format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "id": "example-id-123",
    "name": "my-cluster",
    "shared": false,
    "type": "example-value",
    "userProvided": false,
    "workerPoolID": "example-id-123"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List available add-ons that you can enable in a cluster. For each available add-on, the name, latest version, and minimum Kubernetes version required to run the add-on in a cluster are returned.

GET /v1/addons

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET "/global/v1/addons"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

string[]

AddonCommon represents common properties of an addon

Status Code

200
OK. The name, latest version, and minimum required Kubernetes version for each available add-on are returned.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "defaultVersions": [
      {
        "infrastructureProvider": [
          "vpc-gen2"
        ],
        "kubeRange": "1.28.5",
        "ocpRange": "example-value",
        "openShiftVSRange": "example-value",
        "version": "1.28.5"
      }
    ],
    "installOptionsTemplate": {
      "content": "example-value",
      "immutable": false
    },
    "minKubeVersion": "1.28.5",
    "minOCPVersion": "1.28.5",
    "name": "my-cluster",
    "offeringsThatPreventDisable": [
      "example-value"
    ],
    "supportedInternalProviders": [
      "vpc-gen2"
    ],
    "supportedKubeRange": "1.28.5"
  }
]
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List account configuration information that you can use when making IBM Cloud API requests.

GET /v1/config

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET "/global/v1/config"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

BluemixConfig

Bluemix config

Status Code

200
Success

Example responses

Status 200

{
  "accounts_url": "https://example.com",
  "acct_url": "https://example.com",
  "bluemix_url": "https://example.com",
  "env_name": "my-cluster",
  "iam_base_url": "https://example.com",
  "iam_client_id": "example-id-123",
  "iam_client_secret": "example-value",
  "iam_issuer": "example-value"
}
Copy to clipboard

List available machine types that you can use for a worker node. Machine types vary by zone. Each machine type includes the amount of virtual CPU, memory, and disk space that is set up for the worker node. For more information, see http://ibm.biz/machine_types

GET /v1/datacenters/{datacenter}/machine-types

Request

Path Parameters

datacenter
Required*
string
The zone ID where you want to list available machine types. To list available zones, run ibmcloud ks zone ls or use the GET /v1/datacenters API.

Example request

curl -X GET "/global/v1/datacenters/example-value/machine-types"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

MachineType[]

MachineTypes a type that returns a sorted array of machine types

Status Code

200
Success
400
The specified zone is invalid. To list available zones, run ibmcloud ks zone ls or use the GET /v1/datacenters API.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "cores": "example-value",
    "correspondingMachineType": "example-value",
    "deprecated": false,
    "gpus": "example-value",
    "isTrusted": false,
    "memory": "example-value",
    "name": "my-cluster",
    "networkSpeed": "example-value"
  }
]
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List available Kubernetes versions that you can use to create a cluster. Note: This API call is deprecated. Use the GET /v1/versions API instead.

GET /v1/kube-versions

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET "/global/v1/kube-versions"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

KubeVersion[]

KubeVersion the kubernetes version

Status Code

200
Success. A list of available BOM versions is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "default": false,
    "end_of_service": "example-value",
    "major": 1,
    "minor": 1,
    "patch": 1
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List locations from the IBM Cloud catalog that are supported by the IBM Cloud Kubernetes Service.

GET /v1/locations

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET "/global/v1/locations"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

IKSLocation[]

IKSLocation properties

Status Code

200
Success
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "country": "example-value",
    "display_name": "my-cluster",
    "geography": "example-value",
    "id": "example-id-123",
    "kind": "example-value",
    "metro": "example-value",
    "multizone_metro": "us-south-1",
    "name": "my-cluster"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View the current messages. Messages are notifications for new features or changes that may require attention.

GET /v1/messages

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET "/global/v1/messages"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

MessageResponse[]

MessageResponse is a user message returned from the API

Status Code

200
Success
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "id": "example-id-123",
    "message": "example-value",
    "services": [
      "example-value"
    ]
  }
]
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List product-specific values to substitute for variables in other files.

GET /v1/prodconfig

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET "/global/v1/prodconfig"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ProductConfig

ProductConfig properties

Status Code

200
Success

Example responses

Status 200

{
  "company_name": "my-cluster",
  "container_service_name": "my-cluster",
  "iaas_name": "my-cluster",
  "product_name": "my-cluster",
  "product_name_short": "my-cluster"
}
Copy to clipboard

List available IBM Cloud Kubernetes Service regions. A region is a geographic area that is accessed by a container service endpoint.

GET /v1/regions

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET "/global/v1/regions"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Regions

Regions represnts information about all the regions for the cli and ui

Status Code

200
Success
404
Not found. The list of regions could not be found. Try your request again.

Example responses

Status 200

{
  "regions": [
    {
      "alias": "example-value",
      "cfURL": "https://example.com",
      "freeEnabled": true,
      "name": "my-cluster",
      "satellite": false
    }
  ]
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

List available IBM Cloud Kubernetes Service versions that you can use to create a cluster in a region. The container management platform version that you select is installed on your cluster master and worker nodes. Later, you can update the version but cannot roll back to a previous version or switch to a different container management platform. If you want to use multiple versions, create a separate cluster for each version.

GET /v1/versions

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET "/global/v1/versions"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

object

Status Code

200
Success. Available container management platform versions for the IBM Cloud Kubernetes Service region are returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List available zones (data centers) where you can create a cluster.

GET /v1/zones

Request

Query Parameters

show_flavors
string
Specify true or false to show the machine types available in each zone.
location
string
Specify a location to filter zones for. To see supported locations, use the GET /v1/locations API or run ibmcloud ks locations.

Example request

curl -X GET "/global/v1/zones"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ZoneV1[]

Zonesv1

Status Code

200
Success. A list of available zones is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "flavors": [
      {
        "cores": "example-value",
        "correspondingMachineType": "example-value",
        "deprecated": false,
        "gpus": "example-value",
        "isTrusted": false,
        "memory": "example-value",
        "name": "my-cluster",
        "networkSpeed": "example-value"
      }
    ],
    "id": "example-id-123",
    "metro": "example-value"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View the current messages. Messages are notifications for new features or changes that may require attention.

GET /v2/getMessages

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET "/global/v2/getMessages"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

MessageResponse[]

MessageResponse is a user message returned from the API

Status Code

200
Success
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "id": "example-id-123",
    "message": "example-value",
    "services": [
      "example-value"
    ]
  }
]
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Enable a public or private ALB in your standard cluster.

POST /v1/alb/albs

Request

Request Body

Required*

ALBConfig

The input parameter to enable an ALB. In the albip field, you can optionally specify an IP address that is on a VLAN in the zone that the ALB was created in. The ALB is enabled with and uses this public or private IP address. Note that this IP address must not be in use by another load balancer or ALB in the cluster. If no IP address is provided, the ALB is deployed with a public or private IP address from the portable public or private subnet that was provisioned automatically when you created the cluster, or the public or private IP address that you previously assigned to the ALB. To switch your ALB from one type of image to another, such as from an IBM Cloud Kubernetes Service ALB image to a community Kubernetes Ingress controller image, specify that image version in the ALBBuild field. To see the supported image versions, use the GET /v2/alb/getAlbImages call. For more information, see https://ibm.biz/alb_configure_docs

Example request

curl -X POST "/global/v1/alb/albs"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "albBuild": "example-value",
  "albID": "example-id-123",
  "albType": "example-value",
  "authBuild": "example-value",
  "cluster": "example-value",
  "createdDate": "2024-01-15T10:30:00Z",
  "disableDeployment": false,
  "enable": true
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

201
Enabled. The ALB for the cluster was successfully enabled.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
404
Not found. The specified cluster or ALB could not be found. To list the clusters that you have access to, run ibmcloud ks cluster ls. To list the ALBs available in a cluster, use the GET /clusters/{idOrName} API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View detailed information for an ALB in a cluster.

GET /v1/alb/albs/{alb_id}

Request

Path Parameters

alb_id
Required*
string
The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the GET /clusters/{idOrName} API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.

Example request

curl -X GET "/global/v1/alb/albs/{alb_id}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ALBConfig

ALBConfig config for alb configuration

Status Code

200
Ok. Details for the specified ALB are returned.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster or ALB could not be found. To list the clusters that you have access to, run ibmcloud ks cluster ls. To list the ALBs available in a cluster, use the GET /clusters/{idOrName} API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "albBuild": "example-value",
  "albID": "example-id-123",
  "albType": "example-value",
  "authBuild": "example-value",
  "cluster": "example-value",
  "createdDate": "2024-01-15T10:30:00Z",
  "disableDeployment": false,
  "enable": true
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Disable a public or private ALB in your standard cluster. When you disable an ALB, the IP address that the ALB used goes back into the pool of available portable IPs so that another service can use the IP. If you later try to re-enable the ALB, the ALB might report an error if the IP address it previously used is now in use by another service. You can either stop running the other service or specify another IP address to use when you re-enable the ALB.

DELETE /v1/alb/albs/{alb_id}

Request

Path Parameters

alb_id
Required*
string
The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the GET /clusters/{idOrName} API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.

Example request

curl -X DELETE "/global/v1/alb/albs/{alb_id}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
Disabled. The ALB for the cluster was successfully disabled.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster or ALB could not be found. To list the clusters that you have access to, run ibmcloud ks cluster ls. To list the ALBs available in a cluster, use the GET /clusters/{idOrName} API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List all ALB IDs in a cluster. If no ALB IDs are returned, then the cluster does not have a portable subnet.

GET /v1/alb/clusters/{id_or_name}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster that you want to see ALB information for. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v1/alb/clusters/my-cluster"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

string[]

ClusterALB alb related information for cluster

Status Code

200
Ok. A list of ALB IDs for the cluster is returned.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "alb": [
      {
        "albBuild": "example-value",
        "albID": "example-id-123",
        "albType": "example-value",
        "authBuild": "example-value",
        "cluster": "example-value",
        "createdDate": "2024-01-15T10:30:00Z",
        "disableDeployment": false,
        "enable": true
      }
    ],
    "dataCenter": "example-value",
    "id": "example-id-123",
    "ingressHostname": "my-cluster",
    "ingressSecretName": "my-cluster",
    "isPaid": false,
    "region": "us-south"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

If automatic updates for Ingress ALBs are disabled, you can force a one-time update of your ALB pods. When you choose to manually update the ALBs, all ALB pods in the cluster are updated to the latest build. You cannot update an individual ALB or choose which build to update the ALBs to. Automatic updates remain disabled.

PUT /v1/alb/clusters/{id_or_name}/update

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X PUT "/global/v1/alb/clusters/my-cluster/update"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
Ok. The update has been requested.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Check if automatic updates for Ingress ALBs are enabled and whether your ALB pods are updated to the latest build version.

GET /v1/alb/clusters/{id_or_name}/updatepolicy

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v1/alb/clusters/{id_or_name}/updatepolicy"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

UpdatePolicy

Update policy

Status Code

200
Ok. The current update policy.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "autoUpdate": false,
  "latestVersion": false
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

By default, automatic updates to Ingress ALBs are enabled. ALB pods are automatically updated when a new build version is available. To instead update the Ingress ALB component manually, you can use this call to disable automatic updates, then use the PUT /clusters/{idOrName}/update call to update all ALB pods. Note: When you update the major or minor Kubernetes version of your cluster, IBM automatically makes necessary changes to the Ingress deployment, but does not change the build version of your Ingress ALBs. You are responsible for checking the compatability of the latest Kubernetes versions and your Ingress ALB add-on images. If automatic updates for the Ingress ALB component are disabled, you can re-enable automatic updates. Whenever the next build version becomes available, the ALBs are automatically updated to the latest build.

PUT /v1/alb/clusters/{id_or_name}/updatepolicy

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

UpdatePolicy

The new update policy configuration.

Example request

curl -X PUT "/global/v1/alb/clusters/{id_or_name}/updatepolicy"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "autoUpdate": false,
  "latestVersion": false
}'
Copy to clipboard

Response

Status Code

204
Ok. The ALB update policy has been changed.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a new public or private ALB in a specified zone on a specified VLAN. You can also optionally specify an IP address on that VLAN in that zone for the ALB to use.

POST /v1/alb/clusters/{id_or_name}/zone/{zone_id}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster that you want to see ALB information for. To list the clusters that you have access to, run ibmcloud ks cluster ls.
zone_id
Required*
string
The zone in which you want to create an ALB. To see the zones where you can create an ALB, run ibmcloud ks cluster-get --cluster <cluster_name_or_ID> and look for the Worker Zones field in the output.

Request Body

Required*

ALB

The input parameters to create an ALB. For more information, see https://ibm.biz/alb_create_docs

Example request

curl -X POST "/global/v1/alb/clusters/my-cluster/zone/example-id-123"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "enableByDefault": true,
  "ingressImage": "example-value",
  "ip": "example-value",
  "nlbVersion": "1.28.5",
  "type": "example-value",
  "vlanID": "example-id-123",
  "zone": "us-south-1"
}'
Copy to clipboard

Response

Response Body

AlbCreateResp

AlbCreateResp used to send back the albid on a create request

Status Code

201
The ALB was successfully created.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
404
Not found. The specified cluster or zone could not be found. To list the clusters that you have access to, run ibmcloud ks cluster ls. To list the zones available in a cluster, use the GET /v1/clusters/{idOrName} API or run ibmcloud ks cluster-get --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "alb": "example-value",
  "cluster": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the clusters that you have access to.

GET /v1/clusters

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group to list clusters for. To list available resource groups, run ibmcloud resource groups. If you don't include this header, all the clusters in the account that you have access to are listed.

Query Parameters

location
string
Specify a location to filter clusters for. To see supported locations, use the GET /v1/locations API or run ibmcloud ks locations.
show_resources
string
To view additional cluster resources like addons, VLANs, subnets, and storage, pass true.

Example request

curl -X GET "/global/v1/clusters"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

string[]

Cluster properties

Status Code

200
Success. A list of clusters that you have access to is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "addons": [
      {
        "enabled": true,
        "name": "my-cluster",
        "state": "example-value",
        "status": "example-value"
      }
    ],
    "apiUser": "example-value",
    "createdDate": "2024-01-15T10:30:00Z",
    "crn": "example-value",
    "dataCenter": "example-value",
    "desiredTrustedProfileID": "example-id-123",
    "disableAutoUpdate": false,
    "etcdPort": "example-value",
    "id": "example-id-123",
    "vlans": [
      {
        "id": "example-id-123",
        "region": "us-south",
        "subnets": [
          {
            "cidr": "example-id-123",
            "id": "example-id-123",
            "ips": [
              "example-value"
            ],
            "is_byoip": false,
            "is_public": false
          }
        ],
        "zone": "us-south-1"
      }
    ],
    "workerZones": [
      "us-south-1"
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a cluster in the IBM Cloud account that you are logged into. Note: This API method requires Administrator platform role for IBM Cloud Kubernetes Service at the account level, as well as access to several other services such as the underlying infrastructure provider. For more information, see 'https://ibm.biz/cluster-perms'.

POST /v1/clusters

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group to list clusters for. To list available resource groups, run ibmcloud resource groups. If you don't include this header, all the clusters in the account that you have access to are listed.

Request Body

Required*

ClusterConfig

Input parameter to add a cluster. For more information, see https://ibm.biz/cluster_create_docs

Example request

curl -X POST "/global/v1/clusters"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cseAclEnabled": true,
  "dataCenter": "example-value",
  "defaultWorkerPoolEntitlement": "example-value",
  "defaultWorkerPoolName": "my-cluster",
  "disableAutoUpdate": false,
  "diskEncryption": false,
  "gatewayEnabled": true,
  "isolation": "example-value"
}'
Copy to clipboard

Response

Response Body

ClusterCreateResponse

ClusterCreateResponse is returned during a successful create cluster command

Status Code

201
Created. The cluster was successfully created in the IBM Cloud account that you are logged in to.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
409
Conflict. A cluster with the same name already exists. Choose another name for your cluster.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 201

{
  "id": "example-id-123",
  "non_critical_errors": {
    "incidentID": "example-id-123",
    "items": [
      {
        "code": "example-value",
        "description": "example-value",
        "recoveryCLI": "example-value",
        "terseDescription": "example-value",
        "type": "example-value"
      }
    ]
  }
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View detailed information for a cluster.

GET /v1/clusters/{id_or_name}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Query Parameters

show_resources
string
To view additional cluster resources like addons, VLANs, subnets, and storage, pass true.

Example request

curl -X GET "/global/v1/clusters/{id_or_name}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Cluster

Cluster properties

Status Code

200
Ok. Detailed information about the cluster is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "addons": [
    {
      "enabled": true,
      "name": "my-cluster",
      "state": "example-value",
      "status": "example-value"
    }
  ],
  "apiUser": "example-value",
  "createdDate": "2024-01-15T10:30:00Z",
  "crn": "example-value",
  "dataCenter": "example-value",
  "desiredTrustedProfileID": "example-id-123",
  "disableAutoUpdate": false,
  "etcdPort": "example-value",
  "id": "example-id-123",
  "vlans": [
    {
      "id": "example-id-123",
      "region": "us-south",
      "subnets": [
        {
          "cidr": "example-id-123",
          "id": "example-id-123",
          "ips": [
            "example-value"
          ],
          "is_byoip": false,
          "is_public": false
        }
      ],
      "zone": "us-south-1"
    }
  ],
  "workerZones": [
    "us-south-1"
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Update the Kubernetes master to the default API version. During the update, you cannot access or change the cluster. Worker nodes, apps, and resources that have been deployed by the user are not modified and will continue to run. You might need to change your YAML files for future deployments. For details, see the release notes at https://cloud.ibm.com/docs/containers?topic=containers-cs_versions

PUT /v1/clusters/{id_or_name}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

UpdateMasterCommand

Input parameter to update the Kubernetes master. Set action to update to update the master. Set force to true to attempt the update even if the change is greater than two minor versions. Set version to the Kubernetes version of the cluster. If you do not specify a version, the Kubernetes master is updated to the default API version. To see available versions, use the GET /v1/kube-versions API or run ibmcloud ks versions.

Example request

curl -X PUT "/global/v1/clusters/{id_or_name}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "action": "example-value",
  "force": false,
  "version": "1.28.5"
}'
Copy to clipboard

Response

Status Code

204
Ok. The request to update your master node was successfully processed.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
409
Conflict. The specified value is already set on the cluster. To list the clusters properties, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Delete a cluster from the IBM Cloud account that you are logged in to. When you delete a cluster, all worker nodes, apps, and containers are permanently deleted. This action cannot be undone.

DELETE /v1/clusters/{id_or_name}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Query Parameters

delete_resources
string
To delete additional resources linked to the cluster such as VLANs, subnets, and storage, pass true.
skip_permissions_precheck
string
To skip checking for infrastructure permissions before completing this action, pass 'true'. Note that if you do not have the correct infrastructure permissions, this action might only partially succeed.
delete_open_shift_registry_cos_bucket
string
To delete the COS bucket and the associated service key that holds OpenShift registry backups, pass true

Example request

curl -X DELETE "/global/v1/clusters/{id_or_name}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
Ok. The cluster was successfully removed from the IBM Cloud account that you are logged in to.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View details of the add-ons that are enabled in a cluster, including the add-on versions.

GET /v1/clusters/{id_or_name}/addons

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group of the cluster, use the GET /v1/clusters/{idOrName} API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v1/clusters/{id_or_name}/addons"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

string[]

ClusterAddon represents one add on

Status Code

200
OK. Details for the add-ons in this cluster are returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "allowed_upgrade_versions": [
      "1.28.5"
    ],
    "defaultVersions": [
      {
        "infrastructureProvider": [
          "vpc-gen2"
        ],
        "kubeRange": "1.28.5",
        "ocpRange": "example-value",
        "openShiftVSRange": "example-value",
        "version": "1.28.5"
      }
    ],
    "deprecated": false,
    "healthState": "example-value",
    "healthStatus": "example-value",
    "installOptionsTemplate": {
      "content": "example-value",
      "immutable": false
    },
    "minKubeVersion": "1.28.5",
    "minOCPVersion": "1.28.5",
    "name": "my-cluster",
    "offeringsThatPreventDisable": [
      "example-value"
    ],
    "supportedInternalProviders": [
      "vpc-gen2"
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Enable, disable, or update add-ons for a cluster.

PATCH /v1/clusters/{id_or_name}/addons

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group of the cluster, use the GET /v1/clusters/{idOrName} API.
Content-Type
string
Allowable values: [application/json,application/merge-patch+json]

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

AddonRequest

Input parameters to enable or disable add-ons in your cluster.

Example request

curl -X PATCH "/global/v1/clusters/{id_or_name}/addons"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "addons": [
    {
      "allowed_upgrade_versions": [
        "1.28.5"
      ],
      "defaultVersions": [
        {
          "infrastructureProvider": [
            "vpc-gen2"
          ],
          "kubeRange": "1.28.5",
          "ocpRange": "example-value",
          "openShiftVSRange": "example-value",
          "version": "1.28.5"
        }
      ],
      "deprecated": false,
      "healthState": "example-value",
      "healthStatus": "example-value",
      "installOptionsTemplate": {
        "content": "example-value",
        "immutable": false
      },
      "minKubeVersion": "1.28.5",
      "minOCPVersion": "1.28.5",
      "name": "my-cluster",
      "offeringsThatPreventDisable": [
        "example-value"
      ],
      "supportedInternalProviders": [
        "vpc-gen2"
      ]
    }
  ],
  "enable": true,
  "update": false
}'
Copy to clipboard

Response

Response Body

AddonResponse

AddonResponse represents an addon response

Status Code

200
OK. The add-on changes have been processed.
400
Bad request. The input parameters in the request body are not correct. Be sure to include all of the required parameters in your request in the correct JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
409
Conflict. The current add-on configuration is not compatible. Check 'MissingDeps' for add-ons to enable in this cluster.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.

Example responses

Status 200

{
  "missingDeps": [
    {
      "allowed_upgrade_versions": [
        "1.28.5"
      ],
      "defaultVersions": [
        {
          "infrastructureProvider": [
            "vpc-gen2"
          ],
          "kubeRange": "1.28.5",
          "ocpRange": "example-value",
          "openShiftVSRange": "example-value",
          "version": "1.28.5"
        }
      ],
      "deprecated": false,
      "healthState": "example-value",
      "healthStatus": "example-value",
      "installOptionsTemplate": {
        "content": "example-value",
        "immutable": false
      },
      "minKubeVersion": "1.28.5",
      "minOCPVersion": "1.28.5",
      "name": "my-cluster",
      "offeringsThatPreventDisable": [
        "example-value"
      ],
      "supportedInternalProviders": [
        "vpc-gen2"
      ]
    }
  ],
  "orphanedAddons": {}
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get the cluster-specific Kubernetes configuration data and certificates as a tar file to connect to your cluster and run Kubernetes API calls. To retrieve the administrator certificates and keys, pass admin at the end of the path. For example, /v1/clusters/{idOrName}/config/admin.

GET /v1/clusters/{id_or_name}/config

Request

Custom Headers

X-Auth-Refresh-Token
string
Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster for which you want to download the Kubernetes configuration file and certificates. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Query Parameters

sub
string
The format of the user identity to use in the Kubernetes configuration and policies. Must match the IAM provided user email, up to letter case.
format
string
To format the output in a single YAML file, pass yaml.
create_network_config
boolean
Retrieve the Calico network config with the Admin config. This only works against the admin endpoint('/config/admin')
skip_rbac
boolean
Deprecated: Previously this skipped adding the RBAC roles based on user's access in IAM. RBAC is now always applied and completes asynchronously.

Example request

curl -X GET "/global/v1/clusters/my-cluster/config"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
Ok. The cluster-specific configuration file and certificates are returned as a zip file.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a configuration to enable a key management service (KMS) provider, such as IBM Key Protect, in your cluster. Your customer root key (CRK) from the KMS provider is used to encrypt the Kubernetes secrets within your cluster. After you enable KMS for your cluster, you can update the instance, endpoint, or CRK parameters that are used, but you cannot remove the KMS provider from your cluster. Note on permissions: This API method requires the IBM Cloud IAM Administrator platform role for IBM Cloud Kubernetes Service at the account level. The API key that is used for the region and resource group that the cluster is in requires the appropriate permission to create an instance and CRK in the KMS provider, such as the Editor platform and Writer service role for Key Protect. An additional Reader service-to-service authorization policy between IBM Cloud Kubernetes Service and Key Protect is automatically created for your cluster, if the policy does not already exist. Without this policy, your cluster cannot use all the Key Protect features.

POST /v1/clusters/{id_or_name}/kms

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group of the cluster, use the GET /v1/clusters/{idOrName} API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

KeyProtectData

Input parameters to create the Key Protect config for your cluster. The user specified URL parameter is ignored, because it is fetched from Ghost.

Example request

curl -X POST "/global/v1/clusters/my-cluster/kms"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "accountID": "example-id-123",
  "correlationID": "example-id-123",
  "crkID": "example-id-123",
  "instanceID": "example-id-123",
  "serviceToService": false,
  "url": "https://example.com"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

201
OK. Your Key Protect config will be applied to the cluster.
400
Bad request. The input parameters in the request body are not correct. Be sure to include all of the required parameters in your request in the correct JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
409
Conflict. Processing multiple concurrent requests from your account to create a Key Protect config for the cluster. Wait a few minutes and try again.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Restart the Kubernetes master in the cluster to apply changes to the API server configuration.

PUT /v1/clusters/{id_or_name}/masters

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster that you want to interact with. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

MasterAPIServer

The master state. Currently, refresh is supported.

Example request

curl -X PUT "/global/v1/clusters/my-cluster/masters"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "action": "example-value"
}'
Copy to clipboard

Response

Status Code

204
Ok. The Master will be put into the desired state.
400
Bad Request. Check that all headers are present and that the state is valid. Valid states include refresh.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the IBM Cloud services that are bound in any Kubernetes namespace in the cluster.

GET /v1/clusters/{id_or_name}/services

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster where you want to list bound IBM Cloud services. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v1/clusters/{id_or_name}/services"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

BoundService[]

BoundService properties

Status Code

200
Ok. A list of IBM Cloud services bound to a cluster across all Kubernetes namespaces is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster ID or name could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "namespace": "my-cluster",
    "serviceid": "example-id-123",
    "servicekeyname": "my-cluster",
    "servicename": "my-cluster"
  }
]
Copy to clipboard

{}
{}
{}

Bind an IBM Cloud service instance to a Kubernetes namespace in your cluster. To view available IBM Cloud services from the IBM Cloud catalog, run ibmcloud catalog search --kind service. If you already provisioned IBM Cloud service instances in an IBM Cloud space, you can list them by running ibmcloud resource service-instances. Note: You can add only IBM Cloud services that support service keys, and you must add the service in the same resource group that the cluster is in.

POST /v1/clusters/{id_or_name}/services

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster where you want to list bound IBM Cloud services. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

ServiceBindRequest

The ID of the IBM Cloud service instance that you want to bind. To find the ID of the service instance, use the GET /v1/clusters/{idOrName}/services API or run {[bxcs]} cluster-services <cluster_name_or_ID>.

Example request

curl -X POST "/global/v1/clusters/{id_or_name}/services"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "namespaceID": "my-cluster",
  "role": "example-value",
  "serviceInstanceGUID": "example-id-123",
  "serviceKeyGUID": "example-id-123",
  "serviceKeyJSON": "example-value"
}'
Copy to clipboard

Response

Response Body

ServiceBindResponse

ServiceBindResponse is the response format for a service bind request

Status Code

201
Created. Your IBM Cloud service instance was successfully bound to the Kubernetes namespace of your cluster.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 201

{
  "binding": "example-value",
  "namespaceID": "my-cluster",
  "secretName": "my-cluster",
  "serviceInstanceGUID": "example-id-123"
}
Copy to clipboard

{}
{}
{}

List the IBM Cloud services that are bound to a specific Kubernetes namespace in a cluster.

GET /v1/clusters/{id_or_name}/services/{namespace}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster where you want to list bound IBM Cloud services. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
namespace
Required*
string
The Kubernetes namespace in your cluster where you want to list all bound IBM Cloud services.

Example request

curl -X GET "/global/v1/clusters/my-cluster/services/my-cluster"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

BoundService[]

BoundService properties

Status Code

200
Ok. A list of services bound to a cluster within a specific Kubernetes namespace is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified Kubernetes namespace or cluster ID/name could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To view available Kubernetes namespaces, run kubectl get namespaces.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "namespace": "my-cluster",
    "serviceid": "example-id-123",
    "servicekeyname": "my-cluster",
    "servicename": "my-cluster"
  }
]
Copy to clipboard

{}
{}
{}

Unbind an IBM Cloud service instance from a Kubernetes namespace in your cluster. Note: When you remove an IBM Cloud service, the service credentials are removed from the cluster. If a pod is still using the service, it fails because the service credentials cannot be found.

DELETE /v1/clusters/{id_or_name}/services/{namespace}/{service_instance_id}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster where you want to unbind your IBM Cloud service instance. To list bound IBM Cloud services and their namespaces, use the GET /v1/clusters/{nameOrId}/services API or run ibmcloud ks cluster service ls --cluster <cluster_name_or_ID>.
namespace
Required*
string
The Kubernetes namespace where your IBM Cloud service was bound to. To list bound IBM Cloud services and their namespaces, use the GET /v1/clusters/{nameOrId}/services API or run ibmcloud ks cluster service ls --cluster <cluster_name_or_ID>.
service_instance_id
Required*
string
The name or ID of the IBM Cloud service instance that was bound to your cluster. To list bound IBM Cloud services and their namespaces, use the GET /v1/clusters/{nameOrId}/services API or run ibmcloud ks cluster service ls --cluster <cluster_name_or_ID>.

Example request

curl -X DELETE "/global/v1/clusters/my-cluster/services/my-cluster/example-id-123"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
The IBM Cloud service instance was successfully unbound from the Kubernetes namespace of your cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster, IBM Cloud service instance, or namespace could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list bound IBM Cloud services and their namespaces, use the GET /v1/clusters/{nameOrId}/services API or run ibmcloud ks cluster service ls --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{}
{}
{}

List subnets from your IBM Cloud classic infrastructure account that are bound to a cluster. Before you can call this API method, a one-time per account POST /v1/credentials is required.

GET /v1/clusters/{id_or_name}/subnets

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v1/clusters/my-cluster/subnets"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

VlanConfigField[]

VlanConfigField represents a VLAN config for a portable IP, including subnet, zone, and region info

Status Code

200
Ok. A list of user-managed subnets that are bound to your cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "id": "example-id-123",
    "region": "us-south",
    "subnets": [
      {
        "cidr": "example-id-123",
        "id": "example-id-123",
        "ips": [
          "example-value"
        ],
        "is_byoip": false,
        "is_public": false
      }
    ],
    "zone": "us-south-1"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Make an existing IBM Cloud classic infrastructure subnet available to an existing cluster. Note: When you make a subnet available to a cluster, IP addresses of this subnet are used for cluster networking purposes. To avoid IP address conflicts, make sure that you use a subnet with one cluster only. Do not use a subnet for multiple clusters or for other purposes outside of Kubernetes Service at the same time.

PUT /v1/clusters/{id_or_name}/subnets/{subnet_id}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

subnet_id
Required*
string
The ID of the subnet in your IBM Cloud infrastructure account that you want to add to your cluster. To list available subnets, run ibmcloud ks subnets.
id_or_name
Required*
string
The name or ID of the cluster that you want to make an existing subnet available to. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X PUT "/global/v1/clusters/{id_or_name}/subnets/{subnet_id}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
Ok. The specified subnet was successfully made available to your cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Detach a subnet in your IBM Cloud classic infrastructure account from a cluster. The subnet remains available in your infrastructure account after it is detached.

PATCH /v1/clusters/{id_or_name}/subnets/{subnet_id}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

subnet_id
Required*
string
The ID of the subnet in your IBM Cloud infrastructure account that you want to add to your cluster. To list available subnets, run ibmcloud ks subnets.
id_or_name
Required*
string
The name or ID of the cluster that you want to make an existing subnet available to. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X PATCH "/global/v1/clusters/{id_or_name}/subnets/{subnet_id}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
Ok. The specified subnet was successfully removed from your cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List user-managed subnets that are bound to a cluster. Note that user-managed subnets are deprecated.

GET /v1/clusters/{id_or_name}/usersubnets

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v1/clusters/{id_or_name}/usersubnets"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

VlanConfigField[]

VlanConfigField represents a VLAN config for a portable IP, including subnet, zone, and region info

Status Code

200
Ok. A list of user-managed subnets that are bound to your cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "id": "example-id-123",
    "region": "us-south",
    "subnets": [
      {
        "cidr": "example-id-123",
        "id": "example-id-123",
        "ips": [
          "example-value"
        ],
        "is_byoip": false,
        "is_public": false
      }
    ],
    "zone": "us-south-1"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Make your own private subnet available to an Kubernetes Service cluster. This private subnet is not one provided by IBM Cloud infrastructure (SoftLayer). As such, you must configure any inbound and outbound network traffic routing for the subnet. Note: User-managed subnets are deprecated. When you add a private user subnet to a cluster, IP addresses of this subnet are used for private Load Balancers in the cluster. To avoid IP address conflicts, make sure that you use a subnet with one cluster only. Do not use a subnet for multiple clusters or for other purposes outside of Kubernetes Service at the same time.

POST /v1/clusters/{id_or_name}/usersubnets

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

UserSubnet

Pass the CIDR of your user-managed subnet and the ID of an available private VLAN in the body.

Example request

curl -X POST "/global/v1/clusters/{id_or_name}/usersubnets"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cidr": "example-id-123",
  "vlan_id": "example-id-123"
}'
Copy to clipboard

Response

Status Code

204
Ok. The specified subnet was successfully made available to your cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Remove a private user-managed subnet from a cluster. Note: User-managed subnets are deprecated. Any service that was deployed to an IP address from your own private subnet remains active after the subnet is removed.

DELETE /v1/clusters/{id_or_name}/usersubnets/{subnet_id}/vlans/{vlan_id}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster that you want to remove the user-managed subnet from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
subnet_id
Required*
string
The GUID of the user-managed subnet that you want to remove from your cluster.
vlan_id
Required*
string
The ID of the private VLAN that the user-managed subnet is on.

Example request

curl -X DELETE "/global/v1/clusters/my-cluster/usersubnets/10.240.0.0-24/vlans/example-id-123"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
Ok. The specified subnet was successfully removed from your cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create an IBM Cloud classic infrastructure subnet and make it available to an existing cluster. Note: When you make a subnet available to a cluster, IP addresses of this subnet are used for cluster networking purposes. To avoid IP address conflicts, make sure that you use a subnet with one cluster only. Do not use a subnet for multiple clusters or for other purposes outside of Kubernetes Service at the same time.

POST /v1/clusters/{id_or_name}/vlans/{vlan_id}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster for which you want to make an existing subnet from your IBM Cloud infrastructure account available. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
vlan_id
Required*
string
The VLAN in which to create the subnet. To list available VLANs, use the GET /v1/datacenters/{datacenter}/vlans API or run ibmcloud ks vlan ls <zone>.

Query Parameters

size
string
The number of subnet IP addresses. The default value is 8. Accepted values are 8, 16, 32, 64.

Example request

curl -X POST "/global/v1/clusters/my-cluster/vlans/example-id-123"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
Ok. The specified subnet was successfully made available to your cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List all webhooks for a Kubernetes cluster.

GET /v1/clusters/{id_or_name}/webhooks

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster for which you want to list available webhooks. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v1/clusters/{id_or_name}/webhooks"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ClusterWebhook[]

ClusterWebhook webhook info

Status Code

200
Ok. A list of available webhooks for the cluster is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "level": "example-value",
    "type": "example-value",
    "url": "https://example.com"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Add a webhook, such as for Slack, to a Kubernetes cluster.

POST /v1/clusters/{id_or_name}/webhooks

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster for which you want to list available webhooks. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

ClusterWebhook

Input parameter to create a webhook. Set level to the notification level, such as Normal or Warning. The default value is Warning. Set type to the webhook service type. Currently slack is supported. Set url to the URL for the webhook.

Example request

curl -X POST "/global/v1/clusters/{id_or_name}/webhooks"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "level": "example-value",
  "type": "example-value",
  "url": "https://example.com"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

201
Created. The webhook was successfully added to the cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List all the worker pools that you have in a cluster.

GET /v1/clusters/{id_or_name}/workerpools

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v1/clusters/{id_or_name}/workerpools"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

WorkerPoolResponse[]

WorkerPoolResponse provides worker pool data

Status Code

200
OK. The list of worker pools was successfully retrieved.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list all the clusters, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "autoscaleEnabled": true,
    "id": "example-id-123",
    "isBalanced": false,
    "isolation": "example-value",
    "labels": {},
    "machineType": "example-value",
    "name": "my-cluster",
    "operatingSystem": "example-value"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a worker pool for the specified cluster. Creating a worker pool requires Operator access to Kubernetes Service in the IBM Cloud account.

POST /v1/clusters/{id_or_name}/workerpools

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

WorkerPoolRequest

The

Example request

curl -X POST "/global/v1/clusters/{id_or_name}/workerpools"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "diskEncryption": false,
  "entitlement": "example-value",
  "isolation": "example-value",
  "labels": {},
  "machineType": "example-value",
  "name": "my-cluster",
  "operatingSystem": "example-value",
  "sizePerZone": 3,
  "zones": [
    {
      "id": "example-id-123",
      "privateVlan": "example-value",
      "publicVlan": "example-value"
    }
  ]
}'
Copy to clipboard

Response

Response Body

WorkerPoolResponse

WorkerPoolResponse provides worker pool data

Status Code

201
Created. The worker pool was successfully created in for the specified cluster.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
409
Conflict. A worker pool create may already be in progress for the provided cluster. Please wait a few minutes and try again.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 201

{
  "autoscaleEnabled": true,
  "id": "example-id-123",
  "isBalanced": false,
  "isolation": "example-value",
  "labels": {},
  "machineType": "example-value",
  "name": "my-cluster",
  "operatingSystem": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View detailed information for a worker pool.

GET /v1/clusters/{id_or_name}/workerpools/{poolid_or_name}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

poolid_or_name
Required*
string
The ID of the worker pool. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.
id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v1/clusters/{id_or_name}/workerpools/{poolid_or_name}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

WorkerPoolResponse

WorkerPoolResponse provides worker pool data

Status Code

200
Ok. Detailed information about the worker pool is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls mycluster.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.

Example responses

Status 200

{
  "autoscaleEnabled": true,
  "id": "example-id-123",
  "isBalanced": false,
  "isolation": "example-value",
  "labels": {},
  "machineType": "example-value",
  "name": "my-cluster",
  "operatingSystem": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Remove a worker pool from a cluster. All worker nodes in the pool are deleted. Your pods are rescheduled when you delete. To avoid downtime, be sure that you have enough worker nodes in other worker pools to run your workload.

DELETE /v1/clusters/{id_or_name}/workerpools/{poolid_or_name}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

poolid_or_name
Required*
string
The ID of the worker pool. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.
id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X DELETE "/global/v1/clusters/{id_or_name}/workerpools/{poolid_or_name}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
OK. The request to remove your worker pool was successfully received.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls mycluster.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

To change the number of worker nodes in a worker pool, you can resize or rebalance the worker pool. When you resize the worker pool, you change the number of worker nodes that are created in each zone of the worker pool. For example, if you set the size per zone to 3 and have 3 zones in the pool, you have 9 worker nodes in total. When you rebalance the worker pool, you return the number of worker nodes in the worker pool to a balanced state. For example, if you remove some worker nodes such as to troubleshoot an issue, you might have an uneven number of nodes across zones. You might delete 2 worker nodes in zone dal13 but still have 3 worker nodes each in zones dal10 and dal12 for a total of 7 worker nodes. To fix this unbalanced state, rebalance the worker pool. After rebalancing, the worker pool has 9 worker nodes again. Rebalancing does not change the size per zone of the worker pool, even if you specify a different size per zone.

PATCH /v1/clusters/{id_or_name}/workerpools/{poolid_or_name}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.
Content-Type
string
Allowable values: [application/json,application/merge-patch+json]

Path Parameters

poolid_or_name
Required*
string
The ID of the worker pool. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.
id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

WorkerPoolPatchRequest

You can change the number of worker nodes by resizing or rebalancing the worker pool. To resize, set parameters "state" to "resizing" and "sizePerZone" to the number of worker nodes that you want in each zone. You can also note why you resize the worker pool in the "reasonForResize" string parameter. To rebalance, set parameter "state" to "rebalancing". Note that rebalancing does not change the size per zone of the worker pool. To apply a custom label to the worker pool, set the "state" field to "labels" and fill in the "labels" section with your label key-value pairs. When you apply a label, all existing custom labels are replaced. If you have existing custom labels that you want to keep, include them in your request. To remove a custom label, set the "state" field to "labels" and in the "labels" section, include the same "key" field, but leave the value field blank "". Note that you must not edit the system-provided labels that that come with the worker pool and worker nodes by default, or you might experience unexpected results.

Example request

curl -X PATCH "/global/v1/clusters/{id_or_name}/workerpools/{poolid_or_name}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "allowSingleOpenShiftWorker": false,
  "labels": {},
  "reasonForResize": "example-value",
  "sizePerZone": 3,
  "state": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

202
OK. The request to resize your worker pool was successfully processed.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The request will not be permitted.
404
Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Add a zone to the specified worker pool for a cluster. Worker nodes are created in each added zone, based on the requested size per zone of the worker pool details.

POST /v1/clusters/{id_or_name}/workerpools/{poolid_or_name}/zones

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
poolid_or_name
Required*
string
The ID of the worker pool. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.

Request Body

Required*

WorkerPoolZone

Input parameters to add zones to the worker pool.

Example request

curl -X POST "/global/v1/clusters/my-cluster/workerpools/my-cluster/zones"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "id": "example-id-123",
  "privateVlan": "example-value",
  "publicVlan": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

201
OK. The requested zone has been added to the worker pool.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls mycluster.
409
Conflict. The provided zone already exists in the worker pool.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Remove a zone from a worker pool. All worker nodes for the zone are deleted from the worker pool. To avoid downtime for your apps, make sure that you have enough worker nodes left to reschedule your workloads.

DELETE /v1/clusters/{id_or_name}/workerpools/{poolid_or_name}/zones/{zoneid}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

poolid_or_name
Required*
string
The ID of the worker pool. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.
zoneid
Required*
string
The ID of the worker pool zone. To list all worker pools for a cluster, use the GET /v1/zones API or run ibmcloud ks zone ls.
id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X DELETE "/global/v1/clusters/{id_or_name}/workerpools/{poolid_or_name}/zones/{zoneid}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

202
OK. The request to remove the zone from your worker pool was successfully submitted.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The request will not be permitted.
404
Not found. The specified worker pool or zone could not be found. To list all worker pool zones, use the GET /v1/clusters/{idOrName}/workerpools/{poolIdOrName}/zones API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Update the network configuration details, such as VLANs, for a zone in the wo.

PATCH /v1/clusters/{id_or_name}/workerpools/{poolid_or_name}/zones/{zoneid}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.
Content-Type
string
Allowable values: [application/json,application/merge-patch+json]

Path Parameters

poolid_or_name
Required*
string
The ID of the worker pool. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.
zoneid
Required*
string
The ID of the worker pool zone. To list all worker pools for a cluster, use the GET /v1/zones API or run ibmcloud ks zone ls.
id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

WorkerPoolZonePatchRequest

Updated network configuration values for the worker pool zone.

Example request

curl -X PATCH "/global/v1/clusters/{id_or_name}/workerpools/{poolid_or_name}/zones/{zoneid}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "privateVlan": "example-value",
  "publicVlan": "example-value"
}'
Copy to clipboard

Response

Status Code

204
OK. The request to update network configuration for your worker pool was successful.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The request will not be permitted.
404
Not found. The specified worker pool or zone could not be found. To list all worker pool zones, use the GET /v1/clusters/{idOrName}/workerpools/{poolIdOrName}/zones API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List all worker nodes and the status of each in a cluster.

GET /v1/clusters/{id_or_name}/workers

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster for which you want to list all worker nodes. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Query Parameters

pool
string
The name or ID of the worker pool to filter results for. Run ibmcloud ks worker-pool ls --cluster <cluster name>.
show_deleted
string
true|false Shows deleted workers

Example request

curl -X GET "/global/v1/clusters/{id_or_name}/workers"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Worker[]

Worker properties

Status Code

200
Ok. A list of worker nodes for the specified cluster is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "errorMessage": "example-value",
    "errorMessageDate": "2024-01-15T10:30:00Z",
    "id": "example-id-123",
    "isolation": "example-value",
    "kubeVersion": "1.28.5",
    "location": "us-south",
    "machineType": "example-value",
    "masterVersionEOS": "1.28.5"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Add additional worker nodes to a Kubernetes cluster. Note that adding stand-alone worker nodes is deprecated. Instead, resize the worker pool to add worker nodes.

POST /v1/clusters/{id_or_name}/workers

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster for which you want to list all worker nodes. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

WorkerConfig

Input parameter to add workers to a cluster. For more information, see https://ibm.biz/worker_add_docs

Example request

curl -X POST "/global/v1/clusters/{id_or_name}/workers"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "dataCenter": "example-value",
  "diskEncryption": false,
  "isolation": "example-value",
  "machineType": "example-value",
  "operatingSystem": "example-value",
  "prefix": "example-value",
  "privateVlan": "example-value",
  "publicVlan": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

201
Ok. Additional worker nodes were successfully added to your cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View detailed information for a worker node.

GET /v1/clusters/{id_or_name}/workers/{worker_id}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
worker_id
Required*
string
The ID of the worker node that you want details for. To list all worker nodes for a cluster, use the GET /v1/clusters/{idOrName}/workers API or run ibmcloud ks worker ls --cluster <cluster_name_or_ID>.

Example request

curl -X GET "/global/v1/clusters/{id_or_name}/workers/{worker_id}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Worker

Worker properties

Status Code

200
Ok. Detailed information about the worker node is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "errorMessage": "example-value",
  "errorMessageDate": "2024-01-15T10:30:00Z",
  "id": "example-id-123",
  "isolation": "example-value",
  "kubeVersion": "1.28.5",
  "location": "us-south",
  "machineType": "example-value",
  "masterVersionEOS": "1.28.5"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Reboot, reload, or update a worker node in a Kubernetes cluster. If a problem exists with a worker node, try to reload it, which reloads all the configurations and updates the worker node with the latest image and Kubernetes patch version. When you reboot a worker node, its state remains the same such as deployed, but its status updates as the machine in your infrastructure account is restarted. If you update the worker node, it is reimaged with the Kubernetes version that matches the cluster master. If you reboot, reload, or update a worker node, data is deleted if not stored outside the worker node in persistent storage. This action cannot be undone.

PUT /v1/clusters/{id_or_name}/workers/{worker_id}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
worker_id
Required*
string
The ID of the worker node that you want details for. To list all worker nodes for a cluster, use the GET /v1/clusters/{idOrName}/workers API or run ibmcloud ks worker ls --cluster <cluster_name_or_ID>.

Request Body

Required*

UpdateWorkerCommand

The action that you want your worker node to take. Pass os_reboot, reload, or update as the action string.

Example request

curl -X PUT "/global/v1/clusters/{id_or_name}/workers/{worker_id}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "action": "example-value",
  "force": false
}'
Copy to clipboard

Response

Status Code

204
OK. The request to reboot or reload your worker node was successfully processed.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Delete a worker node from a cluster. This action cannot be undone. When you delete the worker node, the worker node is cordoned and drained so that its pods are rescheduled onto remaining worker nodes in the cluster. Make sure that you have enough capacity in the cluster to support the workload. After you remove the worker node, you can rebalance the worker pool.

DELETE /v1/clusters/{id_or_name}/workers/{worker_id}

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
worker_id
Required*
string
The ID of the worker node that you want details for. To list all worker nodes for a cluster, use the GET /v1/clusters/{idOrName}/workers API or run ibmcloud ks worker ls --cluster <cluster_name_or_ID>.

Example request

curl -X DELETE "/global/v1/clusters/{id_or_name}/workers/{worker_id}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
Ok. The worker node was successfully removed from your cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View the URL for the remote logging service that you are sending API server audit logs to.

GET /v1/clusters/{id_or_name}/apiserverconfigs/auditwebhook

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster that you want audit configuration details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v1/clusters/{id_or_name}/apiserverconfigs/auditwebhook"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

AuditWebhookConfig

Audit webhook config

Status Code

200
Successfully retrieved the audit webhook configuration.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "auditServer": "example-value",
  "caCertificate": "example-value",
  "clientCertificate": "example-value",
  "clientKey": "example-value",
  "policy": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create or update an audit webhook configuration for a cluster. The webhook sends Kubernetes API server audit logs that allow you to monitor API requests to your cluster.

PUT /v1/clusters/{id_or_name}/apiserverconfigs/auditwebhook

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster that you want audit configuration details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

AuditWebhookConfig

The input parameter for creating or updating an audit webhook configuration. For more information, see https://ibm.biz/audit_config_docs

Example request

curl -X PUT "/global/v1/clusters/{id_or_name}/apiserverconfigs/auditwebhook"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "auditServer": "example-value",
  "caCertificate": "example-value",
  "clientCertificate": "example-value",
  "clientKey": "example-value",
  "policy": "example-value"
}'
Copy to clipboard

Response

Status Code

204
Ok. The cluster will send audit logs to the audit server.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
412
Precondition failed. The input parameters in the request body are incorrect. Some typical cases include if the audit server is http and certs are provided or if the server is https and not all certs are provided.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Disable the webhook backend configuration for the cluster's API server. Diabling the webhook backend stops forwarding API server audit logs to a remote server.

DELETE /v1/clusters/{id_or_name}/apiserverconfigs/auditwebhook

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster that you want audit configuration details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X DELETE "/global/v1/clusters/{id_or_name}/apiserverconfigs/auditwebhook"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
Successfully deleted the audit webhook configuration.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get the infrastructure user name of the credentials that are used to access the IBM Cloud classic infrastructure portfolio. Infrastructure credentials are set per region and resource group.

GET /v1/credentials

Request

Custom Headers

X-Region
Required*
string
Target the IBM Cloud Kubernetes Service region where you want to get infrastructure credential details. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

Example request

curl -X GET "/global/v1/credentials"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Credentials

Credentials provides information about user infrastructure credentials

Status Code

200
Ok. The IBM Cloud infrastructure (SoftLayer) account credentials were successfully retrieved from IBM Cloud Kubernetes Service.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. No IBM Cloud infrastructure account credentials are stored in the Kubernetes Service account for this region and resource group.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{ "apiUser": "example-value" }

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Set the IBM Cloud classic infrastructure user name and API key for the region and resource group in your IBM Cloud Kubernetes Service account. Do not set multiple credentials for one IBM Cloud Kubernetes Service account. Every IBM Cloud Kubernetes Service account is linked to one IBM Cloud infrastructure portfolio only. When you manually set infrastructure credentials with this API, these credentials are used instead of any API key that is set for the region and resource group.

POST /v1/credentials

Request

Custom Headers

X-Region
Required*
string
Target the IBM Cloud Kubernetes Service region where you want to get infrastructure credential details. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.
X-Auth-Softlayer-Username
string
The user name of the IBM Cloud classic infrastructure account that you want to use with Kubernetes Service. To retrieve your user name, log in to the IBM Cloud account that you want to use, click Manage > Access (IAM) > Users > your user profile. Then, from the User Details tab, go to the VPN password section. The user name is in a format similar to 1234567_name@email.com.
X-Auth-Softlayer-APIKey
string
The classic infrastructure API key of the IBM Cloud account that you want to use with Kubernetes Service. To retrieve your API key, log in to the IBM Cloud account that you want to use, click Manage > Access (IAM) > API keys. Filter the view for Classic infrastructure API keys. In the row for the API key, click the action menu > Details. In the API key details pane, click the eye icon to view the API key value.

Example request

curl -X POST "/global/v1/credentials"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
Ok. The IBM Cloud infrastructure account credentials were successfully set for this region and resource group.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Remove the IBM Cloud classic infrastructure user name and API key from the region and resource group in your IBM Cloud Kubernetes Service account. After removing the credentials, you cannot access that IBM Cloud classic infrastructure account through your IBM Cloud Kubernetes Service account anymore. Instead, the default infrastructure account for your IBM Cloud account and the corresponding API key is used. Before you remove the infrastructure credentials, check which clusters use these credentials and make a plan to re-create the clusters in the new infrastructure environment. Otherwise, you might not be able to perform infrastructure actions, like updating or adding worker nodes, to the clusters that use the old credentials.

DELETE /v1/credentials

Request

Custom Headers

X-Region
Required*
string
Target the IBM Cloud Kubernetes Service region where you want to get infrastructure credential details. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

Example request

curl -X DELETE "/global/v1/credentials"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
Ok. The IBM Cloud infrastructure account credentials were successfully removed from your IBM Cloud Kubernetes Service account for this region and resource group.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. No IBM Cloud infrastructure account credentials are stored in the Kubernetes Service account for this region and resource group.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get details on the compute, networking, and storage permissions that the IBM Cloud infrastructure (SoftLayer) credentials have in this region and resource group. To review what IBM Cloud infrastructure (SoftLayer) credentials are set, use the GET /v1/credentials API, or run ibmcloud ks credential get or ibmcloud ks api-key info.

GET /v1/infra-permissions

Request

Custom Headers

X-Region
Required*
string
Target the IBM Cloud Kubernetes Service region where you want to check the infrastructure permissions. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.
X-Auth-Resource-Group
string
The ID of the resource group. To list available resource group IDs, run ibmcloud resource groups.

Example request

curl -X GET "/global/v1/infra-permissions"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "X-Auth-Resource-Group: example-id-123"
Copy to clipboard

Response

Response Body

AccountStatus

AccountStatus summarises the IaaS user's view of the provider account

Status Code

200
Ok.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "account": "example-value",
  "accountType": "example-value",
  "networkManagerPermissions": {
    "recommended": {
      "insufficient": false,
      "missingPermissions": [
        "example-value"
      ]
    },
    "required": {
      "insufficient": false,
      "missingPermissions": [
        "example-value"
      ]
    }
  },
  "physicalWorkerManagerPermissions": {
    "recommended": {
      "insufficient": false,
      "missingPermissions": [
        "example-value"
      ]
    },
    "required": {
      "insufficient": false,
      "missingPermissions": [
        "example-value"
      ]
    }
  },
  "storageManagerPermissions": {
    "recommended": {
      "insufficient": false,
      "missingPermissions": [
        "example-value"
      ]
    },
    "required": {
      "insufficient": false,
      "missingPermissions": [
        "example-value"
      ]
    }
  },
  "virtualWorkerManagerPermissions": {
    "recommended": {
      "insufficient": false,
      "missingPermissions": [
        "example-value"
      ]
    },
    "required": {
      "insufficient": false,
      "missingPermissions": [
        "example-value"
      ]
    }
  }
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Replace the IAM API key for the IBM Cloud Kubernetes Service in a region and resource group. The API key is used to access several services, such as the IBM Cloud classic infratructure portfolio, and is required to manage your clusters. To avoid service interruptions, do not replace the API key unless your existing key is compromised.

POST /v1/keys

Request

Custom Headers

X-Region
Required*
string
Target the IBM Cloud Kubernetes Service region where you want to reset the IAM API key. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.
X-Auth-Resource-Group
string
The ID of the resource group where you want to set the API key.

Example request

curl -X POST "/global/v1/keys"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "X-Auth-Resource-Group: example-id-123"
Copy to clipboard

Response

Status Code

204
Ok. The IAM API key is successfully reset.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View the VLAN spanning status for an IBM Cloud Infrastructure (SoftLayer) account. VLAN spanning enables all devices on an account to communicate with each other by means of the private network, regardless of its assigned VLAN.

GET /v1/subnets/vlan-spanning

Request

Custom Headers

X-Region
Required*
string
Target the IBM Cloud Kubernetes Service region where you want to check the VLAN spanning status. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.
X-Auth-Resource-Group
string
The ID of the resource group. To list available resource group IDs, run ibmcloud resource groups.

Example request

curl -X GET "/global/v1/subnets/vlan-spanning"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "X-Auth-Resource-Group: example-id-123"
Copy to clipboard

Response

Response Body

VlanSpan

Vlan span

Status Code

200
Ok. Details of VLAN spanning enablement.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Unable to determine whether VLAN spanning is enabled in the IBM Cloud infrastructure account.

Example responses

Status 200

{
  "enabled": true,
  "modifiedDate": "2024-01-15T10:30:00Z"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

List available public and private VLANs for a specified data center. Before using this operation, you must store your IBM Cloud infrastructure (SoftLayer) credentials in each Kubernetes Service account by using the POST /v1/credentials API or by running ibmcloud ks credential set --infrastructure-api-key <API_key> --infrastructure-username <API_username>.

GET /v1/datacenters/{datacenter}/vlans

Request

Path Parameters

datacenter
Required*
string
The ID of the zone where you want to list available public and private VLANs. To list available zones, run ibmcloud ks zone ls or use the GET /v1/datacenters API.

Example request

curl -X GET "/global/v1/datacenters/example-value/vlans"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

VLAN[]

Vlan

Status Code

200
Ok. A list of available public and private VLANs for the specified zone is returned.
400
The specified zone is invalid. To list available zones, run ibmcloud ks zone ls' or use the GET /v1/datacenters` API.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "id": "example-id-123",
    "properties": {
      "local_disk_storage_capability": "example-value",
      "location": "us-south",
      "name": "my-cluster",
      "note": "example-value",
      "primary_router": "example-value",
      "san_storage_capability": "example-value",
      "subnet_count": 3,
      "vlan_number": "example-value"
    },
    "type": "example-value"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List available subnets in an IBM Cloud classic infrastructure account. Before using this operation, you must store your IBM Cloud classic infrastructure credentials in each Kubernetes Service account by using the POST /v1/credentials API or by running ibmcloud ks credential set --infrastructure-api-key <API_key> --infrastructure-username <API_username>.

GET /v1/subnets

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

datacenters
string
A comma seperated list of datacenters to filter subnets based off of.

Example request

curl -X GET "/global/v1/subnets"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Subnet[]

Subnet provides information about a vpc subnet

Status Code

200
Ok.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "availableIPv4AddressCount": 3,
    "id": "example-id-123",
    "ipv4CIDRBlock": "example-id-123",
    "name": "my-cluster",
    "publicGatewayID": "example-id-123",
    "publicGatewayName": "my-cluster",
    "vpcID": "example-id-123",
    "vpcName": "my-cluster"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View the name and email address for the owner of the cluster's containers-kubernetes-key API key.

GET /v1/logging/{id_or_name}/clusterkeyowner

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster get --cluster <cluster_name_or_ID>.

Path Parameters

id_or_name
Required*
string
The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v1/logging/my-cluster/clusterkeyowner"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group-ID: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ClusterKeyOwnerInfo

ClusterKeyOwnerInfo stores the token owner's information

Status Code

200
Ok. The cluster API key ID and the owner's name and email address.
401
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "email": "example-value",
  "id": "example-id-123",
  "name": "my-cluster"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View the default logging endpoint for the target region.

GET /v1/logging/{id_or_name}/default

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster get --cluster <cluster_name_or_ID>.

Path Parameters

id_or_name
Required*
string
The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v1/logging/my-cluster/default"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group-ID: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

DefaultLoggingEndpointResponse

DefaultLoggingEndpointResponse is the ibm logging service endpoint where logs will be sent by default clusters in the target region

Status Code

200
Ok. The default logging endpoint for the target region.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "endpoint": "https://example.com",
  "hostname": "my-cluster",
  "port": 443
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the log forwarding configurations in the target cluster.

GET /v1/logging/{id_or_name}/loggingconfig

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster get --cluster <cluster_name_or_ID>.

Path Parameters

id_or_name
Required*
string
The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v1/logging/{id_or_name}/loggingconfig"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

string[]

LogConfigResponse is how users will see their logging configs from API responses

Status Code

200
Ok. A list of logging configurations in the Kubernetes cluster.
401
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "appLogContainers": [
      "example-value"
    ],
    "appLogPaths": [
      "example-value"
    ],
    "caCert": "example-value",
    "endpoint": "https://example.com",
    "errors": [
      "example-value"
    ],
    "id": "example-id-123",
    "logSource": "example-value",
    "logSourceContainers": [
      "example-value"
    ],
    "logSourcePaths": [
      "example-value"
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Stops all log forwarding for a cluster by deleting all log forwarding configurations.

DELETE /v1/logging/{id_or_name}/loggingconfig

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster get --cluster <cluster_name_or_ID>.

Path Parameters

id_or_name
Required*
string
The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Query Parameters

force_update
boolean
Forces the request which may cause a new fluentd version to be deployed to the cluster.

Example request

curl -X DELETE "/global/v1/logging/{id_or_name}/loggingconfig"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
Ok. All log forwarding configurations have been removed.
401
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the log forwarding configurations for the specified log source in the target cluster.

GET /v1/logging/{id_or_name}/loggingconfig/{log_source}

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster get --cluster <cluster_name_or_ID>.

Path Parameters

log_source
Required*
string
The type of log source that you want to list configurations for.
id_or_name
Required*
string
The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v1/logging/{id_or_name}/loggingconfig/{log_source}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

string[]

LogConfigResponse is how users will see their logging configs from API responses

Status Code

200
Ok. A list of logging configurations for the specified log source in the cluster.
401
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "appLogContainers": [
      "example-value"
    ],
    "appLogPaths": [
      "example-value"
    ],
    "caCert": "example-value",
    "endpoint": "https://example.com",
    "errors": [
      "example-value"
    ],
    "id": "example-id-123",
    "logSource": "example-value",
    "logSourceContainers": [
      "example-value"
    ],
    "logSourcePaths": [
      "example-value"
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Enable log collection for a specified log source and log forwarding to IBM Cloud Log Analysis or to an external syslog server. If you want to forward logs from one log source to both log collector servers, then you must create two logging configurations.

POST /v1/logging/{id_or_name}/loggingconfig/{log_source}

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster get --cluster <cluster_name_or_ID>.

Path Parameters

log_source
Required*
string
The type of log source that you want to list configurations for.
id_or_name
Required*
string
The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Query Parameters

force_update
boolean
Forces the request which may cause a new fluentd version to be deployed to the cluster.
skip_validation
boolean
Set to true to skip validation of the space and org Cloud Foundry properties. Skipping validation decreases processing time, but an invalid logging configuration will not correctly forward logs.

Request Body

Required*

LogConfigBody

The type of log collector server for the logging configuration. Supported logging types are 'syslog' and 'ibm'.

Example request

curl -X POST "/global/v1/logging/{id_or_name}/loggingconfig/{log_source}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "appLogContainers": [
    "example-value"
  ],
  "appLogPaths": [
    "example-value"
  ],
  "caCert": "example-value",
  "loggingType": "example-value",
  "namespace": "my-cluster",
  "org": "example-value",
  "protocol": "example-value",
  "remoteLogPort": 443
}'
Copy to clipboard

Response

Response Body

LogConfigResponse

LogConfigResponse is how users will see their logging configs from API responses

Status Code

201
Ok. Logs from the specified log source will be forwarded to the log server.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format. Supported logging types are 'syslog' and 'ibm'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.
401
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "appLogContainers": [
    "example-value"
  ],
  "appLogPaths": [
    "example-value"
  ],
  "caCert": "example-value",
  "endpoint": "https://example.com",
  "errors": [
    "example-value"
  ],
  "id": "example-id-123",
  "logSource": "example-value",
  "logSourceContainers": [
    "example-value"
  ],
  "logSourcePaths": [
    "example-value"
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Update the details of a log forwarding configuration.

PUT /v1/logging/{id_or_name}/loggingconfig/{log_source}/{id}

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster get --cluster <cluster_name_or_ID>.

Path Parameters

log_source
Required*
string
The log source from which you want to forward logs. Supported values are container, worker, kubernetes, ingress, and application. If you do not provide a namespace for log source container, then all namespaces use this configuration.
id
Required*
string
The UUID of the logging configuration that you want to update.
id_or_name
Required*
string
The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Query Parameters

force_update
boolean
Forces the request which may cause a new fluentd version to be deployed to the cluster.
skip_validation
boolean
Set to true to skip validation of the space and org Cloud Foundry properties. Skipping validation decreases processing time, but an invalid logging configuration will not correctly forward logs.

Request Body

Required*

LogConfigBody

The new type of log collector server for the logging configuration. Supported logging types are 'syslog'.

Example request

curl -X PUT "/global/v1/logging/{id_or_name}/loggingconfig/{log_source}/{id}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "appLogContainers": [
    "example-value"
  ],
  "appLogPaths": [
    "example-value"
  ],
  "caCert": "example-value",
  "loggingType": "example-value",
  "namespace": "my-cluster",
  "org": "example-value",
  "protocol": "example-value",
  "remoteLogPort": 443
}'
Copy to clipboard

Response

Response Body

LogConfigResponse

LogConfigResponse is how users will see their logging configs from API responses

Status Code

200
Ok. The configuration was updated.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format. Supported logging types are 'syslog'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.
401
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "appLogContainers": [
    "example-value"
  ],
  "appLogPaths": [
    "example-value"
  ],
  "caCert": "example-value",
  "endpoint": "https://example.com",
  "errors": [
    "example-value"
  ],
  "id": "example-id-123",
  "logSource": "example-value",
  "logSourceContainers": [
    "example-value"
  ],
  "logSourcePaths": [
    "example-value"
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Stops log forwarding by deleting a specified logging configuration.

DELETE /v1/logging/{id_or_name}/loggingconfig/{log_source}/{id}

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster get --cluster <cluster_name_or_ID>.

Path Parameters

log_source
Required*
string
The log source from which you want to forward logs. Supported values are container, worker, kubernetes, ingress, and application. If you do not provide a namespace for log source container, then all namespaces use this configuration.
id
Required*
string
The UUID of the logging configuration that you want to update.
id_or_name
Required*
string
The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Query Parameters

force_update
boolean
Forces the request which may cause a new fluentd version to be deployed to the cluster.

Example request

curl -X DELETE "/global/v1/logging/{id_or_name}/loggingconfig/{log_source}/{id}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
Ok. Logs will no longer be forwarded to the log server for the specified logging configuration.
401
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Refresh the logging configuration for a cluster. This refreshes the logging token for any logging configuration that is forwarding to the space level in your cluster.

PUT /v1/logging/{id_or_name}/refresh

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster get --cluster <cluster_name_or_ID>.

Path Parameters

id_or_name
Required*
string
The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Query Parameters

force_update
boolean
Forces the request which may cause a new fluentd version to be deployed to the cluster.

Example request

curl -X PUT "/global/v1/logging/my-cluster/refresh"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group-ID: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
Ok. A request was sent for the cluster's logging configuration to be refreshed.
401
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Check if automatic updates for the Fluentd logging add-on are enabled and whether your Fluentd pods are updated to the latest version.

GET /v1/logging/{id_or_name}/updatepolicy

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster get --cluster <cluster_name_or_ID>.

Path Parameters

id_or_name
Required*
string
The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v1/logging/{id_or_name}/updatepolicy"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

UpdatePolicy

Update policy

Status Code

200
Ok. The current update policy.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format. Supported logging types are 'syslog' and 'ibm'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.
401
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "autoUpdate": false,
  "latestVersion": false
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

By default, automatic updates to the Fluentd logging add-on are enabled. Fluentd pods are automatically updated when a new version is available. To instead update the add-on manually, you can use this call to disable automatic updates. If automatic updates for the Fluentd add-on are disabled, you can re-enable automatic updates. Whenever the next version becomes available, the Fluentd pods are automatically updated to the latest version.

PUT /v1/logging/{id_or_name}/updatepolicy

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster get --cluster <cluster_name_or_ID>.

Path Parameters

id_or_name
Required*
string
The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Request Body

Required*

UpdatePolicy

The new update policy configuration

Example request

curl -X PUT "/global/v1/logging/{id_or_name}/updatepolicy"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "autoUpdate": false,
  "latestVersion": false
}'
Copy to clipboard

Response

Status Code

204
Ok. The logging update policy has been changed.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format. Supported logging types are 'syslog' and 'ibm'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.
401
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the logging filter configurations that you created in a cluster.

GET /v1/logging/{id_or_name}/filterconfigs

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster get --cluster <cluster_name_or_ID>.

Path Parameters

id_or_name
Required*
string
The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Query Parameters

show_matches
boolean
Set to true to populate global filters with all matching logging configurations.

Example request

curl -X GET "/global/v1/logging/{id_or_name}/filterconfigs"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

string[]

FilterConfigResponse is how users will see their logging filter configs from API responses

Status Code

200
Ok. A list of logging filters in the cluster.
401
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "container": "example-value",
    "coveringFilters": [
      "example-value"
    ],
    "id": "example-id-123",
    "label": "example-value",
    "logLevel": "example-value",
    "loggingConfigs": [
      "example-value"
    ],
    "message": "example-value",
    "namespace": "my-cluster"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Start filtering logs that are forwarded by your logging configuration from the given sources based on one or more selectors.

POST /v1/logging/{id_or_name}/filterconfigs

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster get --cluster <cluster_name_or_ID>.

Path Parameters

id_or_name
Required*
string
The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Query Parameters

force_update
boolean
Forces the request which may cause a new fluentd version to be deployed to the cluster.

Request Body

Required*

FilterConfigBody

The new logging filter configuration.

Example request

curl -X POST "/global/v1/logging/{id_or_name}/filterconfigs"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "container": "example-value",
  "logLevel": "example-value",
  "loggingConfigs": [
    "example-value"
  ],
  "message": "example-value",
  "namespace": "my-cluster",
  "regexMessageEnabled": true,
  "type": "example-value"
}'
Copy to clipboard

Response

Response Body

FilterConfigResponse

FilterConfigResponse is how users will see their logging filter configs from API responses

Status Code

201
Ok. Logs from the specified logging configurations will be filtered on the provided selectors.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all of the required parameters, formatted in JSON. Supported logging types are 'syslog' and 'ibm'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.
401
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 201

{
  "container": "example-value",
  "coveringFilters": [
    "example-value"
  ],
  "id": "example-id-123",
  "label": "example-value",
  "logLevel": "example-value",
  "loggingConfigs": [
    "example-value"
  ],
  "message": "example-value",
  "namespace": "my-cluster"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Stops log filtering.

DELETE /v1/logging/{id_or_name}/filterconfigs

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster get --cluster <cluster_name_or_ID>.

Path Parameters

id_or_name
Required*
string
The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Query Parameters

force_update
boolean
Forces the request which may cause a new fluentd version to be deployed to the cluster.

Example request

curl -X DELETE "/global/v1/logging/{id_or_name}/filterconfigs"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
Ok. All log filtering configurations have been removed.
401
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View details for a logging filter configuration.

GET /v1/logging/{id_or_name}/filterconfigs/{id}

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster get --cluster <cluster_name_or_ID>.

Path Parameters

id
Required*
string
The UUID of the logging filter that you want to fetch.
id_or_name
Required*
string
The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Query Parameters

show_matches
boolean
To show matching logging configurations for global filters, set to true.

Example request

curl -X GET "/global/v1/logging/{id_or_name}/filterconfigs/{id}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

string

FilterConfigResponse is how users will see their logging filter configs from API responses

Status Code

200
Ok. A logging filter is configured for your cluster.
401
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "container": "example-value",
  "coveringFilters": [
    "example-value"
  ],
  "id": "example-id-123",
  "label": "example-value",
  "logLevel": "example-value",
  "loggingConfigs": [
    "example-value"
  ],
  "message": "example-value",
  "namespace": "my-cluster"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Update a logging filter config where id is the UUID for the filter config.

PUT /v1/logging/{id_or_name}/filterconfigs/{id}

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster get --cluster <cluster_name_or_ID>.

Path Parameters

id
Required*
string
The UUID of the logging filter that you want to fetch.
id_or_name
Required*
string
The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Query Parameters

force_update
boolean
Forces the request which may cause a new fluentd version to be deployed to the cluster.

Request Body

Required*

FilterConfigBody

The new filter configuration for the specified ID.

Example request

curl -X PUT "/global/v1/logging/{id_or_name}/filterconfigs/{id}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "container": "example-value",
  "logLevel": "example-value",
  "loggingConfigs": [
    "example-value"
  ],
  "message": "example-value",
  "namespace": "my-cluster",
  "regexMessageEnabled": true,
  "type": "example-value"
}'
Copy to clipboard

Response

Response Body

FilterConfigResponse

FilterConfigResponse is how users will see their logging filter configs from API responses

Status Code

200
Ok. The configuration was updated.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all of the required parameters, formatted in JSON. Supported logging types are 'syslog'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.
401
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "container": "example-value",
  "coveringFilters": [
    "example-value"
  ],
  "id": "example-id-123",
  "label": "example-value",
  "logLevel": "example-value",
  "loggingConfigs": [
    "example-value"
  ],
  "message": "example-value",
  "namespace": "my-cluster"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Delete the specified logging filter configuration for a cluster.

DELETE /v1/logging/{id_or_name}/filterconfigs/{id}

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster get --cluster <cluster_name_or_ID>.

Path Parameters

id
Required*
string
The UUID of the logging filter that you want to fetch.
id_or_name
Required*
string
The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Query Parameters

force_update
boolean
Forces the request which may cause a new fluentd version to be deployed to the cluster.

Example request

curl -X DELETE "/global/v1/logging/{id_or_name}/filterconfigs/{id}"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
Ok. Logs will no longer be filtered by the specified filter configuration.
401
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Add an NLB IP address to an existing NLB subdomain that you created. For example, in a multizone cluster, you create an NLB in each zone to expose an app. You registered an NLB IP in one zone with a subdomain by using the POST /clusters/{idOrName}/register call, so now you can add the NLB IPs from the other zones to this existing subdomain.

PUT /v1/nlb-dns/clusters/{id_or_name}/add

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

NlbConfig

The input parameter to update an NLB DNS record. Include only the nlbHost parameter to specify the existing NLB subdomain and the nlbIP parameter to specify the NLB IP you want to add.

Example request

curl -X PUT "/global/v1/nlb-dns/clusters/my-cluster/add"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "certProvider": "vpc-gen2",
  "clusterID": "example-id-123",
  "crn": "example-value",
  "isDefault": false,
  "nlbDnsType": "example-value",
  "nlbHost": "example-value",
  "nlbIPArray": [
    "example-value"
  ],
  "nlbMonitorState": "example-value"
}'
Copy to clipboard

Response

Status Code

204
Ok. The request to update the NLB subdomain was successfully processed.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster, NLB subdomain, or NLB IP address could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>. To list existing NLB IP addresses in a cluster, run kubectl get svc -n <namespace>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Remove an IP address from the DNS record for an existing NLB subdomain. If you remove all IPs from a hostname, the hostname still exists but no IPs are associated with it.

DELETE /v1/nlb-dns/clusters/{id_or_name}/host/{nlb_host}/ip/{nlb_ip}/remove

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
nlb_host
Required*
string
The existing NLB subdomain from which you want remove an NLB IP. To list existing NLB subdomains, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.
nlb_ip
Required*
string
The NLB IP address that you want to unregister from the DNS record for the hostname. To list the NLB IPs registered with NLB subdomains, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.

Example request

curl -X DELETE "/global/v1/nlb-dns/clusters/my-cluster/host/example-value/ip/example-value/remove"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
Deleted. The NLB IP address was successfully unregistered from the DNS record for the NLB subdomain.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster, NLB subdomain, or NLB IP address could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains and the NLB IPs registered with those hostnames, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

In a classic cluster, list NLB subdomains and the NLB IP addresses registered with the DNS provider for each subdomain.

GET /v1/nlb-dns/clusters/{id_or_name}/list

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v1/nlb-dns/clusters/my-cluster/list"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ClusterNlbHostsList

ClusterNlbHostsList used for storing Nlbs, NlbMonitor, NlbHealthCheckStatus

Status Code

200
Ok. A list of NLB subdomains and the NLB IPs associated with the DNS record for the subdomains is returned for this cluster.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "clusterid": "example-id-123",
  "nlbHealthCheckConfigs": [
    {
      "clusterID": "example-id-123",
      "healthCheckStatus": "example-value",
      "nlbHost": "example-value",
      "path": "example-value",
      "port": 443,
      "type": "example-value"
    }
  ],
  "nlbHealthCheckStatus": [
    {
      "clusterID": "example-id-123",
      "monitorState": "example-value",
      "monitorStatus": "example-value",
      "nlbHost": "example-value",
      "nlbIP": "example-value"
    }
  ],
  "nlbs": [
    {
      "certProvider": "vpc-gen2",
      "clusterID": "example-id-123",
      "crn": "example-value",
      "isDefault": false,
      "nlbDnsType": "example-value",
      "nlbHost": "example-value",
      "nlbIPArray": [
        "example-value"
      ],
      "nlbMonitorState": "example-value"
    }
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a new NLB subdomain and register NLB IP addresses with the DNS provider. If the registration fails, an error from the DNS provider is returned.

POST /v1/nlb-dns/clusters/{id_or_name}/register

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

NlbConfig

Include either the nlbIP or the nlbIPArray parameter that specifies the NLB IP address(es) that you want to register.

Example request

curl -X POST "/global/v1/nlb-dns/clusters/my-cluster/register"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "certProvider": "vpc-gen2",
  "clusterID": "example-id-123",
  "crn": "example-value",
  "isDefault": false,
  "nlbDnsType": "example-value",
  "nlbHost": "example-value",
  "nlbIPArray": [
    "example-value"
  ],
  "nlbMonitorState": "example-value"
}'
Copy to clipboard

Response

Response Body

NlbConfig

NlbConfig config for NLB configuration

Status Code

201
Created. The NLB subdomain was successfully created and the NLB IP addres(es) registered with DNS.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster or NLB IP address could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB IP addresses in a cluster, run kubectl get svc -n <namespace>.
500
Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "certProvider": "vpc-gen2",
  "clusterID": "example-id-123",
  "crn": "example-value",
  "isDefault": false,
  "nlbDnsType": "example-value",
  "nlbHost": "example-value",
  "nlbIPArray": [
    "example-value"
  ],
  "nlbMonitorState": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Enable or disable an existing health check monitor for an NLB subdomain.

PUT /v1/nlb-dns/clusters/{id_or_name}/health

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

NlbConfig

Include only the nlbHost parameter to specify the NLB subdomain and the nlbMonitorState parameter to specify the health check monitor as enabled or disabled.

Example request

curl -X PUT "/global/v1/nlb-dns/clusters/my-cluster/health"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "certProvider": "vpc-gen2",
  "clusterID": "example-id-123",
  "crn": "example-value",
  "isDefault": false,
  "nlbDnsType": "example-value",
  "nlbHost": "example-value",
  "nlbIPArray": [
    "example-value"
  ],
  "nlbMonitorState": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
Ok. Health check monitor enable/disable request for successfully processed.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster or NLB subdomain could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create and optionally enable a health check monitor for an existing NLB subdomain in a cluster.

PATCH /v1/nlb-dns/health/clusters/{id_or_name}/config

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Content-Type
string
Allowable values: [application/json,application/merge-patch+json]

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*

NlbHealthSetConfig

The input body to configure the health check monitor for an NLB subdomain. To enable the health check monitor, set monitorState to enabled. For more information about each healthcheckProperties parameter, see https://cloud.ibm.com/docs/containers?topic=containers-cli-plugin-kubernetes-service-cli#cs_nlb-dns-monitor-configure

Example request

curl -X PATCH "/global/v1/nlb-dns/health/clusters/my-cluster/config"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "allowInsecureSet": "example-value",
  "clusterID": "example-id-123",
  "createdOn": "2024-01-15T10:30:00Z",
  "desc": "example-value",
  "followRedirectSet": "example-value",
  "healtcheckPropertiesSetStatus": "example-value",
  "healthcheckProperties": {},
  "modifiedOn": "2024-01-15T10:30:00Z"
}'
Copy to clipboard

Response

Response Body

NlbHealthConfig

NlbHealthConfig config for NLB Health configuration

Status Code

201
Created. The health check monitor was successfully configured for the NLB subdomain.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster or NLB subdomain could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "allowInsecureSet": "example-value",
  "clusterID": "example-id-123",
  "createdOn": "2024-01-15T10:30:00Z",
  "desc": "example-value",
  "followRedirectSet": "example-value",
  "healtcheckPropertiesSetStatus": "example-value",
  "healthcheckProperties": {
    "allow_insecure": true,
    "expectedBody": "example-value",
    "expectedCodes": "example-value",
    "follow_redirects": false,
    "header": {},
    "interval": 1,
    "method": "example-value",
    "name": "my-cluster"
  },
  "modifiedOn": "2024-01-15T10:30:00Z"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View the health check monitor settings for an NLB subdomain.

GET /v1/nlb-dns/health/clusters/{id_or_name}/host/{nlb_host}/config

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
nlb_host
Required*
string
The NLB subdomain that you want health check monitor settings for. To list existing NLB subdomains, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.

Example request

curl -X GET "/global/v1/nlb-dns/health/clusters/my-cluster/host/example-value/config"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

NlbHealthConfig

NlbHealthConfig config for NLB Health configuration

Status Code

200
Ok. Health check monitor settings for the specified NLB subdomain are returned.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster or NLB subdomain could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "allowInsecureSet": "example-value",
  "clusterID": "example-id-123",
  "createdOn": "2024-01-15T10:30:00Z",
  "desc": "example-value",
  "followRedirectSet": "example-value",
  "healtcheckPropertiesSetStatus": "example-value",
  "healthcheckProperties": {
    "allow_insecure": true,
    "expectedBody": "example-value",
    "expectedCodes": "example-value",
    "follow_redirects": false,
    "header": {},
    "interval": 1,
    "method": "example-value",
    "name": "my-cluster"
  },
  "modifiedOn": "2024-01-15T10:30:00Z"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the settings for all existing health check monitors in a cluster.

GET /v1/nlb-dns/health/clusters/{id_or_name}/list

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v1/nlb-dns/health/clusters/my-cluster/list"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ClusterNlbHostsList

ClusterNlbHostsList used for storing Nlbs, NlbMonitor, NlbHealthCheckStatus

Status Code

200
Ok. The health check monitor settings for each NLB subdomain in the cluster are returned.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "clusterid": "example-id-123",
  "nlbHealthCheckConfigs": [
    {
      "clusterID": "example-id-123",
      "healthCheckStatus": "example-value",
      "nlbHost": "example-value",
      "path": "example-value",
      "port": 443,
      "type": "example-value"
    }
  ],
  "nlbHealthCheckStatus": [
    {
      "clusterID": "example-id-123",
      "monitorState": "example-value",
      "monitorStatus": "example-value",
      "nlbHost": "example-value",
      "nlbIP": "example-value"
    }
  ],
  "nlbs": [
    {
      "certProvider": "vpc-gen2",
      "clusterID": "example-id-123",
      "crn": "example-value",
      "isDefault": false,
      "nlbDnsType": "example-value",
      "nlbHost": "example-value",
      "nlbIPArray": [
        "example-value"
      ],
      "nlbMonitorState": "example-value"
    }
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Deprecated: List the health check status (healthy or not healthy) that is returned by the monitors for the IPs behind all NLB subdomains in a cluster.

GET /v1/nlb-dns/health/clusters/{id_or_name}/status

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

id_or_name
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v1/nlb-dns/health/clusters/my-cluster/status"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ClusterNlbHostsList

ClusterNlbHostsList used for storing Nlbs, NlbMonitor, NlbHealthCheckStatus

Status Code

200
Ok. An array that contains the NlbHealthCheckStatus is returned.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "clusterid": "example-id-123",
  "nlbHealthCheckConfigs": [
    {
      "clusterID": "example-id-123",
      "healthCheckStatus": "example-value",
      "nlbHost": "example-value",
      "path": "example-value",
      "port": 443,
      "type": "example-value"
    }
  ],
  "nlbHealthCheckStatus": [
    {
      "clusterID": "example-id-123",
      "monitorState": "example-value",
      "monitorStatus": "example-value",
      "nlbHost": "example-value",
      "nlbIP": "example-value"
    }
  ],
  "nlbs": [
    {
      "certProvider": "vpc-gen2",
      "clusterID": "example-id-123",
      "crn": "example-value",
      "isDefault": false,
      "nlbDnsType": "example-value",
      "nlbHost": "example-value",
      "nlbIPArray": [
        "example-value"
      ],
      "nlbMonitorState": "example-value"
    }
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View whether a user can create free and paid clusters in a region and resource group. If "freeEnabled": true is returned, you can create a free cluster in the specified region. If "storedIaasCredentials": true is returned, your IBM Cloud account uses IBM Cloud infrastructure (SoftLayer) credentials that were manually set with the POST /v1/credentials API or the ibmcloud ks credential set command. When you create a standard cluster in the specified region and resource group, these credentials are used.

GET /v1/user-config

Request

Custom Headers

X-Region
Required*
string
Target the IBM Cloud Kubernetes Service region where you want to check the ability to create free and standard clusters. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

Example request

curl -X GET "/global/v1/user-config"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

UserConfig

UserConfig describes the config values applicable to a user account

Status Code

200
Ok. The user's permissions to create free and paid clusters is returned.

Example responses

Status 200

{
  "freeEnabled": true,
  "storedIaasCredentials": false
}
Copy to clipboard

Ignore specific ingress status errors in ingress status reporting. Ignored errors will not affect the cluster's ingress status state.

POST /v2/alb/addIgnoredIngressStatusErrors

Request

Request Body

Required*

IgnoredIngressStatusErrors

Ingress status errors that are ignored for ingress status reporting.

Example request

curl -X POST "/global/v2/alb/addIgnoredIngressStatusErrors"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "ignoredErrors": [
    "example-value"
  ]
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
Ignored ingress status errors were successfully added to the ingress status configuration.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
404
Not found. The specified cluster could not be found.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View detailed information for an ALB in a VPC or classic cluster. An ALBConfig response will be returned for ALBs in classic clusters.

GET /v2/alb/getAlb

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. This parameter is required for any resource group other than the default. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Query Parameters

alb_id
Required*
string
The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the GET /v2/alb/getClusterAlbs API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.

Example request

curl -X GET "/global/v2/alb/getAlb?alb_id=example-id-123"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ALBConfig

ALBConfig config for alb configuration

Status Code

200
Ok. Details for the specified ALB are returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster or ALB could not be found. To list the classic clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.
500
Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "albBuild": "example-value",
  "albID": "example-id-123",
  "albType": "example-value",
  "authBuild": "example-value",
  "cluster": "example-value",
  "createdDate": "2024-01-15T10:30:00Z",
  "disableDeployment": false,
  "enable": true
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the community Kubernetes Ingress controller and IBM Cloud Kubernetes Service ALB images that are supported.

GET /v2/alb/getAlbImages

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET "/global/v2/alb/getAlbImages"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

string[]

Status Code

200
Ok. A list of supported Ingress controller images is returned.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to list supported Ingress controller images.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

[ "example-value" ]

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List all ALBs in a VPC or classic cluster. A ClusterALB response will be returned for classic clusters.

Note: If no ALB IDs are returned for a VPC cluster, no VPC load balancer exists for the ALBs. If no ALB IDs are returned for a classic cluster, no available portable subnet exists in the VLANs that your ALBs are on.

GET /v2/alb/getClusterAlbs

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Query Parameters

cluster
Required*
string
To list the classic clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.

Example request

curl -X GET "/global/v2/alb/getClusterAlbs?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ClusterALB

ClusterALB alb related information for cluster

Status Code

200
Ok. A list of ALBs for the cluster is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the classic clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.
500
Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "alb": [
    {
      "albBuild": "example-value",
      "albID": "example-id-123",
      "albType": "example-value",
      "authBuild": "example-value",
      "cluster": "example-value",
      "createdDate": "2024-01-15T10:30:00Z",
      "disableDeployment": false,
      "enable": true
    }
  ],
  "dataCenter": "example-value",
  "id": "example-id-123",
  "ingressHostname": "my-cluster",
  "ingressSecretName": "my-cluster",
  "isPaid": false,
  "region": "us-south"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Check the status of the in-cluster ALB health checker.

GET /v2/alb/getIngressClusterHealthcheck

Request

Query Parameters

cluster
Required*
string
The name or ID of the cluster.

Example request

curl -X GET "/global/v2/alb/getIngressClusterHealthcheck?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ALBClusterHealthCheckConfig

ALBClusterHealthCheckConfig status of alb healthcheck

Status Code

200
Ok. The in-cluster ALB health checker status for your cluster is returned.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
404
Not found. The specified cluster could not be found.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "cluster": "example-value",
  "enable": true
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Check the status of the IBM provided subdomain and application load balancers

GET /v2/alb/getStatus

Request

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want information about.

Example request

curl -X GET "/global/v2/alb/getStatus?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Status

Status struct for the top level ingress status, for a cluster

Status Code

200
Ok. The ingress status for your cluster is returned.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
404
Not found. The specified cluster could not be found.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "StatusList": [
    {
      "component": "example-value",
      "status": "example-value",
      "type": "example-value"
    }
  ],
  "albStatus": [
    {
      "component": "example-value",
      "status": [
        "example-value"
      ]
    }
  ],
  "cluster": "example-value",
  "enabled": true,
  "generalComponentStatus": [
    {
      "component": "example-value",
      "status": [
        "example-value"
      ]
    }
  ],
  "ignoredErrors": [
    "example-value"
  ],
  "message": "example-value",
  "nonTranslatedStatus": "example-value",
  "routerStatus": [
    {
      "component": "example-value",
      "status": [
        "example-value"
      ]
    }
  ],
  "secretStatus": [
    {
      "component": "example-value",
      "status": [
        "example-value"
      ]
    }
  ],
  "subdomainStatus": [
    {
      "component": "example-value",
      "status": [
        "example-value"
      ]
    }
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List all ingress status errors that are ignored for the cluster. If no ignored errors are returned, then the cluster does not have ignored ingress status errors.

GET /v2/alb/listIgnoredIngressStatusErrors

Request

Query Parameters

cluster
Required*
string
The name or ID of the cluster.

Example request

curl -X GET "/global/v2/alb/listIgnoredIngressStatusErrors?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

IgnoredIngressStatusErrors

IgnoredIngressStatusErrors is used to ignore errors for ingress status

Status Code

200
Ok. All ignored ingress status errors for your cluster are returned.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
404
Not found. The specified cluster could not be found.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "cluster": "example-value",
  "ignoredErrors": [
    "example-value"
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Unignore specific ingress status errors in ingress status reporting. Unignored errors will affect the cluster's ingress status state.

DELETE /v2/alb/removeIgnoredIngressStatusErrors

Request

Request Body

Required*

IgnoredIngressStatusErrors

Ingress status errors that are ignored for ingress status reporting.

Example request

curl -X DELETE "/global/v2/alb/removeIgnoredIngressStatusErrors"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "ignoredErrors": [
    "example-value"
  ]
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
Ignored ingress status errors were successfully removed from the ingress status configuration.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
404
Not found. The specified cluster could not be found.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Set the in-cluster ingress health checker state. It can be either enabled or disabled.

POST /v2/alb/setIngressClusterHealthcheck

Request

Request Body

Required*

ALBClusterHealthCheckConfig

The desired state of the in-cluster ingress health checker.

Example request

curl -X POST "/global/v2/alb/setIngressClusterHealthcheck"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "enable": true
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
Set successfully finished.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
404
Not found. The specified cluster could not be found.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Set the state of the ingress status for a cluster. It can be either enabled or disabled.

POST /v2/alb/setIngressStatusState

Request

Request Body

Required*

StatusState

The desired state of ingress status.

Example request

curl -X POST "/global/v2/alb/setIngressStatusState"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "enable": true
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
Set successfully finished.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
404
Not found. The specified cluster could not be found.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Update one or more public or private ALBs to a supported IBM Cloud Kubernetes Service ALB image or a supported community Kubernetes Ingress controller image. To update your ALB to a specified image version, automatic updates must be disabled. You can check the automatic update status by using the GET /v1/alb/clusters/{idOrName}/updatepolicy call. NOTE: You cannot use this call to switch your ALB from one type of image to another, such as from an IBM Cloud Kubernetes Service ALB image to a community Kubernetes Ingress controller image. Instead, first disable the ALB by using the DELETE /v1/alb/albs/{albID} call (classic) or the POST /v2/alb/vpc/disableAlb call (VPC). Then, enable the ALB by using the POST /v1/alb/albs (classic) or POST /v2/alb/vpc/enableAlb (VPC) call, and include the ALB image that you want to switch to in the input parameter.

POST /v2/alb/updateAlb

Request

Request Body

Required*

V2UpdateALB

The input parameter to update an ALB's image. To see the supported image versions, use the GET /v2/alb/getAlbImages call.

Example request

curl -X POST "/global/v2/alb/updateAlb"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "albBuild": "example-value",
  "albList": [
    "example-value"
  ],
  "cluster": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
Updated. The ALBs in the cluster were successfully updated.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
404
Not found. The specified cluster or ALB could not be found.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a new public or private ALB in a specified zone and VPC cluster.

POST /v2/alb/vpc/createAlb

Request

Request Body

Required*

ALB

The input parameters to create an ALB. For more information, see https://ibm.biz/alb_create_vpc

Example request

curl -X POST "/global/v2/alb/vpc/createAlb"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "enableByDefault": true,
  "ingressImage": "example-value",
  "ip": "example-value",
  "nlbVersion": "1.28.5",
  "type": "example-value",
  "vlanID": "example-id-123",
  "zone": "us-south-1"
}'
Copy to clipboard

Response

Response Body

AlbCreateResp

AlbCreateResp used to send back the albid on a create request

Status Code

201
The ALB was successfully created.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
404
Not found. The specified cluster or zone could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic. To list the zones available in a VPC cluster, use the GET /v2/vpc/getCluster API or run ibmcloud ks cluster-get --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "alb": "example-value",
  "cluster": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Disable a public or private ALB in your VPC cluster.

POST /v2/alb/vpc/disableAlb

Request

Request Body

Required*

ALBConfig

The input parameters to disable an ALB. DisableDeployment and albID are required. For more information, see https://ibm.biz/alb_configure_vpc

Example request

curl -X POST "/global/v2/alb/vpc/disableAlb"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "albBuild": "example-value",
  "albID": "example-id-123",
  "albType": "example-value",
  "authBuild": "example-value",
  "cluster": "example-value",
  "createdDate": "2024-01-15T10:30:00Z",
  "disableDeployment": false,
  "enable": true
}'
Copy to clipboard

Response

Status Code

204
Disabled. The ALB for the cluster was successfully disabled.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster or ALB could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic. To list the ALBs in a cluster, use the GET /v2/alb/getClusterAlbs API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Enable a public or private ALB in your VPC cluster.

POST /v2/alb/vpc/enableAlb

Request

Request Body

Required*

ALBConfig

The input parameter to enable an ALB. AlbID is required. To switch your ALB from one type of image to another, such as from an IBM Cloud Kubernetes Service ALB image to a community Kubernetes Ingress controller image, specify that image version in the ALBBuild field. To see the supported image versions, use the GET /v2/alb/getAlbImages call. For more information, see https://ibm.biz/alb_configure_vpc

Example request

curl -X POST "/global/v2/alb/vpc/enableAlb"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "albBuild": "example-value",
  "albID": "example-id-123",
  "albType": "example-value",
  "authBuild": "example-value",
  "cluster": "example-value",
  "createdDate": "2024-01-15T10:30:00Z",
  "disableDeployment": false,
  "enable": true
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

201
Enabled. The ALB for the cluster was successfully enabled.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
404
Not found. The specified cluster or ALB could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic. To list the ALBs in a cluster, use the GET /v2/alb/getClusterAlbs API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Apply IAM roles corresponding to your access to the cluster as RoleBindings and ClusterRoleBindings as described in http://ibm.biz/rbac-access. For example, if you have the IAM Viewer role, you will be granted the ibm-view role in the cluster. The roles are applied asynchronously. Use /v2/getRBACStatus to verify when they have finished applying.

POST /v2/applyRBAC

Request

Custom Headers

X-Auth-Refresh-Token
string
Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Request Body

Required*

Kubeconfig

Options to retrieve a kubeconfig file. Default format is 'json', other options include 'yaml' and 'zip'. To retrieve the Calico network config, pass admin:true and format:"zip" in the body.

Example request

curl -X POST "/global/v2/applyRBAC"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "admin": false,
  "cluster": "example-value",
  "endpointType": "https://example.com",
  "format": "example-value",
  "network": false
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

202
Accepted. Applies IAM roles asynchronously.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Apply IAM roles corresponding to your access to the cluster as RoleBindings and ClusterRoleBindings as described in http://ibm.biz/rbac-access, then retrieve the cluster's kubeconfig file to connect to your cluster and run Kubernetes API calls. For example, if you have the IAM Viewer role, you will be granted the ibm-view role in the cluster and your kubeconfig will allow 'view' Kubernetes API calls. The roles are applied asynchronously. Use /v2/getRBACStatus to verify when they have finished applying.

POST /v2/applyRBACAndGetKubeconfig

Request

Custom Headers

X-Auth-Refresh-Token
string
Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.
Accept
string
Allowable values: [application/json,application/zip,text/yaml]

Request Body

Required*

Kubeconfig

Options to retrieve a kubeconfig file. Default format is 'json', other options include 'yaml' and 'zip'. To retrieve the Calico network config, pass admin:true and format:"zip" in the body.

Example request

curl -X POST "/global/v2/applyRBACAndGetKubeconfig"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "admin": false,
  "cluster": "example-value",
  "endpointType": "https://example.com",
  "format": "example-value",
  "network": false
}'
Copy to clipboard

Response

Response Body

ClientKubeConfig

ClientKubeConfig is the kubernetes config file used by kubectl

Status Code

200
Ok. Returns the cluster's kubeconfig file.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "apiVersion": "1.28.5",
  "clusters": [
    {
      "cluster": {
        "certificate-authority": "example-value",
        "certificate-authority-data": "example-value",
        "disable-compression": false,
        "insecure-skip-tls-verify": true,
        "proxy-url": "https://example.com",
        "server": "example-value",
        "tls-server-name": "my-cluster"
      },
      "name": "my-cluster"
    }
  ],
  "contexts": [
    {
      "context": {
        "cluster": "example-value",
        "namespace": "my-cluster",
        "user": "example-value"
      },
      "name": "my-cluster"
    }
  ],
  "current-context": "example-value",
  "kind": "example-value",
  "preferences": {
    "colors": false
  },
  "users": [
    {
      "name": "my-cluster",
      "user": {
        "as": "example-value",
        "as-groups": [
          "example-value"
        ],
        "as-uid": "example-id-123",
        "as-user-extra": {},
        "auth-provider": {
          "config": {},
          "name": "my-cluster"
        },
        "client-certificate": "example-value",
        "client-certificate-data": "example-value",
        "client-key": "example-value"
      }
    }
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Set the autoupdate status of the cluster master. Only a limited set of users can access use this API.

POST /v2/autoUpdateMaster

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*

AutoUpdateMaster

Input parameters to specify the name or ID of the cluster and whether to enable or disable auto master updates. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X POST "/global/v2/autoUpdateMaster"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "autoUpdate": false,
  "cluster": "example-value"
}'
Copy to clipboard

Response

Status Code

204
Ok. The request was processed successfully.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The user doesn't have access to this API.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
409
Conflict. The specified value is already set on the cluster. To list the clusters properties, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Detailed cluster information.

GET /v2/classic/getCluster

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group to list clusters for. To list available resource groups, run ibmcloud resource groups. If you don't include this header, all the clusters in the account that you have access to are listed.

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
show_resources
string
To view additional cluster resources like addons, VLANs, subnets, and storage, pass true.

Example request

curl -X GET "/global/v2/classic/getCluster?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetClusterResponse

Get cluster response

Status Code

200
Success. Detailed cluster information.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "addons": [
    {
      "name": "my-cluster",
      "version": "1.28.5"
    }
  ],
  "caCertRotationStatus": {
    "actionCompletedDate": "2024-01-15T10:30:00Z",
    "actionTriggerDate": "2024-01-15T10:30:00Z",
    "status": "example-value"
  },
  "calicoIPAutodetectionConfig": "example-value",
  "createdDate": "2024-01-15T10:30:00Z",
  "crn": "example-value",
  "datacenter": "example-value",
  "desiredTrustedProfileID": "example-id-123",
  "disableAutoUpdate": false,
  "id": "example-id-123",
  "locationZones": [
    "us-south"
  ],
  "supportedOperatingSystems": [
    "example-value"
  ],
  "vpcs": [
    "example-value"
  ],
  "workerZones": [
    "us-south-1"
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the classic clusters that you have access to.

GET /v2/classic/getClusters

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group to list clusters for. To list available resource groups, run ibmcloud resource groups. If you don't include this header, all the clusters in the account that you have access to are listed.

Query Parameters

location
string
Specify a location to filter clusters for. To see supported locations, use the GET /v1/locations API or run ibmcloud ks locations.
show_resources
string
To view additional cluster resources like addons, VLANs, subnets, and storage, pass true.

Example request

curl -X GET "/global/v2/classic/getClusters"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetClustersResponse[]

GetClustersResponse cluster response for cluster list

Status Code

200
Success. A list of clusters that you have access to is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "addons": [
      {
        "name": "my-cluster",
        "version": "1.28.5"
      }
    ],
    "caCertRotationStatus": {
      "actionCompletedDate": "2024-01-15T10:30:00Z",
      "actionTriggerDate": "2024-01-15T10:30:00Z",
      "status": "example-value"
    },
    "calicoIPAutodetectionConfig": "example-value",
    "createdDate": "2024-01-15T10:30:00Z",
    "datacenter": "example-value",
    "desiredTrustedProfileID": "example-id-123",
    "entitlement": "example-value",
    "etcdPort": "example-value",
    "id": "example-id-123"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get if VRF and Service Endpoint is enabled for the given account in the selected region.

GET /v2/classic/getPrivateServiceEnabled

Request

Custom Headers

X-Region
Required*
string
Specify the region to check for private service enablement.

Example request

curl -X GET "/global/v2/classic/getPrivateServiceEnabled"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

PrivateServiceEndpointEnabled

PrivateServiceEndpointEnabled is a status from the softlayer for the used account OR for the attached infrastructure account in the actual region

Status Code

200
Ok. Detailed information about the private service enablement.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Not authorized to use this command. Only a limited group of early adopters have access to this feature. If you are sure that you are part of the limited group of early adopters, contact IBM Cloud support..
500
Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{ "isPrivateServiceEnabled": true }

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List available public and private VLANs for a specified zone (data center). Before using this operation, you must store your IBM Cloud classic infrastructure credentials in each Kubernetes Service account by using the POST /v1/credentials API or by running ibmcloud ks credential set --infrastructure-api-key <API_key> --infrastructure-username <API_username>.

GET /v2/classic/getVLANs

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group to target.

Query Parameters

zone
Required*
string
The ID of the zone where you want to list available public and private VLANs. To list available zones, run ibmcloud ks zone ls or use the GET /v1/datacenters API.

Example request

curl -X GET "/global/v2/classic/getVLANs?zone=us-south-1"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

VLAN[]

VLANS is a helper type to sort an api.VLAN list. The VLANS will sort the list in order of the Properties.PrimaryRouter value so that VLAN's of a common router are listed consecutively.

Status Code

200
Ok. A list of all VLANs is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions for the infrastructure provider.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "id": "example-id-123",
    "properties": {
      "local_disk_storage_capability": "example-value",
      "location": "us-south",
      "name": "my-cluster",
      "note": "example-value",
      "primary_router": "example-value",
      "san_storage_capability": "example-value",
      "subnet_count": 3,
      "vlan_number": "example-value"
    },
    "type": "example-value"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View detailed information for a worker node in a classic cluster.

GET /v2/classic/getWorker

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
worker
Required*
string
The ID of the worker node that you want details for. To list all worker nodes for a cluster, use the GET /v1/clusters/{idOrName}/workers API or run ibmcloud ks workers <cluster_name_or_ID>.

Example request

curl -X GET "/global/v2/classic/getWorker?cluster=example-value&worker=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetClassicWorkerResponse

Get classic worker response

Status Code

200
Ok. Detailed information about the worker node is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks clusters.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "dedicatedHostId": "example-id-123",
  "dedicatedHostPoolId": "example-id-123",
  "flavor": "example-value",
  "health": {
    "message": "example-value",
    "state": "example-value"
  },
  "id": "example-id-123",
  "kubeVersion": {
    "actual": "example-value",
    "desired": "example-value",
    "eos": "example-value",
    "masterEOS": "example-value",
    "target": "example-value"
  },
  "lifecycle": {
    "actualOperatingSystem": "example-value",
    "actualState": "example-value",
    "desiredOperatingSystem": "example-value",
    "desiredState": "example-value",
    "message": "example-value",
    "messageDate": "2024-01-15T10:30:00Z",
    "messageDetails": "example-value",
    "messageDetailsDate": "2024-01-15T10:30:00Z"
  },
  "location": "us-south"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View detailed information for a worker pool in a classic cluster.

GET /v2/classic/getWorkerPool

Request

Custom Headers

X-Region
string
If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
workerpool
Required*
string
The ID of the worker pool that you want details for. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.

Example request

curl -X GET "/global/v2/classic/getWorkerPool?cluster=example-value&workerpool=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "X-Auth-Resource-Group: example-id-123"
Copy to clipboard

Response

Response Body

GetClassicWorkerPoolResponse

Get classic worker pool response

Status Code

200
Ok. Detailed information about the worker pool is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "autoscaleEnabled": true,
  "dedicatedHostPoolId": "example-id-123",
  "flavor": "example-value",
  "flavorState": "example-value",
  "hostLabels": {},
  "id": "example-id-123",
  "isBalanced": false,
  "isolation": "example-value",
  "zones": [
    {
      "id": "example-id-123",
      "privateVlan": "example-value",
      "publicVlan": "example-value",
      "workerCount": 3
    }
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View detailed information for a worker pool in a classic cluster.

GET /v2/classic/getWorkerPools

Request

Custom Headers

X-Region
string
If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v2/classic/getWorkerPools?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "X-Auth-Resource-Group: example-id-123"
Copy to clipboard

Response

Response Body

GetClassicWorkerPoolResponse[]

Get classic worker pool response

Status Code

200
Ok. Detailed information about the worker pools is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "autoscaleEnabled": true,
    "dedicatedHostPoolId": "example-id-123",
    "flavor": "example-value",
    "flavorState": "example-value",
    "hostLabels": {},
    "id": "example-id-123",
    "isBalanced": false,
    "isolation": "example-value",
    "zones": [
      {
        "id": "example-id-123",
        "privateVlan": "example-value",
        "publicVlan": "example-value",
        "workerCount": 3
      }
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View detailed information for all worker nodes in a classic cluster.

GET /v2/classic/getWorkers

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks clusters.
show_deleted
string
true|false Shows deleted workers
pool
string
The name or ID of the worker pool to filter results for. Run ibmcloud ks worker-pool ls --cluster <cluster name>.

Example request

curl -X GET "/global/v2/classic/getWorkers?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetClassicWorkerResponse[]

Get classic workers response

Status Code

200
Ok. Details for all workers in the classic cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks clusters.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "dedicatedHostId": "example-id-123",
    "dedicatedHostPoolId": "example-id-123",
    "flavor": "example-value",
    "health": {
      "message": "example-value",
      "state": "example-value"
    },
    "id": "example-id-123",
    "kubeVersion": {
      "actual": "example-value",
      "desired": "example-value",
      "eos": "example-value",
      "masterEOS": "example-value",
      "target": "example-value"
    },
    "lifecycle": {
      "actualOperatingSystem": "example-value",
      "actualState": "example-value",
      "desiredOperatingSystem": "example-value",
      "desiredState": "example-value",
      "message": "example-value",
      "messageDate": "2024-01-15T10:30:00Z",
      "messageDetails": "example-value",
      "messageDetailsDate": "2024-01-15T10:30:00Z"
    },
    "location": "us-south"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a dedicated host.

POST /v2/createDedicatedHost

Request

Request Body

Required*

CreateDedicatedHost

The required dedicated host parameters.

Example request

curl -X POST "/global/v2/createDedicatedHost"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "flavor": "example-value",
  "hostPoolID": "example-id-123",
  "zone": "us-south-1"
}'
Copy to clipboard

Response

Response Body

CreateDedicatedHostResponse

Create dedicated host response

Status Code

201
Created. The dedicated host was successfully created.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
409
Conflict. A dedicated host create may already be in progress. Please wait a few minutes and try again.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{ "id": "example-id-123" }

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a dedicated host pool.

POST /v2/createDedicatedHostPool

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group to create the dedicated host pool in. To list available resource groups, run ibmcloud resource groups. If this header is not included, the dedicated host pool is created in the default resource group.

Request Body

Required*

CreateDedicatedHostPool

The required dedicated host pool parameters.

Example request

curl -X POST "/global/v2/createDedicatedHostPool"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "flavorClass": "example-value",
  "metro": "example-value",
  "name": "my-cluster"
}'
Copy to clipboard

Response

Response Body

CreateDedicatedHostResponse

Create dedicated host response

Status Code

201
Created. The dedicated host pool was successfully created.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
409
Conflict. Creation of a dedicated host might already be in progress. Please wait a few minutes and try again.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{ "id": "example-id-123" }

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Disable placement of worker nodes on a dedicated host.

POST /v2/disableDedicatedHostPlacement

Request

Request Body

Required*

UpdateDedicatedHost

The dedicated host pool and host to disable placement on.

Example request

curl -X POST "/global/v2/disableDedicatedHostPlacement"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "hostID": "example-id-123",
  "hostPoolID": "example-id-123"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
OK. The dedicated host placement was successfully disabled.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Enable placement of worker nodes on a dedicated host.

POST /v2/enableDedicatedHostPlacement

Request

Request Body

Required*

UpdateDedicatedHost

The dedicated host pool and host to enable placement on.

Example request

curl -X POST "/global/v2/enableDedicatedHostPlacement"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "hostID": "example-id-123",
  "hostPoolID": "example-id-123"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
OK. The dedicated host placement was successfully enabled.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Enables a key management service (KMS) provider, such as IBM Key Protect, in a cluster. You cannot later disable KMS encryption, so make sure not to delete the KMS instance that you use to encrypt the cluster.

POST /v2/enableKMS

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*

EnableKMSRequest

Input parameters to create the Key Protect config for your cluster.

Example request

curl -X POST "/global/v2/enableKMS"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "account_id": "example-id-123",
  "cluster": "example-value",
  "crk_id": "example-id-123",
  "instance_id": "example-id-123",
  "private_endpoint": false
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
Ok. The requested KMS configuration has been enabled on the cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster or worker could not be found. To list the clusters that you have access to, use the GET /vpc/v2/clusters API or run ibmcloud ks cluster ls --provider vpc-classic.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get the cluster's CA cert to configure services with it to connect to the given cluster.

GET /v2/getCACert

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get CA cert from. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v2/getCACert?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
Ok. Returns the cluster's CA cert.
400
Bad request. The query parameters are either incomplete or in the wrong format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List all the customer root keys (CRKs) for a Key Management Service (KMS) instance, such as a Key Protect service instance, in your IBM Cloud account.

GET /v2/getCRKs

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group. To list available resource group IDs, run ibmcloud resource groups.

Query Parameters

kms_instance
Required*
string
The KMS instance ID to list root keys for. To list available Key Protect service instances, run ibmcloud ks kms instance ls.

Example request

curl -X GET "/global/v2/getCRKs?kms_instance=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

string[]

GetCRKResponse is data returned by a getCRKs request call

Status Code

200
Ok. A list of available root keys in the KMS instance is returned.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster or worker could not be found. To list the clusters that you have access to, use the GET /vpc/v2/clusters API or run ibmcloud ks cluster ls --provider vpc-classic.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "crk_id": "example-id-123",
    "crn": "example-value",
    "keyRingID": "example-id-123",
    "name": "my-cluster"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View detailed information for a cluster, including a VPC cluster.

GET /v2/getCluster

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group to list clusters for. To list available resource groups, run ibmcloud resource groups. If you don't include this header, all the clusters in the account that you have access to are listed.

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.

Example request

curl -X GET "/global/v2/getCluster?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetClusterResponse

Get cluster response

Status Code

200
Success. Detailed cluster information is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "addons": [
    {
      "name": "my-cluster",
      "version": "1.28.5"
    }
  ],
  "caCertRotationStatus": {
    "actionCompletedDate": "2024-01-15T10:30:00Z",
    "actionTriggerDate": "2024-01-15T10:30:00Z",
    "status": "example-value"
  },
  "calicoIPAutodetectionConfig": "example-value",
  "createdDate": "2024-01-15T10:30:00Z",
  "crn": "example-value",
  "datacenter": "example-value",
  "desiredTrustedProfileID": "example-id-123",
  "disableAutoUpdate": false,
  "id": "example-id-123",
  "locationZones": [
    "us-south"
  ],
  "supportedOperatingSystems": [
    "example-value"
  ],
  "vpcs": [
    "example-value"
  ],
  "workerZones": [
    "us-south-1"
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View details of the add-ons that are enabled in a cluster, including the add-on versions.

GET /v2/getClusterAddons

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group of the cluster, use the GET /v1/clusters/{idOrName} API.

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v2/getClusterAddons?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

string[]

ClusterAddon is an enabled add on in the cluster

Status Code

200
OK. Details for the add-ons in this cluster are returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "allowedUpgradeVersions": [
      "1.28.5"
    ],
    "defaultVersions": [
      {
        "infrastructureProvider": [
          "vpc-gen2"
        ],
        "kubeRange": "1.28.5",
        "ocpRange": "example-value",
        "openShiftVSRange": "example-value",
        "version": "1.28.5"
      }
    ],
    "deprecated": false,
    "healthState": "example-value",
    "healthStatus": "example-value",
    "installOptionsTemplate": {
      "content": "example-value",
      "immutable": false
    },
    "name": "my-cluster",
    "options": "example-value"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View detailed information for a dedicated host.

GET /v2/getDedicatedHost

Request

Custom Headers

X-Region
string
If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

Query Parameters

dedicatedhost
Required*
string
The ID of the dedicated host that you want details for..
dedicatedhostpool
Required*
string
The ID of the dedicated host pool that you want to get the dedicated host details from.

Example request

curl -X GET "/global/v2/getDedicatedHost?dedicatedhost=example-value&dedicatedhostpool=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetDedicatedHost

Get dedicated host

Status Code

200
Ok. Detailed information about the dedicated host is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified dedicated host could not be found.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "flavor": "example-value",
  "id": "example-id-123",
  "lifecycle": {
    "actualState": "example-value",
    "createdDate": "2024-01-15T10:30:00Z",
    "desiredState": "example-value",
    "message": "example-value",
    "messageDate": "2024-01-15T10:30:00Z",
    "messageDetails": "example-value",
    "messageDetailsDate": "2024-01-15T10:30:00Z"
  },
  "placementEnabled": true,
  "resources": {
    "capacity": {
      "memoryBytes": 1,
      "vcpu": 1
    },
    "consumed": {
      "memoryBytes": 1,
      "vcpu": 1
    }
  },
  "workers": [
    {
      "clusterID": "example-id-123",
      "flavor": "example-value",
      "workerID": "example-id-123",
      "workerPoolID": "example-id-123"
    }
  ],
  "zone": "us-south-1"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View detailed information for a dedicated host pool.

GET /v2/getDedicatedHostPool

Request

Custom Headers

X-Region
string
If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

Query Parameters

dedicatedhostpool
Required*
string
The ID of the dedicated host pool that you want to get.

Example request

curl -X GET "/global/v2/getDedicatedHostPool?dedicatedhostpool=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetDedicatedHostPool

Get dedicated host pool

Status Code

200
Ok. Detailed information about the dedicated host pool is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified dedicated host could not be found.
500
Internal Server Error. The IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "flavorClass": "example-value",
  "hostCount": 3,
  "id": "example-id-123",
  "metro": "example-value",
  "name": "my-cluster",
  "state": "example-value",
  "workerPools": [
    {
      "clusterID": "example-id-123",
      "workerPoolID": "example-id-123"
    }
  ],
  "zones": [
    {
      "capacity": {
        "memoryBytes": 1,
        "vcpu": 1
      },
      "hostCount": 3,
      "zone": "us-south-1"
    }
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the dedicated host pools.

GET /v2/getDedicatedHostPools

Request

Custom Headers

X-Region
string
If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

Example request

curl -X GET "/global/v2/getDedicatedHostPools"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetDedicatedHostPool[]

Get dedicated host pools

Status Code

200
Ok. Detailed information about the dedicated host pools is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified dedicated host pool could not be found.
500
Internal Server Error. The IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "flavorClass": "example-value",
    "hostCount": 3,
    "id": "example-id-123",
    "metro": "example-value",
    "name": "my-cluster",
    "state": "example-value",
    "workerPools": [
      {
        "clusterID": "example-id-123",
        "workerPoolID": "example-id-123"
      }
    ],
    "zones": [
      {
        "capacity": {
          "memoryBytes": 1,
          "vcpu": 1
        },
        "hostCount": 3,
        "zone": "us-south-1"
      }
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the dedicated hosts.

GET /v2/getDedicatedHosts

Request

Custom Headers

X-Region
string
If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

Query Parameters

dedicatedhostpool
Required*
string
The ID of the dedicated host pool that you want to get the dedicated hosts details from.

Example request

curl -X GET "/global/v2/getDedicatedHosts?dedicatedhostpool=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetDedicatedHost[]

Get dedicated hosts

Status Code

200
Ok. Detailed information about the dedicated hosts is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified dedicated host pool could not be found.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "flavor": "example-value",
    "id": "example-id-123",
    "lifecycle": {
      "actualState": "example-value",
      "createdDate": "2024-01-15T10:30:00Z",
      "desiredState": "example-value",
      "message": "example-value",
      "messageDate": "2024-01-15T10:30:00Z",
      "messageDetails": "example-value",
      "messageDetailsDate": "2024-01-15T10:30:00Z"
    },
    "placementEnabled": true,
    "resources": {
      "capacity": {
        "memoryBytes": 1,
        "vcpu": 1
      },
      "consumed": {
        "memoryBytes": 1,
        "vcpu": 1
      }
    },
    "workers": [
      {
        "clusterID": "example-id-123",
        "flavor": "example-value",
        "workerID": "example-id-123",
        "workerPoolID": "example-id-123"
      }
    ],
    "zone": "us-south-1"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get the details for a worker node flavor, including the flavor's virtual CPU amount, memory, disk space and supported operating systems. Flavors are specific to a IBM Cloud Kubernetes Service zone and infrastructure provider.

GET /v2/getFlavor

Request

Query Parameters

flavor
Required*
string
The ID of the flavor. To list available flavors, run ibmcloud ks flavors --zone ZONE or use the GET /v2/getFlavors API.
zone
Required*
string
The ID of the zone. To list available zones, run ibmcloud ks zone ls or use the GET /v2/zones API.
provider
Required*
string
The name of the provider. To check available providers, see the output of the ibmcloud ks flavors --zone ZONE command or use the GET /v2/getFlavors API.

Example request

curl -X GET "/global/v2/getFlavor?flavor=example-value&zone=us-south-1&provider=vpc-gen2"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Flavor

Flavor Definition of a flavor / machine type that can be deployed

Status Code

200
Success
400
The specified zone is invalid. To list available zones, run ibmcloud ks zone ls or use the GET /v2/zones API.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "architecture": "example-value",
  "correspondingFlavor": "example-value",
  "deprecated": false,
  "id": "example-id-123",
  "isTrusted": false,
  "name": "my-cluster",
  "provider": "vpc-gen2",
  "secondaryStorage": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List available flavors that you can use for a worker node. Flavors are specific to a location and a provider in an IBM Cloud Kubernetes Service zone. Each flavor includes the amount of virtual CPU, memory, and disk space that is set up for the worker node.

GET /v2/getFlavors

Request

Query Parameters

zone
Required*
string
The ID of the location for which you want to list available flavors. To list available locations, run ibmcloud ks zone ls or use the GET /v2/zones API.
provider
string
Filters the flavors to match the provider type specified.

Example request

curl -X GET "/global/v2/getFlavors?zone=us-south-1"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Flavor[]

Flavor Definition of a flavor / machine type that can be deployed

Status Code

200
Success
400
The specified location is invalid. To list available locations, run ibmcloud ks zone ls or use the GET /v2/zones API.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "architecture": "example-value",
    "correspondingFlavor": "example-value",
    "deprecated": false,
    "id": "example-id-123",
    "isTrusted": false,
    "name": "my-cluster",
    "provider": "vpc-gen2",
    "secondaryStorage": "example-value"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Retrieves available key management service (KMS) instances, such as Key Protect, in your IBM Cloud Account

GET /v2/getKMSInstances

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group. To list available resource group IDs, run ibmcloud resource groups.

Example request

curl -X GET "/global/v2/getKMSInstances"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

string[]

Getkms instance response

Status Code

200
Ok. A list of all KMSs in your IBM Cloud Account
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster or worker could not be found. To list the clusters that you have access to, use the GET /vpc/v2/clusters API or run ibmcloud ks cluster ls --provider vpc-classic.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "instance_id": "example-id-123",
    "name": "my-cluster",
    "region": "us-south",
    "service": "example-value"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Apply IAM roles to the cluster asynchronously and retrieve the cluster's kubeconfig file to connect to your cluster and run Kubernetes API calls. Use /v2/getRBACStatus to verify when RBAC finishes applying.

GET /v2/getKubeconfig

Request

Custom Headers

X-Auth-Refresh-Token
string
Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.
Accept
string
Allowable values: [application/json,application/zip,text/yaml]

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.
endpoint_type
string
Default endpoint is the public endpoint if available, private otherwise. Use 'private' to require a private endpoint and 'link' for a Satellite Link endpoint.
format
string
Default format is json. Other options include yaml, and zip.
admin
boolean
Retrieve the admin kubeconfig file.
network
boolean
Retrieve the Calico network config. Requires admin=true and format=zip.

Example request

curl -X GET "/global/v2/getKubeconfig?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ClientKubeConfig

ClientKubeConfig is the kubernetes config file used by kubectl

Status Code

200
Ok. Returns the cluster's kubeconfig file.
400
Bad request. The query parameters are either incomplete or in the wrong format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "apiVersion": "1.28.5",
  "clusters": [
    {
      "cluster": {
        "certificate-authority": "example-value",
        "certificate-authority-data": "example-value",
        "disable-compression": false,
        "insecure-skip-tls-verify": true,
        "proxy-url": "https://example.com",
        "server": "example-value",
        "tls-server-name": "my-cluster"
      },
      "name": "my-cluster"
    }
  ],
  "contexts": [
    {
      "context": {
        "cluster": "example-value",
        "namespace": "my-cluster",
        "user": "example-value"
      },
      "name": "my-cluster"
    }
  ],
  "current-context": "example-value",
  "kind": "example-value",
  "preferences": {
    "colors": false
  },
  "users": [
    {
      "name": "my-cluster",
      "user": {
        "as": "example-value",
        "as-groups": [
          "example-value"
        ],
        "as-uid": "example-id-123",
        "as-user-extra": {},
        "auth-provider": {
          "config": {},
          "name": "my-cluster"
        },
        "client-certificate": "example-value",
        "client-certificate-data": "example-value",
        "client-key": "example-value"
      }
    }
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Lists supported operating systems for the given configuration.

GET /v2/getOperatingSystems

Request

Query Parameters

provider
Required*
string
The name of the infrastructure provider in which to view supported operating systems. Available options include 'classic', 'vpc-gen2', and 'satellite'.
version
Required*
string
The Kubernetes or Openshift version.
core_os_enabled
boolean
Whether HyperShift is enabled.

Example request

curl -X GET "/global/v2/getOperatingSystems?provider=vpc-gen2&version=1.28.5"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

OperatingSystem[]

OperatingSystem is the supported OS

Status Code

200
Ok. The request to list supported operating systems was successfully processed.
400
Bad Request. Required parameters were not set. You must provide the version and provider query parameters.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

Example responses

Status 200

[
  {
    "isDefault": false,
    "isDeprecated": false,
    "name": "my-cluster",
    "workerPoolCreateUnsupported": false
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

View the quota for IBM Cloud Kubernetes Service resources such as clusters and worker nodes. The quota is per region and applies across resource groups in the account. To increase your quota, contact IBM Support and include the new quota limit that you want for the region, resource, and infrastructure provider such as classic or VPC.

GET /v2/getQuota

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET "/global/v2/getQuota"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetQuotaResource[]

GetQuota defines a response when getting quota for an account

Status Code

200
OK. A list of quota limits for resources per region in the account is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "infrastructure": "example-value",
    "regions": [
      {
        "id": "example-id-123",
        "quota": 1
      }
    ],
    "type": "example-value"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get the RBACSync status for the authenticated user. The RBACSync status indicates whether the user has the correct identities and RoleBindings in the cluster. The synchronized: true status means the cluster is ready to receive requests from the user. After calling the /v2/applyRBAC endpoint for the first time on a cluster, poll this endpoint to verify the synchronization is complete.

GET /v2/getRBACStatus

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the RBACSync status from. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v2/getRBACStatus?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

object

Status Code

200
Success
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{ "synchronized": false }

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View detailed information for a worker node in a cluster.

GET /v2/getWorker

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster?cluster=idOrName API.

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.
worker
Required*
string
The ID of the worker node that you want details for. To list all worker nodes for a cluster, use the GET /v2/getWorkers?cluster=idOrName API or run ibmcloud ks worker ls --cluster <cluster_name_or_ID>.

Example request

curl -X GET "/global/v2/getWorker?cluster=example-value&worker=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetCombinedWorkerResponse

Get combined worker response

Status Code

200
Ok. Detailed information about the worker node is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "dedicatedHostId": "example-id-123",
  "dedicatedHostPoolId": "example-id-123",
  "flavor": "example-value",
  "health": {
    "message": "example-value",
    "state": "example-value"
  },
  "id": "example-id-123",
  "kubeVersion": {
    "actual": "example-value",
    "desired": "example-value",
    "eos": "example-value",
    "masterEOS": "example-value",
    "target": "example-value"
  },
  "lifecycle": {
    "actualOperatingSystem": "example-value",
    "actualState": "example-value",
    "desiredOperatingSystem": "example-value",
    "desiredState": "example-value",
    "message": "example-value",
    "messageDate": "2024-01-15T10:30:00Z",
    "messageDetails": "example-value",
    "messageDetailsDate": "2024-01-15T10:30:00Z"
  },
  "location": "us-south"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View detailed information for a worker pool in a cluster.

GET /v2/getWorkerPool

Request

Custom Headers

X-Region
string
If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster?cluster=idOrName API.

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.
workerpool
Required*
string
The ID of the worker pool that you want details for. To list all worker pools for a cluster, use the GET /v2/getWorkerPools?cluster=idOrName API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.

Example request

curl -X GET "/global/v2/getWorkerPool?cluster=example-value&workerpool=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "X-Auth-Resource-Group: example-id-123"
Copy to clipboard

Response

Response Body

GetCombinedWorkerPoolResponse

getCombinedWorkerPoolResponse is a superset of all WorkerPool fields returned by all the v2 get worker(s) operations, regardless of the provider.

Status Code

200
Ok. Detailed information about the worker pool is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "autoscaleEnabled": true,
  "dedicatedHostPoolId": "example-id-123",
  "flavor": "example-value",
  "flavorState": "example-value",
  "hostLabels": {},
  "id": "example-id-123",
  "isBalanced": false,
  "isolation": "example-value",
  "zones": [
    {
      "autobalanceEnabled": true,
      "id": "example-id-123",
      "messages": [
        "example-value"
      ],
      "subnets": [
        {
          "id": "example-id-123",
          "primary": false
        }
      ],
      "workerCount": 3
    }
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the worker pools in a cluster.

GET /v2/getWorkerPools

Request

Custom Headers

X-Region
string
If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster?cluster=idOrName API.

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.

Example request

curl -X GET "/global/v2/getWorkerPools?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "X-Auth-Resource-Group: example-id-123"
Copy to clipboard

Response

Response Body

GetCombinedWorkerPoolResponse[]

getCombinedWorkerPoolResponse is a superset of all WorkerPool fields returned by all the v2 get worker(s) operations, regardless of the provider.

Status Code

200
Ok. Detailed information about the worker pools is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "autoscaleEnabled": true,
    "dedicatedHostPoolId": "example-id-123",
    "flavor": "example-value",
    "flavorState": "example-value",
    "hostLabels": {},
    "id": "example-id-123",
    "isBalanced": false,
    "isolation": "example-value",
    "zones": [
      {
        "autobalanceEnabled": true,
        "id": "example-id-123",
        "messages": [
          "example-value"
        ],
        "subnets": [
          {
            "id": "example-id-123",
            "primary": false
          }
        ],
        "workerCount": 3
      }
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View detailed information for all worker nodes in a cluster.

GET /v2/getWorkers

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster?cluster=idOrName API.

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.
show_deleted
string
true|false Shows deleted workers

Example request

curl -X GET "/global/v2/getWorkers?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetCombinedWorkerResponse[]

Get workers response

Status Code

200
Ok. Details for all workers in the cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "dedicatedHostId": "example-id-123",
    "dedicatedHostPoolId": "example-id-123",
    "flavor": "example-value",
    "health": {
      "message": "example-value",
      "state": "example-value"
    },
    "id": "example-id-123",
    "kubeVersion": {
      "actual": "example-value",
      "desired": "example-value",
      "eos": "example-value",
      "masterEOS": "example-value",
      "target": "example-value"
    },
    "lifecycle": {
      "actualOperatingSystem": "example-value",
      "actualState": "example-value",
      "desiredOperatingSystem": "example-value",
      "desiredState": "example-value",
      "message": "example-value",
      "messageDate": "2024-01-15T10:30:00Z",
      "messageDetails": "example-value",
      "messageDetailsDate": "2024-01-15T10:30:00Z"
    },
    "location": "us-south"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Validates whether the provided entitlement value is supported or not.

GET /v2/hasValidEntitlement

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group whose API key token will be used for entitlement check. To list available resource groups, run ibmcloud resource groups. If you don't include this header, the cluster is created in the default resource group. After you create a cluster, you cannot change the resource group. Note that if you plan to integrate IBM Cloud services with the cluster, all the resources must be in the same group.

Query Parameters

entitlement
Required*
string
The entitlement value to check if it is supported.

Example request

curl -X GET "/global/v2/hasValidEntitlement?entitlement=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

HasValidEntitlementResponse

HasValidEntitlementResponse contains the information if the requested entitlement is supported or not

Status Code

200
Ok. The entitlement validation request was successfully processed.
400
The entitlement option can not be set when the stored API key has a subtype. For more information, see 'http://ibm.biz/api-key'.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Could not connect to the back-end billing validation service. Try again later.

Example responses

{ "hasValidEntitlement": false }

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

When you rebalance the worker pool, you return the number of worker nodes in the worker pool to a balanced state. For example, if you remove some worker nodes such as to troubleshoot an issue, you might have an uneven number of nodes across zones. You might delete 2 worker nodes in zone dal13 but still have 3 worker nodes each in zones dal10 and dal12 for a total of 7 worker nodes. To fix this unbalanced state, rebalance the worker pool. After rebalancing, the worker pool has 9 worker nodes again. Rebalancing does not change the size per zone of the worker pool, even if you specify a different size per zone.

POST /v2/rebalanceWorkerPool

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Request Body

RebalanceWorkerPool

Fields required to rebalance the worker pool.

Example request

curl -X POST "/global/v2/rebalanceWorkerPool"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "workerpool": "example-value"
}'
Copy to clipboard

Response

Status Code

204
OK. The request to balance the worker pool was successfully received.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Restart the Kubernetes master in the cluster to apply changes to the API server configuration.

POST /v2/refreshMaster

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*

RefreshMaster

Input parameters to refresh master. The cluster ID or name is required.

Example request

curl -X POST "/global/v2/refreshMaster"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value"
}'
Copy to clipboard

Response

Status Code

204
Ok. The Master will be put into the desired state.
400
Bad Request. Check that all headers are present and the cluster ID or name is provided.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster. To list the clusters that you have access to, use the GET /vpc/v2/clusters API or run ibmcloud ks cluster ls --provider vpc-classic.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Removes a dedicated host.

POST /v2/removeDedicatedHost

Request

Request Body

Required*

DeleteDedicatedHost

The dedicated host to target in a given dedicated host pool.

Example request

curl -X POST "/global/v2/removeDedicatedHost"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "host": "example-value",
  "hostPool": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

202
OK. The request to remove your dedicated host was successfully received.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. The IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Removes a dedicated host pool.

POST /v2/removeDedicatedHostPool

Request

Request Body

Required*

RemoveDedicatedHostPool

The dedicated host pool to target.

Example request

curl -X POST "/global/v2/removeDedicatedHostPool"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "hostPool": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

202
OK. The request to remove your dedicated host pool was successfully received.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. The IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Delete a worker node from a cluster. This action cannot be undone. When you delete the worker node, the worker node is cordoned and drained so that its pods are rescheduled onto remaining worker nodes in the cluster. Make sure that you have enough capacity in the cluster to support the workload. After you remove the worker node, you can rebalance the worker pool.

POST /v2/removeWorker

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Request Body

Required*

RemoveWorker

Input parameters to remove a worker node. The cluster and worker node ID parameters are required.

Example request

curl -X POST "/global/v2/removeWorker"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "workerID": "example-id-123"
}'
Copy to clipboard

Response

Status Code

204
Ok. The worker node was successfully removed from your cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
The specified cluster or worker node could not be found. To list the clusters that you have access to, use the GET /v2/clusters API or run ibmcloud ks cluster ls. To list worker nodes in the cluster, use the GET /v2/getWorkers API or run ibmcloud ks worker ls -c <cluster_name>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Remove a worker pool from a cluster. All worker nodes in the pool are deleted. Your pods are rescheduled when you delete. To avoid downtime, be sure that you have enough workers to run your workload.

POST /v2/removeWorkerPool

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Request Body

Required*

RemoveWorkerPool

The cluster and worker pool to target.

Example request

curl -X POST "/global/v2/removeWorkerPool"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "allowSingleOpenShiftWorker": false,
  "cluster": "example-value",
  "workerpool": "example-value"
}'
Copy to clipboard

Response

Status Code

204
OK. The request to remove your worker pool was successfully received.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Remove a zone from a worker pool in your cluster. All worker nodes that are deployed to that zone in the worker pool are deleted. The app pods from the deleted worker nodes are rescheduled to other worker nodes when the zone is removed. To avoid downtime, be sure that you have enough worker nodes to handle your workload.

POST /v2/removeWorkerPoolZone

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Request Body

Required*

RemoveWorkerPoolZoneReq

The input parameter to specify the cluster, worker pool, and zone.

Example request

curl -X POST "/global/v2/removeWorkerPoolZone"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "workerpool": "example-value",
  "zone": "us-south-1"
}'
Copy to clipboard

Response

Status Code

204
OK. The request to remove the zone from your worker pool was successfully received..
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Resize a worker pool for the specified cluster, such as to add or remove worker pools from each zone that the worker pool spans. Resizing the worker pool resets the desired count of worker node per zone.

POST /v2/resizeWorkerPool

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Request Body

Required*

ResizeWorkerPool

The resize request.

Example request

curl -X POST "/global/v2/resizeWorkerPool"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "allowSingleOpenShiftWorker": false,
  "cluster": "example-value",
  "size": 3,
  "workerpool": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

202
Accepted. The worker pool will be resized to the specified value.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Set custom labels for a worker pool and each of its worker nodes. You might use labels to restrict a workload to run on only this worker pool, or to apply a taint so that workloads do not run on the worker pool. To confirm that your custom labels are applied, run ibmcloud ks worker-pool get -c <cluster_name_or_ID>. To check the labels of the worker nodes, get the private IP address of the worker node (ibmcloud ks worker ls -c <cluster_name_or_ID>) and run kubectl describe node <worker_private_IP>. Note that you must not edit the system-provided labels that that come with the worker pool and worker nodes by default, or you might experience unexpected results.

POST /v2/setWorkerPoolLabels

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Request Body

Required*

SetWorkerPoolLabels

Labels to apply to the worker pool and each of its worker nodes. To apply a custom label to the worker pool, set the "state" field to "labels" and fill in the "labels" section with your label key-value pairs. When you apply a label, all existing custom labels are replaced. If you have existing custom labels that you want to keep, include them in your request. To remove a custom label, set the "state" field to "labels" and in the "labels" section, include the same "key" field, but leave the value field blank "". Note that you must not edit the system-provided labels that that come with the worker pool and worker nodes by default, or you might experience unexpected results.

Example request

curl -X POST "/global/v2/setWorkerPoolLabels"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "labels": {},
  "workerpool": "example-value"
}'
Copy to clipboard

Response

Status Code

204
OK. The request to set the labels of the worker pool was successfully received.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Set the operating system of a worker pool. To confirm that your modification is applied, check the details of a worker pool (ibmcloud ks worker-pool get --cluster CLUSTER --worker-pool POOL).

POST /v2/setWorkerPoolOperatingSystem

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster belongs to in which the worker pools resides. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Request Body

Required*

SetWorkerPoolOperatingSystem

Sets the operating system of a worker pool.

Example request

curl -X POST "/global/v2/setWorkerPoolOperatingSystem"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "operatingSystem": "example-value",
  "workerPool": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

202
OK. The request to set the operating system of the worker pool was successful.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
The worker pool's operating system is not suitable for an upgrade this way.
404
The specified worker pool could not be found..
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Set custom taints for a worker pool and each of its worker nodes. You might use taints so that workloads do not run on the worker pool. To confirm that your custom taints are applied, check the taints of the worker nodes by getting the private IP address of the worker node (ibmcloud ks worker ls -c <cluster_name_or_ID>) and run kubectl describe node <worker_private_IP>.

POST /v2/setWorkerPoolTaints

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Request Body

Required*

SetWorkerPoolTaints

Taints to apply to the worker pool and each of its worker nodes. To apply a custom taint to the worker pool, set the "state" field to "taints" and fill in the "taints" section with your taint key-value pairs where the value contains the taint value and the taint effect separated by a ":" with valid taint effects being "NoSchedule", "PreferNoSchedule", and "NoExecute". When you apply a taint, all existing custom taints are replaced. If you have existing custom taints that you want to keep, include them in your request. To remove a custom taint, set the "state" field to "taints" and in the "taints" section, include the same "key" field, but leave the value field blank "".

Example request

curl -X POST "/global/v2/setWorkerPoolTaints"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "taints": {},
  "workerpool": "example-value"
}'
Copy to clipboard

Response

Status Code

204
OK. The request to set the taints of the worker pool was successfully received.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a cluster in a Virtual Private Cloud (VPC) that you have access to. Note: This API method requires Administrator platform role for IBM Cloud Kubernetes Service at the account level, as well as access to several other services such as the underlying infrastructure provider. For more information, see 'https://ibm.biz/cluster-perms'.

POST /v2/vpc/createCluster

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group to create the cluster in. To list available resource groups, run ibmcloud resource groups. If you don't include this header, the cluster is created in the default resource group. After you create a cluster, you cannot change the resource group. Note that if you plan to integrate IBM Cloud services with the cluster, all the resources must be in the same group.

Request Body

Required*

VPCCreateCluster

Input parameter to add a cluster. For more information, see https://ibm.biz/cluster_create_docs

Example request

curl -X POST "/global/v2/vpc/createCluster"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cosInstanceCRN": "example-value",
  "cseACLEnabled": true,
  "defaultWorkerPoolEntitlement": "example-value",
  "disableOutboundTrafficProtection": false,
  "disablePublicServiceEndpoint": false,
  "infrastructureTopology": "public",
  "kubeVersion": "1.28.5",
  "name": "my-cluster",
  "previews": [],
  "securityGroupIDs": [
    "example-id-123"
  ]
}'
Copy to clipboard

Response

Response Body

CreateClusterResponse

Create cluster response

Status Code

201
Created. The cluster was successfully created in the IBM Cloud account that you are logged in to.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.
409
Conflict. A cluster with the same name already exists. Choose another name for your cluster.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 201

{
  "clusterID": "example-id-123",
  "messages": [
    {
      "level": "example-value",
      "text": "example-value"
    }
  ],
  "non_critical_errors": {
    "incidentID": "example-id-123",
    "items": [
      {
        "code": "example-value",
        "description": "example-value",
        "recoveryCLI": "example-value",
        "terseDescription": "example-value",
        "type": "example-value"
      }
    ]
  }
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a worker pool for the specified VPC cluster. Creating a worker pool requires Operator access to Kubernetes Service in the IBM Cloud account.

POST /v2/vpc/createWorkerPool

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*

V2VpcCreateWorkerPoolRequest

The

Example request

curl -X POST "/global/v2/vpc/createWorkerPool"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "Zones": [
    {
      "id": "example-id-123",
      "subnetID": "10.240.0.0/24"
    }
  ],
  "cluster": "example-value",
  "diskEncryption": false,
  "entitlement": "example-value",
  "flavor": "example-value",
  "hostPool": "example-value",
  "isolation": "example-value",
  "labels": {},
  "securityGroupIDs": [
    "example-id-123"
  ]
}'
Copy to clipboard

Response

Response Body

CreateWorkerpoolResponse

Create workerpool response

Status Code

201
Created. The worker pool was successfully created in for the specified cluster.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
409
Conflict. A worker pool create may already be in progress for the provided cluster. Please wait a few minutes and try again.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{ "workerPoolID": "example-id-123" }

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a zone in the specified worker pool for a VPC cluster. Workers will be provisioned in each provided zone based on the size of the pool.

POST /v2/vpc/createWorkerPoolZone

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group to create the cluster in. To list available resource groups, run ibmcloud resource groups. If you don't include this header, the cluster is created in the default resource group. After you create a cluster, you cannot change the resource group. Note that if you plan to integrate IBM Cloud services with the cluster, all the resources must be in the same group.

Request Body

Required*

CreateWorkerpoolZoneRequest

Input parameters to add zones to the worker pool.

Example request

curl -X POST "/global/v2/vpc/createWorkerPoolZone"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "id": "example-id-123",
  "subnetID": "10.240.0.0/24",
  "workerpool": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

201
OK. The requested zone has been added to the worker pool.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls mycluster.
409
Conflict. The provided zone already exists in the worker pool.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get details of a VPC cluster.

GET /v2/vpc/getCluster

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
show_resources
string
To view additional cluster resources like addons, VLANs, subnets, and storage, pass true.

Example request

curl -X GET "/global/v2/vpc/getCluster?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetClusterResponse

Get cluster response

Status Code

200
Success. Detailed cluster information.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "addons": [
    {
      "name": "my-cluster",
      "version": "1.28.5"
    }
  ],
  "caCertRotationStatus": {
    "actionCompletedDate": "2024-01-15T10:30:00Z",
    "actionTriggerDate": "2024-01-15T10:30:00Z",
    "status": "example-value"
  },
  "calicoIPAutodetectionConfig": "example-value",
  "createdDate": "2024-01-15T10:30:00Z",
  "crn": "example-value",
  "datacenter": "example-value",
  "desiredTrustedProfileID": "example-id-123",
  "disableAutoUpdate": false,
  "id": "example-id-123",
  "locationZones": [
    "us-south"
  ],
  "supportedOperatingSystems": [
    "example-value"
  ],
  "vpcs": [
    "example-value"
  ],
  "workerZones": [
    "us-south-1"
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the VPC clusters that you have access to.

GET /v2/vpc/getClusters

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group to list clusters for. To list available resource groups, run ibmcloud resource groups. If you don't include this header, all the clusters in the account that you have access to are listed.

Query Parameters

location
string
Specify a location to filter clusters for. To see supported locations, use the GET /v1/locations API or run ibmcloud ks locations.
provider
string
The name of the provider to filter the clusters by.

Example request

curl -X GET "/global/v2/vpc/getClusters"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetClustersResponse[]

GetClustersResponse cluster response for cluster list

Status Code

200
Success. A list of clusters that you have access to is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "addons": [
      {
        "name": "my-cluster",
        "version": "1.28.5"
      }
    ],
    "caCertRotationStatus": {
      "actionCompletedDate": "2024-01-15T10:30:00Z",
      "actionTriggerDate": "2024-01-15T10:30:00Z",
      "status": "example-value"
    },
    "calicoIPAutodetectionConfig": "example-value",
    "createdDate": "2024-01-15T10:30:00Z",
    "datacenter": "example-value",
    "desiredTrustedProfileID": "example-id-123",
    "entitlement": "example-value",
    "etcdPort": "example-value",
    "id": "example-id-123"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View details for subnets in a VPC for the given region and provider.

GET /v2/vpc/getSubnets

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

provider
Required*
string
The name of the VPC provider.
zone
Required*
string
The name of the zone in which to list subnets.
vpc
Required*
string
The ID of the VPC.

Example request

curl -X GET "/global/v2/vpc/getSubnets?provider=vpc-gen2&zone=us-south-1&vpc=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Subnet[]

Subnets

Status Code

200
Ok. A list of all subnets for the given VPC is returned.
400
Bad Request. The given provider, zone, or VPC is invalid.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "availableIPv4AddressCount": 3,
    "id": "example-id-123",
    "ipv4CIDRBlock": "example-id-123",
    "name": "my-cluster",
    "publicGatewayID": "example-id-123",
    "publicGatewayName": "my-cluster",
    "vpcID": "example-id-123",
    "vpcName": "my-cluster"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View details of a virtual private cloud (VPC).

GET /v2/vpc/getVPC

Request

Custom Headers

X-Region
Required*
string
The region of the VPC. To list regions, run ibmcloud ks regions.
X-Auth-Resource-Group
string
Optional, specify a resource group ID to use its API key to list VPCs that the API key of the resource group has access to. To list available resource group IDs, run ibmcloud resource groups.

Query Parameters

provider
Required*
string
The name of the infrastructure provider that the VPC is created in. To list infrastructure providers of a VPC, run ibmcloud ks vpcs or use the GET /v2/vpc/getVPCs API.
vpc_id
Required*
string
The ID of the VPC. To list the ID of a VPC, run ibmcloud ks vpcs or use the GET /v2/vpc/getVPCs API.

Example request

curl -X GET "/global/v2/vpc/getVPC?provider=vpc-gen2&vpc_id=example-id-123"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "X-Auth-Resource-Group: example-id-123"
Copy to clipboard

Response

Response Body

GetVPCResponse

GetVPC defines a response when getting a VPC

Status Code

200
OK. Details of the specified VPC are returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "id": "example-id-123",
  "messages": [
    {
      "level": "example-value",
      "text": "example-value"
    }
  ],
  "name": "my-cluster",
  "resourceGroup": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View details for all VPCs in the given provider

GET /v2/vpc/getVPCs

Request

Custom Headers

X-Auth-Resource-Group
string
Optional, specify a resource group ID to use its API key to list VPCs that the API key of the resource group has access to. To list available resource group IDs, run ibmcloud resource groups.

Query Parameters

provider
Required*
string
The name of the provider in which to list VPCs.

Example request

curl -X GET "/global/v2/vpc/getVPCs?provider=vpc-gen2"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

VirtualPrivateCloudResponse[]

Virtual private clouds

Status Code

200
Ok. A list of all VPCs is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "id": "example-id-123",
    "name": "my-cluster",
    "provider": "vpc-gen2",
    "resourceGroup": "example-value",
    "zones": [
      "us-south-1"
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View detailed information for a worker node in a VPC cluster.

GET /v2/vpc/getWorker

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
worker
Required*
string
The ID of the worker node that you want details for. To list all worker nodes for a cluster, use the GET /v1/clusters/{idOrName}/workers API or run ibmcloud ks worker ls --cluster <cluster_name_or_ID>.

Example request

curl -X GET "/global/v2/vpc/getWorker?cluster=example-value&worker=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetVPCWorkerResponse

Getvpc worker response

Status Code

200
Ok. Detailed information about the worker node is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "dedicatedHostId": "example-id-123",
  "dedicatedHostPoolId": "example-id-123",
  "flavor": "example-value",
  "health": {
    "message": "example-value",
    "state": "example-value"
  },
  "id": "example-id-123",
  "kubeVersion": {
    "actual": "example-value",
    "desired": "example-value",
    "eos": "example-value",
    "masterEOS": "example-value",
    "target": "example-value"
  },
  "lifecycle": {
    "actualOperatingSystem": "example-value",
    "actualState": "example-value",
    "desiredOperatingSystem": "example-value",
    "desiredState": "example-value",
    "message": "example-value",
    "messageDate": "2024-01-15T10:30:00Z",
    "messageDetails": "example-value",
    "messageDetailsDate": "2024-01-15T10:30:00Z"
  },
  "location": "us-south"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View detailed information for a worker pool in a VPC cluster.

GET /v2/vpc/getWorkerPool

Request

Custom Headers

X-Region
string
If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
workerpool
Required*
string
The ID of the worker pool that you want details for. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.

Example request

curl -X GET "/global/v2/vpc/getWorkerPool?cluster=example-value&workerpool=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "X-Auth-Resource-Group: example-id-123"
Copy to clipboard

Response

Response Body

GetVPCWorkerPoolResponse

Getvpc worker pool response

Status Code

200
Ok. Detailed information about the worker pool is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "autoscaleEnabled": true,
  "dedicatedHostPoolId": "example-id-123",
  "flavor": "example-value",
  "flavorState": "example-value",
  "hostLabels": {},
  "id": "example-id-123",
  "isBalanced": false,
  "isolation": "example-value",
  "zones": [
    {
      "autobalanceEnabled": true,
      "id": "example-id-123",
      "messages": [
        "example-value"
      ],
      "subnets": [
        {
          "id": "example-id-123",
          "primary": false
        }
      ],
      "workerCount": 3
    }
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the worker pools in a VPC cluster.

GET /v2/vpc/getWorkerPools

Request

Custom Headers

X-Region
string
If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v2/vpc/getWorkerPools?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "X-Auth-Resource-Group: example-id-123"
Copy to clipboard

Response

Response Body

GetVPCWorkerPoolResponse[]

Getvpc worker pool response

Status Code

200
Ok. Detailed information about the worker pools is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "autoscaleEnabled": true,
    "dedicatedHostPoolId": "example-id-123",
    "flavor": "example-value",
    "flavorState": "example-value",
    "hostLabels": {},
    "id": "example-id-123",
    "isBalanced": false,
    "isolation": "example-value",
    "zones": [
      {
        "autobalanceEnabled": true,
        "id": "example-id-123",
        "messages": [
          "example-value"
        ],
        "subnets": [
          {
            "id": "example-id-123",
            "primary": false
          }
        ],
        "workerCount": 3
      }
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View detailed information for all worker nodes in a VPC cluster.

GET /v2/vpc/getWorkers

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
show_deleted
string
true|false Shows deleted workers
pool
string
The name or ID of the worker pool to filter results for. Run ibmcloud ks worker-pool ls --cluster <cluster name>.

Example request

curl -X GET "/global/v2/vpc/getWorkers?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetVPCWorkerResponse[]

Getvpc workers response

Status Code

200
Ok. Details for all workers in the VPC cluster.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "dedicatedHostId": "example-id-123",
    "dedicatedHostPoolId": "example-id-123",
    "flavor": "example-value",
    "health": {
      "message": "example-value",
      "state": "example-value"
    },
    "id": "example-id-123",
    "kubeVersion": {
      "actual": "example-value",
      "desired": "example-value",
      "eos": "example-value",
      "masterEOS": "example-value",
      "target": "example-value"
    },
    "lifecycle": {
      "actualOperatingSystem": "example-value",
      "actualState": "example-value",
      "desiredOperatingSystem": "example-value",
      "desiredState": "example-value",
      "message": "example-value",
      "messageDate": "2024-01-15T10:30:00Z",
      "messageDetails": "example-value",
      "messageDetailsDate": "2024-01-15T10:30:00Z"
    },
    "location": "us-south"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List available zones that you can use to create a cluster in an IBM Cloud Kubernetes Service region.

GET /v2/vpc/getZones

Request

Query Parameters

provider
string
The provider for which to list zones. Defaults to vpc-classic.
show_flavors
boolean
Determines whether to show the flavors for the returned zones.

Example request

curl -X GET "/global/v2/vpc/getZones"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ZoneResponse[]

Zones sortable list of zone responses

Status Code

200
Success. A list of available zones for a region is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
No zones found for provider. Run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 200

[
  {
    "flavors": [
      {
        "additionalStorage": [
          {
            "Count": 3,
            "DeviceType": "example-value",
            "RAIDConfiguration": "example-id-123",
            "Size": 3,
            "name": "my-cluster",
            "profile": "example-value"
          }
        ],
        "architecture": "example-value",
        "cores": 1,
        "deprecated": false,
        "flavor_class": "example-value",
        "gpus": [
          {
            "Count": 3,
            "Type": "example-value"
          }
        ],
        "id": "example-id-123",
        "memory": "example-value",
        "secondaryStorageOptions": [
          {
            "Count": 3,
            "DeviceType": "example-value",
            "RAIDConfiguration": "example-id-123",
            "Size": 3,
            "name": "my-cluster",
            "profile": "example-value"
          }
        ],
        "supported_isolation": [
          "example-value"
        ],
        "tags": [
          "example-value"
        ]
      }
    ],
    "id": "example-id-123",
    "metro": "example-value",
    "name": "my-cluster"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Delete the specified worker node from the cluster and provision a new worker node to replace the deleted worker node. You might replace a worker node if you cannot reload it, such as if it enters a troubled state. You can also replace the worker node to include an update to the same major and minor version of the master. The replacement worker node is created in the same zone, same worker pool, and with the same flavor as the deleted worker node. However, the replacement worker node is assigned a new private IP address, and loses any custom labels that you applied to the old worker node (worker pool labels are still applied to the replacement worker node). Before you replace the worker node, consider adding more worker nodes to the cluster and draining the worker node to help avoid downtime for your apps.

POST /v2/vpc/replaceWorker

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*

ReplaceWorkerRequest

Input parameters to replace a worker node. The cluster and worker node ID parameters are required. The update parameter is optional. To update the worker node to the same major and minor version as the master, set “update” to true.

Example request

curl -X POST "/global/v2/vpc/replaceWorker"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "update": false,
  "workerID": "example-id-123"
}'
Copy to clipboard

Response

Status Code

204
OK. The worker node is being removed and replaced with a new worker node.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster or worker could not be found. To list the clusters that you have access to, use the GET /vpc/v2/clusters API or run ibmcloud ks cluster ls --provider vpc-classic.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Same behavior as GET /v2/cluster-health/getIssue.

GET /v2/cluster-health/getIssue

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster.

Query Parameters

cluster
Required*
string
Cluster ID or name.
issue
Required*
string
Issue code.

Example request

curl -X GET "/global/v2/cluster-health/getIssue?cluster=example-value&issue=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group-ID: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

DetailedHealthIssue

Detailed health issue

Status Code

200
Success. Detailed health issue payload.
400
Bad request.
401
Unauthorized.
403
Forbidden.
404
Not found.
410
Gone.
500
Internal Server Error.

Example responses

Status 200

{
  "component": "example-value",
  "description": "example-value",
  "detected": "example-value",
  "id": "example-id-123",
  "more_details": [
    {
      "affected_component_type": "example-value",
      "affected_components": [
        "example-value"
      ],
      "message": "example-value",
      "type": 1
    }
  ],
  "severity": "example-value",
  "solution": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Same behavior as GET /v2/cluster-health/getIssues. Use this path when calling a regional Kubernetes Service endpoint directly.

GET /v2/cluster-health/getIssues

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster.

Query Parameters

cluster
Required*
string
Cluster ID or name.

Example request

curl -X GET "/global/v2/cluster-health/getIssues?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group-ID: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

HealthIssueListItem[]

Health issue list item

Status Code

200
Success. An array of health issue summaries.
400
Bad request.
401
Unauthorized. The IAM token is invalid or expired.
403
Forbidden.
410
Gone.
500
Internal Server Error.

Example responses

Status 200

[
  {
    "component": "example-value",
    "description": "example-value",
    "detected": "example-value",
    "id": "example-id-123",
    "severity": "example-value"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Disable image security enforcement for a cluster

POST /v2/disableImageSecurity

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*

ImageSecurity

Input parameters to specify the name or ID of the cluster that you want to disable image security enforcement in.

Example request

curl -X POST "/global/v2/disableImageSecurity"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value"
}'
Copy to clipboard

Response

Status Code

204
Ok. The request to update your master node was successfully processed.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Enable image security enforcement for a cluster

POST /v2/enableImageSecurity

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*

ImageSecurity

Input parameters to specify the name or ID of the cluster that you want to enable image security enforcement in.

Example request

curl -X POST "/global/v2/enableImageSecurity"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value"
}'
Copy to clipboard

Response

Status Code

204
Ok. The request to update your master node was successfully processed.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Deprecated: This API was only available for Kubernetes clusters that ran version 1.24. Disable the Pod Security Policy admission controller for Kubernetes. Use this API when migrating from the deprecated Pod Security Policy to the Pod Security admission controller.

POST /v2/disablePodSecurityPolicy

Request

Request Body

Required*

DisablePodSecurityPolicyRequest

The cluster to target.

Example request

curl -X POST "/global/v2/disablePodSecurityPolicy"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value"
}'
Copy to clipboard

Response

Status Code

204
OK. The request to disable the Pod Security Policy admission controller was successfully received.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Bad Request. Your cluster must run Kubernetes version 1.24 to change the Pod Security Policy admission controller.
Bad Request. Cannot disable the Pod Security Policy admission controller when the Pod Security admission controller is disabled.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Deprecated: This API was only available for Kubernetes clusters that ran version 1.24. Enable the Pod Security Policy admission controller. Use this API when migrating from the deprecated Pod Security Policy to the Pod Security admission controller.

POST /v2/enablePodSecurityPolicy

Request

Request Body

Required*

EnablePodSecurityPolicyRequest

The cluster to target.

Example request

curl -X POST "/global/v2/enablePodSecurityPolicy"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value"
}'
Copy to clipboard

Response

Status Code

204
OK. The request to enable the Pod Security Policy admission controller was successfully received.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Bad Request. Your cluster must run Kubernetes version 1.24 to change the Pod Security Policy admission controller.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

View the Pod Security admission control configuration for a cluster.

GET /v2/getPodSecurity

Request

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the Pod Security admission control configuration for. To list the clusters that you have access to, use the GET /v2/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v2/getPodSecurity?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

PodSecurityResponse

PodSecurityResponse represents the configuration of the cluster PodSecurity admission controller

Status Code

200
Ok. The request to view the Pod Security admission control configuration was successfully processed.
400
Bad Request. Required parameters were not set. You must provide the cluster query parameter.
Bad Request. Pod Security admission is supported only for Kubernetes v1.24 or later clusters.
Bad Request. Pod Security admission is not supported for Red Hat OpenShift clusters.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

Example responses

Status 200

{
  "configuration": "ZXhhbXBsZQ==",
  "enabled": true
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Deprecated: This API was only available for Kubernetes clusters that ran version 1.24. View the Pod Security Policy admission control configuration. Use this API when migrating from the deprecated Pod Security Policy to the Pod Security admission controller.

GET /v2/getPodSecurityPolicy

Request

Query Parameters

cluster
Required*
string
The name or ID of the cluster that you want to get the Pod Security admission control configuration for. To list the clusters that you have access to, use the GET /v2/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v2/getPodSecurityPolicy?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

PodSecurityPolicyResponse

PodSecurityPolicyResponse represents the state of the cluster PodSecurityPolicy admission controller

Status Code

200
Ok. The request to view Pod Security Policy admission control configuration was successfully processed.
400
Bad Request. Required parameters were not set. You must provide the cluster query parameter.
Bad Request. Pod Security admission configuration is not supported for OpenShift clusters.
Bad Request. Your cluster must run Kubernetes version 1.24 to remove the Pod Security admission controller or to change the Pod Security Policy admission controller.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

Example responses

{ "enabled": true }

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Deprecated: This API was only available for Kubernetes clusters that ran version 1.24. Remove the Pod Security admission controller configuration. Use this API when migrating from the deprecated Pod Security Policy to the Pod Security admission controller.

POST /v2/removePodSecurity

Request

Request Body

Required*

RemovePodSecurityRequest

The cluster to target.

Example request

curl -X POST "/global/v2/removePodSecurity"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value"
}'
Copy to clipboard

Response

Status Code

204
OK. The request to remove the Pod Security admission controller configuration was successfully received.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Bad Request. Your cluster must run Kubernetes version 1.24 to remove the Pod Security admission controller or to change the Pod Security Policy admission controller.
Bad Request. Cannot disable the Pod Security admission controller when the Pod Security Policy admission controller is disabled.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Set the Pod Security admission controller configuration.

POST /v2/setPodSecurity

Request

Request Body

Required*

SetPodSecurityRequest

The cluster to target.

Examples:

Example request

curl -X POST "/global/v2/setPodSecurity"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "configuration": "ZXhhbXBsZQ=="
}'
Copy to clipboard

Response

Status Code

204
OK. The request to set the Pod Security admission controller configuration was successfully received.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Bad Request. Your cluster must run Kubernetes version 1.24 or later to modify the Pod Security admission configuration.
Bad Request. Pod Security admission is not supported for Red Hat OpenShift clusters.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Disables a private service endpoint for a cluster.

POST /v2/disablePrivateServiceEndpoint

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*

UpdateServiceEndpoint

Input parameters to specify the name or ID of the cluster and which service endpoint to update. Valid service endpoints are public or private.

Example request

curl -X POST "/global/v2/disablePrivateServiceEndpoint"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value"
}'
Copy to clipboard

Response

Status Code

204
Ok. The request to update your master node was successfully processed.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Disables a public service endpoint for a cluster.

POST /v2/disablePublicServiceEndpoint

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*

UpdateServiceEndpoint

Input parameters to specify the name or ID of the cluster and which service endpoint to update. Valid service endpoints are public or private.

Example request

curl -X POST "/global/v2/disablePublicServiceEndpoint"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value"
}'
Copy to clipboard

Response

Status Code

204
Ok. The request to update your master node was successfully processed.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Enables the private service endpoint for a cluster.

POST /v2/enablePrivateServiceEndpoint

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*

UpdateServiceEndpoint

Input parameters to specify the name or ID of the cluster and which service endpoint to update. Valid service endpoints are public or private.

Example request

curl -X POST "/global/v2/enablePrivateServiceEndpoint"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value"
}'
Copy to clipboard

Response

Status Code

204
Ok. The request to update your master node was successfully processed.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Enables the public service endpoint for a cluster.

POST /v2/enablePublicServiceEndpoint

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*

UpdateServiceEndpoint

Input parameters to specify the name or ID of the cluster and which service endpoint to update. Valid service endpoints are public or private.

Example request

curl -X POST "/global/v2/enablePublicServiceEndpoint"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value"
}'
Copy to clipboard

Response

Status Code

204
Ok. The request to update your master node was successfully processed.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create an image pull secret to IBM Cloud Container Registry in the default .

POST /v2/enablePullSecret

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*

EnablePullSecret

Input parameters to specify the name or ID of the cluster and which to enable pull secrets for.

Example request

curl -X POST "/global/v2/enablePullSecret"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value"
}'
Copy to clipboard

Response

Status Code

204
Ok. The request to update your master node was successfully processed.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List available versions that you can use to create a cluster in a region. The container management platform version that you select is installed on your cluster master and worker nodes. Later, you can update the version but cannot roll back to a previous version or switch to a different container management platform. If you want to use multiple versions, create a separate cluster for each version.

GET /v2/getVersions

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET "/global/v2/getVersions"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

object

Status Code

200
Success. Available container management platform versions for the IBM Cloud Kubernetes Service region are returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Delete the specified worker node from the cluster and create a new worker node in the same worker pool to replace the deleted worker node. The new worker node is assigned new public or private IP addresses. When the worker node is deleted, it is cordoned and drained to reschedule the pods that run on the worker node before deleting it, to avoid downtime for your apps. You might replace a worker node if you cannot reload or update the worker node, such as if it enters a troubled state.

POST /v2/replaceWorker

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of a VPC cluster, use the GET /v2/vpc/getCluster?cluster=idOrName API.

Request Body

Required*

ReplaceWorkerRequest

Input parameters to replace a worker.

Example request

curl -X POST "/global/v2/replaceWorker"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "update": false,
  "workerID": "example-id-123"
}'
Copy to clipboard

Response

Status Code

204
OK. The worker node is being removed and replaced with a new worker node.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster or worker could not be found. To list the VPC clusters that you have access to, use the GET /vpc/v2/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Update the Kubernetes master to the default API version. During the update, you cannot access or change the cluster. Worker nodes, apps, and resources that have been deployed by the user are not modified and will continue to run. You might need to change your YAML files for future deployments. For details, see the release notes at https://cloud.ibm.com/docs/containers?topic=containers-cs_versions

POST /v2/updateMaster

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*

UpdateMaster

Input parameters to specify the name or ID of the cluster, what version to update the master to, and whether to force the update. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X POST "/global/v2/updateMaster"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "force": false,
  "version": "1.28.5"
}'
Copy to clipboard

Response

Status Code

204
Ok. The request to update your master node was successfully processed.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
409
Conflict. The specified value is already set on the cluster. To list the clusters properties, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Update the health monitoring configuration for the specified NLB subdomain in a cluster. Include the cluster ID, NLB subdomain, and any the provider specific configurations for the health check in the request body.

PUT /v2/nlb-dns/configureHealthMonitor

Request

Request Body

Required*

HealthMonitorConfiguration

The full health monitoring configuration to overwrite the current configuration with. The configuration is defined in the corresponding provider specific field.

Example request

curl -X PUT "/global/v2/nlb-dns/configureHealthMonitor"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "akamaiMonitorConfiguration": {
    "httpError3xx": false,
    "httpError4xx": false,
    "httpError5xx": false,
    "httpHeaders": [
      {
        "name": "my-cluster",
        "value": "example-value"
      }
    ],
    "httpMethod": "example-value",
    "name": "my-cluster",
    "peerCertificateVerification": false,
    "testInterval": 1
  },
  "cluster": "example-value",
  "nlbSubdomain": "example-value"
}'
Copy to clipboard

Response

Status Code

204
Ok. The request to update the health monitor config was successfully processed.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster or NLB subdomain could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Delete a secret from an NLB subdomain in your cluster and prevent future renewal of the certificate. You might remove the secret from an NLB subdomain if you no longer use the subdomain or disassociate it from your NLB IP addresses.

POST /v2/nlb-dns/deleteSecret

Request

Request Body

Required*

SecretConfig

Include the NLB subdomain that you want to delete the secret for, and the cluster that the subdomain is in.

Example request

curl -X POST "/global/v2/nlb-dns/deleteSecret"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "subdomain": "example-value"
}'
Copy to clipboard

Response

Status Code

204
Deleted. The secret name was successfully deleted for the NLB subdomain.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster, subdomain, or secret could not be found. To list clusters you have access to, run ibmcloud ks cluster ls. To list existing NLB subdomains and associated secret names, run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_id>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get the health monitoring configuration for the specified NLB subdomain in a cluster.

GET /v2/nlb-dns/getHealthMonitorConfig

Request

Query Parameters

cluster
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
nlb_subdomain
Required*
string
The existing NLB subdomain that you want the monitor config for. To list existing NLB subdomains, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.

Example request

curl -X GET "/global/v2/nlb-dns/getHealthMonitorConfig?cluster=example-value&nlb_subdomain=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

HealthMonitorConfiguration

HealthMonitorConfiguration is a common struct to be used in NLB health monitor related APIs

Status Code

200
OK. Current monitor config returned.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "akamaiMonitorConfiguration": {
    "httpError3xx": false,
    "httpError4xx": false,
    "httpError5xx": false,
    "httpHeaders": [
      {
        "name": "my-cluster",
        "value": "example-value"
      }
    ],
    "httpMethod": "example-value",
    "name": "my-cluster",
    "peerCertificateVerification": false,
    "testInterval": 1
  },
  "cluster": "example-value",
  "nlbSubdomain": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List NLB subdomains and the NLB IP addresses or the load balancer hostnames that are registered with the DNS provider for each NLB subdomain.

GET /v2/nlb-dns/getNlbDNSList

Request

Query Parameters

cluster
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v2/nlb-dns/getNlbDNSList?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

NlbVPCListConfig[]

V2NlbList response for the get api for vpc clusters

Status Code

200
Ok. A list of NLB subdomains and associated details is returned for this cluster.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "Nlb": {
      "certProvider": "vpc-gen2",
      "cluster": "example-value",
      "crn": "example-value",
      "dnsType": "example-value",
      "isDefault": false,
      "lbHostname": "my-cluster",
      "nlbIPArray": [
        "example-value"
      ],
      "nlbSubdomain": "example-value"
    },
    "secretName": "my-cluster",
    "secretStatus": "example-value"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get the details for the NLB subdomain and the NLB IP addresses or the load balancer hostnames that are registered with the DNS provider for each NLB subdomain.

GET /v2/nlb-dns/getNlbDetails

Request

Query Parameters

cluster
Required*
string
The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.
nlb_subdomain
Required*
string
The existing NLB subdomain that you want details for. To list existing NLB subdomains, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.

Example request

curl -X GET "/global/v2/nlb-dns/getNlbDetails?cluster=example-value&nlb_subdomain=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

NlbVPCListConfig

NlbVPCListConfig single nlb subdomain in list response

Status Code

200
OK. Details of the NLB subdomain are returned.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "Nlb": {
    "certProvider": "vpc-gen2",
    "cluster": "example-value",
    "crn": "example-value",
    "dnsType": "example-value",
    "isDefault": false,
    "lbHostname": "my-cluster",
    "nlbIPArray": [
      "example-value"
    ],
    "nlbSubdomain": "example-value"
  },
  "secretName": "my-cluster",
  "secretStatus": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get the details for the subdomain and the IP addresses that are registered with the DNS provider for each subdomain.

GET /v2/nlb-dns/getSatLocationSubdomain

Request

Query Parameters

controller
Required*
string
To list available locations, use the GET /v2/satellite/getControllers API, or run ibmcloud sat location ls.
subdomain
Required*
string
The existing subdomain that you want details for. To list existing subdomains, use the GET /v2/nlb-dns/getSatLocationSubdomains API or run ibmcloud sat location dns ls --cluster <cluster_name_or_ID>.

Example request

curl -X GET "/global/v2/nlb-dns/getSatLocationSubdomain?controller=example-value&subdomain=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

NlbConfig

NlbConfig config for NLB configuration

Status Code

200
OK. A list of subdomains and associated details is returned for this location. If no list is returned, you can assign hosts to your location and try again.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your IAM and UAA tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Could not find the IBM Cloud Satellite location. To list available locations, use the GET /v2/satellite/getControllers API, or run ibmcloud sat location ls.
500
Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "certProvider": "vpc-gen2",
  "clusterID": "example-id-123",
  "crn": "example-value",
  "isDefault": false,
  "nlbDnsType": "example-value",
  "nlbHost": "example-value",
  "nlbIPArray": [
    "example-value"
  ],
  "nlbMonitorState": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get the details for the NLB subdomains along with the NLB IP addresses or CNAME records that are registered with the DNS provider for each NLB subdomain. Your Satellite location has a set of hosts that run control plane operations to manage your Satellite components across all the clusters in the location. If your location becomes unavailable, you might use the NLB subdomain and IP address details of the hosts to help troubleshoot.

GET /v2/nlb-dns/getSatLocationSubdomains

Request

Query Parameters

controller
Required*
string
To list available locations, use the GET /v2/satellite/getControllers API, or run ibmcloud sat location ls.

Example request

curl -X GET "/global/v2/nlb-dns/getSatLocationSubdomains?controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

NlbVPCListConfig[]

V2NlbList response for the get api for vpc clusters

Status Code

200
OK. A list of NLB subdomains and associated details is returned for this location. If no list is returned, you can assign hosts to your location and try again.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Could not find the IBM Cloud Satellite location. To list available locations, use the GET /v2/satellite/getControllers API, or run ibmcloud sat location ls.
500
Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "Nlb": {
      "certProvider": "vpc-gen2",
      "cluster": "example-value",
      "crn": "example-value",
      "dnsType": "example-value",
      "isDefault": false,
      "lbHostname": "my-cluster",
      "nlbIPArray": [
        "example-value"
      ],
      "nlbSubdomain": "example-value"
    },
    "secretName": "my-cluster",
    "secretStatus": "example-value"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Regenerate the certificate and recreate the secret for an NLB subdomain. You might regenerate an NLB subdomain's certificate and secret if you previously deleted the secret.

POST /v2/nlb-dns/regenerateCert

Request

Request Body

Required*

SecretConfig

Include the cluster and subdomain for the NLB subdomain that you want to remove the secret from.

Example request

curl -X POST "/global/v2/nlb-dns/regenerateCert"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "subdomain": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

202
The cert has been successfully triggered for regeneration.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster, subdomain, or secret could not be found. To list clusters you have access to, run ibmcloud ks cluster ls. To list existing NLB subdomains and relevant secret names, run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_id>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Registers Multishift domains for a cluster.

POST /v2/nlb-dns/registerMSCDomains

Request

Request Body

Required*

MSCRegistration

The input parameter to register a Multishift cluster's domains.

Example request

curl -X POST "/global/v2/nlb-dns/registerMSCDomains"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "controller": "example-value",
  "ips": [
    "example-value"
  ]
}'
Copy to clipboard

Response

Response Body

MSCRegisterResp

MSCRegisterResp is returned once multishift controller domains have been registered

Status Code

200
Registered. The multishift cluster domains and cname have been successfully registered.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster or NLB subdomain could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "controller": "example-value",
  "dnsRegistrations": [
    {
      "ips": [
        "example-value"
      ],
      "subdomain": "example-value"
    }
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

In a VPC cluster, create a new NLB subdomain and register a VPC load balancer hostname with the DNS provider. Note that you can create the NLB subdomain with only one VPC load balancer hostname. If the registration fails, an error from the DNS provider is returned.

POST /v2/nlb-dns/vpc/createNlbDNS

Request

Request Body

Required*

NlbVPCConfig

Include the lbHostname parameter that specifies the VPC load balancer hostname that you want to register.

Example request

curl -X POST "/global/v2/nlb-dns/vpc/createNlbDNS"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "dnsType": "example-value",
  "lbHostname": "my-cluster",
  "nlbSubdomain": "example-value",
  "secretNamespace": "my-cluster",
  "type": "example-value"
}'
Copy to clipboard

Response

Response Body

NlbVPCConfig

NlbVPCConfig is the request and response body for the v2 vpc apis

Status Code

201
Created. The NLB subdomain was successfully created and the VPC load balancer hostname is registered with DNS.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified VPC cluster or load balancer hostname could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic. To list existing load balancer hostnames in a cluster, run kubectl get svc -n <namespace>.
500
Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "cluster": "example-value",
  "dnsType": "example-value",
  "lbHostname": "my-cluster",
  "nlbSubdomain": "example-value",
  "secretNamespace": "my-cluster",
  "type": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

In a VPC cluster, remove a load balancer hostname from the DNS record for an existing NLB subdomain. After you remove the load balancer hostname, the NLB subdomain still exists, but no load balancer is associated with it.

POST /v2/nlb-dns/vpc/removeLBHostname

Request

Request Body

Required*

NlbVPCConfig

Include the cluster parameter (required) and the nlbSubdomain parameter (required) for the NLB subdomain that you want to remove the load balancer hostname from.

Example request

curl -X POST "/global/v2/nlb-dns/vpc/removeLBHostname"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "dnsType": "example-value",
  "lbHostname": "my-cluster",
  "nlbSubdomain": "example-value",
  "secretNamespace": "my-cluster",
  "type": "example-value"
}'
Copy to clipboard

Response

Status Code

204
Removed. The load balancer hostname was successfully unregistered from the DNS record for the NLB subdomain.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified VPC cluster or NLB subdomain could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic. To list existing NLB subdomains, run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_id>.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

In a VPC cluster, update the DNS record for an NLB subdomain by replacing the load balancer hostname that is currently associated with the NLB subdomain with another load balancer hostname. Only one load balancer hostname can be associated with an NLB DNS record at a time.

POST /v2/nlb-dns/vpc/replaceLBHostname

Request

Request Body

Required*

NlbVPCConfig

Include only the cluster ID, existing lbHostname that you want to replace, and nlbSubdomain of the DNS record that you want to update.

Example request

curl -X POST "/global/v2/nlb-dns/vpc/replaceLBHostname"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "dnsType": "example-value",
  "lbHostname": "my-cluster",
  "nlbSubdomain": "example-value",
  "secretNamespace": "my-cluster",
  "type": "example-value"
}'
Copy to clipboard

Response

Response Body

NlbVPCConfig

NlbVPCConfig is the request and response body for the v2 vpc apis

Status Code

200
Ok. The request to update the load balancer hostname was successfully processed.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified VPC cluster, load balancer hostname, or NLB subdomain could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic. To list existing load balancer hostnames in a cluster, run kubectl get svc -n <namespace>. To list existing NLB subdomains, run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_id>.
500
Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "cluster": "example-value",
  "dnsType": "example-value",
  "lbHostname": "my-cluster",
  "nlbSubdomain": "example-value",
  "secretNamespace": "my-cluster",
  "type": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Do not use it as this endpoint is not supported in the long term. Rotates the ROKS cluster's HMAC data.

Rotates the HMAC service key, key ID and key GUID associated to the cluster. If the bucket of the cluster doesn't exist it gets created firstly.`

GET /v2/rotateClusterCOSKey

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Query Parameters

cluster
Required*
string
The name or ID of the cluster of which you want to rotate the COS data. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.

Example request

curl -X GET "/global/v2/rotateClusterCOSKey?cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Status Code

204
No Content. Indicates that the rotation was successful.
400
Bad request. The query parameters are either incomplete or in the wrong format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create an OpenShift Container Platform cluster in an IBM Cloud Satellite location. Creating a cluster requires Administrator access to Kubernetes Service in the IBM Cloud account. After you create a Satellite cluster, assign hosts to the cluster to add compute capacity for your workloads.

POST /v2/satellite/createCluster

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group to create the Satellite cluster in. To list the resource group ID of the location, use the GET /v2/satellite/getController API method.

Request Body

Required*

MultishiftCreateCluster

The configuration details for your Satellite cluster, in JSON format. The "controller" field (required) is the name or ID of the location to deploy the cluster to. The "name" field (required) is the name to give the cluster. The "kubeVersion" field is optional, and defaults to the latest Red Hat OpenShift on IBM Cloud version when not specified.

Example request

curl -X POST "/global/v2/satellite/createCluster"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "adminAgentOptIn": false,
  "calicoIPAutodetection": {},
  "controller": "example-value",
  "defaultWorkerPoolEntitlement": "example-value",
  "infrastructureTopology": "public",
  "kubeVersion": "1.28.5",
  "labels": {},
  "name": "my-cluster"
}'
Copy to clipboard

Response

Response Body

MultishiftCreateClusterResponse

MultishiftCreateCluster create multishift cluster response

Status Code

201
Created. The cluster was successfully created in the IBM Cloud Satellite location.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
409
Conflict. A cluster with the same name already exists. Choose another name for your cluster.
500
Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{ "id": "example-id-123" }

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a worker pool for the specified cluster in an IBM Cloud Satellite location. Creating a worker pool requires Operator access to Kubernetes Service in the IBM Cloud account. Specify the worker pool flavor as "upi" for user provided infrastructure. You can also use hostLabels key value pairs so that available hosts with matching labels in the IBM Cloud Satellite location are automatically assigned to the worker pool.

POST /v2/satellite/createWorkerPool

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the GET /v2/satellite/getController API method.

Request Body

Required*

V2SatelliteCreateWorkerPoolRequest

The configuration details for your worker pool, in JSON format.

Example request

curl -X POST "/global/v2/satellite/createWorkerPool"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "Zones": [
    {
      "id": "example-id-123"
    }
  ],
  "cluster": "example-value",
  "diskEncryption": false,
  "entitlement": "example-value",
  "flavor": "example-value",
  "hostLabels": {},
  "isolation": "example-value",
  "labels": {}
}'
Copy to clipboard

Response

Response Body

CreateWorkerpoolResponse

Create workerpool response

Status Code

201
Created. The worker pool was successfully created in the specified cluster.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
409
Conflict. Another worker pool might be provisioning for the specified cluster. Wait a few minutes and try again.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

{ "workerPoolID": "example-id-123" }

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a zone in the specified worker pool for an IBM Cloud Satellite cluster. Worker nodes are provisioned in each zone based on the size per zone of the worker pool.

POST /v2/satellite/createWorkerPoolZone

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the GET /v2/satellite/getController API method.

Request Body

Required*

SatelliteWorkerPoolZoneAdd

Input parameters to add zones to the worker pool.

Example request

curl -X POST "/global/v2/satellite/createWorkerPoolZone"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "id": "example-id-123",
  "workerpool": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

201
OK. The requested zone was added to the worker pool.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the GET /v2/getWorkerPools API or run ibmcloud ks worker-pool ls -c <cluster>.
409
Conflict. The provided zone already exists in the worker pool.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the IBM Cloud Satellite clusters that you have access to.

GET /v2/satellite/getClusters

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the GET /v2/satellite/getController API method.

Example request

curl -X GET "/global/v2/satellite/getClusters"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetClustersResponse[]

GetClustersResponse cluster response for cluster list

Status Code

200
Success. A list of clusters that you have access to is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "addons": [
      {
        "name": "my-cluster",
        "version": "1.28.5"
      }
    ],
    "caCertRotationStatus": {
      "actionCompletedDate": "2024-01-15T10:30:00Z",
      "actionTriggerDate": "2024-01-15T10:30:00Z",
      "status": "example-value"
    },
    "calicoIPAutodetectionConfig": "example-value",
    "createdDate": "2024-01-15T10:30:00Z",
    "datacenter": "example-value",
    "desiredTrustedProfileID": "example-id-123",
    "entitlement": "example-value",
    "etcdPort": "example-value",
    "id": "example-id-123"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create an OpenShift Container Platform cluster in an IBM Cloud Satellite location that belongs to another account. Creating a cluster requires service-to-service IAM authorization in the target IBM Cloud account. After you create a Satellite cluster, the account owner is responsible for providing hosts to run the worker nodes.

POST /v2/satellite/createClusterRemoteLocation

Request

Custom Headers

X-Auth-Supplemental
Required*
string
The IBM Cloud Identity and Access Management (IAM) service CRN token for the service that creates the cluster. For the service CRN token to work for this API request, the user must previously authorize the service with the "Satellite Cluster Creator" action for Satellite in IAM for the IBM Cloud account where the Satellite location exists.
X-Auth-Resource-Group
string
The ID of the resource group the cluster is to be created in.

Request Body

Required*

MultishiftCreateCluster

The configuration details for your Satellite cluster, in JSON format. The "controller" field (required) is the name or ID of the location to deploy the cluster to. The "name" field (required) is the name to give the cluster. The "kubeVersion" field is optional, and defaults to the latest Red Hat OpenShift on IBM Cloud version when not specified.

Example request

curl -X POST "/global/v2/satellite/createClusterRemoteLocation"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Supplemental: example-value"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "adminAgentOptIn": false,
  "calicoIPAutodetection": {},
  "controller": "example-value",
  "defaultWorkerPoolEntitlement": "example-value",
  "infrastructureTopology": "public",
  "kubeVersion": "1.28.5",
  "labels": {},
  "name": "my-cluster"
}'
Copy to clipboard

Response

Response Body

MultishiftCreateClusterResponse

MultishiftCreateCluster create multishift cluster response

Status Code

201
Created. The cluster was successfully created in the IBM Cloud Satellite location.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
409
Conflict. A cluster with the same name already exists. Choose another name for your cluster.
500
Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{ "id": "example-id-123" }

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the clusters that are associated with a Satellite-enabled service that you deployed to your IBM Cloud Satellite location. The clusters in this list are managed by IBM Cloud to provide the cloud service in the location, but you still provide the hosts to run the clusters.

GET /v2/satellite/getServiceClusters

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the GET /v2/satellite/getController API method.

Query Parameters

controller
Required*
string
The ID of the location to list services.

Example request

curl -X GET "/global/v2/satellite/getServiceClusters?controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

MultishiftClustersResponse[]

MultishiftGetServiceClusters describes a multishift service clusters response

Status Code

200
Success. A list of Satellite-enabled service clusters that you have access to is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "addons": [
      {
        "name": "my-cluster",
        "version": "1.28.5"
      }
    ],
    "caCertRotationStatus": {
      "actionCompletedDate": "2024-01-15T10:30:00Z",
      "actionTriggerDate": "2024-01-15T10:30:00Z",
      "status": "example-value"
    },
    "calicoIPAutodetectionConfig": "example-value",
    "createdDate": "2024-01-15T10:30:00Z",
    "datacenter": "example-value",
    "desiredTrustedProfileID": "example-id-123",
    "entitlement": "example-value",
    "etcdPort": "example-value",
    "id": "example-id-123",
    "locationZones": [
      "us-south"
    ],
    "workerPools": [
      {
        "isolation": "example-value",
        "labels": {},
        "machineType": "example-value",
        "name": "my-cluster",
        "operatingSystem": "example-value",
        "sizePerZone": 3
      }
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create an IBM Cloud Satellite location in the IBM Cloud account that you are logged into. Creating a location requires Administrator access to Kubernetes Service in the IBM Cloud account.

POST /v2/satellite/createController

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group to create the Satellite location in. To list available resource group IDs from the command line, run ibmcloud resource groups.

Request Body

Required*

MultishiftCreateController

The configuration details for your Satellite location, in JSON format.

Example request

curl -X POST "/global/v2/satellite/createController"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "calicoIPAutodetection": {},
  "capabilitiesManagedBySatellite": [
    "example-value"
  ],
  "coreos_enabled": true,
  "cos_config": {
    "bucket": "example-value",
    "endpoint": "https://example.com",
    "region": "us-south",
    "serviceInstance": {
      "crn": "example-value"
    }
  },
  "cos_credentials": {
    "access_key-id": "example-id-123",
    "secret_access_key": "example-value"
  },
  "description": "example-value",
  "iaas": {
    "credentials": false,
    "provider": "vpc-gen2",
    "region": "us-south"
  },
  "ingestion_keys": {
    "activity_tracker_key": "example-value",
    "logging_key": "example-value"
  },
  "zones": [
    "us-south-1"
  ]
}'
Copy to clipboard

Response

Response Body

MultishiftCreateControllerResponse

MultishiftCreateController create controller response

Status Code

201
Created. The location was successfully created in the IBM Cloud account that you are logged in to.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
409
Conflict. A location with the same name already exists. Choose another name for your location.
500
Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "crn": "example-value",
  "id": "example-id-123"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get the details for an IBM Cloud Satellite location.

GET /v2/satellite/getController

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the Satellite location is in. To list available resource group IDs from the command line, run ibmcloud resource groups. To list the resource group ID of the location, use the GET /v2/satellite/getController API method.

Query Parameters

controller
Required*
string
The ID of the location to get information about.

Example request

curl -X GET "/global/v2/satellite/getController?controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

MultishiftGetController

MultishiftGetController describes a multishift controller

Status Code

200
Success. The details of the requested IBM Satellite location are returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Could not find the IBM Cloud Satellite location. To list available locations, use the GET /v2/satellite/getControllers API, or run ibmcloud sat location ls.
500
Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "activityTrackerKeyProvided": false,
  "addons": [
    {
      "name": "my-cluster",
      "version": "1.28.5"
    }
  ],
  "caCertRotationStatus": {
    "actionCompletedDate": "2024-01-15T10:30:00Z",
    "actionTriggerDate": "2024-01-15T10:30:00Z",
    "status": "example-value"
  },
  "calicoIPAutodetectionConfig": "example-value",
  "capabilitiesManagedBySatellite": [
    "example-value"
  ],
  "coreosEnabled": true,
  "cos_config": {
    "bucket": "example-value",
    "endpoint": "https://example.com",
    "region": "us-south",
    "serviceInstance": {
      "crn": "example-value"
    }
  },
  "createdDate": "2024-01-15T10:30:00Z",
  "id": "example-id-123",
  "locationZones": [
    "us-south"
  ],
  "supportedOperatingSystems": [
    "example-value"
  ],
  "vpcs": [
    "example-value"
  ],
  "workerZones": [
    "us-south-1"
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the IBM Cloud Satellite locations that you have access to.

GET /v2/satellite/getControllers

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group to filter Satellite locations for. To list available resource group IDs from the command line, run ibmcloud resource groups.

Example request

curl -X GET "/global/v2/satellite/getControllers"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

MultishiftController[]

MultishiftController describes an individual controller

Status Code

200
Success. A list of locations that you have access to is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
500
Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "activityTrackerKeyProvided": false,
    "capabilitiesManagedBySatellite": [
      "example-value"
    ],
    "coreosEnabled": true,
    "createdDate": "2024-01-15T10:30:00Z",
    "crn": "example-value",
    "deployments": {
      "enabled": true,
      "message": "example-value"
    },
    "hostUpdateSeverity": "2024-01-15T10:30:00Z",
    "hosts": {
      "available": 1,
      "total": 1
    },
    "id": "example-id-123",
    "workerZones": [
      "us-south-1"
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Remove an IBM Cloud Satellite location. Before you can remove a location, you must remove any Satellite clusters and the underlying host machines. To list the hosts in your location, run ibmcloud sat hosts --location <name_or_ID> and check the Cluster and Worker details in the output.

POST /v2/satellite/removeController

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the GET /v2/satellite/getController API method.

Request Body

MultishiftCreateClusterFragment

The IBM Satellite location to remove.

Example request

curl -X POST "/global/v2/satellite/removeController"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "calicoIPAutodetection": {},
  "controller": "example-value",
  "infrastructureTopology": "public",
  "networkPlugin": "calico",
  "pullSecret": "example-value"
}'
Copy to clipboard

Response

Status Code

204
OK. The request to remove your IBM Cloud Satellite location was successfully received.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Could not find the IBM Cloud Satellite location. To list available locations, use the GET /v2/satellite/getControllers API, or run ibmcloud sat location ls.
409
Conflict. Cannot delete an IBM Cloud Satellite location that has active clusters. To list the clusters in the Satellite location, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls.
500
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Assign a host to an IBM Cloud Satellite location or cluster. Before you can assign hosts to clusters, first assign at least three hosts to the Satellite location, to run control plane operations. Then, when you have Satellite clusters, you can assign hosts as needed to provide compute resources for your workloads. You can assign hosts by specifying a host ID or by providing labels to match hosts to your request.

POST /v2/satellite/hostqueue/createAssignment

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the GET /v2/satellite/getController API method.

Request Body

Required*

MultishiftCreateAssignment

The configuration details to assign a host to an IBM Cloud Satellite resource, in JSON format. The "cluster" field (required) indicates the name or ID of the IBM Cloud Satellite resource to assign the host. The resource can be the name or ID of the Satellite location itself, or an IBM Cloud Satellite cluster. If "hostID" is specified, that host is assigned if it is available. If a set of "labels" is specified, all the available hosts are scanned to find a host that matches all the labels. If neither "hostID" nor "labels" are specified, a random available host is assigned.

Example request

curl -X POST "/global/v2/satellite/hostqueue/createAssignment"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "controller": "example-value",
  "hostID": "example-id-123",
  "labels": {},
  "workerpool": "example-value",
  "zone": "us-south-1"
}'
Copy to clipboard

Response

Response Body

MultishiftCreateAssignmentResponse

MultishiftCreateAssignment create multishift assignment response

Status Code

201
Created. A host was successfully assigned to your IBM Cloud Satellite resource.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
404
Could not find the IBM Cloud Satellite location. To list available locations, use the GET /v2/satellite/getControllers API, or run ibmcloud sat location ls.
409
Conflict. Could not find any available hosts that match your requested host ID or label parameters.
500
Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "hostID": "example-id-123",
  "id": "example-id-123"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a script to run on a Red Hat Enterprise Linux 7 host in your on-premises infrastructure. The script attaches the host to your IBM Cloud Satellite location. The host must have access to the public network in order for the script to complete.

POST /v2/satellite/hostqueue/createRegistrationScript

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the GET /v2/satellite/getController API method.
Accept
string
Allowable values: [text/plain,application/json]

Request Body

Required*

MultishiftNodeQueue

The configuration details to create an attachment script for your Satellite location, in JSON format. The "labels" field (required) is a set of key-value pairs to describe your host, such as cpu=4. Later, when you assign a host to IBM Cloud Satellite resources, these labels are used to match your host with your request.

Example request

curl -X POST "/global/v2/satellite/hostqueue/createRegistrationScript"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "controller": "example-value",
  "labels": {}
}'
Copy to clipboard

Response

Response Body

string

Status Code

201
Created. The response contains a script that you can run on your host to attach the host to your IBM Cloud Satellite location.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
404
Could not find the IBM Cloud Satellite location. To list available locations, use the GET /v2/satellite/getControllers API, or run ibmcloud sat location ls.
500
Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}
{}
{}
{}

List the hosts in your IBM Cloud Satellite location.

GET /v2/satellite/hostqueue/getHosts

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the GET /v2/satellite/getController API method.

Query Parameters

controller
Required*
string
The ID of the location to to retrieve hosts from.

Example request

curl -X GET "/global/v2/satellite/hostqueue/getHosts?controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

MultishiftQueueNode[]

MultishiftQueueNode describes an individual queue node

Status Code

200
Success. A list of hosts in your IBM Cloud Satellite location is returned.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Could not find the IBM Cloud Satellite location. To list available locations, use the GET /v2/satellite/getControllers API, or run ibmcloud sat location ls.
500
Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "assignment": {
      "clusterID": "example-id-123",
      "clusterName": "my-cluster",
      "ipAddress": "example-value",
      "receivedDate": "2024-01-15T10:30:00Z",
      "requestedDate": "2024-01-15T10:30:00Z",
      "updateSeverity": "2024-01-15T10:30:00Z",
      "workerID": "example-id-123",
      "workerPoolID": "example-id-123"
    },
    "health": {
      "message": "example-value",
      "modifiedDate": "2024-01-15T10:30:00Z",
      "status": "example-value"
    },
    "id": "example-id-123",
    "labels": {},
    "name": "my-cluster",
    "state": "example-value"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Remove a host from an IBM Cloud Satellite resource, such as a cluster. The host is removed from the resource and no longer available in IBM Cloud Satellite. However, if you want, you must still delete the host machine in the underlying infrastructure provider. Before you can remove a host, you must remove the worker node that runs on the host. To check worker nodes on the host, use the GET /v2/satellite/hostqueue/getHosts API or run ibmcloud sat host ls. To remove a worker node, run ibmcloud ks worker rm -c <cluster_name_or_ID> -w <worker_ID>.

POST /v2/satellite/hostqueue/removeHost

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the GET /v2/satellite/getController API method.

Request Body

Required*

MultishiftRemoveNode

The configuration details to remove a host from an IBM Cloud Satellite location, in JSON format.

Example request

curl -X POST "/global/v2/satellite/hostqueue/removeHost"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "controller": "example-value",
  "hostID": "example-id-123"
}'
Copy to clipboard

Response

Status Code

204
OK. The host was successfully removed from your IBM Cloud Satellite location.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
404
Could not find the host. To list available hosts, use the GET /v2/satellite/hostqueue/getHosts API or run ibmcloud sat host ls.
409
Conflict. Cannot remove the host because a worker node runs on the host. Remove the worker node and try again.
500
Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Update the labels of a host in your IBM Cloud Satellite location. You can apply a new set of labels only to hosts that are not already assigned to an IBM Cloud Satellite resource.

POST /v2/satellite/hostqueue/updateHost

Request

Custom Headers

X-Auth-Resource-Group
string
The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the GET /v2/satellite/getController API method.

Request Body

Required*

MultishiftUpdateNode

The configuration details to update a host to an IBM Cloud Satellite resource, in JSON format.

Example request

curl -X POST "/global/v2/satellite/hostqueue/updateHost"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "controller": "example-value",
  "hostID": "example-id-123",
  "labels": {}
}'
Copy to clipboard

Response

Status Code

204
OK. The host was successfully updated.
400
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
403
Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
404
Could not find the host. To list available hosts, use the GET /v2/satellite/hostqueue/getHosts API or run ibmcloud sat host ls.
409
Conflict. The labels cannot be updated because the host is already assigned to an IBM Cloud Satellite resource, such as a cluster.
500
Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create volume attachment for a given worker

POST /v2/storage/createAttachment

Request

Custom Headers

X-Auth-Resource-Group-ID
Required*
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster-get <cluster>.

Request Body

Required*

object

The config includes ID of the cluster, ID of the worker on which you want to attach a volume, and the unique volume ID of the volume to be attached to a worker. To list the clusters that you have access to, run ibmcloud ks clusters. To list all worker nodes for a cluster, run ibmcloud ks workers <cluster_name_or_ID>. To list the volumes that you have access to, run ibmcloud is vols.

Example request

curl -X POST "/global/v2/storage/createAttachment"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group-ID: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "volumeID": "example-id-123",
  "worker": "example-value"
}'
Copy to clipboard

Response

Response Body

VolumeAttachment

Volume attachment

Status Code

201
Ok. Attach request successfully accepted.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified worker could not be found. To list the workers, use the GET /v2/vpc/getWorkers API or run ibmcloud ks workers --cluster <clusterID or Name>.
500
Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "device": {
    "id": "example-id-123"
  },
  "id": "example-id-123",
  "name": "my-cluster",
  "status": "example-value",
  "type": "example-value",
  "volume": {
    "accountId": "example-id-123",
    "capacity": 1,
    "cluster": "example-value",
    "clusterstatus": "example-value",
    "created_at": "example-value",
    "crn": "example-value",
    "datacenter": "example-value",
    "delete_cluster_resources": "example-value",
    "id": "example-id-123",
    "tags": [
      "example-value"
    ]
  }
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Detach volume from given worker.

POST /v2/storage/deleteAttachment

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster-get <cluster>.

Request Body

Required*

VPCVolumeAttachmentConfig

The config includes ID of the cluster, ID of the worker from which you want to detach volume, and the unique volume attachment ID for the attached volume. To list the clusters that you have access to, run ibmcloud ks clusters. To list all worker nodes for a cluster, run ibmcloud ks workers <cluster_name_or_ID>.

Example request

curl -X POST "/global/v2/storage/deleteAttachment"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group-ID: example-id-123"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "volumeAttachmentID": "example-id-123",
  "volumeID": "example-id-123",
  "worker": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

201
Ok. detach request successfully accepted.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified worker could not be found. To list the workers, use the GET /v2/vpc/getWorkers API or run ibmcloud ks workers --cluster <clusterID or Name>.
500
Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get the volume attachment detail for given volume attachment ID

GET /v2/storage/getAttachment

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster-get <cluster>.

Query Parameters

cluster
Required*
string
The ID or name of the cluster. To list the clusters that you have access to, run ibmcloud ks clusters.
worker
Required*
string
The ID of the worker node, whose volume attachments needs to be listed. To list all worker nodes for a cluster, run ibmcloud ks workers <cluster_name_or_ID>.
volume_attachment_id
Required*
string
The unique volume attachment ID for the attached volume

Example request

curl -X GET "/global/v2/storage/getAttachment?cluster=example-value&worker=example-value&volume_attachment_id=example-id-123"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group-ID: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

VolumeAttachment

Volume attachment

Status Code

200
Ok.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified worker could not be found. To list the workers, use the GET /v2/vpc/getWorkers API or run ibmcloud ks workers --cluster <clusterID or Name>.
500
Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "device": {
    "id": "example-id-123"
  },
  "id": "example-id-123",
  "name": "my-cluster",
  "status": "example-value",
  "type": "example-value",
  "volume": {
    "accountId": "example-id-123",
    "capacity": 1,
    "cluster": "example-value",
    "clusterstatus": "example-value",
    "created_at": "example-value",
    "crn": "example-value",
    "datacenter": "example-value",
    "delete_cluster_resources": "example-value",
    "id": "example-id-123",
    "tags": [
      "example-value"
    ]
  }
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get the volume attachments detail for a given worker

GET /v2/storage/getAttachments

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster-get <cluster>.

Query Parameters

cluster
Required*
string
The ID or name of the cluster. To list the clusters that you have access to, run ibmcloud ks clusters.
worker
Required*
string
The ID of the worker node, whose volume attachments needs to be listed.

Example request

curl -X GET "/global/v2/storage/getAttachments?cluster=example-value&worker=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group-ID: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

VolumeAttachmentList

Volume attachment list

Status Code

200
Ok.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified worker could not be found. To list the workers, use the GET /v2/vpc/getWorkers API or run ibmcloud ks workers --cluster <clusterID or Name>.
500
Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "volume_attachments": [
    {
      "device": {
        "id": "example-id-123"
      },
      "id": "example-id-123",
      "name": "my-cluster",
      "status": "example-value",
      "type": "example-value",
      "volume": {
        "accountId": "example-id-123",
        "capacity": 1,
        "cluster": "example-value",
        "clusterstatus": "example-value",
        "created_at": "example-value",
        "crn": "example-value",
        "datacenter": "example-value",
        "delete_cluster_resources": "example-value",
        "id": "example-id-123",
        "tags": [
          "example-value"
        ]
      }
    }
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Get the details of a storage volume.

GET /v2/storage/getVolume

Request

Custom Headers

X-Auth-Resource-Group-ID
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster-get <cluster>.

Query Parameters

volume_id
Required*
string
The unique volume ID. To list the volume ID, use the GET /v2/storage/classic/getVolumes API or run ibmcloud ks storage volume ls classic.

Example request

curl -X GET "/global/v2/storage/getVolume?volume_id=example-id-123"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group-ID: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Volume

Volume Volume create/update/delete request

Status Code

200
Ok.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified worker could not be found. To list the workers, use the GET /v2/vpc/getWorkers API or run ibmcloud ks workers --cluster <clusterID or Name>.
500
Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "accountId": "example-id-123",
  "capacity": 1,
  "cluster": "example-value",
  "clusterstatus": "example-value",
  "created_at": "example-value",
  "crn": "example-value",
  "datacenter": "example-value",
  "delete_cluster_resources": "example-value",
  "id": "example-id-123",
  "tags": [
    "example-value"
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List storage volumes for a cluster or for the account if no cluster is provided.

GET /v2/storage/getVolumes

Request

Custom Headers

X-Auth-Resource-Group-ID
Required*
string
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run ibmcloud ks cluster-get <cluster>.

Query Parameters

cluster
string
The ID or name of the classic cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls --provider classic.
provider
string
Filter the list for a specific infrastructure provider. Supported values are classic, vpc-classic, and vpc-gen2.
zone
string
The zone to filter volume results by. To list available zones, run ibmcloud ks locations.

Example request

curl -X GET "/global/v2/storage/getVolumes"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Auth-Resource-Group-ID: example-id-123"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

VolumesList

Volumes list

Status Code

200
Ok.
401
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.
404
Not found. The specified worker could not be found. To list the workers, use the GET /v2/vpc/getWorkers API or run ibmcloud ks workers --cluster <clusterID or Name>.
500
Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "volumes": [
    {
      "accountId": "example-id-123",
      "capacity": 1,
      "cluster": "example-value",
      "clusterstatus": "example-value",
      "created_at": "example-value",
      "crn": "example-value",
      "datacenter": "example-value",
      "delete_cluster_resources": "example-value",
      "id": "example-id-123",
      "tags": [
        "example-value"
      ]
    }
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Acknowledge the request to expand the storage capacity of an existing storage request.

PATCH /v2/storage/satellite/ackDesiredStorageConfigCapacity

Request

Custom Headers

Content-Type
string
Allowable values: [application/json,application/merge-patch+json]

Request Body

Required*

AckDesiredStorageCapacityRequest

Include the ID of the storage request (request-id), the cluster ID (cluster) and the name or ID of the Satellite location (controller) that the cluster is registered to. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

Example request

curl -X PATCH "/global/v2/storage/satellite/ackDesiredStorageConfigCapacity"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "controller": "example-value",
  "request-id": "example-id-123"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

201
OK. The storage request is created.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
The specified cluster or storage request could not be found. Check the input parameters and try again. Verify the input parameters and retry the request. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create an assignment to install the storage driver that is described by the version of the storage configuration on the cluster group(s). Then, apps that run in the clusters, part of cluster group(s), can use the storage.

POST /v2/storage/satellite/createAssignment

Request

Request Body

Required*

CreateSubscriptionInputData

Include following parameters to create an assignment:

Name of the assignment (name).
Storage configuration name or ID (config). To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.
The name or ID of the Satellite location (controller). To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllersAPI or run ibmcloud sat location ls.
One or more cluster groups (groups) on which you want to apply the configuration. Note that at least one cluster group is required. To list the cluster groups that you have access to, run ibmcloud sat group ls.
Enable or disable automatic upgrades for the assignment (autoUpgrade="true|false").

Example request

curl -X POST "/global/v2/storage/satellite/createAssignment"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "autoUpgrade": "example-value",
  "config": "example-value",
  "controller": "example-value",
  "groups": [
    "example-value"
  ],
  "name": "my-cluster"
}'
Copy to clipboard

Response

Response Body

CreateSubscriptionData

Create subscription data

Status Code

200
OK. An assignment using the storage configuration is created.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified config or cluster group(s) could not be found. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls. To list the Satellite cluster groups you have access to, run ibmcloud sat group ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "addSubscription": {
    "message": "example-value",
    "recoveryCLI": "example-value",
    "uuid": "example-id-123"
  }
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create an assignment to install the storage driver described by the version of the storage configuration on the Satellite cluster or service cluster. Then, apps that run in the cluster can use the storage.

POST /v2/storage/satellite/createAssignmentByCluster

Request

Request Body

Required*

CreateSubscriptionByClusterInputData

Include following parameters to create an assignment:

Name of the assignment (name).
Storage configuration name or ID (config). To list the storage configurations for a location that you have access to, use the GET /v2/storage/satellite/getStorageConfigurationsByController API or run ibmcloud sat storage config ls --location LOCATION.
ID of the Satellite cluster or service cluster that you want to apply the configuration to (cluster). To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
The name or ID of the Satellite location (controller). To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllersAPI or run ibmcloud sat location ls.
Enable or disable automatic upgrades for the assignment (autoUpgrade="true|false").

Example request

curl -X POST "/global/v2/storage/satellite/createAssignmentByCluster"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "autoUpgrade": "example-value",
  "cluster": "example-value",
  "config": "example-value",
  "controller": "example-value",
  "name": "my-cluster"
}'
Copy to clipboard

Response

Response Body

CreateSubscriptionData

Create subscription data

Status Code

200
OK. An assignment using the storage configuration is created.
400
Bad Request. The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified config or cluster or location could not be found. To list the storage configurations for the location that you have access to, use the GET /v2/storage/satellite/getStorageConfigurationsByController API or run ibmcloud sat storage config ls --location LOCATION. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, run ibmcloud sat location ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "addSubscription": {
    "message": "example-value",
    "recoveryCLI": "example-value",
    "uuid": "example-id-123"
  }
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a Satellite storage configuration based off the storage template, custom parameters, and location that you want to use. Then, assign the storage configuration to your clusters to install the storage driver so that the apps that run in the cluster can use the storage.

POST /v2/storage/satellite/createStorageConfiguration

Request

Request Body

Required*

StorageConfigCreateInput

Include a name for the storage configuration (config-name), the storage template name (storage-template-name), version (storage-template-version), required parameters as per the template specified (user-config-parameters, user-secret-parameters, and/or storage-class-parameters) and the Satellite location (location) where you want to use the storage configuration. To list the storage templates and template versions, run ibmcloud sat storage template ls. To list the parameters for a given storage template and template version, run ibmcloud sat storage template get --name=<template-name> --version=<template-version>. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Example request

curl -X POST "/global/v2/storage/satellite/createStorageConfiguration"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "config-name": "my-cluster",
  "controller": "example-value",
  "storage-class-parameters": [
    {}
  ],
  "storage-template-name": "my-cluster",
  "storage-template-version": "1.28.5",
  "user-config-parameters": {},
  "user-secret-parameters": {}
}'
Copy to clipboard

Response

Response Body

CreateConfigurationData

CreateConfigurationData - a single return struct

Status Code

201
OK. The storage configuration is created.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "addChannel": {
    "uuid": "example-id-123"
  }
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a Satellite storage configuration based on the storage template, custom parameters, and location that you want to use. After you create the configuration, install the storage driver by assigning the configuration to your clusters or cluster groups with the /v2/storage/satellite/createAssignmentByCluster or /v2/storage/satellite/createAssignment APIs.

POST /v2/storage/satellite/createStorageConfigurationByController

Request

Request Body

Required*

StorageConfigCreateInput

Include a name for the storage configuration (config-name); the storage template name (storage-template-name), version (storage-template-version) (optionally; if unspecified, the default storage template version is picked), required parameters as per the template specified (user-config-parameters, user-secret-parameters, and/or storage-class-parameters) and ID of the Satellite location (controller) where you want to use the storage configuration. The update-assignments payload parameter may be ignored.

Enter a storage configuration name that is less than 253 characters long and contains only lowercase letters, numbers, -, or ..

To list the storage templates and template versions that you have access to, run ibmcloud sat storage template ls. To list the parameters for a given storage template and template version, run ibmcloud sat storage template get --name=<template-name> --version=<template-version>. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Example request

curl -X POST "/global/v2/storage/satellite/createStorageConfigurationByController"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "config-name": "my-cluster",
  "controller": "example-value",
  "storage-class-parameters": [
    {}
  ],
  "storage-template-name": "my-cluster",
  "storage-template-version": "1.28.5",
  "user-config-parameters": {},
  "user-secret-parameters": {}
}'
Copy to clipboard

Response

Response Body

CreateConfigurationData

CreateConfigurationData - a single return struct

Status Code

201
OK. The storage configuration is created.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "addChannel": {
    "uuid": "example-id-123"
  }
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Expand the capacity of an existing storage request. Specify the storage request that you want to expand, the cluster it is associated with, and the desired total capacity. Note that capacity expansion is subject to acknowledgement from the Satellite location administator.

To check if the Satellite location administrator has acknowledged the capacity expansion for a given storage request, use the /v2/satellite/getDesiredStorageConfig API. After the capacity expansion is acknowledged, the status field in the backend section of the /v2/satellite/getDesiredStorageConfig API response is set to completed.

PATCH /v2/storage/satellite/expandDesiredStorageConfigCapacity

Request

Custom Headers

Content-Type
string
Allowable values: [application/json,application/merge-patch+json]

Request Body

Required*

ExpandDesiredStorageCapacityRequest

Include the ID of the storage request (request-id), the cluster ID (cluster) on which it is placed, and the desired total capacity (total-capacity). Specify the desired total capacity as a positive integer value in kilobytes (K), megabytes (M), gigabytes (G), terabytes (T) or exabytes (E). For example, specify 100G for 100 GB. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API. To list the Satellite clusters you have access to, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

Example request

curl -X PATCH "/global/v2/storage/satellite/expandDesiredStorageConfigCapacity"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "request-id": "example-id-123",
  "total-capacity": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

201
OK. The storage request is created.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
The specified cluster or storage request could not be found. Check the input parameters and try again. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List Satellite storage configurations that are assigned to a Satellite cluster or service cluster.

GET /v2/storage/satellite/getAssignedStorageConfigs

Request

Query Parameters

cluster
Required*
string
ID of the Satellite cluster or service cluster to list the assigned storage configurations for. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
controller
Required*
string
The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite.

Example request

curl -X GET "/global/v2/storage/satellite/getAssignedStorageConfigs?cluster=example-value&controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

AppliedStorageConfig[]

AppliedStorageConfig contains the details of an assigned storage config on a cluster A list of AppliedStorageConfig structs is the response for the GetAssignedStorageConfigs query

Status Code

200
OK. Assigned Satellite storage configurations are listed.
400
Bad Request. The request failed due to one of the following reasons:
1. The cluster is missing or the specified cluster is invalid.
2. The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified cluster or location could not be found. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, run ibmcloud sat location ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "assignment-uuid": "example-id-123",
    "config-attributes": {
      "offering-name": "my-cluster",
      "provider": "vpc-gen2",
      "storage-classes": [
        "example-value"
      ],
      "template-name": "my-cluster",
      "template-version": "1.28.5",
      "total-capacity": "example-value",
      "volume-availability": "example-value",
      "volume-encryption-at-rest": "example-value"
    },
    "config-name": "my-cluster",
    "config-uuid": "example-id-123",
    "rollout-status": {
      "error-count": 3,
      "success-count": 3
    }
  }
]
Copy to clipboard

Status 401

[
  {
    "code": "E0001",
    "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
    "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "recoveryCLI": "ibmcloud iam oauth-tokens",
    "terseDescription": "Unauthorized",
    "type": "Authentication"
  }
]
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View details of an assignment by the assignment UUID.

GET /v2/storage/satellite/getAssignment

Request

Query Parameters

uuid
Required*
string
The UUID of the assignment. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

Example request

curl -X GET "/global/v2/storage/satellite/getAssignment?uuid=example-id-123"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Subscription

Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59

Status Code

200
OK. Assignment details are returned.
400
Bad Request. Either the uuid is missing or the specified uuid is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified assignment could not be found. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "channelName": "my-cluster",
  "channelUuid": "example-id-123",
  "cluster": "example-value",
  "clusterName": "my-cluster",
  "configRevisionStatus": {
    "isRevisionUpdateAvailable": false,
    "latestRevision": "example-value",
    "revision": "example-value"
  },
  "created": "example-value",
  "groups": [
    "example-value"
  ],
  "isAssignmentUpgradeAvailable": false,
  "remoteResources": [
    {
      "cluster": {
        "clusterId": "example-id-123",
        "name": "my-cluster"
      },
      "lastModified": "example-value",
      "searchableData": {
        "kind": "example-value",
        "name": "my-cluster",
        "namespace": "my-cluster",
        "searchableExpression": "example-value"
      }
    }
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View details of an assignment by the assignment name.

GET /v2/storage/satellite/getAssignmentByName

Request

Query Parameters

name
Required*
string
The name of the assignment. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

Example request

curl -X GET "/global/v2/storage/satellite/getAssignmentByName?name=my-cluster"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Subscription

Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59

Status Code

200
OK. Assignment details successfully fetched.
400
Bad Request. Either the name is missing or the specified name is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified assignment could not be found. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "channelName": "my-cluster",
  "channelUuid": "example-id-123",
  "cluster": "example-value",
  "clusterName": "my-cluster",
  "configRevisionStatus": {
    "isRevisionUpdateAvailable": false,
    "latestRevision": "example-value",
    "revision": "example-value"
  },
  "created": "example-value",
  "groups": [
    "example-value"
  ],
  "isAssignmentUpgradeAvailable": false,
  "remoteResources": [
    {
      "cluster": {
        "clusterId": "example-id-123",
        "name": "my-cluster"
      },
      "lastModified": "example-value",
      "searchableData": {
        "kind": "example-value",
        "name": "my-cluster",
        "namespace": "my-cluster",
        "searchableExpression": "example-value"
      }
    }
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List storage assignments that you have access to in the IBM Cloud account. Returned details include the assignment name, UUID, and creation timestamp.

GET /v2/storage/satellite/getAssignments

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET "/global/v2/storage/satellite/getAssignments"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Subscription[]

Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59

Status Code

200
OK. Assignments are listed.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
500
Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "channelName": "my-cluster",
    "channelUuid": "example-id-123",
    "cluster": "example-value",
    "clusterName": "my-cluster",
    "configRevisionStatus": {
      "isRevisionUpdateAvailable": false,
      "latestRevision": "example-value",
      "revision": "example-value"
    },
    "created": "example-value",
    "groups": [
      "example-value"
    ],
    "isAssignmentUpgradeAvailable": false,
    "remoteResources": [
      {
        "cluster": {
          "clusterId": "example-id-123",
          "name": "my-cluster"
        },
        "lastModified": "example-value",
        "searchableData": {
          "kind": "example-value",
          "name": "my-cluster",
          "namespace": "my-cluster",
          "searchableExpression": "example-value"
        }
      }
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List storage assignments created for a Satellite cluster or service cluster. Returned details include the assignment name, UUID, and creation timestamp.

GET /v2/storage/satellite/getAssignmentsByClusterID

Request

Query Parameters

cluster
Required*
string
ID of the Satellite cluster or service cluster to list the storage assignments for. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
controller
Required*
string
The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite.

Example request

curl -X GET "/global/v2/storage/satellite/getAssignmentsByClusterID?cluster=example-value&controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Subscription[]

Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59

Status Code

200
OK. Assignments are listed.
400
Bad Request. The request failed due to one of the following reasons:
1. The cluster is missing or the specified cluster is invalid. 2.The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified cluster or location could not be found. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, run ibmcloud sat location ls.
500
Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "channelName": "my-cluster",
    "channelUuid": "example-id-123",
    "cluster": "example-value",
    "clusterName": "my-cluster",
    "configRevisionStatus": {
      "isRevisionUpdateAvailable": false,
      "latestRevision": "example-value",
      "revision": "example-value"
    },
    "created": "example-value",
    "groups": [
      "example-value"
    ],
    "isAssignmentUpgradeAvailable": false,
    "remoteResources": [
      {
        "cluster": {
          "clusterId": "example-id-123",
          "name": "my-cluster"
        },
        "lastModified": "example-value",
        "searchableData": {
          "kind": "example-value",
          "name": "my-cluster",
          "namespace": "my-cluster",
          "searchableExpression": "example-value"
        }
      }
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List storage assignments by configuration name or UUID. Returned details include the assignment name, UUID, and creation timestamp.

GET /v2/storage/satellite/getAssignmentsByConfig

Request

Query Parameters

config
Required*
string
The name or ID of the Satellite storage configuration. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.

Example request

curl -X GET "/global/v2/storage/satellite/getAssignmentsByConfig?config=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Subscription[]

Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59

Status Code

200
OK. Assignments are listed.
400
Bad Request. Either the config is missing or the specified config is invalid. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified config could not be found. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.
500
Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "channelName": "my-cluster",
    "channelUuid": "example-id-123",
    "cluster": "example-value",
    "clusterName": "my-cluster",
    "configRevisionStatus": {
      "isRevisionUpdateAvailable": false,
      "latestRevision": "example-value",
      "revision": "example-value"
    },
    "created": "example-value",
    "groups": [
      "example-value"
    ],
    "isAssignmentUpgradeAvailable": false,
    "remoteResources": [
      {
        "cluster": {
          "clusterId": "example-id-123",
          "name": "my-cluster"
        },
        "lastModified": "example-value",
        "searchableData": {
          "kind": "example-value",
          "name": "my-cluster",
          "namespace": "my-cluster",
          "searchableExpression": "example-value"
        }
      }
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List storage assignments that you have access to in a Satellite location. Returned details include the assignment name, UUID, and creation timestamp.

GET /v2/storage/satellite/getAssignmentsByController

Request

Query Parameters

controller
Required*
string
The name or ID of the Satellite location to list assignments for. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Example request

curl -X GET "/global/v2/storage/satellite/getAssignmentsByController?controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Subscription[]

Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59

Status Code

200
OK. Assignments are listed.
400
Bad Request. The controller is missing. To list the Satellite locations that you have access to, run ibmcloud sat location ls.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified location could not be found. To list the Satellite locations that you have access to, run ibmcloud sat location ls.
500
Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "channelName": "my-cluster",
    "channelUuid": "example-id-123",
    "cluster": "example-value",
    "clusterName": "my-cluster",
    "configRevisionStatus": {
      "isRevisionUpdateAvailable": false,
      "latestRevision": "example-value",
      "revision": "example-value"
    },
    "created": "example-value",
    "groups": [
      "example-value"
    ],
    "isAssignmentUpgradeAvailable": false,
    "remoteResources": [
      {
        "cluster": {
          "clusterId": "example-id-123",
          "name": "my-cluster"
        },
        "lastModified": "example-value",
        "searchableData": {
          "kind": "example-value",
          "name": "my-cluster",
          "namespace": "my-cluster",
          "searchableExpression": "example-value"
        }
      }
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List and filter the available storage classes from assigned Satellite storage configurations on a Satellite or service cluster. By default, only the available storage classes from Software Defined Storage (SDS) template based Satellite storage configurations are returned. To view all available storage classes, set the onlyShowSDS query paramter flag to false. Optionally, filter the available storage classes based on volume type using the volumeType query parameter.

Note that, if a volume type is specified, the most preferable storage class from each of the assigned storage configurations of specified volume type is returned. For user-defined storage classes, the preference is set while creating the storage configuration. To view the preference for all the storage classes of an assigned storage configuration, run ibmcloud sat storage config class ls --config CONFIG --show-params and look for the parameter storage-class-preference.

GET /v2/storage/satellite/getAvailableStorageClasses

Request

Query Parameters

cluster
Required*
string
The ID of the Satellite cluster or service cluster for which available storage classes from assigned Satellite storage configurations are to be listed. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
controller
Required*
string
The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite.
volume_type
string
Filter the available storage classes by volume type. The supported volume types are file, block and object. If unspecified, available storage classes of all volume types are returned.
only_show_sds
boolean
Specify true or false to view only the available storage classes from software-defined storage (SDS) storage configurations. If unspecified, the default value is true.

Example request

curl -X GET "/global/v2/storage/satellite/getAvailableStorageClasses?cluster=example-value&controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

AvailableStorageClasses

AvailableStorageClasses contains a list of storage class names It is the response for GetAvailableStorageClasses query

Status Code

200
OK. Available storage classes are listed.
400
Bad Request. The request failed due to one of the following reasons:
1. The cluster is missing or the specified cluster is invalid. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
2. The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
3. The specified value is an invalid value for parameter volumeType. Supported values for volumeType parameter are: file, block, object.
4. The specified value is an invalid value for parameter onlyShowSDS. Supported values for onlyShowSDS parameter are: true, false.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified cluster or location could not be found. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, run ibmcloud sat location ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "storage-classes": [
    "example-value"
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the storage requests for a cluster in a Satellite location.

GET /v2/storage/satellite/getDesiredStorageConfig

Request

Query Parameters

cluster
Required*
string
The ID of the cluster where you want to list storage requests. To list the Satellite clusters you have access to, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>. The response body for each storage request contains the request specifications and the following fields:
1. Theassignment field. This field is initially empty when the storage request is created. When the location administrator assigns a storage configuration to the cluster that matches the storage request, this field is populated with the UUID of the assignment.
2. A status field in the config section that indicates the status of storage provisioning or assignment. If a storage assignment is created but no action is taken on it, the status is set to pending. If a storage configuration has been assigned to the cluster, the status is set to assigned. If the storage request is deleted, the status is set to deleted.
3. A status field in the backend section. This field indicates whether the location administrator has acknowledged the request to increase storage capacity. If the storage capacity expansion request is not acknowledged, the status is set to pending. If the request is acknowledged by the location administrator, the status is set to completed.
controller
Required*
string
The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

Example request

curl -X GET "/global/v2/storage/satellite/getDesiredStorageConfig?cluster=example-value&controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetDesiredStorageConfigResponse[]

GetDesiredStorageConfigResponse is the respose body for getDesiredStorageConfig API

Status Code

201
OK. Storage requests are listed.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Could not list the IBM Cloud Satellite storage requests. Verify the input parameters and retry the request. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.
500
Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

[
  {
    "cluster": "example-value",
    "storage-requests": [
      {
        "assignment": "example-value",
        "backend": {
          "attribute": {
            "max-volume-size": "example-value",
            "total-capacity": "example-value"
          },
          "status": "example-value"
        },
        "config": {
          "attribute": {
            "offering-type": "example-value",
            "provider": "vpc-gen2",
            "storageclasses": [
              "example-value"
            ],
            "supported-ocp-versions": "1.28.5",
            "volume-availability": "example-value",
            "volume-encryption-at-rest": "example-value",
            "volume-expansion": "example-value",
            "volume-snapshot": "example-value"
          },
          "status": "example-value"
        },
        "request-id": "example-id-123"
      }
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View the details of a Satellite storage configuration.

GET /v2/storage/satellite/getStorageConfiguration

Request

Query Parameters

name
Required*
string
The name of the storage configuration. To list the storage configurations that you have access to, run ibmcloud sat storage config ls.
include-assignments
boolean
Specify true to include details of assignment(s) of the specified storage configuration. The default value is false.

Example request

curl -X GET "/global/v2/storage/satellite/getStorageConfiguration?name=my-cluster"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

StorageConfig

Storage config

Status Code

201
OK. Storage configuration details are returned.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "config-name": "my-cluster",
  "config-version": "1.28.5",
  "controller": "example-value",
  "created": "example-value",
  "is-revision-update-available": false,
  "is-user-secret-parameters-set": {},
  "latest-revision": "example-value",
  "location": "us-south",
  "storage-class-parameters": [
    {}
  ],
  "subscriptions": [
    {
      "cluster": "example-value",
      "clusterName": "my-cluster",
      "created": "example-value",
      "groups": [
        "example-value"
      ],
      "name": "my-cluster",
      "rolloutStatus": {
        "errorCount": 3,
        "successCount": 3
      },
      "subscriptionType": "example-value",
      "tags": [
        "example-value"
      ]
    }
  ],
  "tags": [
    "example-value"
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the Satellite storage configurations that you have access to in a Satellite location or in the IBM Cloud account.

GET /v2/storage/satellite/getStorageConfigurations

Request

Query Parameters

location
string
The name or ID of the Satellite location to list storage configurations for. If no location is specified, all storage configurations that you have access to in the IBM Cloud account are returned. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Example request

curl -X GET "/global/v2/storage/satellite/getStorageConfigurations"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ListStorageConfigData[]

ListStorageConfigData is the response struct for the list storage configuration APIs i.e. getStorageConfigurations & getStorageConfigurationsByController

Status Code

201
OK. Storage configurations are listed.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
500
Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

[
  {
    "config-name": "my-cluster",
    "config-version": "1.28.5",
    "controller": "example-value",
    "created": "example-value",
    "is-revision-update-available": false,
    "latest-revision": "example-value",
    "location": "us-south",
    "revision": "example-value"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the Satellite storage configurations that you have access to in a Satellite location.

GET /v2/storage/satellite/getStorageConfigurationsByController

Request

Query Parameters

controller
Required*
string
The name or ID of the Satellite location to list storage configurations for. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Example request

curl -X GET "/global/v2/storage/satellite/getStorageConfigurationsByController?controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ListStorageConfigData[]

ListStorageConfigData is the response struct for the list storage configuration APIs i.e. getStorageConfigurations & getStorageConfigurationsByController

Status Code

201
OK. Storage configurations are listed.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
500
Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

[
  {
    "config-name": "my-cluster",
    "config-version": "1.28.5",
    "controller": "example-value",
    "created": "example-value",
    "is-revision-update-available": false,
    "latest-revision": "example-value",
    "location": "us-south",
    "revision": "example-value"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View the details of a Satellite storage template by name and version

GET /v2/storage/satellite/getStorageTemplate

Request

Query Parameters

name
Required*
string
The name of the storage template. To list the storage templates that you have access to, use the GET /v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.
version
Required*
string
The version of the storage template. To list the storage templates that you have access to, use the GET /v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.

Example request

curl -X GET "/global/v2/storage/satellite/getStorageTemplate?name=my-cluster&version=1.28.5"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

RegisteredStorageVersion

Registered storage version

Status Code

200
OK. Storage template details are returned.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
403
Forbidden. User is not allowed to use the specified version of the storage template. To list the storage templates that you have access to, use the GET /v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.
404
Not found. The specified storage template name or version could not be found. To list the storage templates that you have access to, use the GET /v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.
410
The specified version of the storage template is unsupported. To list the storage templates that you have access to, use the GET /v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "custom-parameters": [
    {
      "Validator": {},
      "category": "example-value",
      "default": "example-value",
      "description": "example-value",
      "displayname": "my-cluster",
      "max-length": 1,
      "min-length": 1,
      "mutable": "example-value",
      "supported-values": [
        "example-value"
      ],
      "templateKeyName": [
        "my-cluster"
      ]
    }
  ],
  "description": "example-value",
  "name": "my-cluster",
  "revision": "example-value",
  "status": "example-value",
  "storage-class-parameters": [
    {
      "Validator": {},
      "category": "example-value",
      "default": "example-value",
      "description": "example-value",
      "displayname": "my-cluster",
      "max-length": 1,
      "min-length": 1,
      "mutable": "example-value",
      "supported-values": [
        "example-value"
      ],
      "templateKeyName": [
        "my-cluster"
      ]
    }
  ],
  "storage-class-template": "example-value",
  "tags": [
    {
      "name": "my-cluster",
      "value": "example-value",
      "valueFrom": {
        "configMapKeyRef": {
          "key": "example-value",
          "name": "my-cluster",
          "optional": false
        },
        "fieldRef": {
          "apiVersion": "1.28.5",
          "fieldPath": "example-value"
        },
        "fileKeyRef": {
          "key": "example-value",
          "optional": false,
          "path": "example-value",
          "volumeName": "my-cluster"
        },
        "resourceFieldRef": {
          "containerName": "my-cluster",
          "divisor": {},
          "resource": "example-value"
        },
        "secretKeyRef": {
          "key": "example-value",
          "name": "my-cluster",
          "optional": false
        }
      }
    }
  ],
  "vendor-storage-class-parameters": [
    {}
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View the change log details of all Satellite storage templates or a specific Satellite storage template by name.

GET /v2/storage/satellite/getStorageTemplateChangelog

Request

Query Parameters

name
string
The name of the storage template that you want to get the change log for. To list the storage templates that you have access to, use the GET /v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls. To get change logs for all storage templates that you have access to, skip this parameter.

Example request

curl -X GET "/global/v2/storage/satellite/getStorageTemplateChangelog"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

RevisionLogForVersionResp

Revision log for version resp

Status Code

200
OK. Change log(s) of the storage template(s) is/are returned.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified storage template could not be found. To list the storage templates that you have access to, use the GET /v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.
500
Internal Server Error. Failed to fetch the changelog for the storage template. Note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "latest-revision": {
    "cves": "example-value",
    "fixes": [
      "example-value"
    ],
    "golang": "example-value",
    "new-features": [
      "example-value"
    ],
    "release-date": "2024-01-15T10:30:00Z",
    "revision": "example-value",
    "ubi": "example-value"
  },
  "previous-revision": {
    "cves": "example-value",
    "fixes": [
      "example-value"
    ],
    "golang": "example-value",
    "new-features": [
      "example-value"
    ],
    "release-date": "2024-01-15T10:30:00Z",
    "revision": "example-value",
    "ubi": "example-value"
  },
  "status": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List Satellite storage templates.

GET /v2/storage/satellite/getStorageTemplates

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET "/global/v2/storage/satellite/getStorageTemplates"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

RegisteredStorage[]

Registered storage

Status Code

200
OK. Storage templates are listed.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
500
Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "default-version": "1.28.5",
    "description": "example-value",
    "displayname": "my-cluster",
    "enabled": "example-value",
    "name": "my-cluster",
    "provider": "vpc-gen2",
    "versions": [
      {
        "custom-parameters": [
          {
            "Validator": {},
            "category": "example-value",
            "default": "example-value",
            "description": "example-value",
            "displayname": "my-cluster",
            "max-length": 1,
            "min-length": 1,
            "mutable": "example-value",
            "supported-values": [
              "example-value"
            ],
            "templateKeyName": [
              "my-cluster"
            ]
          }
        ],
        "description": "example-value",
        "name": "my-cluster",
        "revision": "example-value",
        "status": "example-value",
        "storage-class-parameters": [
          {
            "Validator": {},
            "category": "example-value",
            "default": "example-value",
            "description": "example-value",
            "displayname": "my-cluster",
            "max-length": 1,
            "min-length": 1,
            "mutable": "example-value",
            "supported-values": [
              "example-value"
            ],
            "templateKeyName": [
              "my-cluster"
            ]
          }
        ],
        "storage-class-template": "example-value",
        "tags": [
          {
            "name": "my-cluster",
            "value": "example-value",
            "valueFrom": {
              "configMapKeyRef": {
                "key": "example-value",
                "name": "my-cluster",
                "optional": false
              },
              "fieldRef": {
                "apiVersion": "1.28.5",
                "fieldPath": "example-value"
              },
              "fileKeyRef": {
                "key": "example-value",
                "optional": false,
                "path": "example-value",
                "volumeName": "my-cluster"
              },
              "resourceFieldRef": {
                "containerName": "my-cluster",
                "divisor": {},
                "resource": "example-value"
              },
              "secretKeyRef": {
                "key": "example-value",
                "name": "my-cluster",
                "optional": false
              }
            }
          }
        ],
        "vendor-storage-class-parameters": [
          {}
        ]
      }
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Remove an assignment with a given UUID.

DELETE /v2/storage/satellite/removeAssignment

Request

Query Parameters

uuid
Required*
string
ID of the assignment. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
controller
Required*
string
The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllers API or run ibmcloud sat location ls.

Example request

curl -X DELETE "/global/v2/storage/satellite/removeAssignment?uuid=example-id-123&controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

RemoveSubscriptionData

Remove subscription data

Status Code

200
OK. The assignment is removed.
400
Bad Request. Either the uuid is missing or the specified uuid is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified assignment could not be found. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "removeSubscription": {
    "success": false,
    "uuid": "example-id-123"
  }
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Delete a storage request on a cluster. If the cluster assignment status of a storage request is pending when this API is called, the request is deleted from the database. If the storage request is assigned to a cluster, the request is marked as deleted but not removed from the database. To check the cluster assignment status of a storage request, see the status field in the config section of the/v2/satellite/getDesiredStorageConfig API response.

DELETE /v2/storage/satellite/removeDesiredStorageConfig

Request

Query Parameters

request-id
Required*
string
The ID of the storage request. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API.
cluster
Required*
string
The ID of the cluster (cluster) on which the storage request is placed on. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API. To list the Satellite clusters you have access to, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

Example request

curl -X DELETE "/global/v2/storage/satellite/removeDesiredStorageConfig?request-id=example-id-123&cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ErrorResponse

ErrorResponse error response to end users

Status Code

201
OK. The storage configuration is removed.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "code": "example-value",
  "description": "example-value",
  "incidentID": "example-id-123",
  "recoveryCLI": "example-value",
  "terseDescription": "example-value",
  "type": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Remove a Satellite storage configuration with a given UUID. If you want to remove a Satellite storage configuration that is currently used in a Satellite storage assignment, set the removeAssignments query paramter flag to true. This flag when set to true removes the storage configuration as well as any associated assignments.

DELETE /v2/storage/satellite/removeStorageConfiguration

Request

Query Parameters

uuid
Required*
string
The UUID of the storage configuration. To list the storage configurations that you have access to, run ibmcloud sat storage config ls. To view the storage assignments associated with a given storage configuration and the storage configuration UUID, run ibmcloud sat config get --config=<storage-configuration-name>.
controller
Required*
string
The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllers API or run ibmcloud sat location ls.
remove_assignments
boolean
Specify true to remove the storage configuration along with the associated assignments. If unspecified, the default value is false.

Example request

curl -X DELETE "/global/v2/storage/satellite/removeStorageConfiguration?uuid=example-id-123&controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
OK. The storage configuration is removed.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Enable or disable automatic upgrades for an existing assignment(s) of a given storage configuration. To enable automatic upgrades, specify autoUpgrade=true. The default value is false. You can enable automatic upgrades for all assignments by specifying All=true. Alternatively, you can specify one or more individual assignment UUIDs to upgrade specific assignments.

PATCH /v2/storage/satellite/setAssignmentAutoupgrade

Request

Custom Headers

Content-Type
string
Allowable values: [application/json,application/merge-patch+json]

Request Body

Required*

SetAssignmentAutoupgradeInputData

The parameters must include:

Storage configuration name or ID (config).
Satellite Location (controller).
Set the autoUpgrade flag to true to enable assignments for automatic upgrades. If unspecified, it is assumed to be false.
Either set All to enable/disable automatic upgrades for all the assignments of the storage configuration or provide the UUIDs to enable/disable automatic upgrades for a set of assignments.

Example request

curl -X PATCH "/global/v2/storage/satellite/setAssignmentAutoupgrade"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "assignment": {
    "all": false,
    "uuids": [
      "example-id-123"
    ]
  },
  "autoUpgrade": false,
  "config": "example-value",
  "controller": "example-value"
}'
Copy to clipboard

Response

Response Body

SetAssignmentAutoupgradeInputData

Set assignment autoupgrade input data

Status Code

200
OK. The assignment(s) is/are enabled/disabled for automatic upgrades.
400
Bad Request. The request failed due to one of the following reasons:
1. The config name/uuid is missing or the specified config is invalid. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.
2. Both the parameters All and UUIDs are provided. Both cannot be provided at the same time.
3. No assignment(s) provided to enable/disable automatic upgrade. Neither of the parameters All and UUIDs are provided.
4. The assignment uuid provided in UUIDs parameter is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignmentsByConfig API or run ibmcloud sat storage assignment ls --config config.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The request failed due to one of the following reasons:
1. The specified config could not be found. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.
2. The specified assignment could not be found. To list the storage assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "assignment": {
    "all": false,
    "uuids": [
      "example-id-123"
    ]
  },
  "autoUpgrade": false,
  "config": "example-value",
  "controller": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a storage request for a cluster by providing the cluster ID and the required storage specifications. You can only create storage requests for the clusters you have access to.

POST /v2/storage/satellite/setDesiredStorageConfig

Request

Request Body

Required*

SetDesiredStorageConfigRequest

The configuration details for your Satellite storage request. Include the cluster ID (cluster) and the required storage specifications. To list available clusters in the Satellite location, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>. The following storage specifications are supported:

Required: a. Volume type. Specify one of file, block or object. b. Provider. Specify one of the supported providers of storage templates. For a list of supported providers or templates, see https://github.com/IBM/ibm-satellite-storage/blob/develop/config-templates/template_list.json. c. Maximum volume size and total capacity. Specify a positive integer value. Use K for kilobytes, M for megabytes, G for gigabytes, T for terabytes, or E for exabytes. Example: 100G.
Optional parameters. a. Offering type. Specify either sds for software-defined storage or non-sds. b. Volume encryption at rest. This is a boolean value. Specify true or false. c. Volume availability. This is a boolean value. Specify true or false. d. Volume expansion. This is a boolean value. Specify true or false. e. Volume snapshot. This is a boolean value. Specify true or false. f. Storage classes. Include a list of specific storage classes. Note that currently, requested storage classes are not strictly validated while provisioning storage.

See the following example payload for a storage request that specifies the cluster ID, volume type, offering type, provider, volume availability, volume expansion, volume snap shot, and storage classes: {"cluster": "c9l508rw0eo68tnbijrg","storage-requests": {"volume-type": "file","offering-type": "sds","provider": "redhat","volume-availability": "regional","volume-expansion": "true","volume-encryption-at-rest": "true","storageclasses": ["gold"],"volume-snapshot": "false","max-volume-size": "100G","total-capacity": "1T"}}

Example request

curl -X POST "/global/v2/storage/satellite/setDesiredStorageConfig"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "storage-requests": {
    "max-volume-size": "example-value",
    "offering-type": "example-value",
    "provider": "vpc-gen2",
    "storageclasses": [
      "example-value"
    ],
    "total-capacity": "example-value",
    "volume-availability": "example-value",
    "volume-encryption-at-rest": "example-value",
    "volume-expansion": "example-value"
  }
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

201
OK. The storage request is created.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Could not find the IBM Cloud Satellite cluster, volume type, available volume, or storage class. Verify the input parameters and try again. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Update the details of an assignment, such as the name of the assignment, the storage configuration version that it uses, or the cluster group(s) on which you want to apply the configuration. For updating an assignment to the latest available storage configuration version, set the updateConfigVersion flag to true. If unspecified, it is assumed to be false.

PATCH /v2/storage/satellite/updateAssignment

Request

Custom Headers

Content-Type
string
Allowable values: [application/json,application/merge-patch+json]

Request Body

Required*

UpdateSubscriptionInputData

The parameters must include the UUID of the assignment (uuid) along with at least one of the following parameters to be updated:

One or more cluster groups (groups) on which you want to apply the configuration. To list the cluster groups that you have access to, run ibmcloud sat group ls.
New name of the assignment (name).
set the updateConfigVersion flag to true for updating an assignment to the latest available storage configuration version. If unspecified, it is assumed to be false. To see if assignment upgrade is available, use the GET /v2/storage/satellite/getAssignment API and look for isAssignmentUpgradeAvailable field in response or run ibmcloud sat storage assignment get --assignment UUID and look for Assignment Upgrade Available field in response.

Example request

curl -X PATCH "/global/v2/storage/satellite/updateAssignment"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "groups": [
    "example-value"
  ],
  "name": "my-cluster",
  "updateConfigVersion": false,
  "uuid": "example-id-123"
}'
Copy to clipboard

Response

Response Body

UpdateSubscriptionData

Update subscription data

Status Code

200
OK. The assignment is updated.
400
Bad Request. The request failed due to one of the following reasons:
1. The uuid is missing or the specified uuid is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
2. There is no parameter in the request body to update. Input at least one parameter to be updated.
3. Storage assignment is already up to date with the latest available storage configuration version. Set the updateConfigVersion flag to false if you want to update at least assignment name or cluster group(s) on which you want to apply the configuration.
4. Updating an assignment, created for a cluster, to cluster group(s) is not supported. Run ibmcloud sat storage assignment rm to remove the assignment and create new assignment with cluster group(s).
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified assignment or cluster group(s) could not be found. To list the storage assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls. To list the Satellite cluster groups you have access to, run ibmcloud sat group ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "editSubscription": {
    "success": false,
    "uuid": "example-id-123"
  }
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Update an existing Satellite storage configuration. Note that you cannot update Satellite storage configurations that are currently used in a Satellite storage assignment.

POST /v2/storage/satellite/updateStorageConfiguration

Request

Request Body

Required*

StorageConfigUpdateInput

Include the storage template name (storage-template-name) and version (storage-template-version), the name of the existing storage configuration (config-name), the required parameters for the specified template (user-config-parameters, user-secret-parameters, and storage-class-parameters) and the Satellite location (location) where you want to use the storage configuration. To list the storage configurations that you have access to, run ibmcloud sat storage config ls. To view the storage assignments associated with a given storage configuration, run ibmcloud sat config get --config=<storage-configuration-name>. To list the storage templates and template versions, run ibmcloud sat storage template ls. To list the parameters for a given storage template and template version, run ibmcloud sat storage template get --name=<template-name> --version=<template-version>. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Example request

curl -X POST "/global/v2/storage/satellite/updateStorageConfiguration"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "config-name": "my-cluster",
  "controller": "example-value",
  "storage-class-parameters": [
    {}
  ],
  "update-assignments": false,
  "user-config-parameters": {},
  "user-secret-parameters": {}
}'
Copy to clipboard

Response

Response Body

ErrorResponse

ErrorResponse error response to end users

Status Code

201
OK. The storage configuration is updated.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "code": "example-value",
  "description": "example-value",
  "incidentID": "example-id-123",
  "recoveryCLI": "example-value",
  "terseDescription": "example-value",
  "type": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Update an existing Satellite storage configuration. If a Satellite storage configuration is already assigned, only the parameters that are marked as mutable can be updated.

POST /v2/storage/satellite/updateStorageConfigurationByController

Request

Request Body

Required*

StorageConfigUpdateInput

Include the name of the storage configuration (config-name) and the name or ID of the relevant Satellite location (controller). To apply the updated storage configuration to this storage configuration's existing assignments, set the update-assignments option to true. If left unspecified, the update-assignments option defaults to false.

If the storage configuration is assigned, only the configuration (user-config-parameters) and secret (user-secret-parameters) parameters that are marked as mutable can be updated. If the storage configuration is not assigned, all parameters can be updated.

If user-defined storage classes are supported, specify the required storage class parameters (storage-class-parameters) for the template that the storage configuration was created from. Note that any existing user-defined storage classes are overwritten by any storage classes specified in this API request's payload. For example, if you intend to define new storage classes and keep the existing storage classes, you must specify the parameters for both the existing and new user-defined storage classes.

To list the storage configurations that you have access to, run ibmcloud sat storage config ls. To view the storage assignments associated with a given storage configuration, run ibmcloud sat config get --config=<storage-configuration-name>. To list the parameters for a given storage template and template version, run ibmcloud sat storage template get --name=<template-name> --version=<template-version>. To list the parameters of existing storage classes, run ibmcloud sat storage config class ls --config=<storage-configuration-name> --show-params. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Example request

curl -X POST "/global/v2/storage/satellite/updateStorageConfigurationByController"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "config-name": "my-cluster",
  "controller": "example-value",
  "storage-class-parameters": [
    {}
  ],
  "update-assignments": false,
  "user-config-parameters": {},
  "user-secret-parameters": {}
}'
Copy to clipboard

Response

Response Body

ErrorResponse

ErrorResponse error response to end users

Status Code

201
OK. The storage configuration is updated.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "code": "example-value",
  "description": "example-value",
  "incidentID": "example-id-123",
  "recoveryCLI": "example-value",
  "terseDescription": "example-value",
  "type": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Update a Satellite storage configuration to use the latest template revision and optionally update assignment(s) based on the specified storage configuration. To check if a new template revision is available, view the 'getStorageConfiguration' API response for the storage configuration you want to update and compare your current template revision (revision) with the latest template revision (latest-revision). To update assignment(s) of the specified storage configuration, set the update assignments (updateAssignments) flag to true. By default, the flag is set to false if not specified and, assignment(s) are not updated as part of the template revision update operation.

PATCH /v2/storage/satellite/updateStorageConfigurationRevision

Request

Query Parameters

config
Required*
string
The name or UUID of the storage configuration. To list the storage configurations that you have access to, run ibmcloud sat storage config ls.
controller
Required*
string
The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllers API or run ibmcloud sat location ls.
update_assignments
boolean
Specify true or false to update assignment(s) of the specified storage configuration. The default value is false.

Example request

curl -X PATCH "/global/v2/storage/satellite/updateStorageConfigurationRevision?config=example-value&controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ErrorResponse

ErrorResponse error response to end users

Status Code

201
OK. Updated storage configuration template to latest revision.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
406
Storage configuration template is already up to date with the latest revision.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "code": "example-value",
  "description": "example-value",
  "incidentID": "example-id-123",
  "recoveryCLI": "example-value",
  "terseDescription": "example-value",
  "type": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Acknowledge the request to expand the storage capacity of an existing storage request.

PATCH /v2/storage/satellite/ackDesiredStorageConfigCapacity

Request

Custom Headers

Content-Type
string
Allowable values: [application/json,application/merge-patch+json]

Request Body

Required*

AckDesiredStorageCapacityRequest

Include the ID of the storage request (request-id), the cluster ID (cluster) and the name or ID of the Satellite location (controller) that the cluster is registered to. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

Example request

curl -X PATCH "/global/v2/storage/satellite/ackDesiredStorageConfigCapacity"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "controller": "example-value",
  "request-id": "example-id-123"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

201
OK. The storage request is created.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
The specified cluster or storage request could not be found. Check the input parameters and try again. Verify the input parameters and retry the request. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create an assignment to install the storage driver that is described by the version of the storage configuration on the cluster group(s). Then, apps that run in the clusters, part of cluster group(s), can use the storage.

POST /v2/storage/satellite/createAssignment

Request

Request Body

Required*

CreateSubscriptionInputData

Include following parameters to create an assignment:

Name of the assignment (name).
Storage configuration name or ID (config). To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.
The name or ID of the Satellite location (controller). To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllersAPI or run ibmcloud sat location ls.
One or more cluster groups (groups) on which you want to apply the configuration. Note that at least one cluster group is required. To list the cluster groups that you have access to, run ibmcloud sat group ls.
Enable or disable automatic upgrades for the assignment (autoUpgrade="true|false").

Example request

curl -X POST "/global/v2/storage/satellite/createAssignment"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "autoUpgrade": "example-value",
  "config": "example-value",
  "controller": "example-value",
  "groups": [
    "example-value"
  ],
  "name": "my-cluster"
}'
Copy to clipboard

Response

Response Body

CreateSubscriptionData

Create subscription data

Status Code

200
OK. An assignment using the storage configuration is created.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified config or cluster group(s) could not be found. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls. To list the Satellite cluster groups you have access to, run ibmcloud sat group ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "addSubscription": {
    "message": "example-value",
    "recoveryCLI": "example-value",
    "uuid": "example-id-123"
  }
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create an assignment to install the storage driver described by the version of the storage configuration on the Satellite cluster or service cluster. Then, apps that run in the cluster can use the storage.

POST /v2/storage/satellite/createAssignmentByCluster

Request

Request Body

Required*

CreateSubscriptionByClusterInputData

Include following parameters to create an assignment:

Name of the assignment (name).
Storage configuration name or ID (config). To list the storage configurations for a location that you have access to, use the GET /v2/storage/satellite/getStorageConfigurationsByController API or run ibmcloud sat storage config ls --location LOCATION.
ID of the Satellite cluster or service cluster that you want to apply the configuration to (cluster). To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
The name or ID of the Satellite location (controller). To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllersAPI or run ibmcloud sat location ls.
Enable or disable automatic upgrades for the assignment (autoUpgrade="true|false").

Example request

curl -X POST "/global/v2/storage/satellite/createAssignmentByCluster"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "autoUpgrade": "example-value",
  "cluster": "example-value",
  "config": "example-value",
  "controller": "example-value",
  "name": "my-cluster"
}'
Copy to clipboard

Response

Response Body

CreateSubscriptionData

Create subscription data

Status Code

200
OK. An assignment using the storage configuration is created.
400
Bad Request. The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified config or cluster or location could not be found. To list the storage configurations for the location that you have access to, use the GET /v2/storage/satellite/getStorageConfigurationsByController API or run ibmcloud sat storage config ls --location LOCATION. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, run ibmcloud sat location ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "addSubscription": {
    "message": "example-value",
    "recoveryCLI": "example-value",
    "uuid": "example-id-123"
  }
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a Satellite storage configuration based off the storage template, custom parameters, and location that you want to use. Then, assign the storage configuration to your clusters to install the storage driver so that the apps that run in the cluster can use the storage.

POST /v2/storage/satellite/createStorageConfiguration

Request

Request Body

Required*

StorageConfigCreateInput

Include a name for the storage configuration (config-name), the storage template name (storage-template-name), version (storage-template-version), required parameters as per the template specified (user-config-parameters, user-secret-parameters, and/or storage-class-parameters) and the Satellite location (location) where you want to use the storage configuration. To list the storage templates and template versions, run ibmcloud sat storage template ls. To list the parameters for a given storage template and template version, run ibmcloud sat storage template get --name=<template-name> --version=<template-version>. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Example request

curl -X POST "/global/v2/storage/satellite/createStorageConfiguration"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "config-name": "my-cluster",
  "controller": "example-value",
  "storage-class-parameters": [
    {}
  ],
  "storage-template-name": "my-cluster",
  "storage-template-version": "1.28.5",
  "user-config-parameters": {},
  "user-secret-parameters": {}
}'
Copy to clipboard

Response

Response Body

CreateConfigurationData

CreateConfigurationData - a single return struct

Status Code

201
OK. The storage configuration is created.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "addChannel": {
    "uuid": "example-id-123"
  }
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a Satellite storage configuration based on the storage template, custom parameters, and location that you want to use. After you create the configuration, install the storage driver by assigning the configuration to your clusters or cluster groups with the /v2/storage/satellite/createAssignmentByCluster or /v2/storage/satellite/createAssignment APIs.

POST /v2/storage/satellite/createStorageConfigurationByController

Request

Request Body

Required*

StorageConfigCreateInput

Include a name for the storage configuration (config-name); the storage template name (storage-template-name), version (storage-template-version) (optionally; if unspecified, the default storage template version is picked), required parameters as per the template specified (user-config-parameters, user-secret-parameters, and/or storage-class-parameters) and ID of the Satellite location (controller) where you want to use the storage configuration. The update-assignments payload parameter may be ignored.

Enter a storage configuration name that is less than 253 characters long and contains only lowercase letters, numbers, -, or ..

To list the storage templates and template versions that you have access to, run ibmcloud sat storage template ls. To list the parameters for a given storage template and template version, run ibmcloud sat storage template get --name=<template-name> --version=<template-version>. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Example request

curl -X POST "/global/v2/storage/satellite/createStorageConfigurationByController"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "config-name": "my-cluster",
  "controller": "example-value",
  "storage-class-parameters": [
    {}
  ],
  "storage-template-name": "my-cluster",
  "storage-template-version": "1.28.5",
  "user-config-parameters": {},
  "user-secret-parameters": {}
}'
Copy to clipboard

Response

Response Body

CreateConfigurationData

CreateConfigurationData - a single return struct

Status Code

201
OK. The storage configuration is created.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "addChannel": {
    "uuid": "example-id-123"
  }
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Expand the capacity of an existing storage request. Specify the storage request that you want to expand, the cluster it is associated with, and the desired total capacity. Note that capacity expansion is subject to acknowledgement from the Satellite location administator.

To check if the Satellite location administrator has acknowledged the capacity expansion for a given storage request, use the /v2/satellite/getDesiredStorageConfig API. After the capacity expansion is acknowledged, the status field in the backend section of the /v2/satellite/getDesiredStorageConfig API response is set to completed.

PATCH /v2/storage/satellite/expandDesiredStorageConfigCapacity

Request

Custom Headers

Content-Type
string
Allowable values: [application/json,application/merge-patch+json]

Request Body

Required*

ExpandDesiredStorageCapacityRequest

Include the ID of the storage request (request-id), the cluster ID (cluster) on which it is placed, and the desired total capacity (total-capacity). Specify the desired total capacity as a positive integer value in kilobytes (K), megabytes (M), gigabytes (G), terabytes (T) or exabytes (E). For example, specify 100G for 100 GB. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API. To list the Satellite clusters you have access to, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

Example request

curl -X PATCH "/global/v2/storage/satellite/expandDesiredStorageConfigCapacity"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "request-id": "example-id-123",
  "total-capacity": "example-value"
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

201
OK. The storage request is created.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
The specified cluster or storage request could not be found. Check the input parameters and try again. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List Satellite storage configurations that are assigned to a Satellite cluster or service cluster.

GET /v2/storage/satellite/getAssignedStorageConfigs

Request

Query Parameters

cluster
Required*
string
ID of the Satellite cluster or service cluster to list the assigned storage configurations for. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
controller
Required*
string
The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite.

Example request

curl -X GET "/global/v2/storage/satellite/getAssignedStorageConfigs?cluster=example-value&controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

AppliedStorageConfig[]

AppliedStorageConfig contains the details of an assigned storage config on a cluster A list of AppliedStorageConfig structs is the response for the GetAssignedStorageConfigs query

Status Code

200
OK. Assigned Satellite storage configurations are listed.
400
Bad Request. The request failed due to one of the following reasons:
1. The cluster is missing or the specified cluster is invalid.
2. The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified cluster or location could not be found. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, run ibmcloud sat location ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "assignment-uuid": "example-id-123",
    "config-attributes": {
      "offering-name": "my-cluster",
      "provider": "vpc-gen2",
      "storage-classes": [
        "example-value"
      ],
      "template-name": "my-cluster",
      "template-version": "1.28.5",
      "total-capacity": "example-value",
      "volume-availability": "example-value",
      "volume-encryption-at-rest": "example-value"
    },
    "config-name": "my-cluster",
    "config-uuid": "example-id-123",
    "rollout-status": {
      "error-count": 3,
      "success-count": 3
    }
  }
]
Copy to clipboard

Status 401

[
  {
    "code": "E0001",
    "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
    "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "recoveryCLI": "ibmcloud iam oauth-tokens",
    "terseDescription": "Unauthorized",
    "type": "Authentication"
  }
]
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View details of an assignment by the assignment UUID.

GET /v2/storage/satellite/getAssignment

Request

Query Parameters

uuid
Required*
string
The UUID of the assignment. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

Example request

curl -X GET "/global/v2/storage/satellite/getAssignment?uuid=example-id-123"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Subscription

Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59

Status Code

200
OK. Assignment details are returned.
400
Bad Request. Either the uuid is missing or the specified uuid is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified assignment could not be found. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "channelName": "my-cluster",
  "channelUuid": "example-id-123",
  "cluster": "example-value",
  "clusterName": "my-cluster",
  "configRevisionStatus": {
    "isRevisionUpdateAvailable": false,
    "latestRevision": "example-value",
    "revision": "example-value"
  },
  "created": "example-value",
  "groups": [
    "example-value"
  ],
  "isAssignmentUpgradeAvailable": false,
  "remoteResources": [
    {
      "cluster": {
        "clusterId": "example-id-123",
        "name": "my-cluster"
      },
      "lastModified": "example-value",
      "searchableData": {
        "kind": "example-value",
        "name": "my-cluster",
        "namespace": "my-cluster",
        "searchableExpression": "example-value"
      }
    }
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View details of an assignment by the assignment name.

GET /v2/storage/satellite/getAssignmentByName

Request

Query Parameters

name
Required*
string
The name of the assignment. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

Example request

curl -X GET "/global/v2/storage/satellite/getAssignmentByName?name=my-cluster"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Subscription

Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59

Status Code

200
OK. Assignment details successfully fetched.
400
Bad Request. Either the name is missing or the specified name is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified assignment could not be found. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "channelName": "my-cluster",
  "channelUuid": "example-id-123",
  "cluster": "example-value",
  "clusterName": "my-cluster",
  "configRevisionStatus": {
    "isRevisionUpdateAvailable": false,
    "latestRevision": "example-value",
    "revision": "example-value"
  },
  "created": "example-value",
  "groups": [
    "example-value"
  ],
  "isAssignmentUpgradeAvailable": false,
  "remoteResources": [
    {
      "cluster": {
        "clusterId": "example-id-123",
        "name": "my-cluster"
      },
      "lastModified": "example-value",
      "searchableData": {
        "kind": "example-value",
        "name": "my-cluster",
        "namespace": "my-cluster",
        "searchableExpression": "example-value"
      }
    }
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List storage assignments that you have access to in the IBM Cloud account. Returned details include the assignment name, UUID, and creation timestamp.

GET /v2/storage/satellite/getAssignments

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET "/global/v2/storage/satellite/getAssignments"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Subscription[]

Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59

Status Code

200
OK. Assignments are listed.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
500
Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "channelName": "my-cluster",
    "channelUuid": "example-id-123",
    "cluster": "example-value",
    "clusterName": "my-cluster",
    "configRevisionStatus": {
      "isRevisionUpdateAvailable": false,
      "latestRevision": "example-value",
      "revision": "example-value"
    },
    "created": "example-value",
    "groups": [
      "example-value"
    ],
    "isAssignmentUpgradeAvailable": false,
    "remoteResources": [
      {
        "cluster": {
          "clusterId": "example-id-123",
          "name": "my-cluster"
        },
        "lastModified": "example-value",
        "searchableData": {
          "kind": "example-value",
          "name": "my-cluster",
          "namespace": "my-cluster",
          "searchableExpression": "example-value"
        }
      }
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List storage assignments created for a Satellite cluster or service cluster. Returned details include the assignment name, UUID, and creation timestamp.

GET /v2/storage/satellite/getAssignmentsByClusterID

Request

Query Parameters

cluster
Required*
string
ID of the Satellite cluster or service cluster to list the storage assignments for. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
controller
Required*
string
The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite.

Example request

curl -X GET "/global/v2/storage/satellite/getAssignmentsByClusterID?cluster=example-value&controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Subscription[]

Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59

Status Code

200
OK. Assignments are listed.
400
Bad Request. The request failed due to one of the following reasons:
1. The cluster is missing or the specified cluster is invalid. 2.The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified cluster or location could not be found. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, run ibmcloud sat location ls.
500
Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "channelName": "my-cluster",
    "channelUuid": "example-id-123",
    "cluster": "example-value",
    "clusterName": "my-cluster",
    "configRevisionStatus": {
      "isRevisionUpdateAvailable": false,
      "latestRevision": "example-value",
      "revision": "example-value"
    },
    "created": "example-value",
    "groups": [
      "example-value"
    ],
    "isAssignmentUpgradeAvailable": false,
    "remoteResources": [
      {
        "cluster": {
          "clusterId": "example-id-123",
          "name": "my-cluster"
        },
        "lastModified": "example-value",
        "searchableData": {
          "kind": "example-value",
          "name": "my-cluster",
          "namespace": "my-cluster",
          "searchableExpression": "example-value"
        }
      }
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List storage assignments by configuration name or UUID. Returned details include the assignment name, UUID, and creation timestamp.

GET /v2/storage/satellite/getAssignmentsByConfig

Request

Query Parameters

config
Required*
string
The name or ID of the Satellite storage configuration. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.

Example request

curl -X GET "/global/v2/storage/satellite/getAssignmentsByConfig?config=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Subscription[]

Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59

Status Code

200
OK. Assignments are listed.
400
Bad Request. Either the config is missing or the specified config is invalid. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified config could not be found. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.
500
Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "channelName": "my-cluster",
    "channelUuid": "example-id-123",
    "cluster": "example-value",
    "clusterName": "my-cluster",
    "configRevisionStatus": {
      "isRevisionUpdateAvailable": false,
      "latestRevision": "example-value",
      "revision": "example-value"
    },
    "created": "example-value",
    "groups": [
      "example-value"
    ],
    "isAssignmentUpgradeAvailable": false,
    "remoteResources": [
      {
        "cluster": {
          "clusterId": "example-id-123",
          "name": "my-cluster"
        },
        "lastModified": "example-value",
        "searchableData": {
          "kind": "example-value",
          "name": "my-cluster",
          "namespace": "my-cluster",
          "searchableExpression": "example-value"
        }
      }
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List storage assignments that you have access to in a Satellite location. Returned details include the assignment name, UUID, and creation timestamp.

GET /v2/storage/satellite/getAssignmentsByController

Request

Query Parameters

controller
Required*
string
The name or ID of the Satellite location to list assignments for. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Example request

curl -X GET "/global/v2/storage/satellite/getAssignmentsByController?controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

Subscription[]

Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59

Status Code

200
OK. Assignments are listed.
400
Bad Request. The controller is missing. To list the Satellite locations that you have access to, run ibmcloud sat location ls.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified location could not be found. To list the Satellite locations that you have access to, run ibmcloud sat location ls.
500
Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "channelName": "my-cluster",
    "channelUuid": "example-id-123",
    "cluster": "example-value",
    "clusterName": "my-cluster",
    "configRevisionStatus": {
      "isRevisionUpdateAvailable": false,
      "latestRevision": "example-value",
      "revision": "example-value"
    },
    "created": "example-value",
    "groups": [
      "example-value"
    ],
    "isAssignmentUpgradeAvailable": false,
    "remoteResources": [
      {
        "cluster": {
          "clusterId": "example-id-123",
          "name": "my-cluster"
        },
        "lastModified": "example-value",
        "searchableData": {
          "kind": "example-value",
          "name": "my-cluster",
          "namespace": "my-cluster",
          "searchableExpression": "example-value"
        }
      }
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List and filter the available storage classes from assigned Satellite storage configurations on a Satellite or service cluster. By default, only the available storage classes from Software Defined Storage (SDS) template based Satellite storage configurations are returned. To view all available storage classes, set the onlyShowSDS query paramter flag to false. Optionally, filter the available storage classes based on volume type using the volumeType query parameter.

Note that, if a volume type is specified, the most preferable storage class from each of the assigned storage configurations of specified volume type is returned. For user-defined storage classes, the preference is set while creating the storage configuration. To view the preference for all the storage classes of an assigned storage configuration, run ibmcloud sat storage config class ls --config CONFIG --show-params and look for the parameter storage-class-preference.

GET /v2/storage/satellite/getAvailableStorageClasses

Request

Query Parameters

cluster
Required*
string
The ID of the Satellite cluster or service cluster for which available storage classes from assigned Satellite storage configurations are to be listed. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
controller
Required*
string
The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite.
volume_type
string
Filter the available storage classes by volume type. The supported volume types are file, block and object. If unspecified, available storage classes of all volume types are returned.
only_show_sds
boolean
Specify true or false to view only the available storage classes from software-defined storage (SDS) storage configurations. If unspecified, the default value is true.

Example request

curl -X GET "/global/v2/storage/satellite/getAvailableStorageClasses?cluster=example-value&controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

AvailableStorageClasses

AvailableStorageClasses contains a list of storage class names It is the response for GetAvailableStorageClasses query

Status Code

200
OK. Available storage classes are listed.
400
Bad Request. The request failed due to one of the following reasons:
1. The cluster is missing or the specified cluster is invalid. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
2. The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
3. The specified value is an invalid value for parameter volumeType. Supported values for volumeType parameter are: file, block, object.
4. The specified value is an invalid value for parameter onlyShowSDS. Supported values for onlyShowSDS parameter are: true, false.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified cluster or location could not be found. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, run ibmcloud sat location ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "storage-classes": [
    "example-value"
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the storage requests for a cluster in a Satellite location.

GET /v2/storage/satellite/getDesiredStorageConfig

Request

Query Parameters

cluster
Required*
string
The ID of the cluster where you want to list storage requests. To list the Satellite clusters you have access to, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>. The response body for each storage request contains the request specifications and the following fields:
1. Theassignment field. This field is initially empty when the storage request is created. When the location administrator assigns a storage configuration to the cluster that matches the storage request, this field is populated with the UUID of the assignment.
2. A status field in the config section that indicates the status of storage provisioning or assignment. If a storage assignment is created but no action is taken on it, the status is set to pending. If a storage configuration has been assigned to the cluster, the status is set to assigned. If the storage request is deleted, the status is set to deleted.
3. A status field in the backend section. This field indicates whether the location administrator has acknowledged the request to increase storage capacity. If the storage capacity expansion request is not acknowledged, the status is set to pending. If the request is acknowledged by the location administrator, the status is set to completed.
controller
Required*
string
The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

Example request

curl -X GET "/global/v2/storage/satellite/getDesiredStorageConfig?cluster=example-value&controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

GetDesiredStorageConfigResponse[]

GetDesiredStorageConfigResponse is the respose body for getDesiredStorageConfig API

Status Code

201
OK. Storage requests are listed.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Could not list the IBM Cloud Satellite storage requests. Verify the input parameters and retry the request. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.
500
Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

[
  {
    "cluster": "example-value",
    "storage-requests": [
      {
        "assignment": "example-value",
        "backend": {
          "attribute": {
            "max-volume-size": "example-value",
            "total-capacity": "example-value"
          },
          "status": "example-value"
        },
        "config": {
          "attribute": {
            "offering-type": "example-value",
            "provider": "vpc-gen2",
            "storageclasses": [
              "example-value"
            ],
            "supported-ocp-versions": "1.28.5",
            "volume-availability": "example-value",
            "volume-encryption-at-rest": "example-value",
            "volume-expansion": "example-value",
            "volume-snapshot": "example-value"
          },
          "status": "example-value"
        },
        "request-id": "example-id-123"
      }
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View the details of a Satellite storage configuration.

GET /v2/storage/satellite/getStorageConfiguration

Request

Query Parameters

name
Required*
string
The name of the storage configuration. To list the storage configurations that you have access to, run ibmcloud sat storage config ls.
include-assignments
boolean
Specify true to include details of assignment(s) of the specified storage configuration. The default value is false.

Example request

curl -X GET "/global/v2/storage/satellite/getStorageConfiguration?name=my-cluster"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

StorageConfig

Storage config

Status Code

201
OK. Storage configuration details are returned.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "config-name": "my-cluster",
  "config-version": "1.28.5",
  "controller": "example-value",
  "created": "example-value",
  "is-revision-update-available": false,
  "is-user-secret-parameters-set": {},
  "latest-revision": "example-value",
  "location": "us-south",
  "storage-class-parameters": [
    {}
  ],
  "subscriptions": [
    {
      "cluster": "example-value",
      "clusterName": "my-cluster",
      "created": "example-value",
      "groups": [
        "example-value"
      ],
      "name": "my-cluster",
      "rolloutStatus": {
        "errorCount": 3,
        "successCount": 3
      },
      "subscriptionType": "example-value",
      "tags": [
        "example-value"
      ]
    }
  ],
  "tags": [
    "example-value"
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the Satellite storage configurations that you have access to in a Satellite location or in the IBM Cloud account.

GET /v2/storage/satellite/getStorageConfigurations

Request

Query Parameters

location
string
The name or ID of the Satellite location to list storage configurations for. If no location is specified, all storage configurations that you have access to in the IBM Cloud account are returned. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Example request

curl -X GET "/global/v2/storage/satellite/getStorageConfigurations"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ListStorageConfigData[]

ListStorageConfigData is the response struct for the list storage configuration APIs i.e. getStorageConfigurations & getStorageConfigurationsByController

Status Code

201
OK. Storage configurations are listed.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
500
Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

[
  {
    "config-name": "my-cluster",
    "config-version": "1.28.5",
    "controller": "example-value",
    "created": "example-value",
    "is-revision-update-available": false,
    "latest-revision": "example-value",
    "location": "us-south",
    "revision": "example-value"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List the Satellite storage configurations that you have access to in a Satellite location.

GET /v2/storage/satellite/getStorageConfigurationsByController

Request

Query Parameters

controller
Required*
string
The name or ID of the Satellite location to list storage configurations for. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Example request

curl -X GET "/global/v2/storage/satellite/getStorageConfigurationsByController?controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ListStorageConfigData[]

ListStorageConfigData is the response struct for the list storage configuration APIs i.e. getStorageConfigurations & getStorageConfigurationsByController

Status Code

201
OK. Storage configurations are listed.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
500
Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

[
  {
    "config-name": "my-cluster",
    "config-version": "1.28.5",
    "controller": "example-value",
    "created": "example-value",
    "is-revision-update-available": false,
    "latest-revision": "example-value",
    "location": "us-south",
    "revision": "example-value"
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View the details of a Satellite storage template by name and version

GET /v2/storage/satellite/getStorageTemplate

Request

Query Parameters

name
Required*
string
The name of the storage template. To list the storage templates that you have access to, use the GET /v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.
version
Required*
string
The version of the storage template. To list the storage templates that you have access to, use the GET /v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.

Example request

curl -X GET "/global/v2/storage/satellite/getStorageTemplate?name=my-cluster&version=1.28.5"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

RegisteredStorageVersion

Registered storage version

Status Code

200
OK. Storage template details are returned.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
403
Forbidden. User is not allowed to use the specified version of the storage template. To list the storage templates that you have access to, use the GET /v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.
404
Not found. The specified storage template name or version could not be found. To list the storage templates that you have access to, use the GET /v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.
410
The specified version of the storage template is unsupported. To list the storage templates that you have access to, use the GET /v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "custom-parameters": [
    {
      "Validator": {},
      "category": "example-value",
      "default": "example-value",
      "description": "example-value",
      "displayname": "my-cluster",
      "max-length": 1,
      "min-length": 1,
      "mutable": "example-value",
      "supported-values": [
        "example-value"
      ],
      "templateKeyName": [
        "my-cluster"
      ]
    }
  ],
  "description": "example-value",
  "name": "my-cluster",
  "revision": "example-value",
  "status": "example-value",
  "storage-class-parameters": [
    {
      "Validator": {},
      "category": "example-value",
      "default": "example-value",
      "description": "example-value",
      "displayname": "my-cluster",
      "max-length": 1,
      "min-length": 1,
      "mutable": "example-value",
      "supported-values": [
        "example-value"
      ],
      "templateKeyName": [
        "my-cluster"
      ]
    }
  ],
  "storage-class-template": "example-value",
  "tags": [
    {
      "name": "my-cluster",
      "value": "example-value",
      "valueFrom": {
        "configMapKeyRef": {
          "key": "example-value",
          "name": "my-cluster",
          "optional": false
        },
        "fieldRef": {
          "apiVersion": "1.28.5",
          "fieldPath": "example-value"
        },
        "fileKeyRef": {
          "key": "example-value",
          "optional": false,
          "path": "example-value",
          "volumeName": "my-cluster"
        },
        "resourceFieldRef": {
          "containerName": "my-cluster",
          "divisor": {},
          "resource": "example-value"
        },
        "secretKeyRef": {
          "key": "example-value",
          "name": "my-cluster",
          "optional": false
        }
      }
    }
  ],
  "vendor-storage-class-parameters": [
    {}
  ]
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

View the change log details of all Satellite storage templates or a specific Satellite storage template by name.

GET /v2/storage/satellite/getStorageTemplateChangelog

Request

Query Parameters

name
string
The name of the storage template that you want to get the change log for. To list the storage templates that you have access to, use the GET /v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls. To get change logs for all storage templates that you have access to, skip this parameter.

Example request

curl -X GET "/global/v2/storage/satellite/getStorageTemplateChangelog"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

RevisionLogForVersionResp

Revision log for version resp

Status Code

200
OK. Change log(s) of the storage template(s) is/are returned.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified storage template could not be found. To list the storage templates that you have access to, use the GET /v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.
500
Internal Server Error. Failed to fetch the changelog for the storage template. Note the incident ID and contact IBM Cloud support.

Example responses

Status 200

{
  "latest-revision": {
    "cves": "example-value",
    "fixes": [
      "example-value"
    ],
    "golang": "example-value",
    "new-features": [
      "example-value"
    ],
    "release-date": "2024-01-15T10:30:00Z",
    "revision": "example-value",
    "ubi": "example-value"
  },
  "previous-revision": {
    "cves": "example-value",
    "fixes": [
      "example-value"
    ],
    "golang": "example-value",
    "new-features": [
      "example-value"
    ],
    "release-date": "2024-01-15T10:30:00Z",
    "revision": "example-value",
    "ubi": "example-value"
  },
  "status": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

List Satellite storage templates.

GET /v2/storage/satellite/getStorageTemplates

Request

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET "/global/v2/storage/satellite/getStorageTemplates"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

RegisteredStorage[]

Registered storage

Status Code

200
OK. Storage templates are listed.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
500
Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

[
  {
    "default-version": "1.28.5",
    "description": "example-value",
    "displayname": "my-cluster",
    "enabled": "example-value",
    "name": "my-cluster",
    "provider": "vpc-gen2",
    "versions": [
      {
        "custom-parameters": [
          {
            "Validator": {},
            "category": "example-value",
            "default": "example-value",
            "description": "example-value",
            "displayname": "my-cluster",
            "max-length": 1,
            "min-length": 1,
            "mutable": "example-value",
            "supported-values": [
              "example-value"
            ],
            "templateKeyName": [
              "my-cluster"
            ]
          }
        ],
        "description": "example-value",
        "name": "my-cluster",
        "revision": "example-value",
        "status": "example-value",
        "storage-class-parameters": [
          {
            "Validator": {},
            "category": "example-value",
            "default": "example-value",
            "description": "example-value",
            "displayname": "my-cluster",
            "max-length": 1,
            "min-length": 1,
            "mutable": "example-value",
            "supported-values": [
              "example-value"
            ],
            "templateKeyName": [
              "my-cluster"
            ]
          }
        ],
        "storage-class-template": "example-value",
        "tags": [
          {
            "name": "my-cluster",
            "value": "example-value",
            "valueFrom": {
              "configMapKeyRef": {
                "key": "example-value",
                "name": "my-cluster",
                "optional": false
              },
              "fieldRef": {
                "apiVersion": "1.28.5",
                "fieldPath": "example-value"
              },
              "fileKeyRef": {
                "key": "example-value",
                "optional": false,
                "path": "example-value",
                "volumeName": "my-cluster"
              },
              "resourceFieldRef": {
                "containerName": "my-cluster",
                "divisor": {},
                "resource": "example-value"
              },
              "secretKeyRef": {
                "key": "example-value",
                "name": "my-cluster",
                "optional": false
              }
            }
          }
        ],
        "vendor-storage-class-parameters": [
          {}
        ]
      }
    ]
  }
]
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Remove an assignment with a given UUID.

DELETE /v2/storage/satellite/removeAssignment

Request

Query Parameters

uuid
Required*
string
ID of the assignment. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
controller
Required*
string
The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllers API or run ibmcloud sat location ls.

Example request

curl -X DELETE "/global/v2/storage/satellite/removeAssignment?uuid=example-id-123&controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

RemoveSubscriptionData

Remove subscription data

Status Code

200
OK. The assignment is removed.
400
Bad Request. Either the uuid is missing or the specified uuid is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified assignment could not be found. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "removeSubscription": {
    "success": false,
    "uuid": "example-id-123"
  }
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Delete a storage request on a cluster. If the cluster assignment status of a storage request is pending when this API is called, the request is deleted from the database. If the storage request is assigned to a cluster, the request is marked as deleted but not removed from the database. To check the cluster assignment status of a storage request, see the status field in the config section of the/v2/satellite/getDesiredStorageConfig API response.

DELETE /v2/storage/satellite/removeDesiredStorageConfig

Request

Query Parameters

request-id
Required*
string
The ID of the storage request. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API.
cluster
Required*
string
The ID of the cluster (cluster) on which the storage request is placed on. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API. To list the Satellite clusters you have access to, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

Example request

curl -X DELETE "/global/v2/storage/satellite/removeDesiredStorageConfig?request-id=example-id-123&cluster=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ErrorResponse

ErrorResponse error response to end users

Status Code

201
OK. The storage configuration is removed.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "code": "example-value",
  "description": "example-value",
  "incidentID": "example-id-123",
  "recoveryCLI": "example-value",
  "terseDescription": "example-value",
  "type": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Remove a Satellite storage configuration with a given UUID. If you want to remove a Satellite storage configuration that is currently used in a Satellite storage assignment, set the removeAssignments query paramter flag to true. This flag when set to true removes the storage configuration as well as any associated assignments.

DELETE /v2/storage/satellite/removeStorageConfiguration

Request

Query Parameters

uuid
Required*
string
The UUID of the storage configuration. To list the storage configurations that you have access to, run ibmcloud sat storage config ls. To view the storage assignments associated with a given storage configuration and the storage configuration UUID, run ibmcloud sat config get --config=<storage-configuration-name>.
controller
Required*
string
The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllers API or run ibmcloud sat location ls.
remove_assignments
boolean
Specify true to remove the storage configuration along with the associated assignments. If unspecified, the default value is false.

Example request

curl -X DELETE "/global/v2/storage/satellite/removeStorageConfiguration?uuid=example-id-123&controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

200
OK. The storage configuration is removed.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Enable or disable automatic upgrades for an existing assignment(s) of a given storage configuration. To enable automatic upgrades, specify autoUpgrade=true. The default value is false. You can enable automatic upgrades for all assignments by specifying All=true. Alternatively, you can specify one or more individual assignment UUIDs to upgrade specific assignments.

PATCH /v2/storage/satellite/setAssignmentAutoupgrade

Request

Custom Headers

Content-Type
string
Allowable values: [application/json,application/merge-patch+json]

Request Body

Required*

SetAssignmentAutoupgradeInputData

The parameters must include:

Storage configuration name or ID (config).
Satellite Location (controller).
Set the autoUpgrade flag to true to enable assignments for automatic upgrades. If unspecified, it is assumed to be false.
Either set All to enable/disable automatic upgrades for all the assignments of the storage configuration or provide the UUIDs to enable/disable automatic upgrades for a set of assignments.

Example request

curl -X PATCH "/global/v2/storage/satellite/setAssignmentAutoupgrade"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "assignment": {
    "all": false,
    "uuids": [
      "example-id-123"
    ]
  },
  "autoUpgrade": false,
  "config": "example-value",
  "controller": "example-value"
}'
Copy to clipboard

Response

Response Body

SetAssignmentAutoupgradeInputData

Set assignment autoupgrade input data

Status Code

200
OK. The assignment(s) is/are enabled/disabled for automatic upgrades.
400
Bad Request. The request failed due to one of the following reasons:
1. The config name/uuid is missing or the specified config is invalid. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.
2. Both the parameters All and UUIDs are provided. Both cannot be provided at the same time.
3. No assignment(s) provided to enable/disable automatic upgrade. Neither of the parameters All and UUIDs are provided.
4. The assignment uuid provided in UUIDs parameter is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignmentsByConfig API or run ibmcloud sat storage assignment ls --config config.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The request failed due to one of the following reasons:
1. The specified config could not be found. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.
2. The specified assignment could not be found. To list the storage assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "assignment": {
    "all": false,
    "uuids": [
      "example-id-123"
    ]
  },
  "autoUpgrade": false,
  "config": "example-value",
  "controller": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Create a storage request for a cluster by providing the cluster ID and the required storage specifications. You can only create storage requests for the clusters you have access to.

POST /v2/storage/satellite/setDesiredStorageConfig

Request

Request Body

Required*

SetDesiredStorageConfigRequest

The configuration details for your Satellite storage request. Include the cluster ID (cluster) and the required storage specifications. To list available clusters in the Satellite location, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>. The following storage specifications are supported:

Required: a. Volume type. Specify one of file, block or object. b. Provider. Specify one of the supported providers of storage templates. For a list of supported providers or templates, see https://github.com/IBM/ibm-satellite-storage/blob/develop/config-templates/template_list.json. c. Maximum volume size and total capacity. Specify a positive integer value. Use K for kilobytes, M for megabytes, G for gigabytes, T for terabytes, or E for exabytes. Example: 100G.
Optional parameters. a. Offering type. Specify either sds for software-defined storage or non-sds. b. Volume encryption at rest. This is a boolean value. Specify true or false. c. Volume availability. This is a boolean value. Specify true or false. d. Volume expansion. This is a boolean value. Specify true or false. e. Volume snapshot. This is a boolean value. Specify true or false. f. Storage classes. Include a list of specific storage classes. Note that currently, requested storage classes are not strictly validated while provisioning storage.

See the following example payload for a storage request that specifies the cluster ID, volume type, offering type, provider, volume availability, volume expansion, volume snap shot, and storage classes: {"cluster": "c9l508rw0eo68tnbijrg","storage-requests": {"volume-type": "file","offering-type": "sds","provider": "redhat","volume-availability": "regional","volume-expansion": "true","volume-encryption-at-rest": "true","storageclasses": ["gold"],"volume-snapshot": "false","max-volume-size": "100G","total-capacity": "1T"}}

Example request

curl -X POST "/global/v2/storage/satellite/setDesiredStorageConfig"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "cluster": "example-value",
  "storage-requests": {
    "max-volume-size": "example-value",
    "offering-type": "example-value",
    "provider": "vpc-gen2",
    "storageclasses": [
      "example-value"
    ],
    "total-capacity": "example-value",
    "volume-availability": "example-value",
    "volume-encryption-at-rest": "example-value",
    "volume-expansion": "example-value"
  }
}'
Copy to clipboard

Response

Response Body

object

Successful response.

Status Code

201
OK. The storage request is created.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Could not find the IBM Cloud Satellite cluster, volume type, available volume, or storage class. Verify the input parameters and try again. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

{}

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Update the details of an assignment, such as the name of the assignment, the storage configuration version that it uses, or the cluster group(s) on which you want to apply the configuration. For updating an assignment to the latest available storage configuration version, set the updateConfigVersion flag to true. If unspecified, it is assumed to be false.

PATCH /v2/storage/satellite/updateAssignment

Request

Custom Headers

Content-Type
string
Allowable values: [application/json,application/merge-patch+json]

Request Body

Required*

UpdateSubscriptionInputData

The parameters must include the UUID of the assignment (uuid) along with at least one of the following parameters to be updated:

One or more cluster groups (groups) on which you want to apply the configuration. To list the cluster groups that you have access to, run ibmcloud sat group ls.
New name of the assignment (name).
set the updateConfigVersion flag to true for updating an assignment to the latest available storage configuration version. If unspecified, it is assumed to be false. To see if assignment upgrade is available, use the GET /v2/storage/satellite/getAssignment API and look for isAssignmentUpgradeAvailable field in response or run ibmcloud sat storage assignment get --assignment UUID and look for Assignment Upgrade Available field in response.

Example request

curl -X PATCH "/global/v2/storage/satellite/updateAssignment"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "groups": [
    "example-value"
  ],
  "name": "my-cluster",
  "updateConfigVersion": false,
  "uuid": "example-id-123"
}'
Copy to clipboard

Response

Response Body

UpdateSubscriptionData

Update subscription data

Status Code

200
OK. The assignment is updated.
400
Bad Request. The request failed due to one of the following reasons:
1. The uuid is missing or the specified uuid is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
2. There is no parameter in the request body to update. Input at least one parameter to be updated.
3. Storage assignment is already up to date with the latest available storage configuration version. Set the updateConfigVersion flag to false if you want to update at least assignment name or cluster group(s) on which you want to apply the configuration.
4. Updating an assignment, created for a cluster, to cluster group(s) is not supported. Run ibmcloud sat storage assignment rm to remove the assignment and create new assignment with cluster group(s).
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found. The specified assignment or cluster group(s) could not be found. To list the storage assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls. To list the Satellite cluster groups you have access to, run ibmcloud sat group ls.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 200

{
  "editSubscription": {
    "success": false,
    "uuid": "example-id-123"
  }
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Update an existing Satellite storage configuration. Note that you cannot update Satellite storage configurations that are currently used in a Satellite storage assignment.

POST /v2/storage/satellite/updateStorageConfiguration

Request

Request Body

Required*

StorageConfigUpdateInput

Include the storage template name (storage-template-name) and version (storage-template-version), the name of the existing storage configuration (config-name), the required parameters for the specified template (user-config-parameters, user-secret-parameters, and storage-class-parameters) and the Satellite location (location) where you want to use the storage configuration. To list the storage configurations that you have access to, run ibmcloud sat storage config ls. To view the storage assignments associated with a given storage configuration, run ibmcloud sat config get --config=<storage-configuration-name>. To list the storage templates and template versions, run ibmcloud sat storage template ls. To list the parameters for a given storage template and template version, run ibmcloud sat storage template get --name=<template-name> --version=<template-version>. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Example request

curl -X POST "/global/v2/storage/satellite/updateStorageConfiguration"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "config-name": "my-cluster",
  "controller": "example-value",
  "storage-class-parameters": [
    {}
  ],
  "update-assignments": false,
  "user-config-parameters": {},
  "user-secret-parameters": {}
}'
Copy to clipboard

Response

Response Body

ErrorResponse

ErrorResponse error response to end users

Status Code

201
OK. The storage configuration is updated.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "code": "example-value",
  "description": "example-value",
  "incidentID": "example-id-123",
  "recoveryCLI": "example-value",
  "terseDescription": "example-value",
  "type": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Update an existing Satellite storage configuration. If a Satellite storage configuration is already assigned, only the parameters that are marked as mutable can be updated.

POST /v2/storage/satellite/updateStorageConfigurationByController

Request

Request Body

Required*

StorageConfigUpdateInput

Include the name of the storage configuration (config-name) and the name or ID of the relevant Satellite location (controller). To apply the updated storage configuration to this storage configuration's existing assignments, set the update-assignments option to true. If left unspecified, the update-assignments option defaults to false.

If the storage configuration is assigned, only the configuration (user-config-parameters) and secret (user-secret-parameters) parameters that are marked as mutable can be updated. If the storage configuration is not assigned, all parameters can be updated.

If user-defined storage classes are supported, specify the required storage class parameters (storage-class-parameters) for the template that the storage configuration was created from. Note that any existing user-defined storage classes are overwritten by any storage classes specified in this API request's payload. For example, if you intend to define new storage classes and keep the existing storage classes, you must specify the parameters for both the existing and new user-defined storage classes.

To list the storage configurations that you have access to, run ibmcloud sat storage config ls. To view the storage assignments associated with a given storage configuration, run ibmcloud sat config get --config=<storage-configuration-name>. To list the parameters for a given storage template and template version, run ibmcloud sat storage template get --name=<template-name> --version=<template-version>. To list the parameters of existing storage classes, run ibmcloud sat storage config class ls --config=<storage-configuration-name> --show-params. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Example request

curl -X POST "/global/v2/storage/satellite/updateStorageConfigurationByController"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"   -H "Content-Type: application/json"   -d '{
  "config-name": "my-cluster",
  "controller": "example-value",
  "storage-class-parameters": [
    {}
  ],
  "update-assignments": false,
  "user-config-parameters": {},
  "user-secret-parameters": {}
}'
Copy to clipboard

Response

Response Body

ErrorResponse

ErrorResponse error response to end users

Status Code

201
OK. The storage configuration is updated.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "code": "example-value",
  "description": "example-value",
  "incidentID": "example-id-123",
  "recoveryCLI": "example-value",
  "terseDescription": "example-value",
  "type": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

Update a Satellite storage configuration to use the latest template revision and optionally update assignment(s) based on the specified storage configuration. To check if a new template revision is available, view the 'getStorageConfiguration' API response for the storage configuration you want to update and compare your current template revision (revision) with the latest template revision (latest-revision). To update assignment(s) of the specified storage configuration, set the update assignments (updateAssignments) flag to true. By default, the flag is set to false if not specified and, assignment(s) are not updated as part of the template revision update operation.

PATCH /v2/storage/satellite/updateStorageConfigurationRevision

Request

Query Parameters

config
Required*
string
The name or UUID of the storage configuration. To list the storage configurations that you have access to, run ibmcloud sat storage config ls.
controller
Required*
string
The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllers API or run ibmcloud sat location ls.
update_assignments
boolean
Specify true or false to update assignment(s) of the specified storage configuration. The default value is false.

Example request

curl -X PATCH "/global/v2/storage/satellite/updateStorageConfigurationRevision?config=example-value&controller=example-value"   -H "Authorization: Bearer $IAM_TOKEN"   -H "X-Region: us-south"
Copy to clipboard

Response

Response Body

ErrorResponse

ErrorResponse error response to end users

Status Code

201
OK. Updated storage configuration template to latest revision.
401
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.
404
Not found.
406
Storage configuration template is already up to date with the latest revision.
500
Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses

Status 201

{
  "code": "example-value",
  "description": "example-value",
  "incidentID": "example-id-123",
  "recoveryCLI": "example-value",
  "terseDescription": "example-value",
  "type": "example-value"
}
Copy to clipboard

Status 401

{
  "code": "E0001",
  "description": "The provided IAM token is invalid or has expired. Provide a valid IAM token.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud iam oauth-tokens",
  "terseDescription": "Unauthorized",
  "type": "Authentication"
}
Copy to clipboard

Status 404

{
  "code": "E0002",
  "description": "The requested resource could not be found. Verify the resource ID and try again.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster ls",
  "terseDescription": "Not found",
  "type": "NotFound"
}
Copy to clipboard

Status 500

{
  "code": "E0003",
  "description": "An internal server error occurred. Try again later or contact support if the problem persists.",
  "incidentID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recoveryCLI": "ibmcloud ks cluster get --cluster <cluster_name_or_ID>",
  "terseDescription": "Internal error",
  "type": "InternalServerError"
}
Copy to clipboard

v1-v2 | IBM Cloud API Docs

Introduction

Before you begin

Charges

Authentication

Authorization

IAM and Activity Tracker actions by API method

API endpoint

Versioning

Error handling

Methods

Get the autoscaling configuration for an ALB

Request

Path Parameters

id_or_name

alb_id

Response

Response Body

Status Code

200

400

401

403

404

500

Set the autoscaling configuration for an ALB

Request

Path Parameters

id_or_name

alb_id

Request Body

config

Response

Response Body

Status Code

200

400

401

403

404

500

Delete the autoscaling configuration for an ALB

Request

Path Parameters

id_or_name

alb_id

Response

Status Code

204

400

401

403

404

500

Create an Ingress domain for a cluster

Request

Request Body

ips

cluster

crn

hostname

isDefault

provider

secretNamespace

zoneID

Response

Response Body

nlbIPArray

certProvider

cluster

crn

dnsType

isDefault

lbHostname

nlbSubdomain

provider

secretNamespace

statusMessage

type

zoneID