Introduction

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

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:

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.

Methods

Get configuration of load balancers for Ingress ALBs.

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

GET /ingress/v2/load-balancer/configuration

Request

Custom Headers

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

Query Parameters

  • The name or ID of the cluster.

  • Type of load balancer configuration to return. Possible options are public and private.

Response

LBConfig struct models load balancer configuration

Status Code

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

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

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

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

  • Not found. The specified cluster could not be found.

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request 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.

Update the configuration of load balancers for Ingress ALBs.

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

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

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

Response

Status Code

  • Load-balancer configuration submitted and update started.

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

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

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

  • Not found. The specified cluster could not be found.

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request 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.

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

POST /ingress/v2/secret/addField

Request

Custom Headers

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

Input parameter to add a secret field.

Response

Secret struct holding details for a single secret

Status Code

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

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

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

POST /ingress/v2/secret/createSecret

Request

Custom Headers

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

Input parameter to add a secret.

Response

Secret struct holding details for a single secret

Status Code

  • Created. The secret was successfully created in the cluster.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

Delete an Ingress secret from the cluster.

POST /ingress/v2/secret/deleteSecret

Request

Custom Headers

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

Input parameter to add a secret.

Response

Status Code

  • Deleted. The secret was successfully deleted from the cluster.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

View Ingress secret details.

GET /ingress/v2/secret/getSecret

Request

Custom Headers

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

Query Parameters

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

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

  • 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

Secret struct holding details for a single secret

Status Code

  • Ok. Detailed information about the secret is returned.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

View Ingress secrets for a cluster.

GET /ingress/v2/secret/getSecrets

Request

Custom Headers

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

Query Parameters

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

  • To view previously deleted secrets, pass true.

Response

Secrets struct for a secret array

Status Code

  • Ok. The list of available Ingress secrets is returned.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

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

POST /ingress/v2/secret/removeField

Request

Custom Headers

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

Remove input parameter to remove a secret field.

Response

Secret struct holding details for a single secret

Status Code

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

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

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

POST /ingress/v2/secret/updateSecret

Request

Custom Headers

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

Input parameter to add a secret.

Response

Secret struct holding details for a single secret

Status Code

  • Created. The secret was successfully created in the cluster.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

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

GET /ingress/v2/secret/getInstance

Request

Custom Headers

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

Query Parameters

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

  • 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

Instance struct holding details for a single instance

Status Code

  • Ok. Detailed information about the secret is returned.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

View IBM Cloud Secrets Manager instances registered to the cluster.

GET /ingress/v2/secret/getInstances

Request

Custom Headers

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

Query Parameters

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

  • To view previously deleted instances, pass true.

Response

Instances struct for a secret array

Status Code

  • Ok. The list of available Ingress secrets is returned.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

Register an IBM Cloud Secrets Manager instance to the cluster.

POST /ingress/v2/secret/registerInstance

Request

Custom Headers

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

Input parameter to register an instance.

Response

Instance struct holding details for a single instance

Status Code

  • Created. The instance was successfully registered to the cluster.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

Unregister an IBM Cloud Secrets Manager instance from the cluster.

POST /ingress/v2/secret/unregisterInstance

Request

Custom Headers

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

Input parameter to unregister an instance.

Response

Status Code

  • Deleted. The secret was successfully deleted from the cluster.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

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

POST /ingress/v2/secret/updateInstance

Request

Custom Headers

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

Input parameter to update instance registration.

Response

Status Code

  • Update. The instance was successfully updated.

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

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

Get a Satellite cluster's service endpoint allowlist.

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

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

  • 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

  • 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

SatelliteACLResponse response for GET request

Status Code

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

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

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

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

  • 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 for a Satellite cluster's service endpoint.

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

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

  • 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

  • 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

  • Accepted. The request to disable the Satellite allowlist feature for your Satellite cluster's service endpoint was successfully processed.

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

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

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

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

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

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

  • 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

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

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

Response

Status Code

  • Created. The subnets are successfully added to the Satellite cluster's service endpoint allowlist.

  • No content. The subnets are successfully added to the Satellite cluster's service endpoint allowlist.

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

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

  • 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 for a Satellite cluster's service endpoint.

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

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

  • 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

  • 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

  • Accepted. The request to enable the allowlist feature for your Satellite cluster's service endpoint was successfully processed.

  • Bad request. The Satellite service endpoint allowlist feature is already enabled on the specified cluster.

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

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

  • 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 from a Satellite cluster's service endpoint allowlist.

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

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

  • 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

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

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

