Kubernetes Service API | IBM Cloud API Docs

Introduction

Last updated: 2020-04-14

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

Before you begin

Make sure that you have access to a paid IBM Cloud account.
Decide on your cluster networking setup.
Decide on the level of high availability for your cluster.
Review the available worker node flavors to choose from.

Charges

With IBM Cloud Kubernetes Service clusters, you can use IBM Cloud infrastructure compute, networking, and storage resources with platform services such as Watson AI or Compose Database-as-a-Service. Each resource might entail its own charges that can be fixed, metered, tiered, or reserved.

For more information, see the following links:

Authentication

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

Authorization

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

To create a cluster, make sure that you are assigned the following permissions:

Administrator platform role for IBM Cloud Kubernetes Service at the account level.
Writer or Manager service role for IBM Cloud Kubernetes Service.
Administrator platform role for IBM Cloud Container Registry at the account level.
Classic clusters only: Super User role or the minimum required permissions for classic infrastructure.
VPC clusters only: Administrator platform role for VPC Infrastructure.

For a list of permissions that are required for each API, see User access permissions.

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

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

The code examples on this tab use the client library that is provided for Node.js.

IAM and Activity Tracker actions by API method

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

API endpoint

Use the following API endpoint for all API requests:

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

Versioning

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

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

Error handling

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

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

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

GET /ingress/v2/load-balancer/configuration

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

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

Response Body

LBConfig

LBConfig struct models load balancer configuration

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

Available features:

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

PATCH /ingress/v2/load-balancer/configuration

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*

LBConfig

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

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

POST /ingress/v2/secret/addField

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*

UpdateConfig

Input parameter to add a secret field.

Response

Response Body

Secret

Secret struct holding details for a single secret

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

POST /ingress/v2/secret/createSecret

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*

CreateConfig

Input parameter to add a secret.

Response

Response Body

Secret

Secret struct holding details for a single secret

Status Code

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

No Sample Response

This method does not specify any sample responses.

Delete an Ingress secret from the cluster.

POST /ingress/v2/secret/deleteSecret

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*

DeleteConfig

Input parameter to add a secret.

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

View Ingress secret details.

GET /ingress/v2/secret/getSecret

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

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

Response Body

Secret

Secret struct holding details for a single secret

Status Code

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

No Sample Response

This method does not specify any sample responses.

View Ingress secrets for a cluster.

GET /ingress/v2/secret/getSecrets

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

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

Response Body

Secret[]

Secrets struct for a secret array

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

POST /ingress/v2/secret/removeField

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*

UpdateConfig

Remove input parameter to remove a secret field.

Response

Response Body

Secret

Secret struct holding details for a single secret

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

POST /ingress/v2/secret/updateSecret

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*

UpdateConfig

Input parameter to add a secret.

Response

Response Body

Secret

Secret struct holding details for a single secret

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

GET /ingress/v2/secret/getInstance

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

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

Response Body

Instance

Instance struct holding details for a single instance

Status Code

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

No Sample Response

This method does not specify any sample responses.

View IBM Cloud Secrets Manager instances registered to the cluster.

GET /ingress/v2/secret/getInstances

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

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

Response Body

Instance[]

Instances struct for a secret array

Status Code

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

No Sample Response

This method does not specify any sample responses.

Register an IBM Cloud Secrets Manager instance to the cluster.

POST /ingress/v2/secret/registerInstance

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*

RegisterConfig

Input parameter to register an instance.

Response

Response Body

Instance

Instance struct holding details for a single instance

Status Code

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

No Sample Response

This method does not specify any sample responses.

Unregister an IBM Cloud Secrets Manager instance from the cluster.

POST /ingress/v2/secret/unregisterInstance

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*

DeleteConfig

Input parameter to unregister an instance.

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

POST /ingress/v2/secret/updateInstance

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*

UpdateConfig

Input parameter to update instance registration.

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

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

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the Satellite cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Response

Response Body

SatelliteACLResponse

SatelliteACLResponse response for GET request

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

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

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the Satellite cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

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

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Request Body

Required*

csePatchACL

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

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

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

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

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

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the Satellite cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Request Body

Required*

csePatchACL

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

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

GET /v1/acl/{idOrName}

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Response

Response Body

ACLResponse

ACLResponse response for GET request

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

DELETE /v1/acl/{idOrName}

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

PATCH /v1/acl/{idOrName}/add

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Request Body

Required*

csePatchACL

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

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

POST /v1/acl/{idOrName}/enable

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

PATCH /v1/acl/{idOrName}/rm

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Request Body

Required*

csePatchACL

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

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

GET /v1/addons

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

AddonCommon[]

AddonCommon represents common properties of an addon

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

GET /v1/config

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

No Activity Tracker event is generated for this operation.

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

BluemixConfig

Status Code

200
Success

No Sample Response

This method does not specify any sample responses.

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

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.

Response

Response Body

MachineType[]

MachineTypes a type that returns a sorted array of machine types

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

