Delete the autoscaling configuration for an ALB.

DELETE /ingress/v2/clusters/{idOrName}/albs/{albID}/autoscale

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

You must have the Editor platform role for the Kubernetes Service in IAM to call this endpoint.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

  • cluster-alb-autoscale.unset

Request

Path Parameters

idOrName

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

albID

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

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. No autoscaling configuration set for this cluster and ALB, or the specified cluster or ALB could not be found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get the autoscaling configuration for an ALB.

GET /ingress/v2/clusters/{idOrName}/albs/{albID}/autoscale

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To call this endpoint, you must have the Viewer platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • cluster-alb-autoscale.get

Request

Path Parameters

idOrName

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

albID

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

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. No autoscale configuration set for this cluster and ALB, or the specified cluster or ALB could not be found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Set the autoscaling configuration for an ALB.

PUT /ingress/v2/clusters/{idOrName}/albs/{albID}/autoscale

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

You must have the Editor platform role for the Kubernetes Service in IAM to call this endpoint.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

  • cluster-alb-autoscale.set

Request

Request Body

AutoscaleDetails

New autoscale configuration to be set.

config

AutoscaleConfig

AutoscaleConfig is used for configuring autoscaling for albs

cpuAverageUtilization

integer

customMetrics

string

maxReplicas

integer

minReplicas

integer

Path Parameters

idOrName

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

albID

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

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The the specified cluster or ALB could not be found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create an Ingress domain for a cluster.

POST /ingress/v2/dns/createDomain

Create an Ingress domain for a cluster.

Request

Request Body

CreateDomainReq

Input parameter to create a domain.

cluster

string

crn

string

hostname

string

ips

array

isDefault

boolean

provider

string

secretNamespace

string

zoneID

string

Path Parameters

Query Parameters

Response

201 - Created. The domain is created.

certProvider

string

cluster

string

crn

string

dnsType

string

isDefault

boolean

lbHostname

string

nlbIPArray

array

nlbSubdomain

string

provider

string

secretNamespace

string

statusMessage

string

type

string

zoneID

string

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Deprecated: Delete external domain provider credential.

POST /ingress/v2/dns/deleteCredential

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

Request

Path Parameters

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

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Delete a non-default Ingress domain for a cluster.

POST /ingress/v2/dns/deleteDomain

Delete a non-default Ingress domain for a cluster.

Request

Request Body

DeleteDomainReq

Input parameter to delete a domain.

cluster

string

subdomain

string

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Deprecated: Get external domain provider credential metadata.

GET /ingress/v2/dns/getCredential

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

Request

Path Parameters

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

Response

200 - Ok. The credential was successfully fetched.

cluster

string

credID

string

expiresOn

string

lastUpdatedTimestamp

string

provider

string

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Replace the existing default Ingress domain for a cluster.

POST /ingress/v2/dns/replaceDefaultSubdomain

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

Request

Request Body

ReplaceDefaultSubdomainReq

Input parameter to replace default domain.

cluster

string

subdomain

string

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Deprecated: Set external domain provider credential.

POST /ingress/v2/dns/setCredential

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

Request

Request Body

CreateCredentialReq

Input parameter to register an external domain provider credential.

akamai_credentials

AkamaiCredentials

AkamaiCredentials is the struct representation of Akamai creds

access_token

string

client_secret

string

client_token

string

host

string

zone

string

cloudflare_credentials

CloudflareCredentials

CloudflareCredentials is the struct representation of Cloudflare creds

token

string

zone_id

string

cluster

string

provider

string

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Update an Ingress domain for a cluster.

POST /ingress/v2/dns/updateDomain

Update an Ingress domain with the specified IPs or hostnames.

Request

Request Body

UpdateDomainReq

Input parameter to update a domain.

cluster

string

domain

string

hostname

string

ips

array

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get configuration of load balancers for Ingress ALBs.

GET /ingress/v2/load-balancer/configuration

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

Request

Path Parameters

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

Response

200 - Ok. The load balancer configuration for the specified type is returned.

backend

LBBackendConfig

LBBackendConfig stuct for configuring the loadbalancer's backend

cluster

string

proxyProtocol

LBProxyProtocolConfig

LBProxyProtocolConfig stuct for storing the loadbalancer's proxy protocol config in etcd

type

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Update the configuration of load balancers for Ingress ALBs.