Response

Status Code

  • Accepted. The subnets are successfully removed from the Satellite cluster's service endpoint allowlist.

  • No content. The subnets are successfully removed from the Satellite cluster's service endpoint allowlist.

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

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

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

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

Get a cluster's private service endpoint allowlist.

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

GET /v1/acl/{idOrName}

Request

Custom Headers

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

  • 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

  • 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

ACLResponse response for GET request

Status Code

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

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

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 for a cluster's private service endpoint.

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

DELETE /v1/acl/{idOrName}

Request

Custom Headers

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

  • 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

  • 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

  • Accepted. The request to disable the allowlist feature for your cluster's private service endpoint was successfully processed.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 subnets to a cluster's private service endpoint allowlist.

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

PATCH /v1/acl/{idOrName}/add

Request

Custom Headers

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

  • 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

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

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

Response

Status Code

  • Created. The subnets are successfully added to the cluster's private service endpoint allowlist.

  • No content. The subnets are successfully added to the cluster's private service endpoint allowlist.

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

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 subnet allowlist for a cluster's private service endpoint.

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

POST /v1/acl/{idOrName}/enable

Request

Custom Headers

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

  • 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

  • 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

  • Accepted. The request to enable the allowlist feature for your cluster's private service endpoint was successfully processed.

  • Bad request. The private service endpoint allowlist feature is already enabled on the specified cluster.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 from a cluster's private service endpoint allowlist.

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

PATCH /v1/acl/{idOrName}/rm

Request

Custom Headers

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

  • 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

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

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

Response

Status Code

  • Accepted. The subnets are successfully removed from the cluster's private service endpoint allowlist.

  • No content. The subnets are successfully removed from the cluster's private service endpoint allowlist.

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

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

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

AddonCommon represents common properties of an addon

Status Code

  • OK. The name, latest version, and minimum required Kubernetes version for each available add-on are returned.

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 configuration values for your IBM Cloud account.

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

Status Code

  • Success

No Sample Response

This method does not specify any sample responses.

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

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

  • 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

MachineTypes a type that returns a sorted array of machine types

Status Code

  • Success

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

Deprecated: List available Kubernetes versions.

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

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

KubeVersion the kubernetes version

Status Code

  • Success. A list of available BOM versions is returned.

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 locations.

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

IKSLocation properties

Status Code

  • Success

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

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

MessageResponse is a user message returned from the API

Status Code

  • Success

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

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

ProductConfig properties

Status Code

  • Success

No Sample Response

This method does not specify any sample responses.

Deprecated: List available Kubernetes Service regions.

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

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

Status Code

  • Success

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

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

Status Code

  • Success. Available container management platform versions for the IBM Cloud Kubernetes Service region are returned.

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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).

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

  • Specify true or false to show the machine types available in each zone.

  • Specify a location to filter zones for. To see supported locations, use the GET /v1​/locations API or run ibmcloud ks locations.

Response

Zones sortable list of zone responses

Status Code

  • Success. A list of available zones is returned.

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

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

MessageResponse is a user message returned from the API

Status Code

  • Success

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 an existing ALB in a cluster.

Enable a public or private ALB in your standard cluster.

POST /v1/alb/albs

Request

Custom Headers

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

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

  • Enabled. The ALB for the cluster was successfully enabled.

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

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

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request 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 details of an ALB.

View detailed information for an ALB in a cluster.

GET /v1/alb/albs/{albID}

Request

Custom Headers

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

Path Parameters

  • 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

ALBConfig config for alb configuration

Status Code

  • Ok. Details for the specified ALB are returned.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request 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 an ALB in your cluster.

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

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

Path Parameters

  • 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

  • Disabled. The ALB for the cluster was successfully disabled.

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

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request 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 ALBs in a cluster.

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

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

  • 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

  • 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

ClusterALB alb related information for cluster

Status Code

  • Ok. A list of ALB IDs for the cluster is returned.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request 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.

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

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

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

  • 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

  • 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

  • Ok. The update has been requested.

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

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

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

  • 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 in a cluster.

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

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

  • 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

  • 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

  • Ok. The current update policy.

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

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

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

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

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

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

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

  • 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

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

The new update policy configuration.

Response

Status Code

  • Ok. The ALB update policy has been changed.

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

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

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

  • 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 public or private ALB in a specified zone and VLAN.

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

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

  • 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

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

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

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

Response