GET /v1/kube-versions

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

KubeVersion[]

KubeVersion the kubernetes version

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

GET /v1/locations

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

IKSLocation[]

IKSLocation properties

Status Code

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

No Sample Response

This method does not specify any sample responses.

View the current user messages.

GET /v1/messages

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

MessageResponse[]

MessageResponse is a user message returned from the API

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

GET /v1/prodconfig

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

ProductConfig

ProductConfig properties

Status Code

200
Success

No Sample Response

This method does not specify any sample responses.

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

GET /v1/regions

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

Regions

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

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

GET /v1/versions

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

No Activity Tracker event is generated for this operation.

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

object

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

GET /v1/zones

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

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

Response Body

ZoneResponse[]

Zones sortable list of zone responses

Status Code

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

No Sample Response

This method does not specify any sample responses.

View the current user messages.

GET /v2/getMessages

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

MessageResponse[]

MessageResponse is a user message returned from the API

Status Code

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

No Sample Response

This method does not specify any sample responses.

Enable a public or private ALB in your standard cluster.

POST /v1/alb/albs

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*

ALBConfig

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

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

View detailed information for an ALB in a cluster.

GET /v1/alb/albs/{albID}

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

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

Response

Response Body

ALBConfig

ALBConfig config for alb configuration

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

DELETE /v1/alb/albs/{albID}

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

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

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

GET /v1/alb/clusters/{idOrName}

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Response

Response Body

ClusterALB[]

ClusterALB alb related information for cluster

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

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

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

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.

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

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

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

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.

Response

Response Body

UpdatePolicy

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

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

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

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.

Request Body

Required*

UpdatePolicy

The new update policy configuration.

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

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

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

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.

Request Body

Required*

ALB

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

Response

Response Body

AlbCreateResp

AlbCreateResp used to send back the albid on a create request

Status Code

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

No Sample Response

This method does not specify any sample responses.

List the clusters that you have access to.

GET /v1/clusters

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

Clusters are listed.

containers-kubernetes.cluster.list

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group to list clusters for. To list available resource groups, run ibmcloud resource groups. If you don't include this header, all the clusters in the account that you have access to are listed.

Query Parameters

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

Response

Response Body

Cluster[]

Cluster properties

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

POST /v1/clusters

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

The creation of a cluster is requested. This event is sent for any type of cluster, such as clusters that are created in different infrastructure providers.

containers-kubernetes.cluster.create

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
Required*
string
The ID of the resource group to create the cluster in. To list available resource groups, run ibmcloud resource groups. If you don't include this header, the cluster is created in the default resource group. After you create a cluster, you cannot change the resource group. Note that if you plan to integrate IBM Cloud services with the cluster, all the resources must be in the same group.
X-Auth-Refresh-Token
string
Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use the POST /v1/credentials API before this request.

Request Body

Required*

ClusterConfig

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

Response

Response Body

ClusterCreateResponse

ClusterCreateResponse is returned during a successful create cluster command

Status Code

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

No Sample Response

This method does not specify any sample responses.

View detailed information for a cluster.

GET /v1/clusters/{idOrName}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

Details for a cluster are returned.

containers-kubernetes.cluster.get

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

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

Response Body

Cluster

Cluster properties

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

PUT /v1/clusters/{idOrName}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

A cluster master update is requested.

containers-kubernetes.cluster-master.update

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Request Body

Required*

UpdateMasterCommand

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

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

DELETE /v1/clusters/{idOrName}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

A cluster is deleted.

containers-kubernetes.cluster.delete

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

GET /v1/clusters/{idOrName}/addons

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

Cluster add-ons are listed.

containers-kubernetes.cluster-addon.list

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group of the cluster, use the GET /v1/clusters/{idOrName} API.

Path Parameters

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.

Response

Response Body

ClusterAddon[]

ClusterAddon represents one add on

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

PATCH /v1/clusters/{idOrName}/addons

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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 events, depending on any listed conditions.

The event that is generated depends on the operation that you request for the cluster add-on.

containers-kubernetes.cluster-addon.enable
A cluster add-on is enabled. Generated if enable is passed for the addonRequest parameter.
containers-kubernetes.cluster-addon.disable
A cluster add-on is disabled. Generated if disable is passed for the addonRequest parameter.
containers-kubernetes.cluster-addon.update
A cluster add-on is updated. Generated if update is passed for the addonRequest parameter.

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group of the cluster, use the GET /v1/clusters/{idOrName} API.

Path Parameters

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.

Request Body

Required*

AddonRequest

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

Response

Response Body

AddonResponse

AddonResponse represents an addon response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

GET /v1/clusters/{idOrName}/config

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

The Kubernetes configuration file (kubeconfig) for a cluster is requested. Depending on the request, the kubeconfig might contain administrator or network certificates and secrets to access the cluster.

containers-kubernetes.cluster.config

Request

Custom Headers

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