PATCH /ingress/v2/load-balancer/configuration

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`

Request

Request Body

LBConfig

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

backend

LBBackendConfig

LBBackendConfig stuct for configuring the loadbalancer's backend

private

string

public

string

cluster

string

proxyProtocol

LBProxyProtocolConfig

LBProxyProtocolConfig stuct for storing the loadbalancer's proxy protocol config in etcd

cidr

array

enable

boolean

headerTimeout

integer

type

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

423 - Locked. The previous load-balancer configuration is still in progress.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

POST /ingress/v2/secret/addField

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

Request

Request Body

UpdateConfig

Input parameter to add a secret field.

add

array

cluster

string

crn

string

name

string

namespace

string

remove

array

Path Parameters

Query Parameters

Response

201 - Updated. The fields were successfully added to the secret in the cluster.

cluster

string

crn

string

domain

string

deprecated: use "Domains" instead

domains

array

expiresOn

string

fields

Fields

Fields struct for a secret array

lastUpdatedTimestamp

string

name

string

namespace

string

persistence

boolean

secretType

string

status

string

type

string

userManaged

boolean

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

POST /ingress/v2/secret/createSecret

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

Request

Request Body

CreateConfig

Input parameter to add a secret.

add

array

cluster

string

crn

string

name

string

namespace

string

persistence

boolean

type

string

Path Parameters

Query Parameters

Response

201 - Created. The secret was successfully created in the cluster.

cluster

string

crn

string

domain

string

deprecated: use "Domains" instead

domains

array

expiresOn

string

fields

Fields

Fields struct for a secret array

lastUpdatedTimestamp

string

name

string

namespace

string

persistence

boolean

secretType

string

status

string

type

string

userManaged

boolean

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Delete an Ingress secret from the cluster.

POST /ingress/v2/secret/deleteSecret

Delete an Ingress secret from the cluster.

Request

Request Body

DeleteConfig

Input parameter to add a secret.

cluster

string

name

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

GET /ingress/v2/secret/getInstance

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

Request

Path Parameters

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

Response

200 - Ok. Detailed information about the secret is returned.

callbackChannel

string

cluster

string

crn

string

isDefault

boolean

name

string

secretGroupID

string

secretGroupName

string

status

string

type

string

userManaged

boolean

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View IBM Cloud Secrets Manager instances registered to the cluster.

GET /ingress/v2/secret/getInstances

View IBM Cloud Secrets Manager instances registered to the cluster.

Request

Path Parameters

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

showDeleted

string

To view previously deleted instances, pass `true`.

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View Ingress secret details.

GET /ingress/v2/secret/getSecret

View Ingress secret details.

Request

Path Parameters

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

Response

200 - Ok. Detailed information about the secret is returned.

cluster

string

crn

string

domain

string

deprecated: use "Domains" instead

domains

array

expiresOn

string

fields

Fields

Fields struct for a secret array

lastUpdatedTimestamp

string

name

string

namespace

string

persistence

boolean

secretType

string

status

string

type

string

userManaged

boolean

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View Ingress secrets for a cluster.

GET /ingress/v2/secret/getSecrets

View Ingress secrets for a cluster.

Request

Path Parameters

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

showDeleted

string

To view previously deleted secrets, pass `true`.

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Register an IBM Cloud Secrets Manager instance to the cluster.

POST /ingress/v2/secret/registerInstance

Register an IBM Cloud Secrets Manager instance to the cluster.

Request

Request Body

RegisterConfig

Input parameter to register an instance.

cluster

string

crn

string

isDefault

boolean

secretGroupID

string

Path Parameters

Query Parameters

Response

200 - Created. The instance was successfully registered to the cluster.

callbackChannel

string

cluster

string

crn

string

isDefault

boolean

name

string

secretGroupID

string

secretGroupName

string

status

string

type

string

userManaged

boolean

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

POST /ingress/v2/secret/removeField

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

Request

Request Body

UpdateConfig

Remove input parameter to remove a secret field.

add

array

cluster

string

crn

string

name

string

namespace

string

remove

array

Path Parameters

Query Parameters

Response

200 - Updated. The fields were successfully removed from the secret in the cluster.

cluster

string

crn

string

domain

string

deprecated: use "Domains" instead

domains

array

expiresOn

string

fields

Fields

Fields struct for a secret array

lastUpdatedTimestamp

string

name

string

namespace

string

persistence

boolean

secretType

string

status

string

type

string

userManaged

boolean

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Unregister an IBM Cloud Secrets Manager instance from the cluster.

POST /ingress/v2/secret/unregisterInstance

Unregister an IBM Cloud Secrets Manager instance from the cluster.

Request

Request Body

DeleteConfig

Input parameter to unregister an instance.

cluster

string

name

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

POST /ingress/v2/secret/updateInstance

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

Request

Request Body

InstanceUpdateConfig

Input parameter to update instance registration.

cluster

string

isDefault

boolean

name

string

secretGroupID

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

POST /ingress/v2/secret/updateSecret

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

Request

Request Body

UpdateConfig

Input parameter to add a secret.

add

array

cluster

string

crn

string

name

string

namespace

string

remove

array

Path Parameters

Query Parameters

Response

201 - Created. The secret was successfully created in the cluster.

cluster

string

crn

string

domain

string

deprecated: use "Domains" instead

domains

array

expiresOn

string

fields

Fields

Fields struct for a secret array

lastUpdatedTimestamp

string

name

string

namespace

string

persistence

boolean

secretType

string

status

string

type

string

userManaged

boolean

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

GET /ingress/v2/security/port80

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

Request

Path Parameters

Query Parameters

cluster

Required *

string

The name or ID of the cluster.

Response

200 - Ok. The port 80 configuration for the specified cluster is returned.

cluster

string

state

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Enable port 80 on the cluster.

PATCH /ingress/v2/security/port80

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.

Request

Request Body

Port80Config

Specify the security setting for port 80.

cluster

string

state

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get the OAuth access type for a VPC cluster.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • oauth-access-type.get

Request

Path Parameters

idOrName

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

Query Parameters

Response

200 - Ok. The OAuth access type for the specified cluster is returned.

oauth_access_type

string

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Set the OAuth access type for a VPC cluster.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Editor platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

  • oauth-access-type.set

Request

Request Body

OauthAccessTypeJSON

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

oauth_access_type

string

Path Parameters

idOrName

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

Query Parameters

Response

202 - Accepted. The request to set the OAuth access type was successful.

400 - The OAuth access type you specified is not supported.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

POST /network/v2/outbound-traffic-protection

Request

Request Body

OutboundTrafficProtectionRequest

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

cluster

string

operation

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

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

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.

Request

Path Parameters

idOrName

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

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get a Satellite cluster's service endpoint allowlist.

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

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.

Request

Path Parameters

idOrName

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

Query Parameters

Response

200 - Ok. The allowlist for the Satellite cluster's service endpoint is returned.

actualCSEACLList

array

desiredCSEACLList

array

400 - Bad request. Satellite Service Endpoint Allowlist feature is disabled on the specified cluster.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

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

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.

Request

Request Body

csePatchACL

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

aclList

array

The ACL list to patch

Path Parameters

idOrName

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

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Enable the subnet allowlist for a Satellite cluster's service endpoint.

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

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.

Request

Path Parameters

idOrName

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

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

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

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.

Request

Request Body

csePatchACL

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

aclList

array

The ACL list to patch

Path Parameters

idOrName

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

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

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

Request

Request Body

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

cluster

string

disableOutboundTrafficProtection

boolean

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

POST /network/v2/security-group

Request

Request Body

SecurityGroupRequest

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

cluster

string

operation

string

securityGroupID

string

Path Parameters

Query Parameters

Response

202 - Accepted. The requested security group operation was successfully processed.

400 - Bad request. The query parameters are either incomplete or in the wrong format.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List all security groups associated with a cluster.

GET /network/v2/security-group/getSecurityGroups

Request

Path Parameters

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.

userProvided

string

Specify `true` to return the security groups created by user. Specify `false` to return only the IKS managed security groups.

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Deprecated: Private service endpoint allowlists are no longer supported and context based restrictions (CBR) should be used instead. For more details visit: https://cloud.ibm.com/docs/containers?topic=containers-pse-to-cbr-migration

DELETE /v1/acl/{idOrName}

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.

Request

Path Parameters

idOrName

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

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Deprecated: Private service endpoint allowlists are no longer supported and context based restrictions (CBR) should be used instead. For more details visit: https://cloud.ibm.com/docs/containers?topic=containers-pse-to-cbr-migration

GET /v1/acl/{idOrName}

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.

Request

Path Parameters

idOrName

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

Query Parameters

Response

200 - Ok. The allowlist for the cluster's private service endpoint is returned.

actualCSEACLList

CSEACLList

CSEACLList actual and desired

desiredCSEACLList

CSEACLList

CSEACLList actual and desired

400 - Bad request. Private Service Endpoint Allowlist feature is disabled on the specified cluster.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Deprecated: Private service endpoint allowlists are no longer supported and context based restrictions (CBR) should be used instead. For more details visit: https://cloud.ibm.com/docs/containers?topic=containers-pse-to-cbr-migration

PATCH /v1/acl/{idOrName}/add

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.

Request

Request Body

csePatchACL

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

aclList

array

The ACL list to patch

Path Parameters

idOrName

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

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Deprecated: Private service endpoint allowlists are no longer supported and context based restrictions (CBR) should be used instead. For more details visit: https://cloud.ibm.com/docs/containers?topic=containers-pse-to-cbr-migration

POST /v1/acl/{idOrName}/enable

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.

Request

Path Parameters

idOrName

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

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Deprecated: Private service endpoint allowlists are no longer supported and context based restrictions (CBR) should be used instead. For more details visit: https://cloud.ibm.com/docs/containers?topic=containers-pse-to-cbr-migration

PATCH /v1/acl/{idOrName}/rm

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.

Request

Request Body

csePatchACL

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

aclList

array

The ACL list to patch

Path Parameters

idOrName

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

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List available add-ons that you can enable in a cluster.

GET /v1/addons

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

No IBM Cloud IAM role is required for this operation.

  • ``

Auditing

Calling this method generates the following auditing event.

  • ``

Request

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Enable an existing ALB in a cluster.

POST /v1/alb/albs

Enable a public or private ALB in your standard cluster.

Request

Request Body

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

albBuild

string

The build number of the ALB.

albID

string

The ID of the application load balancer (ALB).

albType

string

The type of ALB.

authBuild

string

The auth build of the ALB.

cluster

string

createdDate

string

The date the ALB was created.

disableDeployment

boolean

If set to true, the deployment of the ALB is disabled.

enable

boolean

Set to true to enable the ALB, or false to disable the ALB for the cluster.

loadBalancerHostname

string

name

string

The name of the cluster that the ALB belongs to.

numOfInstances

string

Desired number of ALB replicas that you want in your cluster.

resize

boolean

If set to true, resizing of the ALB is done.

state

string

The state of the ALB.

status

string

The status of the ALB.

zone

string

The zone where you want to add ALBs.

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Disable an ALB in your cluster.

DELETE /v1/alb/albs/{albID}

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.

Request

Path Parameters

albID

Required *

string

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

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details of an ALB.

GET /v1/alb/albs/{albID}

View detailed information for an ALB in a cluster.

Request

Path Parameters

albID

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

Query Parameters

Response

200 - Ok. Details for the specified ALB are returned.

albBuild

string

The build number of the ALB.

albID

string

The ID of the application load balancer (ALB).

albType

string

The type of ALB.

authBuild

string

The auth build of the ALB.

cluster

string

createdDate

string

The date the ALB was created.

disableDeployment

boolean

If set to true, the deployment of the ALB is disabled.

enable

boolean

Set to true to enable the ALB, or false to disable the ALB for the cluster.

loadBalancerHostname

string

name

string

The name of the cluster that the ALB belongs to.

numOfInstances

string

Desired number of ALB replicas that you want in your cluster.

resize

boolean

If set to true, resizing of the ALB is done.

state

string

The state of the ALB.

status

string

The status of the ALB.

zone

string

The zone where you want to add ALBs.

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List all ALBs in a cluster.

GET /v1/alb/clusters/{idOrName}

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

Request

Path Parameters

idOrName

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

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Force a one-time update of all ALB pods to the latest build.

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

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.

Request

Path Parameters

idOrName

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

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Check if automatic updates for Ingress ALBs are enabled in a cluster.

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

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

Request

Path Parameters

idOrName

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

Query Parameters

Response

200 - Ok. The current update policy.

autoUpdate

boolean

If set to true, automatic updates for the ALBs are enabled.

latestVersion

boolean

If set to true, all ALBs in the cluster run the latest ALB version.

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Enable or disable automatic updates for the Ingress ALBs in a cluster.

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

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.

Request

Request Body

UpdatePolicy

The new update policy configuration.

autoUpdate

boolean

If set to true, automatic updates for the ALBs are enabled.

latestVersion

boolean

If set to true, all ALBs in the cluster run the latest ALB version.

Path Parameters

idOrName

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

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create a public or private ALB in a specified zone and VLAN.

POST /v1/alb/clusters/{idOrName}/zone/{zoneId}

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.

Request

Request Body

ALB

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

enableByDefault

boolean

If set to true, the ALB is enabled by default. \

ingressImage

string

The type of Ingress image that you want to use for your ALB deployment.

ip

string

Optional: The IP address that you want to assign to the ALB.

nlbVersion

string

The version of the network load balancer that you want to use for the ALB.

type

string

The type of ALB that you want to create.

vlanID

string

The VLAN ID that you want to use for your ALBs.

zone

string

The zone where you want to deploy the ALB.

Path Parameters

idOrName

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

zoneId

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.

Query Parameters

Response

201 - The ALB was successfully created.

alb

string

cluster

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List the clusters that you have access to.

GET /v1/clusters

List the clusters that you have access to.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster.list

Request

Path Parameters

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

showResources

string

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

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create a cluster.

POST /v1/clusters

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster.create

Request

Request Body

ClusterConfig

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

cseAclEnabled

boolean

dataCenter

string

The data center where the worker node is created.

defaultWorkerPoolEntitlement

string

defaultWorkerPoolName

string

disableAutoUpdate

boolean

diskEncryption

boolean

gatewayEnabled

boolean

isolation

string

machineType

string

The machine type of the worker node.

masterVersion

string

name

string

networkPlugin

string

noSubnet

boolean

operatingSystem

string

podSubnet

string

podSubnets

string

prefix

string

privateSeviceEndpoint

boolean

privateVlan

string

The private VLAN ID that the worker node is attached to.

publicServiceEndpoint

boolean

publicVlan

string

The public VLAN ID that the worker node is attached to.

serviceSubnet

string

skipPermPrecheck

boolean

trustedProfileID

string

vpcNativeRoutingEnabled

boolean

workerNum

integer

Path Parameters

Query Parameters

Response

201 - Created. The cluster was successfully created in the IBM Cloud account that you are logged in to.

id

string

non_critical_errors

ResponseErrors

ResponseErrors are used to communicate to non-critical errors to end users

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

409 - Conflict. A cluster with the same name already exists. Choose another name for your cluster.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Delete a cluster.

DELETE /v1/clusters/{idOrName}

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster.delete

Request

Path Parameters

idOrName

Required *

string

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

Query Parameters

deleteResources

string

To delete additional resources linked to the cluster such as VLANs, subnets, and storage, pass `true`.

skipPermissionsPrecheck

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.

deleteOpenShiftRegistryCOSBucket

string

To delete the COS bucket and the associated service key that holds OpenShift registry backups, pass `true`

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details for a cluster.

GET /v1/clusters/{idOrName}

View detailed information for a cluster.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster.get

Request

Path Parameters

idOrName

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

showResources

string

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

Response

200 - Ok. Detailed information about the cluster is returned.

addons

array

apiUser

string

createdDate

string

crn

string

dataCenter

string

desiredTrustedProfileID

string

disableAutoUpdate

boolean

etcdPort

string

id

string

ignitionServerURL

string

imageSecurityEnabled

boolean

ingressHostname

string

ingressMessage

string

ingressSecretName

string

ingressStatus

string

isPaid

boolean

keyProtectEnabled

boolean

konnectivityServerURL

string

location

string

logOrg

string

logOrgName

string

logSpace

string

logSpaceName

string

masterHealth

string

masterKubeVersion

string

masterState

string

masterStatus

string

masterStatusModifiedDate

string

modifiedDate

string

monitoringURL

string

multiAzCapable

boolean

name

string

oauthServerURL

string

podSubnet

string

podSubnets

string

privateServiceEndpointEnabled

boolean

privateServiceEndpointURL

string

publicServiceEndpointEnabled

boolean

publicServiceEndpointURL

string

pullSecretApplied

boolean

region

string

resourceGroup

string

resourceGroupName

string

serverURL

string

serviceSubnet

string

state

string

status

string

targetVersion

string

trustedProfileID

string

type

string

versionEOS

string

vlans

array

vpcNativeRoutingEnabled

boolean

workerCount

integer

workerZones

array

worker_vlans

VLANS

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.

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Update the version of the Kubernetes cluster master node.

PUT /v1/clusters/{idOrName}

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-master.update

Request

Request Body

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

action

string

The action to perform on the master.

force

boolean

If set to true, any warnings during the update process are ignored.

version

string

The Kubernetes version to use for the update.

Path Parameters

idOrName

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

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details of the add-ons that are enabled in a cluster.

GET /v1/clusters/{idOrName}/addons

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-addon.list

Request

Path Parameters

idOrName

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

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

PATCH /v1/clusters/{idOrName}/addons

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-addon.enable
  • containers-kubernetes.cluster-addon.disable
  • containers-kubernetes.cluster-addon.update

Request

Request Body

AddonRequest

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

addons

Required *

array

The addons to operate on.

enable

boolean

Indicate if the specified addons should be enabled or disabled.

update

boolean

Indicate if the specified addons should be updated. Only Update or Enable should be used, not both.

Path Parameters

idOrName

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

Query Parameters

Response

200 - OK. The add-on changes have been processed.

missingDeps

array

The addon enable request would result in an invalid configuration. Install missing addons to continue.

orphanedAddons

object

The addon disable request would result in an invalid configuration. Inspect the map to determine why the configuration is invalid.

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

409 - Conflict. The current add-on configuration is not compatible. Check 'MissingDeps' for add-ons to enable in this cluster.

missingDeps

array

The addon enable request would result in an invalid configuration. Install missing addons to continue.

orphanedAddons

object

The addon disable request would result in an invalid configuration. Inspect the map to determine why the configuration is invalid.

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Delete an audit webhook configuration.

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

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-audit-webhook.delete

Request

Path Parameters

idOrName

Required *

string

The name or ID of the cluster for which you want to change the audit config. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details for an audit webhook configuration.

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-audit-webhook.get

Request

Path Parameters

idOrName

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

Query Parameters

Response

200 - Successfully retrieved the audit webhook configuration.

auditServer

string

The URL of the server to send audit logs to.

caCertificate

string

The Certificate Authority certificate that is used to connect to the audit server.

clientCertificate

string

The client certificate that is used to connect to the audit server.

clientKey

string

The client key that is used to connect to the audit server.

policy

string

The audit policy type to be configured.

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create or update an audit webhook configuration for a cluster.

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

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Editor platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-audit-webhook.update

Request

Request Body

AuditWebhookConfig

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

auditServer

string

The URL of the server to send audit logs to.

caCertificate

string

The Certificate Authority certificate that is used to connect to the audit server.

clientCertificate

string

The client certificate that is used to connect to the audit server.

clientKey

string

The client key that is used to connect to the audit server.

policy

string

The audit policy type to be configured.

Path Parameters

idOrName

Required *

string

The name or ID of the cluster where you want to add an audit configuration or change the audit configuration. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get the cluster-specific configuration and certificates.

GET /v1/clusters/{idOrName}/config

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster.config

Request

Path Parameters

idOrName

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

createNetworkConfig

boolean

Retrieve the Calico network config with the Admin config. This only works against the admin endpoint('/config/admin')

skipRBAC

boolean

Deprecated: Previously this skipped adding the RBAC roles based on user's access in IAM. RBAC is now always applied and completes asynchronously.

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create and enable a key management service (KMS) provider configuration for a cluster.

POST /v1/clusters/{idOrName}/kms

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-service.list

Request

Request Body

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.

accountID

string

AccountID stores the ID of the account where the key protect instance resides Its value can be either: the same account ID the given cluster resides in (non cross account use case) not the clusters account ID in which the KMS instance resides (cross account use case) empty, in case of old clusters which were secret encrypted before this AccountID field was added to this struct. This case falls back to the first point and should be handled like that (non cross account use case)

correlationID

string

The correlation ID stores the correlation ID used to trace a CRK call through multiple services

crkID

Required *

string

CRK is a Key Protect customer root key. To get the CRK, see http://ibm.biz/kp-viewcrk

instanceID

Required *

string

InstanceID is a Key Protect instance ID. To get the instance ID, run 'ibmcloud resource service-instance <kp_service> --id' and copy the second value (not the full CRN)

serviceToService

boolean

ServiceToService indicates the KP information in this record was enabled via service-to-service integration, so an associated registration was created.

url

Required *

string

URL is a Key Protect endpoint. To get the endpoint, see http://ibm.biz/kp-endpoints

Path Parameters

idOrName

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

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Refresh the Kubernetes master.

PUT /v1/clusters/{idOrName}/masters

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-master.refresh

Request

Request Body

MasterAPIServer

The master state. Currently, `refresh` is supported.

action

string

The action to perform on the API Server.

Path Parameters

idOrName

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

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List the IBM Cloud services bound to a cluster across all namespaces.

GET /v1/clusters/{idOrName}/services

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-service.list

Request

Path Parameters

idOrName

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

Query Parameters

Response

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.

Bind an IBM Cloud service to a cluster.

POST /v1/clusters/{idOrName}/services

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Editor platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-service.bind

Request

Request Body

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

namespaceID

string

role

string

serviceInstanceGUID

string

serviceKeyGUID

string

serviceKeyJSON

string

Path Parameters

idOrName

Required *

string

The name or ID of the cluster where you want to bind your service. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.

Query Parameters

Response

201 - Created. Your IBM Cloud service instance was successfully bound to the Kubernetes namespace of your cluster.

binding

string

namespaceID

string

secretName

string

serviceInstanceGUID

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

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

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-service.list

Request

Path Parameters

idOrName

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.

Query Parameters

Response

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.

Unbind an IBM Cloud service from a cluster.

DELETE /v1/clusters/{idOrName}/services/{namespace}/{serviceInstanceId}

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Editor platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-service.unbind

Request

Path Parameters

idOrName

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

serviceInstanceId

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

Query Parameters

Response

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.

List classic subnets that are bound to a cluster.

GET /v1/clusters/{idOrName}/subnets

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-subnet.list

Request

Path Parameters

idOrName

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

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Detach a public or private portable subnet from a cluster.

PATCH /v1/clusters/{idOrName}/subnets/{subnetId}

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-subnet.detach

Request

Path Parameters

idOrName

Required *

string

The name or ID of the cluster that you want to remove the subnet from. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.

subnetId

Required *

string

The ID of the subnet that you want to remove from your cluster.

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Add an IBM Cloud classic infrastructure subnet to a cluster.

PUT /v1/clusters/{idOrName}/subnets/{subnetId}

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.subnet.add

Request

Path Parameters

idOrName

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

subnetId

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

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

GET /v1/clusters/{idOrName}/usersubnets

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-user-subnet.list

Request

Path Parameters

idOrName

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

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Add an existing user-managed subnet to a cluster.

POST /v1/clusters/{idOrName}/usersubnets

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-user-subnet.add

Request

Request Body

UserSubnet

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

cidr

string

The subnet and the CIDR that you want to add to the cluster in the format 12.34.45.78/24.

vlan_id

string

The private VLAN ID that the subnet CIDR belongs to.

Path Parameters

idOrName

Required *

string

The name or ID of the cluster that you want to make your user-managed subnet available to. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Remove a user-managed subnet from a cluster.

DELETE /v1/clusters/{idOrName}/usersubnets/{subnetId}/vlans/{vlanId}

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.vlan.delete

Request

Path Parameters

idOrName

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

subnetId

Required *

string

The GUID of the user-managed subnet that you want to remove from your cluster.

vlanId

Required *

string

The ID of the private VLAN that the user-managed subnet is on.

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create an IBM Cloud classic infrastructure subnet and add it to an existing cluster.

POST /v1/clusters/{idOrName}/vlans/{vlanId}

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.subnet.create

Request

Path Parameters

idOrName

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

vlanId

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.

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List all webhooks for a cluster.

GET /v1/clusters/{idOrName}/webhooks

List all webhooks for a Kubernetes cluster.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-webhook.list

Request

Path Parameters

idOrName

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

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Add a webhook to a cluster.

POST /v1/clusters/{idOrName}/webhooks

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Editor platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-webhook.create

Request

Request Body

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.

level

string

The notification level that you want to use for the webhook.

type

string

The webhook service type.

url

string

The webhook URL.

Path Parameters

idOrName

Required *

string

The name or ID of the cluster that you want to add a webhook to. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List the worker pools in a cluster.

GET /v1/clusters/{idOrName}/workerpools

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool.list

Request

Path Parameters

idOrName

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

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create a worker pool for a cluster.

POST /v1/clusters/{idOrName}/workerpools

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool.create

Request

Request Body

WorkerPoolRequest

The

diskEncryption

boolean

If set to true, the secondary disk of the worker node is encrypted. If set to false, no encryption is set up.

entitlement

string

isolation

string

labels

object

machineType

string

name

string

operatingSystem

string

sizePerZone

integer

zones

array

Path Parameters

idOrName

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

Query Parameters

Response

201 - Created. The worker pool was successfully created in for the specified cluster.

autoscaleEnabled

boolean

id

string

isBalanced

boolean

isolation

string

labels

object

machineType

string

name

string

operatingSystem

string

reasonForDelete

string

region

string

sizePerZone

integer

state

string

zones

WorkerPoolZoneResponses

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

409 - Conflict. A worker pool create may already be in progress for the provided cluster. Please wait a few minutes and try again.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Remove a worker pool from a cluster.

DELETE /v1/clusters/{idOrName}/workerpools/{poolidOrName}

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool.delete

Request

Path Parameters

idOrName

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

poolidOrName

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

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details for a worker pool.

GET /v1/clusters/{idOrName}/workerpools/{poolidOrName}

View detailed information for a worker pool.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool.get

Request

Path Parameters

idOrName

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

poolidOrName

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

Query Parameters

Response

200 - Ok. Detailed information about the worker pool is returned.

autoscaleEnabled

boolean

id

string

isBalanced

boolean

isolation

string

labels

object

machineType

string

name

string

operatingSystem

string

reasonForDelete

string

region

string

sizePerZone

integer

state

string

zones

WorkerPoolZoneResponses

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Resize or rebalance a worker pool.

PATCH /v1/clusters/{idOrName}/workerpools/{poolidOrName}

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool.rebalance
  • containers-kubernetes.cluster-worker-pool.resize

Request

Request Body

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.

allowSingleOpenShiftWorker

boolean

labels

object

reasonForResize

string

sizePerZone

integer

state

string

Path Parameters

idOrName

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

poolidOrName

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

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The request will not be permitted.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Add a zone to the specified worker pool for a cluster.

POST /v1/clusters/{idOrName}/workerpools/{poolidOrName}/zones

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool-zone.create

Request

Request Body

WorkerPoolZone

Input parameters to add zones to the worker pool.

id

string

privateVlan

string

publicVlan

string

Path Parameters

idOrName

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

poolidOrName

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

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

409 - Conflict. The provided zone already exists in the worker pool.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Remove a zone from a worker pool.

DELETE /v1/clusters/{idOrName}/workerpools/{poolidOrName}/zones/{zoneid}

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool-zone.delete

Request

Path Parameters

idOrName

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

poolidOrName

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 zone that you want to remove from the worker pool. To list all worker pools for a cluster, use the `GET /v1/zones` API or run `ibmcloud ks zone ls`.

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The request will not be permitted.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

PATCH /v1/clusters/{idOrName}/workerpools/{poolidOrName}/zones/{zoneid}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool-zone-network.add

Request

Request Body

WorkerPoolZonePatchRequest

Updated network configuration values for the worker pool zone.

privateVlan

string

publicVlan

string

Path Parameters

idOrName

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

poolidOrName

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

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The request will not be permitted.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List all worker nodes in a cluster.

GET /v1/clusters/{idOrName}/workers

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker.list

Request

Path Parameters

idOrName

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

showDeleted

string

true|false Shows deleted workers

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Add worker nodes to a cluster.

POST /v1/clusters/{idOrName}/workers

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker.add

Request

Request Body

WorkerConfig

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

dataCenter

string

The data center where the worker node is created.

diskEncryption

boolean

isolation

string

machineType

string

The machine type of the worker node.

operatingSystem

string

prefix

string

privateVlan

string

The private VLAN ID that the worker node is attached to.

publicVlan

string

The public VLAN ID that the worker node is attached to.

workerNum

integer

Path Parameters

idOrName

Required *

string

The name or ID of the cluster to which you want to add additional 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

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Delete a worker node from a cluster.

DELETE /v1/clusters/{idOrName}/workers/{workerId}

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.worker.delete

Request

Path Parameters

idOrName

Required *

string

The name or ID of the cluster to add additional worker nodes to. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.

workerId

Required *

string

The ID of the worker node. 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>`.

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details of a worker node.

