Introduction
Deploy highly available containerized apps in Kubernetes clusters and use the powerful tools of IBM Cloud Kubernetes Service to automate, isolate, secure, manage, and monitor your workloads across cloud locations. Use the IBM Cloud Kubernetes Service API to manage your Kubernetes cluster infrastructure in IBM Cloud. For example, you can create clusters; add capacity for your workloads by resizing worker pools; manage networking, storage, and logging resources that are attached to your cluster; and enable IBM Cloud add-ons to optimize your cluster management experience. To use the Kubernetes API to manage your application workloads within your cluster, see the product documentation.
Before you begin
- Make sure that you have access to a paid IBM Cloud account.
- Choose a strategy for setting up and maintaining a cluster. This process includes choosing worker node flavors, setting up networking, and selecting the highest available configuration as possible.
Charges
With IBM Cloud Kubernetes Service clusters, you can use IBM Cloud infrastructure compute, networking, and storage resources with platform services such as Watson AI or Compose Database-as-a-Service. Each resource might entail its own charges that can be fixed, metered, tiered, or reserved. For more information, see What am I charged for when I use IBM Cloud Kubernetes Service?
Authentication
The IBM Cloud Kubernetes Service API uses IBM Cloud Identity and Access Management (IAM) to authenticate requests. Pass a bearer and a refresh token token in an Authorization header or an apikey. Tokens support authenticated requests without embedding service credentials in every call.
Authorization
To use the IBM Cloud Kubernetes Service API, you must be authorized to work with the service in IBM Cloud Identity and Access Management (IAM). The service uses IAM platform and service access roles to determine your permissions and the actions that you can perform. Make sure that you are assigned Permissions to create a cluster.
Beginning with version 4.0.0, the Node SDK returns a Promise for all methods when a callback isn't specified.
The package location moved to ibm-watson. It's available at watson-developer-cloud but is not updated there. Use ibm-watson to stay up to date.
IAM and Activity Tracker actions by API method
For a list of the IBM Cloud Identity and Access Management (IAM) action and Activity Tracker events by API method, see the product documentation.
Versioning
The API is versioned to support the different infrastructure providers that are available for you to create clusters. All /v1 APIs can be used to work only with IBM Cloud classic infrastructure. To work with a cluster that was provisioned on IBM Virtual Private Cloud (VPC) infrastructure, you must use the /v2 API.
For information about the API versions, see About the API.
Error handling
This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.
| HTTP error code | Description | Recovery |
|---|---|---|
200 |
Success | The request was successful. |
400 |
Bad Request | The input parameters in the request body are either incomplete or in the wrong format. Include all required parameters in your request. |
401 |
Unauthorized | You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions. |
403 |
Forbidden | The supplied authentication is not authorized to access the cluster or an associated cluster resource. Check that you have the correct access credentials and permissions. |
404 |
Not Found | The requested resource could not be found. |
408 |
Request Timeout | The connection to the server timed out. Wait a few minutes, then try again. |
409 |
Conflict | The cluster or an associated cluster resource with the same name or ID already exists. |
500 |
Internal Server Error | IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support. |
Methods
Delete the autoscaling configuration for an ALB.
Delete an autoscaling configuration for the ALB. Deleting the configuration disables autoscaling.
DELETE /ingress/v2/clusters/{idOrName}/albs/{albID}/autoscaleRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the
GET /clusters/{idOrName}API or runibmcloud ks alb ls --cluster <cluster_name_or_ID>.
Response
Status Code
Ok. Autoscale config was unset successfully.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
Not found. No autoscaling configuration set for this cluster and ALB, or the specified cluster or ALB could not be found.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Get the autoscaling configuration for an ALB.
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.
GET /ingress/v2/clusters/{idOrName}/albs/{albID}/autoscaleRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the
GET /clusters/{idOrName}API or runibmcloud ks alb ls --cluster <cluster_name_or_ID>.
Response
Status Code
Ok. The autoscaling configuration for your ALB is returned.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
Not found. No autoscale configuration set for this cluster and ALB, or the specified cluster or ALB could not be found.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Set the autoscaling configuration for an ALB.
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.
PUT /ingress/v2/clusters/{idOrName}/albs/{albID}/autoscaleRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the
GET /clusters/{idOrName}API or runibmcloud ks alb ls --cluster <cluster_name_or_ID>.
New autoscale configuration to be set.
AutoscaleConfig
Response
Status Code
Ok. The provided autoscaling configuration for your ALB is set.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
Not found. The the specified cluster or ALB could not be found.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Create an Ingress domain for a cluster.
Create an Ingress domain for a cluster.
POST /ingress/v2/dns/createDomain
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Input parameter to create a domain.
Response
ExtendedNlbVPCConfig is the response body for the get v2 vpc apis
Status Code
Created. The domain is created.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Deprecated: Delete external domain provider credential.
Deprecated: Delete the registered external provider credential for a cluster.
POST /ingress/v2/dns/deleteCredential
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
Status Code
No Content. The credential was successfully fetched.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Delete a non-default Ingress domain for a cluster.
Delete a non-default Ingress domain for a cluster.
POST /ingress/v2/dns/deleteDomain
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Input parameter to delete a domain.
Response
Status Code
Ok. The domain is deleted.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Deprecated: Get external domain provider credential metadata.
Deprecated: Get metadata for the registered external provider credential for a cluster.
GET /ingress/v2/dns/getCredential
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
GetCredentials is the return model for a get on a credential
Status Code
Ok. The credential was successfully fetched.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Replace the existing default Ingress domain for a cluster.
Replace the default Ingress domain for a cluster and refresh the related cluster components.
POST /ingress/v2/dns/replaceDefaultSubdomain
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Input parameter to replace default domain.
Response
Status Code
Ok. The default domain is replaced.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Deprecated: Set external domain provider credential.
Deprecated: Register a credential for external domain provider for use in ingress domain commands.
POST /ingress/v2/dns/setCredential
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Input parameter to register an external domain provider credential.
AkamaiCredentials is the struct representation of Akamai creds
CloudflareCredentials is the struct representation of Cloudflare creds
Response
Status Code
Created. The credential was successfully registered.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Update an Ingress domain for a cluster.
Update an Ingress domain with the specified IPs or hostnames.
POST /ingress/v2/dns/updateDomain
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Input parameter to update a domain.
Response
Status Code
Ok. The domain is updated.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Get configuration of load balancers for Ingress ALBs.
Get settings for load balancers that expose Ingress ALBs in your cluster.
GET /ingress/v2/load-balancer/configuration
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name or ID of the cluster.
Type of load balancer configuration to return. Possible options are
publicandprivate.
Response
LBConfig struct models load balancer configuration
LBProxyProtocolConfig stuct for storing the loadbalancer's proxy protocol config in etcd
Status Code
Ok. The load balancer configuration for the specified type is returned.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
Not found. The specified cluster could not be found.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Update the configuration of load balancers for Ingress ALBs.
Configure settings for load balancers that expose Ingress ALBs in your cluster. After you use this API to set load balancer options, the existing load balancers are deleted and recreated, which can cause service disruptions. Two unused IP addresses for each new load balancer must be available in each subnet during the load balancer recreation. To configure load balancers that expose only your public ALBs or only your private ALBs, specify public or private for the type field in the request body. If you leave the type field empty, the configuration is applied to all load balancers that expose ALBs in the cluster.
Available features:
proxyProtocol:- Limitations:
- This feature is supported only for VPC Gen 2 clusters that run Kubernetes version 1.18 or later.
- This feature is cluster-level, therefore
typefield of the request must be empty.
- Configuration:
enable: Set totrueto enable orfalseto 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:5cidr: Load balancer CIDRs from which ALBs process information in PROXY protocol headers. If requests that contain PROXY headers originate from load balancers in other IP ranges, the information in the headers is not process by the ALB. This option has effect only on ALBs running the Kubernetes Ingress image. Default:0.0.0.0/0
- Limitations:
PATCH /ingress/v2/load-balancer/configuration
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
In the request body, specify the desired configuration of load balancer features you want to change.
LBProxyProtocolConfig stuct for storing the loadbalancer's proxy protocol config in etcd
Response
Status Code
Load-balancer configuration submitted and update started.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
Not found. The specified cluster could not be found.
Locked. The previous load-balancer configuration is still in progress.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Add fields to an Ingress secret with a secret stored in IBM Cloud Secrets Manager.
Add fields to an Ingress secret with a secret stored in IBM Cloud Secrets Manager.
POST /ingress/v2/secret/addField
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Input parameter to add a secret field.
FieldAdd the secret field add request
FieldRemove the secret field remove request
Response
Secret struct holding details for a single secret
deprecated: use "Domains" instead
Secrets struct for a secret array
Status Code
Updated. The fields were successfully added to the secret in the cluster.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Create an Ingress secret with a secret stored in IBM Cloud Secrets Manager.
Create an Ingress secret with a secret stored in IBM Cloud Secrets Manager.
POST /ingress/v2/secret/createSecret
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Input parameter to add a secret.
FieldAdd the secret field add request
Response
Secret struct holding details for a single secret
deprecated: use "Domains" instead
Secrets struct for a secret array
Status Code
Created. The secret was successfully created in the cluster.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Delete an Ingress secret from the cluster.
Delete an Ingress secret from the cluster.
POST /ingress/v2/secret/deleteSecret
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Input parameter to add a secret.
Response
Status Code
Deleted. The secret was successfully deleted from the cluster.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The name of the secret that you want information about. To list the secrets that you have access to, use the
GET /ingress/v2/secret/getSecretsAPI or runibmcloud ks ingress secret ls.The namespace of the secret that you want information about. To list the secrets that you have access to, use the
GET /ingress/v2/secret/getSecretsAPI or runibmcloud ks ingress secret ls.
Response
Secret struct holding details for a single secret
deprecated: use "Domains" instead
Secrets struct for a secret array
Status Code
Ok. Detailed information about the secret is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View Ingress secrets for a cluster.
View Ingress secrets for a cluster.
GET /ingress/v2/secret/getSecrets
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.To view previously deleted secrets, pass
true.
Response
Secrets struct for a secret array
deprecated: use "Domains" instead
Secrets struct for a secret array
Status Code
Ok. The list of available Ingress secrets is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Remove fields from an Ingress secret with a secret stored in IBM Cloud Secrets Manager.
Remove fields from an Ingress secret with a secret stored in IBM Cloud Secrets Manager.
POST /ingress/v2/secret/removeField
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Remove input parameter to remove a secret field.
FieldAdd the secret field add request
FieldRemove the secret field remove request
Response
Secret struct holding details for a single secret
deprecated: use "Domains" instead
Secrets struct for a secret array
Status Code
Updated. The fields were successfully removed from the secret in the cluster.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Update an Ingress secret with a secret stored in IBM Cloud Secrets Manager.
Update an Ingress secret with a secret stored in IBM Cloud Secrets Manager.
POST /ingress/v2/secret/updateSecret
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Input parameter to add a secret.
FieldAdd the secret field add request
FieldRemove the secret field remove request
Response
Secret struct holding details for a single secret
deprecated: use "Domains" instead
Secrets struct for a secret array
Status Code
Created. The secret was successfully created in the cluster.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View an IBM Cloud Secrets Manager instance registered to the cluster.
View an IBM Cloud Secrets Manager instance registered to the cluster.
GET /ingress/v2/secret/getInstance
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The name of the instance that you want information about. To list the instances that you have access to, use the
GET /ingress/v2/secret/getInstancesAPI or runibmcloud ks ingress secret instance ls.
Response
Instance struct holding details for a single instance
Status Code
Ok. Detailed information about the secret is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View IBM Cloud Secrets Manager instances registered to the cluster.
View IBM Cloud Secrets Manager instances registered to the cluster.
GET /ingress/v2/secret/getInstances
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.To view previously deleted instances, pass
true.
Response
Instances struct for a secret array
Status Code
Ok. The list of available Ingress secrets is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Register an IBM Cloud Secrets Manager instance to the cluster.
Register an IBM Cloud Secrets Manager instance to the cluster.
POST /ingress/v2/secret/registerInstance
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Input parameter to register an instance.
Response
Instance struct holding details for a single instance
Status Code
Created. The instance was successfully registered to the cluster.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Unregister an IBM Cloud Secrets Manager instance from the cluster.
Unregister an IBM Cloud Secrets Manager instance from the cluster.
POST /ingress/v2/secret/unregisterInstance
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Input parameter to unregister an instance.
Response
Status Code
Deleted. The secret was successfully deleted from the cluster.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Update an IBM Cloud Secrets Manager instance registration configuration to the cluster.
Update an IBM Cloud Secrets Manager instance registration configuration to the cluster.
POST /ingress/v2/secret/updateInstance
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Input parameter to update instance registration.
Response
Status Code
Update. The instance was successfully updated.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified instance could not be found. To list the registered instances that you have access to, use the
GET /v2/secret/getInstancesAPI or runibmcloud ks ingress secret instance ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
OauthAccessTypeJSON for request and response
Status Code
Ok. The OAuth access type for the specified cluster is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Specify the OAuth access type that you want to use. Accepted values are vpegw or legacy.
Response
Status Code
Accepted. The request to set the OAuth access type was successful.
The OAuth access type you specified is not supported.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Modify the outbound traffic protection policy for a VPC cluster using Secure by Default Networking.
POST /network/v2/outbound-traffic-protection
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token.
Specify the outbound traffic protection policy for your cluster. Available options are enable-outbound-protection and disable-outbound-protection.
Response
Status Code
Accepted. The request to set the outbound traffic protection policy was successful.
Bad request. The query parameters are either incomplete or in the wrong format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Disable the subnet allowlist for a Satellite cluster's service endpoint.
Disable the subnet allowlist feature for a Satellite cluster's service endpoint. After you disable this feature, authorized requests to your Satellite cluster master through the Satellite cluster's service endpoint can originate from any subnet.
DELETE /network/v2/satellite-acl/{idOrName}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the Satellite cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the Satellite cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
Status Code
Accepted. The request to disable the Satellite allowlist feature for your Satellite cluster's service endpoint was successfully processed.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Get a Satellite cluster's service endpoint allowlist.
List all subnets in the Satellite allowlist for a Satellite cluster's service endpoint. This list includes subnets that you manually added by using the PATCH /network/v2/satellite-acl/{idOrName}/add API and subnets that are automatically added and managed by IBM, such as worker node subnets.
GET /network/v2/satellite-acl/{idOrName}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the Satellite cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the Satellite cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
SatelliteACLResponse response for GET request
Status Code
Ok. The allowlist for the Satellite cluster's service endpoint is returned.
Bad request. Satellite Service Endpoint Allowlist feature is disabled on the specified cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Add subnets to a Satellite cluster's service endpoint allowlist.
When you add a subnet to a disabled Satellite cluster's service endpoint allowlist, the Satellite allowlist is automatically enabled. Only authorized requests to your Satellite cluster master that originate from subnets in this allowlist are permitted through the Satellite cluster's service endpoint. The subnets for your Satellite cluster's worker nodes must be added to this allowlist for the worker nodes to communicate with the master through the Satellite service endpoint.
PATCH /network/v2/satellite-acl/{idOrName}/addRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the Satellite cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
The list of subnets to add to the Satellite cluster's service endpoint allowlist.
The ACL list to patch
Response
Status Code
Created. The subnets are successfully added to the Satellite cluster's service endpoint allowlist.
No content. The subnets are successfully added to the Satellite cluster's service endpoint allowlist.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Enable the subnet allowlist for a Satellite cluster's service endpoint.
Enable the subnet allowlist feature for a Satellite cluster's service endpoint. After you enable this feature, you can use the PATCH /network/v2/satellite-acl/{idOrName}/add API to add subnets to the allowlist for this Satellite cluster's service endpoint. Only authorized requests to your Satellite cluster master that originate from subnets in the allowlist are permitted through the Satellite cluster's service endpoints.
POST /network/v2/satellite-acl/{idOrName}/enableRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the Satellite cruiser. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
Status Code
Accepted. The request to enable the allowlist feature for your Satellite cluster's service endpoint was successfully processed.
Bad request. The Satellite service endpoint allowlist feature is already enabled on the specified cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Remove subnets from a Satellite cluster's service endpoint allowlist.
Remove subnets that you previously added to the allowlist for a Satellite cluster's service endpoint. After a subnet is removed, any requests that originate from this subnet to the Satellite cluster master through the service endpoint are denied.
PATCH /network/v2/satellite-acl/{idOrName}/rmRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the Satellite cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the Satellite cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
The list of subnets to remove from the Satellite cluster's service endpoint allowlist.
The ACL list to patch
Response
Status Code
Accepted. The subnets are successfully removed from the Satellite cluster's service endpoint allowlist.
No content. The subnets are successfully removed from the Satellite cluster's service endpoint allowlist.
Bad request. Satellite Service Endpoint Allowlist feature is disabled on the specified cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Disable the subnet allowlist for a cluster's private service endpoint.
Disable the subnet allowlist feature for a cluster's private service endpoint. After you disable this feature, authorized requests to your cluster master through the cluster's private service endpoint can originate from any subnet.
DELETE /v1/acl/{idOrName}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
Status Code
Accepted. The request to disable the allowlist feature for your cluster's private service endpoint was successfully processed.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Get a cluster's private service endpoint allowlist.
List all subnets in the allowlist for a cluster's private service endpoint. This list includes subnets that you manually added by using the PATCH /v1/acl/{idOrName}/add API and subnets that are automatically added and managed by IBM, such as worker node subnets.
GET /v1/acl/{idOrName}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
ACLResponse response for GET request
CSEACLList actual and desired
CSEACLList actual and desired
Status Code
Ok. The allowlist for the cluster's private service endpoint is returned.
Bad request. Private Service Endpoint Allowlist feature is disabled on the specified cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Add subnets to a cluster's private service endpoint allowlist.
After you use the POST /v1/acl/{idOrName}/enable API to enable an allowlist for your cluster's private service endpoint, add subnets to the allowlist. Only authorized requests to your cluster master that originate from subnets in this allowlist are permitted through the cluster's private service endpoint. By default, subnets for your cluster's worker nodes are added to this allowlist so that worker nodes can communicate with the master through the private service endpoint.
PATCH /v1/acl/{idOrName}/addRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
The list of subnets to add to the cluster's private service endpoint allowlist.
The ACL list to patch
Response
Status Code
Created. The subnets are successfully added to the cluster's private service endpoint allowlist.
No content. The subnets are successfully added to the cluster's private service endpoint allowlist.
Bad request. Private Service Endpoint Allowlist feature is disabled on the specified cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Enable a subnet allowlist for a cluster's private service endpoint.
Enable the subnet allowlist feature for a cluster's private service endpoint. After you enable this feature, you can use the PATCH /v1/acl/{idOrName}/add API to add subnets to the allowlist for this cluster's private service endpoint. Only authorized requests to your cluster master that originate from subnets in the allowlist are permitted through the cluster's private service endpoint. If the public service endpoint is enabled for your cluster, authorized requests are still permitted through the public service endpoint.
POST /v1/acl/{idOrName}/enableRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
Status Code
Accepted. The request to enable the allowlist feature for your cluster's private service endpoint was successfully processed.
Bad request. The private service endpoint allowlist feature is already enabled on the specified cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Remove subnets from a cluster's private service endpoint allowlist.
Remove subnets that you previously added to the allowlist for a cluster's private service endpoint. After a subnet is removed, any requests that originate from this subnet to the cluster master through the private service endpoint are denied.
PATCH /v1/acl/{idOrName}/rmRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
The list of subnets to remove from the cluster's private service endpoint allowlist.
The ACL list to patch
Response
Status Code
Accepted. The subnets are successfully removed from the cluster's private service endpoint allowlist.
No content. The subnets are successfully removed from the cluster's private service endpoint allowlist.
Bad request. Private Service Endpoint Allowlist feature is disabled on the specified cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Enable VPC Secure by Default Networking on an existing VPC cluster.
POST /network/v2/secure-by-default/enable
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token.
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.
Response
Status Code
Accepted. The request to enable Secure by Default Networking was successful.
Bad request. The query parameters are either incomplete or in the wrong format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Perform operations against a VPC Security Group associated with a cluster.
POST /network/v2/security-group
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token.
Perform an operation against a VPC security group associated with a cluster. Currently supported operations are reset or sync.
Response
Status Code
Accepted. The requested security group operation was successfully processed.
Bad request. The query parameters are either incomplete or in the wrong format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token.
Query Parameters
The name or ID of the cluster. To list the clusters that you have access to, run
ibmcloud ks cluster ls.Filter security groups by type. Specify
cluster,worker,vpc,vpegw, orlbaas.Specify
trueto return the security groups that are shared across the VPC. Or, specifyfalseto return only the cluster specific security groups.Specify
trueto return the security groups created by user. Specifyfalseto return only the IKS managed security groups.
Response
GetSecurityGroupsResponse defines a response when getting list of security groups that are attached to the cluster
Status Code
Ok. A list of security groups associated with the cluster is returned.
Bad request. The query parameters are either incomplete or in the wrong format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
List available add-ons that you can enable in a cluster.
List available add-ons that you can enable in a cluster. For each available add-on, the name, latest version, and minimum Kubernetes version required to run the add-on in a cluster are returned.
GET /v1/addons
Response
AddonCommon represents common properties of an addon
The addon name such as 'istio'.
The addon default versions based on supported cluster version/provider
- defaultVersions
AddonOptionsTemplate represents the options for an addon
- installOptionsTemplate
The minimum kubernetes version for this addon.
The minimum OpenShift version for this addon.
The addon supported providers.
The supported kubernetes version range for this addon.
The supported Openshift version range for this addon.
The addon target version.
The addon version, omit the version if you wish to use the default version.
VLAN spanning required for multi-zone clusters
Status Code
OK. The name, latest version, and minimum required Kubernetes version for each available add-on are returned.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
List available machine types for a zone (data center).
List available machine types that you can use for a worker node. Machine types vary by zone. Each machine type includes the amount of virtual CPU, memory, and disk space that is set up for the worker node. For more information, see http://ibm.biz/machine_types
GET /v1/datacenters/{datacenter}/machine-typesRequest
Path Parameters
The zone ID where you want to list available machine types. To list available zones, run
ibmcloud ks zone lsor use theGET /v1/datacentersAPI.
Response
MachineTypes a type that returns a sorted array of machine types
Status Code
Success
The specified zone is invalid. To list available zones, run
ibmcloud ks zone lsor use theGET /v1/datacentersAPI.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Deprecated: List available Kubernetes versions.
List available Kubernetes versions that you can use to create a cluster.
Note: This API call is deprecated. Use the GET /v1/versions API instead.
GET /v1/kube-versions
Response
KubeVersion the kubernetes version
Status Code
Success. A list of available BOM versions is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
List available locations.
List locations from the IBM Cloud catalog that are supported by the IBM Cloud Kubernetes Service.
GET /v1/locations
Response
IKSLocation properties
Status Code
Success
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View the current messages.
View the current messages. Messages are notifications for new features or changes that may require attention.
GET /v1/messages
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Response
MessageResponse is a user message returned from the API
Status Code
Success
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
List available IBM Cloud Kubernetes Service versions.
List available IBM Cloud Kubernetes Service versions that you can use to create a cluster in a region. The container management platform version that you select is installed on your cluster master and worker nodes. Later, you can update the version but cannot roll back to a previous version or switch to a different container management platform. If you want to use multiple versions, create a separate cluster for each version.
GET /v1/versions
Response
ReleaseVersion is a Kubernetes or OpenShift release version
- any property
PreviewState is a [ReleaseVersion] preview classification
Status Code
Success. Available container management platform versions for the IBM Cloud Kubernetes Service region are returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
List available zones (data centers).
List available zones (data centers) where you can create a cluster.
GET /v1/zones
Request
Query Parameters
Specify true or false to show the machine types available in each zone.
Specify a location to filter zones for. To see supported locations, use the
GET /v1/locationsAPI or runibmcloud ks locations.
Response
Zone properties
MachineTypes a type that returns a sorted array of machine types
The ID of the zone.
Status Code
Success. A list of available zones is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View the current messages.
View the current messages. Messages are notifications for new features or changes that may require attention.
GET /v2/getMessages
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens. If provided, additional messages specific to you or your account may be included.
Response
MessageResponse is a user message returned from the API
Status Code
Success
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Enable an existing ALB in a cluster.
Enable a public or private ALB in your standard cluster.
POST /v1/alb/albs
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
The input parameter to enable an ALB. In the albip field, you can optionally specify an IP address that is on a VLAN in the zone that the ALB was created in. The ALB is enabled with and uses this public or private IP address. Note that this IP address must not be in use by another load balancer or ALB in the cluster. If no IP address is provided, the ALB is deployed with a public or private IP address from the portable public or private subnet that was provisioned automatically when you created the cluster, or the public or private IP address that you previously assigned to the ALB. To switch your ALB from one type of image to another, such as from an IBM Cloud Kubernetes Service ALB image to a community Kubernetes Ingress controller image, specify that image version in the ALBBuild field. To see the supported image versions, use the GET /v2/alb/getAlbImages call. For more information, see https://ibm.biz/alb_configure_docs
The build number of the ALB.
The ID of the application load balancer (ALB).
The type of ALB.
The public IP address that exposes the ALB.
The auth build of the ALB.
The ID of the cluster that the ALB belongs to.
The date the ALB was created.
If set to true, the deployment of the ALB is disabled.
Set to true to enable the ALB, or false to disable the ALB for the cluster.
The name of the cluster that the ALB belongs to.
The version of network load balancer that the ALB uses.
Desired number of ALB replicas that you want in your cluster.
If set to true, resizing of the ALB is done.
The state of the ALB.
The status of the ALB.
The VLAN ID that the ALB is attached to.
The zone where you want to add ALBs.
Response
Status Code
Enabled. The ALB for the cluster was successfully enabled.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
Not found. The specified cluster or ALB could not be found. To list the clusters that you have access to, run
ibmcloud ks cluster ls. To list the ALBs available in a cluster, use theGET /clusters/{idOrName}API or runibmcloud ks alb ls --cluster <cluster_name_or_ID>.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Disable an ALB in your cluster.
Disable a public or private ALB in your standard cluster. When you disable an ALB, the IP address that the ALB used goes back into the pool of available portable IPs so that another service can use the IP. If you later try to re-enable the ALB, the ALB might report an error if the IP address it previously used is now in use by another service. You can either stop running the other service or specify another IP address to use when you re-enable the ALB.
DELETE /v1/alb/albs/{albID}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Path Parameters
The ID of the ALB that you want to disable. To list the IDs for the ALBs in a cluster, use the
GET /v1/alb/clusters/{idOrName}API or runibmcloud ks alb ls --cluster <cluster_name_or_ID>.
Response
Status Code
Disabled. The ALB for the cluster was successfully disabled.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster or ALB could not be found. To list the clusters that you have access to, run
ibmcloud ks cluster ls. To list the ALBs available in a cluster, use theGET /clusters/{idOrName}API or runibmcloud ks alb ls --cluster <cluster_name_or_ID>.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Path Parameters
The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the
GET /clusters/{idOrName}API or runibmcloud ks alb ls --cluster <cluster_name_or_ID>.
Response
The build number of the ALB.
The ID of the application load balancer (ALB).
The type of ALB.
The public IP address that exposes the ALB.
The auth build of the ALB.
The ID of the cluster that the ALB belongs to.
The date the ALB was created.
If set to true, the deployment of the ALB is disabled.
Set to true to enable the ALB, or false to disable the ALB for the cluster.
The name of the cluster that the ALB belongs to.
The version of network load balancer that the ALB uses.
Desired number of ALB replicas that you want in your cluster.
If set to true, resizing of the ALB is done.
The state of the ALB.
The status of the ALB.
The VLAN ID that the ALB is attached to.
The zone where you want to add ALBs.
Status Code
Ok. Details for the specified ALB are returned.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster or ALB could not be found. To list the clusters that you have access to, run
ibmcloud ks cluster ls. To list the ALBs available in a cluster, use theGET /clusters/{idOrName}API or runibmcloud ks alb ls --cluster <cluster_name_or_ID>.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
List all ALBs in a cluster.
List all ALB IDs in a cluster. If no ALB IDs are returned, then the cluster does not have a portable subnet.
GET /v1/alb/clusters/{idOrName}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster that you want to see ALB information for. To list the clusters that you have access to, run
ibmcloud ks cluster ls.
Response
ClusterALB alb related information for vpc cluster
PrivateIngressHostname string
json:"privateIngressHostname"PrivateIngressSecretName stringjson:"privateIngressSecretName"- alb
The build number of the ALB.
The ID of the application load balancer (ALB).
The type of ALB.
The public IP address that exposes the ALB.
The auth build of the ALB.
The ID of the cluster that the ALB belongs to.
The date the ALB was created.
If set to true, the deployment of the ALB is disabled.
Set to true to enable the ALB, or false to disable the ALB for the cluster.
The name of the cluster that the ALB belongs to.
The version of network load balancer that the ALB uses.
Desired number of ALB replicas that you want in your cluster.
If set to true, resizing of the ALB is done.
The state of the ALB.
The status of the ALB.
The VLAN ID that the ALB is attached to.
The zone where you want to add ALBs.
Status Code
Ok. A list of ALB IDs for the cluster is returned.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, run
ibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Force a one-time update of all ALB pods to the latest build.
If automatic updates for Ingress ALBs are disabled, you can force a one-time update of your ALB pods. When you choose to manually update the ALBs, all ALB pods in the cluster are updated to the latest build. You cannot update an individual ALB or choose which build to update the ALBs to. Automatic updates remain disabled.
PUT /v1/alb/clusters/{idOrName}/updateRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
Status Code
Ok. The update has been requested.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Check if automatic updates for Ingress ALBs are enabled in a cluster.
Check if automatic updates for Ingress ALBs are enabled and whether your ALB pods are updated to the latest build version.
GET /v1/alb/clusters/{idOrName}/updatepolicyRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
If set to
true, the cluster is enabled for automatic updates.If set to
true, the cluster log forwarder runs the latest version.
Status Code
Ok. The current update policy.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Enable or disable automatic updates for the Ingress ALBs in a cluster.
By default, automatic updates to Ingress ALBs are enabled. ALB pods are automatically updated when a new build version is available. To instead update the Ingress ALB component manually, you can use this call to disable automatic updates, then use the PUT /clusters/{idOrName}/update call to update all ALB pods.
Note: When you update the major or minor Kubernetes version of your cluster, IBM automatically makes necessary changes to the Ingress deployment, but does not change the build version of your Ingress ALBs. You are responsible for checking the compatability of the latest Kubernetes versions and your Ingress ALB add-on images. If automatic updates for the Ingress ALB component are disabled, you can re-enable automatic updates. Whenever the next build version becomes available, the ALBs are automatically updated to the latest build.
PUT /v1/alb/clusters/{idOrName}/updatepolicyRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
The new update policy configuration.
If set to
true, the cluster is enabled for automatic updates.If set to
true, the cluster log forwarder runs the latest version.
Response
Status Code
Ok. The ALB update policy has been changed.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Create a public or private ALB in a specified zone and VLAN.
Create a new public or private ALB in a specified zone on a specified VLAN. You can also optionally specify an IP address on that VLAN in that zone for the ALB to use.
POST /v1/alb/clusters/{idOrName}/zone/{zoneId}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster that you want to see ALB information for. To list the clusters that you have access to, run
ibmcloud ks cluster ls.The zone in which you want to create an ALB. To see the zones where you can create an ALB, run
ibmcloud ks cluster-get --cluster <cluster_name_or_ID>and look for theWorker Zonesfield in the output.
The input parameters to create an ALB. For more information, see https://ibm.biz/alb_create_docs
If set to true, the ALB is enabled by default. \
The type of Ingress image that you want to use for your ALB deployment.
The type of ALB that you want to create.
The zone where you want to deploy the ALB.
Response
AlbCreateResp used to send back the albid on a create request
Status Code
The ALB was successfully created.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
Not found. The specified cluster or zone could not be found. To list the clusters that you have access to, run
ibmcloud ks cluster ls. To list the zones available in a cluster, use theGET /v1/clusters/{idOrName}API or runibmcloud ks cluster-get --cluster <cluster_name_or_ID>.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
List the clusters that you have access to.
List the clusters that you have access to.
GET /v1/clusters
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group to list clusters for. To list available resource groups, run
ibmcloud resource groups. If you don't include this header, all the clusters in the account that you have access to are listed.
Query Parameters
Specify a location to filter clusters for. To see supported locations, use the
GET /v1/locationsAPI or runibmcloud ks locations.To view additional cluster resources like addons, VLANs, subnets, and storage, pass
true.
Response
Cluster properties
Addon properties
- addons
VlanConfigField TODO provide meaningful comment
- vlans
SubnetConfigField TODO provide a meaningful comment
VLANS is a helper type to sort an api.VLAN list. The VLANS will sort the list in order of the Properties.PrimaryRouter value so that VLAN's of a common router are listed consecutively.
- worker_vlans
Status Code
Success. A list of clusters that you have access to is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Create a cluster.
Create a cluster in the IBM Cloud account that you are logged into. Note: This API method requires Administrator platform role for IBM Cloud Kubernetes Service at the account level, as well as access to several other services such as the underlying infrastructure provider. For more information, see 'https://ibm.biz/cluster-perms'.
POST /v1/clusters
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use thePOST /v1/credentialsAPI before this request.The ID of the resource group to create the cluster in. To list available resource groups, run
ibmcloud resource groups. If you don't include this header, the cluster is created in the default resource group. After you create a cluster, you cannot change the resource group. Note that if you plan to integrate IBM Cloud services with the cluster, all the resources must be in the same group.
Input parameter to add a cluster. For more information, see https://ibm.biz/cluster_create_docs
The data center where the worker node is created.
The machine type of the worker node.
The private VLAN ID that the worker node is attached to.
The public VLAN ID that the worker node is attached to.
Response
ClusterCreateResponse is returned during a successful create cluster command
ResponseErrors are used to communicate to non-critical errors to end users
Status Code
Created. The cluster was successfully created in the IBM Cloud account that you are logged in to.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Conflict. A cluster with the same name already exists. Choose another name for your cluster.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Delete a cluster.
Delete a cluster from the IBM Cloud account that you are logged in to. When you delete a cluster, all worker nodes, apps, and containers are permanently deleted. This action cannot be undone.
DELETE /v1/clusters/{idOrName}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster that you want to remove. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Query Parameters
To delete additional resources linked to the cluster such as VLANs, subnets, and storage, pass
true.To skip checking for infrastructure permissions before completing this action, pass 'true'. Note that if you do not have the correct infrastructure permissions, this action might only partially succeed.
Response
Status Code
Ok. The cluster was successfully removed from the IBM Cloud account that you are logged in to.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Query Parameters
To view additional cluster resources like addons, VLANs, subnets, and storage, pass
true.
Response
Cluster properties
Addon properties
VlanConfigField TODO provide meaningful comment
VLANS is a helper type to sort an api.VLAN list. The VLANS will sort the list in order of the Properties.PrimaryRouter value so that VLAN's of a common router are listed consecutively.
Status Code
Ok. Detailed information about the cluster is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Update the version of the Kubernetes cluster master node.
Update the Kubernetes master to the default API version. During the update, you cannot access or change the cluster. Worker nodes, apps, and resources that have been deployed by the user are not modified and will continue to run. You might need to change your YAML files for future deployments. For details, see the release notes at https://cloud.ibm.com/docs/containers?topic=containers-cs_versions
PUT /v1/clusters/{idOrName}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Input parameter to update the Kubernetes master. Set action to update to update the master. Set force to true to attempt the update even if the change is greater than two minor versions. Set version to the Kubernetes version of the cluster. If you do not specify a version, the Kubernetes master is updated to the default API version. To see available versions, use the GET /v1/kube-versions API or run ibmcloud ks versions.
The action to perform on the master.
If set to true, any warnings during the update process are ignored.
The Kubernetes version to use for the update.
Response
Status Code
Ok. The request to update your master node was successfully processed.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Conflict. The specified value is already set on the cluster. To list the clusters properties, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View details of the add-ons that are enabled in a cluster.
View details of the add-ons that are enabled in a cluster, including the add-on versions.
GET /v1/clusters/{idOrName}/addonsRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group of the cluster, use the
GET /v1/clusters/{idOrName}API.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
ClusterAddon represents one add on
The addon name such as 'istio'.
The versions that the addon can be upgraded to
The addon default versions based on supported cluster version/provider
- defaultVersions
Determines if this addon version is deprecated
The health state for this addon, a short indication (e.g. critical, pending)
The health status for this addon, provides a description of the state (e.g. error message)
AddonOptionsTemplate represents the options for an addon
- installOptionsTemplate
The minimum kubernetes version for this addon.
The minimum OpenShift version for this addon.
The addon options. Should be a yaml for a kube resource.
The addon supported providers.
The supported kubernetes version range for this addon.
The supported Openshift version range for this addon.
The addon target version.
The addon version, omit the version if you wish to use the default version.
VLAN spanning required for multi-zone clusters
Status Code
OK. Details for the add-ons in this cluster are returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
No Sample Response
Enable, disable, or update add-ons for a cluster.
Enable, disable, or update add-ons for a cluster.
PATCH /v1/clusters/{idOrName}/addonsAuditing
Calling this method generates the following auditing events, depending on any listed conditions.
The event that is generated depends on the operation that you request for the cluster add-on.
containers-kubernetes.cluster-addon.enableA cluster add-on is enabled. Generated if
enableis passed for theaddonRequestparameter.containers-kubernetes.cluster-addon.disableA cluster add-on is disabled. Generated if
disableis passed for theaddonRequestparameter.containers-kubernetes.cluster-addon.updateA cluster add-on is updated. Generated if
updateis passed for theaddonRequestparameter.
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group of the cluster, use the
GET /v1/clusters/{idOrName}API.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Input parameters to enable or disable add-ons in your cluster.
The addons to operate on.
Indicate if the specified addons should be enabled or disabled.
Indicate if the specified addons should be updated. Only Update or Enable should be used, not both.
Response
AddonResponse represents an addon response
The addon enable request would result in an invalid configuration. Install missing addons to continue.
The addon disable request would result in an invalid configuration. Inspect the map to determine why the configuration is invalid.
- orphanedAddons
ClusterAddon represents one add on
Status Code
OK. The add-on changes have been processed.
Bad request. The input parameters in the request body are not correct. Be sure to include all of the required parameters in your request in the correct JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Conflict. The current add-on configuration is not compatible. Check 'MissingDeps' for add-ons to enable in this cluster.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
No Sample Response
Get the cluster-specific configuration and certificates.
Get the cluster-specific Kubernetes configuration data and certificates as a tar file to connect to your cluster and run Kubernetes API calls. To retrieve the administrator certificates and keys, pass admin at the end of the path. For example, /v1/clusters/{idOrName}/config/admin.
GET /v1/clusters/{idOrName}/configAuditing
Calling this method generates the following auditing event.
The Kubernetes configuration file (kubeconfig) for a cluster is requested. Depending on the request, the kubeconfig might contain administrator or network certificates and secrets to access the cluster.
containers-kubernetes.cluster.config
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster for which you want to download the Kubernetes configuration file and certificates. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Query Parameters
The format of the user identity to use in the Kubernetes configuration and policies. Must match the IAM provided user email, up to letter case.
To format the output in a single YAML file, pass
yaml.Retrieve the Calico network config with the Admin config. This only works against the admin endpoint('/config/admin')
Skip adding the RBAC roles based on user's access in IAM.
Response
Status Code
Ok. The cluster-specific configuration file and certificates are returned as a zip file.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Create and enable a key management service (KMS) provider configuration for a cluster.
Create a configuration to enable a key management service (KMS) provider, such as IBM Key Protect, in your cluster. Your customer root key (CRK) from the KMS provider is used to encrypt the Kubernetes secrets within your cluster. After you enable KMS for your cluster, you can update the instance, endpoint, or CRK parameters that are used, but you cannot remove the KMS provider from your cluster. Note on permissions: This API method requires the IBM Cloud IAM Administrator platform role for IBM Cloud Kubernetes Service at the account level. The API key that is used for the region and resource group that the cluster is in requires the appropriate permission to create an instance and CRK in the KMS provider, such as the Editor platform and Writer service role for Key Protect. An additional Reader service-to-service authorization policy between IBM Cloud Kubernetes Service and Key Protect is automatically created for your cluster, if the policy does not already exist. Without this policy, your cluster cannot use all the Key Protect features.
POST /v1/clusters/{idOrName}/kmsRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group of the cluster, use the
GET /v1/clusters/{idOrName}API.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Input parameters to create the Key Protect config for your cluster. The user specified URL parameter is ignored, because it is fetched from Ghost.
CRK is a Key Protect customer root key. To get the CRK, see http://ibm.biz/kp-viewcrk
InstanceID is a Key Protect instance ID. To get the instance ID, run 'ibmcloud resource service-instance <kp_service> --id' and copy the second value (not the full CRN)
URL is a Key Protect endpoint. To get the endpoint, see http://ibm.biz/kp-endpoints
AccountID stores the ID of the account where the key protect instance resides Its value can be either: the same account ID the given cluster resides in (non cross account use case) not the clusters account ID in which the KMS instance resides (cross account use case) empty, in case of old clusters which were secret encrypted before this AccountID field was added to this struct. This case falls back to the first point and should be handled like that (non cross account use case)
The correlation ID stores the correlation ID used to trace a CRK call through multiple services
ServiceToService indicates the KP information in this record was enabled via service-to-service integration, so an associated registration was created.
Response
Status Code
OK. Your Key Protect config will be applied to the cluster.
Bad request. The input parameters in the request body are not correct. Be sure to include all of the required parameters in your request in the correct JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Conflict. Processing multiple concurrent requests from your account to create a Key Protect config for the cluster. Wait a few minutes and try again.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
No Sample Response
Refresh the Kubernetes master.
Restart the Kubernetes master in the cluster to apply changes to the API server configuration.
PUT /v1/clusters/{idOrName}/mastersRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster that you want to interact with. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
The master state. Currently, refresh is supported.
The action to perform on the API Server.
Response
Status Code
Ok. The Master will be put into the desired state.
Bad Request. Check that all headers are present and that the state is valid. Valid states include
refresh.Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
List the IBM Cloud services bound to a cluster across all namespaces.
List the IBM Cloud services that are bound in any Kubernetes namespace in the cluster.
GET /v1/clusters/{idOrName}/servicesRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster where you want to list bound IBM Cloud services. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
BoundService properties
Status Code
Ok. A list of IBM Cloud services bound to a cluster across all Kubernetes namespaces is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster ID or name could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Bind an IBM Cloud service to a cluster.
Bind an IBM Cloud service instance to a Kubernetes namespace in your cluster. To view available IBM Cloud services from the IBM Cloud catalog, run ibmcloud catalog search --kind service. If you already provisioned IBM Cloud service instances in an IBM Cloud space, you can list them by running ibmcloud resource service-instances.
Note: You can add only IBM Cloud services that support service keys, and you must add the service in the same resource group that the cluster is in.
POST /v1/clusters/{idOrName}/servicesRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster where you want to bind your service. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
The ID of the IBM Cloud service instance that you want to bind. To find the ID of the service instance, use the GET /v1/clusters/{idOrName}/services API or run {[bxcs]} cluster-services <cluster_name_or_ID>.
Response
ServiceBindResponse is the response format for a service bind request
Status Code
Created. Your IBM Cloud service instance was successfully bound to the Kubernetes namespace of your cluster.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
List the IBM Cloud services bound to a specific namespace in a cluster.
List the IBM Cloud services that are bound to a specific Kubernetes namespace in a cluster.
GET /v1/clusters/{idOrName}/services/{namespace}Request
Custom Headers
Your IAM IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster where you want to list bound IBM Cloud services. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The Kubernetes namespace in your cluster where you want to list all bound IBM Cloud services.
Response
BoundService properties
Status Code
Ok. A list of services bound to a cluster within a specific Kubernetes namespace is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified Kubernetes namespace or cluster ID/name could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls. To view available Kubernetes namespaces, runkubectl get namespaces.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Unbind an IBM Cloud service from a cluster.
Unbind an IBM Cloud service instance from a Kubernetes namespace in your cluster. Note: When you remove an IBM Cloud service, the service credentials are removed from the cluster. If a pod is still using the service, it fails because the service credentials cannot be found.
DELETE /v1/clusters/{idOrName}/services/{namespace}/{serviceInstanceId}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster where you want to unbind your IBM Cloud service instance. To list bound IBM Cloud services and their namespaces, use the
GET /v1/clusters/{nameOrId}/servicesAPI or runibmcloud ks cluster service ls --cluster <cluster_name_or_ID>.The Kubernetes namespace where your IBM Cloud service was bound to. To list bound IBM Cloud services and their namespaces, use the
GET /v1/clusters/{nameOrId}/servicesAPI or runibmcloud ks cluster service ls --cluster <cluster_name_or_ID>.The name or ID of the IBM Cloud service instance that was bound to your cluster. To list bound IBM Cloud services and their namespaces, use the
GET /v1/clusters/{nameOrId}/servicesAPI or runibmcloud ks cluster service ls --cluster <cluster_name_or_ID>.
Response
Status Code
The IBM Cloud service instance was successfully unbound from the Kubernetes namespace of your cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster, IBM Cloud service instance, or namespace could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls. To list bound IBM Cloud services and their namespaces, use theGET /v1/clusters/{nameOrId}/servicesAPI or runibmcloud ks cluster service ls --cluster <cluster_name_or_ID>.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
List classic subnets that are bound to a cluster.
List subnets from your IBM Cloud classic infrastructure account that are bound to a cluster. Before you can call this API method, a one-time per account POST /v1/credentials is required.
GET /v1/clusters/{idOrName}/subnetsRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
VlanConfigField TODO provide meaningful comment
SubnetConfigField TODO provide a meaningful comment
Status Code
Ok. A list of user-managed subnets that are bound to your cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Detach a public or private portable subnet from a cluster.
Detach a subnet in your IBM Cloud classic infrastructure account from a cluster. The subnet remains available in your infrastructure account after it is detached.
PATCH /v1/clusters/{idOrName}/subnets/{subnetId}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster that you want to remove the subnet from. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The ID of the subnet that you want to remove from your cluster.
Response
Status Code
Ok. The specified subnet was successfully removed from your cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Add an IBM Cloud classic infrastructure subnet to a cluster.
Make an existing IBM Cloud classic infrastructure subnet available to an existing cluster. Note: When you make a subnet available to a cluster, IP addresses of this subnet are used for cluster networking purposes. To avoid IP address conflicts, make sure that you use a subnet with one cluster only. Do not use a subnet for multiple clusters or for other purposes outside of Kubernetes Service at the same time.
PUT /v1/clusters/{idOrName}/subnets/{subnetId}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use thePOST /v1/credentialsAPI before this request.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster that you want to make an existing subnet available to. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The ID of the subnet in your IBM Cloud infrastructure account that you want to add to your cluster. To list available subnets, run
ibmcloud ks subnets.
Response
Status Code
Ok. The specified subnet was successfully made available to your cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
List user-managed subnets that are bound to a cluster.
List user-managed subnets that are bound to a cluster. Note that user-managed subnets are deprecated.
GET /v1/clusters/{idOrName}/usersubnetsRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
VlanConfigField TODO provide meaningful comment
SubnetConfigField TODO provide a meaningful comment
Status Code
Ok. A list of user-managed subnets that are bound to your cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Add an existing user-managed subnet to a cluster.
Make your own private subnet available to an Kubernetes Service cluster. This private subnet is not one provided by IBM Cloud infrastructure (SoftLayer). As such, you must configure any inbound and outbound network traffic routing for the subnet. Note: User-managed subnets are deprecated. When you add a private user subnet to a cluster, IP addresses of this subnet are used for private Load Balancers in the cluster. To avoid IP address conflicts, make sure that you use a subnet with one cluster only. Do not use a subnet for multiple clusters or for other purposes outside of Kubernetes Service at the same time.
POST /v1/clusters/{idOrName}/usersubnetsRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use thePOST /v1/credentialsAPI before this request.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster that you want to make your user-managed subnet available to. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Pass the CIDR of your user-managed subnet and the ID of an available private VLAN in the body.
The subnet and the CIDR that you want to add to the cluster in the format 12.34.45.78/24.
The private VLAN ID that the subnet CIDR belongs to.
Response
Status Code
Ok. The specified subnet was successfully made available to your cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Remove a user-managed subnet from a cluster.
Remove a private user-managed subnet from a cluster. Note: User-managed subnets are deprecated. Any service that was deployed to an IP address from your own private subnet remains active after the subnet is removed.
DELETE /v1/clusters/{idOrName}/usersubnets/{subnetId}/vlans/{vlanId}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster that you want to remove the user-managed subnet from. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The GUID of the user-managed subnet that you want to remove from your cluster.
The ID of the private VLAN that the user-managed subnet is on.
Response
Status Code
Ok. The specified subnet was successfully removed from your cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Create an IBM Cloud classic infrastructure subnet and add it to an existing cluster.
Create an IBM Cloud classic infrastructure subnet and make it available to an existing cluster. Note: When you make a subnet available to a cluster, IP addresses of this subnet are used for cluster networking purposes. To avoid IP address conflicts, make sure that you use a subnet with one cluster only. Do not use a subnet for multiple clusters or for other purposes outside of Kubernetes Service at the same time.
POST /v1/clusters/{idOrName}/vlans/{vlanId}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use thePOST /v1/credentialsAPI before this request.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster for which you want to make an existing subnet from your IBM Cloud infrastructure account available. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The VLAN in which to create the subnet. To list available VLANs, use the
GET /v1/datacenters/{datacenter}/vlansAPI or runibmcloud ks vlan ls <zone>.
Query Parameters
The number of subnet IP addresses. The default value is 8. Accepted values are 8, 16, 32, 64.
Response
Status Code
Ok. The specified subnet was successfully made available to your cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
List all webhooks for a cluster.
List all webhooks for a Kubernetes cluster.
GET /v1/clusters/{idOrName}/webhooksRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster for which you want to list available webhooks. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
ClusterWebhook webhook info
The notification level that you want to use for the webhook.
The webhook service type.
The webhook URL.
Status Code
Ok. A list of available webhooks for the cluster is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Add a webhook to a cluster.
Add a webhook, such as for Slack, to a Kubernetes cluster.
POST /v1/clusters/{idOrName}/webhooksRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster that you want to add a webhook to. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Input parameter to create a webhook. Set level to the notification level, such as Normal or Warning. The default value is Warning. Set type to the webhook service type. Currently slack is supported. Set url to the URL for the webhook.
The notification level that you want to use for the webhook.
The webhook service type.
The webhook URL.
Response
Status Code
Created. The webhook was successfully added to the cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
List the worker pools in a cluster.
List all the worker pools that you have in a cluster.
GET /v1/clusters/{idOrName}/workerpoolsRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
WorkerPoolResponse provides worker pool data
- labels
WorkerPoolZoneResponse response contents for zone
Status Code
OK. The list of worker pools was successfully retrieved.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list all the clusters, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
No Sample Response
Create a worker pool for a cluster.
Create a worker pool for the specified cluster. Creating a worker pool requires Operator access to Kubernetes Service in the IBM Cloud account.
POST /v1/clusters/{idOrName}/workerpoolsRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use thePOST /v1/credentialsAPI before this request.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
The
If set to true, the secondary disk of the worker node is encrypted. If set to false, no encryption is set up.
- labels
WorkerPoolZone provides zone data
Response
WorkerPoolResponse provides worker pool data
- labels
WorkerPoolZoneResponse response contents for zone
Status Code
Created. The worker pool was successfully created in for the specified cluster.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Conflict. A worker pool create may already be in progress for the provided cluster. Please wait a few minutes and try again.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Remove a worker pool from a cluster.
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.
DELETE /v1/clusters/{idOrName}/workerpools/{poolidOrName}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The ID of the worker pool. To list all worker pools for a cluster, use the
GET /v1/clusters/{idOrName}/workerpoolsAPI or runibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.
Response
Status Code
OK. The request to remove your worker pool was successfully received.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the
GET /v1/clusters/{idOrName}/workerpoolsAPI or runibmcloud ks worker-pool ls mycluster.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
No Sample Response
View details for a worker pool.
View detailed information for a worker pool.
GET /v1/clusters/{idOrName}/workerpools/{poolidOrName}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The ID of the worker pool. To list all worker pools for a cluster, use the
GET /v1/clusters/{idOrName}/workerpoolsAPI or runibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.
Response
WorkerPoolResponse provides worker pool data
- labels
WorkerPoolZoneResponse response contents for zone
Status Code
Ok. Detailed information about the worker pool is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the
GET /v1/clusters/{idOrName}/workerpoolsAPI or runibmcloud ks worker-pool ls mycluster.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
No Sample Response
Resize or rebalance a worker pool.
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.
PATCH /v1/clusters/{idOrName}/workerpools/{poolidOrName}Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
The event that is generated depends on the operation that you request for the worker pool.
containers-kubernetes.cluster-worker-pool.rebalanceA worker pool is rebalanced.
containers-kubernetes.cluster-worker-pool.resizeA worker pool is resized, to add or decrease the number of worker nodes in the pool.
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The ID of the worker pool. To list all worker pools for a cluster, use the
GET /v1/clusters/{idOrName}/workerpoolsAPI or runibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.
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.
- labels
Response
Status Code
OK. The request to resize your worker pool was successfully processed.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The request will not be permitted.
Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the
GET /v1/clusters/{idOrName}/workerpoolsAPI or runibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
No Sample Response
Add a zone to the specified worker pool for a cluster.
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.
POST /v1/clusters/{idOrName}/workerpools/{poolidOrName}/zonesRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The ID of the worker pool. To list all worker pools for a cluster, use the
GET /v1/clusters/{idOrName}/workerpoolsAPI or runibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.
Input parameters to add zones to the worker pool.
Response
Status Code
OK. The requested zone has been added to the worker pool.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the
GET /v1/clusters/{idOrName}/workerpoolsAPI or runibmcloud ks worker-pool ls mycluster.Conflict. The provided zone already exists in the worker pool.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
No Sample Response
Remove a zone from a worker pool.
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.
DELETE /v1/clusters/{idOrName}/workerpools/{poolidOrName}/zones/{zoneid}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The ID of the worker pool. To list all worker pools for a cluster, use the
GET /v1/clusters/{idOrName}/workerpoolsAPI or runibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.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/zonesAPI or runibmcloud ks zone ls.
Response
Status Code
OK. The request to remove the zone from your worker pool was successfully submitted.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The request will not be permitted.
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}/zonesAPI or runibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
No Sample Response
Update the network configuration details, such as VLANs, for a zone in the worker pool.
PATCH /v1/clusters/{idOrName}/workerpools/{poolidOrName}/zones/{zoneid}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The ID of the worker pool. To list all worker pools for a cluster, use the
GET /v1/clusters/{idOrName}/workerpoolsAPI or runibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.The ID of the worker pool zone. To list all worker pools for a cluster, use the
GET /v1/zonesAPI or runibmcloud ks zone ls.
Updated network configuration values for the worker pool zone.
Response
Status Code
OK. The request to update network configuration for your worker pool was successful.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The request will not be permitted.
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}/zonesAPI or runibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
No Sample Response
List all worker nodes in a cluster.
List all worker nodes and the status of each in a cluster.
GET /v1/clusters/{idOrName}/workersRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
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/clustersAPI or runibmcloud ks cluster ls.
Query Parameters
The name or ID of the worker pool to filter results for. Run
ibmcloud ks worker-pool ls --cluster <cluster name>.true|false Shows deleted workers
Response
Worker properties
Status Code
Ok. A list of worker nodes for the specified cluster is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Add worker nodes to a cluster.
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.
POST /v1/clusters/{idOrName}/workersRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use thePOST /v1/credentialsAPI before this request.
Path Parameters
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/clustersAPI or runibmcloud ks cluster ls.
Input parameter to add workers to a cluster. For more information, see https://ibm.biz/worker_add_docs
The data center where the worker node is created.
The machine type of the worker node.
The private VLAN ID that the worker node is attached to.
The public VLAN ID that the worker node is attached to.
Response
Status Code
Ok. Additional worker nodes were successfully added to your cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Delete a worker node from a cluster.
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.
DELETE /v1/clusters/{idOrName}/workers/{workerId}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
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/clustersAPI or runibmcloud ks cluster ls.The ID of the worker node. To list all worker nodes for a cluster, use the
GET /v1/clusters/{idOrName}/workersAPI or runibmcloud ks worker ls --cluster <cluster_name_or_ID>.
Response
Status Code
Ok. The worker node was successfully removed from your cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View details of a worker node.
View detailed information for a worker node.
GET /v1/clusters/{idOrName}/workers/{workerId}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
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/clustersAPI or runibmcloud ks cluster ls.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}/workersAPI or runibmcloud ks worker ls --cluster <cluster_name_or_ID>.
Response
Worker properties
Status Code
Ok. Detailed information about the worker node is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Reboot, reload, or update a worker node for a cluster.
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.
PUT /v1/clusters/{idOrName}/workers/{workerId}Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
The event that is generated depends on the operation that you request for the worker node.
containers-kubernetes.worker.rebootA worker node is rebooted. A reboot clears temporary directories, but does not clear the entire file system or reformat the disks. Generated if
os_rebootis passed for theapiCommandparameter.containers-kubernetes.worker.reloadA worker node is reloaded. The worker node is updated with the latest image and patch version. Any data stored locally on the worker node is deleted. Generated if
reloadis passed for theapiCommandparameter.containers-kubernetes.worker.rebootA worker node version is update, such as a minor version update to match the cluster master version. Generated if
updateis passed for theapiCommandparameter.
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The ID of the worker node. To list all worker nodes for a cluster, use the
GET /v1/clusters/{idOrName}/workersAPI or runibmcloud ks worker ls --cluster <cluster_name_or_ID>.
The action that you want your worker node to take. Pass os_reboot, reload, or update as the action string.
The action to perform on the worker node.
Setting force flag to true will ignore if the master is unavailable during 'os_reboot" and 'reload' action
Response
Status Code
OK. The request to reboot or reload your worker node was successfully processed.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
No Sample Response
Delete an audit webhook configuration.
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.
DELETE /v1/clusters/{idOrName}/apiserverconfigs/auditwebhookRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
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/clustersAPI or runibmcloud ks cluster ls.
Response
Status Code
Successfully deleted the audit webhook configuration.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View details for an audit webhook configuration.
View the URL for the remote logging service that you are sending API server audit logs to.
GET /v1/clusters/{idOrName}/apiserverconfigs/auditwebhookRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
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/clustersAPI or runibmcloud ks cluster ls.
Response
The URL of the server to send audit logs to.
The Certificate Authority certificate that is used to connect to the audit server.
The client certificate that is used to connect to the audit server.
The client key that is used to connect to the audit server.
The audit policy type to be configured.
Status Code
Successfully retrieved the audit webhook configuration.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Create or update an audit webhook configuration for a cluster.
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.
PUT /v1/clusters/{idOrName}/apiserverconfigs/auditwebhookRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Path Parameters
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/clustersAPI or runibmcloud ks cluster ls.
The input parameter for creating or updating an audit webhook configuration. For more information, see https://ibm.biz/audit_config_docs
The URL of the server to send audit logs to.
The Certificate Authority certificate that is used to connect to the audit server.
The client certificate that is used to connect to the audit server.
The client key that is used to connect to the audit server.
The audit policy type to be configured.
Response
Status Code
Ok. The cluster will send audit logs to the audit server.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.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.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Remove IBM Cloud classic infrastructure account credentials from your IBM Cloud Kubernetes Service account.
Remove the IBM Cloud classic infrastructure user name, API key, and refresh token 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.
DELETE /v1/credentials
Request
Custom Headers
Target the IBM Cloud Kubernetes Service region where you want to remove infrastructure credentials. To list available regions, use the
GET /v1/regionsAPI or runibmcloud ks region ls.Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Response
Status Code
Ok. The IBM Cloud infrastructure account credentials were successfully removed from your IBM Cloud Kubernetes Service account for this region and resource group.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. No IBM Cloud infrastructure account credentials are stored in the Kubernetes Service account for this region and resource group.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View the IBM Cloud classic infrastructure account credentials that are set for your IBM Cloud Kubernetes Service account.
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.
GET /v1/credentials
Request
Custom Headers
Target the IBM Cloud Kubernetes Service region where you want to get infrastructure credential details. To list available regions, use the
GET /v1/regionsAPI or runibmcloud ks region ls.Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Response
Credentials provides information about user infrastructure credentials
Status Code
Ok. The IBM Cloud infrastructure (SoftLayer) account credentials were successfully retrieved from IBM Cloud Kubernetes Service.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. No IBM Cloud infrastructure account credentials are stored in the Kubernetes Service account for this region and resource group.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Set IBM Cloud classic infrastructure account credentials for your IBM Cloud Kubernetes Service account.
Set the IBM Cloud classic infrastructure user name, API key, and refresh token 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.
POST /v1/credentials
Request
Custom Headers
Target the IBM Cloud Kubernetes Service region where you want to set infrastructure credentials. To list available regions, use the
GET /v1/regionsAPI or runibmcloud ks region ls.Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use thePOST /v1/credentialsAPI before this request.The user name of the IBM Cloud classic infrastructure account that you want to use with Kubernetes Service. To retrieve your user name, log in to the IBM Cloud account that you want to use, click Manage > Access (IAM) > Users > your user profile. Then, from the User Details tab, go to the VPN password section. The user name is in a format similar to 1234567_name@email.com.
The classic infrastructure API key of the IBM Cloud account that you want to use with Kubernetes Service. To retrieve your API key, log in to the IBM Cloud account that you want to use, click Manage > Access (IAM) > API keys. Filter the view for Classic infrastructure API keys. In the row for the API key, click the action menu > Details. In the API key details pane, click the eye icon to view the API key value.
Response
Status Code
Ok. The IBM Cloud infrastructure account credentials were successfully set for this region and resource group.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Get details on the permissions that the IBM Cloud infrastructure (SoftLayer) credentials have.
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.
GET /v1/infra-permissions
Request
Custom Headers
Target the IBM Cloud Kubernetes Service region where you want to check the infrastructure permissions. To list available regions, use the
GET /v1/regionsAPI or runibmcloud ks region ls.Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group. To list available resource group IDs, run
ibmcloud resource groups.
Response
AccountStatus summarises the IaaS user's view of the provider account
ProviderAccountID may contain personally identifiable information
AccountType returns if the account information pertains to a linked or an IaaS account
Permissions describes the result of checking granted permissions Note: the default zero/empty value implies sufficient permissions
Permissions describes the result of checking granted permissions Note: the default zero/empty value implies sufficient permissions
Permissions describes the result of checking granted permissions Note: the default zero/empty value implies sufficient permissions
Permissions describes the result of checking granted permissions Note: the default zero/empty value implies sufficient permissions
Status Code
Ok.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Reset the IAM API key.
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.
POST /v1/keys
Request
Custom Headers
Target the IBM Cloud Kubernetes Service region where you want to reset the IAM API key. To list available regions, use the
GET /v1/regionsAPI or runibmcloud ks region ls.Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group where you want to set the API key.
Response
Status Code
Ok. The IAM API key is successfully reset.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View the VLAN spanning status.
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.
GET /v1/subnets/vlan-spanning
Request
Custom Headers
Target the IBM Cloud Kubernetes Service region where you want to check the VLAN spanning status. To list available regions, use the
GET /v1/regionsAPI or runibmcloud ks region ls.Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group. To list available resource group IDs, run
ibmcloud resource groups.
Response
Status Code
Ok. Details of VLAN spanning enablement.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Unable to determine whether VLAN spanning is enabled in the IBM Cloud infrastructure account.
No Sample Response
List available VLANs for a zone.
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>.
GET /v1/datacenters/{datacenter}/vlansRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use thePOST /v1/credentialsAPI before this request.
Path Parameters
The ID of the zone where you want to list available public and private VLANs. To list available zones, run
ibmcloud ks zone lsor use theGET /v1/datacentersAPI.
Response
Status Code
Ok. A list of available public and private VLANs for the specified zone is returned.
The specified zone is invalid. To list available zones, run
ibmcloud ks zone ls' or use theGET /v1/datacenters` API.Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
List available IBM Cloud classic infrastructure 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>.
GET /v1/subnets
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use thePOST /v1/credentialsAPI before this request.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Query Parameters
A comma seperated list of datacenters to filter subnets based off of.
Response
Subnet provides information about a vpc subnet
Status Code
Ok.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View information about the containers-kubernetes-key API key owner.
View the name and email address for the owner of the cluster's containers-kubernetes-key API key.
GET /v1/logging/{idOrName}/clusterkeyownerRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster get --cluster <cluster_name_or_ID>.
Path Parameters
The name or ID of the target cluster. To list the clusters that you have access to, run
ibmcloud ks cluster ls.
Response
ClusterKeyOwnerInfo stores the token owner's information
Status Code
Ok. The cluster API key ID and the owner's name and email address.
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run
ibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To see a list of your clusters, run
ibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
View the default logging endpoint for the target region.
View the default logging endpoint for the target region.
GET /v1/logging/{idOrName}/defaultRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster get --cluster <cluster_name_or_ID>.
Path Parameters
The name or ID of the target cluster. To list the clusters that you have access to, run
ibmcloud ks cluster ls.
Response
DefaultLoggingEndpointResponse is the ibm logging service endpoint where logs will be sent by default clusters in the target region
The IBM Cloud Log Analysis with LogDNA API endpoint that the hostname uses.
The hostname for the ibm logging service.
The port for the ibm logging service.
Status Code
Ok. The default logging endpoint for the target region.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Delete all log forwarding configurations for a cluster.
Stops all log forwarding for a cluster by deleting all log forwarding configurations.
DELETE /v1/logging/{idOrName}/loggingconfigRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster get --cluster <cluster_name_or_ID>.
Path Parameters
The name or ID of the target cluster. To list the clusters that you have access to, run
ibmcloud ks cluster ls.
Query Parameters
Forces the request which may cause a new fluentd version to be deployed to the cluster.
Response
Status Code
Ok. All log forwarding configurations have been removed.
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run
ibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To see a list of your clusters, run
ibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
List all log forwarding configurations in the cluster.
List the log forwarding configurations in the target cluster.
GET /v1/logging/{idOrName}/loggingconfigRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster get --cluster <cluster_name_or_ID>.
Path Parameters
The name or ID of the target cluster. To list the clusters that you have access to, run
ibmcloud ks cluster ls.
Response
LogConfigResponse is how users will see their logging configs from API responses
A list of container names that you want to collect logs for.
A list of app paths that you want to collect logs for.
The name of the Kubernetes secret that holds the Certificate Authority certificate that you want to use for the syslog TLS termination.
The IBM Cloud Log Analysis with LogDNA API endpoint that the logging configuration uses.
A list of errors that occurred during the last logging config update.
The unique identifier of the log source.
The type of logs that you want to read and forward to the logging server. Supported values are
container,kubernetes,ingress,worker, andapplication.A list of container names that logs are collected for and forwarded to the logging server.
A list of app paths that logs are collected for and forwarded to the logging server.
The logging protocol to use. Supported values are
syslogandibm.The Kubernetes namespace where the logging type is applied. This parameter is set only when the
containerlog source is used.The name of the Cloud Foundry organization where the logging configuration was created.
The GUID of the Cloud Foundry organization where the logging configuration was created.
The protocol that you want to use for syslog forwarding. Supported values are
TCPandUDP. If no value is provided, the protocol is set toUDPby default.The port of the logging server.
The hostname or IP address of the logging server.
The name of the Cloud Foundry space where the logging configuration was created.
The GUID of the Cloud Foundry space where the logging configuration was created.
The verification mode that is used for the syslog TLS protocol.
Internal use only.
Status Code
Ok. A list of logging configurations in the Kubernetes cluster.
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run
ibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To see a list of your clusters, run
ibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
List all log forwarding configurations for a log source in the cluster.
List the log forwarding configurations for the specified log source in the target cluster.
GET /v1/logging/{idOrName}/loggingconfig/{logSource}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster get --cluster <cluster_name_or_ID>.
Path Parameters
The name or ID of the target cluster. To list the clusters that you have access to, run
ibmcloud ks cluster ls.The type of log source that you want to list configurations for.
Response
LogConfigResponse is how users will see their logging configs from API responses
A list of container names that you want to collect logs for.
A list of app paths that you want to collect logs for.
The name of the Kubernetes secret that holds the Certificate Authority certificate that you want to use for the syslog TLS termination.
The IBM Cloud Log Analysis with LogDNA API endpoint that the logging configuration uses.
A list of errors that occurred during the last logging config update.
The unique identifier of the log source.
The type of logs that you want to read and forward to the logging server. Supported values are
container,kubernetes,ingress,worker, andapplication.A list of container names that logs are collected for and forwarded to the logging server.
A list of app paths that logs are collected for and forwarded to the logging server.
The logging protocol to use. Supported values are
syslogandibm.The Kubernetes namespace where the logging type is applied. This parameter is set only when the
containerlog source is used.The name of the Cloud Foundry organization where the logging configuration was created.
The GUID of the Cloud Foundry organization where the logging configuration was created.
The protocol that you want to use for syslog forwarding. Supported values are
TCPandUDP. If no value is provided, the protocol is set toUDPby default.The port of the logging server.
The hostname or IP address of the logging server.
The name of the Cloud Foundry space where the logging configuration was created.
The GUID of the Cloud Foundry space where the logging configuration was created.
The verification mode that is used for the syslog TLS protocol.
Internal use only.
Status Code
Ok. A list of logging configurations for the specified log source in the cluster.
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run
ibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To see a list of your clusters, run
ibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Create a log forwarding configuration.
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.
POST /v1/logging/{idOrName}/loggingconfig/{logSource}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster get --cluster <cluster_name_or_ID>.
Path Parameters
The name or ID of the target cluster. To list the clusters that you have access to, run
ibmcloud ks cluster ls.The log source from which you want to forward logs. Accepted values are
container,worker,kubernetes,ingress, andapplication. If you do not provide a namespace for log sourcecontainer, then all namespaces use this configuration.
Query Parameters
Forces the request which may cause a new fluentd version to be deployed to the cluster.
Set to
trueto 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.
The type of log collector server for the logging configuration. Supported logging types are 'syslog' and 'ibm'.
A list of container names that you want to collect logs for.
A list of app paths that you want to collect logs for.
The name of the Kubernetes secret that holds the Certificate Authority certificate that you want to use for the syslog TLS termination.
The logging type that you want to use. Supported values are
syslogandibm.The Kubernetes namespace where the logging configuration is applied.
The name of the Cloud Foundry organization where the logging configuration is created.
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.
The port that the logging server uses. This value is required only when
LoggingTypeis set tosyslog.The hostname or IP address of the logging server. This values is required only if
LoggingTypeis set tosyslog.The name of the Cloud Foundry space where the logging configuration is created.
The verification mode that you want to use for the syslog TLS protocol. By default,
verify-noneis used. Other supported values includeverify-peer,verify-client-once, andverify-if-no-peer-cert.
Response
LogConfigResponse is how users will see their logging configs from API responses
A list of container names that you want to collect logs for.
A list of app paths that you want to collect logs for.
The name of the Kubernetes secret that holds the Certificate Authority certificate that you want to use for the syslog TLS termination.
The IBM Cloud Log Analysis with LogDNA API endpoint that the logging configuration uses.
A list of errors that occurred during the last logging config update.
The unique identifier of the log source.
The type of logs that you want to read and forward to the logging server. Supported values are
container,kubernetes,ingress,worker, andapplication.A list of container names that logs are collected for and forwarded to the logging server.
A list of app paths that logs are collected for and forwarded to the logging server.
The logging protocol to use. Supported values are
syslogandibm.The Kubernetes namespace where the logging type is applied. This parameter is set only when the
containerlog source is used.The name of the Cloud Foundry organization where the logging configuration was created.
The GUID of the Cloud Foundry organization where the logging configuration was created.
The protocol that you want to use for syslog forwarding. Supported values are
TCPandUDP. If no value is provided, the protocol is set toUDPby default.The port of the logging server.
The hostname or IP address of the logging server.
The name of the Cloud Foundry space where the logging configuration was created.
The GUID of the Cloud Foundry space where the logging configuration was created.
The verification mode that is used for the syslog TLS protocol.
Internal use only.
Status Code
Ok. Logs from the specified log source will be forwarded to the log server.
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.
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run
ibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To see a list of your clusters, run
ibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Delete a log forwarding configuration.
Stops log forwarding by deleting a specified logging configuration.
DELETE /v1/logging/{idOrName}/loggingconfig/{logSource}/{id}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster get --cluster <cluster_name_or_ID>.
Path Parameters
The name or ID of the target cluster. To list the clusters that you have access to, run
ibmcloud ks cluster ls.The log source that you want to stop forwarding logs for.
The UUID of the logging configuration that you want to delete.
Query Parameters
Forces the request which may cause a new fluentd version to be deployed to the cluster.
Response
Status Code
Ok. Logs will no longer be forwarded to the log server for the specified logging configuration.
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run
ibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To see a list of your clusters, run
ibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Update a log forwarding configuration.
Update the details of a log forwarding configuration.
PUT /v1/logging/{idOrName}/loggingconfig/{logSource}/{id}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster get --cluster <cluster_name_or_ID>.
Path Parameters
The name or ID of the target cluster. To list the clusters that you have access to, run
ibmcloud ks cluster ls.The log source from which you want to forward logs. Supported values are
container,worker,kubernetes,ingress, andapplication. If you do not provide a namespace for log sourcecontainer, then all namespaces use this configuration.The UUID of the logging configuration that you want to update.
Query Parameters
Forces the request which may cause a new fluentd version to be deployed to the cluster.
Set to
trueto 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.
The new type of log collector server for the logging configuration. Supported logging types are 'syslog'.
A list of container names that you want to collect logs for.
A list of app paths that you want to collect logs for.
The name of the Kubernetes secret that holds the Certificate Authority certificate that you want to use for the syslog TLS termination.
The logging type that you want to use. Supported values are
syslogandibm.The Kubernetes namespace where the logging configuration is applied.
The name of the Cloud Foundry organization where the logging configuration is created.
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.
The port that the logging server uses. This value is required only when
LoggingTypeis set tosyslog.The hostname or IP address of the logging server. This values is required only if
LoggingTypeis set tosyslog.The name of the Cloud Foundry space where the logging configuration is created.
The verification mode that you want to use for the syslog TLS protocol. By default,
verify-noneis used. Other supported values includeverify-peer,verify-client-once, andverify-if-no-peer-cert.
Response
LogConfigResponse is how users will see their logging configs from API responses
A list of container names that you want to collect logs for.
A list of app paths that you want to collect logs for.
The name of the Kubernetes secret that holds the Certificate Authority certificate that you want to use for the syslog TLS termination.
The IBM Cloud Log Analysis with LogDNA API endpoint that the logging configuration uses.
A list of errors that occurred during the last logging config update.
The unique identifier of the log source.
The type of logs that you want to read and forward to the logging server. Supported values are
container,kubernetes,ingress,worker, andapplication.A list of container names that logs are collected for and forwarded to the logging server.
A list of app paths that logs are collected for and forwarded to the logging server.
The logging protocol to use. Supported values are
syslogandibm.The Kubernetes namespace where the logging type is applied. This parameter is set only when the
containerlog source is used.The name of the Cloud Foundry organization where the logging configuration was created.
The GUID of the Cloud Foundry organization where the logging configuration was created.
The protocol that you want to use for syslog forwarding. Supported values are
TCPandUDP. If no value is provided, the protocol is set toUDPby default.The port of the logging server.
The hostname or IP address of the logging server.
The name of the Cloud Foundry space where the logging configuration was created.
The GUID of the Cloud Foundry space where the logging configuration was created.
The verification mode that is used for the syslog TLS protocol.
Internal use only.
Status Code
Ok. The configuration was updated.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format. Supported logging types are 'syslog'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run
ibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To see a list of your clusters, run
ibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Refresh the cluster's logging configuration.
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.
PUT /v1/logging/{idOrName}/refreshRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster get --cluster <cluster_name_or_ID>.
Path Parameters
The name or ID of the target cluster. To list the clusters that you have access to, run
ibmcloud ks cluster ls.
Query Parameters
Forces the request which may cause a new fluentd version to be deployed to the cluster.
Response
Status Code
Ok. A request was sent for the cluster's logging configuration to be refreshed.
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run
ibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To see a list of your clusters, run
ibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Check if automatic updates for the Fluentd logging add-on are enabled in the cluster.
Check if automatic updates for the Fluentd logging add-on are enabled and whether your Fluentd pods are updated to the latest version.
GET /v1/logging/{idOrName}/updatepolicyRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster get --cluster <cluster_name_or_ID>.
Path Parameters
The name or ID of the target cluster. To list the clusters that you have access to, run
ibmcloud ks cluster ls.
Response
If set to
true, the cluster is enabled for automatic updates.If set to
true, the cluster log forwarder runs the latest version.
Status Code
Ok. The current update policy.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format. Supported logging types are 'syslog' and 'ibm'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run
ibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To see a list of your clusters, run
ibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Enable or diable automatic updates for the Fluentd logging add-on in the cluster.
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.
PUT /v1/logging/{idOrName}/updatepolicyRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster get --cluster <cluster_name_or_ID>.
Path Parameters
The name or ID of the target cluster. To list the clusters that you have access to, run
ibmcloud ks cluster ls.
The new update policy configuration
If set to
true, the cluster is enabled for automatic updates.If set to
true, the cluster log forwarder runs the latest version.
Response
Status Code
Ok. The logging update policy has been changed.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format. Supported logging types are 'syslog' and 'ibm'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run
ibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To see a list of your clusters, run
ibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Deletes all logging filter configurations for the cluster.
Stops log filtering.
DELETE /v1/logging/{idOrName}/filterconfigsRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster get --cluster <cluster_name_or_ID>.
Path Parameters
The name or ID of the target cluster. To list the clusters that you have access to, run
ibmcloud ks cluster ls.
Query Parameters
Forces the request which may cause a new fluentd version to be deployed to the cluster.
Response
Status Code
Ok. All log filtering configurations have been removed.
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run
ibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To see a list of your clusters, run
ibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
List all logging filter configurations in the cluster.
List the logging filter configurations that you created in a cluster.
GET /v1/logging/{idOrName}/filterconfigsRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokensThe unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster get --cluster <cluster_name_or_ID>.
Path Parameters
The name or ID of the target cluster. To list the clusters that you have access to, run
ibmcloud ks cluster ls.
Query Parameters
Set to true to populate global filters with all matching logging configurations.
Response
FilterConfigResponse is how users will see their logging filter configs from API responses
The name of the container that you want to exclude from your logs.
A list of logging filter IDs that the filter covers.
The unique identifier of the logging configuration.
The pod label that you want to exclude from your logs.
The log level that you want to apply to your logs. Supported values are
debugorinfo.A list of logging configuration IDs where you want to apply the log filter.
A string in a log message that you want to exclude from your logs.
The Kubernetes namespace that you want to exclude from your logs.
Set this value to
trueif you want to interpret the message field as a regular expression.The type of filter that you want to apply to your logs. Supported values are
containerandnon-container.Internal use only.
Status Code
Ok. A list of logging filters in the cluster.
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run
ibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To see a list of your clusters, run
ibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Create a logging filter configuration.
Start filtering logs that are forwarded by your logging configuration from the given sources based on one or more selectors.
POST /v1/logging/{idOrName}/filterconfigsRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster get --cluster <cluster_name_or_ID>.
Path Parameters
The name or ID of the target cluster. To list the clusters that you have access to, run
ibmcloud ks cluster ls.
Query Parameters
Forces the request which may cause a new fluentd version to be deployed to the cluster.
The new logging filter configuration.
The name of the container where you want to apply the logging filter.
The log level that you want to apply to your logging filter.
A list of logging configuration IDs where you want to apply the logging filter.
A string in a message to which you want to apply the logging filter.
The Kubernetes namespace where you want to apply the logging filter.
Set this value to
trueif you want the message field to be interpreted as a regular expression.The type of the logging filter.
Response
FilterConfigResponse is how users will see their logging filter configs from API responses
The name of the container that you want to exclude from your logs.
A list of logging filter IDs that the filter covers.
The unique identifier of the logging configuration.
The pod label that you want to exclude from your logs.
The log level that you want to apply to your logs. Supported values are
debugorinfo.A list of logging configuration IDs where you want to apply the log filter.
A string in a log message that you want to exclude from your logs.
The Kubernetes namespace that you want to exclude from your logs.
Set this value to
trueif you want to interpret the message field as a regular expression.The type of filter that you want to apply to your logs. Supported values are
containerandnon-container.Internal use only.
Status Code
Ok. Logs from the specified logging configurations will be filtered on the provided selectors.
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.
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run
ibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To see a list of your clusters, run
ibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Delete a logging filter configuration.
Delete the specified logging filter configuration for a cluster.
DELETE /v1/logging/{idOrName}/filterconfigs/{id}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster get --cluster <cluster_name_or_ID>.
Path Parameters
The name or ID of the target cluster. To list the clusters that you have access to, run
ibmcloud ks cluster ls.The UUID for the filterConfig that you want to delete.
Query Parameters
Forces the request which may cause a new fluentd version to be deployed to the cluster.
Response
Status Code
Ok. Logs will no longer be filtered by the specified filter configuration.
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run
ibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To see a list of your clusters, run
ibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View a logging filter configuration.
View details for a logging filter configuration.
GET /v1/logging/{idOrName}/filterconfigs/{id}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster get --cluster <cluster_name_or_ID>.
Path Parameters
The name or ID of the target cluster. To list the clusters that you have access to, run
ibmcloud ks cluster ls.The UUID of the logging filter that you want to fetch.
Query Parameters
To show matching logging configurations for global filters, set to
true.
Response
FilterConfigResponse is how users will see their logging filter configs from API responses
The name of the container that you want to exclude from your logs.
A list of logging filter IDs that the filter covers.
The unique identifier of the logging configuration.
The pod label that you want to exclude from your logs.
The log level that you want to apply to your logs. Supported values are
debugorinfo.A list of logging configuration IDs where you want to apply the log filter.
A string in a log message that you want to exclude from your logs.
The Kubernetes namespace that you want to exclude from your logs.
Set this value to
trueif you want to interpret the message field as a regular expression.The type of filter that you want to apply to your logs. Supported values are
containerandnon-container.Internal use only.
Status Code
Ok. A logging filter is configured for your cluster.
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run
ibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To see a list of your clusters, run
ibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Update a logging filter configuration.
Update a logging filter config where id is the UUID for the filter config.
PUT /v1/logging/{idOrName}/filterconfigs/{id}Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster get --cluster <cluster_name_or_ID>.
Path Parameters
The name or ID of the target cluster. To list the clusters that you have access to, run
ibmcloud ks cluster ls.The UUID for the filterConfig that you want to update.
Query Parameters
Forces the request which may cause a new fluentd version to be deployed to the cluster.
The new filter configuration for the specified ID.
The name of the container where you want to apply the logging filter.
The log level that you want to apply to your logging filter.
A list of logging configuration IDs where you want to apply the logging filter.
A string in a message to which you want to apply the logging filter.
The Kubernetes namespace where you want to apply the logging filter.
Set this value to
trueif you want the message field to be interpreted as a regular expression.The type of the logging filter.
Response
FilterConfigResponse is how users will see their logging filter configs from API responses
The name of the container that you want to exclude from your logs.
A list of logging filter IDs that the filter covers.
The unique identifier of the logging configuration.
The pod label that you want to exclude from your logs.
The log level that you want to apply to your logs. Supported values are
debugorinfo.A list of logging configuration IDs where you want to apply the log filter.
A string in a log message that you want to exclude from your logs.
The Kubernetes namespace that you want to exclude from your logs.
Set this value to
trueif you want to interpret the message field as a regular expression.The type of filter that you want to apply to your logs. Supported values are
containerandnon-container.Internal use only.
Status Code
Ok. The configuration was updated.
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.
Unauthorized. To retrieve your access tokens, be sure that you're logged in and run
ibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To see a list of your clusters, run
ibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Update a DNS record by adding an NLB IP address.
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.
PUT /v1/nlb-dns/clusters/{idOrName}/addRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
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.
Response
Status Code
Ok. The request to update the NLB subdomain was successfully processed.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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/clustersAPI or runibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use theGET /clusters/{idOrName}/listAPI or runibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>. To list existing NLB IP addresses in a cluster, runkubectl get svc -n <namespace>.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.
No Sample Response
Remove an IP address from an NLB subdomain.
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.
DELETE /v1/nlb-dns/clusters/{idOrName}/host/{nlbHost}/ip/{nlbIP}/removeRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The existing NLB subdomain from which you want remove an NLB IP. To list existing NLB subdomains, use the
GET /clusters/{idOrName}/listAPI or runibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.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}/listAPI or runibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.
Response
Status Code
Deleted. The NLB IP address was successfully unregistered from the DNS record for the NLB subdomain.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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/clustersAPI or runibmcloud ks cluster ls. To list existing NLB subdomains and the NLB IPs registered with those hostnames, use theGET /clusters/{idOrName}/listAPI or runibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.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.
No Sample Response
List registered NLB subdomains and NLB IP addresses.
In a classic cluster, list NLB subdomains and the NLB IP addresses registered with the DNS provider for each subdomain.
GET /v1/nlb-dns/clusters/{idOrName}/listRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
ClusterNlbHostsList used for storing Nlbs, NlbMonitor, NlbHealthCheckStatus
NlbHealthCheckConfig config for Health check monitor configuration list
NlbHealthCheckStatus status of Health check monitors
NlbConfig config for NLB configuration
Status Code
Ok. A list of NLB subdomains and the NLB IPs associated with the DNS record for the subdomains is returned for this cluster.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Create a new NLB subdomain and associate one or more NLB IP addresses with it.
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.
POST /v1/nlb-dns/clusters/{idOrName}/registerRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Include either the nlbIP or the nlbIPArray parameter that specifies the NLB IP address(es) that you want to register.
Response
NlbConfig config for NLB configuration
Status Code
Created. The NLB subdomain was successfully created and the NLB IP addres(es) registered with DNS.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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/clustersAPI or runibmcloud ks cluster ls. To list existing NLB IP addresses in a cluster, runkubectl get svc -n <namespace>.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.
No Sample Response
Enable or disable a health check monitor for an NLB subdomain.
Enable or disable an existing health check monitor for an NLB subdomain.
PUT /v1/nlb-dns/clusters/{idOrName}/healthRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Include only the nlbHost parameter to specify the NLB subdomain and the nlbMonitorState parameter to specify the health check monitor as enabled or disabled.
Response
Status Code
Ok. Health check monitor enable/disable request for successfully processed.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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/clustersAPI or runibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use theGET /clusters/{idOrName}/listAPI or runibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.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.
No Sample Response
Configure a health check monitor for an NLB subdomain.
Create and optionally enable a health check monitor for an existing NLB subdomain in a cluster.
PATCH /v1/nlb-dns/health/clusters/{idOrName}/configRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
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
- healthcheckProperties
Response
NlbHealthConfig config for NLB Health configuration
HealthcheckProperties used for storing config provided by user for healthcheck deprecated
Status Code
Created. The health check monitor was successfully configured for the NLB subdomain.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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/clustersAPI or runibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use theGET /clusters/{idOrName}/listAPI or runibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.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.
No Sample Response
View the health check monitor settings for an NLB subdomain.
View the health check monitor settings for an NLB subdomain.
GET /v1/nlb-dns/health/clusters/{idOrName}/host/{nlbHost}/configRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The NLB subdomain that you want health check monitor settings for. To list existing NLB subdomains, use the
GET /clusters/{idOrName}/listAPI or runibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.
Response
NlbHealthConfig config for NLB Health configuration
HealthcheckProperties used for storing config provided by user for healthcheck deprecated
Status Code
Ok. Health check monitor settings for the specified NLB subdomain are returned.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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/clustersAPI or runibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use theGET /clusters/{idOrName}/listAPI or runibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.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.
No Sample Response
List the health check monitor settings for all NLB subdomains.
List the settings for all existing health check monitors in a cluster.
GET /v1/nlb-dns/health/clusters/{idOrName}/listRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
ClusterNlbHostsList used for storing Nlbs, NlbMonitor, NlbHealthCheckStatus
NlbHealthCheckConfig config for Health check monitor configuration list
NlbHealthCheckStatus status of Health check monitors
NlbConfig config for NLB configuration
Status Code
Ok. The health check monitor settings for each NLB subdomain in the cluster are returned.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Deprecated: List the health check status for the IPs behind NLB subdomains in a cluster.
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.
GET /v1/nlb-dns/health/clusters/{idOrName}/statusRequest
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Path Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
ClusterNlbHostsList used for storing Nlbs, NlbMonitor, NlbHealthCheckStatus
NlbHealthCheckConfig config for Health check monitor configuration list
NlbHealthCheckStatus status of Health check monitors
NlbConfig config for NLB configuration
Status Code
Ok. An array that contains the NlbHealthCheckStatus is returned.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
View a user's ability to create free and standard clusters in a region and resource group.
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.
GET /v1/user-config
Request
Custom Headers
Target the IBM Cloud Kubernetes Service region where you want to check the ability to create free and standard clusters. To list available regions, use the
GET /v1/regionsAPI or runibmcloud ks region ls.Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Ignore specific ingress status errors in ingress status reporting.
Ignore specific ingress status errors in ingress status reporting. Ignored errors will not affect the cluster's ingress status state.
POST /v2/alb/addIgnoredIngressStatusErrors
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Ingress status errors that are ignored for ingress status reporting.
Response
Status Code
Ignored ingress status errors were successfully added to the ingress status configuration.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
Not found. The specified cluster could not be found.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
View details of an ALB.
View detailed information for an ALB in a VPC or classic cluster. An ALBConfig response will be returned for ALBs in classic clusters.
GET /v2/alb/getAlb
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. This parameter is required for any resource group other than the default. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run
ibmcloud resource groups.
Query Parameters
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/getClusterAlbsAPI or runibmcloud ks alb ls --cluster <cluster_name_or_ID>.
Response
The build number of the ALB.
The ID of the application load balancer (ALB).
The type of ALB.
The public IP address that exposes the ALB.
The auth build of the ALB.
The ID of the cluster that the ALB belongs to.
The date the ALB was created.
If set to true, the deployment of the ALB is disabled.
Set to true to enable the ALB, or false to disable the ALB for the cluster.
The name of the cluster that the ALB belongs to.
The version of network load balancer that the ALB uses.
Desired number of ALB replicas that you want in your cluster.
If set to true, resizing of the ALB is done.
The state of the ALB.
The status of the ALB.
The VLAN ID that the ALB is attached to.
The zone where you want to add ALBs.
Status Code
Ok. Details for the specified ALB are returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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/clustersAPI or runibmcloud ks cluster ls. To list the VPC clusters that you have access to, use theGET /v2/vpc/getClustersAPI or runibmcloud ks cluster ls --provider vpc-classic.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.
No Sample Response
List supported Ingress controller images.
List the community Kubernetes Ingress controller and IBM Cloud Kubernetes Service ALB images that are supported.
GET /v2/alb/getAlbImages
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Response
Status Code
Ok. A list of supported Ingress controller images is returned.
Forbidden. The credentials set for the region and resource group have insufficient permissions to list supported Ingress controller images.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
List all ALBs in a cluster.
List all 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.
GET /v2/alb/getClusterAlbs
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.
Query Parameters
To list the classic clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls. To list the VPC clusters that you have access to, use theGET /v2/vpc/getClustersAPI or runibmcloud ks cluster ls --provider vpc-classic.
Response
ClusterALB alb related information for vpc cluster
PrivateIngressHostname string
json:"privateIngressHostname"PrivateIngressSecretName stringjson:"privateIngressSecretName"
Status Code
Ok. A list of ALBs for the cluster is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the classic clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls. To list the VPC clusters that you have access to, use theGET /v2/vpc/getClustersAPI or runibmcloud ks cluster ls --provider vpc-classic.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.
No Sample Response
Get the status of the in-cluster ALB health checker.
Check the status of the in-cluster ALB health checker.
GET /v2/alb/getIngressClusterHealthcheck
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name or ID of the cluster.
Response
ALBClusterHealthCheckConfig
Status Code
Ok. The in-cluster ALB health checker status for your cluster is returned.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
Not found. The specified cluster could not be found.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Get the status of the ingress resources in a cluster.
Check the status of the IBM provided subdomain and application load balancers
GET /v2/alb/getStatus
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name or ID of the cluster that you want information about.
Response
Status struct for the top level ingress status, for a cluster
ComponentStatus status of individual ingress component
V2ComponentStatus status of individual ingress component
V2ComponentStatus status of individual ingress component
V2ComponentStatus status of individual ingress component
V2ComponentStatus status of individual ingress component
V2ComponentStatus status of individual ingress component
Status Code
Ok. The ingress status for your cluster is returned.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
Not found. The specified cluster could not be found.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
List all ingress status errors that are ignored for the cluster.
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.
GET /v2/alb/listIgnoredIngressStatusErrors
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name or ID of the cluster.
Response
IgnoredIngressStatusErrors
Status Code
Ok. All ignored ingress status errors for your cluster are returned.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
Not found. The specified cluster could not be found.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Unignore specific ingress status errors in ingress status reporting.
Unignore specific ingress status errors in ingress status reporting. Unignored errors will affect the cluster's ingress status state.
DELETE /v2/alb/removeIgnoredIngressStatusErrors
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Ingress status errors that are ignored for ingress status reporting.
Response
Status Code
Ignored ingress status errors were successfully removed from the ingress status configuration.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
Not found. The specified cluster could not be found.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Set the in-cluster ingress health checker.
Set the in-cluster ingress health checker state. It can be either enabled or disabled.
POST /v2/alb/setIngressClusterHealthcheck
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
The desired state of the in-cluster ingress health checker.
Response
Status Code
Set successfully finished.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
Not found. The specified cluster could not be found.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Set the state of the ingress status.
Set the state of the ingress status for a cluster. It can be either enabled or disabled.
POST /v2/alb/setIngressStatusState
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
The desired state of ingress status.
Response
Status Code
Set successfully finished.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
Not found. The specified cluster could not be found.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Update ALBs in a cluster.
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.
POST /v2/alb/updateAlb
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
The input parameter to update an ALB's image. To see the supported image versions, use the GET /v2/alb/getAlbImages call.
Response
Status Code
Updated. The ALBs in the cluster were successfully updated.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
Not found. The specified cluster or ALB could not be found.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Create a public or private ALB in a specified zone and VPC cluster.
Create a new public or private ALB in a specified zone and VPC cluster.
POST /v2/alb/vpc/createAlb
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
The input parameters to create an ALB. For more information, see https://ibm.biz/alb_create_vpc
If set to true, the ALB is enabled by default. \
The type of Ingress image that you want to use for your ALB deployment.
The type of ALB that you want to create.
The zone where you want to deploy the ALB.
Response
AlbCreateResp used to send back the albid on a create request
Status Code
The ALB was successfully created.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
Not found. The specified cluster or zone could not be found. To list the VPC clusters that you have access to, use the
GET /v2/vpc/getClustersAPI or runibmcloud ks cluster ls --provider vpc-classic. To list the zones available in a VPC cluster, use theGET /v2/vpc/getClusterAPI or run ibmcloudks cluster-get --cluster <cluster_name_or_ID>.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Disable an ALB in your VPC cluster.
Disable a public or private ALB in your VPC cluster.
POST /v2/alb/vpc/disableAlb
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
The input parameters to disable an ALB. DisableDeployment and albID are required. For more information, see https://ibm.biz/alb_configure_vpc
The build number of the ALB.
The ID of the application load balancer (ALB).
The type of ALB.
The public IP address that exposes the ALB.
The auth build of the ALB.
The ID of the cluster that the ALB belongs to.
The date the ALB was created.
If set to true, the deployment of the ALB is disabled.
Set to true to enable the ALB, or false to disable the ALB for the cluster.
The name of the cluster that the ALB belongs to.
The version of network load balancer that the ALB uses.
Desired number of ALB replicas that you want in your cluster.
If set to true, resizing of the ALB is done.
The state of the ALB.
The status of the ALB.
The VLAN ID that the ALB is attached to.
The zone where you want to add ALBs.
Response
Status Code
Disabled. The ALB for the cluster was successfully disabled.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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/getClustersAPI or runibmcloud ks cluster ls --provider vpc-classic. To list the ALBs in a cluster, use theGET /v2/alb/getClusterAlbsAPI or runibmcloud ks alb ls --cluster <cluster_name_or_ID>.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Enable an existing ALB in a VPC cluster.
Enable a public or private ALB in your VPC cluster.
POST /v2/alb/vpc/enableAlb
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
The input parameter to enable an ALB. 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
The build number of the ALB.
The ID of the application load balancer (ALB).
The type of ALB.
The public IP address that exposes the ALB.
The auth build of the ALB.
The ID of the cluster that the ALB belongs to.
The date the ALB was created.
If set to true, the deployment of the ALB is disabled.
Set to true to enable the ALB, or false to disable the ALB for the cluster.
The name of the cluster that the ALB belongs to.
The version of network load balancer that the ALB uses.
Desired number of ALB replicas that you want in your cluster.
If set to true, resizing of the ALB is done.
The state of the ALB.
The status of the ALB.
The VLAN ID that the ALB is attached to.
The zone where you want to add ALBs.
Response
Status Code
Enabled. The ALB for the cluster was successfully enabled.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions to use a requested optional feature.
Not found. The specified cluster or ALB could not be found. To list the VPC clusters that you have access to, use the
GET /v2/vpc/getClustersAPI or runibmcloud ks cluster ls --provider vpc-classic. To list the ALBs in a cluster, use theGET /v2/alb/getClusterAlbsAPI or runibmcloud ks alb ls --cluster <cluster_name_or_ID>.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Start applying IAM roles to the cluster.
Apply IAM roles to the cluster. The roles are applied asynchronously. Use /v2/getRBACStatus to verify when they finish applying.
POST /v2/applyRBAC
Auditing
Calling this method generates the following auditing event.
IAM roles are applied to the cluster, and the Kubernetes configuration file for the cluster is requested. Depending on the request, the kubeconfig might contain administrator or network certificates and secrets to access the cluster.
containers-kubernetes.cluster.config
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v2/getClusterAPI.
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.
Response
Status Code
Accepted. Applies IAM roles asynchronously.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v2/getClustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Apply IAM roles to the cluster, then retrieve the cluster's kubeconfig file.
Apply IAM roles to the cluster, then retrieve the cluster's kubeconfig file to connect to your cluster and run Kubernetes API calls.
POST /v2/applyRBACAndGetKubeconfig
Auditing
Calling this method generates the following auditing event.
IAM roles are applied to the cluster, and the Kubernetes configuration file for the cluster is requested. Depending on the request, the kubeconfig might contain administrator or network certificates and secrets to access the cluster.
containers-kubernetes.cluster.config
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v2/getClusterAPI.Allowable values: [
application/json,application/zip,text/yaml]
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.
Response
ClientKubeConfig is the kubernetes config file used by kubectl
Legacy field from pkg/api/types.go TypeMeta.
Clusters is a map of referencable names to cluster configs
- clusters
Cluster holds the cluster information
- cluster
CertificateAuthority is the path to a cert file for the certificate authority.
CertificateAuthorityData contains PEM-encoded certificate authority certificates. Overrides CertificateAuthority
DisableCompression allows client to opt-out of response compression for all requests to the server. This is useful to speed up requests (specifically lists) when client-server network bandwidth is ample, by saving time on compression (server-side) and decompression (client-side): https://github.com/kubernetes/kubernetes/issues/112296.
InsecureSkipTLSVerify skips the validity check for the server's certificate. This will make your HTTPS connections insecure.
ProxyURL is the URL to the proxy to be used for all requests made by this client. URLs with "http", "https", and "socks5" schemes are supported. If this configuration is not provided or the empty string, the client attempts to construct a proxy configuration from http_proxy and https_proxy environment variables. If these environment variables are not set, the client does not attempt to proxy requests.
socks5 proxying does not currently support spdy streaming endpoints (exec, attach, port forward).
Server is the address of the kubernetes cluster (https://hostname:port).
TLSServerName is used to check server certificate. If TLSServerName is empty, the hostname used to contact the server is used.
Name is the nickname for this Cluster
Contexts is a map of referencable names to context configs
- contexts
Context holds the context information
- context
Cluster is the name of the cluster for this context
Namespace is the default namespace to use on unspecified requests
AuthInfo is the name of the authInfo for this context
Name is the nickname for this Context
CurrentContext is the name of the context that you would like to use by default
Legacy field from pkg/api/types.go TypeMeta.
Preferences holds general information to be use for cli interactions
- preferences
AuthInfos is a map of referencable names to user configs
- users
Name is the nickname for this AuthInfo
AuthInfo holds the auth information
- user
Impersonate is the username to impersonate. The name matches the flag.
ImpersonateGroups is the groups to impersonate.
ImpersonateUID is the uid to impersonate.
ImpersonateUserExtra contains additional information for impersonated user.
- as-user-extra
AuthProvider specifies a custom authentication plugin for the kubernetes cluster.
- auth-provider
- config
ClientCertificate is the path to a client cert file for TLS.
ClientCertificateData contains PEM-encoded data from a client cert file for TLS. Overrides ClientCertificate
ClientKey is the path to a client key file for TLS.
ClientKeyData contains PEM-encoded data from a client key file for TLS. Overrides ClientKey
Exec specifies a custom exec-based authentication plugin for the kubernetes cluster.
- exec
Preferred input version of the ExecInfo. The returned ExecCredentials MUST use the same encoding version as the input.
Arguments to pass to the command when executing it.
Command to execute.
Env defines additional environment variables to expose to the process. These are unioned with the host's environment, as well as variables client-go uses to pass argument to the plugin.
- env
This text is shown to the user when the executable doesn't seem to be present. For example,
brew install foo-climight be a good InstallHint for foo-cli on Mac OS systems.InteractiveMode determines this plugin's relationship with standard input. Valid values are "Never" (this exec plugin never uses standard input), "IfAvailable" (this exec plugin wants to use standard input if it is available), or "Always" (this exec plugin requires standard input to function). See ExecInteractiveMode values for more details.
If APIVersion is client.authentication.k8s.io/v1alpha1 or client.authentication.k8s.io/v1beta1, then this field is optional and defaults to "IfAvailable" when unset. Otherwise, this field is required. +optional
ProvideClusterInfo determines whether or not to provide cluster information, which could potentially contain very large CA data, to this exec plugin as a part of the KUBERNETES_EXEC_INFO environment variable. By default, it is set to false. Package k8s.io/client-go/tools/auth/exec provides helper methods for reading this environment variable.
Password is the password for basic authentication to the kubernetes cluster.
Token is the bearer token for authentication to the kubernetes cluster.
TokenFile is a pointer to a file that contains a bearer token (as described above). If both Token and TokenFile are present, Token takes precedence.
Username is the username for basic authentication to the kubernetes cluster.
Status Code
Ok. Returns the cluster's kubeconfig file.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v2/getClustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Set the autoupdate status of the cluster master.
Set the autoupdate status of the cluster master. Only a limited set of users can access use this API.
POST /v2/autoUpdateMaster
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
The event that is generated depends on the operation that you request for the cluster.
containers-kubernetes.cluster-master-autoupdate.enableAutomatic updates for master fix pack patch updates are enabled. Generated if the
autoUpdateparameter is set totrue.containers-kubernetes.cluster-master-autoupdate.disableAutomatic updates for master fix pack patch updates are disabled. Generated if the
autoUpdateparameter is set tofalse.
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
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.
Response
Status Code
Ok. The request was processed successfully.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The user doesn't have access to this API.
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Conflict. The specified value is already set on the cluster. To list the clusters properties, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group to list clusters for. To list available resource groups, run
ibmcloud resource groups. If you don't include this header, all the clusters in the account that you have access to are listed.
Query Parameters
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/clustersAPI or runibmcloud ks cluster ls.To view additional cluster resources like addons, VLANs, subnets, and storage, pass
true.
Response
CommonClusterAddon properties
CommonClusterCACertRotation CA cert rotation properties
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'
VlanConfigField TODO provide meaningful comment
VLANS is a helper type to sort an api.VLAN list. The VLANS will sort the list in order of the Properties.PrimaryRouter value so that VLAN's of a common router are listed consecutively.
Status Code
Success. Detailed cluster information.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
List the classic clusters that you have access to.
List the classic clusters that you have access to.
GET /v2/classic/getClusters
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group to list clusters for. To list available resource groups, run
ibmcloud resource groups. If you don't include this header, all the clusters in the account that you have access to are listed.
Query Parameters
Specify a location to filter clusters for. To see supported locations, use the
GET /v1/locationsAPI or runibmcloud ks locations.To view additional cluster resources like addons, VLANs, subnets, and storage, pass
true.
Response
GetClustersResponse cluster response for cluster list
CommonClusterAddon properties
CommonClusterCACertRotation CA cert rotation properties
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 Code
Success. A list of clusters that you have access to is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Get if VRF and Service Endpoint is enabled for the given account in the selected region.
Get if VRF and Service Endpoint is enabled for the given account in the selected region.
GET /v2/classic/getPrivateServiceEnabled
Request
Custom Headers
Specify the region to check for private service enablement.
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Response
PrivateServiceEndpointEnabled is a status from the softlayer for the used account OR for the attached infrastructure account in the actual region
Status Code
Ok. Detailed information about the private service enablement.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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..
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.
No Sample Response
List available classic infrastructure VLANs for a zone.
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>.
GET /v2/classic/getVLANs
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group to target.
Query Parameters
The ID of the zone where you want to list available public and private VLANs. To list available zones, run
ibmcloud ks zone lsor use theGET /v1/datacentersAPI.
Response
Status Code
Ok. A list of all VLANs is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions for the infrastructure provider.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View details of a worker node for classic cluster.
View detailed information for a worker node in a classic cluster.
GET /v2/classic/getWorker
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Query Parameters
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/clustersAPI or runibmcloud ks cluster ls.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}/workersAPI or runibmcloud ks workers <cluster_name_or_ID>.
Response
Status Code
Ok. Detailed information about the worker node is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks clusters.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View details of a worker pool for a classic cluster.
View detailed information for a worker pool in a classic cluster.
GET /v2/classic/getWorkerPool
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the
GET /v1/regionsAPI or runibmcloud ks region ls.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Query Parameters
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/clustersAPI or runibmcloud ks cluster ls.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}/workerpoolsAPI or runibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.
Response
- hostLabels
- labels
- taints
WorkerPoolZoneResponse response contents for zone
Status Code
Ok. Detailed information about the worker pool is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View details of a worker pool for a classic cluster.
View detailed information for a worker pool in a classic cluster.
GET /v2/classic/getWorkerPools
Request
Custom Headers
If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the
GET /v1/regionsAPI or runibmcloud ks region ls.Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Query Parameters
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/clustersAPI or runibmcloud ks cluster ls.
Response
- hostLabels
- labels
- taints
WorkerPoolZoneResponse response contents for zone
Status Code
Ok. Detailed information about the worker pools is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View all workers for a classic cluster.
View detailed information for all worker nodes in a classic cluster.
GET /v2/classic/getWorkers
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Query Parameters
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/clustersAPI or runibmcloud ks clusters.true|false Shows deleted workers
The name or ID of the worker pool to filter results for. Run
ibmcloud ks worker-pool ls --cluster <cluster name>.
Response
Status Code
Ok. Details for all workers in the classic cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks clusters.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers.
The required dedicated host parameters.
Response
Status Code
Created. The dedicated host was successfully created.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Conflict. A dedicated host create may already be in progress. Please wait a few minutes and try again.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers.The ID of the resource group to create the dedicated host pool in. To list available resource groups, run
ibmcloud resource groups. If this header is not included, the dedicated host pool is created in the default resource group.
The required dedicated host pool parameters.
Response
Status Code
Created. The dedicated host pool was successfully created.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Conflict. Creation of a dedicated host might already be in progress. Please wait a few minutes and try again.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Enables KMS in a cluster
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.
POST /v2/enableKMS
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Input parameters to create the Key Protect config for your cluster.
Response
Status Code
Ok. The requested KMS configuration has been enabled on the cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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/clustersAPI or runibmcloud ks cluster ls --provider vpc-classic.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Get the cluster's CA cert.
Get the cluster's CA cert to configure services with it to connect to the given cluster.
GET /v2/getCACert
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v2/getClusterAPI.
Query Parameters
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/getClustersAPI or runibmcloud ks cluster ls.
Response
Status Code
Ok. Returns the cluster's CA cert.
Bad request. The query parameters are either incomplete or in the wrong format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v2/getClustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
List the root keys for a Key Management Service instance.
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.
GET /v2/getCRKs
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group. To list available resource group IDs, run
ibmcloud resource groups.
Query Parameters
The KMS instance ID to list root keys for. To list available Key Protect service instances, run 'ibmcloud ks kms instance ls'.
Response
GetCRKResponse is data returned by a getCRKs request call
Status Code
Ok. A list of available root keys in the KMS instance is returned.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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/clustersAPI or runibmcloud ks cluster ls --provider vpc-classic.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View details for a cluster.
View detailed information for a cluster, including a VPC cluster.
GET /v2/getCluster
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group to list clusters for. To list available resource groups, run
ibmcloud resource groups. If you don't include this header, all the clusters in the account that you have access to are listed.
Query Parameters
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/getClustersAPI or runibmcloud ks cluster ls --provider vpc-classic.
Response
CommonClusterAddon properties
CommonClusterCACertRotation CA cert rotation properties
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'
VlanConfigField TODO provide meaningful comment
VLANS is a helper type to sort an api.VLAN list. The VLANS will sort the list in order of the Properties.PrimaryRouter value so that VLAN's of a common router are listed consecutively.
Status Code
Success. Detailed cluster information is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View details of the add-ons that are enabled in a cluster.
View details of the add-ons that are enabled in a cluster, including the add-on versions.
GET /v2/getClusterAddons
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group of the cluster, use the
GET /v1/clusters/{idOrName}API.
Query Parameters
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/clustersAPI or runibmcloud ks cluster ls.
Response
ClusterAddon represents one add on
The addon name such as 'istio'.
The versions that the addon can be upgraded to
The addon default versions based on supported cluster version/provider
- defaultVersions
Determines if this addon version is deprecated
The health state for this addon, a short indication (e.g. critical, pending)
The health status for this addon, provides a description of the state (e.g. error message)
AddonOptionsTemplate represents the options for an addon
- installOptionsTemplate
The minimum kubernetes version for this addon.
The minimum OpenShift version for this addon.
The addon options. Should be a yaml for a kube resource.
The addon supported providers.
The supported kubernetes version range for this addon.
The supported Openshift version range for this addon.
The addon target version.
The addon version, omit the version if you wish to use the default version.
VLAN spanning required for multi-zone clusters
Status Code
OK. Details for the add-ons in this cluster are returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
No Sample Response
View details of a dedicated host.
View detailed information for a dedicated host.
GET /v2/getDedicatedHost
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the
GET /v1/regionsAPI or runibmcloud ks region ls.
Query Parameters
The ID of the dedicated host that you want details for..
The ID of the dedicated host pool that you want to get the dedicated host details from.
Response
Status Code
Ok. Detailed information about the dedicated host is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified dedicated host could not be found.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View details of a dedicated host pool.
View detailed information for a dedicated host pool.
GET /v2/getDedicatedHostPool
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the
GET /v1/regionsAPI or runibmcloud ks region ls.
Query Parameters
The ID of the dedicated host pool that you want to get.
Response
Status Code
Ok. Detailed information about the dedicated host pool is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified dedicated host could not be found.
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.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the
GET /v1/regionsAPI or runibmcloud ks region ls.
Response
Status Code
Ok. Detailed information about the dedicated host pools is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified dedicated host pool could not be found.
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.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the
GET /v1/regionsAPI or runibmcloud ks region ls.
Query Parameters
The ID of the dedicated host pool that you want to get the dedicated hosts details from.
Response
Status Code
Ok. Detailed information about the dedicated hosts is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified dedicated host pool could not be found.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Get the details for a worker node flavor
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.
GET /v2/getFlavor
Request
Query Parameters
The ID of the flavor. To list available flavors, run
ibmcloud ks flavors --zone ZONEor use theGET /v2/getFlavorsAPI.The ID of the zone. To list available zones, run
ibmcloud ks zone lsor use theGET /v2/zonesAPI.The name of the provider. To check available providers, see the output of the
ibmcloud ks flavors --zone ZONEcommand or use theGET /v2/getFlavorsAPI.
Response
Flavor Definition of a flavor / machine type that can be deployed
The type of CPU architecture that the flavor uses.
The ID of the worker node flavor.
The name of the worker node flavor.
The name of the provider.
Status Code
Success
The specified zone is invalid. To list available zones, run
ibmcloud ks zone lsor use theGET /v2/zonesAPI.Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
List available flavors types for a VPC zone (data center).
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.
GET /v2/getFlavors
Request
Query Parameters
The ID of the location for which you want to list available flavors. To list available locations, run
ibmcloud ks zone lsor use theGET /v2/zonesAPI.Filters the flavors to match the provider type specified.
Response
Flavor Definition of a flavor / machine type that can be deployed
The type of CPU architecture that the flavor uses.
The ID of the worker node flavor.
The name of the worker node flavor.
The name of the provider.
Status Code
Success
The specified location is invalid. To list available locations, run
ibmcloud ks zone lsor use theGET /v2/zonesAPI.Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Gets KMS instances tied to an account
Retrieves available key management service (KMS) instances, such as Key Protect, in your IBM Cloud Account
GET /v2/getKMSInstances
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group. To list available resource group IDs, run
ibmcloud resource groups.
Response
Status Code
Ok. A list of all KMSs in your IBM Cloud Account
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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/clustersAPI or runibmcloud ks cluster ls --provider vpc-classic.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Get the cluster's kubeconfig file.
Get the cluster's Kubernetes configuration file (kubeconfig) to connect to your cluster and run Kubernetes API calls. You can also get the networking and admin configuration files for the cluster.
GET /v2/getKubeconfig
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v2/getClusterAPI.Allowable values: [
application/json,application/zip,text/yaml]
Query Parameters
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/getClustersAPI or runibmcloud ks cluster ls.Default endpoint is the public endpoint if available, private otherwise. Use 'private' to require a private endpoint and 'link' for a Satellite Link endpoint.
Default format is json. Other options include yaml, and zip.
Retrieve the admin kubeconfig file.
Retrieve the Calico network config. Requires admin=true and format=zip.
Response
ClientKubeConfig is the kubernetes config file used by kubectl
Legacy field from pkg/api/types.go TypeMeta.
Clusters is a map of referencable names to cluster configs
- clusters
Cluster holds the cluster information
- cluster
CertificateAuthority is the path to a cert file for the certificate authority.
CertificateAuthorityData contains PEM-encoded certificate authority certificates. Overrides CertificateAuthority
DisableCompression allows client to opt-out of response compression for all requests to the server. This is useful to speed up requests (specifically lists) when client-server network bandwidth is ample, by saving time on compression (server-side) and decompression (client-side): https://github.com/kubernetes/kubernetes/issues/112296.
InsecureSkipTLSVerify skips the validity check for the server's certificate. This will make your HTTPS connections insecure.
ProxyURL is the URL to the proxy to be used for all requests made by this client. URLs with "http", "https", and "socks5" schemes are supported. If this configuration is not provided or the empty string, the client attempts to construct a proxy configuration from http_proxy and https_proxy environment variables. If these environment variables are not set, the client does not attempt to proxy requests.
socks5 proxying does not currently support spdy streaming endpoints (exec, attach, port forward).
Server is the address of the kubernetes cluster (https://hostname:port).
TLSServerName is used to check server certificate. If TLSServerName is empty, the hostname used to contact the server is used.
Name is the nickname for this Cluster
Contexts is a map of referencable names to context configs
- contexts
Context holds the context information
- context
Cluster is the name of the cluster for this context
Namespace is the default namespace to use on unspecified requests
AuthInfo is the name of the authInfo for this context
Name is the nickname for this Context
CurrentContext is the name of the context that you would like to use by default
Legacy field from pkg/api/types.go TypeMeta.
Preferences holds general information to be use for cli interactions
- preferences
AuthInfos is a map of referencable names to user configs
- users
Name is the nickname for this AuthInfo
AuthInfo holds the auth information
- user
Impersonate is the username to impersonate. The name matches the flag.
ImpersonateGroups is the groups to impersonate.
ImpersonateUID is the uid to impersonate.
ImpersonateUserExtra contains additional information for impersonated user.
- as-user-extra
AuthProvider specifies a custom authentication plugin for the kubernetes cluster.
- auth-provider
- config
ClientCertificate is the path to a client cert file for TLS.
ClientCertificateData contains PEM-encoded data from a client cert file for TLS. Overrides ClientCertificate
ClientKey is the path to a client key file for TLS.
ClientKeyData contains PEM-encoded data from a client key file for TLS. Overrides ClientKey
Exec specifies a custom exec-based authentication plugin for the kubernetes cluster.
- exec
Preferred input version of the ExecInfo. The returned ExecCredentials MUST use the same encoding version as the input.
Arguments to pass to the command when executing it.
Command to execute.
Env defines additional environment variables to expose to the process. These are unioned with the host's environment, as well as variables client-go uses to pass argument to the plugin.
- env
This text is shown to the user when the executable doesn't seem to be present. For example,
brew install foo-climight be a good InstallHint for foo-cli on Mac OS systems.InteractiveMode determines this plugin's relationship with standard input. Valid values are "Never" (this exec plugin never uses standard input), "IfAvailable" (this exec plugin wants to use standard input if it is available), or "Always" (this exec plugin requires standard input to function). See ExecInteractiveMode values for more details.
If APIVersion is client.authentication.k8s.io/v1alpha1 or client.authentication.k8s.io/v1beta1, then this field is optional and defaults to "IfAvailable" when unset. Otherwise, this field is required. +optional
ProvideClusterInfo determines whether or not to provide cluster information, which could potentially contain very large CA data, to this exec plugin as a part of the KUBERNETES_EXEC_INFO environment variable. By default, it is set to false. Package k8s.io/client-go/tools/auth/exec provides helper methods for reading this environment variable.
Password is the password for basic authentication to the kubernetes cluster.
Token is the bearer token for authentication to the kubernetes cluster.
TokenFile is a pointer to a file that contains a bearer token (as described above). If both Token and TokenFile are present, Token takes precedence.
Username is the username for basic authentication to the kubernetes cluster.
Status Code
Ok. Returns the cluster's kubeconfig file.
Bad request. The query parameters are either incomplete or in the wrong format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v2/getClustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
List supported operating systems.
Lists supported operating systems for the given configuration.
GET /v2/getOperatingSystems
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name of the infrastructure provider in which to view supported operating systems. Available options include 'classic', 'vpc-gen2', and 'satellite'.
The Kubernetes or Openshift version.
Whether HyperShift is enabled.
Response
OperatingSystem is the supported OS
Status Code
Ok. The request to list supported operating systems was successfully processed.
Bad Request. Required parameters were not set. You must provide the
versionandproviderquery parameters.Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.
No Sample Response
View the quota for resources per region in the account.
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.
GET /v2/getQuota
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Response
GetQuota defines a response when getting quota for an account
Status Code
OK. A list of quota limits for resources per region in the account is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Get the RBACSync status.
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/applyRBACAndGetKubeconfig endpoint for the first time, poll this endpoint to verify the synchronization is complete.
GET /v2/getRBACStatus
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v2/getClusterAPI.
Query Parameters
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/getClustersAPI or runibmcloud ks cluster ls.
Response
Status Code
Success
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v2/getClustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View details of a worker node for cluster.
View detailed information for a worker node in a cluster.
GET /v2/getWorker
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v2/getCluster?cluster=idOrNameAPI.
Query Parameters
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/getClustersAPI or runibmcloud ks cluster ls --provider vpc-classic.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=idOrNameAPI or runibmcloud ks worker ls --cluster <cluster_name_or_ID>.
Response
Status Code
Ok. Detailed information about the worker node is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the VPC clusters that you have access to, use the
GET /v2/vpc/getClustersAPI or runibmcloud ks cluster ls --provider vpc-classic.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View details of a worker pool for a cluster.
View detailed information for a worker pool in a cluster.
GET /v2/getWorkerPool
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the
GET /v1/regionsAPI or runibmcloud ks region ls.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v2/getCluster?cluster=idOrNameAPI.
Query Parameters
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/getClustersAPI or runibmcloud ks cluster ls --provider vpc-classic.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=idOrNameAPI or runibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.
Response
getCombinedWorkerPoolResponse is a superset of all WorkerPool fields returned by all the v2 get worker(s) operations, regardless of the provider.
- hostLabels
- labels
DiskConfigResp response type for describing a disk configuration
- taints
GetWorkerPoolResponseZone provides information about a zone belonging to the worker pool
Status Code
Ok. Detailed information about the worker pool is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the VPC clusters that you have access to, use the
GET /v2/vpc/getClustersAPI or runibmcloud ks cluster ls --provider vpc-classic.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the
GET /v1/regionsAPI or runibmcloud ks region ls.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v2/getCluster?cluster=idOrNameAPI.
Query Parameters
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/getClustersAPI or runibmcloud ks cluster ls --provider vpc-classic.
Response
getCombinedWorkerPoolResponse is a superset of all WorkerPool fields returned by all the v2 get worker(s) operations, regardless of the provider.
- hostLabels
- labels
DiskConfigResp response type for describing a disk configuration
- taints
GetWorkerPoolResponseZone provides information about a zone belonging to the worker pool
Status Code
Ok. Detailed information about the worker pools is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the VPC clusters that you have access to, use the
GET /v2/vpc/getClustersAPI or runibmcloud ks cluster ls --provider vpc-classic.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View all workers for cluster.
View detailed information for all worker nodes in a cluster.
GET /v2/getWorkers
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v2/getCluster?cluster=idOrNameAPI.
Query Parameters
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/getClustersAPI or runibmcloud ks cluster ls --provider vpc-classic.true|false Shows deleted workers
Response
Status Code
Ok. Details for all workers in the cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the VPC clusters that you have access to, use the
GET /v2/vpc/getClustersAPI or runibmcloud ks cluster ls --provider vpc-classic.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Validates user provided entitlement.
Validates whether the provided entitlement value is supported or not.
GET /v2/hasValidEntitlement
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group whose API key token will be used for entitlement check. To list available resource groups, run
ibmcloud resource groups. If you don't include this header, the cluster is created in the default resource group. After you create a cluster, you cannot change the resource group. Note that if you plan to integrate IBM Cloud services with the cluster, all the resources must be in the same group.
Query Parameters
The entitlement value to check if it is supported.
Response
HasValidEntitlementResponse contains the information if the requested entitlement is supported or not
Status Code
Ok. The entitlement validation request was successfully processed.
The entitlement option can not be set when the stored API key has a subtype. For more information, see 'http://ibm.biz/api-key'.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Could not connect to the back-end billing validation service. Try again later.
No Sample Response
Rebalance workers in a worker pool.
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.
POST /v2/rebalanceWorkerPool
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v2/getClusterAPI.
Fields required to rebalance the worker pool.
Response
Status Code
OK. The request to balance the worker pool was successfully received.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Refresh the Kubernetes master.
Restart the Kubernetes master in the cluster to apply changes to the API server configuration.
POST /v2/refreshMaster
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Input parameters to refresh master. The cluster ID or name is required.
Response
Status Code
Ok. The Master will be put into the desired state.
Bad Request. Check that all headers are present and the cluster ID or name is provided.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster. To list the clusters that you have access to, use the
GET /vpc/v2/clustersAPI or runibmcloud ks cluster ls --provider vpc-classic.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
The dedicated host to target in a given dedicated host pool.
Response
Status Code
OK. The request to remove your dedicated host was successfully received.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
The dedicated host pool to target.
Response
Status Code
OK. The request to remove your dedicated host pool was successfully received.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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.
No Sample Response
Delete a worker node from a cluster.
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.
POST /v2/removeWorker
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v2/getClusterAPI.
Input parameters to remove a worker node. The cluster and worker node ID parameters are required.
Response
Status Code
Ok. The worker node was successfully removed from your cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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>.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Removes a worker pool.
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.
POST /v2/removeWorkerPool
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v2/getClusterAPI.
The cluster and worker pool to target.
Response
Status Code
OK. The request to remove your worker pool was successfully received.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Remove a zone from a worker pool.
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.
POST /v2/removeWorkerPoolZone
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v2/getClusterAPI.
The input parameter to specify the cluster, worker pool, and zone.
Response
Status Code
OK. The request to remove the zone from your worker pool was successfully received..
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Resize an existing worker pool.
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.
POST /v2/resizeWorkerPool
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v2/getClusterAPI.
The resize request.
Response
Status Code
Accepted. The worker pool will be resized to the specified value.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Set custom labels for a worker pool.
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.
POST /v2/setWorkerPoolLabels
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v2/getClusterAPI.
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.
- labels
Response
Status Code
OK. The request to set the labels of the worker pool was successfully received.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Set the operating system of a worker pool.
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).
POST /v2/setWorkerPoolOperatingSystem
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster belongs to in which the worker pools resides. To check the resource group ID of the cluster, use the
GET /v2/getClusterAPI.
Sets the operating system of a worker pool.
Response
Status Code
OK. The request to set the operating system of the worker pool was successful.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.The worker pool's operating system is not suitable for an upgrade this way.
The specified worker pool could not be found..
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Set custom taints for a worker pool.
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>.
POST /v2/setWorkerPoolTaints
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v2/getClusterAPI.
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 "".
- taints
Response
Status Code
OK. The request to set the taints of the worker pool was successfully received.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Create a VPC cluster.
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'.
POST /v2/vpc/createCluster
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers.The ID of the resource group to create the cluster in. To list available resource groups, run
ibmcloud resource groups. If you don't include this header, the cluster is created in the default resource group. After you create a cluster, you cannot change the resource group. Note that if you plan to integrate IBM Cloud services with the cluster, all the resources must be in the same group.
Input parameter to add a cluster. For more information, see https://ibm.biz/cluster_create_docs
VPCCreateClusterWorkerPool is the vpc version of the worker pool part of a create cluster request.
Response
UserMessage is used to provide human-readable text to convey useful, non-error information to users when a request was successfully completed.
ResponseErrors are used to communicate to non-critical errors to end users
Status Code
Created. The cluster was successfully created in the IBM Cloud account that you are logged in to.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.
Conflict. A cluster with the same name already exists. Choose another name for your cluster.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Create a worker pool for a VPC cluster.
Create a worker pool for the specified VPC cluster. Creating a worker pool requires Operator access to Kubernetes Service in the IBM Cloud account.
POST /v2/vpc/createWorkerPool
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
The
VPCCreateWorkerPoolZone contains all fields in the zones part of all requests to create worker pools.
- labels
Response
Status Code
Created. The worker pool was successfully created in for the specified cluster.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Conflict. A worker pool create may already be in progress for the provided cluster. Please wait a few minutes and try again.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Create a zone in the specified worker pool for a VPC cluster.
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.
POST /v2/vpc/createWorkerPoolZone
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers.The ID of the resource group to create the cluster in. To list available resource groups, run
ibmcloud resource groups. If you don't include this header, the cluster is created in the default resource group. After you create a cluster, you cannot change the resource group. Note that if you plan to integrate IBM Cloud services with the cluster, all the resources must be in the same group.
Input parameters to add zones to the worker pool.
Response
Status Code
OK. The requested zone has been added to the worker pool.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the
GET /v1/clusters/{idOrName}/workerpoolsAPI or runibmcloud ks worker-pool ls mycluster.Conflict. The provided zone already exists in the worker pool.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Query Parameters
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/clustersAPI or runibmcloud ks cluster ls.To view additional cluster resources like addons, VLANs, subnets, and storage, pass
true.
Response
CommonClusterAddon properties
CommonClusterCACertRotation CA cert rotation properties
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'
VlanConfigField TODO provide meaningful comment
VLANS is a helper type to sort an api.VLAN list. The VLANS will sort the list in order of the Properties.PrimaryRouter value so that VLAN's of a common router are listed consecutively.
Status Code
Success. Detailed cluster information.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
List the VPC clusters that you have access to.
List the VPC clusters that you have access to.
GET /v2/vpc/getClusters
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group to list clusters for. To list available resource groups, run
ibmcloud resource groups. If you don't include this header, all the clusters in the account that you have access to are listed.
Query Parameters
Specify a location to filter clusters for. To see supported locations, use the
GET /v1/locationsAPI or runibmcloud ks locations.The name of the provider to filter the clusters by.
Response
GetClustersResponse cluster response for cluster list
CommonClusterAddon properties
CommonClusterCACertRotation CA cert rotation properties
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 Code
Success. A list of clusters that you have access to is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View subnets for a given VPC.
View details for subnets in a VPC for the given region and provider.
GET /v2/vpc/getSubnets
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Query Parameters
The name of the VPC provider.
The name of the zone in which to list subnets.
The ID of the VPC.
Response
Subnet provides information about a vpc subnet
Status Code
Ok. A list of all subnets for the given VPC is returned.
Bad Request. The given provider, zone, or VPC is invalid.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The region of the VPC. To list regions, run
ibmcloud ks regions.Optional, specify a resource group ID to use its API key to list VPCs that the API key of the resource group has access to. To list available resource group IDs, run
ibmcloud resource groups.
Query Parameters
The name of the infrastructure provider that the VPC is created in. To list infrastructure providers of a VPC, run
ibmcloud ks vpcsor use theGET /v2/vpc/getVPCsAPI.The ID of the VPC. To list the ID of a VPC, run
ibmcloud ks vpcsor use theGET /v2/vpc/getVPCsAPI.
Response
GetVPC defines a response when getting a VPC
UserMessage is used to provide human-readable text to convey useful, non-error information to users when a request was successfully completed.
Status Code
OK. Details of the specified VPC are returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View VPCs for the given provider.
View details for all VPCs in the given provider
GET /v2/vpc/getVPCs
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Optional, specify a resource group ID to use its API key to list VPCs that the API key of the resource group has access to. To list available resource group IDs, run
ibmcloud resource groups.
Query Parameters
The name of the provider in which to list VPCs.
Response
Using the full name to avoid the linter complaining about stutter.
Status Code
Ok. A list of all VPCs is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View details of a worker node for VPC cluster.
View detailed information for a worker node in a VPC cluster.
GET /v2/vpc/getWorker
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Query Parameters
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/clustersAPI or runibmcloud ks cluster ls.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}/workersAPI or runibmcloud ks worker ls --cluster <cluster_name_or_ID>.
Response
Status Code
Ok. Detailed information about the worker node is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View details of a worker pool for a VPC cluster.
View detailed information for a worker pool in a VPC cluster.
GET /v2/vpc/getWorkerPool
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the
GET /v1/regionsAPI or runibmcloud ks region ls.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Query Parameters
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/clustersAPI or runibmcloud ks cluster ls.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}/workerpoolsAPI or runibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.
Response
- hostLabels
- labels
DiskConfigResp response type for describing a disk configuration
- taints
GetWorkerPoolResponseZone provides information about a zone belonging to the worker pool
Status Code
Ok. Detailed information about the worker pool is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the
GET /v1/regionsAPI or runibmcloud ks region ls.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Query Parameters
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/clustersAPI or runibmcloud ks cluster ls.
Response
- hostLabels
- labels
DiskConfigResp response type for describing a disk configuration
- taints
GetWorkerPoolResponseZone provides information about a zone belonging to the worker pool
Status Code
Ok. Detailed information about the worker pools is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
View all workers for VPC cluster.
View detailed information for all worker nodes in a VPC cluster.
GET /v2/vpc/getWorkers
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Query Parameters
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/clustersAPI or runibmcloud ks cluster ls.true|false Shows deleted workers
The name or ID of the worker pool to filter results for. Run
ibmcloud ks worker-pool ls --cluster <cluster name>.
Response
Status Code
Ok. Details for all workers in the VPC cluster.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
List available zones in a region.
List available zones that you can use to create a cluster in an IBM Cloud Kubernetes Service region.
GET /v2/vpc/getZones
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. Note that some zones are only available to certain accounts. Specify your IAM token to get the full list of zones that are available to your account. If no authorization is specified, then only zones that are generally available are returned. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers.
Query Parameters
The provider for which to list zones. Defaults to vpc-classic.
Determines whether to show the flavors for the returned zones.
Response
Zones sortable list of zone responses
FlavorResponse response type for retrieving a flavor
Status Code
Success. A list of available zones for a region is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.No zones found for provider. Run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Replace a worker node with a new worker node.
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.
POST /v2/vpc/replaceWorker
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
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.
Response
Status Code
OK. The worker node is being removed and replaced with a new worker node.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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/clustersAPI or runibmcloud ks cluster ls --provider vpc-classic.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
V2DisableImageSecurity
Disable image security enforcement for a cluster
POST /v2/disableImageSecurity
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Input parameters to specify the name or ID of the cluster that you want to disable image security enforcement in.
Response
Status Code
Ok. The request to update your master node was successfully processed.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Input parameters to specify the name or ID of the cluster that you want to enable image security enforcement in.
Response
Status Code
Ok. The request to update your master node was successfully processed.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Disable the Pod Security Policy admission controller.
Disable the Pod Security Policy admission controller for Kubernetes. This API is available only for Kubernetes clusters that run version 1.24. Use this API when migrating from the deprecated Pod Security Policy to the Pod Security admission controller.
POST /v2/disablePodSecurityPolicy
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
The cluster to target.
Response
Status Code
OK. The request to disable the Pod Security Policy admission controller was successfully received.
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.Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.
No Sample Response
Enable the Pod Security Policy admission controller.
Enable the Pod Security Policy admission controller. This API is available only for Kubernetes clusters that run version 1.24. Use this API when migrating from the deprecated Pod Security Policy to the Pod Security admission controller.
POST /v2/enablePodSecurityPolicy
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
The cluster to target.
Response
Status Code
OK. The request to enable the Pod Security Policy admission controller was successfully received.
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.Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.
No Sample Response
View the Pod Security admission control configuration for a cluster.
View the Pod Security admission control configuration for a cluster.
GET /v2/getPodSecurity
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name or ID of the cluster that you want to get the Pod Security admission control configuration for. To list the clusters that you have access to, use the
GET /v2/clustersAPI or runibmcloud ks cluster ls.
Response
PodSecurityResponse represents the configuration of the cluster PodSecurity admission controller
Configuration is a base64 encoded PodSecurityConfiguration yaml definition
Status Code
Ok. The request to view the Pod Security admission control configuration was successfully processed.
Bad Request. Required parameters were not set. You must provide the
clusterquery 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.Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.
No Sample Response
View the Pod Security Policy admission control configuration.
View the Pod Security Policy admission control configuration. This API is available only for clusters that run Kubernetes version 1.24. Use this API when migrating from the deprecated Pod Security Policy to the Pod Security admission controller.
GET /v2/getPodSecurityPolicy
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name or ID of the cluster that you want to get the Pod Security admission control configuration for. To list the clusters that you have access to, use the
GET /v2/clustersAPI or runibmcloud ks cluster ls.
Response
PodSecurityPolicyResponse represents the state of the cluster PodSecurityPolicy admission controller
Status Code
Ok. The request to view Pod Security Policy admission control configuration was successfully processed.
Bad Request. Required parameters were not set. You must provide the
clusterquery 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.Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.
No Sample Response
Remove the Pod Security admission controller configuration for Kubernetes v1.24 clusters.
Remove the Pod Security admission controller configuration. This API is available only for Kubernetes clusters that run version 1.24. Use this API when migrating from the deprecated Pod Security Policy to the Pod Security admission controller.
POST /v2/removePodSecurity
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
The cluster to target.
Response
Status Code
OK. The request to remove the Pod Security admission controller configuration was successfully received.
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.Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.
No Sample Response
Set the Pod Security admission controller configuration. This feature is available for clusters that run Kubernetes version 1.24 or later.
Set the Pod Security admission controller configuration. This feature is available for clusters that run Kubernetes version 1.24 or later.
POST /v2/setPodSecurity
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
The cluster to target.
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.
Response
Status Code
OK. The request to set the Pod Security admission controller configuration was successfully received.
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.Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Input parameters to specify the name or ID of the cluster and which service endpoint to update. Valid service endpoints are public or private.
Response
Status Code
Ok. The request to update your master node was successfully processed.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Input parameters to specify the name or ID of the cluster and which service endpoint to update. Valid service endpoints are public or private.
Response
Status Code
Ok. The request to update your master node was successfully processed.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Input parameters to specify the name or ID of the cluster and which service endpoint to update. Valid service endpoints are public or private.
Response
Status Code
Ok. The request to update your master node was successfully processed.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Input parameters to specify the name or ID of the cluster and which service endpoint to update. Valid service endpoints are public or private.
Response
Status Code
Ok. The request to update your master node was successfully processed.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Create an 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
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
Input parameters to specify the name or ID of the cluster and which to enable pull secrets for.
Response
Status Code
Ok. The request to update your master node was successfully processed.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
List available cluster versions.
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.
GET /v2/getVersions
Response
ReleaseVersion is a Kubernetes or OpenShift release version
PreviewState is a [ReleaseVersion] preview classification
Status Code
Success. Available container management platform versions for the IBM Cloud Kubernetes Service region are returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Replace a worker node with a new worker node.
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.
POST /v2/replaceWorker
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of a VPC cluster, use the
GET /v2/vpc/getCluster?cluster=idOrNameAPI.
Input parameters to replace a worker.
Response
Status Code
OK. The worker node is being removed and replaced with a new worker node.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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/getClustersAPI or runibmcloud ks cluster ls --provider vpc-classic.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Update the version of the Kubernetes cluster master node.
Update the Kubernetes master to the default API version. During the update, you cannot access or change the cluster. Worker nodes, apps, and resources that have been deployed by the user are not modified and will continue to run. You might need to change your YAML files for future deployments. For details, see the release notes at https://cloud.ibm.com/docs/containers?topic=containers-cs_versions
POST /v2/updateMaster
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v1/clusters/idOrNameAPI.
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.
Response
Status Code
Ok. The request to update your master node was successfully processed.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.
Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Conflict. The specified value is already set on the cluster. To list the clusters properties, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Update the health monitoring configuration for the specified NLB subdomain in a cluster.
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.
PUT /v2/nlb-dns/configureHealthMonitor
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
The full health monitoring configuration to overwrite the current configuration with. The configuration is defined in the corresponding provider specific field.
AkamaiHealthcheckProperties used for storing config provided by user for akamai healthcheck deprecated
Response
Status Code
Ok. The request to update the health monitor config was successfully processed.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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/clustersAPI or runibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use theGET /clusters/{idOrName}/listAPI or runibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.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.
No Sample Response
Remove a secret from an NLB subdomain.
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.
POST /v2/nlb-dns/deleteSecret
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Include the NLB subdomain that you want to delete the secret for, and the cluster that the subdomain is in.
Response
Status Code
Deleted. The secret name was successfully deleted for the NLB subdomain.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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, runibmcloud ks nlb-dns ls --cluster <cluster_name_or_id>.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.
No Sample Response
Get the health monitoring configuration for the specified NLB subdomain in a cluster.
Get the health monitoring configuration for the specified NLB subdomain in a cluster.
GET /v2/nlb-dns/getHealthMonitorConfig
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The existing NLB subdomain that you want the monitor config for. To list existing NLB subdomains, use the
GET /clusters/{idOrName}/listAPI or runibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.
Response
HealthMonitorConfiguration is a common struct to be used in NLB health monitor related APIs
AkamaiHealthcheckProperties used for storing config provided by user for akamai healthcheck deprecated
Status Code
OK. Current monitor config returned.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use theGET /clusters/{idOrName}/listAPI or runibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.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.
No Sample Response
List registered NLB subdomains in a cluster.
List NLB subdomains and the NLB IP addresses or the load balancer hostnames that are registered with the DNS provider for each NLB subdomain.
GET /v2/nlb-dns/getNlbDNSList
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.
Response
V2NlbList response for the get api for vpc clusters
ExtendedNlbVPCConfig is the response body for the get v2 vpc apis
Status Code
Ok. A list of NLB subdomains and associated details is returned for this cluster.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use theGET /clusters/{idOrName}/listAPI or runibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.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.
No Sample Response
Get the details for the specified NLB subdomain in a cluster.
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.
GET /v2/nlb-dns/getNlbDetails
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name or ID of the cluster. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls.The existing NLB subdomain that you want details for. To list existing NLB subdomains, use the
GET /clusters/{idOrName}/listAPI or runibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.
Response
NlbVPCListConfig single nlb subdomain in list response
ExtendedNlbVPCConfig is the response body for the get v2 vpc apis
Status Code
OK. Details of the NLB subdomain are returned.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v1/clustersAPI or runibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use theGET /clusters/{idOrName}/listAPI or runibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.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.
No Sample Response
Get the details for the specified subdomain in a Satellite location.
Get the details for the subdomain and the IP addresses that are registered with the DNS provider for each subdomain.
GET /v2/nlb-dns/getSatLocationSubdomain
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
To list available locations, use the GET
/v2/satellite/getControllersAPI, or runibmcloud sat location ls.The existing subdomain that you want details for. To list existing subdomains, use the
GET /v2/nlb-dns/getSatLocationSubdomainsAPI or runibmcloud sat location dns ls --cluster <cluster_name_or_ID>.
Response
NlbConfig config for NLB configuration
Status Code
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.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your IAM and UAA tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Could not find the IBM Cloud Satellite location. To list available locations, use the GET
/v2/satellite/getControllersAPI, or runibmcloud sat location ls.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.
No Sample Response
List registered NLB subdomains in a Satellite location.
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.
GET /v2/nlb-dns/getSatLocationSubdomains
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
To list available locations, use the GET
/v2/satellite/getControllersAPI, or runibmcloud sat location ls.
Response
V2NlbList response for the get api for vpc clusters
ExtendedNlbVPCConfig is the response body for the get v2 vpc apis
Status Code
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.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Could not find the IBM Cloud Satellite location. To list available locations, use the GET
/v2/satellite/getControllersAPI, or runibmcloud sat location ls.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.
No Sample Response
Regenerates cert for secret.
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.
POST /v2/nlb-dns/regenerateCert
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Include the cluster and subdomain for the NLB subdomain that you want to remove the secret from.
Response
Status Code
The cert has been successfully triggered for regeneration.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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, runibmcloud ks nlb-dns ls --cluster <cluster_name_or_id>.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
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
Registers Multishift domains for a cluster.
POST /v2/nlb-dns/registerMSCDomains
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
ibmcloud iam oauth-tokens. This header may be omitted if you use thePOST /v1/credentialsAPI prior to this request.
The input parameter to register a Multishift cluster's domains.
Response
type MSCRegisterResp returned once multishift controller domains have been registered
type DNSRegistrations
Status Code
Registered. The multishift cluster domains and cname have been successfully registered.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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/clustersAPI or runibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use theGET /clusters/{idOrName}/listAPI or runibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Create a new NLB subdomain in a VPC cluster and associate a load balancer hostname with it.
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.
POST /v2/nlb-dns/vpc/createNlbDNS
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Include the lbHostname parameter that specifies the VPC load balancer hostname that you want to register.
Response
NlbVPCConfig is the request and response body for the v2 vpc apis
Status Code
Created. The NLB subdomain was successfully created and the VPC load balancer hostname is registered with DNS.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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/getClustersAPI or runibmcloud ks cluster ls --provider vpc-classic. To list existing load balancer hostnames in a cluster, runkubectl get svc -n <namespace>.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.
No Sample Response
Remove the load balancer hostname from the DNS record for an existing NLB subdomain.
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.
POST /v2/nlb-dns/vpc/removeLBHostname
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Include the cluster parameter (required) and the nlbSubdomain parameter (required) for the NLB subdomain that you want to remove the load balancer hostname from.
Response
Status Code
Removed. The load balancer hostname was successfully unregistered from the DNS record for the NLB subdomain.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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/getClustersAPI or runibmcloud ks cluster ls --provider vpc-classic. To list existing NLB subdomains, runibmcloud ks nlb-dns ls --cluster <cluster_name_or_id>.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.
No Sample Response
Update the DNS record for an NLB subdomain by replacing the load balancer hostname.
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.
POST /v2/nlb-dns/vpc/replaceLBHostname
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Include only the cluster ID, existing lbHostname that you want to replace, and nlbSubdomain of the DNS record that you want to update.
Response
NlbVPCConfig is the request and response body for the v2 vpc apis
Status Code
Ok. The request to update the load balancer hostname was successfully processed.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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/getClustersAPI or runibmcloud ks cluster ls --provider vpc-classic. To list existing load balancer hostnames in a cluster, runkubectl get svc -n <namespace>. To list existing NLB subdomains, runibmcloud ks nlb-dns ls --cluster <cluster_name_or_id>.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.
No Sample Response
Do not use it as this endpoint is not supported in the long term
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.`
GET /v2/rotateClusterCOSKey
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run
cat ~/.bluemix/config.json. To use thePOST https://iam.cloud.ibm.com/identity/tokenAPI to create a token, see https://ibm.biz/iks-tokens for the required request headers.The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the
GET /v2/getClusterAPI.
Query Parameters
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/getClustersAPI or runibmcloud ks cluster ls.
Response
Status Code
No Content. Indicates that the rotation was successful.
Bad request. The query parameters are either incomplete or in the wrong format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified cluster could not be found. To list the clusters that you have access to, use the
GET /v2/getClustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Create an IBM Cloud Satellite cluster.
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.
POST /v2/satellite/createCluster
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token.
The ID of the resource group to create the Satellite cluster in. To list the resource group ID of the location, use the
GET /v2/satellite/getControllerAPI method.
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.
Optional: User provided value to indicate opt-in agreement to SatCon admin agent
Optional: Used to determine the correct IP for internal routing
- calicoIPAutodetection
The name or ID of the Satellite location
Optional: The entitlement to use in the default worker pool
Optional: Enables single worker node clusters
Optional: The OpenShift Container Platform version
Key-value pairs to label the host, such as cpu=4 to describe the host capabilities
- labels
The unique name for the new IBM Cloud Satellite cluster
Optional: NetworkPlugin indicates what container network interface has to be used in the cluster. If the field is missing it is defaulted to Calico.
Optional: The operating system to use in the default worker pool
Optional: User provided value for the pod subnet
Optional: The RedHat pull secret to create the OpenShift cluster
Optional: Flag to request a secure cluster is created
Optional: User provided value for service subnet
Optional: The number of worker nodes to create per zone in the default worker pool
Optional: The name of the zone to create the default worker pool in
Response
MultishiftCreateCluster create multishift cluster response
Status Code
Created. The cluster was successfully created in the IBM Cloud Satellite location.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
Conflict. A cluster with the same name already exists. Choose another name for your cluster.
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.
No Sample Response
Create a worker pool for an IBM Cloud Satellite cluster.
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.
POST /v2/satellite/createWorkerPool
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token.
The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the
GET /v2/satellite/getControllerAPI method.
The configuration details for your worker pool, in JSON format.
SatelliteCreateWorkerPoolZone contains all fields in the zones part of all requests to create worker pools.
- hostLabels
- labels
Response
Status Code
Created. The worker pool was successfully created in the specified cluster.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Conflict. Another worker pool might be provisioning for the specified cluster. Wait a few minutes and try again.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Create a zone in the specified worker pool for an IBM Cloud Satellite cluster.
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.
POST /v2/satellite/createWorkerPoolZone
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the
GET /v2/satellite/getControllerAPI method.
Input parameters to add zones to the worker pool.
Response
Status Code
OK. The requested zone was added to the worker pool.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the
GET /v2/getWorkerPoolsAPI or runibmcloud ks worker-pool ls -c <cluster>.Conflict. The provided zone already exists in the worker pool.
Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.
No Sample Response
List the IBM Cloud Satellite clusters that you have access to.
List the IBM Cloud Satellite clusters that you have access to.
GET /v2/satellite/getClusters
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the
GET /v2/satellite/getControllerAPI method.
Response
GetClustersResponse cluster response for cluster list
CommonClusterAddon properties
CommonClusterCACertRotation CA cert rotation properties
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 Code
Success. A list of clusters that you have access to is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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.
No Sample Response
Create an IBM Cloud Satellite cluster in a location that does not belong to your account.
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.
POST /v2/satellite/createClusterRemoteLocation
Request
Custom Headers
The IBM Cloud Identity and Access Management (IAM) token for the account to create the cluster in. To retrieve the token, log in to the account and run
ibmcloud iam oauth-tokens.The IBM Cloud Identity and Access Management (IAM) service CRN token for the service that creates the cluster. For the service CRN token to work for this API request, the user must previously authorize the service with the "Satellite Cluster Creator" action for Satellite in IAM for the IBM Cloud account where the Satellite location exists.
The ID of the resource group the cluster is to be created in.
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.
Optional: User provided value to indicate opt-in agreement to SatCon admin agent
Optional: Used to determine the correct IP for internal routing
- calicoIPAutodetection
The name or ID of the Satellite location
Optional: The entitlement to use in the default worker pool
Optional: Enables single worker node clusters
Optional: The OpenShift Container Platform version
Key-value pairs to label the host, such as cpu=4 to describe the host capabilities
- labels
The unique name for the new IBM Cloud Satellite cluster
Optional: NetworkPlugin indicates what container network interface has to be used in the cluster. If the field is missing it is defaulted to Calico.
Optional: The operating system to use in the default worker pool
Optional: User provided value for the pod subnet
Optional: The RedHat pull secret to create the OpenShift cluster
Optional: Flag to request a secure cluster is created
Optional: User provided value for service subnet
Optional: The number of worker nodes to create per zone in the default worker pool
Optional: The name of the zone to create the default worker pool in
Response
MultishiftCreateCluster create multishift cluster response
Status Code
Created. The cluster was successfully created in the IBM Cloud Satellite location.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
Conflict. A cluster with the same name already exists. Choose another name for your cluster.
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.
No Sample Response
List the clusters in an IBM Cloud Satellite location that are associated with a Satellite-enabled service instance.
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.
GET /v2/satellite/getServiceClusters
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the
GET /v2/satellite/getControllerAPI method.
Query Parameters
The ID of the location to list services.
Response
MultishiftGetServiceClusters describes a multishift service clusters response
CommonClusterAddon properties
CommonClusterCACertRotation CA cert rotation properties
MultishiftClusterHosts describes the hosts assigned to a cluster
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'
WorkerPool common worker pool data
Status Code
Success. A list of Satellite-enabled service clusters that you have access to is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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.
No Sample Response
Create an IBM Cloud Satellite location.
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.
POST /v2/satellite/createController
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token.
The ID of the resource group to create the Satellite location in. To list available resource group IDs from the command line, run
ibmcloud resource groups.
The configuration details for your Satellite location, in JSON format.
Optional: Used to determine the correct IP for internal routing
- calicoIPAutodetection
Satellite capabilities attached to the location
Indicates whether CoreOS features should be enabled for the location
COSBucket Optional: IBM Cloud Object Storage bucket configuration details
COSAuthorization Optional: IBM Cloud Object Storage authorization keys
A description of the new Satellite location
IngestionKeys Optional: Keys that can be passed in during Satellite location creation
The IBM Cloud metro from which the Satellite location is managed
The account ID for IBM Log Analysis with LogDNA log forwarding
Optional: Used to determine the pod subnet
Optional: Used to determine the service subnet
A unique name for the new Satellite location
An optional physical address of the new Satellite location which is deployed on premise
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)
Response
MultishiftCreateController create controller response
Status Code
Created. The location was successfully created in the IBM Cloud account that you are logged in to.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
Conflict. A location with the same name already exists. Choose another name for your location.
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.
No Sample Response
Get the details for an IBM Cloud Satellite location.
Get the details for an IBM Cloud Satellite location.
GET /v2/satellite/getController
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the Satellite location is in. To list available resource group IDs from the command line, run
ibmcloud resource groups. To list the resource group ID of the location, use theGET /v2/satellite/getControllerAPI method.
Query Parameters
The ID of the location to get information about.
Response
MultishiftGetController describes a multishift controller
CommonClusterAddon properties
CommonClusterCACertRotation CA cert rotation properties
CapabilityManagedBySatellite is a custom type for satellite capabilities
COSBucket Optional: IBM Cloud Object Storage bucket configuration details
Deployments reports status of deployments on the IBM Cloud Satellite location
Hosts lists the hosts belonging to the IBM Cloud Satellite location
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 Code
Success. The details of the requested IBM Satellite location are returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Could not find the IBM Cloud Satellite location. To list available locations, use the GET
/v2/satellite/getControllersAPI, or runibmcloud sat location ls.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.
No Sample Response
List the IBM Cloud Satellite locations that you have access to.
List the IBM Cloud Satellite locations that you have access to.
GET /v2/satellite/getControllers
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group to filter Satellite locations for. To list available resource group IDs from the command line, run
ibmcloud resource groups.
Response
MultishiftController describes an individual controller
ActivityTrackerKeyProvided indicates whether an Activity Tracker key was provided for the Satellite location
Satellite capabilities attached to the location.
CoreOSEnabled indicates whether the cluster type supports CoreOS
The timestamp when the Satellite location was created
The CRN for the Satellite location
Deployments reports status of deployments on the IBM Cloud Satellite location
Hosts lists the hosts belonging to the IBM Cloud Satellite location
The Satellite location ID
The IBM Cloud metro that the Satellite location is managed from
LogDNAKeyProvided indicates whether a LogDNA key was provided for the Satellite location
The Satellite location name
The IBM Cloud region that the Satellite location is managed from
ResourceGroupID the ID of the resource group that owns the Satellite location
ResourceGroupName the name of the resource group that owns the Satellite location
The health state of the Satellite location. Possible values include action required, critical, host required, normal, and provisioning. For more information, see the docs 'http://ibm.biz/sat-loc-health'
Status Code
Success. A list of locations that you have access to is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.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.
No Sample Response
Remove an IBM Cloud Satellite Location.
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.
POST /v2/satellite/removeController
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the
GET /v2/satellite/getControllerAPI method.
The IBM Satellite location to remove.
Optional: Used to determine the correct IP for internal routing
- calicoIPAutodetection
The name or ID of the Satellite location
Optional: Enables single worker node clusters
Optional: NetworkPlugin indicates what container network interface has to be used in the cluster. If the field is missing it is defaulted to Calico.
Optional: The RedHat pull secret to create the OpenShift cluster
Response
Status Code
OK. The request to remove your IBM Cloud Satellite location was successfully received.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Could not find the IBM Cloud Satellite location. To list available locations, use the GET
/v2/satellite/getControllersAPI, or runibmcloud sat location ls.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/getClustersAPI or runibmcloud ks cluster ls.Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
No Sample Response
Assign a host to an IBM Cloud Satellite location or cluster.
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.
POST /v2/satellite/hostqueue/createAssignment
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token.
The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the
GET /v2/satellite/getControllerAPI method.
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.
The name or ID of a Satellite location or cluster to assign the host to
The name or ID of the Satellite location
Optional: The name or ID of the specific host to assign to a Satellite location or cluster
Key-value pairs to label the host, such as cpu=4 to describe the host capabilities
- labels
Optional: The name or ID of the worker pool within the cluster to assign the host to
Optional: The zone within the cluster to assign the host to
Response
MultishiftCreateAssignment create multishift assignment response
Status Code
Created. A host was successfully assigned to your IBM Cloud Satellite resource.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
Could not find the IBM Cloud Satellite location. To list available locations, use the GET
/v2/satellite/getControllersAPI, or runibmcloud sat location ls.Conflict. Could not find any available hosts that match your requested host ID or label parameters.
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.
No Sample Response
Attach a host to an IBM Cloud Satellite location.
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.
POST /v2/satellite/hostqueue/createRegistrationScript
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token.
The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the
GET /v2/satellite/getControllerAPI method.
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.
The name or ID of the Satellite location
Key-value pairs to label the host, such as cpu=4 to describe the host capabilities
- labels
Response
Status Code
Created. The response contains a script that you can run on your host to attach the host to your IBM Cloud Satellite location.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
Could not find the IBM Cloud Satellite location. To list available locations, use the GET
/v2/satellite/getControllersAPI, or runibmcloud sat location ls.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.
No Sample Response
List the hosts in your IBM Cloud Satellite location.
List the hosts in your IBM Cloud Satellite location.
GET /v2/satellite/hostqueue/getHosts
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the
GET /v2/satellite/getControllerAPI method.
Query Parameters
The ID of the location to to retrieve hosts from.
Response
MultishiftQueueNode describes an individual queue node
Assignment is information about the host assignment
Health is the health status of the host
The unique ID of the host
Key-value pairs to label the host, such as cpu=4 to describe the host capabilities
- labels
The unique name of the host
The availability state of the host. Possible values include assigned and unassigned. For more information, see the docs 'http://ibm.biz/sat-host-health'
Status Code
Success. A list of hosts in your IBM Cloud Satellite location is returned.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Could not find the IBM Cloud Satellite location. To list available locations, use the GET
/v2/satellite/getControllersAPI, or runibmcloud sat location ls.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.
No Sample Response
Remove a host from an IBM Cloud Satellite location or cluster.
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>.
POST /v2/satellite/hostqueue/removeHost
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token.
The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the
GET /v2/satellite/getControllerAPI method.
The configuration details to remove a host from an IBM Cloud Satellite location, in JSON format.
The name or ID of the Satellite location
The name or ID of the host to remove
Response
Status Code
OK. The host was successfully removed from your IBM Cloud Satellite location.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
Could not find the host. To list available hosts, use the GET
/v2/satellite/hostqueue/getHostsAPI or runibmcloud sat host ls.Conflict. Cannot remove the host because a worker node runs on the host. Remove the worker node and try again.
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.
No Sample Response
Update a host in your IBM Cloud Satellite location.
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.
POST /v2/satellite/hostqueue/updateHost
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token.
The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the
GET /v2/satellite/getControllerAPI method.
The configuration details to update a host to an IBM Cloud Satellite resource, in JSON format.
The name or ID of the Satellite location
The name or ID of the host to update
Key-value pairs to label the host, such as cpu=4 to describe the host capabilities
- labels
Response
Status Code
OK. The host was successfully updated.
Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.
Could not find the host. To list available hosts, use the GET
/v2/satellite/hostqueue/getHostsAPI or runibmcloud sat host ls.Conflict. The labels cannot be updated because the host is already assigned to an IBM Cloud Satellite resource, such as a cluster.
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.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokensThe unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster-get <cluster>.
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.
Response
Status Code
Ok. Attach request successfully accepted.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified worker could not be found. To list the workers, use the
GET /v2/vpc/getWorkersAPI or runibmcloud ks workers --cluster <clusterID or Name>.Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokensThe unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster-get <cluster>.
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>.
Response
Status Code
Ok. detach request successfully accepted.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified worker could not be found. To list the workers, use the
GET /v2/vpc/getWorkersAPI or runibmcloud ks workers --cluster <clusterID or Name>.Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
getAttachment
Get the volume attachment detail for given volume attachment ID
GET /v2/storage/getAttachment
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokensThe unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster-get <cluster>.
Query Parameters
The ID or name of the cluster. To list the clusters that you have access to, run
ibmcloud ks clusters.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>.The unique volume attachment ID for the attached volume
Response
Status Code
Ok.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified worker could not be found. To list the workers, use the
GET /v2/vpc/getWorkersAPI or runibmcloud ks workers --cluster <clusterID or Name>.Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokensThe unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster-get <cluster>.
Query Parameters
The ID or name of the cluster. To list the clusters that you have access to, run
ibmcloud ks clusters.The ID of the worker node, whose volume attachments needs to be listed.
Response
Status Code
Ok.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified worker could not be found. To list the workers, use the
GET /v2/vpc/getWorkersAPI or runibmcloud ks workers --cluster <clusterID or Name>.Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokensThe unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster-get <cluster>.
Query Parameters
The unique volume ID. To list the volume ID, use the
GET /v2/storage/classic/getVolumesAPI or runibmcloud ks storage volume ls classic.
Response
ID .. id is of a volume
Name .. Name of the volume
Status Code
Ok.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified worker could not be found. To list the workers, use the
GET /v2/vpc/getWorkersAPI or runibmcloud ks workers --cluster <clusterID or Name>.Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
List storage volumes for a cluster or for the account if no cluster is provided.
GET /v2/storage/getVolumes
Request
Custom Headers
The unique ID of your IBM Cloud resource group when you created your cluster. To see the cluster's resource group ID, run
ibmcloud ks cluster-get <cluster>.Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The ID or name of the classic cluster. To list the clusters that you have access to, run
ibmcloud ks cluster ls --provider classic.Filter the list for a specific infrastructure provider. Supported values are classic, vpc-classic, and vpc-gen2.
The zone to filter volume results by. To list available zones, run
ibmcloud ks locations.
Response
Status Code
Ok.
Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run
ibmcloud loginand thenibmcloud iam oauth-tokens.Not found. The specified worker could not be found. To list the workers, use the
GET /v2/vpc/getWorkersAPI or runibmcloud ks workers --cluster <clusterID or Name>.Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
No Sample Response
Acknowledge the request to expand storage capacity.
Acknowledge the request to expand the storage capacity of an existing storage request.
PATCH /v2/storage/satellite/ackDesiredStorageConfigCapacity
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
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>.
Response
Status Code
OK. The storage request is created.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getClustersAPI or runibmcloud sat service ls --location=<location-name-or-ID>. To list storage requests, use the/v2/satellite/getDesiredStorageConfigAPI.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.
No Sample Response
Create an assignment using a Satellite storage configuration for the cluster group(s).
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.
POST /v2/storage/satellite/createAssignment
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Include following parameters to create an assignment:
- Name of the assignment (
name). - Storage configuration name or ID (
config). To list the storage configurations that you have access to, use the GET/v2/storage/satellite/getStorageConfigurationsAPI or runibmcloud sat storage config ls. - The name or ID of the Satellite location (
controller). To list the Satellite locations that you have access to, use the GET/v2/satellite/getControllersAPIor runibmcloud sat location ls. - 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, runibmcloud sat group ls. - Enable or disable automatic upgrades for the assignment (
autoUpgrade="true|false").
Response
Status Code
OK. An assignment using the storage configuration is created.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getStorageConfigurationsAPI or runibmcloud sat storage config ls. To list the Satellite cluster groups you have access to, runibmcloud sat group ls.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.
No Sample Response
Create an assignment using a Satellite storage configuration for a Satellite cluster or service cluster.
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.
POST /v2/storage/satellite/createAssignmentByCluster
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Include following parameters to create an assignment:
- Name of the assignment (
name). - 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/getStorageConfigurationsByControllerAPI or runibmcloud sat storage config ls --location LOCATION. - 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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION. - The name or ID of the Satellite location (
controller). To list the Satellite locations that you have access to, use the GET/v2/satellite/getControllersAPIor runibmcloud sat location ls. - Enable or disable automatic upgrades for the assignment (
autoUpgrade="true|false").
Response
Status Code
OK. An assignment using the storage configuration is created.
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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION.Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getStorageConfigurationsByControllerAPI or runibmcloud 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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, runibmcloud sat location ls.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.
No Sample Response
Deprecated. To create a Satellite storage configuration, you can use /v2/storage/satellite/createStorageConfigurationByController API instead.
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.
POST /v2/storage/satellite/createStorageConfiguration
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
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.
- storage-class-parameters
- user-config-parameters
- user-secret-parameters
Response
CreateConfigurationData - a single return struct
- addChannel
Status Code
OK. The storage configuration is created.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
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.
No Sample Response
Create a Satellite storage configuration
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.
POST /v2/storage/satellite/createStorageConfigurationByController
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
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.
- storage-class-parameters
- user-config-parameters
- user-secret-parameters
Response
CreateConfigurationData - a single return struct
- addChannel
Status Code
OK. The storage configuration is created.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
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.
No Sample Response
Expand the capacity of a storage request.
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.
PATCH /v2/storage/satellite/expandDesiredStorageConfigCapacity
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
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>.
Response
Status Code
OK. The storage request is created.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getClustersAPI or runibmcloud sat service ls --location=<location-name-or-ID>. To list storage requests, use the/v2/satellite/getDesiredStorageConfigAPI.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.
No Sample Response
List Satellite storage configurations assigned to a Satellite cluster or service cluster.
List Satellite storage configurations that are assigned to a Satellite cluster or service cluster.
GET /v2/storage/satellite/getAssignedStorageConfigs
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION.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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite.
Response
AppliedStorageConfig contains the details of an assigned storage config on a cluster A list of AppliedStorageConfig structs is the response for the GetAssignedStorageConfigs query
- config-attributes
- rollout-status
Status Code
OK. Assigned Satellite storage configurations are listed.
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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, runibmcloud sat location ls.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.
No Sample Response
View details of an assignment.
View details of an assignment by the assignment UUID.
GET /v2/storage/satellite/getAssignment
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The UUID of the assignment. To list the assignments that you have access to, use the GET
/v2/storage/satellite/getAssignmentsAPI or runibmcloud sat storage assignment ls.
Response
Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59
- configRevisionStatus
- owner
- rolloutStatus
Status Code
OK. Assignment details are returned.
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/getAssignmentsAPI or runibmcloud sat storage assignment ls.Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found. The specified assignment could not be found. To list the assignments that you have access to, use the GET
/v2/storage/satellite/getAssignmentsAPI or runibmcloud sat storage assignment ls.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.
No Sample Response
Deprecated. To view details of an assignment, you can use /v2/storage/satellite/getAssignment API instead.
View details of an assignment by the assignment name.
GET /v2/storage/satellite/getAssignmentByName
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The name of the assignment. To list the assignments that you have access to, use the GET
/v2/storage/satellite/getAssignmentsAPI or runibmcloud sat storage assignment ls.
Response
Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59
- configRevisionStatus
- owner
- rolloutStatus
Status Code
OK. Assignment details successfully fetched.
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/getAssignmentsAPI or runibmcloud sat storage assignment ls.Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found. The specified assignment could not be found. To list the assignments that you have access to, use the GET
/v2/storage/satellite/getAssignmentsAPI or runibmcloud sat storage assignment ls.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.
No Sample Response
List storage assignments in the IBM Cloud account.
List storage assignments that you have access to in the IBM Cloud account. Returned details include the assignment name, UUID, and creation timestamp.
GET /v2/storage/satellite/getAssignments
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Response
Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59
- configRevisionStatus
- owner
- rolloutStatus
Status Code
OK. Assignments are listed.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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.
No Sample Response
List storage assignments created for a Satellite cluster or service cluster.
List storage assignments created for a Satellite cluster or service cluster. Returned details include the assignment name, UUID, and creation timestamp.
GET /v2/storage/satellite/getAssignmentsByClusterID
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION.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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite.
Response
Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59
- configRevisionStatus
- owner
- rolloutStatus
Status Code
OK. Assignments are listed.
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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION.
- 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
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, runibmcloud sat location ls.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.
No Sample Response
List storage assignments by configuration name or UUID.
List storage assignments by configuration name or UUID. Returned details include the assignment name, UUID, and creation timestamp.
GET /v2/storage/satellite/getAssignmentsByConfig
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The name or ID of the Satellite storage configuration. To list the storage configurations that you have access to, use the GET
/v2/storage/satellite/getStorageConfigurationsAPI or runibmcloud sat storage config ls.
Response
Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59
- configRevisionStatus
- owner
- rolloutStatus
Status Code
OK. Assignments are listed.
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/getStorageConfigurationsAPI or runibmcloud sat storage config ls.Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getStorageConfigurationsAPI or runibmcloud sat storage config ls.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.
No Sample Response
List storage assignments in a Satellite location.
List storage assignments that you have access to in a Satellite location. Returned details include the assignment name, UUID, and creation timestamp.
GET /v2/storage/satellite/getAssignmentsByController
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The name or ID of the Satellite location to list assignments for. To list the Satellite locations that you have access to, run
ibmcloud sat location ls.
Response
Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59
- configRevisionStatus
- owner
- rolloutStatus
Status Code
OK. Assignments are listed.
Bad Request. The controller is missing. To list the Satellite locations that you have access to, run
ibmcloud sat location ls.Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found. The specified location could not be found. To list the Satellite locations that you have access to, run
ibmcloud sat location ls.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.
No Sample Response
List and filter available storage classes from assigned Satellite storage configurations on a Satellite cluster or service cluster.
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.
GET /v2/storage/satellite/getAvailableStorageClasses
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The 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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION.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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite.Filter the available storage classes by volume type. The supported volume types are
file,blockandobject. If unspecified, available storage classes of all volume types are returned.Specify
trueorfalseto view only the available storage classes from software-defined storage (SDS) storage configurations. If unspecified, the default value istrue.
Response
AvailableStorageClasses contains a list of storage class names It is the response for GetAvailableStorageClasses query
Status Code
OK. Available storage classes are listed.
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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud 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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION. - The specified value is an invalid value for parameter
volumeType. Supported values forvolumeTypeparameter are:file, block, object. - The specified value is an invalid value for parameter
onlyShowSDS. Supported values foronlyShowSDSparameter are:true, false.
- 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
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, runibmcloud sat location ls.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.
No Sample Response
List Storage requests on a cluster.
List the storage requests for a cluster in a Satellite location.
GET /v2/storage/satellite/getDesiredStorageConfig
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The 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/getClustersAPI or runibmcloud sat service ls --location=<location-name-or-ID>. The response body for each storage request contains the request specifications and the following fields:- The
assignmentfield. 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. - A
statusfield in theconfigsection 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 topending. If a storage configuration has been assigned to the cluster, the status is set toassigned. If the storage request is deleted, the status is set todeleted. - A
statusfield in thebackendsection. 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 topending. If the request is acknowledged by the location administrator, the status is set tocompleted.
- The
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/getClustersAPI or runibmcloud sat service ls --location=<location-name-or-ID>.
Response
GetDesiredStorageConfigResponse is the respose body for getDesiredStorageConfig API
StorageRequest defines a storage request
Status Code
OK. Storage requests are listed.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getClustersAPI or runibmcloud sat service ls --location=<location-name-or-ID>.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.
No Sample Response
View details of a Satellite storage configuration.
View the details of a Satellite storage configuration.
GET /v2/storage/satellite/getStorageConfiguration
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The name of the storage configuration. To list the storage configurations that you have access to, run
ibmcloud sat storage config ls.Specify
trueto include details of assignment(s) of the specified storage configuration. The default value isfalse.
Response
- is-user-secret-parameters-set
- storage-class-parameters
ConfigAttributes defines attributes related to storage configuration
ConfigSubscriptionInfo contains the details of subscription to be shows as part of a storage config get or list response
- user-config-parameters
- user-secret-parameters
Status Code
OK. Storage configuration details are returned.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
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.
No Sample Response
List Satellite storage configurations.
List the Satellite storage configurations that you have access to in a Satellite location or in the IBM Cloud account.
GET /v2/storage/satellite/getStorageConfigurations
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The name or ID of the 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
ListStorageConfigData is the response struct for the list storage configuration APIs i.e. getStorageConfigurations & getStorageConfigurationsByController
ConfigAttributes defines attributes related to storage configuration
Status Code
OK. Storage configurations are listed.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
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.
No Sample Response
List Satellite storage configurations in a Satellite location.
List the Satellite storage configurations that you have access to in a Satellite location.
GET /v2/storage/satellite/getStorageConfigurationsByController
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The name or ID of the Satellite location to list storage configurations for. To list the Satellite locations that you have access to, run
ibmcloud sat location ls.
Response
ListStorageConfigData is the response struct for the list storage configuration APIs i.e. getStorageConfigurations & getStorageConfigurationsByController
ConfigAttributes defines attributes related to storage configuration
Status Code
OK. Storage configurations are listed.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
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.
No Sample Response
View the details of a Satellite storage template.
View the details of a Satellite storage template by name and version
GET /v2/storage/satellite/getStorageTemplate
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The name of the storage template. To list the storage templates that you have access to, use the GET
v2/storage/satellite/getStorageTemplatesAPI or runibmcloud sat storage template ls.The version of the storage template. To list the storage templates that you have access to, use the GET
v2/storage/satellite/getStorageTemplatesAPI or runibmcloud sat storage template ls.
Response
- vendor-storage-class-parameters
Status Code
OK. Storage template details are returned.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getStorageTemplatesAPI or runibmcloud sat storage template ls.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/getStorageTemplatesAPI or runibmcloud sat storage template ls.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/getStorageTemplatesAPI or runibmcloud sat storage template ls.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.
No Sample Response
View the change log details of Satellite storage templates.
View the change log details of all Satellite storage templates or a specific Satellite storage template by name.
GET /v2/storage/satellite/getStorageTemplateChangelog
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name 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/getStorageTemplatesAPI or runibmcloud sat storage template ls. To get change logs for all storage templates that you have access to, skip this parameter.
Response
Status Code
OK. Change log(s) of the storage template(s) is/are returned.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getStorageTemplatesAPI or runibmcloud sat storage template ls.Internal Server Error. Failed to fetch the changelog for the storage template. Note the incident ID and contact IBM Cloud support.
No Sample Response
List Satellite storage templates.
List Satellite storage templates.
GET /v2/storage/satellite/getStorageTemplates
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Response
Status Code
OK. Storage templates are listed.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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.
No Sample Response
Remove an assignment.
Remove an assignment with a given UUID.
DELETE /v2/storage/satellite/removeAssignment
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
ID of the assignment. To list the assignments that you have access to, use the GET
/v2/storage/satellite/getAssignmentsAPI or runibmcloud sat storage assignment ls.The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the
GET /v2/satellite/getControllersAPI or runibmcloud sat location ls.
Response
Status Code
OK. The assignment is removed.
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/getAssignmentsAPI or runibmcloud sat storage assignment ls.Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found. The specified assignment could not be found. To list the assignments that you have access to, use the GET
/v2/storage/satellite/getAssignmentsAPI or runibmcloud sat storage assignment ls.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.
No Sample Response
Delete a storage request
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.
DELETE /v2/storage/satellite/removeDesiredStorageConfig
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The ID of the storage request. To list storage requests, use the
/v2/satellite/getDesiredStorageConfigAPI.The ID of the cluster (
cluster) on which the storage request is placed on. To list storage requests, use the/v2/satellite/getDesiredStorageConfigAPI. To list the Satellite clusters you have access to, use the GET/v2/satellite/getClustersAPI or runibmcloud sat service ls --location=<location-name-or-ID>.
Response
ErrorResponse error response to end users
ErrorType error type
Status Code
OK. The storage configuration is removed.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
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.
No Sample Response
Remove a Satellite storage configuration.
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.
DELETE /v2/storage/satellite/removeStorageConfiguration
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The 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, runibmcloud sat config get --config=<storage-configuration-name>.The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the
GET /v2/satellite/getControllersAPI or runibmcloud sat location ls.Specify
trueto remove the storage configuration along with the associated assignments. If unspecified, the default value isfalse.
Response
Status Code
OK. The storage configuration is removed.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
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.
No Sample Response
Enable or disable automatic upgrades for an existing storage assignment(s).
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.
PATCH /v2/storage/satellite/setAssignmentAutoupgrade
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
The parameters must include:
- Storage configuration name or ID (
config). - Satellite Location (
controller). - Set the
autoUpgradeflag totrueto enable assignments for automatic upgrades. If unspecified, it is assumed to befalse. - Either set
Allto enable/disable automatic upgrades for all the assignments of the storage configuration or provide theUUIDsto enable/disable automatic upgrades for a set of assignments.
- assignment
Response
- assignment
Status Code
OK. The assignment(s) is/are enabled/disabled for automatic upgrades.
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/getStorageConfigurationsAPI or runibmcloud sat storage config ls. - Both the parameters
AllandUUIDsare provided. Both cannot be provided at the same time. - No assignment(s) provided to enable/disable automatic upgrade. Neither of the parameters
AllandUUIDsare provided. - The assignment uuid provided in
UUIDsparameter is invalid. To list the assignments that you have access to, use the GET/v2/storage/satellite/getAssignmentsByConfigAPI or runibmcloud sat storage assignment ls --config config.
- 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
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getStorageConfigurationsAPI or runibmcloud 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/getAssignmentsAPI or runibmcloud sat storage assignment ls.
- The specified config could not be found. To list the storage configurations that you have access to, use the GET
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.
No Sample Response
Create a storage request on a cluster
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.
POST /v2/storage/satellite/setDesiredStorageConfig
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
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:
- Required:
a. Volume type. Specify one of
file,blockorobject. b. Provider. Specify one of the supported providers of storage templates. For a list of supported providers or templates, seehttps://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. UseKfor kilobytes,Mfor megabytes,Gfor gigabytes,Tfor terabytes, orEfor exabytes. Example:100G. - Optional parameters.
a. Offering type. Specify either
sdsfor software-defined storage ornon-sds. b. Volume encryption at rest. This is a boolean value. Specifytrueorfalse. c. Volume availability. This is a boolean value. Specifytrueorfalse. d. Volume expansion. This is a boolean value. Specifytrueorfalse. e. Volume snapshot. This is a boolean value. Specifytrueorfalse. 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"}}
DesiredAttributes are various attributes associated with a particular storage request
Response
Status Code
OK. The storage request is created.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getClustersAPI or runibmcloud sat service ls --location=<location-name-or-ID>.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.
No Sample Response
Update an assignment.
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.
PATCH /v2/storage/satellite/updateAssignment
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
The parameters must include the UUID of the assignment (uuid) along with at least one of the following parameters to be updated:
- One or more cluster groups (
groups) on which you want to apply the configuration. To list the cluster groups that you have access to, runibmcloud sat group ls. - New name of the assignment (
name). - set the
updateConfigVersionflag totruefor updating an assignment to the latest available storage configuration version. If unspecified, it is assumed to befalse. To see if assignment upgrade is available, use the GET/v2/storage/satellite/getAssignmentAPI and look forisAssignmentUpgradeAvailablefield in response or runibmcloud sat storage assignment get --assignment UUIDand look forAssignment Upgrade Availablefield in response.
Response
Status Code
OK. The assignment is updated.
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/getAssignmentsAPI or runibmcloud 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
updateConfigVersionflag tofalseif 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).
- The uuid is missing or the specified uuid is invalid. To list the assignments that you have access to, use the GET
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getAssignmentsAPI or runibmcloud sat storage assignment ls. To list the Satellite cluster groups you have access to, runibmcloud sat group ls.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.
No Sample Response
Deprecated. To update a Satellite storage configuration, you can use /v2/storage/satellite/updateStorageConfigurationByController instead.
Update an existing Satellite storage configuration. Note that you cannot update Satellite storage configurations that are currently used in a Satellite storage assignment.
POST /v2/storage/satellite/updateStorageConfiguration
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
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.
- storage-class-parameters
- user-config-parameters
- user-secret-parameters
Response
ErrorResponse error response to end users
ErrorType error type
Status Code
OK. The storage configuration is updated.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
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.
No Sample Response
Update a Satellite storage configuration.
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.
POST /v2/storage/satellite/updateStorageConfigurationByController
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
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.
- storage-class-parameters
- user-config-parameters
- user-secret-parameters
Response
ErrorResponse error response to end users
ErrorType error type
Status Code
OK. The storage configuration is updated.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
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.
No Sample Response
Update a Satellite storage configuration to use the latest template revision.
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.
PATCH /v2/storage/satellite/updateStorageConfigurationRevision
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name or UUID of the storage configuration. To list the storage configurations that you have access to, run
ibmcloud sat storage config ls.The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the
GET /v2/satellite/getControllersAPI or runibmcloud sat location ls.Specify
trueorfalseto update assignment(s) of the specified storage configuration. The default value isfalse.
Response
ErrorResponse error response to end users
ErrorType error type
Status Code
OK. Updated storage configuration template to latest revision.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
Storage configuration template is already up to date with the latest revision.
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.
No Sample Response
Acknowledge the request to expand storage capacity.
Acknowledge the request to expand the storage capacity of an existing storage request.
PATCH /v2/storage/satellite/ackDesiredStorageConfigCapacity
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
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>.
Response
Status Code
OK. The storage request is created.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getClustersAPI or runibmcloud sat service ls --location=<location-name-or-ID>. To list storage requests, use the/v2/satellite/getDesiredStorageConfigAPI.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.
No Sample Response
Create an assignment using a Satellite storage configuration for the cluster group(s).
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.
POST /v2/storage/satellite/createAssignment
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Include following parameters to create an assignment:
- Name of the assignment (
name). - Storage configuration name or ID (
config). To list the storage configurations that you have access to, use the GET/v2/storage/satellite/getStorageConfigurationsAPI or runibmcloud sat storage config ls. - The name or ID of the Satellite location (
controller). To list the Satellite locations that you have access to, use the GET/v2/satellite/getControllersAPIor runibmcloud sat location ls. - 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, runibmcloud sat group ls. - Enable or disable automatic upgrades for the assignment (
autoUpgrade="true|false").
Response
Status Code
OK. An assignment using the storage configuration is created.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getStorageConfigurationsAPI or runibmcloud sat storage config ls. To list the Satellite cluster groups you have access to, runibmcloud sat group ls.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.
No Sample Response
Create an assignment using a Satellite storage configuration for a Satellite cluster or service cluster.
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.
POST /v2/storage/satellite/createAssignmentByCluster
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Include following parameters to create an assignment:
- Name of the assignment (
name). - 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/getStorageConfigurationsByControllerAPI or runibmcloud sat storage config ls --location LOCATION. - 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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION. - The name or ID of the Satellite location (
controller). To list the Satellite locations that you have access to, use the GET/v2/satellite/getControllersAPIor runibmcloud sat location ls. - Enable or disable automatic upgrades for the assignment (
autoUpgrade="true|false").
Response
Status Code
OK. An assignment using the storage configuration is created.
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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION.Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getStorageConfigurationsByControllerAPI or runibmcloud 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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, runibmcloud sat location ls.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.
No Sample Response
Deprecated. To create a Satellite storage configuration, you can use /v2/storage/satellite/createStorageConfigurationByController API instead.
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.
POST /v2/storage/satellite/createStorageConfiguration
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
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.
- storage-class-parameters
- user-config-parameters
- user-secret-parameters
Response
CreateConfigurationData - a single return struct
- addChannel
Status Code
OK. The storage configuration is created.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
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.
No Sample Response
Create a Satellite storage configuration
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.
POST /v2/storage/satellite/createStorageConfigurationByController
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
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.
- storage-class-parameters
- user-config-parameters
- user-secret-parameters
Response
CreateConfigurationData - a single return struct
- addChannel
Status Code
OK. The storage configuration is created.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
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.
No Sample Response
Expand the capacity of a storage request.
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.
PATCH /v2/storage/satellite/expandDesiredStorageConfigCapacity
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
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>.
Response
Status Code
OK. The storage request is created.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getClustersAPI or runibmcloud sat service ls --location=<location-name-or-ID>. To list storage requests, use the/v2/satellite/getDesiredStorageConfigAPI.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.
No Sample Response
List Satellite storage configurations assigned to a Satellite cluster or service cluster.
List Satellite storage configurations that are assigned to a Satellite cluster or service cluster.
GET /v2/storage/satellite/getAssignedStorageConfigs
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION.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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite.
Response
AppliedStorageConfig contains the details of an assigned storage config on a cluster A list of AppliedStorageConfig structs is the response for the GetAssignedStorageConfigs query
- config-attributes
- rollout-status
Status Code
OK. Assigned Satellite storage configurations are listed.
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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, runibmcloud sat location ls.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.
No Sample Response
View details of an assignment.
View details of an assignment by the assignment UUID.
GET /v2/storage/satellite/getAssignment
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The UUID of the assignment. To list the assignments that you have access to, use the GET
/v2/storage/satellite/getAssignmentsAPI or runibmcloud sat storage assignment ls.
Response
Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59
- configRevisionStatus
- owner
- rolloutStatus
Status Code
OK. Assignment details are returned.
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/getAssignmentsAPI or runibmcloud sat storage assignment ls.Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found. The specified assignment could not be found. To list the assignments that you have access to, use the GET
/v2/storage/satellite/getAssignmentsAPI or runibmcloud sat storage assignment ls.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.
No Sample Response
Deprecated. To view details of an assignment, you can use /v2/storage/satellite/getAssignment API instead.
View details of an assignment by the assignment name.
GET /v2/storage/satellite/getAssignmentByName
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The name of the assignment. To list the assignments that you have access to, use the GET
/v2/storage/satellite/getAssignmentsAPI or runibmcloud sat storage assignment ls.
Response
Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59
- configRevisionStatus
- owner
- rolloutStatus
Status Code
OK. Assignment details successfully fetched.
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/getAssignmentsAPI or runibmcloud sat storage assignment ls.Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found. The specified assignment could not be found. To list the assignments that you have access to, use the GET
/v2/storage/satellite/getAssignmentsAPI or runibmcloud sat storage assignment ls.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.
No Sample Response
List storage assignments in the IBM Cloud account.
List storage assignments that you have access to in the IBM Cloud account. Returned details include the assignment name, UUID, and creation timestamp.
GET /v2/storage/satellite/getAssignments
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Response
Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59
- configRevisionStatus
- owner
- rolloutStatus
Status Code
OK. Assignments are listed.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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.
No Sample Response
List storage assignments created for a Satellite cluster or service cluster.
List storage assignments created for a Satellite cluster or service cluster. Returned details include the assignment name, UUID, and creation timestamp.
GET /v2/storage/satellite/getAssignmentsByClusterID
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION.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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite.
Response
Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59
- configRevisionStatus
- owner
- rolloutStatus
Status Code
OK. Assignments are listed.
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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION.
- 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
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, runibmcloud sat location ls.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.
No Sample Response
List storage assignments by configuration name or UUID.
List storage assignments by configuration name or UUID. Returned details include the assignment name, UUID, and creation timestamp.
GET /v2/storage/satellite/getAssignmentsByConfig
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The name or ID of the Satellite storage configuration. To list the storage configurations that you have access to, use the GET
/v2/storage/satellite/getStorageConfigurationsAPI or runibmcloud sat storage config ls.
Response
Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59
- configRevisionStatus
- owner
- rolloutStatus
Status Code
OK. Assignments are listed.
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/getStorageConfigurationsAPI or runibmcloud sat storage config ls.Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getStorageConfigurationsAPI or runibmcloud sat storage config ls.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.
No Sample Response
List storage assignments in a Satellite location.
List storage assignments that you have access to in a Satellite location. Returned details include the assignment name, UUID, and creation timestamp.
GET /v2/storage/satellite/getAssignmentsByController
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The name or ID of the Satellite location to list assignments for. To list the Satellite locations that you have access to, run
ibmcloud sat location ls.
Response
Subscription contains the details of a subscription Razeedash-api link: https://github.com/razee-io/Razeedash-api/blob/master/app/apollo/schema/subscription.js#L40-L59
- configRevisionStatus
- owner
- rolloutStatus
Status Code
OK. Assignments are listed.
Bad Request. The controller is missing. To list the Satellite locations that you have access to, run
ibmcloud sat location ls.Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found. The specified location could not be found. To list the Satellite locations that you have access to, run
ibmcloud sat location ls.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.
No Sample Response
List and filter available storage classes from assigned Satellite storage configurations on a Satellite cluster or service cluster.
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.
GET /v2/storage/satellite/getAvailableStorageClasses
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The 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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION.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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite.Filter the available storage classes by volume type. The supported volume types are
file,blockandobject. If unspecified, available storage classes of all volume types are returned.Specify
trueorfalseto view only the available storage classes from software-defined storage (SDS) storage configurations. If unspecified, the default value istrue.
Response
AvailableStorageClasses contains a list of storage class names It is the response for GetAvailableStorageClasses query
Status Code
OK. Available storage classes are listed.
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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud 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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION. - The specified value is an invalid value for parameter
volumeType. Supported values forvolumeTypeparameter are:file, block, object. - The specified value is an invalid value for parameter
onlyShowSDS. Supported values foronlyShowSDSparameter are:true, false.
- 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
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getClustersAPI or runibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, runibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, runibmcloud sat location ls.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.
No Sample Response
List Storage requests on a cluster.
List the storage requests for a cluster in a Satellite location.
GET /v2/storage/satellite/getDesiredStorageConfig
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The 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/getClustersAPI or runibmcloud sat service ls --location=<location-name-or-ID>. The response body for each storage request contains the request specifications and the following fields:- The
assignmentfield. 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. - A
statusfield in theconfigsection 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 topending. If a storage configuration has been assigned to the cluster, the status is set toassigned. If the storage request is deleted, the status is set todeleted. - A
statusfield in thebackendsection. 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 topending. If the request is acknowledged by the location administrator, the status is set tocompleted.
- The
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/getClustersAPI or runibmcloud sat service ls --location=<location-name-or-ID>.
Response
GetDesiredStorageConfigResponse is the respose body for getDesiredStorageConfig API
StorageRequest defines a storage request
Status Code
OK. Storage requests are listed.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getClustersAPI or runibmcloud sat service ls --location=<location-name-or-ID>.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.
No Sample Response
View details of a Satellite storage configuration.
View the details of a Satellite storage configuration.
GET /v2/storage/satellite/getStorageConfiguration
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The name of the storage configuration. To list the storage configurations that you have access to, run
ibmcloud sat storage config ls.Specify
trueto include details of assignment(s) of the specified storage configuration. The default value isfalse.
Response
- is-user-secret-parameters-set
- storage-class-parameters
ConfigAttributes defines attributes related to storage configuration
ConfigSubscriptionInfo contains the details of subscription to be shows as part of a storage config get or list response
- user-config-parameters
- user-secret-parameters
Status Code
OK. Storage configuration details are returned.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
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.
No Sample Response
List Satellite storage configurations.
List the Satellite storage configurations that you have access to in a Satellite location or in the IBM Cloud account.
GET /v2/storage/satellite/getStorageConfigurations
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The name or ID of the 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
ListStorageConfigData is the response struct for the list storage configuration APIs i.e. getStorageConfigurations & getStorageConfigurationsByController
ConfigAttributes defines attributes related to storage configuration
Status Code
OK. Storage configurations are listed.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
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.
No Sample Response
List Satellite storage configurations in a Satellite location.
List the Satellite storage configurations that you have access to in a Satellite location.
GET /v2/storage/satellite/getStorageConfigurationsByController
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The name or ID of the Satellite location to list storage configurations for. To list the Satellite locations that you have access to, run
ibmcloud sat location ls.
Response
ListStorageConfigData is the response struct for the list storage configuration APIs i.e. getStorageConfigurations & getStorageConfigurationsByController
ConfigAttributes defines attributes related to storage configuration
Status Code
OK. Storage configurations are listed.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
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.
No Sample Response
View the details of a Satellite storage template.
View the details of a Satellite storage template by name and version
GET /v2/storage/satellite/getStorageTemplate
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The name of the storage template. To list the storage templates that you have access to, use the GET
v2/storage/satellite/getStorageTemplatesAPI or runibmcloud sat storage template ls.The version of the storage template. To list the storage templates that you have access to, use the GET
v2/storage/satellite/getStorageTemplatesAPI or runibmcloud sat storage template ls.
Response
- vendor-storage-class-parameters
Status Code
OK. Storage template details are returned.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getStorageTemplatesAPI or runibmcloud sat storage template ls.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/getStorageTemplatesAPI or runibmcloud sat storage template ls.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/getStorageTemplatesAPI or runibmcloud sat storage template ls.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.
No Sample Response
View the change log details of Satellite storage templates.
View the change log details of all Satellite storage templates or a specific Satellite storage template by name.
GET /v2/storage/satellite/getStorageTemplateChangelog
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name 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/getStorageTemplatesAPI or runibmcloud sat storage template ls. To get change logs for all storage templates that you have access to, skip this parameter.
Response
Status Code
OK. Change log(s) of the storage template(s) is/are returned.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getStorageTemplatesAPI or runibmcloud sat storage template ls.Internal Server Error. Failed to fetch the changelog for the storage template. Note the incident ID and contact IBM Cloud support.
No Sample Response
List Satellite storage templates.
List Satellite storage templates.
GET /v2/storage/satellite/getStorageTemplates
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Response
Status Code
OK. Storage templates are listed.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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.
No Sample Response
Remove an assignment.
Remove an assignment with a given UUID.
DELETE /v2/storage/satellite/removeAssignment
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
ID of the assignment. To list the assignments that you have access to, use the GET
/v2/storage/satellite/getAssignmentsAPI or runibmcloud sat storage assignment ls.The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the
GET /v2/satellite/getControllersAPI or runibmcloud sat location ls.
Response
Status Code
OK. The assignment is removed.
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/getAssignmentsAPI or runibmcloud sat storage assignment ls.Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found. The specified assignment could not be found. To list the assignments that you have access to, use the GET
/v2/storage/satellite/getAssignmentsAPI or runibmcloud sat storage assignment ls.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.
No Sample Response
Delete a storage request
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.
DELETE /v2/storage/satellite/removeDesiredStorageConfig
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The ID of the storage request. To list storage requests, use the
/v2/satellite/getDesiredStorageConfigAPI.The ID of the cluster (
cluster) on which the storage request is placed on. To list storage requests, use the/v2/satellite/getDesiredStorageConfigAPI. To list the Satellite clusters you have access to, use the GET/v2/satellite/getClustersAPI or runibmcloud sat service ls --location=<location-name-or-ID>.
Response
ErrorResponse error response to end users
ErrorType error type
Status Code
OK. The storage configuration is removed.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
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.
No Sample Response
Remove a Satellite storage configuration.
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.
DELETE /v2/storage/satellite/removeStorageConfiguration
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
Query Parameters
The 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, runibmcloud sat config get --config=<storage-configuration-name>.The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the
GET /v2/satellite/getControllersAPI or runibmcloud sat location ls.Specify
trueto remove the storage configuration along with the associated assignments. If unspecified, the default value isfalse.
Response
Status Code
OK. The storage configuration is removed.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
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.
No Sample Response
Enable or disable automatic upgrades for an existing storage assignment(s).
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.
PATCH /v2/storage/satellite/setAssignmentAutoupgrade
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
The parameters must include:
- Storage configuration name or ID (
config). - Satellite Location (
controller). - Set the
autoUpgradeflag totrueto enable assignments for automatic upgrades. If unspecified, it is assumed to befalse. - Either set
Allto enable/disable automatic upgrades for all the assignments of the storage configuration or provide theUUIDsto enable/disable automatic upgrades for a set of assignments.
- assignment
Response
- assignment
Status Code
OK. The assignment(s) is/are enabled/disabled for automatic upgrades.
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/getStorageConfigurationsAPI or runibmcloud sat storage config ls. - Both the parameters
AllandUUIDsare provided. Both cannot be provided at the same time. - No assignment(s) provided to enable/disable automatic upgrade. Neither of the parameters
AllandUUIDsare provided. - The assignment uuid provided in
UUIDsparameter is invalid. To list the assignments that you have access to, use the GET/v2/storage/satellite/getAssignmentsByConfigAPI or runibmcloud sat storage assignment ls --config config.
- 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
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getStorageConfigurationsAPI or runibmcloud 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/getAssignmentsAPI or runibmcloud sat storage assignment ls.
- The specified config could not be found. To list the storage configurations that you have access to, use the GET
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.
No Sample Response
Create a storage request on a cluster
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.
POST /v2/storage/satellite/setDesiredStorageConfig
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
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:
- Required:
a. Volume type. Specify one of
file,blockorobject. b. Provider. Specify one of the supported providers of storage templates. For a list of supported providers or templates, seehttps://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. UseKfor kilobytes,Mfor megabytes,Gfor gigabytes,Tfor terabytes, orEfor exabytes. Example:100G. - Optional parameters.
a. Offering type. Specify either
sdsfor software-defined storage ornon-sds. b. Volume encryption at rest. This is a boolean value. Specifytrueorfalse. c. Volume availability. This is a boolean value. Specifytrueorfalse. d. Volume expansion. This is a boolean value. Specifytrueorfalse. e. Volume snapshot. This is a boolean value. Specifytrueorfalse. 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"}}
DesiredAttributes are various attributes associated with a particular storage request
Response
Status Code
OK. The storage request is created.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getClustersAPI or runibmcloud sat service ls --location=<location-name-or-ID>.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.
No Sample Response
Update an assignment.
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.
PATCH /v2/storage/satellite/updateAssignment
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
The parameters must include the UUID of the assignment (uuid) along with at least one of the following parameters to be updated:
- One or more cluster groups (
groups) on which you want to apply the configuration. To list the cluster groups that you have access to, runibmcloud sat group ls. - New name of the assignment (
name). - set the
updateConfigVersionflag totruefor updating an assignment to the latest available storage configuration version. If unspecified, it is assumed to befalse. To see if assignment upgrade is available, use the GET/v2/storage/satellite/getAssignmentAPI and look forisAssignmentUpgradeAvailablefield in response or runibmcloud sat storage assignment get --assignment UUIDand look forAssignment Upgrade Availablefield in response.
Response
Status Code
OK. The assignment is updated.
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/getAssignmentsAPI or runibmcloud 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
updateConfigVersionflag tofalseif 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).
- The uuid is missing or the specified uuid is invalid. To list the assignments that you have access to, use the GET
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.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/getAssignmentsAPI or runibmcloud sat storage assignment ls. To list the Satellite cluster groups you have access to, runibmcloud sat group ls.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.
No Sample Response
Deprecated. To update a Satellite storage configuration, you can use /v2/storage/satellite/updateStorageConfigurationByController instead.
Update an existing Satellite storage configuration. Note that you cannot update Satellite storage configurations that are currently used in a Satellite storage assignment.
POST /v2/storage/satellite/updateStorageConfiguration
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
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.
- storage-class-parameters
- user-config-parameters
- user-secret-parameters
Response
ErrorResponse error response to end users
ErrorType error type
Status Code
OK. The storage configuration is updated.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
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.
No Sample Response
Update a Satellite storage configuration.
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.
POST /v2/storage/satellite/updateStorageConfigurationByController
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens
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.
- storage-class-parameters
- user-config-parameters
- user-secret-parameters
Response
ErrorResponse error response to end users
ErrorType error type
Status Code
OK. The storage configuration is updated.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
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.
No Sample Response
Update a Satellite storage configuration to use the latest template revision.
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.
PATCH /v2/storage/satellite/updateStorageConfigurationRevision
Request
Custom Headers
Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run
ibmcloud iam oauth-tokens.
Query Parameters
The name or UUID of the storage configuration. To list the storage configurations that you have access to, run
ibmcloud sat storage config ls.The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the
GET /v2/satellite/getControllersAPI or runibmcloud sat location ls.Specify
trueorfalseto update assignment(s) of the specified storage configuration. The default value isfalse.
Response
ErrorResponse error response to end users
ErrorType error type
Status Code
OK. Updated storage configuration template to latest revision.
Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run
ibmcloud iam oauth-tokensto retrieve your access tokens.Not found.
Storage configuration template is already up to date with the latest revision.
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.