Path Parameters

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
Skip adding the RBAC roles based on user's access in IAM.

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

POST /v1/clusters/{idOrName}/kms

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

The IBM Cloud services that are bound to a cluster are listed, across all Kubernetes namespaces in the cluster.

containers-kubernetes.cluster-service.list

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group of the cluster, use the GET /v1/clusters/{idOrName} API.

Path Parameters

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.

Request Body

Required*

KeyProtectData

Input parameters to create the Key Protect config for your cluster.

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

PUT /v1/clusters/{idOrName}/masters

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

A cluster master refresh is requested.

containers-kubernetes.cluster-master.refresh

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
Required*
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Request Body

MasterAPIServer

The master state. Currently, refresh is supported.

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

GET /v1/clusters/{idOrName}/services

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

The IBM Cloud services that are bound to a cluster are listed, across all Kubernetes namespaces in the cluster.

containers-kubernetes.cluster-service.list

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Response

Response Body

BoundService[]

BoundService properties

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

POST /v1/clusters/{idOrName}/services

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

An IBM Cloud service is bound to a namespace in the cluster.

containers-kubernetes.cluster-service.bind

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Request Body

Required*

string

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

Response

Response Body

BoundService

BoundService properties

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

The IBM Cloud services that are bound to a cluster are listed, filtered to a Kubernetes namespace in the cluster.

containers-kubernetes.cluster-service.list

Request

Custom Headers

Authorization
Required*
string
Your IAM IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Response

Response Body

BoundService[]

BoundService properties

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

An IBM Cloud service is removed from a namespace in the cluster.

containers-kubernetes.cluster-service.unbind

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

GET /v1/clusters/{idOrName}/subnets

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

The subnets for a cluster are listed.

containers-kubernetes.cluster-subnet.list

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

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.

Response

Response Body

VlanConfigField[]

VlanConfigField TODO provide meaningful comment

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

An existing IBM Cloud infrastructure subnet is added to a cluster.

containers-kubernetes.subnet.add

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Refresh-Token
string
Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use the POST /v1/credentials API before this request.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

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.

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

A public or private portable subnet is detached from a cluster.

containers-kubernetes.cluster-subnet.detach

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

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.

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

GET /v1/clusters/{idOrName}/usersubnets

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

User-managed subnets for a cluster are listed.

containers-kubernetes.cluster-user-subnet.list

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

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.

Response

Response Body

VlanConfigField[]

VlanConfigField TODO provide meaningful comment

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

POST /v1/clusters/{idOrName}/usersubnets

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

A user-managed subnet is added to the cluster.

containers-kubernetes.cluster-user-subnet.add

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Refresh-Token
string
Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use the POST /v1/credentials API before this request.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

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.

Request Body

Required*

UserSubnet

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

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

A user-managed subnet is removed from the cluster.

containers-kubernetes.vlan.delete

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

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.

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

A subnet is created.

containers-kubernetes.subnet.create

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Refresh-Token
string
Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use the POST /v1/credentials API before this request.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

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

Status Code

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

No Sample Response

This method does not specify any sample responses.

List all webhooks for a Kubernetes cluster.

GET /v1/clusters/{idOrName}/webhooks

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

Webhooks, such as for Slack, for a cluster are listed.

containers-kubernetes.cluster-webhook.list

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Response

Response Body

ClusterWebhook[]

ClusterWebhook webhook info

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

POST /v1/clusters/{idOrName}/webhooks

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

A cluster webhook, such as for Slack, is created.

containers-kubernetes.cluster-webhook.create

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Request Body

Required*

ClusterWebhook

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

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

GET /v1/clusters/{idOrName}/workerpools

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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.

The worker pools for a cluster are listed.

containers-kubernetes.cluster-worker-pool.list

Request

Custom Headers

Authorization
Required*
string
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.
X-Auth-Resource-Group
string
The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

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.

Response

Response Body

WorkerPoolResponse[]

WorkerPoolResponse provides worker pool data

Status Code

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

No Sample Response

This method does not specify any sample responses.

Introduction

Before you begin

Charges

Authentication

Authorization

IAM and Activity Tracker actions by API method

API endpoint

Versioning

Error handling

Methods

Get configuration of load balancers for Ingress ALBs.

Request

Custom Headers

Authorization

Query Parameters

cluster

type

Response

Response Body

cluster

proxyProtocol

type

Status Code

200

400

401

403

404

500

No Sample Response

Update the configuration of load balancers for Ingress ALBs.

Request

Custom Headers

Authorization

Request Body

cluster

proxyProtocol

type

Response

Status Code

202

400

401

403

404

423

500

No Sample Response

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

Request

Custom Headers

Authorization

Request Body

cluster

ingestionKey

privateEndpoint

Response

Response Body

cluster

crn

domain

expiresOn

fields

lastUpdatedTimestamp

name

namespace

persistence

secretType

status

type

userManaged

Status Code

201

400

401

500

No Sample Response

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

Request

Custom Headers