GET /v1/clusters/{idOrName}/workers/{workerId}

View detailed information for a worker node.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.worker.get

Request

Path Parameters

idOrName

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

workerId

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

Query Parameters

Response

200 - Ok. Detailed information about the worker node is returned.

errorMessage

string

errorMessageDate

string

id

string

isolation

string

kubeVersion

string

location

string

machineType

string

masterVersionEOS

string

pendingOperation

string

poolName

string

poolid

string

privateIP

string

privateVlan

string

publicIP

string

publicVlan

string

reasonForDelete

string

state

string

status

string

statusDate

string

statusDetails

string

targetVersion

string

trustedStatus

string

versionEOS

string

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Reboot, reload, or update a worker node for a cluster.

PUT /v1/clusters/{idOrName}/workers/{workerId}

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.worker.reboot
  • containers-kubernetes.worker.reload
  • containers-kubernetes.worker.reboot

Request

Request Body

UpdateWorkerCommand

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

action

string

The action to perform on the worker node.

force

boolean

Setting force flag to true will ignore if the master is unavailable during 'os_reboot" and 'reload' action

Path Parameters

idOrName

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

workerId

Required *

string

The ID of the worker node. 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>`.

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List configuration values for your IBM Cloud account.

GET /v1/config

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • ``

Request

Response

200 - Success

accounts_url

string

acct_url

string

Deprecated: the account and user management APIs are now separated to AccountsURL and UserManagementURL respectively

bluemix_url

string

env_name

string

iam_base_url

string

iam_client_id

string

iam_client_secret

string

iam_issuer

string

iam_papurl

string

iam_pdpurl

string

iam_url

string

uaa_url

string

user_management_url

string

Remove IBM Cloud classic infrastructure account credentials from your IBM Cloud Kubernetes Service account.

DELETE /v1/credentials

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-infra-credential.delete

Request

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. No IBM Cloud infrastructure account credentials are stored in the Kubernetes Service account for this region and resource group.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View the IBM Cloud classic infrastructure account credentials that are set for your IBM Cloud Kubernetes Service account.

GET /v1/credentials

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-infra-credential.get

Request

Path Parameters

Query Parameters

Response

200 - Ok. The IBM Cloud infrastructure (SoftLayer) account credentials were successfully retrieved from IBM Cloud Kubernetes Service.

apiUser

string

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. No IBM Cloud infrastructure account credentials are stored in the Kubernetes Service account for this region and resource group.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Set IBM Cloud classic infrastructure account credentials for your IBM Cloud Kubernetes Service account.

POST /v1/credentials

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-infra-credential.set

Request

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List available machine types for a zone (data center).

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

No IBM Cloud IAM role is required for this operation.

  • ``

Auditing

Calling this method generates the following auditing event.

  • ``

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.

Query Parameters

Response

200 - Success

400 - The specified zone is invalid. To list available zones, run `ibmcloud ks zone ls` or use the `GET /v1/datacenters` API.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List available VLANs for a zone.

GET /v1/datacenters/{datacenter}/vlans

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

No IBM Cloud IAM role is required for this operation.

  • ``

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-datacenter-vlan.list

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.

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get details on the permissions that the IBM Cloud infrastructure (SoftLayer) credentials have.

GET /v1/infra-permissions

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-infra-permission.get

Request

Path Parameters

Query Parameters

Response

200 - Ok.

account

string

ProviderAccountID may contain personally identifiable information

accountType

string

AccountType returns if the account information pertains to a linked or an IaaS account

networkManagerPermissions

Permissions

Permissions describes the result of checking granted permissions Note: the default zero/empty value implies sufficient permissions

physicalWorkerManagerPermissions

Permissions

Permissions describes the result of checking granted permissions Note: the default zero/empty value implies sufficient permissions

storageManagerPermissions

Permissions

Permissions describes the result of checking granted permissions Note: the default zero/empty value implies sufficient permissions

virtualWorkerManagerPermissions

Permissions

Permissions describes the result of checking granted permissions Note: the default zero/empty value implies sufficient permissions

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Reset the IAM API key.

POST /v1/keys

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-api-key.reset

Request

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Deprecated: List available Kubernetes versions.

GET /v1/kube-versions

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

No IBM Cloud IAM role is required for this operation.

  • ``

Auditing

Calling this method generates the following auditing event.

  • ``

Request

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List available locations.

GET /v1/locations

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

No IBM Cloud IAM role is required for this operation.

  • ``

Auditing

Calling this method generates the following auditing event.

  • ``

Request

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View information about the containers-kubernetes-key API key owner.

GET /v1/logging/{idOrName}/clusterkeyowner

View the name and email address for the owner of the cluster's containers-kubernetes-key API key.

Request

Path Parameters

idOrName

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

Response

200 - Ok. The cluster API key ID and the owner's name and email address.

email

string

id

string

name

string

401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View the default logging endpoint for the target region.

GET /v1/logging/{idOrName}/default

View the default logging endpoint for the target region.

Request

Path Parameters

idOrName

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

Response

200 - Ok. The default logging endpoint for the target region.

endpoint

string

The IBM Cloud Log Analysis with LogDNA API endpoint that the hostname uses.

hostname

string

The hostname for the ibm logging service.

port

integer

The port for the ibm logging service.

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Deletes all logging filter configurations for the cluster.

DELETE /v1/logging/{idOrName}/filterconfigs

Stops log filtering.

Request

Path Parameters

idOrName

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

forceUpdate

boolean

Forces the request which may cause a new fluentd version to be deployed to the cluster.

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List all logging filter configurations in the cluster.

GET /v1/logging/{idOrName}/filterconfigs

List the logging filter configurations that you created in a cluster.

Request

Path Parameters

idOrName

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

showMatches

boolean

Set to true to populate global filters with all matching logging configurations.

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create a logging filter configuration.

POST /v1/logging/{idOrName}/filterconfigs

Start filtering logs that are forwarded by your logging configuration from the given sources based on one or more selectors.

Request

Request Body

FilterConfigBody

The new logging filter configuration.

container

string

The name of the container where you want to apply the logging filter.

logLevel

string

The log level that you want to apply to your logging filter.

loggingConfigs

array

A list of logging configuration IDs where you want to apply the logging filter.

message

string

A string in a message to which you want to apply the logging filter.

namespace

string

The Kubernetes namespace where you want to apply the logging filter.

regexMessageEnabled

boolean

Set this value to `true` if you want the message field to be interpreted as a regular expression.

type

string

The type of the logging filter.

Path Parameters

idOrName

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

forceUpdate

boolean

Forces the request which may cause a new fluentd version to be deployed to the cluster.

Response

201 - Ok. Logs from the specified logging configurations will be filtered on the provided selectors.

container

string

The name of the container that you want to exclude from your logs.

coveringFilters

array

A list of logging filter IDs that the filter covers.

id

string

The unique identifier of the logging configuration.

label

string

The pod label that you want to exclude from your logs.

logLevel

string

The log level that you want to apply to your logs. Supported values are `debug` or `info`.

loggingConfigs

array

A list of logging configuration IDs where you want to apply the log filter.

message

string

A string in a log message that you want to exclude from your logs.

namespace

string

The Kubernetes namespace that you want to exclude from your logs.

regexMessageEnabled

boolean

Set this value to `true` if you want to interpret the message field as a regular expression.

type

string

The type of filter that you want to apply to your logs. Supported values are `container` and `non-container`.

version

string

Internal use only.

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Delete a logging filter configuration.

DELETE /v1/logging/{idOrName}/filterconfigs/{id}

Delete the specified logging filter configuration for a cluster.

Request

Path Parameters

idOrName

Required *

string

The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.

id

Required *

string

The UUID for the filterConfig that you want to delete.

Query Parameters

forceUpdate

boolean

Forces the request which may cause a new fluentd version to be deployed to the cluster.

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View a logging filter configuration.

GET /v1/logging/{idOrName}/filterconfigs/{id}

View details for a logging filter configuration.

Request

Path Parameters

idOrName

Required *

string

The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.

id

Required *

string

The UUID of the logging filter that you want to fetch.

Query Parameters

showMatches

boolean

To show matching logging configurations for global filters, set to `true`.

Response

200 - Ok. A logging filter is configured for your cluster.

container

string

The name of the container that you want to exclude from your logs.

coveringFilters

array

A list of logging filter IDs that the filter covers.

id

string

The unique identifier of the logging configuration.

label

string

The pod label that you want to exclude from your logs.

logLevel

string

The log level that you want to apply to your logs. Supported values are `debug` or `info`.

loggingConfigs

array

A list of logging configuration IDs where you want to apply the log filter.

message

string

A string in a log message that you want to exclude from your logs.

namespace

string

The Kubernetes namespace that you want to exclude from your logs.

regexMessageEnabled

boolean

Set this value to `true` if you want to interpret the message field as a regular expression.

type

string

The type of filter that you want to apply to your logs. Supported values are `container` and `non-container`.

version

string

Internal use only.

401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Update a logging filter configuration.

PUT /v1/logging/{idOrName}/filterconfigs/{id}

Update a logging filter config where `id` is the UUID for the filter config.

Request

Request Body

FilterConfigBody

The new filter configuration for the specified ID.

container

string

The name of the container where you want to apply the logging filter.

logLevel

string

The log level that you want to apply to your logging filter.

loggingConfigs

array

A list of logging configuration IDs where you want to apply the logging filter.

message

string

A string in a message to which you want to apply the logging filter.

namespace

string

The Kubernetes namespace where you want to apply the logging filter.

regexMessageEnabled

boolean

Set this value to `true` if you want the message field to be interpreted as a regular expression.

type

string

The type of the logging filter.

Path Parameters

idOrName

Required *

string

The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.

id

Required *

string

The UUID for the filterConfig that you want to update.

Query Parameters

forceUpdate

boolean

Forces the request which may cause a new fluentd version to be deployed to the cluster.

Response

200 - Ok. The configuration was updated.

container

string

The name of the container that you want to exclude from your logs.

coveringFilters

array

A list of logging filter IDs that the filter covers.

id

string

The unique identifier of the logging configuration.

label

string

The pod label that you want to exclude from your logs.

logLevel

string

The log level that you want to apply to your logs. Supported values are `debug` or `info`.

loggingConfigs

array

A list of logging configuration IDs where you want to apply the log filter.

message

string

A string in a log message that you want to exclude from your logs.

namespace

string

The Kubernetes namespace that you want to exclude from your logs.

regexMessageEnabled

boolean

Set this value to `true` if you want to interpret the message field as a regular expression.

type

string

The type of filter that you want to apply to your logs. Supported values are `container` and `non-container`.

version

string

Internal use only.

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Delete all log forwarding configurations for a cluster.

DELETE /v1/logging/{idOrName}/loggingconfig

Stops all log forwarding for a cluster by deleting all log forwarding configurations.

Request

Path Parameters

idOrName

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

forceUpdate

boolean

Forces the request which may cause a new fluentd version to be deployed to the cluster.

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List all log forwarding configurations in the cluster.

GET /v1/logging/{idOrName}/loggingconfig

List the log forwarding configurations in the target cluster.

Request

Path Parameters

idOrName

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

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List all log forwarding configurations for a log source in the cluster.

GET /v1/logging/{idOrName}/loggingconfig/{logSource}

List the log forwarding configurations for the specified log source in the target cluster.

Request

Path Parameters

idOrName

Required *

string

The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.

logSource

Required *

string

The type of log source that you want to list configurations for.

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create a log forwarding configuration.

POST /v1/logging/{idOrName}/loggingconfig/{logSource}

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.

Request

Request Body

LogConfigBody

The type of log collector server for the logging configuration. Supported logging types are 'syslog' and 'ibm'.

appLogContainers

array

A list of container names that you want to collect logs for.

appLogPaths

array

A list of app paths that you want to collect logs for.

caCert

string

The name of the Kubernetes secret that holds the Certificate Authority certificate that you want to use for the syslog TLS termination.

loggingType

string

The logging type that you want to use. Supported values are `syslog` and `ibm`.

namespace

string

The Kubernetes namespace where the logging configuration is applied.

org

string

The name of the Cloud Foundry organization where the logging configuration is created.

protocol

string

The protocol that you want to use for syslog forwarding. Supported values are TCP, TLS and UDP. If no value is provided, the protocol is set to UDP by default.

remoteLogPort

integer

The port that the logging server uses. This value is required only when `LoggingType` is set to `syslog`.

remoteLogServer

string

The hostname or IP address of the logging server. This values is required only if `LoggingType` is set to `syslog`.

space

string

The name of the Cloud Foundry space where the logging configuration is created.

verifyMode

string

The verification mode that you want to use for the syslog TLS protocol. By default, `verify-none` is used. Other supported values include `verify-peer`, `verify-client-once`, and `verify-if-no-peer-cert`.

Path Parameters

idOrName

Required *

string

The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.

logSource

Required *

string

The log source from which you want to forward logs. Accepted 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.

Query Parameters

forceUpdate

boolean

Forces the request which may cause a new fluentd version to be deployed to the cluster.

skipValidation

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.

Response

201 - Ok. Logs from the specified log source will be forwarded to the log server.

appLogContainers

array

A list of container names that you want to collect logs for.

appLogPaths

array

A list of app paths that you want to collect logs for.

caCert

string

The name of the Kubernetes secret that holds the Certificate Authority certificate that you want to use for the syslog TLS termination.

endpoint

string

The IBM Cloud Log Analysis with LogDNA API endpoint that the logging configuration uses.

errors

array

A list of errors that occurred during the last logging config update.

id

string

The unique identifier of the log source.

logSource

string

The type of logs that you want to read and forward to the logging server. Supported values are `container`, `kubernetes`, `ingress`, `worker`, and `application`.

logSourceContainers

array

A list of container names that logs are collected for and forwarded to the logging server.

logSourcePaths

array

A list of app paths that logs are collected for and forwarded to the logging server.

loggingType

string

The logging protocol to use. Supported values are `syslog` and `ibm`.

namespace

string

The Kubernetes namespace where the logging type is applied. This parameter is set only when the `container` log source is used.

org

string

The name of the Cloud Foundry organization where the logging configuration was created.

orgGUID

string

The GUID of the Cloud Foundry organization where the logging configuration was created.

protocol

string

The protocol that you want to use for syslog forwarding. Supported values are `TCP` and `UDP`. If no value is provided, the protocol is set to `UDP` by default.

remoteLogPort

integer

The port of the logging server.

remoteLogServer

string

The hostname or IP address of the logging server.

space

string

The name of the Cloud Foundry space where the logging configuration was created.

spaceGUID

string

The GUID of the Cloud Foundry space where the logging configuration was created.

verifyMode

string

The verification mode that is used for the syslog TLS protocol.

version

string

Internal use only.

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Delete a log forwarding configuration.

DELETE /v1/logging/{idOrName}/loggingconfig/{logSource}/{id}

Stops log forwarding by deleting a specified logging configuration.

Request

Path Parameters

idOrName

Required *

string

The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.

logSource

Required *

string

The log source that you want to stop forwarding logs for.

id

Required *

string

The UUID of the logging configuration that you want to delete.

Query Parameters

forceUpdate

boolean

Forces the request which may cause a new fluentd version to be deployed to the cluster.

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Update a log forwarding configuration.

PUT /v1/logging/{idOrName}/loggingconfig/{logSource}/{id}

Update the details of a log forwarding configuration.

Request

Request Body

LogConfigBody

The new type of log collector server for the logging configuration. Supported logging types are 'syslog'.

appLogContainers

array

A list of container names that you want to collect logs for.

appLogPaths

array

A list of app paths that you want to collect logs for.

caCert

string

The name of the Kubernetes secret that holds the Certificate Authority certificate that you want to use for the syslog TLS termination.

loggingType

string

The logging type that you want to use. Supported values are `syslog` and `ibm`.

namespace

string

The Kubernetes namespace where the logging configuration is applied.

org

string

The name of the Cloud Foundry organization where the logging configuration is created.

protocol

string

The protocol that you want to use for syslog forwarding. Supported values are TCP, TLS and UDP. If no value is provided, the protocol is set to UDP by default.

remoteLogPort

integer

The port that the logging server uses. This value is required only when `LoggingType` is set to `syslog`.

remoteLogServer

string

The hostname or IP address of the logging server. This values is required only if `LoggingType` is set to `syslog`.

space

string

The name of the Cloud Foundry space where the logging configuration is created.

verifyMode

string

The verification mode that you want to use for the syslog TLS protocol. By default, `verify-none` is used. Other supported values include `verify-peer`, `verify-client-once`, and `verify-if-no-peer-cert`.

Path Parameters

idOrName

Required *

string

The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.

logSource

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.

Query Parameters

forceUpdate

boolean

Forces the request which may cause a new fluentd version to be deployed to the cluster.

skipValidation

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.

Response

200 - Ok. The configuration was updated.

appLogContainers

array

A list of container names that you want to collect logs for.

appLogPaths

array

A list of app paths that you want to collect logs for.

caCert

string

The name of the Kubernetes secret that holds the Certificate Authority certificate that you want to use for the syslog TLS termination.

endpoint

string

The IBM Cloud Log Analysis with LogDNA API endpoint that the logging configuration uses.

errors

array

A list of errors that occurred during the last logging config update.

id

string

The unique identifier of the log source.

logSource

string

The type of logs that you want to read and forward to the logging server. Supported values are `container`, `kubernetes`, `ingress`, `worker`, and `application`.

logSourceContainers

array

A list of container names that logs are collected for and forwarded to the logging server.

logSourcePaths

array

A list of app paths that logs are collected for and forwarded to the logging server.

loggingType

string

The logging protocol to use. Supported values are `syslog` and `ibm`.

namespace

string

The Kubernetes namespace where the logging type is applied. This parameter is set only when the `container` log source is used.

org

string

The name of the Cloud Foundry organization where the logging configuration was created.

orgGUID

string

The GUID of the Cloud Foundry organization where the logging configuration was created.

protocol

string

The protocol that you want to use for syslog forwarding. Supported values are `TCP` and `UDP`. If no value is provided, the protocol is set to `UDP` by default.

remoteLogPort

integer

The port of the logging server.

remoteLogServer

string

The hostname or IP address of the logging server.

space

string

The name of the Cloud Foundry space where the logging configuration was created.

spaceGUID

string

The GUID of the Cloud Foundry space where the logging configuration was created.

verifyMode

string

The verification mode that is used for the syslog TLS protocol.

version

string

Internal use only.

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Refresh the cluster's logging configuration.

PUT /v1/logging/{idOrName}/refresh

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.

Request

Path Parameters

idOrName

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

forceUpdate

boolean

Forces the request which may cause a new fluentd version to be deployed to the cluster.

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Check if automatic updates for the Fluentd logging add-on are enabled in the cluster.

GET /v1/logging/{idOrName}/updatepolicy

Check if automatic updates for the Fluentd logging add-on are enabled and whether your Fluentd pods are updated to the latest version.

Request

Path Parameters

idOrName

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

Response

200 - Ok. The current update policy.

autoUpdate

boolean

If set to true, automatic updates for the ALBs are enabled.

latestVersion

boolean

If set to true, all ALBs in the cluster run the latest ALB version.

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Enable or diable automatic updates for the Fluentd logging add-on in the cluster.

PUT /v1/logging/{idOrName}/updatepolicy

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.

Request

Request Body

UpdatePolicy

The new update policy configuration

autoUpdate

boolean

If set to true, automatic updates for the ALBs are enabled.

latestVersion

boolean

If set to true, all ALBs in the cluster run the latest ALB version.

Path Parameters

idOrName

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

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View the current messages.

GET /v1/messages

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

No IBM Cloud IAM role is required for this operation.

  • ``

Auditing

Calling this method generates the following auditing event.

  • ``

Request

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Update a DNS record by adding an NLB IP address.

PUT /v1/nlb-dns/clusters/{idOrName}/add

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.

Request

Request Body

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.

certProvider

string

clusterID

string

crn

string

isDefault

boolean

nlbDnsType

string

nlbHost

string

nlbIPArray

array

nlbMonitorState

string

nlbSslSecretName

string

nlbSslSecretStatus

string

nlbStatusMessage

string

nlbType

string

provider

string

secretNamespace

string

zoneID

string

Path Parameters

idOrName

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

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Enable or disable a health check monitor for an NLB subdomain.

PUT /v1/nlb-dns/clusters/{idOrName}/health

Enable or disable an existing health check monitor for an NLB subdomain.

Request

Request Body

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

certProvider

string

clusterID

string

crn

string

isDefault

boolean

nlbDnsType

string

nlbHost

string

nlbIPArray

array

nlbMonitorState

string

nlbSslSecretName

string

nlbSslSecretStatus

string

nlbStatusMessage

string

nlbType

string

provider

string

secretNamespace

string

zoneID

string

Path Parameters

idOrName

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

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Remove an IP address from an NLB subdomain.

DELETE /v1/nlb-dns/clusters/{idOrName}/host/{nlbHost}/ip/{nlbIP}/remove

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.

Request

Path Parameters

idOrName

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

nlbHost

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

nlbIP

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

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List registered NLB subdomains and NLB IP addresses.

GET /v1/nlb-dns/clusters/{idOrName}/list

In a classic cluster, list NLB subdomains and the NLB IP addresses registered with the DNS provider for each subdomain.

Request

Path Parameters

idOrName

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

Query Parameters

Response

200 - Ok. A list of NLB subdomains and the NLB IPs associated with the DNS record for the subdomains is returned for this cluster.

clusterid

string

nlbHealthCheckConfigs

array

nlbHealthCheckStatus

array

nlbs

array

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create a new NLB subdomain and associate one or more NLB IP addresses with it.

POST /v1/nlb-dns/clusters/{idOrName}/register

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.

Request

Request Body

NlbConfig

Include either the `nlbIP` or the `nlbIPArray` parameter that specifies the NLB IP address(es) that you want to register.

certProvider

string

clusterID

string

crn

string

isDefault

boolean

nlbDnsType

string

nlbHost

string

nlbIPArray

array

nlbMonitorState

string

nlbSslSecretName

string

nlbSslSecretStatus

string

nlbStatusMessage

string

nlbType

string

provider

string

secretNamespace

string

zoneID

string

Path Parameters

idOrName

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

Query Parameters

Response

201 - Created. The NLB subdomain was successfully created and the NLB IP addres(es) registered with DNS.

certProvider

string

clusterID

string

crn

string

isDefault

boolean

nlbDnsType

string

nlbHost

string

nlbIPArray

array

nlbMonitorState

string

nlbSslSecretName

string

nlbSslSecretStatus

string

nlbStatusMessage

string

nlbType

string

provider

string

secretNamespace

string

zoneID

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Configure a health check monitor for an NLB subdomain.

PATCH /v1/nlb-dns/health/clusters/{idOrName}/config

Create and optionally enable a health check monitor for an existing NLB subdomain in a cluster.

Request

Request Body

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

allowInsecureSet

string

clusterID

string

createdOn

string

desc

string

followRedirectSet

string

healtcheckPropertiesSetStatus

string

healthcheckProperties

object

modifiedOn

string

monitorState

string

nlbHost

string

Path Parameters

idOrName

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

Query Parameters

Response

201 - Created. The health check monitor was successfully configured for the NLB subdomain.

allowInsecureSet

string

clusterID

string

createdOn

string

desc

string

followRedirectSet

string

healtcheckPropertiesSetStatus

string

healthcheckProperties

HealthcheckProperties

HealthcheckProperties used for storing config provided by user for healthcheck deprecated

modifiedOn

string

monitorState

string

nlbHost

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View the health check monitor settings for an NLB subdomain.

GET /v1/nlb-dns/health/clusters/{idOrName}/host/{nlbHost}/config

View the health check monitor settings for an NLB subdomain.

Request

Path Parameters

idOrName

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

nlbHost

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

Query Parameters

Response

200 - Ok. Health check monitor settings for the specified NLB subdomain are returned.

allowInsecureSet

string

clusterID

string

createdOn

string

desc

string

followRedirectSet

string

healtcheckPropertiesSetStatus

string

healthcheckProperties

HealthcheckProperties

HealthcheckProperties used for storing config provided by user for healthcheck deprecated

modifiedOn

string

monitorState

string

nlbHost

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List the health check monitor settings for all NLB subdomains.

GET /v1/nlb-dns/health/clusters/{idOrName}/list

List the settings for all existing health check monitors in a cluster.

Request

Path Parameters

idOrName

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

Query Parameters

Response

200 - Ok. The health check monitor settings for each NLB subdomain in the cluster are returned.

clusterid

string

nlbHealthCheckConfigs

array

nlbHealthCheckStatus

array

nlbs

array

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Deprecated: List the health check status for the IPs behind NLB subdomains in a cluster.

GET /v1/nlb-dns/health/clusters/{idOrName}/status

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.

Request

Path Parameters

idOrName

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

Query Parameters

Response

200 - Ok. An array that contains the NlbHealthCheckStatus is returned.

clusterid

string

nlbHealthCheckConfigs

array

nlbHealthCheckStatus

array

nlbs

array

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

GET /v1/prodconfig

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

No IBM Cloud IAM role is required for this operation.

  • ``

Auditing

Calling this method generates the following auditing event.

  • ``

Request

Response

200 - Success

company_name

string

container_service_name

string

iaas_name

string

product_name

string

product_name_short

string

Deprecated: List available Kubernetes Service regions.

GET /v1/regions

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

No IBM Cloud IAM role is required for this operation.

  • ``

Auditing

Calling this method generates the following auditing event.

  • ``

Request

Path Parameters

Query Parameters

Response

200 - Success

regions

array

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List available IBM Cloud classic infrastructure subnets.

GET /v1/subnets

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-subnet.list

Request

Path Parameters

Query Parameters

datacenters

string

A comma seperated list of datacenters to filter subnets based off of.

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View the VLAN spanning status.

GET /v1/subnets/vlan-spanning

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-subnet-vlan-spanning.get

Request

Path Parameters

Query Parameters

Response

200 - Ok. Details of VLAN spanning enablement.

enabled

boolean

modifiedDate

string

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Unable to determine whether VLAN spanning is enabled in the IBM Cloud infrastructure account.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View a user's ability to create free and standard clusters in a region and resource group.

GET /v1/user-config

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-user-config.get

Request

Path Parameters

Query Parameters

Response

200 - Ok. The user's permissions to create free and paid clusters is returned.

freeEnabled

boolean

storedIaasCredentials

boolean

List available IBM Cloud Kubernetes Service versions.

GET /v1/versions

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • ``

Request

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List available zones (data centers).

GET /v1/zones

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

No IBM Cloud IAM role is required for this operation.

  • ``

Auditing

Calling this method generates the following auditing event.

  • ``

Request

Path Parameters

Query Parameters

showFlavors

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

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Ignore specific ingress status errors in ingress status reporting.

POST /v2/alb/addIgnoredIngressStatusErrors

Ignore specific ingress status errors in ingress status reporting. Ignored errors will not affect the cluster's ingress status state.

Request

Request Body

IgnoredIngressStatusErrors

Ingress status errors that are ignored for ingress status reporting.

cluster

string

ignoredErrors

array

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details of an ALB.

GET /v2/alb/getAlb

View detailed information for an ALB in a VPC or classic cluster. An `ALBConfig` response will be returned for ALBs in classic clusters.

Request

Path Parameters

Query Parameters

albID

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

Response

200 - Ok. Details for the specified ALB are returned.

albBuild

string

The build number of the ALB.

albID

string

The ID of the application load balancer (ALB).

albType

string

The type of ALB.

authBuild

string

The auth build of the ALB.

cluster

string

createdDate

string

The date the ALB was created.

disableDeployment

boolean

If set to true, the deployment of the ALB is disabled.

enable

boolean

Set to true to enable the ALB, or false to disable the ALB for the cluster.

loadBalancerHostname

string

name

string

The name of the cluster that the ALB belongs to.

numOfInstances

string

Desired number of ALB replicas that you want in your cluster.

resize

boolean

If set to true, resizing of the ALB is done.

state

string

The state of the ALB.

status

string

The status of the ALB.

zone

string

The zone where you want to add ALBs.

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List supported Ingress controller images.

GET /v2/alb/getAlbImages

List the community Kubernetes Ingress controller and IBM Cloud Kubernetes Service ALB images that are supported.

Request

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List all ALBs in a cluster.

GET /v2/alb/getClusterAlbs

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.

Request

Path Parameters

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

Response

200 - Ok. A list of ALBs for the cluster is returned.

alb

array

PrivateIngressHostname string `json:"privateIngressHostname"` PrivateIngressSecretName string `json:"privateIngressSecretName"`

dataCenter

string

id

string

ingressHostname

string

ingressSecretName

string

isPaid

boolean

region

string

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get the status of the in-cluster ALB health checker.

GET /v2/alb/getIngressClusterHealthcheck

Check the status of the in-cluster ALB health checker.

Request

Path Parameters

Query Parameters

cluster

Required *

string

The name or ID of the cluster.

Response

200 - Ok. The in-cluster ALB health checker status for your cluster is returned.

cluster

string

enable

boolean

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get the status of the ingress resources in a cluster.

GET /v2/alb/getStatus

Check the status of the IBM provided subdomain and application load balancers

Request

Path Parameters

Query Parameters

cluster

Required *

string

The name or ID of the cluster that you want information about.

Response

200 - Ok. The ingress status for your cluster is returned.

StatusList

array

albStatus

array

cluster

string

enabled

boolean

generalComponentStatus

array

ignoredErrors

array

message

string

nonTranslatedStatus

string

routerStatus

array

secretStatus

array

status

string

subdomainStatus

array

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List all ingress status errors that are ignored for the cluster.

GET /v2/alb/listIgnoredIngressStatusErrors

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.

Request

Path Parameters

Query Parameters

cluster

Required *

string

The name or ID of the cluster.

Response

200 - Ok. All ignored ingress status errors for your cluster are returned.

cluster

string

ignoredErrors

array

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Unignore specific ingress status errors in ingress status reporting.

DELETE /v2/alb/removeIgnoredIngressStatusErrors

Unignore specific ingress status errors in ingress status reporting. Unignored errors will affect the cluster's ingress status state.

Request

Request Body

IgnoredIngressStatusErrors

Ingress status errors that are ignored for ingress status reporting.

cluster

string

ignoredErrors

array

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Set the in-cluster ingress health checker.

POST /v2/alb/setIngressClusterHealthcheck

Set the in-cluster ingress health checker state. It can be either enabled or disabled.

Request

Request Body

ALBClusterHealthCheckConfig

The desired state of the in-cluster ingress health checker.

cluster

string

enable

boolean

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Set the state of the ingress status.

POST /v2/alb/setIngressStatusState

Set the state of the ingress status for a cluster. It can be either enabled or disabled.

Request

Request Body

StatusState

The desired state of ingress status.

cluster

string

enable

boolean

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster could not be found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Update ALBs in a cluster.

POST /v2/alb/updateAlb

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.

Request

Request Body

V2UpdateALB

The input parameter to update an ALB's image. To see the supported image versions, use the `GET ​/v2​/alb​/getAlbImages` call.

albBuild

string

albList

array

cluster

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified cluster or ALB could not be found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create a public or private ALB in a specified zone and VPC cluster.

POST /v2/alb/vpc/createAlb

Create a new public or private ALB in a specified zone and VPC cluster.

Request

Request Body

ALB

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

enableByDefault

boolean

If set to true, the ALB is enabled by default. \

ingressImage

string

The type of Ingress image that you want to use for your ALB deployment.

ip

string

Optional: The IP address that you want to assign to the ALB.

nlbVersion

string

The version of the network load balancer that you want to use for the ALB.

type

string

The type of ALB that you want to create.

vlanID

string

The VLAN ID that you want to use for your ALBs.

zone

string

The zone where you want to deploy the ALB.

Path Parameters

Query Parameters

Response

201 - The ALB was successfully created.

alb

string

cluster

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Disable an ALB in your VPC cluster.

POST /v2/alb/vpc/disableAlb

Disable a public or private ALB in your VPC cluster.

Request

Request Body

ALBConfig

The input parameters to disable an ALB. DisableDeployment and albID are required. For more information, see https://ibm.biz/alb_configure_vpc

albBuild

string

The build number of the ALB.

albID

string

The ID of the application load balancer (ALB).

albType

string

The type of ALB.

authBuild

string

The auth build of the ALB.

cluster

string

createdDate

string

The date the ALB was created.

disableDeployment

boolean

If set to true, the deployment of the ALB is disabled.

enable

boolean

Set to true to enable the ALB, or false to disable the ALB for the cluster.

loadBalancerHostname

string

name

string

The name of the cluster that the ALB belongs to.

numOfInstances

string

Desired number of ALB replicas that you want in your cluster.

resize

boolean

If set to true, resizing of the ALB is done.

state

string

The state of the ALB.

status

string

The status of the ALB.

zone

string

The zone where you want to add ALBs.

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Enable an existing ALB in a VPC cluster.

POST /v2/alb/vpc/enableAlb

Enable a public or private ALB in your VPC cluster.

Request

Request Body

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

albBuild

string

The build number of the ALB.

albID

string

The ID of the application load balancer (ALB).

albType

string

The type of ALB.

authBuild

string

The auth build of the ALB.

cluster

string

createdDate

string

The date the ALB was created.

disableDeployment

boolean

If set to true, the deployment of the ALB is disabled.

enable

boolean

Set to true to enable the ALB, or false to disable the ALB for the cluster.

loadBalancerHostname

string

name

string

The name of the cluster that the ALB belongs to.

numOfInstances

string

Desired number of ALB replicas that you want in your cluster.

resize

boolean

If set to true, resizing of the ALB is done.

state

string

The state of the ALB.

status

string

The status of the ALB.

zone

string

The zone where you want to add ALBs.

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Start applying IAM roles corresponding to your access to the cluster.

POST /v2/applyRBAC

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster.config

Request

Request Body

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.

admin

boolean

AdminUser Retrieve the admin kubeconfig file.

cluster

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

endpointType

string

EndpointType The type of endpoint server URL to return in the kubeconfig. Supported values are 'default', 'private', 'vpe', 'link', 'vpc'. The 'default' endpoint returns the public endpoint when available, and the private endpoint otherwise. Default is 'default'.

format

string

Format Default format is json. Other options include yaml, and zip.

network

boolean

NetworkConfig Retrieve the Calico network config. Requires admin=true and format=zip.

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Start applying IAM roles corresponding to your access to the cluster, then retrieve the cluster's kubeconfig file.

POST /v2/applyRBACAndGetKubeconfig

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster.config

Request

Request Body

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.

admin

boolean

AdminUser Retrieve the admin kubeconfig file.

cluster

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

endpointType

string

EndpointType The type of endpoint server URL to return in the kubeconfig. Supported values are 'default', 'private', 'vpe', 'link', 'vpc'. The 'default' endpoint returns the public endpoint when available, and the private endpoint otherwise. Default is 'default'.

format

string

Format Default format is json. Other options include yaml, and zip.

network

boolean

NetworkConfig Retrieve the Calico network config. Requires admin=true and format=zip.

Path Parameters

Query Parameters

Response

200 - Ok. Returns the cluster's kubeconfig file.

apiVersion

string

Legacy field from pkg/api/types.go TypeMeta.

clusters

array

Clusters is a map of referencable names to cluster configs

contexts

array

Contexts is a map of referencable names to context configs

current-context

string

CurrentContext is the name of the context that you would like to use by default

kind

string

Legacy field from pkg/api/types.go TypeMeta.

preferences

object

Preferences holds general information to be use for cli interactions

users

array

AuthInfos is a map of referencable names to user configs

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Set the autoupdate status of the cluster master.

POST /v2/autoUpdateMaster

Set the autoupdate status of the cluster master. Only a limited set of users can access use this API.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-master-autoupdate.enable
  • containers-kubernetes.cluster-master-autoupdate.disable

Request

Request Body

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

autoUpdate

boolean

cluster

string

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The user doesn't have access to this API.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Detailed cluster information.

GET /v2/classic/getCluster

Detailed cluster information.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster.get

Request

Path Parameters

Query Parameters

showResources

string

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

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

Response

200 - Success. Detailed cluster information.

addons

array

caCertRotationStatus

CommonClusterCACertRotation

CommonClusterCACertRotation CA cert rotation properties

calicoIPAutodetectionConfig

string

createdDate

string

crn

string

datacenter

string

desiredTrustedProfileID

string

disableAutoUpdate

boolean

entitlement

string

etcdPort

string

features

CommonClusterFeatures

id

string

ignitionServerURL

string

imageSecurityEnabled

boolean

ingress

CommonClusterIngress

isPaid

boolean

keyManagementService

CommonClusterKMS

konnectivityServerURL

string

lifecycle

CommonClusterLifecycle

location

string

locationZones

array

masterKubeVersion

string

masterURL

string

monitoringURL

string

multiAzCapable

boolean

name

string

oauthServerURL

string

offering

string

podSubnet

string

provider

string

region

string

resourceGroup

string

resourceGroupName

string

secureRequested

boolean

serviceEndpoints

CommonClusterServiceEndpoint

serviceSubnet

string

state

string

The lifecycle state of the cluster. Possible values include aborted, critical, delete_failed, deleted, deleting, deploy_failed, deploying, normal, pending, requested, updating, unsupported, and warning. For more information, see the docs 'http://ibm.biz/cluster-health-states'

status

string

supportedOperatingSystems

array

targetVersion

string

trustedProfileID

string

type

string

versionEOS

string

vlans

array

workerCount

integer

workerZones

array

worker_vlans

VLANS

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.

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List the classic clusters that you have access to.

GET /v2/classic/getClusters

List the classic clusters that you have access to.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster.list

Request

Path Parameters

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

showResources

string

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

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get if VRF and Service Endpoint is enabled for the given account in the selected region.

GET /v2/classic/getPrivateServiceEnabled

Get if VRF and Service Endpoint is enabled for the given account in the selected region.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool.get

Request

Path Parameters

Query Parameters

Response

200 - Ok. Detailed information about the private service enablement.

isPrivateServiceEnabled

boolean

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List available classic infrastructure VLANs for a zone.

GET /v2/classic/getVLANs

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-datacenter-vlan.list

Request

Path Parameters

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.

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the infrastructure provider.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details of a worker node for classic cluster.

GET /v2/classic/getWorker

View detailed information for a worker node in a classic cluster.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.worker.get

Request

Path Parameters

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

Response

200 - Ok. Detailed information about the worker node is returned.

dedicatedHostId

string

dedicatedHostPoolId

string

flavor

string

health

GetWorkerResponseHealth

id

string

kubeVersion

GetWorkerResponseKubeVersion

lifecycle

GetWorkerResponseLifecycle

location

string

networkInformation

GetWorkerResponseNetworkInformation

poolID

string

poolName

string

provider

string

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details of a worker pool for a classic cluster.

GET /v2/classic/getWorkerPool

View detailed information for a worker pool in a classic cluster.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool.list

Request

Path Parameters

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

Response

200 - Ok. Detailed information about the worker pool is returned.

autoscaleEnabled

boolean

dedicatedHostPoolId

string

flavor

string

flavorState

string

hostLabels

object

id

string

isBalanced

boolean

isolation

string

labels

object

lifecycle

GetWorkerPoolResponseLifecycle

openshiftLicense

string

operatingSystem

string

poolName

string

provider

string

reservationID

string

reservationName

string

taints

object

workerCount

integer

zones

array

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details of a worker pool for a classic cluster.

GET /v2/classic/getWorkerPools

View detailed information for a worker pool in a classic cluster.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool.get

Request

Path Parameters

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

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View all workers for a classic cluster.

GET /v2/classic/getWorkers

View detailed information for all worker nodes in a classic cluster.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker.list

Request

Path Parameters

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

showDeleted

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

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get detailed information for one health issue (regional URL prefix).

GET /v2/cluster-health/getIssue

Same behavior as `GET /v2/cluster-health/getIssue`.

Request

Path Parameters

Query Parameters

cluster

Required *

string

Cluster ID or name.

issue

Required *

string

Issue code.

Response

200 - Success. Detailed health issue payload.

component

string

description

string

detected

string

id

string

more_details

array

severity

string

solution

string

400 - Bad request.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

410 - Gone.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

500 - Internal Server Error.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List aggregated health issues for a cluster (regional URL prefix).

GET /v2/cluster-health/getIssues

Same behavior as `GET /v2/cluster-health/getIssues`. Use this path when calling a regional Kubernetes Service endpoint directly.

Request

Path Parameters

Query Parameters

cluster

Required *

string

Cluster ID or name.

Response

200 - Success. An array of health issue summaries.

400 - Bad request.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

410 - Gone.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

500 - Internal Server Error.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create a dedicated host.

POST /v2/createDedicatedHost

Create a dedicated host.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To create a dedicated host, you must have the Administrator platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.account-dedicated-host.create

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-dedicated-host.create

Request

Request Body

CreateDedicatedHost

The required dedicated host parameters.

flavor

string

hostPoolID

string

zone

string

Path Parameters

Query Parameters

Response

201 - Created. The dedicated host was successfully created.

id

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

409 - Conflict. A dedicated host create may already be in progress. Please wait a few minutes and try again.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create a dedicated host pool.

POST /v2/createDedicatedHostPool

Create a dedicated host pool.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To create a dedicated host pool, you must have the Administrator platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.account-dedicated-host-pool.create

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-dedicated-host-pool.create

Request

Request Body

CreateDedicatedHostPool

The required dedicated host pool parameters.

flavorClass

string

metro

string

name

string

Path Parameters

Query Parameters

Response

201 - Created. The dedicated host pool was successfully created.

id

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

409 - Conflict. Creation of a dedicated host might already be in progress. Please wait a few minutes and try again.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Disable dedicated host placement.

POST /v2/disableDedicatedHostPlacement

Disable placement of worker nodes on a dedicated host.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To disable dedicated host placement, you must have the Administrator platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.account-dedicated-host-placement.disable

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-dedicated-host-placement.disable

Request

Request Body

UpdateDedicatedHost

The dedicated host pool and host to disable placement on.

hostID

string

hostPoolID

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

POST /v2/disableImageSecurity

Disable image security enforcement for a cluster

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Request

Request Body

ImageSecurity

Input parameters to specify the name or ID of the cluster that you want to disable image security enforcement in.

cluster

string

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Deprecated: Disable the Pod Security Policy admission controller.

POST /v2/disablePodSecurityPolicy

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To change the Pod Security Policy admission controller configuration, you must have the Administrator platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-pod-security.disable

Request

Request Body

DisablePodSecurityPolicyRequest

The cluster to target.

cluster

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Disables a private service endpoint for a cluster.

POST /v2/disablePrivateServiceEndpoint

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-private-service-endpoint.disable

Request

Request Body

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.

cluster

string

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Disables a public service endpoint for a cluster.

POST /v2/disablePublicServiceEndpoint

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-public-service-endpoint.disable

Request

Request Body

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.

cluster

string

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Enable dedicated host placement.

POST /v2/enableDedicatedHostPlacement

Enable placement of worker nodes on a dedicated host.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To enable dedicated host placement, you must have the Administrator platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.account-dedicated-host-placement.enable

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-dedicated-host-placement.enable

Request

Request Body

UpdateDedicatedHost

The dedicated host pool and host to enable placement on.

hostID

string

hostPoolID

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

POST /v2/enableImageSecurity

Enable image security enforcement for a cluster

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Request

Request Body

ImageSecurity

Input parameters to specify the name or ID of the cluster that you want to enable image security enforcement in.

cluster

string

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Enables KMS in a cluster

POST /v2/enableKMS

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-kms.enable

Request

Request Body

EnableKMSRequest

Input parameters to create the Key Protect config for your cluster.

account_id

string

cluster

string

crk_id

string

instance_id

string

private_endpoint

boolean

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Deprecated: Enable the Pod Security Policy admission controller.

POST /v2/enablePodSecurityPolicy

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To change the Pod Security Policy admission controller configuration, you must have the Administrator platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-pod-security-policy.enable

Request

Request Body

EnablePodSecurityPolicyRequest

The cluster to target.

cluster

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Enables the private service endpoint for a cluster.

POST /v2/enablePrivateServiceEndpoint

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-private-service-endpoint.enable

Request

Request Body

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.

cluster

string

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Enables the public service endpoint for a cluster.

POST /v2/enablePublicServiceEndpoint

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-public-service-endpoint.enable

Request

Request Body

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.

cluster

string

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create an image pull secret to IBM Cloud Container Registry in the `default` namespace of the cluster. Note that this API method also requires the Administrator platform role to IBM Cloud Container Registry.

POST /v2/enablePullSecret

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service and Administrator platform role to Container Registry in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-pull-secret.enable

Request

Request Body

EnablePullSecret

Input parameters to specify the name or ID of the cluster and which to enable pull secrets for.

cluster

string

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get the cluster's CA cert.

GET /v2/getCACert

Get the cluster's CA cert to configure services with it to connect to the given cluster.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-ca-certificate.get

Request

Path Parameters

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

Response

200 - Ok. Returns the cluster's CA cert.

400 - Bad request. The query parameters are either incomplete or in the wrong format.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List the root keys for a Key Management Service instance.

GET /v2/getCRKs

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-customer-root-key.list

Request

Path Parameters

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

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details for a cluster.

GET /v2/getCluster

View detailed information for a cluster, including a VPC cluster.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster.get

Request

Path Parameters

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

Response

200 - Success. Detailed cluster information is returned.

addons

array

caCertRotationStatus

CommonClusterCACertRotation

CommonClusterCACertRotation CA cert rotation properties

calicoIPAutodetectionConfig

string

createdDate

string

crn

string

datacenter

string

desiredTrustedProfileID

string

disableAutoUpdate

boolean

entitlement

string

etcdPort

string

features

CommonClusterFeatures

id

string

ignitionServerURL

string

imageSecurityEnabled

boolean

ingress

CommonClusterIngress

isPaid

boolean

keyManagementService

CommonClusterKMS

konnectivityServerURL

string

lifecycle

CommonClusterLifecycle

location

string

locationZones

array

masterKubeVersion

string

masterURL

string

monitoringURL

string

multiAzCapable

boolean

name

string

oauthServerURL

string

offering

string

podSubnet

string

provider

string

region

string

resourceGroup

string

resourceGroupName

string

secureRequested

boolean

serviceEndpoints

CommonClusterServiceEndpoint

serviceSubnet

string

state

string

The lifecycle state of the cluster. Possible values include aborted, critical, delete_failed, deleted, deleting, deploy_failed, deploying, normal, pending, requested, updating, unsupported, and warning. For more information, see the docs 'http://ibm.biz/cluster-health-states'

status

string

supportedOperatingSystems

array

targetVersion

string

trustedProfileID

string

type

string

versionEOS

string

vlans

array

workerCount

integer

workerZones

array

worker_vlans

VLANS

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.

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details of the add-ons that are enabled in a cluster.

GET /v2/getClusterAddons

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-addon.list

Request

Path Parameters

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

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details of a dedicated host.

GET /v2/getDedicatedHost

View detailed information for a dedicated host.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To view the details of a dedicated host, you must have the Viewer platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.account.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-dedicated-host.get

Request

Path Parameters

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.

Response

200 - Ok. Detailed information about the dedicated host is returned.

flavor

string

id

string

lifecycle

DedicatedHostLifecycle

placementEnabled

boolean

resources

DedicatedHostResources

workers

array

zone

string

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified dedicated host could not be found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details of a dedicated host pool.

GET /v2/getDedicatedHostPool

View detailed information for a dedicated host pool.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To view the details of a dedicated host pool, the user must have the Viewer platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.account.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-dedicated-host-pool.get

Request

Path Parameters

Query Parameters

dedicatedhostpool

Required *

string

The ID of the dedicated host pool that you want to get.

Response

200 - Ok. Detailed information about the dedicated host pool is returned.

flavorClass

string

hostCount

integer

id

string

metro

string

name

string

state

string

workerPools

array

zones

array

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified dedicated host could not be found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List the dedicated host pools.

GET /v2/getDedicatedHostPools

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To list dedicated host pools, you must have the Viewer platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.account.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-dedicated-host-pool.list

Request

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified dedicated host pool could not be found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List the dedicated hosts.

GET /v2/getDedicatedHosts

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To list dedicated hosts, you must have the Viewer platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.account.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-dedicated-host.list

Request

Path Parameters

Query Parameters

dedicatedhostpool

Required *

string

The ID of the dedicated host pool that you want to get the dedicated hosts details from.

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found. The specified dedicated host pool could not be found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get the details for a worker node flavor

GET /v2/getFlavor

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

No IBM Cloud IAM role is required for this operation.

  • ``

Auditing

Calling this method generates the following auditing event.

  • ``

Request

Path Parameters

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.

Response

200 - Success

architecture

string

The type of CPU architecture that the flavor uses.

correspondingFlavor

string

deprecated

boolean

id

string

The ID of the worker node flavor.

isTrusted

boolean

name

string

The name of the worker node flavor.

provider

string

The name of the provider.

secondaryStorage

string

secondaryStorageEncrypted

boolean

storage

string

400 - The specified zone is invalid. To list available zones, run `ibmcloud ks zone ls` or use the `GET /v2/zones` API.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List available flavors types for a VPC zone (data center).

GET /v2/getFlavors

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

No IBM Cloud IAM role is required for this operation.

  • ``

Auditing

Calling this method generates the following auditing event.

  • ``

Request

Path Parameters

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.

Response

200 - Success

400 - The specified location is invalid. To list available locations, run `ibmcloud ks zone ls` or use the `GET /v2/zones` API.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Gets KMS instances tied to an account

GET /v2/getKMSInstances

Retrieves available key management service (KMS) instances, such as Key Protect, in your IBM Cloud Account

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-key-management-service-instance.list

Request

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get the cluster's kubeconfig file.

GET /v2/getKubeconfig

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM. Note that to pull the networking or admin configuration files, you must have the Administrator platform role.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-config.get

Request

Path Parameters

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

endpointType

string

The type of endpoint server URL to return in the kubeconfig. Supported values are 'default', 'private', 'vpe', 'link', 'vpc'. Default is 'default'.

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.

Response

200 - Ok. Returns the cluster's kubeconfig file.

apiVersion

string

Legacy field from pkg/api/types.go TypeMeta.

clusters

array

Clusters is a map of referencable names to cluster configs

contexts

array

Contexts is a map of referencable names to context configs

current-context

string

CurrentContext is the name of the context that you would like to use by default

kind

string

Legacy field from pkg/api/types.go TypeMeta.

preferences

object

Preferences holds general information to be use for cli interactions

users

array

AuthInfos is a map of referencable names to user configs

400 - Bad request. The query parameters are either incomplete or in the wrong format.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View the current messages.

GET /v2/getMessages

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

No IBM Cloud IAM role is required for this operation.

  • ``

Auditing

Calling this method generates the following auditing event.

  • ``

Request

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List supported operating systems.

GET /v2/getOperatingSystems

Lists supported operating systems for the given configuration.

Auditing

Calling this method generates the following auditing event.

  • cluster-worker-pool-supported-operating-systems.get

Request

Path Parameters

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.

coreOSEnabled

boolean

Whether HyperShift is enabled.

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View the Pod Security admission control configuration for a cluster.

GET /v2/getPodSecurity

View the Pod Security admission control configuration for a cluster.

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-pod-security.get

Request

Path Parameters

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

Response

200 - Ok. The request to view the Pod Security admission control configuration was successfully processed.

configuration

string

Configuration is a base64 encoded PodSecurityConfiguration yaml definition

enabled

boolean

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Deprecated: View the Pod Security Policy admission control configuration.

GET /v2/getPodSecurityPolicy

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.

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-pod-security-policy.get

Request

Path Parameters

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

Response

200 - Ok. The request to view Pod Security Policy admission control configuration was successfully processed.

enabled

boolean

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View the quota for resources per region in the account.

GET /v2/getQuota

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-quota.get

Request

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get the RBACSync status.

GET /v2/getRBACStatus

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the RBACSync status, you must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-rbac.status

Request

Path Parameters

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

Response

200 - Success

synchronized

boolean

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List available cluster versions.

GET /v2/getVersions

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • ``

Request

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details of a worker node for cluster.

GET /v2/getWorker

View detailed information for a worker node in a cluster.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.worker.get

Request

Path Parameters

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

Response

200 - Ok. Detailed information about the worker node is returned.

dedicatedHostId

string

dedicatedHostPoolId

string

flavor

string

health

GetWorkerResponseHealth

id

string

kubeVersion

GetWorkerResponseKubeVersion

lifecycle

GetWorkerResponseLifecycle

location

string

networkInformation

GetWorkerResponseNetworkInformation

networkInterfaces

GetWorkerResponseNetworkInterfaces

poolID

string

poolName

string

provider

string

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details of a worker pool for a cluster.

GET /v2/getWorkerPool

View detailed information for a worker pool in a cluster.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool.get

Request

Path Parameters

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

Response

200 - Ok. Detailed information about the worker pool is returned.

autoscaleEnabled

boolean

dedicatedHostPoolId

string

flavor

string

flavorState

string

hostLabels

object

id

string

isBalanced

boolean

isolation

string

labels

object

lifecycle

GetWorkerPoolResponseLifecycle

openshiftLicense

string

operatingSystem

string

poolName

string

provider

string

reservationID

string

reservationName

string

secondaryStorageOption

DiskConfigResp

DiskConfigResp response type for describing a disk configuration

staticNetworkInterfaceCount

integer

taints

object

vpcID

string

workerCount

integer

workerVolumeEncryption

WorkerVolumeEncryption

WorkerVolumeEncryption contains encryption related fields

zones

array

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List the worker pools in a cluster.

GET /v2/getWorkerPools

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool.list

Request

Path Parameters

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

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View all workers for cluster.

GET /v2/getWorkers

View detailed information for all worker nodes in a cluster.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker.list

Request

Path Parameters

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

showDeleted

string

true|false Shows deleted workers

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Validates user provided entitlement.

GET /v2/hasValidEntitlement

Validates whether the provided entitlement value is supported or not.

Auditing

Calling this method generates the following auditing event.

  • account-has-valid-entitlement.get

Request

Path Parameters

Query Parameters

entitlement

Required *

string

The entitlement value to check if it is supported.

Response

200 - Ok. The entitlement validation request was successfully processed.

hasValidEntitlement

boolean

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

500 - Could not connect to the back-end billing validation service. Try again later.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Update the health monitoring configuration for the specified NLB subdomain in a cluster.

PUT /v2/nlb-dns/configureHealthMonitor

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To call this endpoint, you must have the Editor platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

  • cluster-nlb-dns-monitor.create

Request

Request Body

HealthMonitorConfiguration

The full health monitoring configuration to overwrite the current configuration with. The configuration is defined in the corresponding provider specific field.

akamaiMonitorConfiguration

AkamaiHealthcheckProperties

AkamaiHealthcheckProperties used for storing config provided by user for akamai healthcheck deprecated

httpError3xx

boolean

httpError4xx

boolean

httpError5xx

boolean

httpHeaders

array

httpMethod

string

name

string

peerCertificateVerification

boolean

testInterval

integer

testObject

string

testObjectPort

integer

testObjectProtocol

string

testTimeout

number

cluster

string

nlbSubdomain

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Remove a secret from an NLB subdomain.

POST /v2/nlb-dns/deleteSecret

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.

Request

Request Body

SecretConfig

Include the NLB subdomain that you want to delete the secret for, and the cluster that the subdomain is in.

cluster

string

subdomain

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get the health monitoring configuration for the specified NLB subdomain in a cluster.

GET /v2/nlb-dns/getHealthMonitorConfig

Get the health monitoring configuration for the specified NLB subdomain in a cluster.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To call this endpoint, you must have the Viewer platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

  • cluster-nlb-dns-monitor.get

Request

Path Parameters

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

nlbSubdomain

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

Response

200 - OK. Current monitor config returned.

akamaiMonitorConfiguration

AkamaiHealthcheckProperties

AkamaiHealthcheckProperties used for storing config provided by user for akamai healthcheck deprecated

cluster

string

nlbSubdomain

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List registered NLB subdomains in a cluster.

GET /v2/nlb-dns/getNlbDNSList

List NLB subdomains and the NLB IP addresses or the load balancer hostnames that are registered with the DNS provider for each NLB subdomain.

Request

Path Parameters

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

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get the details for the specified NLB subdomain in a cluster.

GET /v2/nlb-dns/getNlbDetails

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.

Request

Path Parameters

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

nlbSubdomain

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

Response

200 - OK. Details of the NLB subdomain are returned.

Nlb

ExtendedNlbVPCConfig

ExtendedNlbVPCConfig is the response body for the get v2 vpc apis

secretName

string

secretStatus

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get the details for the specified subdomain in a Satellite location.

GET /v2/nlb-dns/getSatLocationSubdomain

Get the details for the subdomain and the IP addresses that are registered with the DNS provider for each subdomain.

Request

Path Parameters

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

Response

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.

certProvider

string

clusterID

string

crn

string

isDefault

boolean

nlbDnsType

string

nlbHost

string

nlbIPArray

array

nlbMonitorState

string

nlbSslSecretName

string

nlbSslSecretStatus

string

nlbStatusMessage

string

nlbType

string

provider

string

secretNamespace

string

zoneID

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List registered NLB subdomains in a Satellite location.

GET /v2/nlb-dns/getSatLocationSubdomains

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.

Request

Path Parameters

Query Parameters

controller

Required *

string

To list available locations, use the `GET /v2/satellite/getControllers` API, or run `ibmcloud sat location ls`.

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Regenerates cert for secret.

POST /v2/nlb-dns/regenerateCert

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.

Request

Request Body

SecretConfig

Include the cluster and subdomain for the NLB subdomain that you want to remove the secret from.

cluster

string

subdomain

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Registers domains: c001, c002, c003, each tied to a corresponding IP and c000 tied to all of the IPs for the cluster. Also registers 1 cname, ce00, for the specified multishift cluster

POST /v2/nlb-dns/registerMSCDomains

Registers Multishift domains for a cluster.

Request

Request Body

MSCRegistration

The input parameter to register a Multishift cluster's domains.

controller

string

ips

array

Path Parameters

Query Parameters

Response

200 - Registered. The multishift cluster domains and cname have been successfully registered.

controller

string

dnsRegistrations

array

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create a new NLB subdomain in a VPC cluster and associate a load balancer hostname with it.

POST /v2/nlb-dns/vpc/createNlbDNS

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.

Request

Request Body

NlbVPCConfig

Include the `lbHostname` parameter that specifies the VPC load balancer hostname that you want to register.

cluster

string

dnsType

string

lbHostname

string

nlbSubdomain

string

secretNamespace

string

type

string

Path Parameters

Query Parameters

Response

201 - Created. The NLB subdomain was successfully created and the VPC load balancer hostname is registered with DNS.

cluster

string

dnsType

string

lbHostname

string

nlbSubdomain

string

secretNamespace

string

type

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Remove the load balancer hostname from the DNS record for an existing NLB subdomain.

POST /v2/nlb-dns/vpc/removeLBHostname

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.

Request

Request Body

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.

cluster

string

dnsType

string

lbHostname

string

nlbSubdomain

string

secretNamespace

string

type

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Update the DNS record for an NLB subdomain by replacing the load balancer hostname.

POST /v2/nlb-dns/vpc/replaceLBHostname

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.

Request

Request Body

NlbVPCConfig

Include only the `cluster` ID, existing `lbHostname` that you want to replace, and `nlbSubdomain` of the DNS record that you want to update.

cluster

string

dnsType

string

lbHostname

string

nlbSubdomain

string

secretNamespace

string

type

string

Path Parameters

Query Parameters

Response

200 - Ok. The request to update the load balancer hostname was successfully processed.

cluster

string

dnsType

string

lbHostname

string

nlbSubdomain

string

secretNamespace

string

type

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Rebalance workers in a worker pool.

POST /v2/rebalanceWorkerPool

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.workerpool.rebalance

Request

Request Body

RebalanceWorkerPool

Fields required to rebalance the worker pool.

cluster

string

workerpool

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Refresh the Kubernetes master.

POST /v2/refreshMaster

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-master.refresh

Request

Request Body

RefreshMaster

Input parameters to refresh master. The cluster ID or name is required.

cluster

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Removes a dedicated host.

POST /v2/removeDedicatedHost

Removes a dedicated host.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To remove a dedicated host, you must have the Administrator platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.account-dedicated-host.delete

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-dedicated-host.delete

Request

Request Body

DeleteDedicatedHost

The dedicated host to target in a given dedicated host pool.

host

string

hostPool

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Removes a dedicated host pool.

POST /v2/removeDedicatedHostPool

Removes a dedicated host pool.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To remove a dedicated host pool, you must have the Administrator platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.account-dedicated-host-pool.delete

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-dedicated-host-pool.delete

Request

Request Body

RemoveDedicatedHostPool

The dedicated host pool to target.

hostPool

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Deprecated: Remove the Pod Security admission controller configuration for Kubernetes v1.24 clusters.

POST /v2/removePodSecurity

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To change the Pod Security admission controller configuration, you must have the Administrator platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-pod-security.remove

Request

Request Body

RemovePodSecurityRequest

The cluster to target.

cluster

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Delete a worker node from a cluster.

POST /v2/removeWorker

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.worker.delete

Request

Request Body

RemoveWorker

Input parameters to remove a worker node. The cluster and worker node ID parameters are required.

cluster

string

workerID

string

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Removes a worker pool.

POST /v2/removeWorkerPool

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.workerpool.delete

Request

Request Body

RemoveWorkerPool

The cluster and worker pool to target.

allowSingleOpenShiftWorker

boolean

cluster

string

workerpool

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Remove a zone from a worker pool.

POST /v2/removeWorkerPoolZone

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.zone.delete

Request

Request Body

RemoveWorkerPoolZoneReq

The input parameter to specify the cluster, worker pool, and zone.

cluster

string

workerpool

string

zone

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Replace a worker node with a new worker node.

POST /v2/replaceWorker

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.worker.replace

Request

Request Body

ReplaceWorkerRequest

Input parameters to replace a worker.

cluster

string

update

boolean

workerID

string

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Resize an existing worker pool.

POST /v2/resizeWorkerPool

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool.resize

Request

Request Body

ResizeWorkerPool

The resize request.

allowSingleOpenShiftWorker

boolean

cluster

string

size

integer

workerpool

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Do not use it as this endpoint is not supported in the long term

GET /v2/rotateClusterCOSKey

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-cos-key.rotate

Request

Path Parameters

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

Response

204 - No Content. Indicates that the rotation was successful.

400 - Bad request. The query parameters are either incomplete or in the wrong format.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create an IBM Cloud Satellite cluster.

POST /v2/satellite/createCluster

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.

Request

Request Body

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.

adminAgentOptIn

boolean

Optional: User provided value to indicate opt-in agreement to SatCon admin agent

calicoIPAutodetection

object

Optional: Used to determine the correct IP for internal routing

controller

string

The name or ID of the Satellite location

defaultWorkerPoolEntitlement

string

Optional: The entitlement to use in the default worker pool

infrastructureTopology

string

Optional: Enables single worker node clusters

kubeVersion

string

Optional: The OpenShift Container Platform version

labels

object

Key-value pairs to label the host, such as cpu=4 to describe the host capabilities

name

string

The unique name for the new IBM Cloud Satellite cluster

networkPlugin

string

Optional: NetworkPlugin indicates what container network interface has to be used in the cluster. If the field is missing it is defaulted to Calico.

operatingSystem

string

Optional: The operating system to use in the default worker pool

podSubnet

string

Optional: User provided value for the pod subnet

pullSecret

string

Optional: The RedHat pull secret to create the OpenShift cluster

requestSecure

boolean

Optional: Flag to request a secure cluster is created

serviceSubnet

string

Optional: User provided value for service subnet

trustedProfileID

string

Optional: The trusted profile ID to set in the cluster

workerCount

integer

Optional: The number of worker nodes to create per zone in the default worker pool

zone

string

Optional: The name of the zone to create the default worker pool in

Path Parameters

Query Parameters

Response

201 - Created. The cluster was successfully created in the IBM Cloud Satellite location.

id

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

409 - Conflict. A cluster with the same name already exists. Choose another name for your cluster.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create an IBM Cloud Satellite cluster in a location that does not belong to your account.

POST /v2/satellite/createClusterRemoteLocation

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.

Request

Request Body

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.

adminAgentOptIn

boolean

Optional: User provided value to indicate opt-in agreement to SatCon admin agent

calicoIPAutodetection

object

Optional: Used to determine the correct IP for internal routing

controller

string

The name or ID of the Satellite location

defaultWorkerPoolEntitlement

string

Optional: The entitlement to use in the default worker pool

infrastructureTopology

string

Optional: Enables single worker node clusters

kubeVersion

string

Optional: The OpenShift Container Platform version

labels

object

Key-value pairs to label the host, such as cpu=4 to describe the host capabilities

name

string

The unique name for the new IBM Cloud Satellite cluster

networkPlugin

string

Optional: NetworkPlugin indicates what container network interface has to be used in the cluster. If the field is missing it is defaulted to Calico.

operatingSystem

string

Optional: The operating system to use in the default worker pool

podSubnet

string

Optional: User provided value for the pod subnet

pullSecret

string

Optional: The RedHat pull secret to create the OpenShift cluster

requestSecure

boolean

Optional: Flag to request a secure cluster is created

serviceSubnet

string

Optional: User provided value for service subnet

trustedProfileID

string

Optional: The trusted profile ID to set in the cluster

workerCount

integer

Optional: The number of worker nodes to create per zone in the default worker pool

zone

string

Optional: The name of the zone to create the default worker pool in

Path Parameters

Query Parameters

Response

201 - Created. The cluster was successfully created in the IBM Cloud Satellite location.

id

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

409 - Conflict. A cluster with the same name already exists. Choose another name for your cluster.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create an IBM Cloud Satellite location.

POST /v2/satellite/createController

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.

Request

Request Body

MultishiftCreateController

The configuration details for your Satellite location, in JSON format.

calicoIPAutodetection

object

Optional: Used to determine the correct IP for internal routing

capabilitiesManagedBySatellite

array

Satellite capabilities attached to the location

coreos_enabled

boolean

Indicates whether CoreOS features should be enabled for the location. A null value signals that the server should apply its default policy.

cos_config

COSBucket

COSBucket Optional: IBM Cloud Object Storage bucket configuration details

bucket

string

endpoint

string

region

string

serviceInstance

object

cos_credentials

COSAuthorization

COSAuthorization Optional: IBM Cloud Object Storage authorization keys

access_key-id

string

The HMAC secret access key ID

secret_access_key

string

The HMAC secret access key

description

string

A description of the new Satellite location

iaas

IAAS

credential

array

A JSON encoded credential string specific to the chosen provider

provider

string

The name of the infrastructure provider for the Satellite location, such as AWS, Azure, GCP or IBM Cloud.

region

string

The name of region in the infrastructure provider that is used for the Satellite location, such as the AWS 'us-east-2' region.

ingestion_keys

IngestionKeys

IngestionKeys Optional: Keys that can be passed in during Satellite location creation

activity_tracker_key

string

logging_key

string

location

string

The IBM Cloud metro from which the Satellite location is managed

loggingAccountID

string

The account ID for IBM Log Analysis with LogDNA log forwarding

multishiftPodSubnet

string

Optional: Used to determine the pod subnet

multishiftServiceSubnet

string

Optional: Used to determine the service subnet

name

string

A unique name for the new Satellite location

physicalAddress

string

An optional physical address of the new Satellite location which is deployed on premise

zones

array

The names of at least three high availability zones to use for the location (e.g. cloud-zone-1, cloud-zone-2, cloud-zone-3)

Path Parameters

Query Parameters

Response

201 - Created. The location was successfully created in the IBM Cloud account that you are logged in to.

crn

string

id

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

409 - Conflict. A location with the same name already exists. Choose another name for your location.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create a worker pool for an IBM Cloud Satellite cluster.

POST /v2/satellite/createWorkerPool

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.

Request

Request Body

v2SatelliteCreateWorkerPoolRequest

The configuration details for your worker pool, in JSON format.

Zones

array

cluster

string

diskEncryption

boolean

entitlement

string

flavor

string

hostLabels

object

isolation

string

labels

object

name

string

operatingSystem

string

workerCount

integer

Path Parameters

Query Parameters

Response

201 - Created. The worker pool was successfully created in the specified cluster.

workerPoolID

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

409 - Conflict. Another worker pool might be provisioning for the specified cluster. Wait a few minutes and try again.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create a zone in the specified worker pool for an IBM Cloud Satellite cluster.

POST /v2/satellite/createWorkerPoolZone

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.

Request

Request Body

SatelliteWorkerPoolZoneAdd

Input parameters to add zones to the worker pool.

cluster

string

id

string

workerpool

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

409 - Conflict. The provided zone already exists in the worker pool.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List the IBM Cloud Satellite clusters that you have access to.

GET /v2/satellite/getClusters

List the IBM Cloud Satellite clusters that you have access to.

Request

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get the details for an IBM Cloud Satellite location.

GET /v2/satellite/getController

Get the details for an IBM Cloud Satellite location.

Request

Path Parameters

Query Parameters

controller

Required *

string

The ID of the location to get information about.

Response

200 - Success. The details of the requested IBM Satellite location are returned.

activityTrackerKeyProvided

boolean

addons

array

caCertRotationStatus

CommonClusterCACertRotation

CommonClusterCACertRotation CA cert rotation properties

calicoIPAutodetectionConfig

string

capabilitiesManagedBySatellite

array

coreosEnabled

boolean

cos_config

COSBucket

COSBucket Optional: IBM Cloud Object Storage bucket configuration details

createdDate

string

crn

string

datacenter

string

deployments

Deployments

Deployments reports status of deployments on the IBM Cloud Satellite location

description

string

desiredTrustedProfileID

string

disableAutoUpdate

boolean

entitlement

string

etcdPort

string

features

CommonClusterFeatures

hostUpdateSeverity

string

HostUpdateSeverity indicates the highest update severity among all worker nodes (hosts) in this location. Possible values: "" (no update needed), warning (behind by patch/build version), critical (behind by minor version).

hosts

Hosts

Hosts lists the hosts belonging to the IBM Cloud Satellite location

iaas

IAAS

id

string

ignitionServerURL

string

ignition_server_port

integer

imageSecurityEnabled

boolean

ingress

CommonClusterIngress

isPaid

boolean

keyManagementService

CommonClusterKMS

konnectivityServerURL

string

konnectivity_server_port

integer

lifecycle

CommonClusterLifecycle

location

string

locationZones

array

logDNAKeyProvided

boolean

masterKubeVersion

string

masterURL

string

multiAzCapable

boolean

name

string

networkPlugin

string

oauthServerURL

string

offering

string

open_vpn_server_port

integer

outboundTrafficProtection

string

physicalAddress

string

podSubnet

string

provider

string

region

string

resourceGroup

string

resourceGroupName

string

secureByDefault

string

secureRequested

boolean

serviceEndpoints

CommonClusterServiceEndpoint

serviceSubnet

string

state

string

The lifecycle state of the cluster. Possible values include aborted, critical, delete_failed, deleted, deleting, deploy_failed, deploying, normal, pending, requested, updating, unsupported, and warning. For more information, see the docs 'http://ibm.biz/cluster-health-states'

status

string

supportedOperatingSystems

array

targetVersion

string

trustedProfileID

string

type

string

versionEOS

string

virtualPrivateEndpointURL

string

vpcs

array

workerCount

integer

workerZones

array

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List the IBM Cloud Satellite locations that you have access to.

GET /v2/satellite/getControllers

List the IBM Cloud Satellite locations that you have access to.

Request

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List the clusters in an IBM Cloud Satellite location that are associated with a Satellite-enabled service instance.

GET /v2/satellite/getServiceClusters

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.

Request

Path Parameters

Query Parameters

controller

Required *

string

The ID of the location to list services.

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Assign a host to an IBM Cloud Satellite location or cluster.

POST /v2/satellite/hostqueue/createAssignment

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.

Request

Request Body

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.

cluster

string

The name or ID of a Satellite location or cluster to assign the host to

controller

string

The name or ID of the Satellite location

hostID

string

Optional: The name or ID of the specific host to assign to a Satellite location or cluster

labels

object

Key-value pairs to label the host, such as cpu=4 to describe the host capabilities

workerpool

string

Optional: The name or ID of the worker pool within the cluster to assign the host to

zone

string

Optional: The zone within the cluster to assign the host to

Path Parameters

Query Parameters

Response

201 - Created. A host was successfully assigned to your IBM Cloud Satellite resource.

hostID

string

id

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

409 - Conflict. Could not find any available hosts that match your requested host ID or label parameters.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Attach a host to an IBM Cloud Satellite location.

POST /v2/satellite/hostqueue/createRegistrationScript

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.

Request

Request Body

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.

controller

string

The name or ID of the Satellite location

labels

object

Key-value pairs to label the host, such as cpu=4 to describe the host capabilities

Path Parameters

Query Parameters

Response

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.

List the hosts in your IBM Cloud Satellite location.

GET /v2/satellite/hostqueue/getHosts

List the hosts in your IBM Cloud Satellite location.

Request

Path Parameters

Query Parameters

controller

Required *

string

The ID of the location to to retrieve hosts from.

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Remove a host from an IBM Cloud Satellite location or cluster.

POST /v2/satellite/hostqueue/removeHost

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

Request

Request Body

MultishiftRemoveNode

The configuration details to remove a host from an IBM Cloud Satellite location, in JSON format.

controller

string

The name or ID of the Satellite location

hostID

string

The name or ID of the host to remove

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Could not find the host. To list available hosts, use the `GET /v2/satellite/hostqueue/getHosts` API or run `ibmcloud sat host ls`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

409 - Conflict. Cannot remove the host because a worker node runs on the host. Remove the worker node and try again.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Update a host in your IBM Cloud Satellite location.

POST /v2/satellite/hostqueue/updateHost

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.

Request

Request Body

MultishiftUpdateNode

The configuration details to update a host to an IBM Cloud Satellite resource, in JSON format.

controller

string

The name or ID of the Satellite location

hostID

string

The name or ID of the host to update

labels

object

Key-value pairs to label the host, such as cpu=4 to describe the host capabilities

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Could not find the host. To list available hosts, use the `GET /v2/satellite/hostqueue/getHosts` API or run `ibmcloud sat host ls`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

409 - Conflict. The labels cannot be updated because the host is already assigned to an IBM Cloud Satellite resource, such as a cluster.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Remove an IBM Cloud Satellite Location.

POST /v2/satellite/removeController

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.

Request

Request Body

MultishiftCreateClusterFragment

The IBM Satellite location to remove.

calicoIPAutodetection

object

Optional: Used to determine the correct IP for internal routing

controller

string

The name or ID of the Satellite location

infrastructureTopology

string

Optional: Enables single worker node clusters

networkPlugin

string

Optional: NetworkPlugin indicates what container network interface has to be used in the cluster. If the field is missing it is defaulted to Calico.

pullSecret

string

Optional: The RedHat pull secret to create the OpenShift cluster

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Set the Pod Security admission controller configuration.

POST /v2/setPodSecurity

Set the Pod Security admission controller configuration.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To change the Pod Security admission controller configuration, you must have the Administrator platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-pod-security.set

Request

Request Body

SetPodSecurityRequest

The cluster to target.

cluster

string

configuration

string

Optional: A base64 encoded Kubernetes PodSecurityConfiguration yaml definition. If configuration is present the specified custom configuration will be used. If configuration is not present the default Kubernetes configuration will be used.

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Set custom labels for a worker pool.

POST /v2/setWorkerPoolLabels

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool-label.set

Request

Request Body

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.

cluster

string

labels

object

workerpool

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Set the operating system of a worker pool.

POST /v2/setWorkerPoolOperatingSystem

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • cluster-worker-pool-operating-system.set

Request

Request Body

SetWorkerPoolOperatingSystem

Sets the operating system of a worker pool.

cluster

string

operatingSystem

string

workerPool

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - The worker pool's operating system is not suitable for an upgrade this way.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - The specified worker pool could not be found..

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Set custom taints for a worker pool.

POST /v2/setWorkerPoolTaints

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool-taint.set

Request

Request Body

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

cluster

string

taints

object

workerpool

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

POST /v2/storage/createAttachment

Create volume attachment for a given worker

Request

Request Body

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

cluster

string

volumeID

string

worker

string

Path Parameters

Query Parameters

Response

201 - Ok. Attach request successfully accepted.

device

Device

id

string

name

string

status

string

type

string

volume

Volume

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Detach volume from given worker.

POST /v2/storage/deleteAttachment

Request

Request Body

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

cluster

string

volumeAttachmentID

string

volumeID

string

worker

string

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

GET /v2/storage/getAttachment

Get the volume attachment detail for given volume attachment ID

Request

Path Parameters

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

volumeAttachmentID

Required *

string

The unique volume attachment ID for the attached volume

Response

200 - Ok.

device

Device

id

string

name

string

status

string

type

string

volume

Volume

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

GET /v2/storage/getAttachments

Get the volume attachments detail for a given worker

Request

Path Parameters

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.

Response

200 - Ok.

volume_attachments

array

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get the details of a storage volume.

GET /v2/storage/getVolume

Request

Path Parameters

Query Parameters

volumeID

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

Response

200 - Ok.

id

string

ID .. id is of a volume

name

string

Name .. Name of the volume

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List storage volumes for a cluster or for the account if no cluster is provided.

GET /v2/storage/getVolumes

Request

Path Parameters

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

Response

200 - Ok.

volumes

array

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Acknowledge the request to expand storage capacity.

PATCH /v2/storage/satellite/ackDesiredStorageConfigCapacity

Acknowledge the request to expand the storage capacity of an existing storage request.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Read Satellite Location access in IAM.

  • satellite.location.read

Auditing

Calling this method generates the following auditing event.

  • satellite.storage-configuration.ack-desired-capacity

Request

Request Body

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

cluster

string

controller

string

request-id

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create an assignment using a Satellite storage configuration for the cluster group(s).

POST /v2/storage/satellite/createAssignment

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Satellite Config Subscription Create access in IAM.

  • satellite.config-subscription.create

Auditing

Calling this method generates the following auditing event.

  • satellite.subscription.create

Request

Request Body

CreateSubscriptionInputData

Include following parameters to create an assignment: 1. Name of the assignment (`name`). 2. 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`. 3. 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`. 4. 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`. 5. Enable or disable automatic upgrades for the assignment (`autoUpgrade="true|false"`).

