Delete the autoscaling configuration for an ALB.
DELETE /ingress/v2/clusters/{idOrName}/albs/{albID}/autoscale
Delete an autoscaling configuration for the ALB. Deleting the configuration disables autoscaling.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
You must have the Editor platform role for the Kubernetes Service in IAM to call this endpoint.
containers-kubernetes.cluster.update
Auditing
Calling this method generates the following auditing event.
cluster-alb-autoscale.unset
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
albID
Required *
string
The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the `GET /clusters/{idOrName}` API or run `ibmcloud ks alb ls --cluster <cluster_name_or_ID>`.
Query Parameters
Response
204 - Ok. Autoscale config was unset successfully.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. No autoscaling configuration set for this cluster and ALB, or the specified cluster or ALB could not be found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get the autoscaling configuration for an ALB.
GET /ingress/v2/clusters/{idOrName}/albs/{albID}/autoscale
Get the autoscaling configuration for an ALB. The autoscaling feature is enabled when there is a configuration set for the ALB. If the configuration is missing, the feature is disabled.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To call this endpoint, you must have the Viewer platform role for the Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
cluster-alb-autoscale.get
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
albID
Required *
string
The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the `GET /clusters/{idOrName}` API or run `ibmcloud ks alb ls --cluster <cluster_name_or_ID>`.
Query Parameters
Response
200 - Ok. The autoscaling configuration for your ALB is returned.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. No autoscale configuration set for this cluster and ALB, or the specified cluster or ALB could not be found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Set the autoscaling configuration for an ALB.
PUT /ingress/v2/clusters/{idOrName}/albs/{albID}/autoscale
Set an autoscaling configuration for an ALB. Setting a configuration enables the autoscaling feature. You can also use this endpoint to change the autoscaling configuration.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
You must have the Editor platform role for the Kubernetes Service in IAM to call this endpoint.
containers-kubernetes.cluster.update
Auditing
Calling this method generates the following auditing event.
cluster-alb-autoscale.set
Request
Request Body
AutoscaleDetails
New autoscale configuration to be set.
config
AutoscaleConfig
AutoscaleConfig is used for configuring autoscaling for albs
cpuAverageUtilization
integer
customMetrics
string
maxReplicas
integer
minReplicas
integer
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
albID
Required *
string
The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the `GET /clusters/{idOrName}` API or run `ibmcloud ks alb ls --cluster <cluster_name_or_ID>`.
Query Parameters
Response
200 - Ok. The provided autoscaling configuration for your ALB is set.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The the specified cluster or ALB could not be found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create an Ingress domain for a cluster.
POST /ingress/v2/dns/createDomain
Create an Ingress domain for a cluster.
Request
Request Body
CreateDomainReq
Input parameter to create a domain.
cluster
string
crn
string
hostname
string
ips
array
isDefault
boolean
provider
string
secretNamespace
string
zoneID
string
Path Parameters
Query Parameters
Response
201 - Created. The domain is created.
certProvider
string
cluster
string
crn
string
dnsType
string
isDefault
boolean
lbHostname
string
nlbIPArray
array
nlbSubdomain
string
provider
string
secretNamespace
string
statusMessage
string
type
string
zoneID
string
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Deprecated: Delete external domain provider credential.
POST /ingress/v2/dns/deleteCredential
Deprecated: Delete the registered external provider credential for a cluster.
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Response
204 - No Content. The credential was successfully fetched.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Delete a non-default Ingress domain for a cluster.
POST /ingress/v2/dns/deleteDomain
Delete a non-default Ingress domain for a cluster.
Request
Request Body
DeleteDomainReq
Input parameter to delete a domain.
cluster
string
subdomain
string
Path Parameters
Query Parameters
Response
200 - Ok. The domain is deleted.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Deprecated: Get external domain provider credential metadata.
GET /ingress/v2/dns/getCredential
Deprecated: Get metadata for the registered external provider credential for a cluster.
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Response
200 - Ok. The credential was successfully fetched.
cluster
string
credID
string
expiresOn
string
lastUpdatedTimestamp
string
provider
string
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Replace the existing default Ingress domain for a cluster.
POST /ingress/v2/dns/replaceDefaultSubdomain
Replace the default Ingress domain for a cluster and refresh the related cluster components.
Request
Request Body
ReplaceDefaultSubdomainReq
Input parameter to replace default domain.
cluster
string
subdomain
string
Path Parameters
Query Parameters
Response
200 - Ok. The default domain is replaced.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Deprecated: Set external domain provider credential.
POST /ingress/v2/dns/setCredential
Deprecated: Register a credential for external domain provider for use in ingress domain commands.
Request
Request Body
CreateCredentialReq
Input parameter to register an external domain provider credential.
akamai_credentials
AkamaiCredentials
AkamaiCredentials is the struct representation of Akamai creds
access_token
string
client_secret
string
client_token
string
host
string
zone
string
cloudflare_credentials
CloudflareCredentials
CloudflareCredentials is the struct representation of Cloudflare creds
token
string
zone_id
string
cluster
string
provider
string
Path Parameters
Query Parameters
Response
201 - Created. The credential was successfully registered.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Update an Ingress domain for a cluster.
POST /ingress/v2/dns/updateDomain
Update an Ingress domain with the specified IPs or hostnames.
Request
Request Body
UpdateDomainReq
Input parameter to update a domain.
cluster
string
domain
string
hostname
string
ips
array
Path Parameters
Query Parameters
Response
200 - Ok. The domain is updated.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get configuration of load balancers for Ingress ALBs.
GET /ingress/v2/load-balancer/configuration
Get settings for load balancers that expose Ingress ALBs in your cluster.
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster.
type
Required *
string
Type of load balancer configuration to return. Possible options are `public` and `private`.
Response
200 - Ok. The load balancer configuration for the specified type is returned.
backend
LBBackendConfig
LBBackendConfig stuct for configuring the loadbalancer's backend
cluster
string
proxyProtocol
LBProxyProtocolConfig
LBProxyProtocolConfig stuct for storing the loadbalancer's proxy protocol config in etcd
type
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
PATCH /ingress/v2/load-balancer/configuration
Configure settings for load balancers that expose Ingress ALBs in your cluster. After you use this API to set load balancer options, the existing load balancers are deleted and recreated, which can cause service disruptions. Two unused IP addresses for each new load balancer must be available in each subnet during the load balancer recreation. To configure load balancers that expose only your public ALBs or only your private ALBs, specify `public` or `private` for the `type` field in the request body. If you leave the `type` field empty, the configuration is applied to all load balancers that expose ALBs in the cluster.
Available features: + `proxyProtocol`: + Limitations: + This feature is supported only for VPC Gen 2 clusters that run Kubernetes version 1.18 or later. + This feature is cluster-level, therefore `type` field of the request must be empty. + Configuration: + `enable`: Set to `true` to enable or `false` to disable the PROXY protocol for the ALB load balancers. The PROXY protocol enables load balancers to pass client connection information that is contained in headers on the client request, including the client IP address, the proxy server IP address, and both port numbers, to ALBs. + `headerTimeout`: The timeout value, in seconds, for the load balancer to receive the PROXY protocol headers that contain the client connection information. This option has effect only on ALBs running the Kubernetes Ingress image. Default: `5` + `cidr`: Load balancer CIDRs from which ALBs process information in PROXY protocol headers. If requests that contain PROXY headers originate from load balancers in other IP ranges, the information in the headers is not process by the ALB. This option has effect only on ALBs running the Kubernetes Ingress image. Default: `0.0.0.0/0`
Request
Request Body
LBConfig
In the request body, specify the desired configuration of load balancer features you want to change.
backend
LBBackendConfig
LBBackendConfig stuct for configuring the loadbalancer's backend
private
string
public
string
cluster
string
proxyProtocol
LBProxyProtocolConfig
LBProxyProtocolConfig stuct for storing the loadbalancer's proxy protocol config in etcd
cidr
array
enable
boolean
headerTimeout
integer
type
string
Path Parameters
Query Parameters
Response
202 - Load-balancer configuration submitted and update started.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
423 - Locked. The previous load-balancer configuration is still in progress.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Add fields to an Ingress secret with a secret stored in IBM Cloud Secrets Manager.
POST /ingress/v2/secret/addField
Add fields to an Ingress secret with a secret stored in IBM Cloud Secrets Manager.
Request
Request Body
UpdateConfig
Input parameter to add a secret field.
add
array
cluster
string
crn
string
name
string
namespace
string
remove
array
Path Parameters
Query Parameters
Response
201 - Updated. The fields were successfully added to the secret in the cluster.
cluster
string
crn
string
domain
string
deprecated: use "Domains" instead
domains
array
expiresOn
string
fields
Fields
Fields struct for a secret array
lastUpdatedTimestamp
string
name
string
namespace
string
persistence
boolean
secretType
string
status
string
type
string
userManaged
boolean
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create an Ingress secret with a secret stored in IBM Cloud Secrets Manager.
POST /ingress/v2/secret/createSecret
Create an Ingress secret with a secret stored in IBM Cloud Secrets Manager.
Request
Request Body
CreateConfig
Input parameter to add a secret.
add
array
cluster
string
crn
string
name
string
namespace
string
persistence
boolean
type
string
Path Parameters
Query Parameters
Response
201 - Created. The secret was successfully created in the cluster.
cluster
string
crn
string
domain
string
deprecated: use "Domains" instead
domains
array
expiresOn
string
fields
Fields
Fields struct for a secret array
lastUpdatedTimestamp
string
name
string
namespace
string
persistence
boolean
secretType
string
status
string
type
string
userManaged
boolean
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Delete an Ingress secret from the cluster.
POST /ingress/v2/secret/deleteSecret
Delete an Ingress secret from the cluster.
Request
Request Body
DeleteConfig
Input parameter to add a secret.
cluster
string
name
string
Path Parameters
Query Parameters
Response
204 - Deleted. The secret was successfully deleted from the cluster.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View an IBM Cloud Secrets Manager instance registered to the cluster.
GET /ingress/v2/secret/getInstance
View an IBM Cloud Secrets Manager instance registered to the cluster.
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
name
Required *
string
The name of the instance that you want information about. To list the instances that you have access to, use the `GET /ingress/v2/secret/getInstances` API or run `ibmcloud ks ingress secret instance ls`.
Response
200 - Ok. Detailed information about the secret is returned.
callbackChannel
string
cluster
string
crn
string
isDefault
boolean
name
string
secretGroupID
string
secretGroupName
string
status
string
type
string
userManaged
boolean
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View IBM Cloud Secrets Manager instances registered to the cluster.
GET /ingress/v2/secret/getInstances
View IBM Cloud Secrets Manager instances registered to the cluster.
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
showDeleted
string
To view previously deleted instances, pass `true`.
Response
200 - Ok. The list of available Ingress secrets is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View Ingress secret details.
GET /ingress/v2/secret/getSecret
View Ingress secret details.
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
name
Required *
string
The name of the secret that you want information about. To list the secrets that you have access to, use the `GET /ingress/v2/secret/getSecrets` API or run `ibmcloud ks ingress secret ls`.
namespace
Required *
string
The namespace of the secret that you want information about. To list the secrets that you have access to, use the `GET /ingress/v2/secret/getSecrets` API or run `ibmcloud ks ingress secret ls`.
Response
200 - Ok. Detailed information about the secret is returned.
cluster
string
crn
string
domain
string
deprecated: use "Domains" instead
domains
array
expiresOn
string
fields
Fields
Fields struct for a secret array
lastUpdatedTimestamp
string
name
string
namespace
string
persistence
boolean
secretType
string
status
string
type
string
userManaged
boolean
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View Ingress secrets for a cluster.
GET /ingress/v2/secret/getSecrets
View Ingress secrets for a cluster.
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
showDeleted
string
To view previously deleted secrets, pass `true`.
Response
200 - Ok. The list of available Ingress secrets is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Register an IBM Cloud Secrets Manager instance to the cluster.
POST /ingress/v2/secret/registerInstance
Register an IBM Cloud Secrets Manager instance to the cluster.
Request
Request Body
RegisterConfig
Input parameter to register an instance.
cluster
string
crn
string
isDefault
boolean
secretGroupID
string
Path Parameters
Query Parameters
Response
200 - Created. The instance was successfully registered to the cluster.
callbackChannel
string
cluster
string
crn
string
isDefault
boolean
name
string
secretGroupID
string
secretGroupName
string
status
string
type
string
userManaged
boolean
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Remove fields from an Ingress secret with a secret stored in IBM Cloud Secrets Manager.
POST /ingress/v2/secret/removeField
Remove fields from an Ingress secret with a secret stored in IBM Cloud Secrets Manager.
Request
Request Body
UpdateConfig
Remove input parameter to remove a secret field.
add
array
cluster
string
crn
string
name
string
namespace
string
remove
array
Path Parameters
Query Parameters
Response
200 - Updated. The fields were successfully removed from the secret in the cluster.
cluster
string
crn
string
domain
string
deprecated: use "Domains" instead
domains
array
expiresOn
string
fields
Fields
Fields struct for a secret array
lastUpdatedTimestamp
string
name
string
namespace
string
persistence
boolean
secretType
string
status
string
type
string
userManaged
boolean
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Unregister an IBM Cloud Secrets Manager instance from the cluster.
POST /ingress/v2/secret/unregisterInstance
Unregister an IBM Cloud Secrets Manager instance from the cluster.
Request
Request Body
DeleteConfig
Input parameter to unregister an instance.
cluster
string
name
string
Path Parameters
Query Parameters
Response
200 - Deleted. The secret was successfully deleted from the cluster.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Update an IBM Cloud Secrets Manager instance registration configuration to the cluster.
POST /ingress/v2/secret/updateInstance
Update an IBM Cloud Secrets Manager instance registration configuration to the cluster.
Request
Request Body
InstanceUpdateConfig
Input parameter to update instance registration.
cluster
string
isDefault
boolean
name
string
secretGroupID
string
Path Parameters
Query Parameters
Response
200 - Update. The instance was successfully updated.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified instance could not be found. To list the registered instances that you have access to, use the `GET /v2/secret/getInstances` API or run `ibmcloud ks ingress secret instance ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Update an Ingress secret with a secret stored in IBM Cloud Secrets Manager.
POST /ingress/v2/secret/updateSecret
Update an Ingress secret with a secret stored in IBM Cloud Secrets Manager.
Request
Request Body
UpdateConfig
Input parameter to add a secret.
add
array
cluster
string
crn
string
name
string
namespace
string
remove
array
Path Parameters
Query Parameters
Response
201 - Created. The secret was successfully created in the cluster.
cluster
string
crn
string
domain
string
deprecated: use "Domains" instead
domains
array
expiresOn
string
fields
Fields
Fields struct for a secret array
lastUpdatedTimestamp
string
name
string
namespace
string
persistence
boolean
secretType
string
status
string
type
string
userManaged
boolean
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get the configuration of a cluster's port 80 security settings.
GET /ingress/v2/security/port80
Get the configuration of a cluster's port 80 security settings.
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster.
Response
200 - Ok. The port 80 configuration for the specified cluster is returned.
cluster
string
state
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Enable port 80 on the cluster.
PATCH /ingress/v2/security/port80
Enable port 80 on a Kubernetes or Red Hat OpenShift cluster. For clusters created after December 1, 2025, port 80 belonging to the default OpenShift router and Kubernetes ingress is disabled by default. Configure this setting to enable the port.
Request
Request Body
Port80Config
Specify the security setting for port 80.
cluster
string
state
string
Path Parameters
Query Parameters
Response
200 - Port 80 security configuration submitted and update started.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get the OAuth access type for a VPC cluster.
GET /network/v2/oauth-access-type/{idOrName}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
oauth-access-type.get
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - Ok. The OAuth access type for the specified cluster is returned.
oauth_access_type
string
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Set the OAuth access type for a VPC cluster.
POST /network/v2/oauth-access-type/{idOrName}/set
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Editor platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.update
Auditing
Calling this method generates the following auditing event.
oauth-access-type.set
Request
Request Body
OauthAccessTypeJSON
Specify the OAuth access type that you want to use. Accepted values are `vpegw` or `legacy`.
oauth_access_type
string
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
202 - Accepted. The request to set the OAuth access type was successful.
400 - The OAuth access type you specified is not supported.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Modify the outbound traffic protection policy for a VPC cluster using Secure by Default Networking.
POST /network/v2/outbound-traffic-protection
Request
Request Body
OutboundTrafficProtectionRequest
Specify the outbound traffic protection policy for your cluster. Available options are `enable-outbound-protection` and `disable-outbound-protection`.
cluster
string
operation
string
Path Parameters
Query Parameters
Response
202 - Accepted. The request to set the outbound traffic protection policy was successful.
400 - Bad request. The query parameters are either incomplete or in the wrong format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Disable the subnet allowlist for a Satellite cluster's service endpoint.
DELETE /network/v2/satellite-acl/{idOrName}
Disable the subnet allowlist feature for a Satellite cluster's service endpoint. After you disable this feature, authorized requests to your Satellite cluster master through the Satellite cluster's service endpoint can originate from any subnet.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the Satellite cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
202 - Accepted. The request to disable the Satellite allowlist feature for your Satellite cluster's service endpoint was successfully processed.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get a Satellite cluster's service endpoint allowlist.
GET /network/v2/satellite-acl/{idOrName}
List all subnets in the Satellite allowlist for a Satellite cluster's service endpoint. This list includes subnets that you manually added by using the `PATCH /network/v2/satellite-acl/{idOrName}/add` API and subnets that are automatically added and managed by IBM, such as worker node subnets.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the Satellite cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - Ok. The allowlist for the Satellite cluster's service endpoint is returned.
actualCSEACLList
array
desiredCSEACLList
array
400 - Bad request. Satellite Service Endpoint Allowlist feature is disabled on the specified cluster.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Add subnets to a Satellite cluster's service endpoint allowlist.
PATCH /network/v2/satellite-acl/{idOrName}/add
When you add a subnet to a disabled Satellite cluster's service endpoint allowlist, the Satellite allowlist is automatically enabled. Only authorized requests to your Satellite cluster master that originate from subnets in this allowlist are permitted through the Satellite cluster's service endpoint. The subnets for your Satellite cluster's worker nodes must be added to this allowlist for the worker nodes to communicate with the master through the Satellite service endpoint.
Request
Request Body
csePatchACL
The list of subnets to add to the Satellite cluster's service endpoint allowlist.
aclList
array
The ACL list to patch
Path Parameters
idOrName
Required *
string
The name or ID of the Satellite cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
201 - Created. The subnets are successfully added to the Satellite cluster's service endpoint allowlist.
204 - No content. The subnets are successfully added to the Satellite cluster's service endpoint allowlist.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Enable the subnet allowlist for a Satellite cluster's service endpoint.
POST /network/v2/satellite-acl/{idOrName}/enable
Enable the subnet allowlist feature for a Satellite cluster's service endpoint. After you enable this feature, you can use the `PATCH /network/v2/satellite-acl/{idOrName}/add` API to add subnets to the allowlist for this Satellite cluster's service endpoint. Only authorized requests to your Satellite cluster master that originate from subnets in the allowlist are permitted through the Satellite cluster's service endpoints.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the Satellite cruiser. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
202 - Accepted. The request to enable the allowlist feature for your Satellite cluster's service endpoint was successfully processed.
400 - Bad request. The Satellite service endpoint allowlist feature is already enabled on the specified cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Remove subnets from a Satellite cluster's service endpoint allowlist.
PATCH /network/v2/satellite-acl/{idOrName}/rm
Remove subnets that you previously added to the allowlist for a Satellite cluster's service endpoint. After a subnet is removed, any requests that originate from this subnet to the Satellite cluster master through the service endpoint are denied.
Request
Request Body
csePatchACL
The list of subnets to remove from the Satellite cluster's service endpoint allowlist.
aclList
array
The ACL list to patch
Path Parameters
idOrName
Required *
string
The name or ID of the Satellite cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
202 - Accepted. The subnets are successfully removed from the Satellite cluster's service endpoint allowlist.
204 - No content. The subnets are successfully removed from the Satellite cluster's service endpoint allowlist.
400 - Bad request. Satellite Service Endpoint Allowlist feature is disabled on the specified cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Enable VPC Secure by Default Networking on an existing VPC cluster.
POST /network/v2/secure-by-default/enable
Request
Request Body
EnableSecureByDefaultClusterRequest
Enable a one-way migration to Secure by Default Networking on an existing VPC cluster currently using legacy security groups. Available options for `disableOutboundTrafficProtection` are `true` or `false`.
cluster
string
disableOutboundTrafficProtection
boolean
Path Parameters
Query Parameters
Response
202 - Accepted. The request to enable Secure by Default Networking was successful.
400 - Bad request. The query parameters are either incomplete or in the wrong format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Perform operations against a VPC Security Group associated with a cluster.
POST /network/v2/security-group
Request
Request Body
SecurityGroupRequest
Perform an operation against a VPC security group associated with a cluster. Currently supported operations are `reset` or `sync`.
cluster
string
operation
string
securityGroupID
string
Path Parameters
Query Parameters
Response
202 - Accepted. The requested security group operation was successfully processed.
400 - Bad request. The query parameters are either incomplete or in the wrong format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List all security groups associated with a cluster.
GET /network/v2/security-group/getSecurityGroups
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
type
string
Filter security groups by type. Specify `cluster`, `worker`, `vpc`, `vpegw`, or `lbaas`.
shared
string
Specify `true` to return the security groups that are shared across the VPC. Or, specify `false` to return only the cluster specific security groups.
userProvided
string
Specify `true` to return the security groups created by user. Specify `false` to return only the IKS managed security groups.
Response
200 - Ok. A list of security groups associated with the cluster is returned.
400 - Bad request. The query parameters are either incomplete or in the wrong format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
DELETE /v1/acl/{idOrName}
Disable the subnet allowlist for a cluster's private service endpoint.
Disable the subnet allowlist feature for a cluster's private service endpoint. After you disable this feature, authorized requests to your cluster master through the cluster's private service endpoint can originate from any subnet.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
202 - Accepted. The request to disable the allowlist feature for your cluster's private service endpoint was successfully processed.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
GET /v1/acl/{idOrName}
Get a cluster's private service endpoint allowlist.
List all subnets in the allowlist for a cluster's private service endpoint. This list includes subnets that you manually added by using the `PATCH /v1/acl/{idOrName}/add` API and subnets that are automatically added and managed by IBM, such as worker node subnets.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - Ok. The allowlist for the cluster's private service endpoint is returned.
actualCSEACLList
CSEACLList
CSEACLList actual and desired
desiredCSEACLList
CSEACLList
CSEACLList actual and desired
400 - Bad request. Private Service Endpoint Allowlist feature is disabled on the specified cluster.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
PATCH /v1/acl/{idOrName}/add
Add subnets to a cluster's private service endpoint allowlist.
After you use the `POST /v1/acl/{idOrName}/enable` API to enable an allowlist for your cluster's private service endpoint, add subnets to the allowlist. Only authorized requests to your cluster master that originate from subnets in this allowlist are permitted through the cluster's private service endpoint. By default, subnets for your cluster's worker nodes are added to this allowlist so that worker nodes can communicate with the master through the private service endpoint.
Request
Request Body
csePatchACL
The list of subnets to add to the cluster's private service endpoint allowlist.
aclList
array
The ACL list to patch
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
201 - Created. The subnets are successfully added to the cluster's private service endpoint allowlist.
204 - No content. The subnets are successfully added to the cluster's private service endpoint allowlist.
400 - Bad request. Private Service Endpoint Allowlist feature is disabled on the specified cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
POST /v1/acl/{idOrName}/enable
Enable a subnet allowlist for a cluster's private service endpoint.
Enable the subnet allowlist feature for a cluster's private service endpoint. After you enable this feature, you can use the `PATCH /v1/acl/{idOrName}/add` API to add subnets to the allowlist for this cluster's private service endpoint. Only authorized requests to your cluster master that originate from subnets in the allowlist are permitted through the cluster's private service endpoint. If the public service endpoint is enabled for your cluster, authorized requests are still permitted through the public service endpoint.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
202 - Accepted. The request to enable the allowlist feature for your cluster's private service endpoint was successfully processed.
400 - Bad request. The private service endpoint allowlist feature is already enabled on the specified cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
PATCH /v1/acl/{idOrName}/rm
Remove subnets from a cluster's private service endpoint allowlist.
Remove subnets that you previously added to the allowlist for a cluster's private service endpoint. After a subnet is removed, any requests that originate from this subnet to the cluster master through the private service endpoint are denied.
Request
Request Body
csePatchACL
The list of subnets to remove from the cluster's private service endpoint allowlist.
aclList
array
The ACL list to patch
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
202 - Accepted. The subnets are successfully removed from the cluster's private service endpoint allowlist.
204 - No content. The subnets are successfully removed from the cluster's private service endpoint allowlist.
400 - Bad request. Private Service Endpoint Allowlist feature is disabled on the specified cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List available add-ons that you can enable in a cluster.
GET /v1/addons
List available add-ons that you can enable in a cluster. For each available add-on, the name, latest version, and minimum Kubernetes version required to run the add-on in a cluster are returned.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
No IBM Cloud IAM role is required for this operation.
- ``
Auditing
Calling this method generates the following auditing event.
- ``
Request
Path Parameters
Query Parameters
Response
200 - OK. The name, latest version, and minimum required Kubernetes version for each available add-on are returned.
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Enable an existing ALB in a cluster.
POST /v1/alb/albs
Enable a public or private ALB in your standard cluster.
Request
Request Body
ALBConfig
The input parameter to enable an ALB. In the `albip` field, you can optionally specify an IP address that is on a VLAN in the zone that the ALB was created in. The ALB is enabled with and uses this public or private IP address. Note that this IP address must not be in use by another load balancer or ALB in the cluster. If no IP address is provided, the ALB is deployed with a public or private IP address from the portable public or private subnet that was provisioned automatically when you created the cluster, or the public or private IP address that you previously assigned to the ALB. To switch your ALB from one type of image to another, such as from an IBM Cloud Kubernetes Service ALB image to a community Kubernetes Ingress controller image, specify that image version in the ALBBuild field. To see the supported image versions, use the `GET /v2/alb/getAlbImages` call. For more information, see https://ibm.biz/alb_configure_docs
albBuild
string
The build number of the ALB.
albID
string
The ID of the application load balancer (ALB).
albType
string
The type of ALB.
authBuild
string
The auth build of the ALB.
cluster
string
createdDate
string
The date the ALB was created.
disableDeployment
boolean
If set to true, the deployment of the ALB is disabled.
enable
boolean
Set to true to enable the ALB, or false to disable the ALB for the cluster.
loadBalancerHostname
string
name
string
The name of the cluster that the ALB belongs to.
numOfInstances
string
Desired number of ALB replicas that you want in your cluster.
resize
boolean
If set to true, resizing of the ALB is done.
state
string
The state of the ALB.
status
string
The status of the ALB.
zone
string
The zone where you want to add ALBs.
Path Parameters
Query Parameters
Response
201 - Enabled. The ALB for the cluster was successfully enabled.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or ALB could not be found. To list the clusters that you have access to, run `ibmcloud ks cluster ls`. To list the ALBs available in a cluster, use the `GET /clusters/{idOrName}` API or run `ibmcloud ks alb ls --cluster <cluster_name_or_ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Disable an ALB in your cluster.
DELETE /v1/alb/albs/{albID}
Disable a public or private ALB in your standard cluster. When you disable an ALB, the IP address that the ALB used goes back into the pool of available portable IPs so that another service can use the IP. If you later try to re-enable the ALB, the ALB might report an error if the IP address it previously used is now in use by another service. You can either stop running the other service or specify another IP address to use when you re-enable the ALB.
Request
Path Parameters
albID
Required *
string
The ID of the ALB that you want to disable. To list the IDs for the ALBs in a cluster, use the `GET /v1/alb/clusters/{idOrName}` API or run `ibmcloud ks alb ls --cluster <cluster_name_or_ID>`.
Query Parameters
Response
204 - Disabled. The ALB for the cluster was successfully disabled.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or ALB could not be found. To list the clusters that you have access to, run `ibmcloud ks cluster ls`. To list the ALBs available in a cluster, use the `GET /clusters/{idOrName}` API or run `ibmcloud ks alb ls --cluster <cluster_name_or_ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details of an ALB.
GET /v1/alb/albs/{albID}
View detailed information for an ALB in a cluster.
Request
Path Parameters
albID
Required *
string
The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the `GET /clusters/{idOrName}` API or run `ibmcloud ks alb ls --cluster <cluster_name_or_ID>`.
Query Parameters
Response
200 - Ok. Details for the specified ALB are returned.
albBuild
string
The build number of the ALB.
albID
string
The ID of the application load balancer (ALB).
albType
string
The type of ALB.
authBuild
string
The auth build of the ALB.
cluster
string
createdDate
string
The date the ALB was created.
disableDeployment
boolean
If set to true, the deployment of the ALB is disabled.
enable
boolean
Set to true to enable the ALB, or false to disable the ALB for the cluster.
loadBalancerHostname
string
name
string
The name of the cluster that the ALB belongs to.
numOfInstances
string
Desired number of ALB replicas that you want in your cluster.
resize
boolean
If set to true, resizing of the ALB is done.
state
string
The state of the ALB.
status
string
The status of the ALB.
zone
string
The zone where you want to add ALBs.
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or ALB could not be found. To list the clusters that you have access to, run `ibmcloud ks cluster ls`. To list the ALBs available in a cluster, use the `GET /clusters/{idOrName}` API or run `ibmcloud ks alb ls --cluster <cluster_name_or_ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List all ALBs in a cluster.
GET /v1/alb/clusters/{idOrName}
List all ALB IDs in a cluster. If no ALB IDs are returned, then the cluster does not have a portable subnet.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster that you want to see ALB information for. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - Ok. A list of ALB IDs for the cluster is returned.
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Force a one-time update of all ALB pods to the latest build.
PUT /v1/alb/clusters/{idOrName}/update
If automatic updates for Ingress ALBs are disabled, you can force a one-time update of your ALB pods. When you choose to manually update the ALBs, all ALB pods in the cluster are updated to the latest build. You cannot update an individual ALB or choose which build to update the ALBs to. Automatic updates remain disabled.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - Ok. The update has been requested.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Check if automatic updates for Ingress ALBs are enabled in a cluster.
GET /v1/alb/clusters/{idOrName}/updatepolicy
Check if automatic updates for Ingress ALBs are enabled and whether your ALB pods are updated to the latest build version.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - Ok. The current update policy.
autoUpdate
boolean
If set to true, automatic updates for the ALBs are enabled.
latestVersion
boolean
If set to true, all ALBs in the cluster run the latest ALB version.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Enable or disable automatic updates for the Ingress ALBs in a cluster.
PUT /v1/alb/clusters/{idOrName}/updatepolicy
By default, automatic updates to Ingress ALBs are enabled. ALB pods are automatically updated when a new build version is available. To instead update the Ingress ALB component manually, you can use this call to disable automatic updates, then use the `PUT /clusters/{idOrName}/update` call to update all ALB pods. Note: When you update the major or minor Kubernetes version of your cluster, IBM automatically makes necessary changes to the Ingress deployment, but does not change the build version of your Ingress ALBs. You are responsible for checking the compatability of the latest Kubernetes versions and your Ingress ALB add-on images. If automatic updates for the Ingress ALB component are disabled, you can re-enable automatic updates. Whenever the next build version becomes available, the ALBs are automatically updated to the latest build.
Request
Request Body
UpdatePolicy
The new update policy configuration.
autoUpdate
boolean
If set to true, automatic updates for the ALBs are enabled.
latestVersion
boolean
If set to true, all ALBs in the cluster run the latest ALB version.
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
204 - Ok. The ALB update policy has been changed.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create a public or private ALB in a specified zone and VLAN.
POST /v1/alb/clusters/{idOrName}/zone/{zoneId}
Create a new public or private ALB in a specified zone on a specified VLAN. You can also optionally specify an IP address on that VLAN in that zone for the ALB to use.
Request
Request Body
ALB
The input parameters to create an ALB. For more information, see https://ibm.biz/alb_create_docs
enableByDefault
boolean
If set to true, the ALB is enabled by default. \
ingressImage
string
The type of Ingress image that you want to use for your ALB deployment.
ip
string
Optional: The IP address that you want to assign to the ALB.
nlbVersion
string
The version of the network load balancer that you want to use for the ALB.
type
string
The type of ALB that you want to create.
vlanID
string
The VLAN ID that you want to use for your ALBs.
zone
string
The zone where you want to deploy the ALB.
Path Parameters
idOrName
Required *
string
The name or ID of the cluster that you want to see ALB information for. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
zoneId
Required *
string
The zone in which you want to create an ALB. To see the zones where you can create an ALB, run `ibmcloud ks cluster-get --cluster <cluster_name_or_ID>` and look for the `Worker Zones` field in the output.
Query Parameters
Response
201 - The ALB was successfully created.
alb
string
cluster
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or zone could not be found. To list the clusters that you have access to, run `ibmcloud ks cluster ls`. To list the zones available in a cluster, use the `GET /v1/clusters/{idOrName}` API or run `ibmcloud ks cluster-get --cluster <cluster_name_or_ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List the clusters that you have access to.
GET /v1/clusters
List the clusters that you have access to.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster.list
Request
Path Parameters
Query Parameters
location
string
Specify a location to filter clusters for. To see supported locations, use the `GET /v1/locations` API or run `ibmcloud ks locations`.
showResources
string
To view additional cluster resources like addons, VLANs, subnets, and storage, pass `true`.
Response
200 - Success. A list of clusters that you have access to is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create a cluster.
POST /v1/clusters
Create a cluster in the IBM Cloud account that you are logged into. Note: This API method requires Administrator platform role for IBM Cloud Kubernetes Service at the account level, as well as access to several other services such as the underlying infrastructure provider. For more information, see 'https://ibm.biz/cluster-perms'.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.
containers-kubernetes.cluster.create
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster.create
Request
Request Body
ClusterConfig
Input parameter to add a cluster. For more information, see https://ibm.biz/cluster_create_docs
cseAclEnabled
boolean
dataCenter
string
The data center where the worker node is created.
defaultWorkerPoolEntitlement
string
defaultWorkerPoolName
string
disableAutoUpdate
boolean
diskEncryption
boolean
gatewayEnabled
boolean
isolation
string
machineType
string
The machine type of the worker node.
masterVersion
string
name
string
networkPlugin
string
noSubnet
boolean
operatingSystem
string
podSubnet
string
podSubnets
string
prefix
string
privateSeviceEndpoint
boolean
privateVlan
string
The private VLAN ID that the worker node is attached to.
publicServiceEndpoint
boolean
publicVlan
string
The public VLAN ID that the worker node is attached to.
serviceSubnet
string
skipPermPrecheck
boolean
trustedProfileID
string
vpcNativeRoutingEnabled
boolean
workerNum
integer
Path Parameters
Query Parameters
Response
201 - Created. The cluster was successfully created in the IBM Cloud account that you are logged in to.
id
string
non_critical_errors
ResponseErrors
ResponseErrors are used to communicate to non-critical errors to end users
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. A cluster with the same name already exists. Choose another name for your cluster.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Delete a cluster.
DELETE /v1/clusters/{idOrName}
Delete a cluster from the IBM Cloud account that you are logged in to. When you delete a cluster, all worker nodes, apps, and containers are permanently deleted. This action cannot be undone.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.create
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster.delete
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster that you want to remove. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
deleteResources
string
To delete additional resources linked to the cluster such as VLANs, subnets, and storage, pass `true`.
skipPermissionsPrecheck
string
To skip checking for infrastructure permissions before completing this action, pass 'true'. Note that if you do not have the correct infrastructure permissions, this action might only partially succeed.
deleteOpenShiftRegistryCOSBucket
string
To delete the COS bucket and the associated service key that holds OpenShift registry backups, pass `true`
Response
204 - Ok. The cluster was successfully removed from the IBM Cloud account that you are logged in to.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details for a cluster.
GET /v1/clusters/{idOrName}
View detailed information for a cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster.get
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
showResources
string
To view additional cluster resources like addons, VLANs, subnets, and storage, pass `true`.
Response
200 - Ok. Detailed information about the cluster is returned.
addons
array
apiUser
string
createdDate
string
crn
string
dataCenter
string
desiredTrustedProfileID
string
disableAutoUpdate
boolean
etcdPort
string
id
string
ignitionServerURL
string
imageSecurityEnabled
boolean
ingressHostname
string
ingressMessage
string
ingressSecretName
string
ingressStatus
string
isPaid
boolean
keyProtectEnabled
boolean
konnectivityServerURL
string
location
string
logOrg
string
logOrgName
string
logSpace
string
logSpaceName
string
masterHealth
string
masterKubeVersion
string
masterState
string
masterStatus
string
masterStatusModifiedDate
string
modifiedDate
string
monitoringURL
string
multiAzCapable
boolean
name
string
oauthServerURL
string
podSubnet
string
podSubnets
string
privateServiceEndpointEnabled
boolean
privateServiceEndpointURL
string
publicServiceEndpointEnabled
boolean
publicServiceEndpointURL
string
pullSecretApplied
boolean
region
string
resourceGroup
string
resourceGroupName
string
serverURL
string
serviceSubnet
string
state
string
status
string
targetVersion
string
trustedProfileID
string
type
string
versionEOS
string
vlans
array
vpcNativeRoutingEnabled
boolean
workerCount
integer
workerZones
array
worker_vlans
VLANS
VLANS is a helper type to sort an api.VLAN list. The VLANS will sort the list in order of the Properties.PrimaryRouter value so that VLAN's of a common router are listed consecutively.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Update the version of the Kubernetes cluster master node.
PUT /v1/clusters/{idOrName}
Update the Kubernetes master to the default API version. During the update, you cannot access or change the cluster. Worker nodes, apps, and resources that have been deployed by the user are not modified and will continue to run. You might need to change your YAML files for future deployments. For details, see the release notes at https://cloud.ibm.com/docs/containers?topic=containers-cs_versions
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-master.update
Request
Request Body
UpdateMasterCommand
Input parameter to update the Kubernetes master. Set `action` to `update` to update the master. Set `force` to `true` to attempt the update even if the change is greater than two minor versions. Set `version` to the Kubernetes version of the cluster. If you do not specify a version, the Kubernetes master is updated to the default API version. To see available versions, use the `GET /v1/kube-versions` API or run `ibmcloud ks versions`.
action
string
The action to perform on the master.
force
boolean
If set to true, any warnings during the update process are ignored.
version
string
The Kubernetes version to use for the update.
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
204 - Ok. The request to update your master node was successfully processed.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. The specified value is already set on the cluster. To list the clusters properties, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details of the add-ons that are enabled in a cluster.
GET /v1/clusters/{idOrName}/addons
View details of the add-ons that are enabled in a cluster, including the add-on versions.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-addon.list
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - OK. Details for the add-ons in this cluster are returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Enable, disable, or update add-ons for a cluster.
PATCH /v1/clusters/{idOrName}/addons
Enable, disable, or update add-ons for a cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.
containers-kubernetes.cluster.create
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-addon.enablecontainers-kubernetes.cluster-addon.disablecontainers-kubernetes.cluster-addon.update
Request
Request Body
AddonRequest
Input parameters to enable or disable add-ons in your cluster.
addons
Required *
array
The addons to operate on.
enable
boolean
Indicate if the specified addons should be enabled or disabled.
update
boolean
Indicate if the specified addons should be updated. Only Update or Enable should be used, not both.
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - OK. The add-on changes have been processed.
missingDeps
array
The addon enable request would result in an invalid configuration. Install missing addons to continue.
orphanedAddons
object
The addon disable request would result in an invalid configuration. Inspect the map to determine why the configuration is invalid.
400 - Bad request. The input parameters in the request body are not correct. Be sure to include all of the required parameters in your request in the correct JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. The current add-on configuration is not compatible. Check 'MissingDeps' for add-ons to enable in this cluster.
missingDeps
array
The addon enable request would result in an invalid configuration. Install missing addons to continue.
orphanedAddons
object
The addon disable request would result in an invalid configuration. Inspect the map to determine why the configuration is invalid.
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Delete an audit webhook configuration.
DELETE /v1/clusters/{idOrName}/apiserverconfigs/auditwebhook
Disable the webhook backend configuration for the cluster's API server. Diabling the webhook backend stops forwarding API server audit logs to a remote server.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-audit-webhook.delete
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster for which you want to change the audit config. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
204 - Successfully deleted the audit webhook configuration.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details for an audit webhook configuration.
GET /v1/clusters/{idOrName}/apiserverconfigs/auditwebhook
View the URL for the remote logging service that you are sending API server audit logs to.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-audit-webhook.get
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster that you want audit configuration details from. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - Successfully retrieved the audit webhook configuration.
auditServer
string
The URL of the server to send audit logs to.
caCertificate
string
The Certificate Authority certificate that is used to connect to the audit server.
clientCertificate
string
The client certificate that is used to connect to the audit server.
clientKey
string
The client key that is used to connect to the audit server.
policy
string
The audit policy type to be configured.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create or update an audit webhook configuration for a cluster.
PUT /v1/clusters/{idOrName}/apiserverconfigs/auditwebhook
Create or update an audit webhook configuration for a cluster. The webhook sends Kubernetes API server audit logs that allow you to monitor API requests to your cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Editor platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.
containers-kubernetes.cluster.update
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-audit-webhook.update
Request
Request Body
AuditWebhookConfig
The input parameter for creating or updating an audit webhook configuration. For more information, see https://ibm.biz/audit_config_docs
auditServer
string
The URL of the server to send audit logs to.
caCertificate
string
The Certificate Authority certificate that is used to connect to the audit server.
clientCertificate
string
The client certificate that is used to connect to the audit server.
clientKey
string
The client key that is used to connect to the audit server.
policy
string
The audit policy type to be configured.
Path Parameters
idOrName
Required *
string
The name or ID of the cluster where you want to add an audit configuration or change the audit configuration. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
204 - Ok. The cluster will send audit logs to the audit server.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
412 - Precondition failed. The input parameters in the request body are incorrect. Some typical cases include if the audit server is http and certs are provided or if the server is https and not all certs are provided.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get the cluster-specific configuration and certificates.
GET /v1/clusters/{idOrName}/config
Get the cluster-specific Kubernetes configuration data and certificates as a tar file to connect to your cluster and run Kubernetes API calls. To retrieve the administrator certificates and keys, pass `admin` at the end of the path. For example, `/v1/clusters/{idOrName}/config/admin`.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster.config
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster for which you want to download the Kubernetes configuration file and certificates. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
sub
string
The format of the user identity to use in the Kubernetes configuration and policies. Must match the IAM provided user email, up to letter case.
format
string
To format the output in a single YAML file, pass `yaml`.
createNetworkConfig
boolean
Retrieve the Calico network config with the Admin config. This only works against the admin endpoint('/config/admin')
skipRBAC
boolean
Deprecated: Previously this skipped adding the RBAC roles based on user's access in IAM. RBAC is now always applied and completes asynchronously.
Response
200 - Ok. The cluster-specific configuration file and certificates are returned as a zip file.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create and enable a key management service (KMS) provider configuration for a cluster.
POST /v1/clusters/{idOrName}/kms
Create a configuration to enable a key management service (KMS) provider, such as IBM Key Protect, in your cluster. Your customer root key (CRK) from the KMS provider is used to encrypt the Kubernetes secrets within your cluster. After you enable KMS for your cluster, you can update the instance, endpoint, or CRK parameters that are used, but you cannot remove the KMS provider from your cluster. Note on permissions: This API method requires the IBM Cloud IAM Administrator platform role for IBM Cloud Kubernetes Service at the account level. The API key that is used for the region and resource group that the cluster is in requires the appropriate permission to create an instance and CRK in the KMS provider, such as the Editor platform and Writer service role for Key Protect. An additional Reader service-to-service authorization policy between IBM Cloud Kubernetes Service and Key Protect is automatically created for your cluster, if the policy does not already exist. Without this policy, your cluster cannot use all the Key Protect features.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.create
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-service.list
Request
Request Body
KeyProtectData
Input parameters to create the Key Protect config for your cluster. The user specified URL parameter is ignored, because it is fetched from Ghost.
accountID
string
AccountID stores the ID of the account where the key protect instance resides Its value can be either: the same account ID the given cluster resides in (non cross account use case) not the clusters account ID in which the KMS instance resides (cross account use case) empty, in case of old clusters which were secret encrypted before this AccountID field was added to this struct. This case falls back to the first point and should be handled like that (non cross account use case)
correlationID
string
The correlation ID stores the correlation ID used to trace a CRK call through multiple services
crkID
Required *
string
CRK is a Key Protect customer root key. To get the CRK, see http://ibm.biz/kp-viewcrk
instanceID
Required *
string
InstanceID is a Key Protect instance ID. To get the instance ID, run 'ibmcloud resource service-instance <kp_service> --id' and copy the second value (not the full CRN)
serviceToService
boolean
ServiceToService indicates the KP information in this record was enabled via service-to-service integration, so an associated registration was created.
url
Required *
string
URL is a Key Protect endpoint. To get the endpoint, see http://ibm.biz/kp-endpoints
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
201 - OK. Your Key Protect config will be applied to the cluster.
400 - Bad request. The input parameters in the request body are not correct. Be sure to include all of the required parameters in your request in the correct JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. Processing multiple concurrent requests from your account to create a Key Protect config for the cluster. Wait a few minutes and try again.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Refresh the Kubernetes master.
PUT /v1/clusters/{idOrName}/masters
Restart the Kubernetes master in the cluster to apply changes to the API server configuration.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-master.refresh
Request
Request Body
MasterAPIServer
The master state. Currently, `refresh` is supported.
action
string
The action to perform on the API Server.
Path Parameters
idOrName
Required *
string
The name or ID of the cluster that you want to interact with. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
204 - Ok. The Master will be put into the desired state.
400 - Bad Request. Check that all headers are present and that the state is valid. Valid states include `refresh`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List the IBM Cloud services bound to a cluster across all namespaces.
GET /v1/clusters/{idOrName}/services
List the IBM Cloud services that are bound in any Kubernetes namespace in the cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-service.list
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster where you want to list bound IBM Cloud services. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - Ok. A list of IBM Cloud services bound to a cluster across all Kubernetes namespaces is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
404 - Not found. The specified cluster ID or name could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
Bind an IBM Cloud service to a cluster.
POST /v1/clusters/{idOrName}/services
Bind an IBM Cloud service instance to a Kubernetes namespace in your cluster. To view available IBM Cloud services from the IBM Cloud catalog, run `ibmcloud catalog search --kind service`. If you already provisioned IBM Cloud service instances in an IBM Cloud space, you can list them by running `ibmcloud resource service-instances`. Note: You can add only IBM Cloud services that support service keys, and you must add the service in the same resource group that the cluster is in.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Editor platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.update
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-service.bind
Request
Request Body
ServiceBindRequest
The ID of the IBM Cloud service instance that you want to bind. To find the ID of the service instance, use the `GET /v1/clusters/{idOrName}/services` API or run `{[bxcs]} cluster-services <cluster_name_or_ID>`.
namespaceID
string
role
string
serviceInstanceGUID
string
serviceKeyGUID
string
serviceKeyJSON
string
Path Parameters
idOrName
Required *
string
The name or ID of the cluster where you want to bind your service. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
201 - Created. Your IBM Cloud service instance was successfully bound to the Kubernetes namespace of your cluster.
binding
string
namespaceID
string
secretName
string
serviceInstanceGUID
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
List the IBM Cloud services bound to a specific namespace in a cluster.
GET /v1/clusters/{idOrName}/services/{namespace}
List the IBM Cloud services that are bound to a specific Kubernetes namespace in a cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-service.list
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster where you want to list bound IBM Cloud services. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
namespace
Required *
string
The Kubernetes namespace in your cluster where you want to list all bound IBM Cloud services.
Query Parameters
Response
200 - Ok. A list of services bound to a cluster within a specific Kubernetes namespace is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
404 - Not found. The specified Kubernetes namespace or cluster ID/name could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`. To view available Kubernetes namespaces, run `kubectl get namespaces`.
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
Unbind an IBM Cloud service from a cluster.
DELETE /v1/clusters/{idOrName}/services/{namespace}/{serviceInstanceId}
Unbind an IBM Cloud service instance from a Kubernetes namespace in your cluster. Note: When you remove an IBM Cloud service, the service credentials are removed from the cluster. If a pod is still using the service, it fails because the service credentials cannot be found.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Editor platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.update
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-service.unbind
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster where you want to unbind your IBM Cloud service instance. To list bound IBM Cloud services and their namespaces, use the `GET /v1/clusters/{nameOrId}/services` API or run `ibmcloud ks cluster service ls --cluster <cluster_name_or_ID>`.
namespace
Required *
string
The Kubernetes namespace where your IBM Cloud service was bound to. To list bound IBM Cloud services and their namespaces, use the `GET /v1/clusters/{nameOrId}/services` API or run `ibmcloud ks cluster service ls --cluster <cluster_name_or_ID>`.
serviceInstanceId
Required *
string
The name or ID of the IBM Cloud service instance that was bound to your cluster. To list bound IBM Cloud services and their namespaces, use the `GET /v1/clusters/{nameOrId}/services` API or run `ibmcloud ks cluster service ls --cluster <cluster_name_or_ID>`.
Query Parameters
Response
204 - The IBM Cloud service instance was successfully unbound from the Kubernetes namespace of your cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
404 - Not found. The specified cluster, IBM Cloud service instance, or namespace could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`. To list bound IBM Cloud services and their namespaces, use the `GET /v1/clusters/{nameOrId}/services` API or run `ibmcloud ks cluster service ls --cluster <cluster_name_or_ID>`.
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
List classic subnets that are bound to a cluster.
GET /v1/clusters/{idOrName}/subnets
List subnets from your IBM Cloud classic infrastructure account that are bound to a cluster. Before you can call this API method, a one-time per account `POST /v1/credentials` is required.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-subnet.list
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - Ok. A list of user-managed subnets that are bound to your cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Detach a public or private portable subnet from a cluster.
PATCH /v1/clusters/{idOrName}/subnets/{subnetId}
Detach a subnet in your IBM Cloud classic infrastructure account from a cluster. The subnet remains available in your infrastructure account after it is detached.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-subnet.detach
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster that you want to remove the subnet from. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
subnetId
Required *
string
The ID of the subnet that you want to remove from your cluster.
Query Parameters
Response
204 - Ok. The specified subnet was successfully removed from your cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Add an IBM Cloud classic infrastructure subnet to a cluster.
PUT /v1/clusters/{idOrName}/subnets/{subnetId}
Make an existing IBM Cloud classic infrastructure subnet available to an existing cluster. Note: When you make a subnet available to a cluster, IP addresses of this subnet are used for cluster networking purposes. To avoid IP address conflicts, make sure that you use a subnet with one cluster only. Do not use a subnet for multiple clusters or for other purposes outside of Kubernetes Service at the same time.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.subnet.add
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster that you want to make an existing subnet available to. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
subnetId
Required *
string
The ID of the subnet in your IBM Cloud infrastructure account that you want to add to your cluster. To list available subnets, run `ibmcloud ks subnets`.
Query Parameters
Response
204 - Ok. The specified subnet was successfully made available to your cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List user-managed subnets that are bound to a cluster.
GET /v1/clusters/{idOrName}/usersubnets
List user-managed subnets that are bound to a cluster. Note that user-managed subnets are deprecated.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-user-subnet.list
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - Ok. A list of user-managed subnets that are bound to your cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Add an existing user-managed subnet to a cluster.
POST /v1/clusters/{idOrName}/usersubnets
Make your own private subnet available to an Kubernetes Service cluster. This private subnet is not one provided by IBM Cloud infrastructure (SoftLayer). As such, you must configure any inbound and outbound network traffic routing for the subnet. Note: User-managed subnets are deprecated. When you add a private user subnet to a cluster, IP addresses of this subnet are used for private Load Balancers in the cluster. To avoid IP address conflicts, make sure that you use a subnet with one cluster only. Do not use a subnet for multiple clusters or for other purposes outside of Kubernetes Service at the same time.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-user-subnet.add
Request
Request Body
UserSubnet
Pass the CIDR of your user-managed subnet and the ID of an available private VLAN in the body.
cidr
string
The subnet and the CIDR that you want to add to the cluster in the format 12.34.45.78/24.
vlan_id
string
The private VLAN ID that the subnet CIDR belongs to.
Path Parameters
idOrName
Required *
string
The name or ID of the cluster that you want to make your user-managed subnet available to. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
204 - Ok. The specified subnet was successfully made available to your cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Remove a user-managed subnet from a cluster.
DELETE /v1/clusters/{idOrName}/usersubnets/{subnetId}/vlans/{vlanId}
Remove a private user-managed subnet from a cluster. Note: User-managed subnets are deprecated. Any service that was deployed to an IP address from your own private subnet remains active after the subnet is removed.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.vlan.delete
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster that you want to remove the user-managed subnet from. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
subnetId
Required *
string
The GUID of the user-managed subnet that you want to remove from your cluster.
vlanId
Required *
string
The ID of the private VLAN that the user-managed subnet is on.
Query Parameters
Response
204 - Ok. The specified subnet was successfully removed from your cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create an IBM Cloud classic infrastructure subnet and add it to an existing cluster.
POST /v1/clusters/{idOrName}/vlans/{vlanId}
Create an IBM Cloud classic infrastructure subnet and make it available to an existing cluster. Note: When you make a subnet available to a cluster, IP addresses of this subnet are used for cluster networking purposes. To avoid IP address conflicts, make sure that you use a subnet with one cluster only. Do not use a subnet for multiple clusters or for other purposes outside of Kubernetes Service at the same time.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.create
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.subnet.create
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster for which you want to make an existing subnet from your IBM Cloud infrastructure account available. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
vlanId
Required *
string
The VLAN in which to create the subnet. To list available VLANs, use the `GET /v1/datacenters/{datacenter}/vlans` API or run `ibmcloud ks vlan ls <zone>`.
Query Parameters
size
string
The number of subnet IP addresses. The default value is 8. Accepted values are 8, 16, 32, 64.
Response
204 - Ok. The specified subnet was successfully made available to your cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List all webhooks for a cluster.
GET /v1/clusters/{idOrName}/webhooks
List all webhooks for a Kubernetes cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-webhook.list
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster for which you want to list available webhooks. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - Ok. A list of available webhooks for the cluster is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Add a webhook to a cluster.
POST /v1/clusters/{idOrName}/webhooks
Add a webhook, such as for Slack, to a Kubernetes cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Editor platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.update
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-webhook.create
Request
Request Body
ClusterWebhook
Input parameter to create a webhook. Set `level` to the notification level, such as `Normal` or `Warning`. The default value is `Warning`. Set `type` to the webhook service type. Currently `slack` is supported. Set `url` to the URL for the webhook.
level
string
The notification level that you want to use for the webhook.
type
string
The webhook service type.
url
string
The webhook URL.
Path Parameters
idOrName
Required *
string
The name or ID of the cluster that you want to add a webhook to. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
201 - Created. The webhook was successfully added to the cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List the worker pools in a cluster.
GET /v1/clusters/{idOrName}/workerpools
List all the worker pools that you have in a cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool.list
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - OK. The list of worker pools was successfully retrieved.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list all the clusters, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create a worker pool for a cluster.
POST /v1/clusters/{idOrName}/workerpools
Create a worker pool for the specified cluster. Creating a worker pool requires Operator access to Kubernetes Service in the IBM Cloud account.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool.create
Request
Request Body
WorkerPoolRequest
The
diskEncryption
boolean
If set to true, the secondary disk of the worker node is encrypted. If set to false, no encryption is set up.
entitlement
string
isolation
string
labels
object
machineType
string
name
string
operatingSystem
string
sizePerZone
integer
zones
array
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
201 - Created. The worker pool was successfully created in for the specified cluster.
autoscaleEnabled
boolean
id
string
isBalanced
boolean
isolation
string
labels
object
machineType
string
name
string
operatingSystem
string
reasonForDelete
string
region
string
sizePerZone
integer
state
string
zones
WorkerPoolZoneResponses
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. A worker pool create may already be in progress for the provided cluster. Please wait a few minutes and try again.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Remove a worker pool from a cluster.
DELETE /v1/clusters/{idOrName}/workerpools/{poolidOrName}
Remove a worker pool from a cluster. All worker nodes in the pool are deleted. Your pods are rescheduled when you delete. To avoid downtime, be sure that you have enough worker nodes in other worker pools to run your workload.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool.delete
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
poolidOrName
Required *
string
The ID of the worker pool. To list all worker pools for a cluster, use the `GET /v1/clusters/{idOrName}/workerpools` API or run `ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>`.
Query Parameters
Response
204 - OK. The request to remove your worker pool was successfully received.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the `GET /v1/clusters/{idOrName}/workerpools` API or run `ibmcloud ks worker-pool ls mycluster`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details for a worker pool.
GET /v1/clusters/{idOrName}/workerpools/{poolidOrName}
View detailed information for a worker pool.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool.get
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
poolidOrName
Required *
string
The ID of the worker pool. To list all worker pools for a cluster, use the `GET /v1/clusters/{idOrName}/workerpools` API or run `ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>`.
Query Parameters
Response
200 - Ok. Detailed information about the worker pool is returned.
autoscaleEnabled
boolean
id
string
isBalanced
boolean
isolation
string
labels
object
machineType
string
name
string
operatingSystem
string
reasonForDelete
string
region
string
sizePerZone
integer
state
string
zones
WorkerPoolZoneResponses
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the `GET /v1/clusters/{idOrName}/workerpools` API or run `ibmcloud ks worker-pool ls mycluster`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Resize or rebalance a worker pool.
PATCH /v1/clusters/{idOrName}/workerpools/{poolidOrName}
To change the number of worker nodes in a worker pool, you can resize or rebalance the worker pool. When you resize the worker pool, you change the number of worker nodes that are created in each zone of the worker pool. For example, if you set the size per zone to 3 and have 3 zones in the pool, you have 9 worker nodes in total. When you rebalance the worker pool, you return the number of worker nodes in the worker pool to a balanced state. For example, if you remove some worker nodes such as to troubleshoot an issue, you might have an uneven number of nodes across zones. You might delete 2 worker nodes in zone dal13 but still have 3 worker nodes each in zones dal10 and dal12 for a total of 7 worker nodes. To fix this unbalanced state, rebalance the worker pool. After rebalancing, the worker pool has 9 worker nodes again. Rebalancing does not change the size per zone of the worker pool, even if you specify a different size per zone.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool.rebalancecontainers-kubernetes.cluster-worker-pool.resize
Request
Request Body
WorkerPoolPatchRequest
You can change the number of worker nodes by resizing or rebalancing the worker pool. To resize, set parameters `"state"` to `"resizing"` and `"sizePerZone"` to the number of worker nodes that you want in each zone. You can also note why you resize the worker pool in the `"reasonForResize"` string parameter. To rebalance, set parameter `"state"` to `"rebalancing"`. Note that rebalancing does not change the size per zone of the worker pool. To apply a custom label to the worker pool, set the `"state"` field to `"labels"` and fill in the `"labels"` section with your label key-value pairs. When you apply a label, all existing custom labels are replaced. If you have existing custom labels that you want to keep, include them in your request. To remove a custom label, set the `"state"` field to `"labels"` and in the `"labels"` section, include the same `"key"` field, but leave the value field blank `""`. Note that you must not edit the system-provided labels that that come with the worker pool and worker nodes by default, or you might experience unexpected results.
allowSingleOpenShiftWorker
boolean
labels
object
reasonForResize
string
sizePerZone
integer
state
string
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
poolidOrName
Required *
string
The ID of the worker pool. To list all worker pools for a cluster, use the `GET /v1/clusters/{idOrName}/workerpools` API or run `ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>`.
Query Parameters
Response
202 - OK. The request to resize your worker pool was successfully processed.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The request will not be permitted.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the `GET /v1/clusters/{idOrName}/workerpools` API or run `ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Add a zone to the specified worker pool for a cluster.
POST /v1/clusters/{idOrName}/workerpools/{poolidOrName}/zones
Add a zone to the specified worker pool for a cluster. Worker nodes are created in each added zone, based on the requested size per zone of the worker pool details.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool-zone.create
Request
Request Body
WorkerPoolZone
Input parameters to add zones to the worker pool.
id
string
privateVlan
string
publicVlan
string
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
poolidOrName
Required *
string
The ID of the worker pool. To list all worker pools for a cluster, use the `GET /v1/clusters/{idOrName}/workerpools` API or run `ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>`.
Query Parameters
Response
201 - OK. The requested zone has been added to the worker pool.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the `GET /v1/clusters/{idOrName}/workerpools` API or run `ibmcloud ks worker-pool ls mycluster`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. The provided zone already exists in the worker pool.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Remove a zone from a worker pool.
DELETE /v1/clusters/{idOrName}/workerpools/{poolidOrName}/zones/{zoneid}
Remove a zone from a worker pool. All worker nodes for the zone are deleted from the worker pool. To avoid downtime for your apps, make sure that you have enough worker nodes left to reschedule your workloads.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool-zone.delete
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
poolidOrName
Required *
string
The ID of the worker pool. To list all worker pools for a cluster, use the `GET /v1/clusters/{idOrName}/workerpools` API or run `ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>`.
zoneid
Required *
string
The ID of the zone that you want to remove from the worker pool. To list all worker pools for a cluster, use the `GET /v1/zones` API or run `ibmcloud ks zone ls`.
Query Parameters
Response
202 - OK. The request to remove the zone from your worker pool was successfully submitted.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The request will not be permitted.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified worker pool or zone could not be found. To list all worker pool zones, use the `GET /v1/clusters/{idOrName}/workerpools/{poolIdOrName}/zones` API or run `ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Update the network configuration details, such as VLANs, for a zone in the worker pool.
PATCH /v1/clusters/{idOrName}/workerpools/{poolidOrName}/zones/{zoneid}
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool-zone-network.add
Request
Request Body
WorkerPoolZonePatchRequest
Updated network configuration values for the worker pool zone.
privateVlan
string
publicVlan
string
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
poolidOrName
Required *
string
The ID of the worker pool. To list all worker pools for a cluster, use the `GET /v1/clusters/{idOrName}/workerpools` API or run `ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>`.
zoneid
Required *
string
The ID of the worker pool zone. To list all worker pools for a cluster, use the `GET /v1/zones` API or run `ibmcloud ks zone ls`.
Query Parameters
Response
204 - OK. The request to update network configuration for your worker pool was successful.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The request will not be permitted.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified worker pool or zone could not be found. To list all worker pool zones, use the `GET /v1/clusters/{idOrName}/workerpools/{poolIdOrName}/zones` API or run `ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List all worker nodes in a cluster.
GET /v1/clusters/{idOrName}/workers
List all worker nodes and the status of each in a cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker.list
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster for which you want to list all worker nodes. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
pool
string
The name or ID of the worker pool to filter results for. Run `ibmcloud ks worker-pool ls --cluster <cluster name>`.
showDeleted
string
true|false Shows deleted workers
Response
200 - Ok. A list of worker nodes for the specified cluster is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Add worker nodes to a cluster.
POST /v1/clusters/{idOrName}/workers
Add additional worker nodes to a Kubernetes cluster. Note that adding stand-alone worker nodes is deprecated. Instead, resize the worker pool to add worker nodes.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker.add
Request
Request Body
WorkerConfig
Input parameter to add workers to a cluster. For more information, see https://ibm.biz/worker_add_docs
dataCenter
string
The data center where the worker node is created.
diskEncryption
boolean
isolation
string
machineType
string
The machine type of the worker node.
operatingSystem
string
prefix
string
privateVlan
string
The private VLAN ID that the worker node is attached to.
publicVlan
string
The public VLAN ID that the worker node is attached to.
workerNum
integer
Path Parameters
idOrName
Required *
string
The name or ID of the cluster to which you want to add additional worker nodes. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
201 - Ok. Additional worker nodes were successfully added to your cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Delete a worker node from a cluster.
DELETE /v1/clusters/{idOrName}/workers/{workerId}
Delete a worker node from a cluster. This action cannot be undone. When you delete the worker node, the worker node is cordoned and drained so that its pods are rescheduled onto remaining worker nodes in the cluster. Make sure that you have enough capacity in the cluster to support the workload. After you remove the worker node, you can rebalance the worker pool.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.worker.delete
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster to add additional worker nodes to. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
workerId
Required *
string
The ID of the worker node. To list all worker nodes for a cluster, use the `GET /v1/clusters/{idOrName}/workers` API or run `ibmcloud ks worker ls --cluster <cluster_name_or_ID>`.
Query Parameters
Response
204 - Ok. The worker node was successfully removed from your cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details of a worker node.
GET /v1/clusters/{idOrName}/workers/{workerId}
View detailed information for a worker node.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.worker.get
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
workerId
Required *
string
The ID of the worker node that you want details for. To list all worker nodes for a cluster, use the `GET /v1/clusters/{idOrName}/workers` API or run `ibmcloud ks worker ls --cluster <cluster_name_or_ID>`.
Query Parameters
Response
200 - Ok. Detailed information about the worker node is returned.
errorMessage
string
errorMessageDate
string
id
string
isolation
string
kubeVersion
string
location
string
machineType
string
masterVersionEOS
string
pendingOperation
string
poolName
string
poolid
string
privateIP
string
privateVlan
string
publicIP
string
publicVlan
string
reasonForDelete
string
state
string
status
string
statusDate
string
statusDetails
string
targetVersion
string
trustedStatus
string
versionEOS
string
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Reboot, reload, or update a worker node for a cluster.
PUT /v1/clusters/{idOrName}/workers/{workerId}
Reboot, reload, or update a worker node in a Kubernetes cluster. If a problem exists with a worker node, try to reload it, which reloads all the configurations and updates the worker node with the latest image and Kubernetes patch version. When you reboot a worker node, its state remains the same such as `deployed`, but its status updates as the machine in your infrastructure account is restarted. If you update the worker node, it is reimaged with the Kubernetes version that matches the cluster master. If you reboot, reload, or update a worker node, data is deleted if not stored outside the worker node in persistent storage. This action cannot be undone.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.worker.rebootcontainers-kubernetes.worker.reloadcontainers-kubernetes.worker.reboot
Request
Request Body
UpdateWorkerCommand
The action that you want your worker node to take. Pass `os_reboot`, `reload`, or `update` as the action string.
action
string
The action to perform on the worker node.
force
boolean
Setting force flag to true will ignore if the master is unavailable during 'os_reboot" and 'reload' action
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
workerId
Required *
string
The ID of the worker node. To list all worker nodes for a cluster, use the `GET /v1/clusters/{idOrName}/workers` API or run `ibmcloud ks worker ls --cluster <cluster_name_or_ID>`.
Query Parameters
Response
204 - OK. The request to reboot or reload your worker node was successfully processed.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List configuration values for your IBM Cloud account.
GET /v1/config
List account configuration information that you can use when making IBM Cloud API requests.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
- ``
Request
Response
200 - Success
accounts_url
string
acct_url
string
Deprecated: the account and user management APIs are now separated to AccountsURL and UserManagementURL respectively
bluemix_url
string
env_name
string
iam_base_url
string
iam_client_id
string
iam_client_secret
string
iam_issuer
string
iam_papurl
string
iam_pdpurl
string
iam_url
string
uaa_url
string
user_management_url
string
Remove IBM Cloud classic infrastructure account credentials from your IBM Cloud Kubernetes Service account.
DELETE /v1/credentials
Remove the IBM Cloud classic infrastructure user name and API key from the region and resource group in your IBM Cloud Kubernetes Service account. After removing the credentials, you cannot access that IBM Cloud classic infrastructure account through your IBM Cloud Kubernetes Service account anymore. Instead, the default infrastructure account for your IBM Cloud account and the corresponding API key is used. Before you remove the infrastructure credentials, check which clusters use these credentials and make a plan to re-create the clusters in the new infrastructure environment. Otherwise, you might not be able to perform infrastructure actions, like updating or adding worker nodes, to the clusters that use the old credentials.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.create
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-infra-credential.delete
Request
Path Parameters
Query Parameters
Response
204 - Ok. The IBM Cloud infrastructure account credentials were successfully removed from your IBM Cloud Kubernetes Service account for this region and resource group.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. No IBM Cloud infrastructure account credentials are stored in the Kubernetes Service account for this region and resource group.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View the IBM Cloud classic infrastructure account credentials that are set for your IBM Cloud Kubernetes Service account.
GET /v1/credentials
Get the infrastructure user name of the credentials that are used to access the IBM Cloud classic infrastructure portfolio. Infrastructure credentials are set per region and resource group.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-infra-credential.get
Request
Path Parameters
Query Parameters
Response
200 - Ok. The IBM Cloud infrastructure (SoftLayer) account credentials were successfully retrieved from IBM Cloud Kubernetes Service.
apiUser
string
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. No IBM Cloud infrastructure account credentials are stored in the Kubernetes Service account for this region and resource group.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Set IBM Cloud classic infrastructure account credentials for your IBM Cloud Kubernetes Service account.
POST /v1/credentials
Set the IBM Cloud classic infrastructure user name and API key for the region and resource group in your IBM Cloud Kubernetes Service account. Do not set multiple credentials for one IBM Cloud Kubernetes Service account. Every IBM Cloud Kubernetes Service account is linked to one IBM Cloud infrastructure portfolio only. When you manually set infrastructure credentials with this API, these credentials are used instead of any API key that is set for the region and resource group.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.create
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-infra-credential.set
Request
Path Parameters
Query Parameters
Response
204 - Ok. The IBM Cloud infrastructure account credentials were successfully set for this region and resource group.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List available machine types for a zone (data center).
GET /v1/datacenters/{datacenter}/machine-types
List available machine types that you can use for a worker node. Machine types vary by zone. Each machine type includes the amount of virtual CPU, memory, and disk space that is set up for the worker node. For more information, see http://ibm.biz/machine_types
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
No IBM Cloud IAM role is required for this operation.
- ``
Auditing
Calling this method generates the following auditing event.
- ``
Request
Path Parameters
datacenter
Required *
string
The zone ID where you want to list available machine types. To list available zones, run `ibmcloud ks zone ls` or use the `GET /v1/datacenters` API.
Query Parameters
Response
200 - Success
400 - The specified zone is invalid. To list available zones, run `ibmcloud ks zone ls` or use the `GET /v1/datacenters` API.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List available VLANs for a zone.
GET /v1/datacenters/{datacenter}/vlans
List available public and private VLANs for a specified data center. Before using this operation, you must store your IBM Cloud infrastructure (SoftLayer) credentials in each Kubernetes Service account by using the `POST /v1/credentials` API or by running `ibmcloud ks credential set --infrastructure-api-key <API_key> --infrastructure-username <API_username>`.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
No IBM Cloud IAM role is required for this operation.
- ``
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-datacenter-vlan.list
Request
Path Parameters
datacenter
Required *
string
The ID of the zone where you want to list available public and private VLANs. To list available zones, run `ibmcloud ks zone ls` or use the `GET /v1/datacenters` API.
Query Parameters
Response
200 - Ok. A list of available public and private VLANs for the specified zone is returned.
400 - The specified zone is invalid. To list available zones, run `ibmcloud ks zone ls' or use the `GET /v1/datacenters` API.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get details on the permissions that the IBM Cloud infrastructure (SoftLayer) credentials have.
GET /v1/infra-permissions
Get details on the compute, networking, and storage permissions that the IBM Cloud infrastructure (SoftLayer) credentials have in this region and resource group. To review what IBM Cloud infrastructure (SoftLayer) credentials are set, use the `GET /v1/credentials` API, or run `ibmcloud ks credential get` or `ibmcloud ks api-key info`.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-infra-permission.get
Request
Path Parameters
Query Parameters
Response
200 - Ok.
account
string
ProviderAccountID may contain personally identifiable information
accountType
string
AccountType returns if the account information pertains to a linked or an IaaS account
networkManagerPermissions
Permissions
Permissions describes the result of checking granted permissions Note: the default zero/empty value implies sufficient permissions
physicalWorkerManagerPermissions
Permissions
Permissions describes the result of checking granted permissions Note: the default zero/empty value implies sufficient permissions
storageManagerPermissions
Permissions
Permissions describes the result of checking granted permissions Note: the default zero/empty value implies sufficient permissions
virtualWorkerManagerPermissions
Permissions
Permissions describes the result of checking granted permissions Note: the default zero/empty value implies sufficient permissions
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Reset the IAM API key.
POST /v1/keys
Replace the IAM API key for the IBM Cloud Kubernetes Service in a region and resource group. The API key is used to access several services, such as the IBM Cloud classic infratructure portfolio, and is required to manage your clusters. To avoid service interruptions, do not replace the API key unless your existing key is compromised.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.create
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-api-key.reset
Request
Path Parameters
Query Parameters
Response
204 - Ok. The IAM API key is successfully reset.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Deprecated: List available Kubernetes versions.
GET /v1/kube-versions
List available Kubernetes versions that you can use to create a cluster. Note: This API call is deprecated. Use the `GET /v1/versions` API instead.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
No IBM Cloud IAM role is required for this operation.
- ``
Auditing
Calling this method generates the following auditing event.
- ``
Request
Path Parameters
Query Parameters
Response
200 - Success. A list of available BOM versions is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List available locations.
GET /v1/locations
List locations from the IBM Cloud catalog that are supported by the IBM Cloud Kubernetes Service.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
No IBM Cloud IAM role is required for this operation.
- ``
Auditing
Calling this method generates the following auditing event.
- ``
Request
Path Parameters
Query Parameters
Response
200 - Success
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View information about the containers-kubernetes-key API key owner.
GET /v1/logging/{idOrName}/clusterkeyowner
View the name and email address for the owner of the cluster's containers-kubernetes-key API key.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - Ok. The cluster API key ID and the owner's name and email address.
string
id
string
name
string
401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View the default logging endpoint for the target region.
GET /v1/logging/{idOrName}/default
View the default logging endpoint for the target region.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - Ok. The default logging endpoint for the target region.
endpoint
string
The IBM Cloud Log Analysis with LogDNA API endpoint that the hostname uses.
hostname
string
The hostname for the ibm logging service.
port
integer
The port for the ibm logging service.
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Deletes all logging filter configurations for the cluster.
DELETE /v1/logging/{idOrName}/filterconfigs
Stops log filtering.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
Query Parameters
forceUpdate
boolean
Forces the request which may cause a new fluentd version to be deployed to the cluster.
Response
204 - Ok. All log filtering configurations have been removed.
401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List all logging filter configurations in the cluster.
GET /v1/logging/{idOrName}/filterconfigs
List the logging filter configurations that you created in a cluster.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
Query Parameters
showMatches
boolean
Set to true to populate global filters with all matching logging configurations.
Response
200 - Ok. A list of logging filters in the cluster.
401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create a logging filter configuration.
POST /v1/logging/{idOrName}/filterconfigs
Start filtering logs that are forwarded by your logging configuration from the given sources based on one or more selectors.
Request
Request Body
FilterConfigBody
The new logging filter configuration.
container
string
The name of the container where you want to apply the logging filter.
logLevel
string
The log level that you want to apply to your logging filter.
loggingConfigs
array
A list of logging configuration IDs where you want to apply the logging filter.
message
string
A string in a message to which you want to apply the logging filter.
namespace
string
The Kubernetes namespace where you want to apply the logging filter.
regexMessageEnabled
boolean
Set this value to `true` if you want the message field to be interpreted as a regular expression.
type
string
The type of the logging filter.
Path Parameters
idOrName
Required *
string
The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
Query Parameters
forceUpdate
boolean
Forces the request which may cause a new fluentd version to be deployed to the cluster.
Response
201 - Ok. Logs from the specified logging configurations will be filtered on the provided selectors.
container
string
The name of the container that you want to exclude from your logs.
coveringFilters
array
A list of logging filter IDs that the filter covers.
id
string
The unique identifier of the logging configuration.
label
string
The pod label that you want to exclude from your logs.
logLevel
string
The log level that you want to apply to your logs. Supported values are `debug` or `info`.
loggingConfigs
array
A list of logging configuration IDs where you want to apply the log filter.
message
string
A string in a log message that you want to exclude from your logs.
namespace
string
The Kubernetes namespace that you want to exclude from your logs.
regexMessageEnabled
boolean
Set this value to `true` if you want to interpret the message field as a regular expression.
type
string
The type of filter that you want to apply to your logs. Supported values are `container` and `non-container`.
version
string
Internal use only.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all of the required parameters, formatted in JSON. Supported logging types are 'syslog' and 'ibm'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Delete a logging filter configuration.
DELETE /v1/logging/{idOrName}/filterconfigs/{id}
Delete the specified logging filter configuration for a cluster.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
id
Required *
string
The UUID for the filterConfig that you want to delete.
Query Parameters
forceUpdate
boolean
Forces the request which may cause a new fluentd version to be deployed to the cluster.
Response
204 - Ok. Logs will no longer be filtered by the specified filter configuration.
401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View a logging filter configuration.
GET /v1/logging/{idOrName}/filterconfigs/{id}
View details for a logging filter configuration.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
id
Required *
string
The UUID of the logging filter that you want to fetch.
Query Parameters
showMatches
boolean
To show matching logging configurations for global filters, set to `true`.
Response
200 - Ok. A logging filter is configured for your cluster.
container
string
The name of the container that you want to exclude from your logs.
coveringFilters
array
A list of logging filter IDs that the filter covers.
id
string
The unique identifier of the logging configuration.
label
string
The pod label that you want to exclude from your logs.
logLevel
string
The log level that you want to apply to your logs. Supported values are `debug` or `info`.
loggingConfigs
array
A list of logging configuration IDs where you want to apply the log filter.
message
string
A string in a log message that you want to exclude from your logs.
namespace
string
The Kubernetes namespace that you want to exclude from your logs.
regexMessageEnabled
boolean
Set this value to `true` if you want to interpret the message field as a regular expression.
type
string
The type of filter that you want to apply to your logs. Supported values are `container` and `non-container`.
version
string
Internal use only.
401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Update a logging filter configuration.
PUT /v1/logging/{idOrName}/filterconfigs/{id}
Update a logging filter config where `id` is the UUID for the filter config.
Request
Request Body
FilterConfigBody
The new filter configuration for the specified ID.
container
string
The name of the container where you want to apply the logging filter.
logLevel
string
The log level that you want to apply to your logging filter.
loggingConfigs
array
A list of logging configuration IDs where you want to apply the logging filter.
message
string
A string in a message to which you want to apply the logging filter.
namespace
string
The Kubernetes namespace where you want to apply the logging filter.
regexMessageEnabled
boolean
Set this value to `true` if you want the message field to be interpreted as a regular expression.
type
string
The type of the logging filter.
Path Parameters
idOrName
Required *
string
The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
id
Required *
string
The UUID for the filterConfig that you want to update.
Query Parameters
forceUpdate
boolean
Forces the request which may cause a new fluentd version to be deployed to the cluster.
Response
200 - Ok. The configuration was updated.
container
string
The name of the container that you want to exclude from your logs.
coveringFilters
array
A list of logging filter IDs that the filter covers.
id
string
The unique identifier of the logging configuration.
label
string
The pod label that you want to exclude from your logs.
logLevel
string
The log level that you want to apply to your logs. Supported values are `debug` or `info`.
loggingConfigs
array
A list of logging configuration IDs where you want to apply the log filter.
message
string
A string in a log message that you want to exclude from your logs.
namespace
string
The Kubernetes namespace that you want to exclude from your logs.
regexMessageEnabled
boolean
Set this value to `true` if you want to interpret the message field as a regular expression.
type
string
The type of filter that you want to apply to your logs. Supported values are `container` and `non-container`.
version
string
Internal use only.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all of the required parameters, formatted in JSON. Supported logging types are 'syslog'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Delete all log forwarding configurations for a cluster.
DELETE /v1/logging/{idOrName}/loggingconfig
Stops all log forwarding for a cluster by deleting all log forwarding configurations.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
Query Parameters
forceUpdate
boolean
Forces the request which may cause a new fluentd version to be deployed to the cluster.
Response
204 - Ok. All log forwarding configurations have been removed.
401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List all log forwarding configurations in the cluster.
GET /v1/logging/{idOrName}/loggingconfig
List the log forwarding configurations in the target cluster.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - Ok. A list of logging configurations in the Kubernetes cluster.
401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List all log forwarding configurations for a log source in the cluster.
GET /v1/logging/{idOrName}/loggingconfig/{logSource}
List the log forwarding configurations for the specified log source in the target cluster.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
logSource
Required *
string
The type of log source that you want to list configurations for.
Query Parameters
Response
200 - Ok. A list of logging configurations for the specified log source in the cluster.
401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create a log forwarding configuration.
POST /v1/logging/{idOrName}/loggingconfig/{logSource}
Enable log collection for a specified log source and log forwarding to IBM Cloud Log Analysis or to an external syslog server. If you want to forward logs from one log source to both log collector servers, then you must create two logging configurations.
Request
Request Body
LogConfigBody
The type of log collector server for the logging configuration. Supported logging types are 'syslog' and 'ibm'.
appLogContainers
array
A list of container names that you want to collect logs for.
appLogPaths
array
A list of app paths that you want to collect logs for.
caCert
string
The name of the Kubernetes secret that holds the Certificate Authority certificate that you want to use for the syslog TLS termination.
loggingType
string
The logging type that you want to use. Supported values are `syslog` and `ibm`.
namespace
string
The Kubernetes namespace where the logging configuration is applied.
org
string
The name of the Cloud Foundry organization where the logging configuration is created.
protocol
string
The protocol that you want to use for syslog forwarding. Supported values are TCP, TLS and UDP. If no value is provided, the protocol is set to UDP by default.
remoteLogPort
integer
The port that the logging server uses. This value is required only when `LoggingType` is set to `syslog`.
remoteLogServer
string
The hostname or IP address of the logging server. This values is required only if `LoggingType` is set to `syslog`.
space
string
The name of the Cloud Foundry space where the logging configuration is created.
verifyMode
string
The verification mode that you want to use for the syslog TLS protocol. By default, `verify-none` is used. Other supported values include `verify-peer`, `verify-client-once`, and `verify-if-no-peer-cert`.
Path Parameters
idOrName
Required *
string
The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
logSource
Required *
string
The log source from which you want to forward logs. Accepted values are `container`, `worker`, `kubernetes`, `ingress`, and `application`. If you do not provide a namespace for log source `container`, then all namespaces use this configuration.
Query Parameters
forceUpdate
boolean
Forces the request which may cause a new fluentd version to be deployed to the cluster.
skipValidation
boolean
Set to `true` to skip validation of the space and org Cloud Foundry properties. Skipping validation decreases processing time, but an invalid logging configuration will not correctly forward logs.
Response
201 - Ok. Logs from the specified log source will be forwarded to the log server.
appLogContainers
array
A list of container names that you want to collect logs for.
appLogPaths
array
A list of app paths that you want to collect logs for.
caCert
string
The name of the Kubernetes secret that holds the Certificate Authority certificate that you want to use for the syslog TLS termination.
endpoint
string
The IBM Cloud Log Analysis with LogDNA API endpoint that the logging configuration uses.
errors
array
A list of errors that occurred during the last logging config update.
id
string
The unique identifier of the log source.
logSource
string
The type of logs that you want to read and forward to the logging server. Supported values are `container`, `kubernetes`, `ingress`, `worker`, and `application`.
logSourceContainers
array
A list of container names that logs are collected for and forwarded to the logging server.
logSourcePaths
array
A list of app paths that logs are collected for and forwarded to the logging server.
loggingType
string
The logging protocol to use. Supported values are `syslog` and `ibm`.
namespace
string
The Kubernetes namespace where the logging type is applied. This parameter is set only when the `container` log source is used.
org
string
The name of the Cloud Foundry organization where the logging configuration was created.
orgGUID
string
The GUID of the Cloud Foundry organization where the logging configuration was created.
protocol
string
The protocol that you want to use for syslog forwarding. Supported values are `TCP` and `UDP`. If no value is provided, the protocol is set to `UDP` by default.
remoteLogPort
integer
The port of the logging server.
remoteLogServer
string
The hostname or IP address of the logging server.
space
string
The name of the Cloud Foundry space where the logging configuration was created.
spaceGUID
string
The GUID of the Cloud Foundry space where the logging configuration was created.
verifyMode
string
The verification mode that is used for the syslog TLS protocol.
version
string
Internal use only.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format. Supported logging types are 'syslog' and 'ibm'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Delete a log forwarding configuration.
DELETE /v1/logging/{idOrName}/loggingconfig/{logSource}/{id}
Stops log forwarding by deleting a specified logging configuration.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
logSource
Required *
string
The log source that you want to stop forwarding logs for.
id
Required *
string
The UUID of the logging configuration that you want to delete.
Query Parameters
forceUpdate
boolean
Forces the request which may cause a new fluentd version to be deployed to the cluster.
Response
204 - Ok. Logs will no longer be forwarded to the log server for the specified logging configuration.
401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Update a log forwarding configuration.
PUT /v1/logging/{idOrName}/loggingconfig/{logSource}/{id}
Update the details of a log forwarding configuration.
Request
Request Body
LogConfigBody
The new type of log collector server for the logging configuration. Supported logging types are 'syslog'.
appLogContainers
array
A list of container names that you want to collect logs for.
appLogPaths
array
A list of app paths that you want to collect logs for.
caCert
string
The name of the Kubernetes secret that holds the Certificate Authority certificate that you want to use for the syslog TLS termination.
loggingType
string
The logging type that you want to use. Supported values are `syslog` and `ibm`.
namespace
string
The Kubernetes namespace where the logging configuration is applied.
org
string
The name of the Cloud Foundry organization where the logging configuration is created.
protocol
string
The protocol that you want to use for syslog forwarding. Supported values are TCP, TLS and UDP. If no value is provided, the protocol is set to UDP by default.
remoteLogPort
integer
The port that the logging server uses. This value is required only when `LoggingType` is set to `syslog`.
remoteLogServer
string
The hostname or IP address of the logging server. This values is required only if `LoggingType` is set to `syslog`.
space
string
The name of the Cloud Foundry space where the logging configuration is created.
verifyMode
string
The verification mode that you want to use for the syslog TLS protocol. By default, `verify-none` is used. Other supported values include `verify-peer`, `verify-client-once`, and `verify-if-no-peer-cert`.
Path Parameters
idOrName
Required *
string
The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
logSource
Required *
string
The log source from which you want to forward logs. Supported values are `container`, `worker`, `kubernetes`, `ingress`, and `application`. If you do not provide a namespace for log source `container`, then all namespaces use this configuration.
id
Required *
string
The UUID of the logging configuration that you want to update.
Query Parameters
forceUpdate
boolean
Forces the request which may cause a new fluentd version to be deployed to the cluster.
skipValidation
boolean
Set to `true` to skip validation of the space and org Cloud Foundry properties. Skipping validation decreases processing time, but an invalid logging configuration will not correctly forward logs.
Response
200 - Ok. The configuration was updated.
appLogContainers
array
A list of container names that you want to collect logs for.
appLogPaths
array
A list of app paths that you want to collect logs for.
caCert
string
The name of the Kubernetes secret that holds the Certificate Authority certificate that you want to use for the syslog TLS termination.
endpoint
string
The IBM Cloud Log Analysis with LogDNA API endpoint that the logging configuration uses.
errors
array
A list of errors that occurred during the last logging config update.
id
string
The unique identifier of the log source.
logSource
string
The type of logs that you want to read and forward to the logging server. Supported values are `container`, `kubernetes`, `ingress`, `worker`, and `application`.
logSourceContainers
array
A list of container names that logs are collected for and forwarded to the logging server.
logSourcePaths
array
A list of app paths that logs are collected for and forwarded to the logging server.
loggingType
string
The logging protocol to use. Supported values are `syslog` and `ibm`.
namespace
string
The Kubernetes namespace where the logging type is applied. This parameter is set only when the `container` log source is used.
org
string
The name of the Cloud Foundry organization where the logging configuration was created.
orgGUID
string
The GUID of the Cloud Foundry organization where the logging configuration was created.
protocol
string
The protocol that you want to use for syslog forwarding. Supported values are `TCP` and `UDP`. If no value is provided, the protocol is set to `UDP` by default.
remoteLogPort
integer
The port of the logging server.
remoteLogServer
string
The hostname or IP address of the logging server.
space
string
The name of the Cloud Foundry space where the logging configuration was created.
spaceGUID
string
The GUID of the Cloud Foundry space where the logging configuration was created.
verifyMode
string
The verification mode that is used for the syslog TLS protocol.
version
string
Internal use only.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format. Supported logging types are 'syslog'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Refresh the cluster's logging configuration.
PUT /v1/logging/{idOrName}/refresh
Refresh the logging configuration for a cluster. This refreshes the logging token for any logging configuration that is forwarding to the space level in your cluster.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
Query Parameters
forceUpdate
boolean
Forces the request which may cause a new fluentd version to be deployed to the cluster.
Response
204 - Ok. A request was sent for the cluster's logging configuration to be refreshed.
401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Check if automatic updates for the Fluentd logging add-on are enabled in the cluster.
GET /v1/logging/{idOrName}/updatepolicy
Check if automatic updates for the Fluentd logging add-on are enabled and whether your Fluentd pods are updated to the latest version.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - Ok. The current update policy.
autoUpdate
boolean
If set to true, automatic updates for the ALBs are enabled.
latestVersion
boolean
If set to true, all ALBs in the cluster run the latest ALB version.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format. Supported logging types are 'syslog' and 'ibm'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Enable or diable automatic updates for the Fluentd logging add-on in the cluster.
PUT /v1/logging/{idOrName}/updatepolicy
By default, automatic updates to the Fluentd logging add-on are enabled. Fluentd pods are automatically updated when a new version is available. To instead update the add-on manually, you can use this call to disable automatic updates. If automatic updates for the Fluentd add-on are disabled, you can re-enable automatic updates. Whenever the next version becomes available, the Fluentd pods are automatically updated to the latest version.
Request
Request Body
UpdatePolicy
The new update policy configuration
autoUpdate
boolean
If set to true, automatic updates for the ALBs are enabled.
latestVersion
boolean
If set to true, all ALBs in the cluster run the latest ALB version.
Path Parameters
idOrName
Required *
string
The name or ID of the target cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls`.
Query Parameters
Response
204 - Ok. The logging update policy has been changed.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format. Supported logging types are 'syslog' and 'ibm'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. To retrieve your access tokens, be sure that you're logged in and run `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To see a list of your clusters, run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View the current messages.
GET /v1/messages
View the current messages. Messages are notifications for new features or changes that may require attention.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
No IBM Cloud IAM role is required for this operation.
- ``
Auditing
Calling this method generates the following auditing event.
- ``
Request
Path Parameters
Query Parameters
Response
200 - Success
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Update a DNS record by adding an NLB IP address.
PUT /v1/nlb-dns/clusters/{idOrName}/add
Add an NLB IP address to an existing NLB subdomain that you created. For example, in a multizone cluster, you create an NLB in each zone to expose an app. You registered an NLB IP in one zone with a subdomain by using the `POST /clusters/{idOrName}/register` call, so now you can add the NLB IPs from the other zones to this existing subdomain.
Request
Request Body
NlbConfig
The input parameter to update an NLB DNS record. Include only the `nlbHost` parameter to specify the existing NLB subdomain and the `nlbIP` parameter to specify the NLB IP you want to add.
certProvider
string
clusterID
string
crn
string
isDefault
boolean
nlbDnsType
string
nlbHost
string
nlbIPArray
array
nlbMonitorState
string
nlbSslSecretName
string
nlbSslSecretStatus
string
nlbStatusMessage
string
nlbType
string
provider
string
secretNamespace
string
zoneID
string
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
204 - Ok. The request to update the NLB subdomain was successfully processed.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster, NLB subdomain, or NLB IP address could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`. To list existing NLB subdomains for a cluster, use the `GET /clusters/{idOrName}/list` API or run `ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>`. To list existing NLB IP addresses in a cluster, run `kubectl get svc -n <namespace>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Enable or disable a health check monitor for an NLB subdomain.
PUT /v1/nlb-dns/clusters/{idOrName}/health
Enable or disable an existing health check monitor for an NLB subdomain.
Request
Request Body
NlbConfig
Include only the `nlbHost` parameter to specify the NLB subdomain and the `nlbMonitorState` parameter to specify the health check monitor as `enabled` or `disabled`.
certProvider
string
clusterID
string
crn
string
isDefault
boolean
nlbDnsType
string
nlbHost
string
nlbIPArray
array
nlbMonitorState
string
nlbSslSecretName
string
nlbSslSecretStatus
string
nlbStatusMessage
string
nlbType
string
provider
string
secretNamespace
string
zoneID
string
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - Ok. Health check monitor enable/disable request for successfully processed.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or NLB subdomain could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`. To list existing NLB subdomains for a cluster, use the `GET /clusters/{idOrName}/list` API or run `ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Remove an IP address from an NLB subdomain.
DELETE /v1/nlb-dns/clusters/{idOrName}/host/{nlbHost}/ip/{nlbIP}/remove
Remove an IP address from the DNS record for an existing NLB subdomain. If you remove all IPs from a hostname, the hostname still exists but no IPs are associated with it.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
nlbHost
Required *
string
The existing NLB subdomain from which you want remove an NLB IP. To list existing NLB subdomains, use the `GET /clusters/{idOrName}/list` API or run `ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>`.
nlbIP
Required *
string
The NLB IP address that you want to unregister from the DNS record for the hostname. To list the NLB IPs registered with NLB subdomains, use the `GET /clusters/{idOrName}/list` API or run `ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>`.
Query Parameters
Response
204 - Deleted. The NLB IP address was successfully unregistered from the DNS record for the NLB subdomain.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster, NLB subdomain, or NLB IP address could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`. To list existing NLB subdomains and the NLB IPs registered with those hostnames, use the `GET /clusters/{idOrName}/list` API or run `ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List registered NLB subdomains and NLB IP addresses.
GET /v1/nlb-dns/clusters/{idOrName}/list
In a classic cluster, list NLB subdomains and the NLB IP addresses registered with the DNS provider for each subdomain.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - Ok. A list of NLB subdomains and the NLB IPs associated with the DNS record for the subdomains is returned for this cluster.
clusterid
string
nlbHealthCheckConfigs
array
nlbHealthCheckStatus
array
nlbs
array
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create a new NLB subdomain and associate one or more NLB IP addresses with it.
POST /v1/nlb-dns/clusters/{idOrName}/register
Create a new NLB subdomain and register NLB IP addresses with the DNS provider. If the registration fails, an error from the DNS provider is returned.
Request
Request Body
NlbConfig
Include either the `nlbIP` or the `nlbIPArray` parameter that specifies the NLB IP address(es) that you want to register.
certProvider
string
clusterID
string
crn
string
isDefault
boolean
nlbDnsType
string
nlbHost
string
nlbIPArray
array
nlbMonitorState
string
nlbSslSecretName
string
nlbSslSecretStatus
string
nlbStatusMessage
string
nlbType
string
provider
string
secretNamespace
string
zoneID
string
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
201 - Created. The NLB subdomain was successfully created and the NLB IP addres(es) registered with DNS.
certProvider
string
clusterID
string
crn
string
isDefault
boolean
nlbDnsType
string
nlbHost
string
nlbIPArray
array
nlbMonitorState
string
nlbSslSecretName
string
nlbSslSecretStatus
string
nlbStatusMessage
string
nlbType
string
provider
string
secretNamespace
string
zoneID
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or NLB IP address could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`. To list existing NLB IP addresses in a cluster, run `kubectl get svc -n <namespace>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Configure a health check monitor for an NLB subdomain.
PATCH /v1/nlb-dns/health/clusters/{idOrName}/config
Create and optionally enable a health check monitor for an existing NLB subdomain in a cluster.
Request
Request Body
NlbHealthSetConfig
The input body to configure the health check monitor for an NLB subdomain. To enable the health check monitor, set `monitorState` to `enabled`. For more information about each `healthcheckProperties` parameter, see https://cloud.ibm.com/docs/containers?topic=containers-cli-plugin-kubernetes-service-cli#cs_nlb-dns-monitor-configure
allowInsecureSet
string
clusterID
string
createdOn
string
desc
string
followRedirectSet
string
healtcheckPropertiesSetStatus
string
healthcheckProperties
object
modifiedOn
string
monitorState
string
nlbHost
string
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
201 - Created. The health check monitor was successfully configured for the NLB subdomain.
allowInsecureSet
string
clusterID
string
createdOn
string
desc
string
followRedirectSet
string
healtcheckPropertiesSetStatus
string
healthcheckProperties
HealthcheckProperties
HealthcheckProperties used for storing config provided by user for healthcheck deprecated
modifiedOn
string
monitorState
string
nlbHost
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or NLB subdomain could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`. To list existing NLB subdomains for a cluster, use the `GET /clusters/{idOrName}/list` API or run `ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View the health check monitor settings for an NLB subdomain.
GET /v1/nlb-dns/health/clusters/{idOrName}/host/{nlbHost}/config
View the health check monitor settings for an NLB subdomain.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
nlbHost
Required *
string
The NLB subdomain that you want health check monitor settings for. To list existing NLB subdomains, use the `GET /clusters/{idOrName}/list` API or run `ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>`.
Query Parameters
Response
200 - Ok. Health check monitor settings for the specified NLB subdomain are returned.
allowInsecureSet
string
clusterID
string
createdOn
string
desc
string
followRedirectSet
string
healtcheckPropertiesSetStatus
string
healthcheckProperties
HealthcheckProperties
HealthcheckProperties used for storing config provided by user for healthcheck deprecated
modifiedOn
string
monitorState
string
nlbHost
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or NLB subdomain could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`. To list existing NLB subdomains for a cluster, use the `GET /clusters/{idOrName}/list` API or run `ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List the health check monitor settings for all NLB subdomains.
GET /v1/nlb-dns/health/clusters/{idOrName}/list
List the settings for all existing health check monitors in a cluster.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - Ok. The health check monitor settings for each NLB subdomain in the cluster are returned.
clusterid
string
nlbHealthCheckConfigs
array
nlbHealthCheckStatus
array
nlbs
array
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Deprecated: List the health check status for the IPs behind NLB subdomains in a cluster.
GET /v1/nlb-dns/health/clusters/{idOrName}/status
Deprecated: List the health check status (`healthy` or `not healthy`) that is returned by the monitors for the IPs behind all NLB subdomains in a cluster.
Request
Path Parameters
idOrName
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Query Parameters
Response
200 - Ok. An array that contains the NlbHealthCheckStatus is returned.
clusterid
string
nlbHealthCheckConfigs
array
nlbHealthCheckStatus
array
nlbs
array
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List product-specific values to substitute for variables in other files.
GET /v1/prodconfig
List product-specific values to substitute for variables in other files.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
No IBM Cloud IAM role is required for this operation.
- ``
Auditing
Calling this method generates the following auditing event.
- ``
Request
Response
200 - Success
company_name
string
container_service_name
string
iaas_name
string
product_name
string
product_name_short
string
Deprecated: List available Kubernetes Service regions.
GET /v1/regions
List available IBM Cloud Kubernetes Service regions. A region is a geographic area that is accessed by a container service endpoint.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
No IBM Cloud IAM role is required for this operation.
- ``
Auditing
Calling this method generates the following auditing event.
- ``
Request
Path Parameters
Query Parameters
Response
200 - Success
regions
array
404 - Not found. The list of regions could not be found. Try your request again.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List available IBM Cloud classic infrastructure subnets.
GET /v1/subnets
List available subnets in an IBM Cloud classic infrastructure account. Before using this operation, you must store your IBM Cloud classic infrastructure credentials in each Kubernetes Service account by using the `POST /v1/credentials` API or by running `ibmcloud ks credential set --infrastructure-api-key <API_key> --infrastructure-username <API_username>`.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-subnet.list
Request
Path Parameters
Query Parameters
datacenters
string
A comma seperated list of datacenters to filter subnets based off of.
Response
200 - Ok.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View the VLAN spanning status.
GET /v1/subnets/vlan-spanning
View the VLAN spanning status for an IBM Cloud Infrastructure (SoftLayer) account. VLAN spanning enables all devices on an account to communicate with each other by means of the private network, regardless of its assigned VLAN.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-subnet-vlan-spanning.get
Request
Path Parameters
Query Parameters
Response
200 - Ok. Details of VLAN spanning enablement.
enabled
boolean
modifiedDate
string
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Unable to determine whether VLAN spanning is enabled in the IBM Cloud infrastructure account.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View a user's ability to create free and standard clusters in a region and resource group.
GET /v1/user-config
View whether a user can create free and paid clusters in a region and resource group. If `"freeEnabled": true` is returned, you can create a free cluster in the specified region. If `"storedIaasCredentials": true` is returned, your IBM Cloud account uses IBM Cloud infrastructure (SoftLayer) credentials that were manually set with the `POST /v1/credentials` API or the `ibmcloud ks credential set` command. When you create a standard cluster in the specified region and resource group, these credentials are used.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-user-config.get
Request
Path Parameters
Query Parameters
Response
200 - Ok. The user's permissions to create free and paid clusters is returned.
freeEnabled
boolean
storedIaasCredentials
boolean
List available IBM Cloud Kubernetes Service versions.
GET /v1/versions
List available IBM Cloud Kubernetes Service versions that you can use to create a cluster in a region. The container management platform version that you select is installed on your cluster master and worker nodes. Later, you can update the version but cannot roll back to a previous version or switch to a different container management platform. If you want to use multiple versions, create a separate cluster for each version.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
- ``
Request
Path Parameters
Query Parameters
Response
200 - Success. Available container management platform versions for the IBM Cloud Kubernetes Service region are returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List available zones (data centers).
GET /v1/zones
List available zones (data centers) where you can create a cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
No IBM Cloud IAM role is required for this operation.
- ``
Auditing
Calling this method generates the following auditing event.
- ``
Request
Path Parameters
Query Parameters
showFlavors
string
Specify true or false to show the machine types available in each zone.
location
string
Specify a location to filter zones for. To see supported locations, use the `GET /v1/locations` API or run `ibmcloud ks locations`.
Response
200 - Success. A list of available zones is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Ignore specific ingress status errors in ingress status reporting.
POST /v2/alb/addIgnoredIngressStatusErrors
Ignore specific ingress status errors in ingress status reporting. Ignored errors will not affect the cluster's ingress status state.
Request
Request Body
IgnoredIngressStatusErrors
Ingress status errors that are ignored for ingress status reporting.
cluster
string
ignoredErrors
array
Path Parameters
Query Parameters
Response
200 - Ignored ingress status errors were successfully added to the ingress status configuration.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details of an ALB.
GET /v2/alb/getAlb
View detailed information for an ALB in a VPC or classic cluster. An `ALBConfig` response will be returned for ALBs in classic clusters.
Request
Path Parameters
Query Parameters
albID
Required *
string
The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the `GET /v2/alb/getClusterAlbs` API or run `ibmcloud ks alb ls --cluster <cluster_name_or_ID>`.
Response
200 - Ok. Details for the specified ALB are returned.
albBuild
string
The build number of the ALB.
albID
string
The ID of the application load balancer (ALB).
albType
string
The type of ALB.
authBuild
string
The auth build of the ALB.
cluster
string
createdDate
string
The date the ALB was created.
disableDeployment
boolean
If set to true, the deployment of the ALB is disabled.
enable
boolean
Set to true to enable the ALB, or false to disable the ALB for the cluster.
loadBalancerHostname
string
name
string
The name of the cluster that the ALB belongs to.
numOfInstances
string
Desired number of ALB replicas that you want in your cluster.
resize
boolean
If set to true, resizing of the ALB is done.
state
string
The state of the ALB.
status
string
The status of the ALB.
zone
string
The zone where you want to add ALBs.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or ALB could not be found. To list the classic clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`. To list the VPC clusters that you have access to, use the `GET /v2/vpc/getClusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List supported Ingress controller images.
GET /v2/alb/getAlbImages
List the community Kubernetes Ingress controller and IBM Cloud Kubernetes Service ALB images that are supported.
Request
Path Parameters
Query Parameters
Response
200 - Ok. A list of supported Ingress controller images is returned.
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to list supported Ingress controller images.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
GET /v2/alb/getClusterAlbs
List all ALBs in a VPC or classic cluster. A `ClusterALB` response will be returned for classic clusters.
Note: If no ALB IDs are returned for a VPC cluster, no VPC load balancer exists for the ALBs. If no ALB IDs are returned for a classic cluster, no available portable subnet exists in the VLANs that your ALBs are on.
Request
Path Parameters
Query Parameters
cluster
Required *
string
To list the classic clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`. To list the VPC clusters that you have access to, use the `GET /v2/vpc/getClusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`.
Response
200 - Ok. A list of ALBs for the cluster is returned.
alb
array
PrivateIngressHostname string `json:"privateIngressHostname"` PrivateIngressSecretName string `json:"privateIngressSecretName"`
dataCenter
string
id
string
ingressHostname
string
ingressSecretName
string
isPaid
boolean
region
string
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the classic clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`. To list the VPC clusters that you have access to, use the `GET /v2/vpc/getClusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get the status of the in-cluster ALB health checker.
GET /v2/alb/getIngressClusterHealthcheck
Check the status of the in-cluster ALB health checker.
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster.
Response
200 - Ok. The in-cluster ALB health checker status for your cluster is returned.
cluster
string
enable
boolean
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get the status of the ingress resources in a cluster.
GET /v2/alb/getStatus
Check the status of the IBM provided subdomain and application load balancers
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want information about.
Response
200 - Ok. The ingress status for your cluster is returned.
StatusList
array
albStatus
array
cluster
string
enabled
boolean
generalComponentStatus
array
ignoredErrors
array
message
string
nonTranslatedStatus
string
routerStatus
array
secretStatus
array
status
string
subdomainStatus
array
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List all ingress status errors that are ignored for the cluster.
GET /v2/alb/listIgnoredIngressStatusErrors
List all ingress status errors that are ignored for the cluster. If no ignored errors are returned, then the cluster does not have ignored ingress status errors.
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster.
Response
200 - Ok. All ignored ingress status errors for your cluster are returned.
cluster
string
ignoredErrors
array
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Unignore specific ingress status errors in ingress status reporting.
DELETE /v2/alb/removeIgnoredIngressStatusErrors
Unignore specific ingress status errors in ingress status reporting. Unignored errors will affect the cluster's ingress status state.
Request
Request Body
IgnoredIngressStatusErrors
Ingress status errors that are ignored for ingress status reporting.
cluster
string
ignoredErrors
array
Path Parameters
Query Parameters
Response
200 - Ignored ingress status errors were successfully removed from the ingress status configuration.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Set the in-cluster ingress health checker.
POST /v2/alb/setIngressClusterHealthcheck
Set the in-cluster ingress health checker state. It can be either enabled or disabled.
Request
Request Body
ALBClusterHealthCheckConfig
The desired state of the in-cluster ingress health checker.
cluster
string
enable
boolean
Path Parameters
Query Parameters
Response
200 - Set successfully finished.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Set the state of the ingress status.
POST /v2/alb/setIngressStatusState
Set the state of the ingress status for a cluster. It can be either enabled or disabled.
Request
Request Body
StatusState
The desired state of ingress status.
cluster
string
enable
boolean
Path Parameters
Query Parameters
Response
200 - Set successfully finished.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Update ALBs in a cluster.
POST /v2/alb/updateAlb
Update one or more public or private ALBs to a supported IBM Cloud Kubernetes Service ALB image or a supported community Kubernetes Ingress controller image. To update your ALB to a specified image version, automatic updates must be disabled. You can check the automatic update status by using the `GET /v1/alb/clusters/{idOrName}/updatepolicy` call. NOTE: You cannot use this call to switch your ALB from one type of image to another, such as from an IBM Cloud Kubernetes Service ALB image to a community Kubernetes Ingress controller image. Instead, first disable the ALB by using the `DELETE /v1/alb/albs/{albID}` call (classic) or the `POST /v2/alb/vpc/disableAlb` call (VPC). Then, enable the ALB by using the `POST /v1/alb/albs` (classic) or `POST /v2/alb/vpc/enableAlb` (VPC) call, and include the ALB image that you want to switch to in the input parameter.
Request
Request Body
V2UpdateALB
The input parameter to update an ALB's image. To see the supported image versions, use the `GET /v2/alb/getAlbImages` call.
albBuild
string
albList
array
cluster
string
Path Parameters
Query Parameters
Response
200 - Updated. The ALBs in the cluster were successfully updated.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or ALB could not be found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create a public or private ALB in a specified zone and VPC cluster.
POST /v2/alb/vpc/createAlb
Create a new public or private ALB in a specified zone and VPC cluster.
Request
Request Body
ALB
The input parameters to create an ALB. For more information, see https://ibm.biz/alb_create_vpc
enableByDefault
boolean
If set to true, the ALB is enabled by default. \
ingressImage
string
The type of Ingress image that you want to use for your ALB deployment.
ip
string
Optional: The IP address that you want to assign to the ALB.
nlbVersion
string
The version of the network load balancer that you want to use for the ALB.
type
string
The type of ALB that you want to create.
vlanID
string
The VLAN ID that you want to use for your ALBs.
zone
string
The zone where you want to deploy the ALB.
Path Parameters
Query Parameters
Response
201 - The ALB was successfully created.
alb
string
cluster
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or zone could not be found. To list the VPC clusters that you have access to, use the `GET /v2/vpc/getClusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`. To list the zones available in a VPC cluster, use the `GET /v2/vpc/getCluster` API or run `ibmcloud ks cluster-get --cluster <cluster_name_or_ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Disable an ALB in your VPC cluster.
POST /v2/alb/vpc/disableAlb
Disable a public or private ALB in your VPC cluster.
Request
Request Body
ALBConfig
The input parameters to disable an ALB. DisableDeployment and albID are required. For more information, see https://ibm.biz/alb_configure_vpc
albBuild
string
The build number of the ALB.
albID
string
The ID of the application load balancer (ALB).
albType
string
The type of ALB.
authBuild
string
The auth build of the ALB.
cluster
string
createdDate
string
The date the ALB was created.
disableDeployment
boolean
If set to true, the deployment of the ALB is disabled.
enable
boolean
Set to true to enable the ALB, or false to disable the ALB for the cluster.
loadBalancerHostname
string
name
string
The name of the cluster that the ALB belongs to.
numOfInstances
string
Desired number of ALB replicas that you want in your cluster.
resize
boolean
If set to true, resizing of the ALB is done.
state
string
The state of the ALB.
status
string
The status of the ALB.
zone
string
The zone where you want to add ALBs.
Path Parameters
Query Parameters
Response
204 - Disabled. The ALB for the cluster was successfully disabled.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or ALB could not be found. To list the VPC clusters that you have access to, use the `GET /v2/vpc/getClusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`. To list the ALBs in a cluster, use the `GET /v2/alb/getClusterAlbs` API or run `ibmcloud ks alb ls --cluster <cluster_name_or_ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Enable an existing ALB in a VPC cluster.
POST /v2/alb/vpc/enableAlb
Enable a public or private ALB in your VPC cluster.
Request
Request Body
ALBConfig
The input parameter to enable an ALB. AlbID is required. To switch your ALB from one type of image to another, such as from an IBM Cloud Kubernetes Service ALB image to a community Kubernetes Ingress controller image, specify that image version in the ALBBuild field. To see the supported image versions, use the `GET /v2/alb/getAlbImages` call. For more information, see https://ibm.biz/alb_configure_vpc
albBuild
string
The build number of the ALB.
albID
string
The ID of the application load balancer (ALB).
albType
string
The type of ALB.
authBuild
string
The auth build of the ALB.
cluster
string
createdDate
string
The date the ALB was created.
disableDeployment
boolean
If set to true, the deployment of the ALB is disabled.
enable
boolean
Set to true to enable the ALB, or false to disable the ALB for the cluster.
loadBalancerHostname
string
name
string
The name of the cluster that the ALB belongs to.
numOfInstances
string
Desired number of ALB replicas that you want in your cluster.
resize
boolean
If set to true, resizing of the ALB is done.
state
string
The state of the ALB.
status
string
The status of the ALB.
zone
string
The zone where you want to add ALBs.
Path Parameters
Query Parameters
Response
201 - Enabled. The ALB for the cluster was successfully enabled.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or ALB could not be found. To list the VPC clusters that you have access to, use the `GET /v2/vpc/getClusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`. To list the ALBs in a cluster, use the `GET /v2/alb/getClusterAlbs` API or run `ibmcloud ks alb ls --cluster <cluster_name_or_ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Start applying IAM roles corresponding to your access to the cluster.
POST /v2/applyRBAC
Apply IAM roles corresponding to your access to the cluster as RoleBindings and ClusterRoleBindings as described in http://ibm.biz/rbac-access. For example, if you have the IAM Viewer role, you will be granted the `ibm-view` role in the cluster. The roles are applied asynchronously. Use `/v2/getRBACStatus` to verify when they have finished applying.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster.config
Request
Request Body
Kubeconfig
Options to retrieve a kubeconfig file. Default format is 'json', other options include 'yaml' and 'zip'. To retrieve the Calico network config, pass admin:true and format:"zip" in the body.
admin
boolean
AdminUser Retrieve the admin kubeconfig file.
cluster
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the `GET /v2/getClusters` API or run `ibmcloud ks cluster ls`.
endpointType
string
EndpointType The type of endpoint server URL to return in the kubeconfig. Supported values are 'default', 'private', 'vpe', 'link', 'vpc'. The 'default' endpoint returns the public endpoint when available, and the private endpoint otherwise. Default is 'default'.
format
string
Format Default format is json. Other options include yaml, and zip.
network
boolean
NetworkConfig Retrieve the Calico network config. Requires admin=true and format=zip.
Path Parameters
Query Parameters
Response
202 - Accepted. Applies IAM roles asynchronously.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v2/getClusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Start applying IAM roles corresponding to your access to the cluster, then retrieve the cluster's kubeconfig file.
POST /v2/applyRBACAndGetKubeconfig
Apply IAM roles corresponding to your access to the cluster as RoleBindings and ClusterRoleBindings as described in http://ibm.biz/rbac-access, then retrieve the cluster's kubeconfig file to connect to your cluster and run Kubernetes API calls. For example, if you have the IAM Viewer role, you will be granted the `ibm-view` role in the cluster and your kubeconfig will allow 'view' Kubernetes API calls. The roles are applied asynchronously. Use `/v2/getRBACStatus` to verify when they have finished applying.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster.config
Request
Request Body
Kubeconfig
Options to retrieve a kubeconfig file. Default format is 'json', other options include 'yaml' and 'zip'. To retrieve the Calico network config, pass admin:true and format:"zip" in the body.
admin
boolean
AdminUser Retrieve the admin kubeconfig file.
cluster
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the `GET /v2/getClusters` API or run `ibmcloud ks cluster ls`.
endpointType
string
EndpointType The type of endpoint server URL to return in the kubeconfig. Supported values are 'default', 'private', 'vpe', 'link', 'vpc'. The 'default' endpoint returns the public endpoint when available, and the private endpoint otherwise. Default is 'default'.
format
string
Format Default format is json. Other options include yaml, and zip.
network
boolean
NetworkConfig Retrieve the Calico network config. Requires admin=true and format=zip.
Path Parameters
Query Parameters
Response
200 - Ok. Returns the cluster's kubeconfig file.
apiVersion
string
Legacy field from pkg/api/types.go TypeMeta.
clusters
array
Clusters is a map of referencable names to cluster configs
contexts
array
Contexts is a map of referencable names to context configs
current-context
string
CurrentContext is the name of the context that you would like to use by default
kind
string
Legacy field from pkg/api/types.go TypeMeta.
preferences
object
Preferences holds general information to be use for cli interactions
users
array
AuthInfos is a map of referencable names to user configs
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v2/getClusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Set the autoupdate status of the cluster master.
POST /v2/autoUpdateMaster
Set the autoupdate status of the cluster master. Only a limited set of users can access use this API.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.create
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-master-autoupdate.enablecontainers-kubernetes.cluster-master-autoupdate.disable
Request
Request Body
AutoUpdateMaster
Input parameters to specify the name or ID of the cluster and whether to enable or disable auto master updates. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
autoUpdate
boolean
cluster
string
Path Parameters
Query Parameters
Response
204 - Ok. The request was processed successfully.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The user doesn't have access to this API.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. The specified value is already set on the cluster. To list the clusters properties, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Detailed cluster information.
GET /v2/classic/getCluster
Detailed cluster information.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster.get
Request
Path Parameters
Query Parameters
showResources
string
To view additional cluster resources like addons, VLANs, subnets, and storage, pass `true`.
cluster
Required *
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Response
200 - Success. Detailed cluster information.
addons
array
caCertRotationStatus
CommonClusterCACertRotation
CommonClusterCACertRotation CA cert rotation properties
calicoIPAutodetectionConfig
string
createdDate
string
crn
string
datacenter
string
desiredTrustedProfileID
string
disableAutoUpdate
boolean
entitlement
string
etcdPort
string
features
CommonClusterFeatures
id
string
ignitionServerURL
string
imageSecurityEnabled
boolean
ingress
CommonClusterIngress
isPaid
boolean
keyManagementService
CommonClusterKMS
konnectivityServerURL
string
lifecycle
CommonClusterLifecycle
location
string
locationZones
array
masterKubeVersion
string
masterURL
string
monitoringURL
string
multiAzCapable
boolean
name
string
oauthServerURL
string
offering
string
podSubnet
string
provider
string
region
string
resourceGroup
string
resourceGroupName
string
secureRequested
boolean
serviceEndpoints
CommonClusterServiceEndpoint
serviceSubnet
string
state
string
The lifecycle state of the cluster. Possible values include aborted, critical, delete_failed, deleted, deleting, deploy_failed, deploying, normal, pending, requested, updating, unsupported, and warning. For more information, see the docs 'http://ibm.biz/cluster-health-states'
status
string
supportedOperatingSystems
array
targetVersion
string
trustedProfileID
string
type
string
versionEOS
string
vlans
array
workerCount
integer
workerZones
array
worker_vlans
VLANS
VLANS is a helper type to sort an api.VLAN list. The VLANS will sort the list in order of the Properties.PrimaryRouter value so that VLAN's of a common router are listed consecutively.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List the classic clusters that you have access to.
GET /v2/classic/getClusters
List the classic clusters that you have access to.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster.list
Request
Path Parameters
Query Parameters
location
string
Specify a location to filter clusters for. To see supported locations, use the `GET /v1/locations` API or run `ibmcloud ks locations`.
showResources
string
To view additional cluster resources like addons, VLANs, subnets, and storage, pass `true`.
Response
200 - Success. A list of clusters that you have access to is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get if VRF and Service Endpoint is enabled for the given account in the selected region.
GET /v2/classic/getPrivateServiceEnabled
Get if VRF and Service Endpoint is enabled for the given account in the selected region.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool.get
Request
Path Parameters
Query Parameters
Response
200 - Ok. Detailed information about the private service enablement.
isPrivateServiceEnabled
boolean
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Not authorized to use this command. Only a limited group of early adopters have access to this feature. If you are sure that you are part of the limited group of early adopters, contact IBM Cloud support..
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List available classic infrastructure VLANs for a zone.
GET /v2/classic/getVLANs
List available public and private VLANs for a specified zone (data center). Before using this operation, you must store your IBM Cloud classic infrastructure credentials in each Kubernetes Service account by using the `POST /v1/credentials` API or by running `ibmcloud ks credential set --infrastructure-api-key <API_key> --infrastructure-username <API_username>`.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-datacenter-vlan.list
Request
Path Parameters
Query Parameters
zone
Required *
string
The ID of the zone where you want to list available public and private VLANs. To list available zones, run `ibmcloud ks zone ls` or use the `GET /v1/datacenters` API.
Response
200 - Ok. A list of all VLANs is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the infrastructure provider.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details of a worker node for classic cluster.
GET /v2/classic/getWorker
View detailed information for a worker node in a classic cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.worker.get
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
worker
Required *
string
The ID of the worker node that you want details for. To list all worker nodes for a cluster, use the `GET /v1/clusters/{idOrName}/workers` API or run `ibmcloud ks workers <cluster_name_or_ID>`.
Response
200 - Ok. Detailed information about the worker node is returned.
dedicatedHostId
string
dedicatedHostPoolId
string
flavor
string
health
GetWorkerResponseHealth
id
string
kubeVersion
GetWorkerResponseKubeVersion
lifecycle
GetWorkerResponseLifecycle
location
string
networkInformation
GetWorkerResponseNetworkInformation
poolID
string
poolName
string
provider
string
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks clusters`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details of a worker pool for a classic cluster.
GET /v2/classic/getWorkerPool
View detailed information for a worker pool in a classic cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool.list
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
workerpool
Required *
string
The ID of the worker pool that you want details for. To list all worker pools for a cluster, use the `GET /v1/clusters/{idOrName}/workerpools` API or run `ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>`.
Response
200 - Ok. Detailed information about the worker pool is returned.
autoscaleEnabled
boolean
dedicatedHostPoolId
string
flavor
string
flavorState
string
hostLabels
object
id
string
isBalanced
boolean
isolation
string
labels
object
lifecycle
GetWorkerPoolResponseLifecycle
openshiftLicense
string
operatingSystem
string
poolName
string
provider
string
reservationID
string
reservationName
string
taints
object
workerCount
integer
zones
array
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details of a worker pool for a classic cluster.
GET /v2/classic/getWorkerPools
View detailed information for a worker pool in a classic cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool.get
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Response
200 - Ok. Detailed information about the worker pools is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View all workers for a classic cluster.
GET /v2/classic/getWorkers
View detailed information for all worker nodes in a classic cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker.list
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks clusters`.
showDeleted
string
true|false Shows deleted workers
pool
string
The name or ID of the worker pool to filter results for. Run `ibmcloud ks worker-pool ls --cluster <cluster name>`.
Response
200 - Ok. Details for all workers in the classic cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks clusters`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get detailed information for one health issue (regional URL prefix).
GET /v2/cluster-health/getIssue
Same behavior as `GET /v2/cluster-health/getIssue`.
Request
Path Parameters
Query Parameters
cluster
Required *
string
Cluster ID or name.
issue
Required *
string
Issue code.
Response
200 - Success. Detailed health issue payload.
component
string
description
string
detected
string
id
string
more_details
array
severity
string
solution
string
400 - Bad request.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
410 - Gone.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List aggregated health issues for a cluster (regional URL prefix).
GET /v2/cluster-health/getIssues
Same behavior as `GET /v2/cluster-health/getIssues`. Use this path when calling a regional Kubernetes Service endpoint directly.
Request
Path Parameters
Query Parameters
cluster
Required *
string
Cluster ID or name.
Response
200 - Success. An array of health issue summaries.
400 - Bad request.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
410 - Gone.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create a dedicated host.
POST /v2/createDedicatedHost
Create a dedicated host.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To create a dedicated host, you must have the Administrator platform role for the Kubernetes Service in IAM.
containers-kubernetes.account-dedicated-host.create
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-dedicated-host.create
Request
Request Body
CreateDedicatedHost
The required dedicated host parameters.
flavor
string
hostPoolID
string
zone
string
Path Parameters
Query Parameters
Response
201 - Created. The dedicated host was successfully created.
id
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. A dedicated host create may already be in progress. Please wait a few minutes and try again.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create a dedicated host pool.
POST /v2/createDedicatedHostPool
Create a dedicated host pool.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To create a dedicated host pool, you must have the Administrator platform role for the Kubernetes Service in IAM.
containers-kubernetes.account-dedicated-host-pool.create
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-dedicated-host-pool.create
Request
Request Body
CreateDedicatedHostPool
The required dedicated host pool parameters.
flavorClass
string
metro
string
name
string
Path Parameters
Query Parameters
Response
201 - Created. The dedicated host pool was successfully created.
id
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. Creation of a dedicated host might already be in progress. Please wait a few minutes and try again.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Disable dedicated host placement.
POST /v2/disableDedicatedHostPlacement
Disable placement of worker nodes on a dedicated host.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To disable dedicated host placement, you must have the Administrator platform role for the Kubernetes Service in IAM.
containers-kubernetes.account-dedicated-host-placement.disable
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-dedicated-host-placement.disable
Request
Request Body
UpdateDedicatedHost
The dedicated host pool and host to disable placement on.
hostID
string
hostPoolID
string
Path Parameters
Query Parameters
Response
200 - OK. The dedicated host placement was successfully disabled.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
POST /v2/disableImageSecurity
Disable image security enforcement for a cluster
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.create
Request
Request Body
ImageSecurity
Input parameters to specify the name or ID of the cluster that you want to disable image security enforcement in.
cluster
string
Path Parameters
Query Parameters
Response
204 - Ok. The request to update your master node was successfully processed.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Deprecated: Disable the Pod Security Policy admission controller.
POST /v2/disablePodSecurityPolicy
Deprecated: This API was only available for Kubernetes clusters that ran version 1.24. Disable the Pod Security Policy admission controller for Kubernetes. Use this API when migrating from the deprecated Pod Security Policy to the Pod Security admission controller.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To change the Pod Security Policy admission controller configuration, you must have the Administrator platform role for the Kubernetes Service in IAM.
containers-kubernetes.cluster.update
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-pod-security.disable
Request
Request Body
DisablePodSecurityPolicyRequest
The cluster to target.
cluster
string
Path Parameters
Query Parameters
Response
204 - OK. The request to disable the Pod Security Policy admission controller was successfully received.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format. \
Bad Request. Your cluster must run Kubernetes version 1.24 to change the Pod Security Policy admission controller.
Bad Request. Cannot disable the Pod Security Policy admission controller when the Pod Security admission controller is disabled.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Disables a private service endpoint for a cluster.
POST /v2/disablePrivateServiceEndpoint
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.create
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-private-service-endpoint.disable
Request
Request Body
UpdateServiceEndpoint
Input parameters to specify the name or ID of the cluster and which service endpoint to update. Valid service endpoints are public or private.
cluster
string
Path Parameters
Query Parameters
Response
204 - Ok. The request to update your master node was successfully processed.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Disables a public service endpoint for a cluster.
POST /v2/disablePublicServiceEndpoint
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.create
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-public-service-endpoint.disable
Request
Request Body
UpdateServiceEndpoint
Input parameters to specify the name or ID of the cluster and which service endpoint to update. Valid service endpoints are public or private.
cluster
string
Path Parameters
Query Parameters
Response
204 - Ok. The request to update your master node was successfully processed.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Enable dedicated host placement.
POST /v2/enableDedicatedHostPlacement
Enable placement of worker nodes on a dedicated host.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To enable dedicated host placement, you must have the Administrator platform role for the Kubernetes Service in IAM.
containers-kubernetes.account-dedicated-host-placement.enable
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-dedicated-host-placement.enable
Request
Request Body
UpdateDedicatedHost
The dedicated host pool and host to enable placement on.
hostID
string
hostPoolID
string
Path Parameters
Query Parameters
Response
200 - OK. The dedicated host placement was successfully enabled.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
POST /v2/enableImageSecurity
Enable image security enforcement for a cluster
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.create
Request
Request Body
ImageSecurity
Input parameters to specify the name or ID of the cluster that you want to enable image security enforcement in.
cluster
string
Path Parameters
Query Parameters
Response
204 - Ok. The request to update your master node was successfully processed.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Enables KMS in a cluster
POST /v2/enableKMS
Enables a key management service (KMS) provider, such as IBM Key Protect, in a cluster. You cannot later disable KMS encryption, so make sure not to delete the KMS instance that you use to encrypt the cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.create
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-kms.enable
Request
Request Body
EnableKMSRequest
Input parameters to create the Key Protect config for your cluster.
account_id
string
cluster
string
crk_id
string
instance_id
string
private_endpoint
boolean
Path Parameters
Query Parameters
Response
200 - Ok. The requested KMS configuration has been enabled on the cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or worker could not be found. To list the clusters that you have access to, use the `GET /vpc/v2/clusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Deprecated: Enable the Pod Security Policy admission controller.
POST /v2/enablePodSecurityPolicy
Deprecated: This API was only available for Kubernetes clusters that ran version 1.24. Enable the Pod Security Policy admission controller. Use this API when migrating from the deprecated Pod Security Policy to the Pod Security admission controller.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To change the Pod Security Policy admission controller configuration, you must have the Administrator platform role for the Kubernetes Service in IAM.
containers-kubernetes.cluster.update
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-pod-security-policy.enable
Request
Request Body
EnablePodSecurityPolicyRequest
The cluster to target.
cluster
string
Path Parameters
Query Parameters
Response
204 - OK. The request to enable the Pod Security Policy admission controller was successfully received.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format. \
Bad Request. Your cluster must run Kubernetes version 1.24 to change the Pod Security Policy admission controller.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Enables the private service endpoint for a cluster.
POST /v2/enablePrivateServiceEndpoint
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.create
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-private-service-endpoint.enable
Request
Request Body
UpdateServiceEndpoint
Input parameters to specify the name or ID of the cluster and which service endpoint to update. Valid service endpoints are public or private.
cluster
string
Path Parameters
Query Parameters
Response
204 - Ok. The request to update your master node was successfully processed.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Enables the public service endpoint for a cluster.
POST /v2/enablePublicServiceEndpoint
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.create
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-public-service-endpoint.enable
Request
Request Body
UpdateServiceEndpoint
Input parameters to specify the name or ID of the cluster and which service endpoint to update. Valid service endpoints are public or private.
cluster
string
Path Parameters
Query Parameters
Response
204 - Ok. The request to update your master node was successfully processed.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create an image pull secret to IBM Cloud Container Registry in the `default` namespace of the cluster. Note that this API method also requires the Administrator platform role to IBM Cloud Container Registry.
POST /v2/enablePullSecret
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service and Administrator platform role to Container Registry in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-pull-secret.enable
Request
Request Body
EnablePullSecret
Input parameters to specify the name or ID of the cluster and which to enable pull secrets for.
cluster
string
Path Parameters
Query Parameters
Response
204 - Ok. The request to update your master node was successfully processed.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get the cluster's CA cert.
GET /v2/getCACert
Get the cluster's CA cert to configure services with it to connect to the given cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-ca-certificate.get
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want to get CA cert from. To list the clusters that you have access to, use the `GET /v2/getClusters` API or run `ibmcloud ks cluster ls`.
Response
200 - Ok. Returns the cluster's CA cert.
400 - Bad request. The query parameters are either incomplete or in the wrong format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v2/getClusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List the root keys for a Key Management Service instance.
GET /v2/getCRKs
List all the customer root keys (CRKs) for a Key Management Service (KMS) instance, such as a Key Protect service instance, in your IBM Cloud account.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-customer-root-key.list
Request
Path Parameters
Query Parameters
kms_instance
Required *
string
The KMS instance ID to list root keys for. To list available Key Protect service instances, run `ibmcloud ks kms instance ls`.
Response
200 - Ok. A list of available root keys in the KMS instance is returned.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or worker could not be found. To list the clusters that you have access to, use the `GET /vpc/v2/clusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details for a cluster.
GET /v2/getCluster
View detailed information for a cluster, including a VPC cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster.get
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want to get the worker node details from. To list the VPC clusters that you have access to, use the `GET /v2/vpc/getClusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`.
Response
200 - Success. Detailed cluster information is returned.
addons
array
caCertRotationStatus
CommonClusterCACertRotation
CommonClusterCACertRotation CA cert rotation properties
calicoIPAutodetectionConfig
string
createdDate
string
crn
string
datacenter
string
desiredTrustedProfileID
string
disableAutoUpdate
boolean
entitlement
string
etcdPort
string
features
CommonClusterFeatures
id
string
ignitionServerURL
string
imageSecurityEnabled
boolean
ingress
CommonClusterIngress
isPaid
boolean
keyManagementService
CommonClusterKMS
konnectivityServerURL
string
lifecycle
CommonClusterLifecycle
location
string
locationZones
array
masterKubeVersion
string
masterURL
string
monitoringURL
string
multiAzCapable
boolean
name
string
oauthServerURL
string
offering
string
podSubnet
string
provider
string
region
string
resourceGroup
string
resourceGroupName
string
secureRequested
boolean
serviceEndpoints
CommonClusterServiceEndpoint
serviceSubnet
string
state
string
The lifecycle state of the cluster. Possible values include aborted, critical, delete_failed, deleted, deleting, deploy_failed, deploying, normal, pending, requested, updating, unsupported, and warning. For more information, see the docs 'http://ibm.biz/cluster-health-states'
status
string
supportedOperatingSystems
array
targetVersion
string
trustedProfileID
string
type
string
versionEOS
string
vlans
array
workerCount
integer
workerZones
array
worker_vlans
VLANS
VLANS is a helper type to sort an api.VLAN list. The VLANS will sort the list in order of the Properties.PrimaryRouter value so that VLAN's of a common router are listed consecutively.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details of the add-ons that are enabled in a cluster.
GET /v2/getClusterAddons
View details of the add-ons that are enabled in a cluster, including the add-on versions.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-addon.list
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Response
200 - OK. Details for the add-ons in this cluster are returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details of a dedicated host.
GET /v2/getDedicatedHost
View detailed information for a dedicated host.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To view the details of a dedicated host, you must have the Viewer platform role for the Kubernetes Service in IAM.
containers-kubernetes.account.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-dedicated-host.get
Request
Path Parameters
Query Parameters
dedicatedhost
Required *
string
The ID of the dedicated host that you want details for..
dedicatedhostpool
Required *
string
The ID of the dedicated host pool that you want to get the dedicated host details from.
Response
200 - Ok. Detailed information about the dedicated host is returned.
flavor
string
id
string
lifecycle
DedicatedHostLifecycle
placementEnabled
boolean
resources
DedicatedHostResources
workers
array
zone
string
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified dedicated host could not be found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details of a dedicated host pool.
GET /v2/getDedicatedHostPool
View detailed information for a dedicated host pool.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To view the details of a dedicated host pool, the user must have the Viewer platform role for the Kubernetes Service in IAM.
containers-kubernetes.account.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-dedicated-host-pool.get
Request
Path Parameters
Query Parameters
dedicatedhostpool
Required *
string
The ID of the dedicated host pool that you want to get.
Response
200 - Ok. Detailed information about the dedicated host pool is returned.
flavorClass
string
hostCount
integer
id
string
metro
string
name
string
state
string
workerPools
array
zones
array
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified dedicated host could not be found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. The IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List the dedicated host pools.
GET /v2/getDedicatedHostPools
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To list dedicated host pools, you must have the Viewer platform role for the Kubernetes Service in IAM.
containers-kubernetes.account.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-dedicated-host-pool.list
Request
Path Parameters
Query Parameters
Response
200 - Ok. Detailed information about the dedicated host pools is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified dedicated host pool could not be found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. The IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List the dedicated hosts.
GET /v2/getDedicatedHosts
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To list dedicated hosts, you must have the Viewer platform role for the Kubernetes Service in IAM.
containers-kubernetes.account.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-dedicated-host.list
Request
Path Parameters
Query Parameters
dedicatedhostpool
Required *
string
The ID of the dedicated host pool that you want to get the dedicated hosts details from.
Response
200 - Ok. Detailed information about the dedicated hosts is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified dedicated host pool could not be found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get the details for a worker node flavor
GET /v2/getFlavor
Get the details for a worker node flavor, including the flavor's virtual CPU amount, memory, disk space and supported operating systems. Flavors are specific to a IBM Cloud Kubernetes Service zone and infrastructure provider.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
No IBM Cloud IAM role is required for this operation.
- ``
Auditing
Calling this method generates the following auditing event.
- ``
Request
Path Parameters
Query Parameters
flavor
Required *
string
The ID of the flavor. To list available flavors, run `ibmcloud ks flavors --zone ZONE` or use the `GET /v2/getFlavors` API.
zone
Required *
string
The ID of the zone. To list available zones, run `ibmcloud ks zone ls` or use the `GET /v2/zones` API.
provider
Required *
string
The name of the provider. To check available providers, see the output of the `ibmcloud ks flavors --zone ZONE` command or use the `GET /v2/getFlavors` API.
Response
200 - Success
architecture
string
The type of CPU architecture that the flavor uses.
correspondingFlavor
string
deprecated
boolean
id
string
The ID of the worker node flavor.
isTrusted
boolean
name
string
The name of the worker node flavor.
provider
string
The name of the provider.
secondaryStorage
string
secondaryStorageEncrypted
boolean
storage
string
400 - The specified zone is invalid. To list available zones, run `ibmcloud ks zone ls` or use the `GET /v2/zones` API.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List available flavors types for a VPC zone (data center).
GET /v2/getFlavors
List available flavors that you can use for a worker node. Flavors are specific to a location and a provider in an IBM Cloud Kubernetes Service zone. Each flavor includes the amount of virtual CPU, memory, and disk space that is set up for the worker node.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
No IBM Cloud IAM role is required for this operation.
- ``
Auditing
Calling this method generates the following auditing event.
- ``
Request
Path Parameters
Query Parameters
zone
Required *
string
The ID of the location for which you want to list available flavors. To list available locations, run `ibmcloud ks zone ls` or use the `GET /v2/zones` API.
provider
string
Filters the flavors to match the provider type specified.
Response
200 - Success
400 - The specified location is invalid. To list available locations, run `ibmcloud ks zone ls` or use the `GET /v2/zones` API.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Gets KMS instances tied to an account
GET /v2/getKMSInstances
Retrieves available key management service (KMS) instances, such as Key Protect, in your IBM Cloud Account
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-key-management-service-instance.list
Request
Path Parameters
Query Parameters
Response
200 - Ok. A list of all KMSs in your IBM Cloud Account
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or worker could not be found. To list the clusters that you have access to, use the `GET /vpc/v2/clusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get the cluster's kubeconfig file.
GET /v2/getKubeconfig
Apply IAM roles to the cluster asynchronously and retrieve the cluster's kubeconfig file to connect to your cluster and run Kubernetes API calls. Use `/v2/getRBACStatus` to verify when RBAC finishes applying.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM. Note that to pull the networking or admin configuration files, you must have the Administrator platform role.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-config.get
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the `GET /v2/getClusters` API or run `ibmcloud ks cluster ls`.
endpointType
string
The type of endpoint server URL to return in the kubeconfig. Supported values are 'default', 'private', 'vpe', 'link', 'vpc'. Default is 'default'.
format
string
Default format is json. Other options include yaml, and zip.
admin
boolean
Retrieve the admin kubeconfig file.
network
boolean
Retrieve the Calico network config. Requires admin=true and format=zip.
Response
200 - Ok. Returns the cluster's kubeconfig file.
apiVersion
string
Legacy field from pkg/api/types.go TypeMeta.
clusters
array
Clusters is a map of referencable names to cluster configs
contexts
array
Contexts is a map of referencable names to context configs
current-context
string
CurrentContext is the name of the context that you would like to use by default
kind
string
Legacy field from pkg/api/types.go TypeMeta.
preferences
object
Preferences holds general information to be use for cli interactions
users
array
AuthInfos is a map of referencable names to user configs
400 - Bad request. The query parameters are either incomplete or in the wrong format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v2/getClusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View the current messages.
GET /v2/getMessages
View the current messages. Messages are notifications for new features or changes that may require attention.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
No IBM Cloud IAM role is required for this operation.
- ``
Auditing
Calling this method generates the following auditing event.
- ``
Request
Path Parameters
Query Parameters
Response
200 - Success
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List supported operating systems.
GET /v2/getOperatingSystems
Lists supported operating systems for the given configuration.
Auditing
Calling this method generates the following auditing event.
cluster-worker-pool-supported-operating-systems.get
Request
Path Parameters
Query Parameters
provider
Required *
string
The name of the infrastructure provider in which to view supported operating systems. Available options include 'classic', 'vpc-gen2', and 'satellite'.
version
Required *
string
The Kubernetes or Openshift version.
coreOSEnabled
boolean
Whether HyperShift is enabled.
Response
200 - Ok. The request to list supported operating systems was successfully processed.
400 - Bad Request. Required parameters were not set. You must provide the `version` and `provider` query parameters.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View the Pod Security admission control configuration for a cluster.
GET /v2/getPodSecurity
View the Pod Security admission control configuration for a cluster.
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-pod-security.get
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want to get the Pod Security admission control configuration for. To list the clusters that you have access to, use the `GET /v2/clusters` API or run `ibmcloud ks cluster ls`.
Response
200 - Ok. The request to view the Pod Security admission control configuration was successfully processed.
configuration
string
Configuration is a base64 encoded PodSecurityConfiguration yaml definition
enabled
boolean
400 - Bad Request. Required parameters were not set. You must provide the `cluster` query parameter. \
Bad Request. Pod Security admission is supported only for Kubernetes v1.24 or later clusters.
Bad Request. Pod Security admission is not supported for Red Hat OpenShift clusters.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Deprecated: View the Pod Security Policy admission control configuration.
GET /v2/getPodSecurityPolicy
Deprecated: This API was only available for Kubernetes clusters that ran version 1.24. View the Pod Security Policy admission control configuration. Use this API when migrating from the deprecated Pod Security Policy to the Pod Security admission controller.
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-pod-security-policy.get
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want to get the Pod Security admission control configuration for. To list the clusters that you have access to, use the `GET /v2/clusters` API or run `ibmcloud ks cluster ls`.
Response
200 - Ok. The request to view Pod Security Policy admission control configuration was successfully processed.
enabled
boolean
400 - Bad Request. Required parameters were not set. You must provide the `cluster` query parameter. \
Bad Request. Pod Security admission configuration is not supported for OpenShift clusters.
Bad Request. Your cluster must run Kubernetes version 1.24 to remove the Pod Security admission controller or to change the Pod Security Policy admission controller.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View the quota for resources per region in the account.
GET /v2/getQuota
View the quota for IBM Cloud Kubernetes Service resources such as clusters and worker nodes. The quota is per region and applies across resource groups in the account. To increase your quota, contact IBM Support and include the new quota limit that you want for the region, resource, and infrastructure provider such as classic or VPC.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-quota.get
Request
Path Parameters
Query Parameters
Response
200 - OK. A list of quota limits for resources per region in the account is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get the RBACSync status.
GET /v2/getRBACStatus
Get the RBACSync status for the authenticated user. The RBACSync status indicates whether the user has the correct identities and RoleBindings in the cluster. The `synchronized: true` status means the cluster is ready to receive requests from the user. After calling the `/v2/applyRBAC` endpoint for the first time on a cluster, poll this endpoint to verify the synchronization is complete.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the RBACSync status, you must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-rbac.status
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want to get the RBACSync status from. To list the clusters that you have access to, use the `GET /v2/getClusters` API or run `ibmcloud ks cluster ls`.
Response
200 - Success
synchronized
boolean
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v2/getClusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List available cluster versions.
GET /v2/getVersions
List available versions that you can use to create a cluster in a region. The container management platform version that you select is installed on your cluster master and worker nodes. Later, you can update the version but cannot roll back to a previous version or switch to a different container management platform. If you want to use multiple versions, create a separate cluster for each version.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
- ``
Request
Path Parameters
Query Parameters
Response
200 - Success. Available container management platform versions for the IBM Cloud Kubernetes Service region are returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details of a worker node for cluster.
GET /v2/getWorker
View detailed information for a worker node in a cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.worker.get
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want to get the worker node details from. To list the VPC clusters that you have access to, use the `GET /v2/vpc/getClusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`.
worker
Required *
string
The ID of the worker node that you want details for. To list all worker nodes for a cluster, use the `GET /v2/getWorkers?cluster=idOrName` API or run `ibmcloud ks worker ls --cluster <cluster_name_or_ID>`.
Response
200 - Ok. Detailed information about the worker node is returned.
dedicatedHostId
string
dedicatedHostPoolId
string
flavor
string
health
GetWorkerResponseHealth
id
string
kubeVersion
GetWorkerResponseKubeVersion
lifecycle
GetWorkerResponseLifecycle
location
string
networkInformation
GetWorkerResponseNetworkInformation
networkInterfaces
GetWorkerResponseNetworkInterfaces
poolID
string
poolName
string
provider
string
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the VPC clusters that you have access to, use the `GET /v2/vpc/getClusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details of a worker pool for a cluster.
GET /v2/getWorkerPool
View detailed information for a worker pool in a cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool.get
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want to get the worker node details from. To list the VPC clusters that you have access to, use the `GET /v2/vpc/getClusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`.
workerpool
Required *
string
The ID of the worker pool that you want details for. To list all worker pools for a cluster, use the `GET /v2/getWorkerPools?cluster=idOrName` API or run `ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>`.
Response
200 - Ok. Detailed information about the worker pool is returned.
autoscaleEnabled
boolean
dedicatedHostPoolId
string
flavor
string
flavorState
string
hostLabels
object
id
string
isBalanced
boolean
isolation
string
labels
object
lifecycle
GetWorkerPoolResponseLifecycle
openshiftLicense
string
operatingSystem
string
poolName
string
provider
string
reservationID
string
reservationName
string
secondaryStorageOption
DiskConfigResp
DiskConfigResp response type for describing a disk configuration
staticNetworkInterfaceCount
integer
taints
object
vpcID
string
workerCount
integer
workerVolumeEncryption
WorkerVolumeEncryption
WorkerVolumeEncryption contains encryption related fields
zones
array
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the VPC clusters that you have access to, use the `GET /v2/vpc/getClusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List the worker pools in a cluster.
GET /v2/getWorkerPools
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool.list
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want to get the worker node details from. To list the VPC clusters that you have access to, use the `GET /v2/vpc/getClusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`.
Response
200 - Ok. Detailed information about the worker pools is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the VPC clusters that you have access to, use the `GET /v2/vpc/getClusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View all workers for cluster.
GET /v2/getWorkers
View detailed information for all worker nodes in a cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker.list
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want to get the worker node details from. To list the VPC clusters that you have access to, use the `GET /v2/vpc/getClusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`.
showDeleted
string
true|false Shows deleted workers
Response
200 - Ok. Details for all workers in the cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the VPC clusters that you have access to, use the `GET /v2/vpc/getClusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Validates user provided entitlement.
GET /v2/hasValidEntitlement
Validates whether the provided entitlement value is supported or not.
Auditing
Calling this method generates the following auditing event.
account-has-valid-entitlement.get
Request
Path Parameters
Query Parameters
entitlement
Required *
string
The entitlement value to check if it is supported.
Response
200 - Ok. The entitlement validation request was successfully processed.
hasValidEntitlement
boolean
400 - The entitlement option can not be set when the stored API key has a subtype. For more information, see 'http://ibm.biz/api-key'.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Could not connect to the back-end billing validation service. Try again later.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Update the health monitoring configuration for the specified NLB subdomain in a cluster.
PUT /v2/nlb-dns/configureHealthMonitor
Update the health monitoring configuration for the specified NLB subdomain in a cluster. Include the cluster ID, NLB subdomain, and any the provider specific configurations for the health check in the request body.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To call this endpoint, you must have the Editor platform role for the Kubernetes Service in IAM.
containers-kubernetes.cluster.update
Auditing
Calling this method generates the following auditing event.
cluster-nlb-dns-monitor.create
Request
Request Body
HealthMonitorConfiguration
The full health monitoring configuration to overwrite the current configuration with. The configuration is defined in the corresponding provider specific field.
akamaiMonitorConfiguration
AkamaiHealthcheckProperties
AkamaiHealthcheckProperties used for storing config provided by user for akamai healthcheck deprecated
httpError3xx
boolean
httpError4xx
boolean
httpError5xx
boolean
httpHeaders
array
httpMethod
string
name
string
peerCertificateVerification
boolean
testInterval
integer
testObject
string
testObjectPort
integer
testObjectProtocol
string
testTimeout
number
cluster
string
nlbSubdomain
string
Path Parameters
Query Parameters
Response
204 - Ok. The request to update the health monitor config was successfully processed.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or NLB subdomain could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`. To list existing NLB subdomains for a cluster, use the `GET /clusters/{idOrName}/list` API or run `ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Remove a secret from an NLB subdomain.
POST /v2/nlb-dns/deleteSecret
Delete a secret from an NLB subdomain in your cluster and prevent future renewal of the certificate. You might remove the secret from an NLB subdomain if you no longer use the subdomain or disassociate it from your NLB IP addresses.
Request
Request Body
SecretConfig
Include the NLB subdomain that you want to delete the secret for, and the cluster that the subdomain is in.
cluster
string
subdomain
string
Path Parameters
Query Parameters
Response
204 - Deleted. The secret name was successfully deleted for the NLB subdomain.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster, subdomain, or secret could not be found. To list clusters you have access to, run `ibmcloud ks cluster ls`. To list existing NLB subdomains and associated secret names, run `ibmcloud ks nlb-dns ls --cluster <cluster_name_or_id>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get the health monitoring configuration for the specified NLB subdomain in a cluster.
GET /v2/nlb-dns/getHealthMonitorConfig
Get the health monitoring configuration for the specified NLB subdomain in a cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To call this endpoint, you must have the Viewer platform role for the Kubernetes Service in IAM.
containers-kubernetes.cluster.update
Auditing
Calling this method generates the following auditing event.
cluster-nlb-dns-monitor.get
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
nlbSubdomain
Required *
string
The existing NLB subdomain that you want the monitor config for. To list existing NLB subdomains, use the `GET /clusters/{idOrName}/list` API or run `ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>`.
Response
200 - OK. Current monitor config returned.
akamaiMonitorConfiguration
AkamaiHealthcheckProperties
AkamaiHealthcheckProperties used for storing config provided by user for akamai healthcheck deprecated
cluster
string
nlbSubdomain
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`. To list existing NLB subdomains for a cluster, use the `GET /clusters/{idOrName}/list` API or run `ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List registered NLB subdomains in a cluster.
GET /v2/nlb-dns/getNlbDNSList
List NLB subdomains and the NLB IP addresses or the load balancer hostnames that are registered with the DNS provider for each NLB subdomain.
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Response
200 - Ok. A list of NLB subdomains and associated details is returned for this cluster.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`. To list existing NLB subdomains for a cluster, use the `GET /clusters/{idOrName}/list` API or run `ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get the details for the specified NLB subdomain in a cluster.
GET /v2/nlb-dns/getNlbDetails
Get the details for the NLB subdomain and the NLB IP addresses or the load balancer hostnames that are registered with the DNS provider for each NLB subdomain.
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
nlbSubdomain
Required *
string
The existing NLB subdomain that you want details for. To list existing NLB subdomains, use the `GET /clusters/{idOrName}/list` API or run `ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>`.
Response
200 - OK. Details of the NLB subdomain are returned.
Nlb
ExtendedNlbVPCConfig
ExtendedNlbVPCConfig is the response body for the get v2 vpc apis
secretName
string
secretStatus
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`. To list existing NLB subdomains for a cluster, use the `GET /clusters/{idOrName}/list` API or run `ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get the details for the specified subdomain in a Satellite location.
GET /v2/nlb-dns/getSatLocationSubdomain
Get the details for the subdomain and the IP addresses that are registered with the DNS provider for each subdomain.
Request
Path Parameters
Query Parameters
controller
Required *
string
To list available locations, use the `GET /v2/satellite/getControllers` API, or run `ibmcloud sat location ls`.
subdomain
Required *
string
The existing subdomain that you want details for. To list existing subdomains, use the `GET /v2/nlb-dns/getSatLocationSubdomains` API or run `ibmcloud sat location dns ls --cluster <cluster_name_or_ID>`.
Response
200 - OK. A list of subdomains and associated details is returned for this location. If no list is returned, you can assign hosts to your location and try again.
certProvider
string
clusterID
string
crn
string
isDefault
boolean
nlbDnsType
string
nlbHost
string
nlbIPArray
array
nlbMonitorState
string
nlbSslSecretName
string
nlbSslSecretStatus
string
nlbStatusMessage
string
nlbType
string
provider
string
secretNamespace
string
zoneID
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your IAM and UAA tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Could not find the IBM Cloud Satellite location. To list available locations, use the `GET /v2/satellite/getControllers` API, or run `ibmcloud sat location ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List registered NLB subdomains in a Satellite location.
GET /v2/nlb-dns/getSatLocationSubdomains
Get the details for the NLB subdomains along with the NLB IP addresses or CNAME records that are registered with the DNS provider for each NLB subdomain. Your Satellite location has a set of hosts that run control plane operations to manage your Satellite components across all the clusters in the location. If your location becomes unavailable, you might use the NLB subdomain and IP address details of the hosts to help troubleshoot.
Request
Path Parameters
Query Parameters
controller
Required *
string
To list available locations, use the `GET /v2/satellite/getControllers` API, or run `ibmcloud sat location ls`.
Response
200 - OK. A list of NLB subdomains and associated details is returned for this location. If no list is returned, you can assign hosts to your location and try again.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Could not find the IBM Cloud Satellite location. To list available locations, use the `GET /v2/satellite/getControllers` API, or run `ibmcloud sat location ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Regenerates cert for secret.
POST /v2/nlb-dns/regenerateCert
Regenerate the certificate and recreate the secret for an NLB subdomain. You might regenerate an NLB subdomain's certificate and secret if you previously deleted the secret.
Request
Request Body
SecretConfig
Include the cluster and subdomain for the NLB subdomain that you want to remove the secret from.
cluster
string
subdomain
string
Path Parameters
Query Parameters
Response
202 - The cert has been successfully triggered for regeneration.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster, subdomain, or secret could not be found. To list clusters you have access to, run `ibmcloud ks cluster ls`. To list existing NLB subdomains and relevant secret names, run `ibmcloud ks nlb-dns ls --cluster <cluster_name_or_id>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Registers domains: c001, c002, c003, each tied to a corresponding IP and c000 tied to all of the IPs for the cluster. Also registers 1 cname, ce00, for the specified multishift cluster
POST /v2/nlb-dns/registerMSCDomains
Registers Multishift domains for a cluster.
Request
Request Body
MSCRegistration
The input parameter to register a Multishift cluster's domains.
controller
string
ips
array
Path Parameters
Query Parameters
Response
200 - Registered. The multishift cluster domains and cname have been successfully registered.
controller
string
dnsRegistrations
array
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or NLB subdomain could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`. To list existing NLB subdomains for a cluster, use the `GET /clusters/{idOrName}/list` API or run `ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create a new NLB subdomain in a VPC cluster and associate a load balancer hostname with it.
POST /v2/nlb-dns/vpc/createNlbDNS
In a VPC cluster, create a new NLB subdomain and register a VPC load balancer hostname with the DNS provider. Note that you can create the NLB subdomain with only one VPC load balancer hostname. If the registration fails, an error from the DNS provider is returned.
Request
Request Body
NlbVPCConfig
Include the `lbHostname` parameter that specifies the VPC load balancer hostname that you want to register.
cluster
string
dnsType
string
lbHostname
string
nlbSubdomain
string
secretNamespace
string
type
string
Path Parameters
Query Parameters
Response
201 - Created. The NLB subdomain was successfully created and the VPC load balancer hostname is registered with DNS.
cluster
string
dnsType
string
lbHostname
string
nlbSubdomain
string
secretNamespace
string
type
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified VPC cluster or load balancer hostname could not be found. To list the VPC clusters that you have access to, use the `GET /v2/vpc/getClusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`. To list existing load balancer hostnames in a cluster, run `kubectl get svc -n <namespace>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Remove the load balancer hostname from the DNS record for an existing NLB subdomain.
POST /v2/nlb-dns/vpc/removeLBHostname
In a VPC cluster, remove a load balancer hostname from the DNS record for an existing NLB subdomain. After you remove the load balancer hostname, the NLB subdomain still exists, but no load balancer is associated with it.
Request
Request Body
NlbVPCConfig
Include the cluster parameter (required) and the nlbSubdomain parameter (required) for the NLB subdomain that you want to remove the load balancer hostname from.
cluster
string
dnsType
string
lbHostname
string
nlbSubdomain
string
secretNamespace
string
type
string
Path Parameters
Query Parameters
Response
204 - Removed. The load balancer hostname was successfully unregistered from the DNS record for the NLB subdomain.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified VPC cluster or NLB subdomain could not be found. To list the VPC clusters that you have access to, use the `GET /v2/vpc/getClusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`. To list existing NLB subdomains, run `ibmcloud ks nlb-dns ls --cluster <cluster_name_or_id>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Update the DNS record for an NLB subdomain by replacing the load balancer hostname.
POST /v2/nlb-dns/vpc/replaceLBHostname
In a VPC cluster, update the DNS record for an NLB subdomain by replacing the load balancer hostname that is currently associated with the NLB subdomain with another load balancer hostname. Only one load balancer hostname can be associated with an NLB DNS record at a time.
Request
Request Body
NlbVPCConfig
Include only the `cluster` ID, existing `lbHostname` that you want to replace, and `nlbSubdomain` of the DNS record that you want to update.
cluster
string
dnsType
string
lbHostname
string
nlbSubdomain
string
secretNamespace
string
type
string
Path Parameters
Query Parameters
Response
200 - Ok. The request to update the load balancer hostname was successfully processed.
cluster
string
dnsType
string
lbHostname
string
nlbSubdomain
string
secretNamespace
string
type
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified VPC cluster, load balancer hostname, or NLB subdomain could not be found. To list the VPC clusters that you have access to, use the `GET /v2/vpc/getClusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`. To list existing load balancer hostnames in a cluster, run `kubectl get svc -n <namespace>`. To list existing NLB subdomains, run `ibmcloud ks nlb-dns ls --cluster <cluster_name_or_id>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Rebalance workers in a worker pool.
POST /v2/rebalanceWorkerPool
When you rebalance the worker pool, you return the number of worker nodes in the worker pool to a balanced state. For example, if you remove some worker nodes such as to troubleshoot an issue, you might have an uneven number of nodes across zones. You might delete 2 worker nodes in zone dal13 but still have 3 worker nodes each in zones dal10 and dal12 for a total of 7 worker nodes. To fix this unbalanced state, rebalance the worker pool. After rebalancing, the worker pool has 9 worker nodes again. Rebalancing does not change the size per zone of the worker pool, even if you specify a different size per zone.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.workerpool.rebalance
Request
Request Body
RebalanceWorkerPool
Fields required to rebalance the worker pool.
cluster
string
workerpool
string
Path Parameters
Query Parameters
Response
204 - OK. The request to balance the worker pool was successfully received.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Refresh the Kubernetes master.
POST /v2/refreshMaster
Restart the Kubernetes master in the cluster to apply changes to the API server configuration.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-master.refresh
Request
Request Body
RefreshMaster
Input parameters to refresh master. The cluster ID or name is required.
cluster
string
Path Parameters
Query Parameters
Response
204 - Ok. The Master will be put into the desired state.
400 - Bad Request. Check that all headers are present and the cluster ID or name is provided.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster. To list the clusters that you have access to, use the `GET /vpc/v2/clusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Removes a dedicated host.
POST /v2/removeDedicatedHost
Removes a dedicated host.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To remove a dedicated host, you must have the Administrator platform role for the Kubernetes Service in IAM.
containers-kubernetes.account-dedicated-host.delete
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-dedicated-host.delete
Request
Request Body
DeleteDedicatedHost
The dedicated host to target in a given dedicated host pool.
host
string
hostPool
string
Path Parameters
Query Parameters
Response
202 - OK. The request to remove your dedicated host was successfully received.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. The IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Removes a dedicated host pool.
POST /v2/removeDedicatedHostPool
Removes a dedicated host pool.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To remove a dedicated host pool, you must have the Administrator platform role for the Kubernetes Service in IAM.
containers-kubernetes.account-dedicated-host-pool.delete
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-dedicated-host-pool.delete
Request
Request Body
RemoveDedicatedHostPool
The dedicated host pool to target.
hostPool
string
Path Parameters
Query Parameters
Response
202 - OK. The request to remove your dedicated host pool was successfully received.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. The IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Deprecated: Remove the Pod Security admission controller configuration for Kubernetes v1.24 clusters.
POST /v2/removePodSecurity
Deprecated: This API was only available for Kubernetes clusters that ran version 1.24. Remove the Pod Security admission controller configuration. Use this API when migrating from the deprecated Pod Security Policy to the Pod Security admission controller.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To change the Pod Security admission controller configuration, you must have the Administrator platform role for the Kubernetes Service in IAM.
containers-kubernetes.cluster.update
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-pod-security.remove
Request
Request Body
RemovePodSecurityRequest
The cluster to target.
cluster
string
Path Parameters
Query Parameters
Response
204 - OK. The request to remove the Pod Security admission controller configuration was successfully received.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format. \
Bad Request. Your cluster must run Kubernetes version 1.24 to remove the Pod Security admission controller or to change the Pod Security Policy admission controller.
Bad Request. Cannot disable the Pod Security admission controller when the Pod Security Policy admission controller is disabled.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Delete a worker node from a cluster.
POST /v2/removeWorker
Delete a worker node from a cluster. This action cannot be undone. When you delete the worker node, the worker node is cordoned and drained so that its pods are rescheduled onto remaining worker nodes in the cluster. Make sure that you have enough capacity in the cluster to support the workload. After you remove the worker node, you can rebalance the worker pool.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.worker.delete
Request
Request Body
RemoveWorker
Input parameters to remove a worker node. The cluster and worker node ID parameters are required.
cluster
string
workerID
string
Path Parameters
Query Parameters
Response
204 - Ok. The worker node was successfully removed from your cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - The specified cluster or worker node could not be found. To list the clusters that you have access to, use the `GET /v2/clusters` API or run `ibmcloud ks cluster ls`. To list worker nodes in the cluster, use the `GET /v2/getWorkers` API or run `ibmcloud ks worker ls -c <cluster_name>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Removes a worker pool.
POST /v2/removeWorkerPool
Remove a worker pool from a cluster. All worker nodes in the pool are deleted. Your pods are rescheduled when you delete. To avoid downtime, be sure that you have enough workers to run your workload.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.workerpool.delete
Request
Request Body
RemoveWorkerPool
The cluster and worker pool to target.
allowSingleOpenShiftWorker
boolean
cluster
string
workerpool
string
Path Parameters
Query Parameters
Response
204 - OK. The request to remove your worker pool was successfully received.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Remove a zone from a worker pool.
POST /v2/removeWorkerPoolZone
Remove a zone from a worker pool in your cluster. All worker nodes that are deployed to that zone in the worker pool are deleted. The app pods from the deleted worker nodes are rescheduled to other worker nodes when the zone is removed. To avoid downtime, be sure that you have enough worker nodes to handle your workload.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.zone.delete
Request
Request Body
RemoveWorkerPoolZoneReq
The input parameter to specify the cluster, worker pool, and zone.
cluster
string
workerpool
string
zone
string
Path Parameters
Query Parameters
Response
204 - OK. The request to remove the zone from your worker pool was successfully received..
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Replace a worker node with a new worker node.
POST /v2/replaceWorker
Delete the specified worker node from the cluster and create a new worker node in the same worker pool to replace the deleted worker node. The new worker node is assigned new public or private IP addresses. When the worker node is deleted, it is cordoned and drained to reschedule the pods that run on the worker node before deleting it, to avoid downtime for your apps. You might replace a worker node if you cannot reload or update the worker node, such as if it enters a troubled state.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.worker.replace
Request
Request Body
ReplaceWorkerRequest
Input parameters to replace a worker.
cluster
string
update
boolean
workerID
string
Path Parameters
Query Parameters
Response
204 - OK. The worker node is being removed and replaced with a new worker node.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or worker could not be found. To list the VPC clusters that you have access to, use the `GET /vpc/v2/getClusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Resize an existing worker pool.
POST /v2/resizeWorkerPool
Resize a worker pool for the specified cluster, such as to add or remove worker pools from each zone that the worker pool spans. Resizing the worker pool resets the desired count of worker node per zone.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool.resize
Request
Request Body
ResizeWorkerPool
The resize request.
allowSingleOpenShiftWorker
boolean
cluster
string
size
integer
workerpool
string
Path Parameters
Query Parameters
Response
202 - Accepted. The worker pool will be resized to the specified value.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
GET /v2/rotateClusterCOSKey
Do not use it as this endpoint is not supported in the long term. Rotates the ROKS cluster's HMAC data.
Rotates the HMAC service key, key ID and key GUID associated to the cluster. If the bucket of the cluster doesn't exist it gets created firstly.`
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-cos-key.rotate
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster of which you want to rotate the COS data. To list the clusters that you have access to, use the `GET /v2/getClusters` API or run `ibmcloud ks cluster ls`.
Response
204 - No Content. Indicates that the rotation was successful.
400 - Bad request. The query parameters are either incomplete or in the wrong format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v2/getClusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create an IBM Cloud Satellite cluster.
POST /v2/satellite/createCluster
Create an OpenShift Container Platform cluster in an IBM Cloud Satellite location. Creating a cluster requires Administrator access to Kubernetes Service in the IBM Cloud account. After you create a Satellite cluster, assign hosts to the cluster to add compute capacity for your workloads.
Request
Request Body
MultishiftCreateCluster
The configuration details for your Satellite cluster, in JSON format. The "controller" field (required) is the name or ID of the location to deploy the cluster to. The "name" field (required) is the name to give the cluster. The "kubeVersion" field is optional, and defaults to the latest Red Hat OpenShift on IBM Cloud version when not specified.
adminAgentOptIn
boolean
Optional: User provided value to indicate opt-in agreement to SatCon admin agent
calicoIPAutodetection
object
Optional: Used to determine the correct IP for internal routing
controller
string
The name or ID of the Satellite location
defaultWorkerPoolEntitlement
string
Optional: The entitlement to use in the default worker pool
infrastructureTopology
string
Optional: Enables single worker node clusters
kubeVersion
string
Optional: The OpenShift Container Platform version
labels
object
Key-value pairs to label the host, such as cpu=4 to describe the host capabilities
name
string
The unique name for the new IBM Cloud Satellite cluster
networkPlugin
string
Optional: NetworkPlugin indicates what container network interface has to be used in the cluster. If the field is missing it is defaulted to Calico.
operatingSystem
string
Optional: The operating system to use in the default worker pool
podSubnet
string
Optional: User provided value for the pod subnet
pullSecret
string
Optional: The RedHat pull secret to create the OpenShift cluster
requestSecure
boolean
Optional: Flag to request a secure cluster is created
serviceSubnet
string
Optional: User provided value for service subnet
trustedProfileID
string
Optional: The trusted profile ID to set in the cluster
workerCount
integer
Optional: The number of worker nodes to create per zone in the default worker pool
zone
string
Optional: The name of the zone to create the default worker pool in
Path Parameters
Query Parameters
Response
201 - Created. The cluster was successfully created in the IBM Cloud Satellite location.
id
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. A cluster with the same name already exists. Choose another name for your cluster.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create an IBM Cloud Satellite cluster in a location that does not belong to your account.
POST /v2/satellite/createClusterRemoteLocation
Create an OpenShift Container Platform cluster in an IBM Cloud Satellite location that belongs to another account. Creating a cluster requires service-to-service IAM authorization in the target IBM Cloud account. After you create a Satellite cluster, the account owner is responsible for providing hosts to run the worker nodes.
Request
Request Body
MultishiftCreateCluster
The configuration details for your Satellite cluster, in JSON format. The "controller" field (required) is the name or ID of the location to deploy the cluster to. The "name" field (required) is the name to give the cluster. The "kubeVersion" field is optional, and defaults to the latest Red Hat OpenShift on IBM Cloud version when not specified.
adminAgentOptIn
boolean
Optional: User provided value to indicate opt-in agreement to SatCon admin agent
calicoIPAutodetection
object
Optional: Used to determine the correct IP for internal routing
controller
string
The name or ID of the Satellite location
defaultWorkerPoolEntitlement
string
Optional: The entitlement to use in the default worker pool
infrastructureTopology
string
Optional: Enables single worker node clusters
kubeVersion
string
Optional: The OpenShift Container Platform version
labels
object
Key-value pairs to label the host, such as cpu=4 to describe the host capabilities
name
string
The unique name for the new IBM Cloud Satellite cluster
networkPlugin
string
Optional: NetworkPlugin indicates what container network interface has to be used in the cluster. If the field is missing it is defaulted to Calico.
operatingSystem
string
Optional: The operating system to use in the default worker pool
podSubnet
string
Optional: User provided value for the pod subnet
pullSecret
string
Optional: The RedHat pull secret to create the OpenShift cluster
requestSecure
boolean
Optional: Flag to request a secure cluster is created
serviceSubnet
string
Optional: User provided value for service subnet
trustedProfileID
string
Optional: The trusted profile ID to set in the cluster
workerCount
integer
Optional: The number of worker nodes to create per zone in the default worker pool
zone
string
Optional: The name of the zone to create the default worker pool in
Path Parameters
Query Parameters
Response
201 - Created. The cluster was successfully created in the IBM Cloud Satellite location.
id
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. A cluster with the same name already exists. Choose another name for your cluster.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create an IBM Cloud Satellite location.
POST /v2/satellite/createController
Create an IBM Cloud Satellite location in the IBM Cloud account that you are logged into. Creating a location requires Administrator access to Kubernetes Service in the IBM Cloud account.
Request
Request Body
MultishiftCreateController
The configuration details for your Satellite location, in JSON format.
calicoIPAutodetection
object
Optional: Used to determine the correct IP for internal routing
capabilitiesManagedBySatellite
array
Satellite capabilities attached to the location
coreos_enabled
boolean
Indicates whether CoreOS features should be enabled for the location. A null value signals that the server should apply its default policy.
cos_config
COSBucket
COSBucket Optional: IBM Cloud Object Storage bucket configuration details
bucket
string
endpoint
string
region
string
serviceInstance
object
cos_credentials
COSAuthorization
COSAuthorization Optional: IBM Cloud Object Storage authorization keys
access_key-id
string
The HMAC secret access key ID
secret_access_key
string
The HMAC secret access key
description
string
A description of the new Satellite location
iaas
IAAS
credential
array
A JSON encoded credential string specific to the chosen provider
provider
string
The name of the infrastructure provider for the Satellite location, such as AWS, Azure, GCP or IBM Cloud.
region
string
The name of region in the infrastructure provider that is used for the Satellite location, such as the AWS 'us-east-2' region.
ingestion_keys
IngestionKeys
IngestionKeys Optional: Keys that can be passed in during Satellite location creation
activity_tracker_key
string
logging_key
string
location
string
The IBM Cloud metro from which the Satellite location is managed
loggingAccountID
string
The account ID for IBM Log Analysis with LogDNA log forwarding
multishiftPodSubnet
string
Optional: Used to determine the pod subnet
multishiftServiceSubnet
string
Optional: Used to determine the service subnet
name
string
A unique name for the new Satellite location
physicalAddress
string
An optional physical address of the new Satellite location which is deployed on premise
zones
array
The names of at least three high availability zones to use for the location (e.g. cloud-zone-1, cloud-zone-2, cloud-zone-3)
Path Parameters
Query Parameters
Response
201 - Created. The location was successfully created in the IBM Cloud account that you are logged in to.
crn
string
id
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. A location with the same name already exists. Choose another name for your location.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create a worker pool for an IBM Cloud Satellite cluster.
POST /v2/satellite/createWorkerPool
Create a worker pool for the specified cluster in an IBM Cloud Satellite location. Creating a worker pool requires Operator access to Kubernetes Service in the IBM Cloud account. Specify the worker pool `flavor` as "upi" for user provided infrastructure. You can also use `hostLabels` key value pairs so that available hosts with matching labels in the IBM Cloud Satellite location are automatically assigned to the worker pool.
Request
Request Body
v2SatelliteCreateWorkerPoolRequest
The configuration details for your worker pool, in JSON format.
Zones
array
cluster
string
diskEncryption
boolean
entitlement
string
flavor
string
hostLabels
object
isolation
string
labels
object
name
string
operatingSystem
string
workerCount
integer
Path Parameters
Query Parameters
Response
201 - Created. The worker pool was successfully created in the specified cluster.
workerPoolID
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. Another worker pool might be provisioning for the specified cluster. Wait a few minutes and try again.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create a zone in the specified worker pool for an IBM Cloud Satellite cluster.
POST /v2/satellite/createWorkerPoolZone
Create a zone in the specified worker pool for an IBM Cloud Satellite cluster. Worker nodes are provisioned in each zone based on the size per zone of the worker pool.
Request
Request Body
SatelliteWorkerPoolZoneAdd
Input parameters to add zones to the worker pool.
cluster
string
id
string
workerpool
string
Path Parameters
Query Parameters
Response
201 - OK. The requested zone was added to the worker pool.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the `GET /v2/getWorkerPools` API or run `ibmcloud ks worker-pool ls -c <cluster>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. The provided zone already exists in the worker pool.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List the IBM Cloud Satellite clusters that you have access to.
GET /v2/satellite/getClusters
List the IBM Cloud Satellite clusters that you have access to.
Request
Path Parameters
Query Parameters
Response
200 - Success. A list of clusters that you have access to is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get the details for an IBM Cloud Satellite location.
GET /v2/satellite/getController
Get the details for an IBM Cloud Satellite location.
Request
Path Parameters
Query Parameters
controller
Required *
string
The ID of the location to get information about.
Response
200 - Success. The details of the requested IBM Satellite location are returned.
activityTrackerKeyProvided
boolean
addons
array
caCertRotationStatus
CommonClusterCACertRotation
CommonClusterCACertRotation CA cert rotation properties
calicoIPAutodetectionConfig
string
capabilitiesManagedBySatellite
array
coreosEnabled
boolean
cos_config
COSBucket
COSBucket Optional: IBM Cloud Object Storage bucket configuration details
createdDate
string
crn
string
datacenter
string
deployments
Deployments
Deployments reports status of deployments on the IBM Cloud Satellite location
description
string
desiredTrustedProfileID
string
disableAutoUpdate
boolean
entitlement
string
etcdPort
string
features
CommonClusterFeatures
hostUpdateSeverity
string
HostUpdateSeverity indicates the highest update severity among all worker nodes (hosts) in this location. Possible values: "" (no update needed), warning (behind by patch/build version), critical (behind by minor version).
hosts
Hosts
Hosts lists the hosts belonging to the IBM Cloud Satellite location
iaas
IAAS
id
string
ignitionServerURL
string
ignition_server_port
integer
imageSecurityEnabled
boolean
ingress
CommonClusterIngress
isPaid
boolean
keyManagementService
CommonClusterKMS
konnectivityServerURL
string
konnectivity_server_port
integer
lifecycle
CommonClusterLifecycle
location
string
locationZones
array
logDNAKeyProvided
boolean
masterKubeVersion
string
masterURL
string
multiAzCapable
boolean
name
string
networkPlugin
string
oauthServerURL
string
offering
string
open_vpn_server_port
integer
outboundTrafficProtection
string
physicalAddress
string
podSubnet
string
provider
string
region
string
resourceGroup
string
resourceGroupName
string
secureByDefault
string
secureRequested
boolean
serviceEndpoints
CommonClusterServiceEndpoint
serviceSubnet
string
state
string
The lifecycle state of the cluster. Possible values include aborted, critical, delete_failed, deleted, deleting, deploy_failed, deploying, normal, pending, requested, updating, unsupported, and warning. For more information, see the docs 'http://ibm.biz/cluster-health-states'
status
string
supportedOperatingSystems
array
targetVersion
string
trustedProfileID
string
type
string
versionEOS
string
virtualPrivateEndpointURL
string
vpcs
array
workerCount
integer
workerZones
array
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Could not find the IBM Cloud Satellite location. To list available locations, use the `GET /v2/satellite/getControllers` API, or run `ibmcloud sat location ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List the IBM Cloud Satellite locations that you have access to.
GET /v2/satellite/getControllers
List the IBM Cloud Satellite locations that you have access to.
Request
Path Parameters
Query Parameters
Response
200 - Success. A list of locations that you have access to is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List the clusters in an IBM Cloud Satellite location that are associated with a Satellite-enabled service instance.
GET /v2/satellite/getServiceClusters
List the clusters that are associated with a Satellite-enabled service that you deployed to your IBM Cloud Satellite location. The clusters in this list are managed by IBM Cloud to provide the cloud service in the location, but you still provide the hosts to run the clusters.
Request
Path Parameters
Query Parameters
controller
Required *
string
The ID of the location to list services.
Response
200 - Success. A list of Satellite-enabled service clusters that you have access to is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Assign a host to an IBM Cloud Satellite location or cluster.
POST /v2/satellite/hostqueue/createAssignment
Assign a host to an IBM Cloud Satellite location or cluster. Before you can assign hosts to clusters, first assign at least three hosts to the Satellite location, to run control plane operations. Then, when you have Satellite clusters, you can assign hosts as needed to provide compute resources for your workloads. You can assign hosts by specifying a host ID or by providing labels to match hosts to your request.
Request
Request Body
MultishiftCreateAssignment
The configuration details to assign a host to an IBM Cloud Satellite resource, in JSON format. The "cluster" field (required) indicates the name or ID of the IBM Cloud Satellite resource to assign the host. The resource can be the name or ID of the Satellite location itself, or an IBM Cloud Satellite cluster. If "hostID" is specified, that host is assigned if it is available. If a set of "labels" is specified, all the available hosts are scanned to find a host that matches all the labels. If neither "hostID" nor "labels" are specified, a random available host is assigned.
cluster
string
The name or ID of a Satellite location or cluster to assign the host to
controller
string
The name or ID of the Satellite location
hostID
string
Optional: The name or ID of the specific host to assign to a Satellite location or cluster
labels
object
Key-value pairs to label the host, such as cpu=4 to describe the host capabilities
workerpool
string
Optional: The name or ID of the worker pool within the cluster to assign the host to
zone
string
Optional: The zone within the cluster to assign the host to
Path Parameters
Query Parameters
Response
201 - Created. A host was successfully assigned to your IBM Cloud Satellite resource.
hostID
string
id
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Could not find the IBM Cloud Satellite location. To list available locations, use the `GET /v2/satellite/getControllers` API, or run `ibmcloud sat location ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. Could not find any available hosts that match your requested host ID or label parameters.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Attach a host to an IBM Cloud Satellite location.
POST /v2/satellite/hostqueue/createRegistrationScript
Create a script to run on a Red Hat Enterprise Linux 7 host in your on-premises infrastructure. The script attaches the host to your IBM Cloud Satellite location. The host must have access to the public network in order for the script to complete.
Request
Request Body
MultishiftNodeQueue
The configuration details to create an attachment script for your Satellite location, in JSON format. The "labels" field (required) is a set of key-value pairs to describe your host, such as cpu=4. Later, when you assign a host to IBM Cloud Satellite resources, these labels are used to match your host with your request.
controller
string
The name or ID of the Satellite location
labels
object
Key-value pairs to label the host, such as cpu=4 to describe the host capabilities
Path Parameters
Query Parameters
Response
201 - Created. The response contains a script that you can run on your host to attach the host to your IBM Cloud Satellite location.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
404 - Could not find the IBM Cloud Satellite location. To list available locations, use the `GET /v2/satellite/getControllers` API, or run `ibmcloud sat location ls`.
500 - Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
List the hosts in your IBM Cloud Satellite location.
GET /v2/satellite/hostqueue/getHosts
List the hosts in your IBM Cloud Satellite location.
Request
Path Parameters
Query Parameters
controller
Required *
string
The ID of the location to to retrieve hosts from.
Response
200 - Success. A list of hosts in your IBM Cloud Satellite location is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Could not find the IBM Cloud Satellite location. To list available locations, use the `GET /v2/satellite/getControllers` API, or run `ibmcloud sat location ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Remove a host from an IBM Cloud Satellite location or cluster.
POST /v2/satellite/hostqueue/removeHost
Remove a host from an IBM Cloud Satellite resource, such as a cluster. The host is removed from the resource and no longer available in IBM Cloud Satellite. However, if you want, you must still delete the host machine in the underlying infrastructure provider. Before you can remove a host, you must remove the worker node that runs on the host. To check worker nodes on the host, use the `GET /v2/satellite/hostqueue/getHosts` API or run `ibmcloud sat host ls`. To remove a worker node, run `ibmcloud ks worker rm -c <cluster_name_or_ID> -w <worker_ID>`.
Request
Request Body
MultishiftRemoveNode
The configuration details to remove a host from an IBM Cloud Satellite location, in JSON format.
controller
string
The name or ID of the Satellite location
hostID
string
The name or ID of the host to remove
Path Parameters
Query Parameters
Response
204 - OK. The host was successfully removed from your IBM Cloud Satellite location.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Could not find the host. To list available hosts, use the `GET /v2/satellite/hostqueue/getHosts` API or run `ibmcloud sat host ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. Cannot remove the host because a worker node runs on the host. Remove the worker node and try again.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Update a host in your IBM Cloud Satellite location.
POST /v2/satellite/hostqueue/updateHost
Update the labels of a host in your IBM Cloud Satellite location. You can apply a new set of labels only to hosts that are not already assigned to an IBM Cloud Satellite resource.
Request
Request Body
MultishiftUpdateNode
The configuration details to update a host to an IBM Cloud Satellite resource, in JSON format.
controller
string
The name or ID of the Satellite location
hostID
string
The name or ID of the host to update
labels
object
Key-value pairs to label the host, such as cpu=4 to describe the host capabilities
Path Parameters
Query Parameters
Response
204 - OK. The host was successfully updated.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Could not find the host. To list available hosts, use the `GET /v2/satellite/hostqueue/getHosts` API or run `ibmcloud sat host ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. The labels cannot be updated because the host is already assigned to an IBM Cloud Satellite resource, such as a cluster.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Remove an IBM Cloud Satellite Location.
POST /v2/satellite/removeController
Remove an IBM Cloud Satellite location. Before you can remove a location, you must remove any Satellite clusters and the underlying host machines. To list the hosts in your location, run `ibmcloud sat hosts --location <name_or_ID>` and check the Cluster and Worker details in the output.
Request
Request Body
MultishiftCreateClusterFragment
The IBM Satellite location to remove.
calicoIPAutodetection
object
Optional: Used to determine the correct IP for internal routing
controller
string
The name or ID of the Satellite location
infrastructureTopology
string
Optional: Enables single worker node clusters
networkPlugin
string
Optional: NetworkPlugin indicates what container network interface has to be used in the cluster. If the field is missing it is defaulted to Calico.
pullSecret
string
Optional: The RedHat pull secret to create the OpenShift cluster
Path Parameters
Query Parameters
Response
204 - OK. The request to remove your IBM Cloud Satellite location was successfully received.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Could not find the IBM Cloud Satellite location. To list available locations, use the `GET /v2/satellite/getControllers` API, or run `ibmcloud sat location ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. Cannot delete an IBM Cloud Satellite location that has active clusters. To list the clusters in the Satellite location, use the `GET /v2/satellite/getClusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Set the Pod Security admission controller configuration.
POST /v2/setPodSecurity
Set the Pod Security admission controller configuration.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To change the Pod Security admission controller configuration, you must have the Administrator platform role for the Kubernetes Service in IAM.
containers-kubernetes.cluster.update
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-pod-security.set
Request
Request Body
SetPodSecurityRequest
The cluster to target.
cluster
string
configuration
string
Optional: A base64 encoded Kubernetes PodSecurityConfiguration yaml definition. If configuration is present the specified custom configuration will be used. If configuration is not present the default Kubernetes configuration will be used.
Path Parameters
Query Parameters
Response
204 - OK. The request to set the Pod Security admission controller configuration was successfully received.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format. \
Bad Request. Your cluster must run Kubernetes version 1.24 or later to modify the Pod Security admission configuration.
Bad Request. Pod Security admission is not supported for Red Hat OpenShift clusters.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Set custom labels for a worker pool.
POST /v2/setWorkerPoolLabels
Set custom labels for a worker pool and each of its worker nodes. You might use labels to restrict a workload to run on only this worker pool, or to apply a taint so that workloads do not run on the worker pool. To confirm that your custom labels are applied, run `ibmcloud ks worker-pool get -c <cluster_name_or_ID>`. To check the labels of the worker nodes, get the private IP address of the worker node (`ibmcloud ks worker ls -c <cluster_name_or_ID>`) and run `kubectl describe node <worker_private_IP>`. Note that you must not edit the system-provided labels that that come with the worker pool and worker nodes by default, or you might experience unexpected results.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool-label.set
Request
Request Body
SetWorkerPoolLabels
Labels to apply to the worker pool and each of its worker nodes. To apply a custom label to the worker pool, set the "state" field to "labels" and fill in the "labels" section with your label key-value pairs. When you apply a label, all existing custom labels are replaced. If you have existing custom labels that you want to keep, include them in your request. To remove a custom label, set the "state" field to "labels" and in the "labels" section, include the same "key" field, but leave the value field blank "". Note that you must not edit the system-provided labels that that come with the worker pool and worker nodes by default, or you might experience unexpected results.
cluster
string
labels
object
workerpool
string
Path Parameters
Query Parameters
Response
204 - OK. The request to set the labels of the worker pool was successfully received.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Set the operating system of a worker pool.
POST /v2/setWorkerPoolOperatingSystem
Set the operating system of a worker pool. To confirm that your modification is applied, check the details of a worker pool (`ibmcloud ks worker-pool get --cluster CLUSTER --worker-pool POOL`).
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
cluster-worker-pool-operating-system.set
Request
Request Body
SetWorkerPoolOperatingSystem
Sets the operating system of a worker pool.
cluster
string
operatingSystem
string
workerPool
string
Path Parameters
Query Parameters
Response
202 - OK. The request to set the operating system of the worker pool was successful.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - The worker pool's operating system is not suitable for an upgrade this way.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - The specified worker pool could not be found..
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Set custom taints for a worker pool.
POST /v2/setWorkerPoolTaints
Set custom taints for a worker pool and each of its worker nodes. You might use taints so that workloads do not run on the worker pool. To confirm that your custom taints are applied, check the taints of the worker nodes by getting the private IP address of the worker node (`ibmcloud ks worker ls -c <cluster_name_or_ID>`) and run `kubectl describe node <worker_private_IP>`.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool-taint.set
Request
Request Body
SetWorkerPoolTaints
Taints to apply to the worker pool and each of its worker nodes. To apply a custom taint to the worker pool, set the "state" field to "taints" and fill in the "taints" section with your taint key-value pairs where the value contains the taint value and the taint effect separated by a ":" with valid taint effects being "NoSchedule", "PreferNoSchedule", and "NoExecute". When you apply a taint, all existing custom taints are replaced. If you have existing custom taints that you want to keep, include them in your request. To remove a custom taint, set the "state" field to "taints" and in the "taints" section, include the same "key" field, but leave the value field blank "".
cluster
string
taints
object
workerpool
string
Path Parameters
Query Parameters
Response
204 - OK. The request to set the taints of the worker pool was successfully received.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
POST /v2/storage/createAttachment
Create volume attachment for a given worker
Request
Request Body
The config includes ID of the cluster, ID of the worker on which you want to attach a volume, and the unique volume ID of the volume to be attached to a worker. To list the clusters that you have access to, run `ibmcloud ks clusters`. To list all worker nodes for a cluster, run `ibmcloud ks workers <cluster_name_or_ID>`. To list the volumes that you have access to, run `ibmcloud is vols`.
cluster
string
volumeID
string
worker
string
Path Parameters
Query Parameters
Response
201 - Ok. Attach request successfully accepted.
device
Device
id
string
name
string
status
string
type
string
volume
Volume
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified worker could not be found. To list the workers, use the `GET /v2/vpc/getWorkers` API or run `ibmcloud ks workers --cluster <clusterID or Name>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Detach volume from given worker.
POST /v2/storage/deleteAttachment
Request
Request Body
VPCVolumeAttachmentConfig
The config includes ID of the cluster, ID of the worker from which you want to detach volume, and the unique volume attachment ID for the attached volume. To list the clusters that you have access to, run `ibmcloud ks clusters`. To list all worker nodes for a cluster, run `ibmcloud ks workers <cluster_name_or_ID>`.
cluster
string
volumeAttachmentID
string
volumeID
string
worker
string
Path Parameters
Query Parameters
Response
201 - Ok. detach request successfully accepted.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified worker could not be found. To list the workers, use the `GET /v2/vpc/getWorkers` API or run `ibmcloud ks workers --cluster <clusterID or Name>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
GET /v2/storage/getAttachment
Get the volume attachment detail for given volume attachment ID
Request
Path Parameters
Query Parameters
cluster
Required *
string
The ID or name of the cluster. To list the clusters that you have access to, run `ibmcloud ks clusters`.
worker
Required *
string
The ID of the worker node, whose volume attachments needs to be listed. To list all worker nodes for a cluster, run `ibmcloud ks workers <cluster_name_or_ID>`.
volumeAttachmentID
Required *
string
The unique volume attachment ID for the attached volume
Response
200 - Ok.
device
Device
id
string
name
string
status
string
type
string
volume
Volume
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified worker could not be found. To list the workers, use the `GET /v2/vpc/getWorkers` API or run `ibmcloud ks workers --cluster <clusterID or Name>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
GET /v2/storage/getAttachments
Get the volume attachments detail for a given worker
Request
Path Parameters
Query Parameters
cluster
Required *
string
The ID or name of the cluster. To list the clusters that you have access to, run `ibmcloud ks clusters`.
worker
Required *
string
The ID of the worker node, whose volume attachments needs to be listed.
Response
200 - Ok.
volume_attachments
array
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified worker could not be found. To list the workers, use the `GET /v2/vpc/getWorkers` API or run `ibmcloud ks workers --cluster <clusterID or Name>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get the details of a storage volume.
GET /v2/storage/getVolume
Request
Path Parameters
Query Parameters
volumeID
Required *
string
The unique volume ID. To list the volume ID, use the `GET /v2/storage/classic/getVolumes` API or run `ibmcloud ks storage volume ls classic`.
Response
200 - Ok.
id
string
ID .. id is of a volume
name
string
Name .. Name of the volume
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified worker could not be found. To list the workers, use the `GET /v2/vpc/getWorkers` API or run `ibmcloud ks workers --cluster <clusterID or Name>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List storage volumes for a cluster or for the account if no cluster is provided.
GET /v2/storage/getVolumes
Request
Path Parameters
Query Parameters
cluster
string
The ID or name of the classic cluster. To list the clusters that you have access to, run `ibmcloud ks cluster ls --provider classic`.
provider
string
Filter the list for a specific infrastructure provider. Supported values are classic, vpc-classic, and vpc-gen2.
zone
string
The zone to filter volume results by. To list available zones, run `ibmcloud ks locations`.
Response
200 - Ok.
volumes
array
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified worker could not be found. To list the workers, use the `GET /v2/vpc/getWorkers` API or run `ibmcloud ks workers --cluster <clusterID or Name>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Acknowledge the request to expand storage capacity.
PATCH /v2/storage/satellite/ackDesiredStorageConfigCapacity
Acknowledge the request to expand the storage capacity of an existing storage request.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Read Satellite Location access in IAM.
satellite.location.read
Auditing
Calling this method generates the following auditing event.
satellite.storage-configuration.ack-desired-capacity
Request
Request Body
AckDesiredStorageCapacityRequest
Include the ID of the storage request (`request-id`), the cluster ID (`cluster`) and the name or ID of the Satellite location (`controller`) that the cluster is registered to. To list storage requests, use the `/v2/satellite/getDesiredStorageConfig` API. To list the Satellite clusters you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud sat service ls --location=<location-name-or-ID>`.
cluster
string
controller
string
request-id
string
Path Parameters
Query Parameters
Response
201 - OK. The storage request is created.
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - The specified cluster or storage request could not be found. Check the input parameters and try again. Verify the input parameters and retry the request. To list the Satellite clusters you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud sat service ls --location=<location-name-or-ID>`. To list storage requests, use the `/v2/satellite/getDesiredStorageConfig` API.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create an assignment using a Satellite storage configuration for the cluster group(s).
POST /v2/storage/satellite/createAssignment
Create an assignment to install the storage driver that is described by the version of the storage configuration on the cluster group(s). Then, apps that run in the clusters, part of cluster group(s), can use the storage.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Satellite Config Subscription Create access in IAM.
satellite.config-subscription.create
Auditing
Calling this method generates the following auditing event.
satellite.subscription.create
Request
Request Body
CreateSubscriptionInputData
Include following parameters to create an assignment: 1. Name of the assignment (`name`). 2. Storage configuration name or ID (`config`). To list the storage configurations that you have access to, use the `GET /v2/storage/satellite/getStorageConfigurations` API or run `ibmcloud sat storage config ls`. 3. The name or ID of the Satellite location (`controller`). To list the Satellite locations that you have access to, use the `GET /v2/satellite/getControllersAPI` or run `ibmcloud sat location ls`. 4. One or more cluster groups (`groups`) on which you want to apply the configuration. Note that at least one cluster group is required. To list the cluster groups that you have access to, run `ibmcloud sat group ls`. 5. Enable or disable automatic upgrades for the assignment (`autoUpgrade="true|false"`).
autoUpgrade
string
config
string
controller
string
groups
array
name
string
Path Parameters
Query Parameters
Response
200 - OK. An assignment using the storage configuration is created.
addSubscription
AddSubscriptionType
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified config or cluster group(s) could not be found. To list the storage configurations that you have access to, use the `GET /v2/storage/satellite/getStorageConfigurations` API or run `ibmcloud sat storage config ls`. To list the Satellite cluster groups you have access to, run `ibmcloud sat group ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create an assignment using a Satellite storage configuration for a Satellite cluster or service cluster.
POST /v2/storage/satellite/createAssignmentByCluster
Create an assignment to install the storage driver described by the version of the storage configuration on the Satellite cluster or service cluster. Then, apps that run in the cluster can use the storage.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Satellite Config Subscription Create access in IAM.
satellite.config-subscription.create
Auditing
Calling this method generates the following auditing event.
satellite.subscription.create-by-cluster
Request
Request Body
CreateSubscriptionByClusterInputData
Include following parameters to create an assignment: 1. Name of the assignment (`name`). 2. Storage configuration name or ID (`config`). To list the storage configurations for a location that you have access to, use the `GET /v2/storage/satellite/getStorageConfigurationsByController` API or run `ibmcloud sat storage config ls --location LOCATION`. 3. ID of the Satellite cluster or service cluster that you want to apply the configuration to (`cluster`). To list the Satellite clusters that you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud ks cluster ls --provider=satellite`. To list the service clusters for a location that you have access to, run `ibmcloud sat services --location LOCATION`. 4. The name or ID of the Satellite location (`controller`). To list the Satellite locations that you have access to, use the `GET /v2/satellite/getControllersAPI` or run `ibmcloud sat location ls`. 5. Enable or disable automatic upgrades for the assignment (`autoUpgrade="true|false"`).
autoUpgrade
string
cluster
string
config
string
controller
string
name
string
Path Parameters
Query Parameters
Response
200 - OK. An assignment using the storage configuration is created.
addSubscription
AddSubscriptionType
400 - Bad Request. The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud ks cluster ls --provider=satellite`. To list the service clusters for a location that you have access to, run `ibmcloud sat services --location LOCATION`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified config or cluster or location could not be found. To list the storage configurations for the location that you have access to, use the `GET /v2/storage/satellite/getStorageConfigurationsByController` API or run `ibmcloud sat storage config ls --location LOCATION`. To list the Satellite clusters you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud ks cluster ls --provider=satellite`. To list the service clusters for a location that you have access to, run `ibmcloud sat services --location LOCATION`. To list the Satellite locations that you have access to, run `ibmcloud sat location ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Deprecated. To create a Satellite storage configuration, you can use /v2/storage/satellite/createStorageConfigurationByController API instead.
POST /v2/storage/satellite/createStorageConfiguration
Create a Satellite storage configuration based off the storage template, custom parameters, and location that you want to use. Then, assign the storage configuration to your clusters to install the storage driver so that the apps that run in the cluster can use the storage.
Request
Request Body
StorageConfigCreateInput
Include a name for the storage configuration (`config-name`), the storage template name (`storage-template-name`), version (`storage-template-version`), required parameters as per the template specified (`user-config-parameters`, `user-secret-parameters`, and/or `storage-class-parameters`) and the Satellite location (`location`) where you want to use the storage configuration. To list the storage templates and template versions, run `ibmcloud sat storage template ls`. To list the parameters for a given storage template and template version, run `ibmcloud sat storage template get --name=<template-name> --version=<template-version>`. To list the Satellite locations that you have access to, run `ibmcloud sat location ls`.
config-name
string
controller
string
storage-class-parameters
array
storage-template-name
string
storage-template-version
string
user-config-parameters
object
user-secret-parameters
object
Path Parameters
Query Parameters
Response
201 - OK. The storage configuration is created.
addChannel
object
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create a Satellite storage configuration
POST /v2/storage/satellite/createStorageConfigurationByController
Create a Satellite storage configuration based on the storage template, custom parameters, and location that you want to use. After you create the configuration, install the storage driver by assigning the configuration to your clusters or cluster groups with the `/v2/storage/satellite/createAssignmentByCluster` or `/v2/storage/satellite/createAssignment` APIs.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Satellite Config Configuration Update access in IAM.
satellite.config-configuration.update
Auditing
Calling this method generates the following auditing event.
satellite.storage-configuration.create
Request
Request Body
StorageConfigCreateInput
Include a name for the storage configuration (`config-name`); the storage template name (`storage-template-name`), version (`storage-template-version`) (optionally; if unspecified, the default storage template version is picked), required parameters as per the template specified (`user-config-parameters`, `user-secret-parameters`, and/or `storage-class-parameters`) and ID of the Satellite location (`controller`) where you want to use the storage configuration. The `update-assignments` payload parameter may be ignored.
Enter a storage configuration name that is less than 253 characters long and contains only lowercase letters, numbers, `-`, or `.`.
To list the storage templates and template versions that you have access to, run `ibmcloud sat storage template ls`. To list the parameters for a given storage template and template version, run `ibmcloud sat storage template get --name=<template-name> --version=<template-version>`. To list the Satellite locations that you have access to, run `ibmcloud sat location ls`.
config-name
string
controller
string
storage-class-parameters
array
storage-template-name
string
storage-template-version
string
user-config-parameters
object
user-secret-parameters
object
Path Parameters
Query Parameters
Response
201 - OK. The storage configuration is created.
addChannel
object
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
PATCH /v2/storage/satellite/expandDesiredStorageConfigCapacity
Expand the capacity of an existing storage request. Specify the storage request that you want to expand, the cluster it is associated with, and the desired total capacity. Note that capacity expansion is subject to acknowledgement from the Satellite location administator.
To check if the Satellite location administrator has acknowledged the capacity expansion for a given storage request, use the `/v2/satellite/getDesiredStorageConfig` API. After the capacity expansion is acknowledged, the `status` field in the `backend` section of the `/v2/satellite/getDesiredStorageConfig` API response is set to `completed`.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
satellite.storage-configuration.expand-desired
Request
Request Body
ExpandDesiredStorageCapacityRequest
Include the ID of the storage request (`request-id`), the cluster ID (`cluster`) on which it is placed, and the desired total capacity (`total-capacity`). Specify the desired total capacity as a positive integer value in kilobytes (`K`), megabytes (`M`), gigabytes (`G`), terabytes (`T`) or exabytes (`E`). For example, specify `100G` for 100 GB. To list storage requests, use the `/v2/satellite/getDesiredStorageConfig` API. To list the Satellite clusters you have access to, use the `GET /v2/satellite/getClusters` API or run `ibmcloud sat service ls --location=<location-name-or-ID>`.
cluster
string
request-id
string
total-capacity
string
Path Parameters
Query Parameters
Response
201 - OK. The storage request is created.
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - The specified cluster or storage request could not be found. Check the input parameters and try again. To list the Satellite clusters you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud sat service ls --location=<location-name-or-ID>`. To list storage requests, use the `/v2/satellite/getDesiredStorageConfig` API.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List Satellite storage configurations assigned to a Satellite cluster or service cluster.
GET /v2/storage/satellite/getAssignedStorageConfigs
List Satellite storage configurations that are assigned to a Satellite cluster or service cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Read Satellite Location access or the Viewer platform role to Kubernetes Service in IAM.
satellite.location.readcontainers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
satellite.storage-configuration.get-assigned
Request
Path Parameters
Query Parameters
cluster
Required *
string
ID of the Satellite cluster or service cluster to list the assigned storage configurations for. To list the Satellite clusters that you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud ks cluster ls --provider=satellite`. To list the service clusters for a location that you have access to, run `ibmcloud sat services --location LOCATION`.
controller
Required *
string
The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud ks cluster ls --provider=satellite`.
Response
200 - OK. Assigned Satellite storage configurations are listed.
400 - Bad Request. The request failed due to one of the following reasons:
- The cluster is missing or the specified cluster is invalid.
- The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters that you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud ks cluster ls --provider=satellite`. To list the service clusters for a location that you have access to, run `ibmcloud sat services --location LOCATION`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
404 - Not found. The specified cluster or location could not be found. To list the Satellite clusters that you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud ks cluster ls --provider=satellite`. To list the service clusters for a location that you have access to, run `ibmcloud sat services --location LOCATION`. To list the Satellite locations that you have access to, run `ibmcloud sat location ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details of an assignment.
GET /v2/storage/satellite/getAssignment
View details of an assignment by the assignment UUID.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Satellite Config Subscription Read access in IAM.
satellite.config-subscription.read
Auditing
Calling this method generates the following auditing event.
satellite.subscription.get
Request
Path Parameters
Query Parameters
uuid
Required *
string
The UUID of the assignment. To list the assignments that you have access to, use the `GET /v2/storage/satellite/getAssignments` API or run `ibmcloud sat storage assignment ls`.
Response
200 - OK. Assignment details are returned.
channelName
string
channelUuid
string
cluster
string
clusterName
string
configRevisionStatus
object
created
string
groups
array
isAssignmentUpgradeAvailable
boolean
isAutoUpgradeEnabled
boolean
name
string
orgId
string
owner
object
remoteResources
array
rolloutStatus
object
satSvcClusterId
string
satcluster
string
subscriptionType
string
updated
string
uuid
string
version
string
versionUuid
string
400 - Bad Request. Either the uuid is missing or the specified uuid is invalid. To list the assignments that you have access to, use the `GET /v2/storage/satellite/getAssignments` API or run `ibmcloud sat storage assignment ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified assignment could not be found. To list the assignments that you have access to, use the `GET /v2/storage/satellite/getAssignments` API or run `ibmcloud sat storage assignment ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Deprecated. To view details of an assignment, you can use /v2/storage/satellite/getAssignment API instead.
GET /v2/storage/satellite/getAssignmentByName
View details of an assignment by the assignment name.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Satellite Config Subscription Read access in IAM.
satellite.config-subscription.read
Auditing
Calling this method generates the following auditing event.
satellite.subscription.get-by-name
Request
Path Parameters
Query Parameters
name
Required *
string
The name of the assignment. To list the assignments that you have access to, use the `GET /v2/storage/satellite/getAssignments` API or run `ibmcloud sat storage assignment ls`.
Response
200 - OK. Assignment details successfully fetched.
channelName
string
channelUuid
string
cluster
string
clusterName
string
configRevisionStatus
object
created
string
groups
array
isAssignmentUpgradeAvailable
boolean
isAutoUpgradeEnabled
boolean
name
string
orgId
string
owner
object
remoteResources
array
rolloutStatus
object
satSvcClusterId
string
satcluster
string
subscriptionType
string
updated
string
uuid
string
version
string
versionUuid
string
400 - Bad Request. Either the name is missing or the specified name is invalid. To list the assignments that you have access to, use the `GET /v2/storage/satellite/getAssignments` API or run `ibmcloud sat storage assignment ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified assignment could not be found. To list the assignments that you have access to, use the `GET /v2/storage/satellite/getAssignments` API or run `ibmcloud sat storage assignment ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List storage assignments in the IBM Cloud account.
GET /v2/storage/satellite/getAssignments
List storage assignments that you have access to in the IBM Cloud account. Returned details include the assignment name, UUID, and creation timestamp.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Satellite Config Subscription Read access in IAM.
satellite.config-subscription.read
Auditing
Calling this method generates the following auditing event.
satellite.subscription.list
Request
Path Parameters
Query Parameters
Response
200 - OK. Assignments are listed.
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List storage assignments created for a Satellite cluster or service cluster.
GET /v2/storage/satellite/getAssignmentsByClusterID
List storage assignments created for a Satellite cluster or service cluster. Returned details include the assignment name, UUID, and creation timestamp.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Read Satellite Location access or the Viewer platform role to Kubernetes Service in IAM.
satellite.location.readcontainers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
satellite.subscription.get-by-clusterid
Request
Path Parameters
Query Parameters
cluster
Required *
string
ID of the Satellite cluster or service cluster to list the storage assignments for. To list the Satellite clusters that you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud ks cluster ls --provider=satellite`. To list the service clusters for a location that you have access to, run `ibmcloud sat services --location LOCATION`.
controller
Required *
string
The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud ks cluster ls --provider=satellite`.
Response
200 - OK. Assignments are listed.
400 - Bad Request. The request failed due to one of the following reasons:
- The cluster is missing or the specified cluster is invalid. 2.The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters that you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud ks cluster ls --provider=satellite`. To list the service clusters for a location that you have access to, run `ibmcloud sat services --location LOCATION`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or location could not be found. To list the Satellite clusters that you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud ks cluster ls --provider=satellite`. To list the service clusters for a location that you have access to, run `ibmcloud sat services --location LOCATION`. To list the Satellite locations that you have access to, run `ibmcloud sat location ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List storage assignments by configuration name or UUID.
GET /v2/storage/satellite/getAssignmentsByConfig
List storage assignments by configuration name or UUID. Returned details include the assignment name, UUID, and creation timestamp.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Satellite Config Organization Read access in IAM.
satellite.config-organization.read
Auditing
Calling this method generates the following auditing event.
satellite.subscription.get-by-config
Request
Path Parameters
Query Parameters
config
Required *
string
The name or ID of the Satellite storage configuration. To list the storage configurations that you have access to, use the `GET /v2/storage/satellite/getStorageConfigurations` API or run `ibmcloud sat storage config ls`.
Response
200 - OK. Assignments are listed.
400 - Bad Request. Either the config is missing or the specified config is invalid. To list the storage configurations that you have access to, use the `GET /v2/storage/satellite/getStorageConfigurations` API or run `ibmcloud sat storage config ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified config could not be found. To list the storage configurations that you have access to, use the `GET /v2/storage/satellite/getStorageConfigurations` API or run `ibmcloud sat storage config ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List storage assignments in a Satellite location.
GET /v2/storage/satellite/getAssignmentsByController
List storage assignments that you have access to in a Satellite location. Returned details include the assignment name, UUID, and creation timestamp.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Satellite Config Subscription Read access in IAM.
satellite.config-subscription.read
Auditing
Calling this method generates the following auditing event.
satellite.subscription.get-by-controller
Request
Path Parameters
Query Parameters
controller
Required *
string
The name or ID of the Satellite location to list assignments for. To list the Satellite locations that you have access to, run `ibmcloud sat location ls`.
Response
200 - OK. Assignments are listed.
400 - Bad Request. The controller is missing. To list the Satellite locations that you have access to, run `ibmcloud sat location ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified location could not be found. To list the Satellite locations that you have access to, run `ibmcloud sat location ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
GET /v2/storage/satellite/getAvailableStorageClasses
List and filter the available storage classes from assigned Satellite storage configurations on a Satellite or service cluster. By default, only the available storage classes from Software Defined Storage (SDS) template based Satellite storage configurations are returned. To view all available storage classes, set the `onlyShowSDS` query paramter flag to `false`. Optionally, filter the available storage classes based on volume type using the `volumeType` query parameter.
Note that, if a volume type is specified, the most preferable storage class from each of the assigned storage configurations of specified volume type is returned. For user-defined storage classes, the preference is set while creating the storage configuration. To view the preference for all the storage classes of an assigned storage configuration, run `ibmcloud sat storage config class ls --config CONFIG --show-params` and look for the parameter `storage-class-preference`.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Read Satellite Location access or the Viewer platform role to Kubernetes Service in IAM.
satellite.location.readcontainers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
satellite.available.classes.get
Request
Path Parameters
Query Parameters
cluster
Required *
string
The ID of the Satellite cluster or service cluster for which available storage classes from assigned Satellite storage configurations are to be listed. To list the Satellite clusters that you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud ks cluster ls --provider=satellite`. To list the service clusters for a location that you have access to, run `ibmcloud sat services --location LOCATION`.
controller
Required *
string
The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud ks cluster ls --provider=satellite`.
volumeType
string
Filter the available storage classes by volume type. The supported volume types are `file`, `block` and `object`. If unspecified, available storage classes of all volume types are returned.
onlyShowSDS
boolean
Specify `true` or `false` to view only the available storage classes from software-defined storage (SDS) storage configurations. If unspecified, the default value is `true`.
Response
200 - OK. Available storage classes are listed.
storage-classes
array
400 - Bad Request. The request failed due to one of the following reasons:
- The cluster is missing or the specified cluster is invalid. To list the Satellite clusters that you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud ks cluster ls --provider=satellite`. To list the service clusters for a location that you have access to, run `ibmcloud sat services --location LOCATION`.
- The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters that you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud ks cluster ls --provider=satellite`. To list the service clusters for a location that you have access to, run `ibmcloud sat services --location LOCATION`.
- The specified value is an invalid value for parameter `volumeType`. Supported values for `volumeType` parameter are: `file, block, object`.
- The specified value is an invalid value for parameter `onlyShowSDS`. Supported values for `onlyShowSDS` parameter are: `true, false`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or location could not be found. To list the Satellite clusters that you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud ks cluster ls --provider=satellite`. To list the service clusters for a location that you have access to, run `ibmcloud sat services --location LOCATION`. To list the Satellite locations that you have access to, run `ibmcloud sat location ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List Storage requests on a cluster.
GET /v2/storage/satellite/getDesiredStorageConfig
List the storage requests for a cluster in a Satellite location.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Read Satellite Location access or the Viewer platform role to Kubernetes Service in IAM.
satellite.location.readcontainers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
satellite.storage-configuration.get-desired
Request
Path Parameters
Query Parameters
cluster
Required *
string
The ID of the cluster where you want to list storage requests. To list the Satellite clusters you have access to, use the `GET /v2/satellite/getClusters` API or run `ibmcloud sat service ls --location=<location-name-or-ID>`. The response body for each storage request contains the request specifications and the following fields: 1. The`assignment` field. This field is initially empty when the storage request is created. When the location administrator assigns a storage configuration to the cluster that matches the storage request, this field is populated with the UUID of the assignment. 2. A `status` field in the `config` section that indicates the status of storage provisioning or assignment. If a storage assignment is created but no action is taken on it, the status is set to `pending`. If a storage configuration has been assigned to the cluster, the status is set to `assigned`. If the storage request is deleted, the status is set to `deleted`. 3. A `status` field in the `backend` section. This field indicates whether the location administrator has acknowledged the request to increase storage capacity. If the storage capacity expansion request is not acknowledged, the status is set to `pending`. If the request is acknowledged by the location administrator, the status is set to `completed`.
controller
Required *
string
The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters that you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud sat service ls --location=<location-name-or-ID>`.
Response
201 - OK. Storage requests are listed.
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Could not list the IBM Cloud Satellite storage requests. Verify the input parameters and retry the request. To list the Satellite clusters that you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud sat service ls --location=<location-name-or-ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details of a Satellite storage configuration.
GET /v2/storage/satellite/getStorageConfiguration
View the details of a Satellite storage configuration.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Satellite Config Organization Read access in IAM.
satellite.config-organization.read
Auditing
Calling this method generates the following auditing event.
satellite.storage-configuration.get
Request
Path Parameters
Query Parameters
name
Required *
string
The name of the storage configuration. To list the storage configurations that you have access to, run `ibmcloud sat storage config ls`.
include-assignments
boolean
Specify `true` to include details of assignment(s) of the specified storage configuration. The default value is `false`.
Response
201 - OK. Storage configuration details are returned.
config-name
string
config-version
string
controller
string
created
string
is-revision-update-available
boolean
is-user-secret-parameters-set
object
latest-revision
string
location
string
orgId
string
revision
string
storage-class-parameters
array
storage-template-metadata
ConfigAttributes
ConfigAttributes defines attributes related to storage configuration
storage-template-name
string
storage-template-version
string
subscriptions
array
tags
array
template-status
string
user-config-parameters
object
user-secret-parameters
object
uuid
string
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List Satellite storage configurations.
GET /v2/storage/satellite/getStorageConfigurations
List the Satellite storage configurations that you have access to in a Satellite location or in the IBM Cloud account.
Request
Path Parameters
Query Parameters
location
string
The name or ID of the Satellite location to list storage configurations for. If no location is specified, all storage configurations that you have access to in the IBM Cloud account are returned. To list the Satellite locations that you have access to, run `ibmcloud sat location ls`.
Response
201 - OK. Storage configurations are listed.
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List Satellite storage configurations in a Satellite location.
GET /v2/storage/satellite/getStorageConfigurationsByController
List the Satellite storage configurations that you have access to in a Satellite location.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Satellite Config Organization Read access in IAM.
satellite.config-organization.read
Auditing
Calling this method generates the following auditing event.
satellite.storage-configuration.get-by-controller
Request
Path Parameters
Query Parameters
controller
Required *
string
The name or ID of the Satellite location to list storage configurations for. To list the Satellite locations that you have access to, run `ibmcloud sat location ls`.
Response
201 - OK. Storage configurations are listed.
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View the details of a Satellite storage template.
GET /v2/storage/satellite/getStorageTemplate
View the details of a Satellite storage template by name and version
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Read Satellite Location access in IAM.
satellite.location.read
Auditing
Calling this method generates the following auditing event.
satellite.storage-template.get
Request
Path Parameters
Query Parameters
name
Required *
string
The name of the storage template. To list the storage templates that you have access to, use the `GET /v2/storage/satellite/getStorageTemplates` API or run `ibmcloud sat storage template ls`.
version
Required *
string
The version of the storage template. To list the storage templates that you have access to, use the `GET /v2/storage/satellite/getStorageTemplates` API or run `ibmcloud sat storage template ls`.
Response
200 - OK. Storage template details are returned.
custom-parameters
array
description
string
name
string
revision
string
status
string
storage-class-parameters
array
storage-class-template
string
tags
array
vendor-storage-class-parameters
array
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. User is not allowed to use the specified version of the storage template. To list the storage templates that you have access to, use the `GET /v2/storage/satellite/getStorageTemplates` API or run `ibmcloud sat storage template ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified storage template name or version could not be found. To list the storage templates that you have access to, use the `GET /v2/storage/satellite/getStorageTemplates` API or run `ibmcloud sat storage template ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
410 - The specified version of the storage template is unsupported. To list the storage templates that you have access to, use the `GET /v2/storage/satellite/getStorageTemplates` API or run `ibmcloud sat storage template ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View the change log details of Satellite storage templates.
GET /v2/storage/satellite/getStorageTemplateChangelog
View the change log details of all Satellite storage templates or a specific Satellite storage template by name.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Read Satellite Location access in IAM.
satellite.location.read
Auditing
Calling this method generates the following auditing event.
satellite.storage-template.get-changelog
Request
Path Parameters
Query Parameters
name
string
The name of the storage template that you want to get the change log for. To list the storage templates that you have access to, use the `GET /v2/storage/satellite/getStorageTemplates` API or run `ibmcloud sat storage template ls`. To get change logs for all storage templates that you have access to, skip this parameter.
Response
200 - OK. Change log(s) of the storage template(s) is/are returned.
latest-revision
RevisionDetails
previous-revision
RevisionDetails
status
string
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified storage template could not be found. To list the storage templates that you have access to, use the `GET /v2/storage/satellite/getStorageTemplates` API or run `ibmcloud sat storage template ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Failed to fetch the changelog for the storage template. Note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List Satellite storage templates.
GET /v2/storage/satellite/getStorageTemplates
List Satellite storage templates.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Read Satellite Location access in IAM.
satellite.location.read
Auditing
Calling this method generates the following auditing event.
satellite.storage-template.list
Request
Path Parameters
Query Parameters
Response
200 - OK. Storage templates are listed.
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Remove an assignment.
DELETE /v2/storage/satellite/removeAssignment
Remove an assignment with a given UUID.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Satellite Config Subscription Delete access in IAM.
satellite.config-subscription.delete
Auditing
Calling this method generates the following auditing event.
satellite.subscription.delete
Request
Path Parameters
Query Parameters
uuid
Required *
string
ID of the assignment. To list the assignments that you have access to, use the `GET /v2/storage/satellite/getAssignments` API or run `ibmcloud sat storage assignment ls`.
controller
Required *
string
The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the `GET /v2/satellite/getControllers` API or run `ibmcloud sat location ls`.
Response
200 - OK. The assignment is removed.
removeSubscription
RemoveSubscriptionType
400 - Bad Request. Either the uuid is missing or the specified uuid is invalid. To list the assignments that you have access to, use the `GET /v2/storage/satellite/getAssignments` API or run `ibmcloud sat storage assignment ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified assignment could not be found. To list the assignments that you have access to, use the `GET /v2/storage/satellite/getAssignments` API or run `ibmcloud sat storage assignment ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Delete a storage request
DELETE /v2/storage/satellite/removeDesiredStorageConfig
Delete a storage request on a cluster. If the cluster assignment status of a storage request is `pending` when this API is called, the request is deleted from the database. If the storage request is assigned to a cluster, the request is marked as `deleted` but not removed from the database. To check the cluster assignment status of a storage request, see the `status` field in the `config` section of the`/v2/satellite/getDesiredStorageConfig` API response.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
satellite.storage-configuration.delete-desired
Request
Path Parameters
Query Parameters
request-id
Required *
string
The ID of the storage request. To list storage requests, use the `/v2/satellite/getDesiredStorageConfig` API.
cluster
Required *
string
The ID of the cluster (`cluster`) on which the storage request is placed on. To list storage requests, use the `/v2/satellite/getDesiredStorageConfig` API. To list the Satellite clusters you have access to, use the `GET /v2/satellite/getClusters` API or run `ibmcloud sat service ls --location=<location-name-or-ID>`.
Response
201 - OK. The storage configuration is removed.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Remove a Satellite storage configuration.
DELETE /v2/storage/satellite/removeStorageConfiguration
Remove a Satellite storage configuration with a given UUID. If you want to remove a Satellite storage configuration that is currently used in a Satellite storage assignment, set the `removeAssignments` query paramter flag to `true`. This flag when set to `true` removes the storage configuration as well as any associated assignments.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Satellite Config Configuration Update access in IAM.
satellite.config-configuration.update
Auditing
Calling this method generates the following auditing event.
satellite.storage-configuration.delete
Request
Path Parameters
Query Parameters
uuid
Required *
string
The UUID of the storage configuration. To list the storage configurations that you have access to, run `ibmcloud sat storage config ls`. To view the storage assignments associated with a given storage configuration and the storage configuration UUID, run `ibmcloud sat config get --config=<storage-configuration-name>`.
controller
Required *
string
The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the `GET /v2/satellite/getControllers` API or run `ibmcloud sat location ls`.
removeAssignments
boolean
Specify `true` to remove the storage configuration along with the associated assignments. If unspecified, the default value is `false`.
Response
200 - OK. The storage configuration is removed.
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Enable or disable automatic upgrades for an existing storage assignment(s).
PATCH /v2/storage/satellite/setAssignmentAutoupgrade
Enable or disable automatic upgrades for an existing assignment(s) of a given storage configuration. To enable automatic upgrades, specify `autoUpgrade=true`. The default value is `false`. You can enable automatic upgrades for all assignments by specifying `All=true`. Alternatively, you can specify one or more individual assignment `UUIDs` to upgrade specific assignments.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Satellite Config Subscription Update access in IAM.
satellite.config-subscription.update
Auditing
Calling this method generates the following auditing event.
satellite.subscription.update
Request
Request Body
SetAssignmentAutoupgradeInputData
The parameters must include: 1. Storage configuration name or ID (`config`). 2. Satellite Location (`controller`). 3. Set the `autoUpgrade` flag to `true` to enable assignments for automatic upgrades. If unspecified, it is assumed to be `false`. 4. Either set `All` to enable/disable automatic upgrades for all the assignments of the storage configuration or provide the `UUIDs` to enable/disable automatic upgrades for a set of assignments.
assignment
object
all
boolean
uuids
array
autoUpgrade
boolean
config
string
controller
string
Path Parameters
Query Parameters
Response
200 - OK. The assignment(s) is/are enabled/disabled for automatic upgrades.
assignment
object
autoUpgrade
boolean
config
string
controller
string
400 - Bad Request. The request failed due to one of the following reasons:
- The config name/uuid is missing or the specified config is invalid. To list the storage configurations that you have access to, use the `GET /v2/storage/satellite/getStorageConfigurations` API or run `ibmcloud sat storage config ls`.
- Both the parameters `All` and `UUIDs` are provided. Both cannot be provided at the same time.
- No assignment(s) provided to enable/disable automatic upgrade. Neither of the parameters `All` and `UUIDs` are provided.
- The assignment uuid provided in `UUIDs` parameter is invalid. To list the assignments that you have access to, use the `GET /v2/storage/satellite/getAssignmentsByConfig` API or run `ibmcloud sat storage assignment ls --config config`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The request failed due to one of the following reasons:
- The specified config could not be found. To list the storage configurations that you have access to, use the `GET /v2/storage/satellite/getStorageConfigurations` API or run `ibmcloud sat storage config ls`.
- The specified assignment could not be found. To list the storage assignments that you have access to, use the `GET /v2/storage/satellite/getAssignments` API or run `ibmcloud sat storage assignment ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create a storage request on a cluster
POST /v2/storage/satellite/setDesiredStorageConfig
Create a storage request for a cluster by providing the cluster ID and the required storage specifications. You can only create storage requests for the clusters you have access to.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
satellite.storage-configuration.set-desired
Request
Request Body
SetDesiredStorageConfigRequest
The configuration details for your Satellite storage request. Include the cluster ID (`cluster`) and the required storage specifications. To list available clusters in the Satellite location, use the `GET /v2/satellite/getClusters` API or run `ibmcloud sat service ls --location=<location-name-or-ID>`. The following storage specifications are supported: 1. Required: a. Volume type. Specify one of `file`, `block` or `object`. b. Provider. Specify one of the supported providers of storage templates. For a list of supported providers or templates, see `https://github.com/IBM/ibm-satellite-storage/blob/develop/config-templates/template_list.json`. c. Maximum volume size and total capacity. Specify a positive integer value. Use `K` for kilobytes, `M` for megabytes, `G` for gigabytes, `T` for terabytes, or `E` for exabytes. Example: `100G`. 2. Optional parameters. a. Offering type. Specify either `sds` for software-defined storage or `non-sds`. b. Volume encryption at rest. This is a boolean value. Specify `true` or `false`. c. Volume availability. This is a boolean value. Specify `true` or `false`. d. Volume expansion. This is a boolean value. Specify `true` or `false`. e. Volume snapshot. This is a boolean value. Specify `true` or `false`. f. Storage classes. Include a list of specific storage classes. Note that currently, requested storage classes are not strictly validated while provisioning storage.
See the following example payload for a storage request that specifies the cluster ID, volume type, offering type, provider, volume availability, volume expansion, volume snap shot, and storage classes: `{"cluster": "c9l508rw0eo68tnbijrg","storage-requests": {"volume-type": "file","offering-type": "sds","provider": "redhat","volume-availability": "regional","volume-expansion": "true","volume-encryption-at-rest": "true","storageclasses": ["gold"],"volume-snapshot": "false","max-volume-size": "100G","total-capacity": "1T"}}`
cluster
string
storage-requests
DesiredAttributes
DesiredAttributes are various attributes associated with a particular storage request
max-volume-size
string
offering-type
string
provider
string
storageclasses
array
total-capacity
string
volume-availability
string
volume-encryption-at-rest
string
volume-expansion
string
volume-snapshot
string
volume-type
string
Path Parameters
Query Parameters
Response
201 - OK. The storage request is created.
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Could not find the IBM Cloud Satellite cluster, volume type, available volume, or storage class. Verify the input parameters and try again. To list the Satellite clusters that you have access to and their respective location name or ID, use the `GET /v2/satellite/getClusters` API or run `ibmcloud sat service ls --location=<location-name-or-ID>`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Update an assignment.
PATCH /v2/storage/satellite/updateAssignment
Update the details of an assignment, such as the name of the assignment, the storage configuration version that it uses, or the cluster group(s) on which you want to apply the configuration. For updating an assignment to the latest available storage configuration version, set the `updateConfigVersion` flag to `true`. If unspecified, it is assumed to be `false`.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Satellite Config Subscription Update access in IAM.
satellite.config-subscription.update
Auditing
Calling this method generates the following auditing event.
satellite.subscription.update
Request
Request Body
UpdateSubscriptionInputData
The parameters must include the UUID of the assignment (`uuid`) along with at least one of the following parameters to be updated: 1. One or more cluster groups (`groups`) on which you want to apply the configuration. To list the cluster groups that you have access to, run `ibmcloud sat group ls`. 2. New name of the assignment (`name`). 3. set the `updateConfigVersion` flag to `true` for updating an assignment to the latest available storage configuration version. If unspecified, it is assumed to be `false`. To see if assignment upgrade is available, use the `GET /v2/storage/satellite/getAssignment` API and look for `isAssignmentUpgradeAvailable` field in response or run `ibmcloud sat storage assignment get --assignment UUID` and look for `Assignment Upgrade Available` field in response.
groups
array
name
string
updateConfigVersion
boolean
uuid
string
Path Parameters
Query Parameters
Response
200 - OK. The assignment is updated.
editSubscription
UpdateSubscriptionType
400 - Bad Request. The request failed due to one of the following reasons:
- The uuid is missing or the specified uuid is invalid. To list the assignments that you have access to, use the `GET /v2/storage/satellite/getAssignments` API or run `ibmcloud sat storage assignment ls`.
- There is no parameter in the request body to update. Input at least one parameter to be updated.
- Storage assignment is already up to date with the latest available storage configuration version. Set the `updateConfigVersion` flag to `false` if you want to update at least assignment name or cluster group(s) on which you want to apply the configuration.
- Updating an assignment, created for a cluster, to cluster group(s) is not supported. Run `ibmcloud sat storage assignment rm` to remove the assignment and create new assignment with cluster group(s).
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified assignment or cluster group(s) could not be found. To list the storage assignments that you have access to, use the `GET /v2/storage/satellite/getAssignments` API or run `ibmcloud sat storage assignment ls`. To list the Satellite cluster groups you have access to, run `ibmcloud sat group ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Deprecated. To update a Satellite storage configuration, you can use /v2/storage/satellite/updateStorageConfigurationByController instead.
POST /v2/storage/satellite/updateStorageConfiguration
Update an existing Satellite storage configuration. Note that you cannot update Satellite storage configurations that are currently used in a Satellite storage assignment.
Request
Request Body
StorageConfigUpdateInput
Include the storage template name (`storage-template-name`) and version (`storage-template-version`), the name of the existing storage configuration (`config-name`), the required parameters for the specified template (`user-config-parameters`, `user-secret-parameters`, and `storage-class-parameters`) and the Satellite location (`location`) where you want to use the storage configuration. To list the storage configurations that you have access to, run `ibmcloud sat storage config ls`. To view the storage assignments associated with a given storage configuration, run `ibmcloud sat config get --config=<storage-configuration-name>`. To list the storage templates and template versions, run `ibmcloud sat storage template ls`. To list the parameters for a given storage template and template version, run `ibmcloud sat storage template get --name=<template-name> --version=<template-version>`. To list the Satellite locations that you have access to, run `ibmcloud sat location ls`.
config-name
string
controller
string
storage-class-parameters
array
update-assignments
boolean
user-config-parameters
object
user-secret-parameters
object
Path Parameters
Query Parameters
Response
201 - OK. The storage configuration is updated.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Update a Satellite storage configuration.
POST /v2/storage/satellite/updateStorageConfigurationByController
Update an existing Satellite storage configuration. If a Satellite storage configuration is already assigned, only the parameters that are marked as `mutable` can be updated.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Satellite Config Configuration Update access in IAM.
satellite.config-configuration.update
Auditing
Calling this method generates the following auditing event.
satellite.storage-configuration.update
Request
Request Body
StorageConfigUpdateInput
Include the name of the storage configuration (`config-name`) and the name or ID of the relevant Satellite location (`controller`). To apply the updated storage configuration to this storage configuration's existing assignments, set the `update-assignments` option to `true`. If left unspecified, the `update-assignments` option defaults to `false`.
If the storage configuration is assigned, only the configuration (`user-config-parameters`) and secret (`user-secret-parameters`) parameters that are marked as `mutable` can be updated. If the storage configuration is not assigned, all parameters can be updated.
If user-defined storage classes are supported, specify the required storage class parameters (`storage-class-parameters`) for the template that the storage configuration was created from. Note that any existing user-defined storage classes are overwritten by any storage classes specified in this API request's payload. For example, if you intend to define new storage classes and keep the existing storage classes, you must specify the parameters for both the existing and new user-defined storage classes.
To list the storage configurations that you have access to, run `ibmcloud sat storage config ls`. To view the storage assignments associated with a given storage configuration, run `ibmcloud sat config get --config=<storage-configuration-name>`. To list the parameters for a given storage template and template version, run `ibmcloud sat storage template get --name=<template-name> --version=<template-version>`. To list the parameters of existing storage classes, run `ibmcloud sat storage config class ls --config=<storage-configuration-name> --show-params`. To list the Satellite locations that you have access to, run `ibmcloud sat location ls`.
config-name
string
controller
string
storage-class-parameters
array
update-assignments
boolean
user-config-parameters
object
user-secret-parameters
object
Path Parameters
Query Parameters
Response
201 - OK. The storage configuration is updated.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Update a Satellite storage configuration to use the latest template revision.
PATCH /v2/storage/satellite/updateStorageConfigurationRevision
Update a Satellite storage configuration to use the latest template revision and optionally update assignment(s) based on the specified storage configuration. To check if a new template revision is available, view the 'getStorageConfiguration' API response for the storage configuration you want to update and compare your current template revision (`revision`) with the latest template revision (`latest-revision`). To update assignment(s) of the specified storage configuration, set the update assignments (`updateAssignments`) flag to `true`. By default, the flag is set to `false` if not specified and, assignment(s) are not updated as part of the template revision update operation.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Satellite Config Configuration Update access in IAM.
satellite.config-configuration.update
Auditing
Calling this method generates the following auditing event.
satellite.storage-configuration.update-revision
Request
Path Parameters
Query Parameters
config
Required *
string
The name or UUID of the storage configuration. To list the storage configurations that you have access to, run `ibmcloud sat storage config ls`.
controller
Required *
string
The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the `GET /v2/satellite/getControllers` API or run `ibmcloud sat location ls`.
updateAssignments
boolean
Specify `true` or `false` to update assignment(s) of the specified storage configuration. The default value is `false`.
Response
201 - OK. Updated storage configuration template to latest revision.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run `ibmcloud iam oauth-tokens` to retrieve your access tokens.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
406 - Storage configuration template is already up to date with the latest revision.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Update the version of the Kubernetes cluster master node.
POST /v2/updateMaster
Update the Kubernetes master to the default API version. During the update, you cannot access or change the cluster. Worker nodes, apps, and resources that have been deployed by the user are not modified and will continue to run. You might need to change your YAML files for future deployments. For details, see the release notes at https://cloud.ibm.com/docs/containers?topic=containers-cs_versions
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-master.update
Request
Request Body
UpdateMaster
Input parameters to specify the name or ID of the cluster, what version to update the master to, and whether to force the update. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
cluster
string
force
boolean
version
string
Path Parameters
Query Parameters
Response
204 - Ok. The request to update your master node was successfully processed.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. The specified value is already set on the cluster. To list the clusters properties, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create a VPC cluster.
POST /v2/vpc/createCluster
Create a cluster in a Virtual Private Cloud (VPC) that you have access to. Note: This API method requires Administrator platform role for IBM Cloud Kubernetes Service at the account level, as well as access to several other services such as the underlying infrastructure provider. For more information, see 'https://ibm.biz/cluster-perms'.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.
containers-kubernetes.cluster.create
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster.create
Request
Request Body
VPCCreateCluster
Input parameter to add a cluster. For more information, see https://ibm.biz/cluster_create_docs
cosInstanceCRN
string
cseACLEnabled
boolean
defaultWorkerPoolEntitlement
string
disableOutboundTrafficProtection
boolean
disablePublicServiceEndpoint
boolean
infrastructureTopology
string
kubeVersion
string
name
string
networkPlugin
string
offering
string
podSubnet
string
previews
array
provider
string
requestSecure
boolean
securityGroupIDs
array
serviceSubnet
string
trustedProfileID
string
workerPool
VPCCreateClusterWorkerPool
VPCCreateClusterWorkerPool is the vpc version of the worker pool part of a create cluster request.
diskEncryption
boolean
flavor
string
hostPoolID
string
isolation
string
labels
object
name
string
operatingSystem
string
secondaryStorageOption
string
vpcID
string
workerCount
integer
workerVolumeEncryption
object
WorkerVolumeEncryption contains encryption related fields
zones
array
Path Parameters
Query Parameters
Response
201 - Created. The cluster was successfully created in the IBM Cloud account that you are logged in to.
clusterID
string
messages
array
non_critical_errors
ResponseErrors
ResponseErrors are used to communicate to non-critical errors to end users
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. A cluster with the same name already exists. Choose another name for your cluster.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create a worker pool for a VPC cluster.
POST /v2/vpc/createWorkerPool
Create a worker pool for the specified VPC cluster. Creating a worker pool requires Operator access to Kubernetes Service in the IBM Cloud account.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool.create
Request
Request Body
v2VPCCreateWorkerPoolRequest
The
Zones
array
cluster
string
diskEncryption
boolean
entitlement
string
flavor
string
hostPool
string
isolation
string
labels
object
name
string
operatingSystem
string
secondaryStorageOption
string
securityGroupIDs
array
vpcID
string
workerCount
integer
workerVolumeEncryption
WorkerVolumeEncryption
WorkerVolumeEncryption contains encryption related fields
kmsAccountID
string
kmsInstanceID
string
workerVolumeCRKID
string
Path Parameters
Query Parameters
Response
201 - Created. The worker pool was successfully created in for the specified cluster.
workerPoolID
string
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. A worker pool create may already be in progress for the provided cluster. Please wait a few minutes and try again.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Create a zone in the specified worker pool for a VPC cluster.
POST /v2/vpc/createWorkerPoolZone
Create a zone in the specified worker pool for a VPC cluster. Workers will be provisioned in each provided zone based on the size of the pool.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool-zone.create
Request
Request Body
CreateWorkerpoolZoneRequest
Input parameters to add zones to the worker pool.
cluster
string
id
string
subnetID
string
workerpool
string
Path Parameters
Query Parameters
Response
201 - OK. The requested zone has been added to the worker pool.
400 - Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the `GET /v1/clusters/{idOrName}/workerpools` API or run `ibmcloud ks worker-pool ls mycluster`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
409 - Conflict. The provided zone already exists in the worker pool.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Get details of a VPC cluster.
GET /v2/vpc/getCluster
Get details of a VPC cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster.get
Request
Path Parameters
Query Parameters
showResources
string
To view additional cluster resources like addons, VLANs, subnets, and storage, pass `true`.
cluster
Required *
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Response
200 - Success. Detailed cluster information.
addons
array
caCertRotationStatus
CommonClusterCACertRotation
CommonClusterCACertRotation CA cert rotation properties
calicoIPAutodetectionConfig
string
createdDate
string
crn
string
datacenter
string
desiredTrustedProfileID
string
disableAutoUpdate
boolean
entitlement
string
etcdPort
string
features
CommonClusterFeatures
id
string
ignitionServerURL
string
imageSecurityEnabled
boolean
ingress
CommonClusterIngress
isPaid
boolean
keyManagementService
CommonClusterKMS
konnectivityServerURL
string
lifecycle
CommonClusterLifecycle
location
string
locationZones
array
masterKubeVersion
string
masterURL
string
monitoringURL
string
multiAzCapable
boolean
name
string
oauthServerURL
string
offering
string
podSubnet
string
provider
string
region
string
resourceGroup
string
resourceGroupName
string
secureRequested
boolean
serviceEndpoints
CommonClusterServiceEndpoint
serviceSubnet
string
state
string
The lifecycle state of the cluster. Possible values include aborted, critical, delete_failed, deleted, deleting, deploy_failed, deploying, normal, pending, requested, updating, unsupported, and warning. For more information, see the docs 'http://ibm.biz/cluster-health-states'
status
string
supportedOperatingSystems
array
targetVersion
string
trustedProfileID
string
type
string
versionEOS
string
vlans
array
workerCount
integer
workerZones
array
worker_vlans
VLANS
VLANS is a helper type to sort an api.VLAN list. The VLANS will sort the list in order of the Properties.PrimaryRouter value so that VLAN's of a common router are listed consecutively.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List the VPC clusters that you have access to.
GET /v2/vpc/getClusters
List the VPC clusters that you have access to.
Request
Path Parameters
Query Parameters
location
string
Specify a location to filter clusters for. To see supported locations, use the `GET /v1/locations` API or run `ibmcloud ks locations`.
provider
string
The name of the provider to filter the clusters by.
Response
200 - Success. A list of clusters that you have access to is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View subnets for a given VPC.
GET /v2/vpc/getSubnets
View details for subnets in a VPC for the given region and provider.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-subnet.list
Request
Path Parameters
Query Parameters
provider
Required *
string
The name of the VPC provider.
zone
Required *
string
The name of the zone in which to list subnets.
vpc
Required *
string
The ID of the VPC.
Response
200 - Ok. A list of all subnets for the given VPC is returned.
400 - Bad Request. The given provider, zone, or VPC is invalid.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details of a VPC.
GET /v2/vpc/getVPC
View details of a virtual private cloud (VPC).
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-vpc.get
Request
Path Parameters
Query Parameters
provider
Required *
string
The name of the infrastructure provider that the VPC is created in. To list infrastructure providers of a VPC, run `ibmcloud ks vpcs` or use the `GET /v2/vpc/getVPCs` API.
vpcID
Required *
string
The ID of the VPC. To list the ID of a VPC, run `ibmcloud ks vpcs` or use the `GET /v2/vpc/getVPCs` API.
Response
200 - OK. Details of the specified VPC are returned.
id
string
messages
array
name
string
resourceGroup
string
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View VPCs for the given provider.
GET /v2/vpc/getVPCs
View details for all VPCs in the given provider
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.account-vpc.list
Request
Path Parameters
Query Parameters
provider
Required *
string
The name of the provider in which to list VPCs.
Response
200 - Ok. A list of all VPCs is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
403 - Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details of a worker node for VPC cluster.
GET /v2/vpc/getWorker
View detailed information for a worker node in a VPC cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.worker.get
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
worker
Required *
string
The ID of the worker node that you want details for. To list all worker nodes for a cluster, use the `GET /v1/clusters/{idOrName}/workers` API or run `ibmcloud ks worker ls --cluster <cluster_name_or_ID>`.
Response
200 - Ok. Detailed information about the worker node is returned.
dedicatedHostId
string
dedicatedHostPoolId
string
flavor
string
health
GetWorkerResponseHealth
id
string
kubeVersion
GetWorkerResponseKubeVersion
lifecycle
GetWorkerResponseLifecycle
location
string
networkInterfaces
GetWorkerResponseNetworkInterfaces
poolID
string
poolName
string
provider
string
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View details of a worker pool for a VPC cluster.
GET /v2/vpc/getWorkerPool
View detailed information for a worker pool in a VPC cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool.get
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
workerpool
Required *
string
The ID of the worker pool that you want details for. To list all worker pools for a cluster, use the `GET /v1/clusters/{idOrName}/workerpools` API or run `ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>`.
Response
200 - Ok. Detailed information about the worker pool is returned.
autoscaleEnabled
boolean
dedicatedHostPoolId
string
flavor
string
flavorState
string
hostLabels
object
id
string
isBalanced
boolean
isolation
string
labels
object
lifecycle
GetWorkerPoolResponseLifecycle
openshiftLicense
string
operatingSystem
string
poolName
string
provider
string
secondaryStorageOption
DiskConfigResp
DiskConfigResp response type for describing a disk configuration
staticNetworkInterfaceCount
integer
taints
object
vpcID
string
workerCount
integer
workerVolumeEncryption
WorkerVolumeEncryption
WorkerVolumeEncryption contains encryption related fields
zones
array
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List the worker pools in a VPC cluster.
GET /v2/vpc/getWorkerPools
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker-pool.list
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
Response
200 - Ok. Detailed information about the worker pools is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
View all workers for VPC cluster.
GET /v2/vpc/getWorkers
View detailed information for all worker nodes in a VPC cluster.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.read
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.cluster-worker.list
Request
Path Parameters
Query Parameters
cluster
Required *
string
The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
showDeleted
string
true|false Shows deleted workers
pool
string
The name or ID of the worker pool to filter results for. Run `ibmcloud ks worker-pool ls --cluster <cluster name>`.
Response
200 - Ok. Details for all workers in the VPC cluster.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster could not be found. To list the clusters that you have access to, use the `GET /v1/clusters` API or run `ibmcloud ks cluster ls`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
List available zones in a region.
GET /v2/vpc/getZones
List available zones that you can use to create a cluster in an IBM Cloud Kubernetes Service region.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
No IBM Cloud IAM role is required for this operation.
- ``
Auditing
Calling this method generates the following auditing event.
- ``
Request
Path Parameters
Query Parameters
provider
string
The provider for which to list zones. Defaults to vpc-classic.
showFlavors
boolean
Determines whether to show the flavors for the returned zones.
Response
200 - Success. A list of available zones for a region is returned.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - No zones found for provider. Run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
Replace a worker node with a new worker node.
POST /v2/vpc/replaceWorker
Delete the specified worker node from the cluster and provision a new worker node to replace the deleted worker node. You might replace a worker node if you cannot reload it, such as if it enters a troubled state. You can also replace the worker node to include an update to the same major and minor version of the master. The replacement worker node is created in the same zone, same worker pool, and with the same flavor as the deleted worker node. However, the replacement worker node is assigned a new private IP address, and loses any custom labels that you applied to the old worker node (worker pool labels are still applied to the replacement worker node). Before you replace the worker node, consider adding more worker nodes to the cluster and draining the worker node to help avoid downtime for your apps.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.
containers-kubernetes.cluster.operate
Auditing
Calling this method generates the following auditing event.
containers-kubernetes.worker.replace
Request
Request Body
ReplaceWorkerRequest
Input parameters to replace a worker node. The cluster and worker node ID parameters are required. The update parameter is optional. To update the worker node to the same major and minor version as the master, set “update” to true.
cluster
string
update
boolean
workerID
string
Path Parameters
Query Parameters
Response
204 - OK. The worker node is being removed and replaced with a new worker node.
401 - Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run `ibmcloud login` and then `ibmcloud iam oauth-tokens`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
404 - Not found. The specified cluster or worker could not be found. To list the clusters that you have access to, use the `GET /vpc/v2/clusters` API or run `ibmcloud ks cluster ls --provider vpc-classic`.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type
500 - Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
code
string
description
string
incidentID
string
recoveryCLI
string
terseDescription
string
type
string
ErrorType error type