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
- Make sure that you have access to a paid IBM Cloud account.
- Decide on your cluster networking setup.
- Decide on the level of high availability for your cluster.
- Review the available worker node flavors to choose from.
Charges
With IBM Cloud Kubernetes Service clusters, you can use IBM Cloud infrastructure compute, networking, and storage resources with platform services such as Watson AI or Compose Database-as-a-Service. Each resource might entail its own charges that can be fixed, metered, tiered, or reserved.
For more information, see the following links:
Authentication
The IBM Cloud Kubernetes Service API uses IBM Cloud Identity and Access Management (IAM) to authenticate requests. Pass a bearer and a refresh token token in an Authorization header or an apikey
. Tokens support authenticated requests without embedding service credentials in every call.
Authorization
To use the IBM Cloud Kubernetes Service API, you must be authorized to work with the service in IBM Cloud Identity and Access Management (IAM). The service uses IAM platform and service access roles to determine your permissions and the actions that you can perform.
To create a cluster, make sure that you are assigned the following permissions:
- Administrator platform role for IBM Cloud Kubernetes Service at the account level.
- Writer or Manager service role for IBM Cloud Kubernetes Service.
- Administrator platform role for IBM Cloud Container Registry at the account level.
- Classic clusters only: Super User role or the minimum required permissions for classic infrastructure.
- VPC clusters only: Administrator platform role for VPC Infrastructure.
For a list of permissions that are required for each API, see User access permissions.
Beginning with version 4.0.0, the Node SDK returns a Promise for all methods when a callback isn't specified.
The package location moved to ibm-watson
. It's available at watson-developer-cloud
but is not updated there. Use ibm-watson
to stay up to date.
The code examples on this tab use the client library that is provided for Node.js.
IAM and Activity Tracker actions by API method
For a list of the IBM Cloud Identity and Access Management (IAM) action and Activity Tracker events by API method, see the product documentation.
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
andprivate
.
Response
LBConfig struct models load balancer configuration
LBProxyProtocolConfig stuct for storing the loadbalancer's proxy protocol config in etcd
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 thenibmcloud 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
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 totrue
to enable orfalse
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
- Limitations:
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.
LBProxyProtocolConfig stuct for storing the loadbalancer's proxy protocol config in etcd
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 thenibmcloud 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
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
Secrets struct for a secret array
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 thenibmcloud 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
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.
FieldAdd the secret field add request
Response
Secret struct holding details for a single secret
Secrets struct for a secret array
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 thenibmcloud 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
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 thenibmcloud 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
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 runibmcloud 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 runibmcloud 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 runibmcloud ks ingress secret ls
.
Response
Secret struct holding details for a single secret
Secrets struct for a secret array
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 thenibmcloud 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 runibmcloud 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
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 runibmcloud ks cluster ls
.To view previously deleted secrets, pass
true
.
Response
Secrets struct for a secret array
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 thenibmcloud 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 runibmcloud 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
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
Secrets struct for a secret array
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 thenibmcloud 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
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
Secrets struct for a secret array
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 thenibmcloud 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
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 runibmcloud 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 runibmcloud 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 thenibmcloud 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 runibmcloud 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
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 runibmcloud 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 thenibmcloud 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 runibmcloud 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
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 thenibmcloud 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
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 thenibmcloud 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
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 thenibmcloud 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 runibmcloud 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
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 runibmcloud 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 thenibmcloud 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 runibmcloud 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
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 runibmcloud 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 thenibmcloud 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 runibmcloud 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
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 runibmcloud ks cluster ls
.
The list of subnets to add to the Satellite cluster's service endpoint allowlist.
The ACL list to patch
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 thenibmcloud 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 runibmcloud 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
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 runibmcloud 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 thenibmcloud 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 runibmcloud 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
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 runibmcloud ks cluster ls
.
The list of subnets to remove from the Satellite cluster's service endpoint allowlist.
The ACL list to patch
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 thenibmcloud 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 runibmcloud 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
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 runibmcloud ks cluster ls
.
Response
ACLResponse response for GET request
CSEACLList actual and desired
CSEACLList actual and desired
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 thenibmcloud 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 runibmcloud 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
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 runibmcloud 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 thenibmcloud 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 runibmcloud 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
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 runibmcloud ks cluster ls
.
The list of subnets to add to the cluster's private service endpoint allowlist.
The ACL list to patch
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 thenibmcloud 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 runibmcloud 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
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 runibmcloud 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 thenibmcloud 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 runibmcloud 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
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 runibmcloud ks cluster ls
.
The list of subnets to remove from the cluster's private service endpoint allowlist.
The ACL list to patch
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 thenibmcloud 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 runibmcloud 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
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
Response
AddonCommon represents common properties of an addon
The addon name such as 'istio'.
The addon default versions based on supported cluster version/provider
AddonOptionsTemplate represents the options for an addon
The minimum kubernetes version for this addon.
The minimum OpenShift version for this addon.
The supported kubernetes version range for this addon.
The supported Openshift version range for this addon.
The addon target version.
The addon version, omit the version if you wish to use the default version.
VLAN spanning required for multi-zone clusters
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
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
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 theGET /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 theGET /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
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
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 thenibmcloud 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
List available locations.
List locations from the IBM Cloud catalog that are supported by the IBM Cloud Kubernetes Service.
GET /v1/locations
Response
IKSLocation properties
Status Code
Success
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud login
and thenibmcloud 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
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
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
Response
KubeVersion the kubernetes version
any property
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 thenibmcloud 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
List available zones (data centers).
List available zones (data centers) where you can create a cluster.
GET /v1/zones
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 runibmcloud ks locations
.
Response
Zones sortable list of zone responses
FlavorResponse response type for retrieving a flavor
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 thenibmcloud 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
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
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
The build number of the ALB.
The ID of the application load balancer (ALB).
The type of ALB.
The auth build of the ALB.
The date the ALB was created.
If set to true, the deployment of the ALB is disabled.
Set to true to enable the ALB, or false to disable the ALB for the cluster.
The name of the cluster that the ALB belongs to.
Desired number of ALB replicas that you want in your cluster.
If set to true, resizing of the ALB is done.
The state of the ALB.
The status of the ALB.
The zone where you want to add ALBs.
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 thenibmcloud 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 theGET /clusters/{idOrName}
API or runibmcloud 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
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 runibmcloud ks alb ls --cluster <cluster_name_or_ID>
.
Response
ALBConfig config for alb configuration
The build number of the ALB.
The ID of the application load balancer (ALB).
The type of ALB.
The auth build of the ALB.
The date the ALB was created.
If set to true, the deployment of the ALB is disabled.
Set to true to enable the ALB, or false to disable the ALB for the cluster.
The name of the cluster that the ALB belongs to.
Desired number of ALB replicas that you want in your cluster.
If set to true, resizing of the ALB is done.
The state of the ALB.
The status of the ALB.
The zone where you want to add ALBs.
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 thenibmcloud 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 theGET /clusters/{idOrName}
API or runibmcloud 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
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 runibmcloud 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 thenibmcloud 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 theGET /clusters/{idOrName}
API or runibmcloud 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
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
PrivateIngressHostname string
json:"privateIngressHostname"
PrivateIngressSecretName stringjson:"privateIngressSecretName"
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 thenibmcloud 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
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 runibmcloud 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 thenibmcloud 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 runibmcloud 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
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 runibmcloud ks cluster ls
.
Response
If set to true, automatic updates for the ALBs are enabled.
If set to true, all ALBs in the cluster run the latest ALB version.
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 thenibmcloud 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 runibmcloud 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
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 runibmcloud ks cluster ls
.
The new update policy configuration.
If set to true, automatic updates for the ALBs are enabled.
If set to true, all ALBs in the cluster run the latest ALB version.
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 thenibmcloud 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 runibmcloud 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
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 theWorker Zones
field in the output.
The input parameters to create an ALB. For more information, see https://ibm.biz/alb_create_docs
If set to true, the ALB is enabled by default. \
The type of Ingress image that you want to use for your ALB deployment.
Optional: The IP address that you want to assign to the ALB.
The version of the network load balancer that you want to use for the ALB.
The type of ALB that you want to create.
The VLAN ID that you want to use for your ALBs.
The zone where you want to deploy the ALB.
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 thenibmcloud 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 theGET /v1/clusters/{idOrName}
API or runibmcloud 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
List the clusters that you have access to.
List the clusters that you have access to.
GET /v1/clusters
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 runibmcloud ks locations
.To view additional cluster resources like addons, VLANs, subnets, and storage, pass
true
.
Response
Cluster properties
Addon properties
VlanConfigField TODO provide meaningful comment
VLANS is a helper type to sort an api.VLAN list. The VLANS will sort the list in order of the Properties.PrimaryRouter value so that VLAN's of a common router are listed consecutively.
Status Code
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 thenibmcloud 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
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
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 thePOST 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 thePOST /v1/credentials
API before this request.
Input parameter to add a cluster. For more information, see https://ibm.biz/cluster_create_docs
The data center where the worker node is created.
The machine type of the worker node.
The private VLAN ID that the worker node is attached to.
The public VLAN ID that the worker node is attached to.
Response
ClusterCreateResponse is returned during a successful create cluster command
ResponseErrors are used to communicate to non-critical errors to end users
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 thenibmcloud 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
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 runibmcloud ks cluster ls
.
Query Parameters
To view additional cluster resources like addons, VLANs, subnets, and storage, pass
true
.
Response
Cluster properties
Addon properties
VlanConfigField TODO provide meaningful comment
VLANS is a helper type to sort an api.VLAN list. The VLANS will sort the list in order of the Properties.PrimaryRouter value so that VLAN's of a common router are listed consecutively.
Status Code
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 thenibmcloud 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 runibmcloud 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
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}
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 runibmcloud 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
.
The action to perform on the master.
If set to true, any warnings during the update process are ignored.
The Kubernetes version to use for the update.
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 thenibmcloud 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 runibmcloud 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 runibmcloud 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
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}
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 runibmcloud 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 thenibmcloud 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 runibmcloud 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
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
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 runibmcloud ks cluster ls
.
Response
ClusterAddon represents one add on
The addon name such as 'istio'.
The versions that the addon can be upgraded to
The addon default versions based on supported cluster version/provider
Determines if this addon version is deprecated
The health state for this addon, a short indication (e.g. critical, pending)
The health status for this addon, provides a description of the state (e.g. error message)
AddonOptionsTemplate represents the options for an addon
The minimum kubernetes version for this addon.
The minimum OpenShift version for this addon.
The addon options. Should be a yaml for a kube resource.
The supported kubernetes version range for this addon.
The supported Openshift version range for this addon.
The addon target version.
The addon version, omit the version if you wish to use the default version.
VLAN spanning required for multi-zone clusters
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 thenibmcloud 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 runibmcloud 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
Enable, disable, or update add-ons for a cluster.
Enable, disable, or update add-ons for a cluster.
PATCH /v1/clusters/{idOrName}/addons
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 theaddonRequest
parameter.containers-kubernetes.cluster-addon.disable
A cluster add-on is disabled. Generated if
disable
is passed for theaddonRequest
parameter.containers-kubernetes.cluster-addon.update
A cluster add-on is updated. Generated if
update
is passed for theaddonRequest
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 runibmcloud ks cluster ls
.
Input parameters to enable or disable add-ons in your cluster.
The addons to operate on.
Indicate if the specified addons should be enabled or disabled.
Indicate if the specified addons should be updated. Only Update or Enable should be used, not both.
Response
AddonResponse represents an addon response
The addon enable request would result in an invalid configuration. Install missing addons to continue.
The addon disable request would result in an invalid configuration. Inspect the map to determine why the configuration is invalid.
ClusterAddon represents one add on
orphanedAddons
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 thenibmcloud 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 runibmcloud 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
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
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 thePOST 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 runibmcloud 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 thenibmcloud 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 runibmcloud 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
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
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 runibmcloud ks cluster ls
.
Input parameters to create the Key Protect config for your cluster.
CRK is a Key Protect customer root key. To get the CRK, see http://ibm.biz/kp-viewcrk
InstanceID is a Key Protect instance ID. To get the instance ID, run 'ibmcloud resource service-instance <kp_service> --id' and copy the second value (not the full CRN)
URL is a Key Protect endpoint. To get the endpoint, see http://ibm.biz/kp-endpoints
AccountID stores the ID of the account where the key protect instance resides Its value can be either: the same account ID the given cluster resides in (non cross account use case) not the clusters account ID in which the KMS instance resides (cross account use case) empty, in case of old clusters which were secret encrypted before this AccountID field was added to this struct. This case falls back to the first point and should be handled like that (non cross account use case)
The correlation ID stores the correlation ID used to trace a CRK call through multiple services
ServiceToService indicates the KP information in this record was enabled via service-to-service integration, so an associated registration was created.
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 thenibmcloud 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 runibmcloud 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
Refresh the Kubernetes master.
Restart the Kubernetes master in the cluster to apply changes to the API server configuration.
PUT /v1/clusters/{idOrName}/masters
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 runibmcloud ks cluster ls
.
The master state. Currently, refresh
is supported.
The action to perform on the API Server.
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 thenibmcloud 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 runibmcloud 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
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
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 runibmcloud 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 thenibmcloud 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 runibmcloud 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
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
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 runibmcloud 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 thenibmcloud 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 runibmcloud 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
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}
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 runibmcloud 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 thenibmcloud 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 runibmcloud ks cluster ls
. To view available Kubernetes namespaces, runkubectl 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
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}
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 runibmcloud 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 runibmcloud 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 runibmcloud 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 thenibmcloud 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 runibmcloud ks cluster ls
. To list bound IBM Cloud services and their namespaces, use theGET /v1/clusters/{nameOrId}/services
API or runibmcloud 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
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
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 runibmcloud ks cluster ls
.
Response
VlanConfigField TODO provide meaningful comment
SubnetConfigField TODO provide a 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 thenibmcloud 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 runibmcloud 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
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}
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 thePOST 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 thePOST /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 runibmcloud 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 thenibmcloud 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 runibmcloud 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
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}
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 runibmcloud 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 thenibmcloud 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 runibmcloud 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
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
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 runibmcloud ks cluster ls
.
Response
VlanConfigField TODO provide meaningful comment
SubnetConfigField TODO provide a 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 thenibmcloud 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 runibmcloud 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
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
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 thePOST 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 thePOST /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 runibmcloud ks cluster ls
.
Pass the CIDR of your user-managed subnet and the ID of an available private VLAN in the body.
The subnet and the CIDR that you want to add to the cluster in the format 12.34.45.78/24.
The private VLAN ID that the subnet CIDR belongs to.
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 thenibmcloud 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 runibmcloud 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
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}
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 runibmcloud 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 thenibmcloud 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 runibmcloud 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
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}
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 thePOST 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 thePOST /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 runibmcloud ks cluster ls
.The VLAN in which to create the subnet. To list available VLANs, use the
GET /v1/datacenters/{datacenter}/vlans
API or runibmcloud 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 thenibmcloud 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 runibmcloud 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
List all webhooks for a cluster.
List all webhooks for a Kubernetes cluster.
GET /v1/clusters/{idOrName}/webhooks
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 runibmcloud ks cluster ls
.
Response
ClusterWebhook webhook info
The notification level that you want to use for the webhook.
The webhook service type.
The webhook URL.
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 thenibmcloud 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 runibmcloud 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
Add a webhook to a cluster.
Add a webhook, such as for Slack, to a Kubernetes cluster.
POST /v1/clusters/{idOrName}/webhooks
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 runibmcloud 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.
The notification level that you want to use for the webhook.
The webhook service type.
The webhook URL.
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 thenibmcloud 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 runibmcloud 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
List the worker pools in a cluster.
List all the worker pools that you have in a cluster.
GET /v1/clusters/{idOrName}/workerpools
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 runibmcloud ks cluster ls
.
Response
WorkerPoolResponse provides worker pool data
labels
WorkerPoolZoneResponse response contents for zone
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 thenibmcloud iam oauth-tokens
.Not found. The specified cluster could not be found. To list all the clusters, use the
GET /v1/clusters
API or runibmcloud 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.