autoUpgrade

string

config

string

controller

string

groups

array

name

string

Path Parameters

Query Parameters

Response

200 - OK. An assignment using the storage configuration is created.

addSubscription

AddSubscriptionType

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create an assignment using a Satellite storage configuration for a Satellite cluster or service cluster.

POST /v2/storage/satellite/createAssignmentByCluster

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Satellite Config Subscription Create access in IAM.

  • satellite.config-subscription.create

Auditing

Calling this method generates the following auditing event.

  • satellite.subscription.create-by-cluster

Request

Request Body

CreateSubscriptionByClusterInputData

Include following parameters to create an assignment: 1. Name of the assignment (`name`). 2. 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`. 3. 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`. 4. 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`. 5. Enable or disable automatic upgrades for the assignment (`autoUpgrade="true|false"`).

autoUpgrade

string

cluster

string

config

string

controller

string

name

string

Path Parameters

Query Parameters

Response

200 - OK. An assignment using the storage configuration is created.

addSubscription

AddSubscriptionType

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Deprecated. To create a Satellite storage configuration, you can use /v2/storage/satellite/createStorageConfigurationByController API instead.

POST /v2/storage/satellite/createStorageConfiguration

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.

Request

Request Body

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

config-name

string

controller

string

storage-class-parameters

array

storage-template-name

string

storage-template-version

string

user-config-parameters

object

user-secret-parameters

object

Path Parameters

Query Parameters

Response

201 - OK. The storage configuration is created.

addChannel

object

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create a Satellite storage configuration

POST /v2/storage/satellite/createStorageConfigurationByController

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Satellite Config Configuration Update access in IAM.

  • satellite.config-configuration.update

Auditing

Calling this method generates the following auditing event.

  • satellite.storage-configuration.create

Request

Request Body

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

config-name

string

controller

string

storage-class-parameters

array

storage-template-name

string

storage-template-version

string

user-config-parameters

object

user-secret-parameters

object

Path Parameters

Query Parameters

Response

201 - OK. The storage configuration is created.

addChannel

object

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Expand the capacity of a storage request.

PATCH /v2/storage/satellite/expandDesiredStorageConfigCapacity

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • satellite.storage-configuration.expand-desired

Request

Request Body

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

cluster

string

request-id

string

total-capacity

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List Satellite storage configurations assigned to a Satellite cluster or service cluster.

GET /v2/storage/satellite/getAssignedStorageConfigs

List Satellite storage configurations that are assigned to a Satellite cluster or service cluster.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Read Satellite Location access or the Viewer platform role to Kubernetes Service in IAM.

  • satellite.location.read
  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • satellite.storage-configuration.get-assigned

Request

Path Parameters

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

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details of an assignment.

GET /v2/storage/satellite/getAssignment

View details of an assignment by the assignment UUID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Satellite Config Subscription Read access in IAM.

  • satellite.config-subscription.read

Auditing

Calling this method generates the following auditing event.

  • satellite.subscription.get

Request

Path Parameters

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

Response

200 - OK. Assignment details are returned.

channelName

string

channelUuid

string

cluster

string

clusterName

string

configRevisionStatus

object

created

string

groups

array

isAssignmentUpgradeAvailable

boolean

isAutoUpgradeEnabled

boolean

name

string

orgId

string

owner

object

remoteResources

array

rolloutStatus

object

satSvcClusterId

string

satcluster

string

subscriptionType

string

updated

string

uuid

string

version

string

versionUuid

string

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Deprecated. To view details of an assignment, you can use /v2/storage/satellite/getAssignment API instead.

GET /v2/storage/satellite/getAssignmentByName

View details of an assignment by the assignment name.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Satellite Config Subscription Read access in IAM.

  • satellite.config-subscription.read

Auditing

Calling this method generates the following auditing event.

  • satellite.subscription.get-by-name

Request

Path Parameters

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

Response

200 - OK. Assignment details successfully fetched.

channelName

string

channelUuid

string

cluster

string

clusterName

string

configRevisionStatus

object

created

string

groups

array

isAssignmentUpgradeAvailable

boolean

isAutoUpgradeEnabled

boolean

name

string

orgId

string

owner

object

remoteResources

array

rolloutStatus

object

satSvcClusterId

string

satcluster

string

subscriptionType

string

updated

string

uuid

string

version

string

versionUuid

string

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List storage assignments in the IBM Cloud account.

GET /v2/storage/satellite/getAssignments

List storage assignments that you have access to in the IBM Cloud account. Returned details include the assignment name, UUID, and creation timestamp.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Satellite Config Subscription Read access in IAM.

  • satellite.config-subscription.read

Auditing

Calling this method generates the following auditing event.

  • satellite.subscription.list

Request

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List storage assignments created for a Satellite cluster or service cluster.

GET /v2/storage/satellite/getAssignmentsByClusterID

List storage assignments created for a Satellite cluster or service cluster. Returned details include the assignment name, UUID, and creation timestamp.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Read Satellite Location access or the Viewer platform role to Kubernetes Service in IAM.

  • satellite.location.read
  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • satellite.subscription.get-by-clusterid

Request

Path Parameters

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

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List storage assignments by configuration name or UUID.

GET /v2/storage/satellite/getAssignmentsByConfig

List storage assignments by configuration name or UUID. Returned details include the assignment name, UUID, and creation timestamp.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Satellite Config Organization Read access in IAM.

  • satellite.config-organization.read

Auditing

Calling this method generates the following auditing event.

  • satellite.subscription.get-by-config

Request

Path Parameters

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

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List storage assignments in a Satellite location.

GET /v2/storage/satellite/getAssignmentsByController

List storage assignments that you have access to in a Satellite location. Returned details include the assignment name, UUID, and creation timestamp.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Satellite Config Subscription Read access in IAM.

  • satellite.config-subscription.read

Auditing

Calling this method generates the following auditing event.

  • satellite.subscription.get-by-controller

Request

Path Parameters

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

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List and filter available storage classes from assigned Satellite storage configurations on a Satellite cluster or service cluster.

GET /v2/storage/satellite/getAvailableStorageClasses

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Read Satellite Location access or the Viewer platform role to Kubernetes Service in IAM.

  • satellite.location.read
  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • satellite.available.classes.get

Request

Path Parameters

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

volumeType

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.

onlyShowSDS

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

Response

200 - OK. Available storage classes are listed.

storage-classes

array

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List Storage requests on a cluster.

GET /v2/storage/satellite/getDesiredStorageConfig

List the storage requests for a cluster in a Satellite location.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Read Satellite Location access or the Viewer platform role to Kubernetes Service in IAM.

  • satellite.location.read
  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • satellite.storage-configuration.get-desired

Request

Path Parameters

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. The`assignment` 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>`.

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details of a Satellite storage configuration.