AlbCreateResp used to send back the albid on a create request

Status Code

  • The ALB was successfully created.

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

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

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request 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.

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

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

  • 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

  • Specify a location to filter clusters for. To see supported locations, use the GET /v1​/locations API or run ibmcloud ks locations.

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

Response

Cluster properties

Status Code

  • Success. A list of clusters that you have access to is returned.

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

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

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

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

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

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

Response

ClusterCreateResponse is returned during a successful create cluster command

Status Code

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

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

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 for a cluster.

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

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

  • 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

  • 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

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

Response

Cluster properties

Status Code

  • Ok. Detailed information about the cluster is returned.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 version of the Kubernetes cluster master node.

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

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

  • 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

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

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

  • Ok. The request to update your master node was successfully processed.

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

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

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

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

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

  • 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

  • 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

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

  • 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

  • Ok. The cluster was successfully removed from the IBM Cloud account that you are logged in to.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

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

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

  • 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

  • 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

ClusterAddon represents one add on

Status Code

  • OK. Details for the add-ons in this cluster are returned.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your 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.

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

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

  • 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

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

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

Response

AddonResponse represents an addon response

Status Code

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

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

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

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your 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 configuration and certificates.

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

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

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

  • 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

  • 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

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

  • To format the output in a single YAML file, pass yaml.

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

  • Skip adding the RBAC roles based on user's access in IAM.

Response

Status Code

  • Ok. The cluster-specific configuration file and certificates are returned as a zip file.

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

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 key management service (KMS) provider configuration for a cluster.

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

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

  • 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

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

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

Response

Status Code

  • OK. Your Key Protect config will be applied to the cluster.

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

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

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

  • Conflict. Processing multiple concurrent requests from your account to create a Key Protect config for the cluster. Wait a few minutes and try again.

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your 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.

Refresh the Kubernetes master.

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

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

  • 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

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

The master state. Currently, refresh is supported.

Response

Status Code

  • Ok. The Master will be put into the desired state.

  • Bad Request. Check that all headers are present and that the state is valid. Valid states include refresh.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 bound to a cluster across all namespaces.

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

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

  • 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

  • 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

BoundService properties

Status Code

  • Ok. A list of IBM Cloud services bound to a cluster across all Kubernetes namespaces is returned.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 to a cluster.

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

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

  • 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

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

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

BoundService properties

Status Code

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

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

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 bound to a specific namespace in a cluster.

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

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

  • 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

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

  • The Kubernetes namespace in your cluster where you want to list all bound IBM Cloud services.

Response

BoundService properties

Status Code

  • Ok. A list of services bound to a cluster within a specific Kubernetes namespace is returned.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 from a cluster.

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

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

  • 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

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

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

  • 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

  • The IBM Cloud service instance was successfully unbound from the Kubernetes namespace of your cluster.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 classic subnets that are bound to a cluster.

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

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

  • 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

  • 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

VlanConfigField TODO provide meaningful comment

Status Code

  • Ok. A list of user-managed subnets that are bound to your cluster.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 an IBM Cloud classic infrastructure subnet to a cluster.

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

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

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

  • 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

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

  • 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

  • Ok. The specified subnet was successfully made available to your cluster.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 public or private portable subnet from a cluster.

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

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

  • 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

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

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

Response

Status Code

  • Ok. The specified subnet was successfully removed from your cluster.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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.

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

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

  • 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

  • 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

VlanConfigField TODO provide meaningful comment

Status Code

  • Ok. A list of user-managed subnets that are bound to your cluster.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 an existing user-managed subnet to a cluster.

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

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

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

  • 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

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

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

Response

Status Code

  • Ok. The specified subnet was successfully made available to your cluster.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 user-managed subnet from a cluster.

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

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

  • 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

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

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

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

Response

Status Code

  • Ok. The specified subnet was successfully removed from your cluster.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 add it to an existing cluster.

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

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

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

  • 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

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

  • 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

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

Response

Status Code

  • Ok. The specified subnet was successfully made available to your cluster.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 cluster.

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

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

  • 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

  • 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

ClusterWebhook webhook info

Status Code

  • Ok. A list of available webhooks for the cluster is returned.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 to a cluster.

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

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

  • 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

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

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

  • Created. The webhook was successfully added to the cluster.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be 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 worker pools in a cluster.

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

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

  • 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

  • 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

WorkerPoolResponse provides worker pool data

Status Code

  • OK. The list of worker pools was successfully retrieved.

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

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

  • Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your 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.