GET /v2/storage/satellite/getStorageConfiguration

View the details of a Satellite storage configuration.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Satellite Config Organization Read access in IAM.

  • satellite.config-organization.read

Auditing

Calling this method generates the following auditing event.

  • satellite.storage-configuration.get

Request

Path Parameters

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

Response

201 - OK. Storage configuration details are returned.

config-name

string

config-version

string

controller

string

created

string

is-revision-update-available

boolean

is-user-secret-parameters-set

object

latest-revision

string

location

string

orgId

string

revision

string

storage-class-parameters

array

storage-template-metadata

ConfigAttributes

ConfigAttributes defines attributes related to storage configuration

storage-template-name

string

storage-template-version

string

subscriptions

array

tags

array

template-status

string

user-config-parameters

object

user-secret-parameters

object

uuid

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List Satellite storage configurations.

GET /v2/storage/satellite/getStorageConfigurations

List the Satellite storage configurations that you have access to in a Satellite location or in the IBM Cloud account.

Request

Path Parameters

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

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List Satellite storage configurations in a Satellite location.

GET /v2/storage/satellite/getStorageConfigurationsByController

List the Satellite storage configurations that you have access to in a Satellite location.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Satellite Config Organization Read access in IAM.

  • satellite.config-organization.read

Auditing

Calling this method generates the following auditing event.

  • satellite.storage-configuration.get-by-controller

Request

Path Parameters

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

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View the details of a Satellite storage template.

GET /v2/storage/satellite/getStorageTemplate

View the details of a Satellite storage template by name and version

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Read Satellite Location access in IAM.

  • satellite.location.read

Auditing

Calling this method generates the following auditing event.

  • satellite.storage-template.get

Request

Path Parameters

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

Response

200 - OK. Storage template details are returned.

custom-parameters

array

description

string

name

string

revision

string

status

string

storage-class-parameters

array

storage-class-template

string

tags

array

vendor-storage-class-parameters

array

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View the change log details of Satellite storage templates.

GET /v2/storage/satellite/getStorageTemplateChangelog

View the change log details of all Satellite storage templates or a specific Satellite storage template by name.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Read Satellite Location access in IAM.

  • satellite.location.read

Auditing

Calling this method generates the following auditing event.

  • satellite.storage-template.get-changelog

Request

Path Parameters

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.

Response

200 - OK. Change log(s) of the storage template(s) is/are returned.

latest-revision

RevisionDetails

previous-revision

RevisionDetails

status

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

500 - Internal Server Error. Failed to fetch the changelog for the storage template. Note the incident ID and contact IBM Cloud support.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List Satellite storage templates.

GET /v2/storage/satellite/getStorageTemplates

List Satellite storage templates.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Read Satellite Location access in IAM.

  • satellite.location.read

Auditing

Calling this method generates the following auditing event.

  • satellite.storage-template.list

Request

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Remove an assignment.

DELETE /v2/storage/satellite/removeAssignment

Remove an assignment with a given UUID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Satellite Config Subscription Delete access in IAM.

  • satellite.config-subscription.delete

Auditing

Calling this method generates the following auditing event.

  • satellite.subscription.delete

Request

Path Parameters

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

Response

200 - OK. The assignment is removed.

removeSubscription

RemoveSubscriptionType

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Delete a storage request

DELETE /v2/storage/satellite/removeDesiredStorageConfig

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • satellite.storage-configuration.delete-desired

Request

Path Parameters

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

Response

201 - OK. The storage configuration is removed.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Remove a Satellite storage configuration.

DELETE /v2/storage/satellite/removeStorageConfiguration

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Satellite Config Configuration Update access in IAM.

  • satellite.config-configuration.update

Auditing

Calling this method generates the following auditing event.

  • satellite.storage-configuration.delete

Request

Path Parameters

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

removeAssignments

boolean

Specify `true` to remove the storage configuration along with the associated assignments. If unspecified, the default value is `false`.

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Enable or disable automatic upgrades for an existing storage assignment(s).

PATCH /v2/storage/satellite/setAssignmentAutoupgrade

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Satellite Config Subscription Update access in IAM.

  • satellite.config-subscription.update

Auditing

Calling this method generates the following auditing event.

  • satellite.subscription.update

Request

Request Body

SetAssignmentAutoupgradeInputData

The parameters must include: 1. Storage configuration name or ID (`config`). 2. Satellite Location (`controller`). 3. Set the `autoUpgrade` flag to `true` to enable assignments for automatic upgrades. If unspecified, it is assumed to be `false`. 4. 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.

assignment

object

all

boolean

uuids

array

autoUpgrade

boolean

config

string

controller

string

Path Parameters

Query Parameters

Response

200 - OK. The assignment(s) is/are enabled/disabled for automatic upgrades.

assignment

object

autoUpgrade

boolean

config

string

controller

string

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create a storage request on a cluster

POST /v2/storage/satellite/setDesiredStorageConfig

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • satellite.storage-configuration.set-desired

Request

Request Body

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: 1. 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`. 2. 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"}}`

cluster

string

storage-requests

DesiredAttributes

DesiredAttributes are various attributes associated with a particular storage request

max-volume-size

string

offering-type

string

provider

string

storageclasses

array

total-capacity

string

volume-availability

string

volume-encryption-at-rest

string

volume-expansion

string

volume-snapshot

string

volume-type

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Update an assignment.

PATCH /v2/storage/satellite/updateAssignment

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Satellite Config Subscription Update access in IAM.

  • satellite.config-subscription.update

Auditing

Calling this method generates the following auditing event.

  • satellite.subscription.update

Request

Request Body

UpdateSubscriptionInputData

The parameters must include the UUID of the assignment (`uuid`) along with at least one of the following parameters to be updated: 1. 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`. 2. New name of the assignment (`name`). 3. 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.

groups

array

name

string

updateConfigVersion

boolean

uuid

string

Path Parameters

Query Parameters

Response

200 - OK. The assignment is updated.

editSubscription

UpdateSubscriptionType

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Deprecated. To update a Satellite storage configuration, you can use /v2/storage/satellite/updateStorageConfigurationByController instead.

POST /v2/storage/satellite/updateStorageConfiguration

Update an existing Satellite storage configuration. Note that you cannot update Satellite storage configurations that are currently used in a Satellite storage assignment.

Request

Request Body

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

config-name

string

controller

string

storage-class-parameters

array

update-assignments

boolean

user-config-parameters

object

user-secret-parameters

object

Path Parameters

Query Parameters

Response

201 - OK. The storage configuration is updated.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Update a Satellite storage configuration.

POST /v2/storage/satellite/updateStorageConfigurationByController

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Satellite Config Configuration Update access in IAM.

  • satellite.config-configuration.update

Auditing

Calling this method generates the following auditing event.

  • satellite.storage-configuration.update

Request

Request Body

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

config-name

string

controller

string

storage-class-parameters

array

update-assignments

boolean

user-config-parameters

object

user-secret-parameters

object

Path Parameters

Query Parameters

Response

201 - OK. The storage configuration is updated.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Update a Satellite storage configuration to use the latest template revision.

PATCH /v2/storage/satellite/updateStorageConfigurationRevision

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Satellite Config Configuration Update access in IAM.

  • satellite.config-configuration.update

Auditing

Calling this method generates the following auditing event.

  • satellite.storage-configuration.update-revision

Request

Path Parameters

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

updateAssignments

boolean

Specify `true` or `false` to update assignment(s) of the specified storage configuration. The default value is `false`.

Response

201 - OK. Updated storage configuration template to latest revision.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - Not found.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

406 - Storage configuration template is already up to date with the latest revision.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Update the version of the Kubernetes cluster master node.

POST /v2/updateMaster

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-master.update

Request

Request Body

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

cluster

string

force

boolean

version

string

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create a VPC cluster.

POST /v2/vpc/createCluster

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster.create

Request

Request Body

VPCCreateCluster

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

cosInstanceCRN

string

cseACLEnabled

boolean

defaultWorkerPoolEntitlement

string

disableOutboundTrafficProtection

boolean

disablePublicServiceEndpoint

boolean

infrastructureTopology

string

kubeVersion

string

name

string

networkPlugin

string

offering

string

podSubnet

string

previews

array

provider

string

requestSecure

boolean

securityGroupIDs

array

serviceSubnet

string

trustedProfileID

string

workerPool

VPCCreateClusterWorkerPool

VPCCreateClusterWorkerPool is the vpc version of the worker pool part of a create cluster request.

diskEncryption

boolean

flavor

string

hostPoolID

string

isolation

string

labels

object

name

string

operatingSystem

string

secondaryStorageOption

string

vpcID

string

workerCount

integer

workerVolumeEncryption

object

WorkerVolumeEncryption contains encryption related fields

zones

array

Path Parameters

Query Parameters

Response

201 - Created. The cluster was successfully created in the IBM Cloud account that you are logged in to.

clusterID

string

messages

array

non_critical_errors

ResponseErrors

ResponseErrors are used to communicate to non-critical errors to end users

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

409 - Conflict. A cluster with the same name already exists. Choose another name for your cluster.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create a worker pool for a VPC cluster.

POST /v2/vpc/createWorkerPool

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool.create

Request

Request Body

v2VPCCreateWorkerPoolRequest

The

Zones

array

cluster

string

diskEncryption

boolean

entitlement

string

flavor

string

hostPool

string

isolation

string

labels

object

name

string

operatingSystem

string

secondaryStorageOption

string

securityGroupIDs

array

vpcID

string

workerCount

integer

workerVolumeEncryption

WorkerVolumeEncryption

WorkerVolumeEncryption contains encryption related fields

kmsAccountID

string

kmsInstanceID

string

workerVolumeCRKID

string

Path Parameters

Query Parameters

Response

201 - Created. The worker pool was successfully created in for the specified cluster.

workerPoolID

string

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

409 - Conflict. A worker pool create may already be in progress for the provided cluster. Please wait a few minutes and try again.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Create a zone in the specified worker pool for a VPC cluster.

POST /v2/vpc/createWorkerPoolZone

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool-zone.create

Request

Request Body

CreateWorkerpoolZoneRequest

Input parameters to add zones to the worker pool.

cluster

string

id

string

subnetID

string

workerpool

string

Path Parameters

Query Parameters

Response

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

409 - Conflict. The provided zone already exists in the worker pool.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Get details of a VPC cluster.

GET /v2/vpc/getCluster

Get details of a VPC cluster.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster.get

Request

Path Parameters

Query Parameters

showResources

string

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

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

Response

200 - Success. Detailed cluster information.

addons

array

caCertRotationStatus

CommonClusterCACertRotation

CommonClusterCACertRotation CA cert rotation properties

calicoIPAutodetectionConfig

string

createdDate

string

crn

string

datacenter

string

desiredTrustedProfileID

string

disableAutoUpdate

boolean

entitlement

string

etcdPort

string

features

CommonClusterFeatures

id

string

ignitionServerURL

string

imageSecurityEnabled

boolean

ingress

CommonClusterIngress

isPaid

boolean

keyManagementService

CommonClusterKMS

konnectivityServerURL

string

lifecycle

CommonClusterLifecycle

location

string

locationZones

array

masterKubeVersion

string

masterURL

string

monitoringURL

string

multiAzCapable

boolean

name

string

oauthServerURL

string

offering

string

podSubnet

string

provider

string

region

string

resourceGroup

string

resourceGroupName

string

secureRequested

boolean

serviceEndpoints

CommonClusterServiceEndpoint

serviceSubnet

string

state

string

The lifecycle state of the cluster. Possible values include aborted, critical, delete_failed, deleted, deleting, deploy_failed, deploying, normal, pending, requested, updating, unsupported, and warning. For more information, see the docs 'http://ibm.biz/cluster-health-states'

status

string

supportedOperatingSystems

array

targetVersion

string

trustedProfileID

string

type

string

versionEOS

string

vlans

array

workerCount

integer

workerZones

array

worker_vlans

VLANS

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.

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List the VPC clusters that you have access to.

GET /v2/vpc/getClusters

List the VPC clusters that you have access to.

Request

Path Parameters

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.

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View subnets for a given VPC.

GET /v2/vpc/getSubnets

View details for subnets in a VPC for the given region and provider.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-subnet.list

Request

Path Parameters

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.

Response

200 - Ok. A list of all subnets for the given VPC is returned.

400 - Bad Request. The given provider, zone, or VPC is invalid.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details of a VPC.

GET /v2/vpc/getVPC

View details of a virtual private cloud (VPC).

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-vpc.get

Request

Path Parameters

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.

vpcID

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.

Response

200 - OK. Details of the specified VPC are returned.

id

string

messages

array

name

string

resourceGroup

string

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View VPCs for the given provider.

GET /v2/vpc/getVPCs

View details for all VPCs in the given provider

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.account-vpc.list

Request

Path Parameters

Query Parameters

provider

Required *

string

The name of the provider in which to list VPCs.

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details of a worker node for VPC cluster.

GET /v2/vpc/getWorker

View detailed information for a worker node in a VPC cluster.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.worker.get

Request

Path Parameters

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

Response

200 - Ok. Detailed information about the worker node is returned.

dedicatedHostId

string

dedicatedHostPoolId

string

flavor

string

health

GetWorkerResponseHealth

id

string

kubeVersion

GetWorkerResponseKubeVersion

lifecycle

GetWorkerResponseLifecycle

location

string

networkInterfaces

GetWorkerResponseNetworkInterfaces

poolID

string

poolName

string

provider

string

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View details of a worker pool for a VPC cluster.

GET /v2/vpc/getWorkerPool

View detailed information for a worker pool in a VPC cluster.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool.get

Request

Path Parameters

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

Response

200 - Ok. Detailed information about the worker pool is returned.

autoscaleEnabled

boolean

dedicatedHostPoolId

string

flavor

string

flavorState

string

hostLabels

object

id

string

isBalanced

boolean

isolation

string

labels

object

lifecycle

GetWorkerPoolResponseLifecycle

openshiftLicense

string

operatingSystem

string

poolName

string

provider

string

secondaryStorageOption

DiskConfigResp

DiskConfigResp response type for describing a disk configuration

staticNetworkInterfaceCount

integer

taints

object

vpcID

string

workerCount

integer

workerVolumeEncryption

WorkerVolumeEncryption

WorkerVolumeEncryption contains encryption related fields

zones

array

401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List the worker pools in a VPC cluster.

GET /v2/vpc/getWorkerPools

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker-pool.list

Request

Path Parameters

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

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

View all workers for VPC cluster.

GET /v2/vpc/getWorkers

View detailed information for all worker nodes in a VPC cluster.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.cluster-worker.list

Request

Path Parameters

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

showDeleted

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

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

List available zones in a region.

GET /v2/vpc/getZones

List available zones that you can use to create a cluster in an IBM Cloud Kubernetes Service region.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

No IBM Cloud IAM role is required for this operation.

  • ``

Auditing

Calling this method generates the following auditing event.

  • ``

Request

Path Parameters

Query Parameters

provider

string

The provider for which to list zones. Defaults to vpc-classic.

showFlavors

boolean

Determines whether to show the flavors for the returned zones.

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

404 - No zones found for provider. Run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

Replace a worker node with a new worker node.

POST /v2/vpc/replaceWorker

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

  • containers-kubernetes.worker.replace

Request

Request Body

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.

cluster

string

update

boolean

workerID

string

Path Parameters

Query Parameters

Response

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type

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.

code

string

description

string

incidentID

string

recoveryCLI

string

terseDescription

string

type

string

ErrorType error type