IBM Cloud API Docs

Introduction

Last updated: 2023-09-28

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

Before you begin

Charges

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

For more information, see the following links:

Authentication

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

Authorization

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

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

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

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

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

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

IAM and Activity Tracker actions by API method

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

API endpoint

Use the following API endpoint for all API requests:

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

Versioning

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

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

Error handling

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

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

Methods

Get 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}/autoscale

Authorization

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

To call this endpoint, you must have the Viewer platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

An autoscaling configuration is returned.

  • cluster-alb-autoscale.get

Request

Custom Headers

  • Authorization
    Required*
    string

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

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • albID
    Required*
    string

    The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the GET /clusters/{idOrName} API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.

Response

Status Code

  • 200

    Ok. The autoscaling configuration for your ALB is returned.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

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

  • 404

    Not found. No autoscale configuration set for this cluster and ALB, or the specified cluster or ALB could not be found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}/autoscale

Authorization

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

You must have the Editor platform role for the Kubernetes Service in IAM to call this endpoint.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

An autoscaling configuration is created or updated.

  • cluster-alb-autoscale.set

Request

Custom Headers

  • Authorization
    Required*
    string

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

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • albID
    Required*
    string

    The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the GET /clusters/{idOrName} API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.

Request Body

Required*
AutoscaleDetails

New autoscale configuration to be set.

Response

Status Code

  • 200

    Ok. The provided autoscaling configuration for your ALB is set.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

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

  • 404

    Not found. The the specified cluster or ALB could not be found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}/autoscale

Authorization

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

You must have the Editor platform role for the Kubernetes Service in IAM to call this endpoint.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

An autoscaling configuration is deleted.

  • cluster-alb-autoscale.unset

Request

Custom Headers

  • Authorization
    Required*
    string

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

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • albID
    Required*
    string

    The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the GET /clusters/{idOrName} API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.

Response

Status Code

  • 204

    Ok. Autoscale config was unset successfully.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

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

  • 404

    Not found. No autoscaling configuration set for this cluster and ALB, or the specified cluster or ALB could not be found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Create an Ingress domain for a cluster.

Create an Ingress domain for a cluster.

POST /ingress/v2/dns/createDomain

Request

Custom Headers

  • Authorization
    Required*
    string

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

Request Body

Required*
CreateDomainReq

Input parameter to create a domain.

Response

Response Body

ExtendedNlbVPCConfig

ExtendedNlbVPCConfig is the response body for the get v2 vpc apis

Status Code

  • 201

    Created. The domain is created.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Delete external domain provider credential.

Delete the registered external provider credential for a cluster.

POST /ingress/v2/dns/deleteCredential

Request

Custom Headers

  • Authorization
    Required*
    string

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

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Status Code

  • 204

    No Content. The credential was successfully fetched.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

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

Request Body

Required*
DeleteDomainReq

Input parameter to delete a domain.

Response

Status Code

  • 200

    Ok. The domain is deleted.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Get external domain provider credential metadata.

Get metadata for the registered external provider credential for a cluster.

GET /ingress/v2/dns/getCredential

Request

Custom Headers

  • Authorization
    Required*
    string

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

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

GetCredentials

GetCredentials is the return model for a get on a credential

Status Code

  • 200

    Ok. The credential was successfully fetched.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

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

Request Body

Required*
ReplaceDefaultSubdomainReq

Input parameter to replace default domain.

Response

Status Code

  • 200

    Ok. The default domain is replaced.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Set external domain provider credential.

Register a credential for external domain provider for use in ingress domain commands.

POST /ingress/v2/dns/setCredential

Request

Custom Headers

  • Authorization
    Required*
    string

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

Request Body

Required*
CreateCredentialReq

Input parameter to register an external domain provider credential.

Response

Status Code

  • 201

    Created. The credential was successfully registered.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Update an Ingress domain for a cluster.

Update an Ingress domain with the specified IPs or hostnames.

POST /ingress/v2/dns/updateDomain

Request

Custom Headers

  • Authorization
    Required*
    string

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

Request Body

Required*
UpdateDomainReq

Input parameter to update a domain.

Response

Status Code

  • 200

    Ok. The domain is updated.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

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

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster.

  • type
    Required*
    string

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

Response

Response Body

LBConfig

LBConfig struct models load balancer configuration

Status Code

  • 200

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

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

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

  • 404

    Not found. The specified cluster could not be found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Update the configuration of load balancers for Ingress ALBs.

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

Available features:

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

Request

Custom Headers

  • Authorization
    Required*
    string

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

Request Body

Required*
LBConfig

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

Response

Status Code

  • 202

    Load-balancer configuration submitted and update started.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

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

  • 404

    Not found. The specified cluster could not be found.

  • 423

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

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

POST /ingress/v2/secret/addField

Request

Custom Headers

  • Authorization
    Required*
    string

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

Request Body

Required*
UpdateConfig

Input parameter to add a secret field.

Response

Response Body

Secret

Secret struct holding details for a single secret

Status Code

  • 201

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

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

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

POST /ingress/v2/secret/createSecret

Request

Custom Headers

  • Authorization
    Required*
    string

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

Request Body

Required*
CreateConfig

Input parameter to add a secret.

Response

Response Body

Secret

Secret struct holding details for a single secret

Status Code

  • 201

    Created. The secret was successfully created in the cluster.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

Delete an Ingress secret from the cluster.

Delete an Ingress secret from the cluster.

POST /ingress/v2/secret/deleteSecret

Request

Custom Headers

  • Authorization
    Required*
    string

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

Request Body

Required*
DeleteConfig

Input parameter to add a secret.

Response

Status Code

  • 204

    Deleted. The secret was successfully deleted from the cluster.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

View Ingress secret details.

View Ingress secret details.

GET /ingress/v2/secret/getSecret

Request

Custom Headers

  • Authorization
    Required*
    string

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

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • name
    Required*
    string

    The name of the secret that you want information about. To list the secrets that you have access to, use the GET /ingress/v2/secret/getSecrets API or run ibmcloud ks ingress secret ls.

  • namespace
    Required*
    string

    The namespace of the secret that you want information about. To list the secrets that you have access to, use the GET /ingress/v2/secret/getSecrets API or run ibmcloud ks ingress secret ls.

Response

Response Body

Secret

Secret struct holding details for a single secret

Status Code

  • 200

    Ok. Detailed information about the secret is returned.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View Ingress secrets for a cluster.

View Ingress secrets for a cluster.

GET /ingress/v2/secret/getSecrets

Request

Custom Headers

  • Authorization
    Required*
    string

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

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • showDeleted
    string

    To view previously deleted secrets, pass true.

Response

Response Body

Secret[]

Secrets struct for a secret array

Status Code

  • 200

    Ok. The list of available Ingress secrets is returned.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

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

POST /ingress/v2/secret/removeField

Request

Custom Headers

  • Authorization
    Required*
    string

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

Request Body

Required*
UpdateConfig

Remove input parameter to remove a secret field.

Response

Response Body

Secret

Secret struct holding details for a single secret

Status Code

  • 200

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

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

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

POST /ingress/v2/secret/updateSecret

Request

Custom Headers

  • Authorization
    Required*
    string

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

Request Body

Required*
UpdateConfig

Input parameter to add a secret.

Response

Response Body

Secret

Secret struct holding details for a single secret

Status Code

  • 201

    Created. The secret was successfully created in the cluster.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

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

GET /ingress/v2/secret/getInstance

Request

Custom Headers

  • Authorization
    Required*
    string

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

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • name
    Required*
    string

    The name of the instance that you want information about. To list the instances that you have access to, use the GET /ingress/v2/secret/getInstances API or run ibmcloud ks ingress secret instance ls.

Response

Response Body

Instance

Instance struct holding details for a single instance

Status Code

  • 200

    Ok. Detailed information about the secret is returned.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View IBM Cloud Secrets Manager instances registered to the cluster.

View IBM Cloud Secrets Manager instances registered to the cluster.

GET /ingress/v2/secret/getInstances

Request

Custom Headers

  • Authorization
    Required*
    string

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

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • showDeleted
    string

    To view previously deleted instances, pass true.

Response

Response Body

Instance[]

Instances struct for a secret array

Status Code

  • 200

    Ok. The list of available Ingress secrets is returned.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Register an IBM Cloud Secrets Manager instance to the cluster.

Register an IBM Cloud Secrets Manager instance to the cluster.

POST /ingress/v2/secret/registerInstance

Request

Custom Headers

  • Authorization
    Required*
    string

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

Request Body

Required*
RegisterConfig

Input parameter to register an instance.

Response

Response Body

Instance

Instance struct holding details for a single instance

Status Code

  • 200

    Created. The instance was successfully registered to the cluster.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

Unregister an IBM Cloud Secrets Manager instance from the cluster.

Unregister an IBM Cloud Secrets Manager instance from the cluster.

POST /ingress/v2/secret/unregisterInstance

Request

Custom Headers

  • Authorization
    Required*
    string

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

Request Body

Required*
DeleteConfig

Input parameter to unregister an instance.

Response

Status Code

  • 200

    Deleted. The secret was successfully deleted from the cluster.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

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

POST /ingress/v2/secret/updateInstance

Request

Custom Headers

  • Authorization
    Required*
    string

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

Request Body

Required*
UpdateConfig

Input parameter to update instance registration.

Response

Status Code

  • 200

    Update. The instance was successfully updated.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified instance could not be found. To list the registered instances that you have access to, use the GET /v2/secret/getInstances API or run ibmcloud ks ingress secret instance ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

GetOauthAccessType

Perform Oauth access type get Operations

GET /network/v2/oauth-access-type/{idOrName}

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Get the OAuth access type for a cluster.

  • oauth-access-type.get

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

OauthAccessTypeJSON

OauthAccessTypeJSON for request and response

Status Code

  • 200

    Ok. The OAuth access type for the specified cluster is returned.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

SetOauthAccessType

Set the OAuth access type for a cluster

POST /network/v2/oauth-access-type/{idOrName}/set

Authorization

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

To get the action, the user must have the Editor platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

A cluster's OAuth access type is updated or configured

  • oauth-access-type.set

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*
OauthAccessTypeJSON

Specify the OAuth access type that you want to use. Accepted values are vpegw or legacy.

Response

Status Code

  • 202

    Accepted. The request to set the OAuth access type was successful.

  • 400

    The OAuth access type you specified is not supported.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the Satellite cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the Satellite cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

SatelliteACLResponse

SatelliteACLResponse response for GET request

Status Code

  • 200

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

  • 400

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

  • 401

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

  • 404

    Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Disable the subnet allowlist 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

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the Satellite cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the Satellite cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Status Code

  • 202

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

  • 401

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

  • 404

    Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

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

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

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the Satellite cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*
csePatchACL

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

Response

Status Code

  • 201

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

  • 204

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

  • 401

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

  • 404

    Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Enable the subnet allowlist for a Satellite cluster's service endpoint.

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

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

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the Satellite cruiser. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Status Code

  • 202

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

  • 400

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

  • 401

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

  • 404

    Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Remove subnets from a Satellite cluster's service endpoint allowlist.

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

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

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the Satellite cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the Satellite cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*
csePatchACL

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

Response

Status Code

  • 202

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

  • 204

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

  • 400

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

  • 401

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

  • 404

    Not found. The specified Satellite cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

ACLResponse

ACLResponse response for GET request

Status Code

  • 200

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

  • 400

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

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Disable the subnet allowlist 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

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Status Code

  • 202

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

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

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

PATCH /v1/acl/{idOrName}/add

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*
csePatchACL

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

Response

Status Code

  • 201

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

  • 204

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

  • 400

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

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Enable a subnet allowlist for a cluster's private service endpoint.

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

POST /v1/acl/{idOrName}/enable

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Status Code

  • 202

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

  • 400

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

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Remove subnets from a cluster's private service endpoint allowlist.

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

PATCH /v1/acl/{idOrName}/rm

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*
csePatchACL

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

Response

Status Code

  • 202

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

  • 204

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

  • 400

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

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

securityGroupsOperation

Perform Security Group Operations

POST /network/v2/security-group

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token.

Request Body

Required*
SecurityGroupRequest

Security group operation. Currently supported operations are reset, sync.

Response

Status Code

  • 202

    Accepted. The request to security group operation was successfully processed.

  • 400

    Not found. The specified security group could not be found. To list all security groups you have access to, run ibmcloud is security-groups.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

List all security groups attached to the cluster.

GET /network/v2/security-group/getSecurityGroups

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

  • type
    string

    Filter security groups by type. Specify cluster, worker, vpc, vpegw, or lbaas.

  • shared
    string

    Specify true to return the security groups that are shared across the VPC. Or, specify false to return only the cluster specific security groups.

  • userProvided
    string

    Specify true to return the security groups created by user. Specify false to return only the default cluster security groups.

Response

Response Body

GetSecurityGroupsResponse[]

GetSecurityGroupsResponse defines a response when getting list of security groups that are attached to the cluster

Status Code

  • 200

    ok. A list of Security Groups attached to the cluster is returned.

  • 400

    Bad request. The query parameters are either incomplete or in the wrong format.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

List available add-ons that you can enable in a cluster.

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

GET /v1/addons

Authorization

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

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

AddonCommon[]

AddonCommon represents common properties of an addon

Status Code

  • 200

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

List configuration values for your IBM Cloud account.

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

GET /v1/config

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

BluemixConfig

Status Code

  • 200

    Success

No Sample Response

This method does not specify any sample responses.

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

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

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

Authorization

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

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

Path Parameters

  • datacenter
    Required*
    string

    The zone ID where you want to list available machine types. To list available zones, run ibmcloud ks zone ls or use the GET /v1/datacenters API.

Response

Response Body

MachineType[]

MachineTypes a type that returns a sorted array of machine types

Status Code

  • 200

    Success

  • 400

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

Deprecated: List available Kubernetes versions.

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

GET /v1/kube-versions

Authorization

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

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

KubeVersion[]

KubeVersion the kubernetes version

Status Code

  • 200

    Success. A list of available BOM versions is returned.

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

List available locations.

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

GET /v1/locations

Authorization

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

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

IKSLocation[]

IKSLocation properties

Status Code

  • 200

    Success

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

View the current user messages.

View the current user messages.

GET /v1/messages

Authorization

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

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

MessageResponse[]

MessageResponse is a user message returned from the API

Status Code

  • 200

    Success

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

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

GET /v1/prodconfig

Authorization

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

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

ProductConfig

ProductConfig properties

Status Code

  • 200

    Success

No Sample Response

This method does not specify any sample responses.

Deprecated: List available Kubernetes Service regions.

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

GET /v1/regions

Authorization

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

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

Regions

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

Status Code

  • 200

    Success

  • 404

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

No Sample Response

This method does not specify any sample responses.

List available IBM Cloud Kubernetes Service versions.

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

GET /v1/versions

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

object

Status Code

  • 200

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

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

List available zones (data centers).

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

GET /v1/zones

Authorization

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

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

Query Parameters

  • showFlavors
    string

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

  • location
    string

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

Response

Response Body

ZoneV1[]

Zone properties

Status Code

  • 200

    Success. A list of available zones is returned.

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

View the current user messages.

View the current user messages.

GET /v2/getMessages

Authorization

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

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

MessageResponse[]

MessageResponse is a user message returned from the API

Status Code

  • 200

    Success

  • 500

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

No Sample Response

This method does not specify any sample responses.

Enable an existing ALB in a cluster.

Enable a public or private ALB in your standard cluster.

POST /v1/alb/albs

Request

Custom Headers

  • Authorization
    Required*
    string

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

Request Body

Required*
ALBConfig

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

Response

Status Code

  • 201

    Enabled. The ALB for the cluster was successfully enabled.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

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

  • 404

    Not found. The specified cluster or ALB could not be found. To list the clusters that you have access to, run ibmcloud ks cluster ls. To list the ALBs available in a cluster, use the GET /clusters/{idOrName} API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View details of an ALB.

View detailed information for an ALB in a cluster.

GET /v1/alb/albs/{albID}

Request

Custom Headers

  • Authorization
    Required*
    string

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

Path Parameters

  • albID
    Required*
    string

    The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the GET /clusters/{idOrName} API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.

Response

Response Body

ALBConfig

ALBConfig config for alb configuration

Status Code

  • 200

    Ok. Details for the specified ALB are returned.

  • 401

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

  • 404

    Not found. The specified cluster or ALB could not be found. To list the clusters that you have access to, run ibmcloud ks cluster ls. To list the ALBs available in a cluster, use the GET /clusters/{idOrName} API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Disable 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

  • Authorization
    Required*
    string

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

Path Parameters

  • albID
    Required*
    string

    The ID of the ALB that you want to disable. To list the IDs for the ALBs in a cluster, use the GET /v1/alb/clusters/{idOrName} API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.

Response

Status Code

  • 204

    Disabled. The ALB for the cluster was successfully disabled.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified cluster or ALB could not be found. To list the clusters that you have access to, run ibmcloud ks cluster ls. To list the ALBs available in a cluster, use the GET /clusters/{idOrName} API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.

  • 500

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

No Sample Response

This method does not specify any sample responses.

List all 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

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster that you want to see ALB information for. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Response

Response Body

ClusterALB[]

ClusterALB alb related information for vpc cluster

Status Code

  • 200

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

  • 401

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

  • 404

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

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

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

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Status Code

  • 200

    Ok. The update has been requested.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Check if automatic updates for Ingress ALBs are enabled in a cluster.

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

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

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

UpdatePolicy

Status Code

  • 200

    Ok. The current update policy.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

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

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

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*
UpdatePolicy

The new update policy configuration.

Response

Status Code

  • 204

    Ok. The ALB update policy has been changed.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Create a 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

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster that you want to see ALB information for. To list the clusters that you have access to, run ibmcloud ks cluster ls.

  • zoneId
    Required*
    string

    The zone in which you want to create an ALB. To see the zones where you can create an ALB, run ibmcloud ks cluster-get --cluster <cluster_name_or_ID> and look for the Worker Zones field in the output.

Request Body

Required*
ALB

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

Response

Response Body

AlbCreateResp

AlbCreateResp used to send back the albid on a create request

Status Code

  • 201

    The ALB was successfully created.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

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

  • 404

    Not found. The specified cluster or zone could not be found. To list the clusters that you have access to, run ibmcloud ks cluster ls. To list the zones available in a cluster, use the GET /v1/clusters/{idOrName} API or run ibmcloud ks cluster-get --cluster <cluster_name_or_ID>.

  • 500

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

No Sample Response

This method does not specify any sample responses.

List the clusters that you have access to.

List the clusters that you have access to.

GET /v1/clusters

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Clusters are listed.

  • containers-kubernetes.cluster.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group to list clusters for. To list available resource groups, run ibmcloud resource groups. If you don't include this header, all the clusters in the account that you have access to are listed.

Query Parameters

  • location
    string

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

  • showResources
    string

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

Response

Response Body

Cluster[]

Cluster properties

Status Code

  • 200

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

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

Create a cluster.

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

POST /v1/clusters

Authorization

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

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

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

  • containers-kubernetes.cluster.create

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Refresh-Token
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use the POST /v1/credentials API before this request.

  • X-Auth-Resource-Group
    string

    The ID of the resource group 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.

Request Body

Required*
ClusterConfig

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

Response

Response Body

ClusterCreateResponse

ClusterCreateResponse is returned during a successful create cluster command

Status Code

  • 201

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

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 409

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

View details for a cluster.

View detailed information for a cluster.

GET /v1/clusters/{idOrName}

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Details for a cluster are returned.

  • containers-kubernetes.cluster.get

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster that you want information about. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Query Parameters

  • showResources
    string

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

Response

Response Body

Cluster

Cluster properties

Status Code

  • 200

    Ok. Detailed information about the cluster is returned.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Update the version of the Kubernetes cluster master node.

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

PUT /v1/clusters/{idOrName}

Authorization

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

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A cluster master update is requested.

  • containers-kubernetes.cluster-master.update

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*
UpdateMasterCommand

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

Response

Status Code

  • 204

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

  • 401

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

  • 403

    Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 409

    Conflict. The specified value is already set on the cluster. To list the clusters properties, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Delete a cluster.

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

DELETE /v1/clusters/{idOrName}

Authorization

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

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

A cluster is deleted.

  • containers-kubernetes.cluster.delete

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster that you want to remove. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Query Parameters

  • deleteResources
    string

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

  • skipPermissionsPrecheck
    string

    To skip checking for infrastructure permissions before completing this action, pass 'true'. Note that if you do not have the correct infrastructure permissions, this action might only partially succeed.

Response

Status Code

  • 204

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

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View details of the add-ons that are enabled in a cluster.

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

GET /v1/clusters/{idOrName}/addons

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Cluster add-ons are listed.

  • containers-kubernetes.cluster-addon.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group of the cluster, use the GET /v1/clusters/{idOrName} API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

ClusterAddon[]

ClusterAddon represents one add on

Status Code

  • 200

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

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

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

PATCH /v1/clusters/{idOrName}/addons

Authorization

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

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing events, depending on any listed conditions.

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

  • containers-kubernetes.cluster-addon.enable

    A cluster add-on is enabled. Generated if enable is passed for the addonRequest parameter.

  • containers-kubernetes.cluster-addon.disable

    A cluster add-on is disabled. Generated if disable is passed for the addonRequest parameter.

  • containers-kubernetes.cluster-addon.update

    A cluster add-on is updated. Generated if update is passed for the addonRequest parameter.

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group of the cluster, use the GET /v1/clusters/{idOrName} API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*
AddonRequest

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

Response

Response Body

AddonResponse

AddonResponse represents an addon response

Status Code

  • 200

    OK. The add-on changes have been processed.

  • 400

    Bad request. The input parameters in the request body are not correct. Be sure to include all of the required parameters in your request in the correct JSON format.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 409

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

Get the cluster-specific configuration and certificates.

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

GET /v1/clusters/{idOrName}/config

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

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

  • containers-kubernetes.cluster.config

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Refresh-Token
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster for which you want to download the Kubernetes configuration file and certificates. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Query Parameters

  • sub
    string

    The format of the user identity to use in the Kubernetes configuration and policies. Must match the IAM provided user email, up to letter case.

  • format
    string

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

  • createNetworkConfig
    boolean

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

  • skipRBAC
    boolean

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

Response

Status Code

  • 200

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

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Create 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}/kms

Authorization

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

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

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

  • containers-kubernetes.cluster-service.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group of the cluster, use the GET /v1/clusters/{idOrName} API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*
KeyProtectData

Input parameters to create the Key Protect config for your cluster. The user specified URL parameter is ignored, because it is fetched from Ghost.

Response

Status Code

  • 201

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

  • 400

    Bad request. The input parameters in the request body are not correct. Be sure to include all of the required parameters in your request in the correct JSON format.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 409

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

Refresh the Kubernetes master.

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

PUT /v1/clusters/{idOrName}/masters

Authorization

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

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A cluster master refresh is requested.

  • containers-kubernetes.cluster-master.refresh

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster that you want to interact with. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

MasterAPIServer

The master state. Currently, refresh is supported.

Response

Status Code

  • 204

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

  • 400

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

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

List the IBM Cloud services bound to a cluster across all namespaces.

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

GET /v1/clusters/{idOrName}/services

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

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

  • containers-kubernetes.cluster-service.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster where you want to list bound IBM Cloud services. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

BoundService[]

BoundService properties

Status Code

  • 200

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

  • 401

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

  • 404

    Not found. The specified cluster ID or name could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Bind an IBM Cloud service to a cluster.

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

POST /v1/clusters/{idOrName}/services

Authorization

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

To get the action, the user must have the Editor platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

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

  • containers-kubernetes.cluster-service.bind

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster where you want to bind your service. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*
ServiceBindRequest

The ID of the IBM Cloud service instance that you want to bind. To find the ID of the service instance, use the GET /v1/clusters/{idOrName}/services API or run {[bxcs]} cluster-services <cluster_name_or_ID>.

Response

Response Body

ServiceBindResponse

ServiceBindResponse is the response format for a service bind request

Status Code

  • 201

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

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

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

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

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

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

  • containers-kubernetes.cluster-service.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster where you want to list bound IBM Cloud services. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • namespace
    Required*
    string

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

Response

Response Body

BoundService[]

BoundService properties

Status Code

  • 200

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

  • 401

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

  • 404

    Not found. The specified Kubernetes namespace or cluster ID/name could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To view available Kubernetes namespaces, run kubectl get namespaces.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Unbind an IBM Cloud service from a cluster.

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

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

Authorization

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

To get the action, the user must have the Editor platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

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

  • containers-kubernetes.cluster-service.unbind

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster where you want to unbind your IBM Cloud service instance. To list bound IBM Cloud services and their namespaces, use the GET /v1/clusters/{nameOrId}/services API or run ibmcloud ks cluster service ls --cluster <cluster_name_or_ID>.

  • namespace
    Required*
    string

    The Kubernetes namespace where your IBM Cloud service was bound to. To list bound IBM Cloud services and their namespaces, use the GET /v1/clusters/{nameOrId}/services API or run ibmcloud ks cluster service ls --cluster <cluster_name_or_ID>.

  • serviceInstanceId
    Required*
    string

    The name or ID of the IBM Cloud service instance that was bound to your cluster. To list bound IBM Cloud services and their namespaces, use the GET /v1/clusters/{nameOrId}/services API or run ibmcloud ks cluster service ls --cluster <cluster_name_or_ID>.

Response

Status Code

  • 204

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

  • 401

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

  • 404

    Not found. The specified cluster, IBM Cloud service instance, or namespace could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list bound IBM Cloud services and their namespaces, use the GET /v1/clusters/{nameOrId}/services API or run ibmcloud ks cluster service ls --cluster <cluster_name_or_ID>.

  • 500

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

No Sample Response

This method does not specify any sample responses.

List classic subnets that are bound to a cluster.

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

GET /v1/clusters/{idOrName}/subnets

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The subnets for a cluster are listed.

  • containers-kubernetes.cluster-subnet.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

VlanConfigField[]

VlanConfigField represents a VLAN config for a portable IP, including subnet, zone, and region info

Status Code

  • 200

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

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Add an IBM Cloud classic infrastructure subnet to a cluster.

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

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

Authorization

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

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

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

  • containers-kubernetes.subnet.add

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Refresh-Token
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use the POST /v1/credentials API before this request.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster that you want to make an existing subnet available to. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • subnetId
    Required*
    string

    The ID of the subnet in your IBM Cloud infrastructure account that you want to add to your cluster. To list available subnets, run ibmcloud ks subnets.

Response

Status Code

  • 204

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

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Detach a public or private portable subnet from a cluster.

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

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

Authorization

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

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

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

  • containers-kubernetes.cluster-subnet.detach

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster that you want to remove the subnet from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • subnetId
    Required*
    string

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

Response

Status Code

  • 204

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

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

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

GET /v1/clusters/{idOrName}/usersubnets

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

User-managed subnets for a cluster are listed.

  • containers-kubernetes.cluster-user-subnet.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

VlanConfigField[]

VlanConfigField represents a VLAN config for a portable IP, including subnet, zone, and region info

Status Code

  • 200

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

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Add an existing user-managed subnet to a cluster.

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

POST /v1/clusters/{idOrName}/usersubnets

Authorization

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

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A user-managed subnet is added to the cluster.

  • containers-kubernetes.cluster-user-subnet.add

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Refresh-Token
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use the POST /v1/credentials API before this request.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster that you want to make your user-managed subnet available to. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*
UserSubnet

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

Response

Status Code

  • 204

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

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Remove a user-managed subnet from a cluster.

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

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

Authorization

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

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A user-managed subnet is removed from the cluster.

  • containers-kubernetes.vlan.delete

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster that you want to remove the user-managed subnet from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • subnetId
    Required*
    string

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

  • vlanId
    Required*
    string

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

Response

Status Code

  • 204

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

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Create an IBM Cloud classic infrastructure subnet and add it to an existing cluster.

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

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

Authorization

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

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

A subnet is created.

  • containers-kubernetes.subnet.create

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Refresh-Token
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use the POST /v1/credentials API before this request.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster for which you want to make an existing subnet from your IBM Cloud infrastructure account available. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • vlanId
    Required*
    string

    The VLAN in which to create the subnet. To list available VLANs, use the GET /v1/datacenters/{datacenter}/vlans API or run ibmcloud ks vlan ls <zone>.

Query Parameters

  • size
    string

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

Response

Status Code

  • 204

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

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

List all webhooks for a cluster.

List all webhooks for a Kubernetes cluster.

GET /v1/clusters/{idOrName}/webhooks

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

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

  • containers-kubernetes.cluster-webhook.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster for which you want to list available webhooks. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

ClusterWebhook[]

ClusterWebhook webhook info

Status Code

  • 200

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

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Add a webhook to a cluster.

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

POST /v1/clusters/{idOrName}/webhooks

Authorization

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

To get the action, the user must have the Editor platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

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

  • containers-kubernetes.cluster-webhook.create

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster that you want to add a webhook to. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*
ClusterWebhook

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

Response

Status Code

  • 201

    Created. The webhook was successfully added to the cluster.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

List the worker pools in a cluster.

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

GET /v1/clusters/{idOrName}/workerpools

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The worker pools for a cluster are listed.

  • containers-kubernetes.cluster-worker-pool.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

WorkerPoolResponse[]

WorkerPoolResponse provides worker pool data

Status Code

  • 200

    OK. The list of worker pools was successfully retrieved.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list all the clusters, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}/workerpools

Authorization

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

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A worker pool is created in the cluster.

  • containers-kubernetes.cluster-worker-pool.create

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Refresh-Token
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use the POST /v1/credentials API before this request.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*
WorkerPoolRequest

The

Response

Response Body

WorkerPoolResponse

WorkerPoolResponse provides worker pool data

Status Code

  • 201

    Created. The worker pool was successfully created in for the specified cluster.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 409

    Conflict. A worker pool create may already be in progress for the provided cluster. Please wait a few minutes and try again.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View details for a worker pool.

View detailed information for a worker pool.

GET /v1/clusters/{idOrName}/workerpools/{poolidOrName}

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The details of a worker pool in the cluster are returned.

  • containers-kubernetes.cluster-worker-pool.get

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • poolidOrName
    Required*
    string

    The ID of the worker pool. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.

Response

Response Body

WorkerPoolResponse

WorkerPoolResponse provides worker pool data

Status Code

  • 200

    Ok. Detailed information about the worker pool is returned.

  • 401

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

  • 404

    Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls mycluster.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}

Authorization

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

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A worker pool is deleted from the cluster.

  • containers-kubernetes.cluster-worker-pool.delete

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • poolidOrName
    Required*
    string

    The ID of the worker pool. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.

Response

Status Code

  • 204

    OK. The request to remove your worker pool was successfully received.

  • 401

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

  • 404

    Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls mycluster.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}

Authorization

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

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing 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.rebalance

    A worker pool is rebalanced.

  • containers-kubernetes.cluster-worker-pool.resize

    A worker pool is resized, to add or decrease the number of worker nodes in the pool.

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • poolidOrName
    Required*
    string

    The ID of the worker pool. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.

Request Body

Required*
WorkerPoolPatchRequest

You can change the number of worker nodes by resizing or rebalancing the worker pool. To resize, set parameters "state" to "resizing" and "sizePerZone" to the number of worker nodes that you want in each zone. You can also note why you resize the worker pool in the "reasonForResize" string parameter. To rebalance, set parameter "state" to "rebalancing". Note that rebalancing does not change the size per zone of the worker pool. To apply a custom label to the worker pool, set the "state" field to "labels" and fill in the "labels" section with your label key-value pairs. When you apply a label, all existing custom labels are replaced. If you have existing custom labels that you want to keep, include them in your request. To remove a custom label, set the "state" field to "labels" and in the "labels" section, include the same "key" field, but leave the value field blank "". Note that you must not edit the system-provided labels that that come with the worker pool and worker nodes by default, or you might experience unexpected results.

Response

Status Code

  • 202

    OK. The request to resize your worker pool was successfully processed.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

    Forbidden. The request will not be permitted.

  • 404

    Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}/zones

Authorization

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

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A zone is added to a worker pool.

  • containers-kubernetes.cluster-worker-pool-zone.create

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • poolidOrName
    Required*
    string

    The ID of the worker pool. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.

Request Body

Required*
WorkerPoolZone

Input parameters to add zones to the worker pool.

Response

Status Code

  • 201

    OK. The requested zone has been added to the worker pool.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls mycluster.

  • 409

    Conflict. The provided zone already exists in the worker pool.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}

Authorization

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

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A zone is deleted from a worker pool.

  • containers-kubernetes.cluster-worker-pool-zone.delete

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • poolidOrName
    Required*
    string

    The ID of the worker pool. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.

  • zoneid
    Required*
    string

    The ID of the zone that you want to remove from the worker pool. To list all worker pools for a cluster, use the GET /v1/zones API or run ibmcloud ks zone ls.

Response

Status Code

  • 202

    OK. The request to remove the zone from your worker pool was successfully submitted.

  • 401

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

  • 403

    Forbidden. The request will not be permitted.

  • 404

    Not found. The specified worker pool or zone could not be found. To list all worker pool zones, use the GET /v1/clusters/{idOrName}/workerpools/{poolIdOrName}/zones API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Update the network configuration details, such as VLANs, for a zone in the worker pool.

PATCH /v1/clusters/{idOrName}/workerpools/{poolidOrName}/zones/{zoneid}

Authorization

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

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

The networking data, such as public and private VLAN data, is added for a zone that the worker pool spans.

  • containers-kubernetes.cluster-worker-pool-zone-network.add

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • poolidOrName
    Required*
    string

    The ID of the worker pool. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.

  • zoneid
    Required*
    string

    The ID of the worker pool zone. To list all worker pools for a cluster, use the GET /v1/zones API or run ibmcloud ks zone ls.

Request Body

Required*
WorkerPoolZonePatchRequest

Updated network configuration values for the worker pool zone.

Response

Status Code

  • 204

    OK. The request to update network configuration for your worker pool was successful.

  • 401

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

  • 403

    Forbidden. The request will not be permitted.

  • 404

    Not found. The specified worker pool or zone could not be found. To list all worker pool zones, use the GET /v1/clusters/{idOrName}/workerpools/{poolIdOrName}/zones API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.

  • 500

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

No Sample Response

This method does not specify any sample responses.

List all worker nodes in a cluster.

List all worker nodes and the status of each in a cluster.

GET /v1/clusters/{idOrName}/workers

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The worker nodes for a cluster are listed.

  • containers-kubernetes.cluster-worker.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster for which you want to list all worker nodes. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Query Parameters

  • pool
    string

    The name or ID of the worker pool to filter results for. Run ibmcloud ks worker-pool ls --cluster <cluster name>.

  • showDeleted
    string

    true|false Shows deleted workers

Response

Response Body

Worker[]

Worker properties

Status Code

  • 200

    Ok. A list of worker nodes for the specified cluster is returned.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Add 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}/workers

Authorization

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

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A worker node is added to the cluster.

  • containers-kubernetes.cluster-worker.add

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    Required*
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

  • X-Auth-Refresh-Token
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use the POST /v1/credentials API before this request.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster to which you want to add additional worker nodes. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*
WorkerConfig

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

Response

Status Code

  • 201

    Ok. Additional worker nodes were successfully added to your cluster.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View details of a worker node.

View detailed information for a worker node.

GET /v1/clusters/{idOrName}/workers/{workerId}

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

View details of a worker node in the cluster.

  • containers-kubernetes.worker.get

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • workerId
    Required*
    string

    The ID of the worker node that you want details for. To list all worker nodes for a cluster, use the GET /v1/clusters/{idOrName}/workers API or run ibmcloud ks worker ls --cluster <cluster_name_or_ID>.

Response

Response Body

Worker

Worker properties

Status Code

  • 200

    Ok. Detailed information about the worker node is returned.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}

Authorization

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

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing 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.reboot

    A worker node is rebooted. A reboot clears temporary directories, but does not clear the entire file system or reformat the disks. Generated if os_reboot is passed for the apiCommand parameter.

  • containers-kubernetes.worker.reload

    A 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 reload is passed for the apiCommand parameter.

  • containers-kubernetes.worker.reboot

    A worker node version is update, such as a minor version update to match the cluster master version. Generated if update is passed for the apiCommand parameter.

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • workerId
    Required*
    string

    The ID of the worker node. To list all worker nodes for a cluster, use the GET /v1/clusters/{idOrName}/workers API or run ibmcloud ks worker ls --cluster <cluster_name_or_ID>.

Request Body

Required*
UpdateWorkerCommand

The action that you want your worker node to take. Pass os_reboot, reload, or update as the action string.

Response

Status Code

  • 204

    OK. The request to reboot or reload your worker node was successfully processed.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}

Authorization

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

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A worker node is deleted from the cluster.

  • containers-kubernetes.worker.delete

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster to add additional worker nodes to. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • workerId
    Required*
    string

    The ID of the worker node. To list all worker nodes for a cluster, use the GET /v1/clusters/{idOrName}/workers API or run ibmcloud ks worker ls --cluster <cluster_name_or_ID>.

Response

Status Code

  • 204

    Ok. The worker node was successfully removed from your cluster.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View details 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/auditwebhook

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Audit webhooks for a cluster are listed.

  • containers-kubernetes.cluster-audit-webhook.get

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster that you want audit configuration details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

AuditWebhookConfig

Status Code

  • 200

    Successfully retrieved the audit webhook configuration.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Create 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/auditwebhook

Authorization

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

To get the action, the user must have the Editor platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

A cluster audit webhook for forwarding master API server audit logs is updated.

  • containers-kubernetes.cluster-audit-webhook.update

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster where you want to add an audit configuration or change the audit configuration. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*
AuditWebhookConfig

The input parameter for creating or updating an audit webhook configuration. For more information, see https://ibm.biz/audit_config_docs

Response

Status Code

  • 204

    Ok. The cluster will send audit logs to the audit server.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 412

    Precondition failed. The input parameters in the request body are incorrect. Some typical cases include if the audit server is http and certs are provided or if the server is https and not all certs are provided.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Delete an 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/auditwebhook

Authorization

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

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A cluster audit webhook for forwarding master API server audit logs is removed.

  • containers-kubernetes.cluster-audit-webhook.delete

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster for which you want to change the audit config. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Status Code

  • 204

    Successfully deleted the audit webhook configuration.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View 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

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Details on the classic infrastructure credentials that are set for managing clusters in the region and resource group are returned.

  • containers-kubernetes.account-infra-credential.get

Request

Custom Headers

  • X-Region
    Required*
    string

    Target the IBM Cloud Kubernetes Service region where you want to get infrastructure credential details. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

  • Authorization
    Required*
    string

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

Response

Response Body

Credentials

Credentials provides information about user infrastructure credentials

Status Code

  • 200

    Ok. The IBM Cloud infrastructure (SoftLayer) account credentials were successfully retrieved from IBM Cloud Kubernetes Service.

  • 401

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

  • 404

    Not found. No IBM Cloud infrastructure account credentials are stored in the Kubernetes Service account for this region and resource group.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

Authorization

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

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

Classic infrastructure credentials for managing clusters in the region and resource group are set.

  • containers-kubernetes.account-infra-credential.set

Request

Custom Headers

  • X-Region
    Required*
    string

    Target the IBM Cloud Kubernetes Service region where you want to set infrastructure credentials. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

  • Authorization
    Required*
    string

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

  • X-Auth-Refresh-Token
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use the POST /v1/credentials API before this request.

  • X-Auth-Softlayer-Username
    string

    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.

  • X-Auth-Softlayer-APIKey
    string

    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

  • 204

    Ok. The IBM Cloud infrastructure account credentials were successfully set for this region and resource group.

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

Remove 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

Authorization

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

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

Classic infrastructure credentials for managing clusters in the region and resource group are deleted.

  • containers-kubernetes.account-infra-credential.delete

Request

Custom Headers

  • X-Region
    Required*
    string

    Target the IBM Cloud Kubernetes Service region where you want to remove infrastructure credentials. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

  • Authorization
    Required*
    string

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

Response

Status Code

  • 204

    Ok. The IBM Cloud infrastructure account credentials were successfully removed from your IBM Cloud Kubernetes Service account for this region and resource group.

  • 401

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

  • 404

    Not found. No IBM Cloud infrastructure account credentials are stored in the Kubernetes Service account for this region and resource group.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Details on the compute, networking, and storage classic infrastructure permissions that are set for managing clusters in the region and resource group are returned.

  • containers-kubernetes.account-infra-permission.get

Request

Custom Headers

  • X-Region
    Required*
    string

    Target the IBM Cloud Kubernetes Service region where you want to check the infrastructure permissions. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group. To list available resource group IDs, run ibmcloud resource groups.

Response

Response Body

AccountStatus

AccountStatus summarises the IaaS user's view of the provider account

Status Code

  • 200

    Ok.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

Authorization

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

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

The API key that is used for all clusters in the region and resource group is set to the requesting user's API key credentials.

  • containers-kubernetes.account-api-key.reset

Request

Custom Headers

  • X-Region
    Required*
    string

    Target the IBM Cloud Kubernetes Service region where you want to reset the IAM API key. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group where you want to set the API key.

Response

Status Code

  • 204

    Ok. The IAM API key is successfully reset.

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

View the 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

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Details on whether the IBM Cloud account has VLAN spanning enabled are returned.

  • containers-kubernetes.account-subnet-vlan-spanning.get

Request

Custom Headers

  • X-Region
    Required*
    string

    Target the IBM Cloud Kubernetes Service region where you want to check the VLAN spanning status. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group. To list available resource group IDs, run ibmcloud resource groups.

Response

Response Body

VlanSpan

Status Code

  • 200

    Ok. Details of VLAN spanning enablement.

  • 401

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

  • 403

    Unable to determine whether VLAN spanning is enabled in the IBM Cloud infrastructure account.

No Sample Response

This method does not specify any sample responses.

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}/vlans

Authorization

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

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

VLANs in an IBM Cloud account for a particular data center are listed.

  • containers-kubernetes.account-datacenter-vlan.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Refresh-Token
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use the POST /v1/credentials API before this request.

Path Parameters

  • datacenter
    Required*
    string

    The ID of the zone where you want to list available public and private VLANs. To list available zones, run ibmcloud ks zone ls or use the GET /v1/datacenters API.

Response

Response Body

VLAN[]

Status Code

  • 200

    Ok. A list of available public and private VLANs for the specified zone is returned.

  • 400

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

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

List available 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

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Subnets in the IBM Cloud classic infrastructure account are listed.

  • containers-kubernetes.account-subnet.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Refresh-Token
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers. This header can be omitted if you use the POST /v1/credentials API before this request.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

  • datacenters
    string

    A comma seperated list of datacenters to filter subnets based off of.

Response

Response Body

Subnet[]

Subnet provides information about a vpc subnet

Status Code

  • 200

    Ok.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View 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}/clusterkeyowner

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group-ID
    string

    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

  • idOrName
    Required*
    string

    The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Response

Response Body

ClusterKeyOwnerInfo

ClusterKeyOwnerInfo stores the token owner's information

Status Code

  • 200

    Ok. The cluster API key ID and the owner's name and email address.

  • 401

    Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View the default logging endpoint for the target region.

View the default logging endpoint for the target region.

GET /v1/logging/{idOrName}/default

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group-ID
    string

    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

  • idOrName
    Required*
    string

    The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Response

Response Body

DefaultLoggingEndpointResponse

DefaultLoggingEndpointResponse is the ibm logging service endpoint where logs will be sent by default clusters in the target region

Status Code

  • 200

    Ok. The default logging endpoint for the target region.

  • 500

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

No Sample Response

This method does not specify any sample responses.

List all log forwarding configurations in the cluster.

List the log forwarding configurations in the target cluster.

GET /v1/logging/{idOrName}/loggingconfig

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group-ID
    string

    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

  • idOrName
    Required*
    string

    The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Response

Response Body

LogConfigResponse[]

LogConfigResponse is how users will see their logging configs from API responses

Status Code

  • 200

    Ok. A list of logging configurations in the Kubernetes cluster.

  • 401

    Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}/loggingconfig

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group-ID
    string

    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

  • idOrName
    Required*
    string

    The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Query Parameters

  • forceUpdate
    boolean

    Forces the request which may cause a new fluentd version to be deployed to the cluster.

Response

Status Code

  • 204

    Ok. All log forwarding configurations have been removed.

  • 401

    Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group-ID
    string

    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

  • idOrName
    Required*
    string

    The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

  • logSource
    Required*
    string

    The type of log source that you want to list configurations for.

Response

Response Body

LogConfigResponse[]

LogConfigResponse is how users will see their logging configs from API responses

Status Code

  • 200

    Ok. A list of logging configurations for the specified log source in the cluster.

  • 401

    Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group-ID
    string

    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

  • idOrName
    Required*
    string

    The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

  • logSource
    Required*
    string

    The log source from which you want to forward logs. Accepted values are container, worker, kubernetes, ingress, and application. If you do not provide a namespace for log source container, then all namespaces use this configuration.

Query Parameters

  • forceUpdate
    boolean

    Forces the request which may cause a new fluentd version to be deployed to the cluster.

  • skipValidation
    boolean

    Set to true to skip validation of the space and org Cloud Foundry properties. Skipping validation decreases processing time, but an invalid logging configuration will not correctly forward logs.

Request Body

Required*
LogConfigBody

The type of log collector server for the logging configuration. Supported logging types are 'syslog' and 'ibm'.

Response

Response Body

LogConfigResponse

LogConfigResponse is how users will see their logging configs from API responses

Status Code

  • 201

    Ok. Logs from the specified log source will be forwarded to the log server.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format. Supported logging types are 'syslog' and 'ibm'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.

  • 401

    Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Update a log forwarding configuration.

Update the details of a log forwarding configuration.

PUT /v1/logging/{idOrName}/loggingconfig/{logSource}/{id}

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group-ID
    string

    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

  • idOrName
    Required*
    string

    The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

  • logSource
    Required*
    string

    The log source from which you want to forward logs. Supported values are container, worker, kubernetes, ingress, and application. If you do not provide a namespace for log source container, then all namespaces use this configuration.

  • id
    Required*
    string

    The UUID of the logging configuration that you want to update.

Query Parameters

  • forceUpdate
    boolean

    Forces the request which may cause a new fluentd version to be deployed to the cluster.

  • skipValidation
    boolean

    Set to true to skip validation of the space and org Cloud Foundry properties. Skipping validation decreases processing time, but an invalid logging configuration will not correctly forward logs.

Request Body

Required*
LogConfigBody

The new type of log collector server for the logging configuration. Supported logging types are 'syslog'.

Response

Response Body

LogConfigResponse

LogConfigResponse is how users will see their logging configs from API responses

Status Code

  • 200

    Ok. The configuration was updated.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format. Supported logging types are 'syslog'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.

  • 401

    Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Delete a log forwarding configuration.

Stops log forwarding by deleting a specified logging configuration.

DELETE /v1/logging/{idOrName}/loggingconfig/{logSource}/{id}

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group-ID
    string

    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

  • idOrName
    Required*
    string

    The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

  • logSource
    Required*
    string

    The log source that you want to stop forwarding logs for.

  • id
    Required*
    string

    The UUID of the logging configuration that you want to delete.

Query Parameters

  • forceUpdate
    boolean

    Forces the request which may cause a new fluentd version to be deployed to the cluster.

Response

Status Code

  • 204

    Ok. Logs will no longer be forwarded to the log server for the specified logging configuration.

  • 401

    Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}/refresh

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group-ID
    string

    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

  • idOrName
    Required*
    string

    The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Query Parameters

  • forceUpdate
    boolean

    Forces the request which may cause a new fluentd version to be deployed to the cluster.

Response

Status Code

  • 204

    Ok. A request was sent for the cluster's logging configuration to be refreshed.

  • 401

    Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}/updatepolicy

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group-ID
    string

    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

  • idOrName
    Required*
    string

    The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Response

Response Body

UpdatePolicy

Status Code

  • 200

    Ok. The current update policy.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format. Supported logging types are 'syslog' and 'ibm'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.

  • 401

    Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}/updatepolicy

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group-ID
    string

    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

  • idOrName
    Required*
    string

    The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Request Body

Required*
UpdatePolicy

The new update policy configuration

Response

Status Code

  • 204

    Ok. The logging update policy has been changed.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format. Supported logging types are 'syslog' and 'ibm'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.

  • 401

    Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Create a LogDNA logging configuration for a cluster.

Create a logging configuration for your IBM Cloud Kubernetes Service cluster to automatically collect pod logs and send them to IBM Cloud Log Analysis with LogDNA. This API deploys a LogDNA agent as a Kubernetes daemonset in the ibm-observe namespace of your cluster. The agent collects logs with the extension *.log and extensionless files that are stored in the /var/log directory of your pod from all namespaces, including kube-system. The agent then forwards the logs to your IBM Cloud Log Analysis with LogDNA service instance.

Note: Before you use this API, make sure that you have an existing IBM Cloud Log Analysis with LogDNA service instance.

POST /v2/observe/logging/createConfig

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens. This value is required only if no IAM cookie is provided in your API request or the API is invoked through a CURL command.

  • X-Auth-Refresh-Token
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. Required only in the absense of an IAM cookie and when the API is invoked through a CURL command.

Request Body

Required*
ConfigBody

The input parameter to create the configmap for the LogDNA agent. The ingestionKey and privateEndpoint parameters are optional.

Response

Response Body

ConfigResponse

Status Code

  • 201

    Created. The LogDNA logging configuration was successfully created for your cluster.

  • 400

    Bad request. The query parameters or the input parameters in the request body are either incomplete or in the wrong format. Make sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

    Unauthorized. The user does not have the correct IAM platform and service roles to complete this operation. Check with your IBM Cloud Administor for the correct permissions`.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Discover a LogDNA agent previously deployed in the cluster.

Discover a LogDNA agent previously deployed in the cluster and create a logging configuration for it.

POST /v2/observe/logging/discoverAgent

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens. This value is required if the API is invoked through a CURL command.

  • X-Auth-Refresh-Token
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. Required when the API is invoked through a CURL command.

Request Body

Required*
DiscoverConfig

The input parameter to discover an existing LogDNA agent. The cluster parameter is required.

Response

Response Body

ObsConfig

Status Code

  • 201

    Discovered. The logging configuration was successfully created for a discovered agent.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Make sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

    Unauthorized. The user does not have the correct IAM platform and service roles to complete this operation. Check with your IBM Cloud Administor for the correct permissions`.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Show the details of an existing LogDNA logging configuration.

Retrieve information about an existing LogDNA logging configuration for your cluster. To use this API, you must provide the name or ID of the cluster and the IBM Cloud Log Analysis with LogDNA service instance as query parameters in the format /getConfig?cluster={idOrName}\u0026instance={idOrName}.

GET /v2/observe/logging/getConfig

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens. This value is required only if no IAM cookie is provided in your API request or the API is invoked through a CURL command.

  • X-Auth-Refresh-Token
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. Required only in the absense of an IAM cookie and when the API is invoked through a CURL command.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster for which you want to show details of an existing LogDNA logging configuration. To list available clusters, run ibmcloud ks cluster ls.

  • instance
    Required*
    string

    The name or ID of the LogDNA service instance that you configured for the cluster. To list available LogDNA service instances, run ibmcloud resource service-instances.

Response

Response Body

ObsConfig

Status Code

  • 200

    Ok. Information about the LogDNA logging configuration is returned.

  • 400

    Bad request. One or more query parameters are missing in your API request. Make sure to include all required parameters in your request.

  • 401

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

  • 403

    Unauthorized. The user does not have the correct IAM platform and service roles to complete this operation. Check with your IBM Cloud Administor for the correct permissions`.

  • 500

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

No Sample Response

This method does not specify any sample responses.

List all LogDNA logging configurations for a cluster.

Retrieve information about all LogDNA logging configurations that exist for a cluster. To use the API, you must provide the name or ID of the cluster as a query parameter in the format /getConfigs?cluster={idOrName}.

GET /v2/observe/logging/getConfigs

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. This value is required only if no IAM cookie is provided in your API request or the API is invoked through a CURL command.

  • X-Auth-Refresh-Token
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster for which you want to list existing LogDNA logging configurations. To list available clusters, run ibmcloud ks cluster ls.

Response

Response Body

ObsConfig[]

ObsConfigs is an array of all configmaps

Status Code

  • 200

    Ok. Information about existing LogDNA logging configurations is returned.

  • 400

    Bad request. The query parameter is missing or unknown query parameters were specified in your API request. Make sure to include all required parameters in your request.

  • 401

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

  • 403

    Unauthorized. The user does not have the correct IAM platform and service roles to complete this operation. Check with your IBM Cloud Administor for the correct permissions`.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Update a LogDNA logging configuration in the cluster.

Update an existing LogDNA configuration in the cluster. Changes can be made to the logging instance connected to the cluster, ingestion key, or use of public or private endpoints for the logging instance.

POST /v2/observe/logging/modifyConfig

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens. This value is required if the API is invoked through a CURL command.

  • X-Auth-Refresh-Token
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. Required when the API is invoked through a CURL command.

Request Body

Required*
ModifyBody

The input parameter to update the configmap for the LogDNA agent. The cluster and instance parameters are required.

Response

Response Body

ObsConfig

Status Code

  • 201

    Modified. The LogDNA logging configuration was successfully modified for your cluster.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Make sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

    Unauthorized. The user does not have the correct IAM platform and service roles to complete this operation. Check with your IBM Cloud Administor for the correct permissions`.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Remove a LogDNA logging configuration from a cluster.

Remove an existing LogDNA logging configuration from a cluster. When you remove the logging configuration, pod logs are no longer sent to your IBM Cloud Log Analysis with LogDNA service instance. However, existing log data is still available until your selected retention period ends. To use the API, you must provide the name or ID of the cluster and the LogDNA service instance as query parameters in the format /removeConfig?cluster={idOrName}\u0026instance={idOrName}.

POST /v2/observe/logging/removeConfig

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens. This value is required only if no IAM cookie is provided in your API request or the API is invoked through a CURL command.

  • X-Auth-Refresh-Token
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. Required only in the absense of an IAM cookie and when the API is invoked through a CURL command.

Request Body

Required*
DeleteConfig

The input parameter to remove the configmap from the cluster.

Response

Status Code

  • 200

    Ok. The LogDNA logging configuration was successfully removed from the cluster.

  • 400

    Bad request. One or more query parameters are missing or unknown query parameters were specified in your API request. Make sure to include all required parameters in your request.

  • 401

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

  • 403

    Unauthorized. The user does not have the correct IAM platform and service roles to complete this operation. Check with your IBM Cloud Administor for the correct permissions`.

  • 500

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

No Sample Response

This method does not specify any sample responses.

List all logging filter configurations in the cluster.

List the logging filter configurations that you created in a cluster.

GET /v1/logging/{idOrName}/filterconfigs

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group-ID
    string

    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

  • idOrName
    Required*
    string

    The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Query Parameters

  • showMatches
    boolean

    Set to true to populate global filters with all matching logging configurations.

Response

Response Body

FilterConfigResponse[]

FilterConfigResponse is how users will see their logging filter configs from API responses

Status Code

  • 200

    Ok. A list of logging filters in the cluster.

  • 401

    Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Create a 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}/filterconfigs

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group-ID
    string

    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

  • idOrName
    Required*
    string

    The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Query Parameters

  • forceUpdate
    boolean

    Forces the request which may cause a new fluentd version to be deployed to the cluster.

Request Body

Required*
FilterConfigBody

The new logging filter configuration.

Response

Response Body

FilterConfigResponse

FilterConfigResponse is how users will see their logging filter configs from API responses

Status Code

  • 201

    Ok. Logs from the specified logging configurations will be filtered on the provided selectors.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all of the required parameters, formatted in JSON. Supported logging types are 'syslog' and 'ibm'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.

  • 401

    Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Deletes all logging filter configurations for the cluster.

Stops log filtering.

DELETE /v1/logging/{idOrName}/filterconfigs

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group-ID
    string

    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

  • idOrName
    Required*
    string

    The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

Query Parameters

  • forceUpdate
    boolean

    Forces the request which may cause a new fluentd version to be deployed to the cluster.

Response

Status Code

  • 204

    Ok. All log filtering configurations have been removed.

  • 401

    Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View a logging filter configuration.

View details for a logging filter configuration.

GET /v1/logging/{idOrName}/filterconfigs/{id}

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group-ID
    string

    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

  • idOrName
    Required*
    string

    The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

  • id
    Required*
    string

    The UUID of the logging filter that you want to fetch.

Query Parameters

  • showMatches
    boolean

    To show matching logging configurations for global filters, set to true.

Response

Response Body

FilterConfigResponse

FilterConfigResponse is how users will see their logging filter configs from API responses

Status Code

  • 200

    Ok. A logging filter is configured for your cluster.

  • 401

    Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Update 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

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group-ID
    string

    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

  • idOrName
    Required*
    string

    The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

  • id
    Required*
    string

    The UUID for the filterConfig that you want to update.

Query Parameters

  • forceUpdate
    boolean

    Forces the request which may cause a new fluentd version to be deployed to the cluster.

Request Body

Required*
FilterConfigBody

The new filter configuration for the specified ID.

Response

Response Body

FilterConfigResponse

FilterConfigResponse is how users will see their logging filter configs from API responses

Status Code

  • 200

    Ok. The configuration was updated.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all of the required parameters, formatted in JSON. Supported logging types are 'syslog'. Log forwarding is not supported for the 'ibm-system' and 'kube-system' namespaces.

  • 401

    Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Delete a logging filter configuration.

Delete the specified logging filter configuration for a cluster.

DELETE /v1/logging/{idOrName}/filterconfigs/{id}

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group-ID
    string

    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

  • idOrName
    Required*
    string

    The name or ID of the target cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls.

  • id
    Required*
    string

    The UUID for the filterConfig that you want to delete.

Query Parameters

  • forceUpdate
    boolean

    Forces the request which may cause a new fluentd version to be deployed to the cluster.

Response

Status Code

  • 204

    Ok. Logs will no longer be filtered by the specified filter configuration.

  • 401

    Unauthorized. To retrieve your access tokens, be sure that you're logged in and run ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To see a list of your clusters, run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Update 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}/add

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*
NlbConfig

The input parameter to update an NLB DNS record. Include only the nlbHost parameter to specify the existing NLB subdomain and the nlbIP parameter to specify the NLB IP you want to add.

Response

Status Code

  • 204

    Ok. The request to update the NLB subdomain was successfully processed.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified cluster, NLB subdomain, or NLB IP address could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>. To list existing NLB IP addresses in a cluster, run kubectl get svc -n <namespace>.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}/remove

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • nlbHost
    Required*
    string

    The existing NLB subdomain from which you want remove an NLB IP. To list existing NLB subdomains, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.

  • nlbIP
    Required*
    string

    The NLB IP address that you want to unregister from the DNS record for the hostname. To list the NLB IPs registered with NLB subdomains, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.

Response

Status Code

  • 204

    Deleted. The NLB IP address was successfully unregistered from the DNS record for the NLB subdomain.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified cluster, NLB subdomain, or NLB IP address could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains and the NLB IPs registered with those hostnames, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}/list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

ClusterNlbHostsList

ClusterNlbHostsList used for storing Nlbs, NlbMonitor, NlbHealthCheckStatus

Status Code

  • 200

    Ok. A list of NLB subdomains and the NLB IPs associated with the DNS record for the subdomains is returned for this cluster.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}/register

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*
NlbConfig

Include either the nlbIP or the nlbIPArray parameter that specifies the NLB IP address(es) that you want to register.

Response

Response Body

NlbConfig

NlbConfig config for NLB configuration

Status Code

  • 201

    Created. The NLB subdomain was successfully created and the NLB IP addres(es) registered with DNS.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified cluster or NLB IP address could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB IP addresses in a cluster, run kubectl get svc -n <namespace>.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}/health

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*
NlbConfig

Include only the nlbHost parameter to specify the NLB subdomain and the nlbMonitorState parameter to specify the health check monitor as enabled or disabled.

Response

Status Code

  • 200

    Ok. Health check monitor enable/disable request for successfully processed.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified cluster or NLB subdomain could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}/config

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Request Body

Required*
NlbHealthSetConfig

The input body to configure the health check monitor for an NLB subdomain. To enable the health check monitor, set monitorState to enabled. For more information about each healthcheckProperties parameter, see https://cloud.ibm.com/docs/containers?topic=containers-cli-plugin-kubernetes-service-cli#cs_nlb-dns-monitor-configure

Response

Response Body

NlbHealthConfig

NlbHealthConfig config for NLB Health configuration

Status Code

  • 201

    Created. The health check monitor was successfully configured for the NLB subdomain.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified cluster or NLB subdomain could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}/config

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • nlbHost
    Required*
    string

    The NLB subdomain that you want health check monitor settings for. To list existing NLB subdomains, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.

Response

Response Body

NlbHealthConfig

NlbHealthConfig config for NLB Health configuration

Status Code

  • 200

    Ok. Health check monitor settings for the specified NLB subdomain are returned.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified cluster or NLB subdomain could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}/list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

ClusterNlbHostsList

ClusterNlbHostsList used for storing Nlbs, NlbMonitor, NlbHealthCheckStatus

Status Code

  • 200

    Ok. The health check monitor settings for each NLB subdomain in the cluster are returned.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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}/status

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Path Parameters

  • idOrName
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

ClusterNlbHostsList

ClusterNlbHostsList used for storing Nlbs, NlbMonitor, NlbHealthCheckStatus

Status Code

  • 200

    Ok. An array that contains the NlbHealthCheckStatus is returned.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Details on whether a user can create free or standard clusters in a certain region and resource group are returned.

  • containers-kubernetes.account-user-config.get

Request

Custom Headers

  • X-Region
    Required*
    string

    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/regions API or run ibmcloud ks region ls.

  • Authorization
    Required*
    string

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

Response

Response Body

UserConfig

UserConfig describes the config values applicable to a user account

Status Code

  • 200

    Ok. The user's permissions to create free and paid clusters is returned.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

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

Request Body

Required*
IgnoredIngressStatusErrors

Ingress status errors that are ignored for ingress status reporting.

Response

Status Code

  • 200

    Ignored ingress status errors were successfully added to the ingress status configuration.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

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

  • 404

    Not found. The specified cluster could not be found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. 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

  • albID
    Required*
    string

    The ID of the ALB that you want details for. To list the IDs for the ALBs in a cluster, use the GET /v2/alb/getClusterAlbs API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.

Response

Response Body

ALBConfig

ALBConfig config for alb configuration

Status Code

  • 200

    Ok. Details for the specified ALB are returned.

  • 401

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

  • 404

    Not found. The specified cluster or ALB could not be found. To list the classic clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

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

Response

Response Body

string[]

Status Code

  • 200

    Ok. A list of supported Ingress controller images is returned.

  • 403

    Forbidden. The credentials set for the region and resource group have insufficient permissions to list supported Ingress controller images.

  • 500

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

No Sample Response

This method does not specify any sample responses.

List all 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

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API. To list available resource group IDs, run ibmcloud resource groups.

Query Parameters

  • cluster
    Required*
    string

    To list the classic clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.

Response

Response Body

ClusterALB

ClusterALB alb related information for vpc cluster

Status Code

  • 200

    Ok. A list of ALBs for the cluster is returned.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the classic clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

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

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster.

Response

Response Body

ALBClusterHealthCheckConfig

ALBClusterHealthCheckConfig

Status Code

  • 200

    Ok. The in-cluster ALB health checker status for your cluster is returned.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

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

  • 404

    Not found. The specified cluster could not be found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

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

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want information about.

Response

Response Body

Status

Status struct for the top level ingress status, for a cluster

Status Code

  • 200

    Ok. The ingress status for your cluster is returned.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

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

  • 404

    Not found. The specified cluster could not be found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

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

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster.

Response

Response Body

IgnoredIngressStatusErrors

IgnoredIngressStatusErrors

Status Code

  • 200

    Ok. All ignored ingress status errors for your cluster are returned.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

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

  • 404

    Not found. The specified cluster could not be found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

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

Request Body

Required*
IgnoredIngressStatusErrors

Ingress status errors that are ignored for ingress status reporting.

Response

Status Code

  • 200

    Ignored ingress status errors were successfully removed from the ingress status configuration.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

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

  • 404

    Not found. The specified cluster could not be found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

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

Request Body

Required*
ALBClusterHealthCheckConfig

The desired state of the in-cluster ingress health checker.

Response

Status Code

  • 200

    Set successfully finished.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

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

  • 404

    Not found. The specified cluster could not be found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

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

Request Body

Required*
StatusState

The desired state of ingress status.

Response

Status Code

  • 200

    Set successfully finished.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

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

  • 404

    Not found. The specified cluster could not be found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

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

Request Body

Required*
V2UpdateALB

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

  • 200

    Updated. The ALBs in the cluster were successfully updated.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

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

  • 404

    Not found. The specified cluster or ALB could not be found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

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

Request Body

Required*
ALB

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

Response

Response Body

AlbCreateResp

AlbCreateResp used to send back the albid on a create request

Status Code

  • 201

    The ALB was successfully created.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

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

  • 404

    Not found. The specified cluster or zone could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic. To list the zones available in a VPC cluster, use the GET /v2/vpc/getCluster API or run ibmcloud ks cluster-get --cluster <cluster_name_or_ID>.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Disable an ALB in your VPC cluster.

Disable a public or private ALB in your VPC cluster.

POST /v2/alb/vpc/disableAlb

Request

Custom Headers

  • Authorization
    Required*
    string

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

Request Body

Required*
ALBConfig

The input parameters to disable an ALB. DisableDeployment and albID are required. For more information, see https://ibm.biz/alb_configure_vpc

Response

Status Code

  • 204

    Disabled. The ALB for the cluster was successfully disabled.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified cluster or ALB could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic. To list the ALBs in a cluster, use the GET /v2/alb/getClusterAlbs API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

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

Request Body

Required*
ALBConfig

The input parameter to enable an ALB. 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

Response

Status Code

  • 201

    Enabled. The ALB for the cluster was successfully enabled.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 403

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

  • 404

    Not found. The specified cluster or ALB could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic. To list the ALBs in a cluster, use the GET /v2/alb/getClusterAlbs API or run ibmcloud ks alb ls --cluster <cluster_name_or_ID>.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

Authorization

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

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

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

  • Authorization
    Required*
    string

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

  • X-Auth-Refresh-Token
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Request Body

Required*
Kubeconfig

Options to retrieve a kubeconfig file. Default format is 'json', other options include 'yaml' and 'zip'. To retrieve the Calico network config, pass admin:true and format:"zip" in the body.

Response

Status Code

  • 202

    Accepted. Applies IAM roles asynchronously.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

Authorization

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

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

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

  • Authorization
    Required*
    string

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

  • X-Auth-Refresh-Token
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

  • Accept
    string

    Allowable values: [application/json,application/zip,text/yaml]

Request Body

Required*
Kubeconfig

Options to retrieve a kubeconfig file. Default format is 'json', other options include 'yaml' and 'zip'. To retrieve the Calico network config, pass admin:true and format:"zip" in the body.

Response

Response Body

ClientKubeConfig

ClientKubeConfig is the kubernetes config file used by kubectl

Status Code

  • 200

    Ok. Returns the cluster's kubeconfig file.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

Authorization

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

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing 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.enable

    Automatic updates for master fix pack patch updates are enabled. Generated if the autoUpdate parameter is set to true.

  • containers-kubernetes.cluster-master-autoupdate.disable

    Automatic updates for master fix pack patch updates are disabled. Generated if the autoUpdate parameter is set to false.

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*
AutoUpdateMaster

Input parameters to specify the name or ID of the cluster and whether to enable or disable auto master updates. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Status Code

  • 204

    Ok. The request was processed successfully.

  • 401

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

  • 403

    Forbidden. The user doesn't have access to this API.

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 409

    Conflict. The specified value is already set on the cluster. To list the clusters properties, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Detailed cluster information.

Detailed cluster information.

GET /v2/classic/getCluster

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Details for a cluster are returned.

  • containers-kubernetes.cluster.get

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group 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

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • showResources
    string

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

Response

Response Body

GetClusterResponse

Status Code

  • 200

    Success. Detailed cluster information.

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

List the classic clusters that you have access to.

List the classic clusters that you have access to.

GET /v2/classic/getClusters

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Clusters are listed.

  • containers-kubernetes.cluster.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group to list clusters for. To list available resource groups, run ibmcloud resource groups. If you don't include this header, all the clusters in the account that you have access to are listed.

Query Parameters

  • location
    string

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

  • showResources
    string

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

Response

Response Body

GetClustersResponse[]

GetClustersResponse cluster response for cluster list

Status Code

  • 200

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

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The details of a worker pool in the cluster are returned.

  • containers-kubernetes.cluster-worker-pool.get

Request

Custom Headers

  • X-Region
    Required*
    string

    Specify the region to check for private service enablement.

  • Authorization
    Required*
    string

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

Response

Response Body

PrivateServiceEndpointEnabled

PrivateServiceEndpointEnabled is a status from the softlayer for the used account OR for the attached infrastructure account in the actual region

Status Code

  • 200

    Ok. Detailed information about the private service enablement.

  • 401

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

  • 403

    Not authorized to use this command. Only a limited group of early adopters have access to this feature. If you are sure that you are part of the limited group of early adopters, contact IBM Cloud support..

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

VLANs in an IBM Cloud account for a particular data center are listed.

  • containers-kubernetes.account-datacenter-vlan.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group to target.

Query Parameters

  • zone
    Required*
    string

    The ID of the zone where you want to list available public and private VLANs. To list available zones, run ibmcloud ks zone ls or use the GET /v1/datacenters API.

Response

Response Body

VLAN

Status Code

  • 200

    Ok. A list of all VLANs is returned.

  • 401

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

  • 403

    Forbidden. The credentials set for the region and resource group have insufficient permissions for the infrastructure provider.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View details of a worker node for classic cluster.

View detailed information for a worker node in a classic cluster.

GET /v2/classic/getWorker

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The details of a worker node in the cluster are returned.

  • containers-kubernetes.worker.get

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • worker
    Required*
    string

    The ID of the worker node that you want details for. To list all worker nodes for a cluster, use the GET /v1/clusters/{idOrName}/workers API or run ibmcloud ks workers <cluster_name_or_ID>.

Response

Response Body

GetWorkerResponse

Status Code

  • 200

    Ok. Detailed information about the worker node is returned.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks clusters.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View details of a worker pool for a classic cluster.

View detailed information for a worker pool in a classic cluster.

GET /v2/classic/getWorkerPool

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The worker pools for a cluster are listed.

  • containers-kubernetes.cluster-worker-pool.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Region
    string

    If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • workerpool
    Required*
    string

    The ID of the worker pool that you want details for. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.

Response

Response Body

GetClassicWorkerPoolResponse

Status Code

  • 200

    Ok. Detailed information about the worker pool is returned.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View details of a worker pool for a classic cluster.

View detailed information for a worker pool in a classic cluster.

GET /v2/classic/getWorkerPools

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The details of a worker pool in the cluster are returned.

  • containers-kubernetes.cluster-worker-pool.get

Request

Custom Headers

  • X-Region
    string

    If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

  • Authorization
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

GetClassicWorkerPoolResponse[]

Status Code

  • 200

    Ok. Detailed information about the worker pools is returned.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View all workers for a classic cluster.

View detailed information for all worker nodes in a classic cluster.

GET /v2/classic/getWorkers

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The worker nodes for a cluster are listed.

  • containers-kubernetes.cluster-worker.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks clusters.

  • showDeleted
    string

    true|false Shows deleted workers

  • pool
    string

    The name or ID of the worker pool to filter results for. Run ibmcloud ks worker-pool ls --cluster <cluster name>.

Response

Response Body

GetWorkerResponse[]

Status Code

  • 200

    Ok. Details for all workers in the classic cluster.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks clusters.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Create a dedicated host.

Create a dedicated host.

POST /v2/createDedicatedHost

Authorization

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

To create a dedicated host, you must have the Operator platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.account-dedicated-host.create

Auditing

Calling this method generates the following auditing event.

A dedicated host is created.

  • containers-kubernetes.account-dedicated-host.create

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Refresh-Token
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers.

Request Body

Required*
CreateDedicatedHost

The required dedicated host parameters.

Response

Response Body

CreateDedicatedHostResponse

Status Code

  • 201

    Created. The dedicated host was successfully created.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 409

    Conflict. A dedicated host create may already be in progress. Please wait a few minutes and try again.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Create a dedicated host pool.

Create a dedicated host pool.

POST /v2/createDedicatedHostPool

Authorization

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

To create a dedicated host pool, you must have the Operator platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.account-dedicated-host-pool.create

Auditing

Calling this method generates the following auditing event.

A dedicated host is created.

  • containers-kubernetes.account-dedicated-host-pool.create

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Refresh-Token
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers.

  • X-Auth-Resource-Group
    string

    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.

Request Body

Required*
CreateDedicatedHostPool

The required dedicated host pool parameters.

Response

Response Body

CreateDedicatedHostResponse

Status Code

  • 201

    Created. The dedicated host pool was successfully created.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 409

    Conflict. Creation of a dedicated host might already be in progress. Please wait a few minutes and try again.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

Authorization

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

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

A key management service (KMS) provider is enabled for a cluster.

  • containers-kubernetes.cluster-kms.enable

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*
EnableKMSRequest

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

Response

Status Code

  • 200

    Ok. The requested KMS configuration has been enabled on the cluster.

  • 401

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

  • 404

    Not found. The specified cluster or worker could not be found. To list the clusters that you have access to, use the GET /vpc/v2/clusters API or run ibmcloud ks cluster ls --provider vpc-classic.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The CA cert for a cluster is requested.

  • containers-kubernetes.cluster-ca-certificate.get

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get CA cert from. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.

Response

Status Code

  • 200

    Ok. Returns the cluster's CA cert.

  • 400

    Bad request. The query parameters are either incomplete or in the wrong format.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

List the 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

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Root keys from key management service instances for the IBM Cloud account are listed.

  • containers-kubernetes.account-customer-root-key.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group. To list available resource group IDs, run ibmcloud resource groups.

Query Parameters

  • kms_instance
    Required*
    string

    The KMS instance ID to list root keys for. To list available Key Protect service instances, run 'ibmcloud ks kms instance ls'.

Response

Response Body

GetCRKResponse[]

GetCRKResponse is data returned by a getCRKs request call

Status Code

  • 200

    Ok. A list of available root keys in the KMS instance is returned.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

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

  • 404

    Not found. The specified cluster or worker could not be found. To list the clusters that you have access to, use the GET /vpc/v2/clusters API or run ibmcloud ks cluster ls --provider vpc-classic.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View details for a cluster.

View detailed information for a cluster, including a VPC cluster.

GET /v2/getCluster

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Details for a cluster are returned.

  • containers-kubernetes.cluster.get

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group 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

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the worker node details from. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.

Response

Response Body

GetClusterResponse

Status Code

  • 200

    Success. Detailed cluster information is returned.

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

View 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

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Cluster add-ons are listed.

  • containers-kubernetes.cluster-addon.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group of the cluster, use the GET /v1/clusters/{idOrName} API.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

ClusterAddon[]

ClusterAddon represents one add on

Status Code

  • 200

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

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View details of a dedicated host.

View detailed information for a dedicated host.

GET /v2/getDedicatedHost

Authorization

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

To view the details of a dedicated host, you must have the Viewer platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.account.read

Auditing

Calling this method generates the following auditing event.

The details of a dedicated host are returned.

  • containers-kubernetes.account-dedicated-host.get

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Region
    string

    If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

Query Parameters

  • dedicatedhost
    Required*
    string

    The ID of the dedicated host that you want details for..

  • dedicatedhostpool
    Required*
    string

    The ID of the dedicated host pool that you want to get the dedicated host details from.

Response

Response Body

GetDedicatedHost

Status Code

  • 200

    Ok. Detailed information about the dedicated host is returned.

  • 401

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

  • 404

    Not found. The specified dedicated host could not be found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View details of a dedicated host pool.

View detailed information for a dedicated host pool.

GET /v2/getDedicatedHostPool

Authorization

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

To view the details of a dedicated host pool, the user must have the Viewer platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.account.read

Auditing

Calling this method generates the following auditing event.

The details of a dedicated host pool are returned.

  • containers-kubernetes.account-dedicated-host-pool.get

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Region
    string

    If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

Query Parameters

  • dedicatedhostpool
    Required*
    string

    The ID of the dedicated host pool that you want to get.

Response

Response Body

GetDedicatedHostPool

Status Code

  • 200

    Ok. Detailed information about the dedicated host pool is returned.

  • 401

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

  • 404

    Not found. The specified dedicated host could not be found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

List the dedicated host pools.

GET /v2/getDedicatedHostPools

Authorization

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

To list dedicated host pools, you must have the Viewer platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.account.read

Auditing

Calling this method generates the following auditing event.

The dedicated host pools are listed.

  • containers-kubernetes.account-dedicated-host-pool.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Region
    string

    If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

Response

Response Body

GetDedicatedHostPool[]

Status Code

  • 200

    Ok. Detailed information about the dedicated host pools is returned.

  • 401

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

  • 404

    Not found. The specified dedicated host pool could not be found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

List the dedicated hosts.

GET /v2/getDedicatedHosts

Authorization

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

To list dedicated hosts, you must have the Viewer platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.account.read

Auditing

Calling this method generates the following auditing event.

The dedicated hosts are listed.

  • containers-kubernetes.account-dedicated-host.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Region
    string

    If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

Query Parameters

  • dedicatedhostpool
    Required*
    string

    The ID of the dedicated host pool that you want to get the dedicated hosts details from.

Response

Response Body

GetDedicatedHost[]

Status Code

  • 200

    Ok. Detailed information about the dedicated hosts is returned.

  • 401

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

  • 404

    Not found. The specified dedicated host pool could not be found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

Authorization

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

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

Query Parameters

  • flavor
    Required*
    string

    The ID of the flavor. To list available flavors, run ibmcloud ks flavors --zone ZONE or use the GET /v2/getFlavors API.

  • zone
    Required*
    string

    The ID of the zone. To list available zones, run ibmcloud ks zone ls or use the GET /v2/zones API.

  • provider
    Required*
    string

    The name of the provider. To check available providers, see the output of the ibmcloud ks flavors --zone ZONE command or use the GET /v2/getFlavors API.

Response

Response Body

Flavor

Flavor Definition of a flavor / machine type that can be deployed

Status Code

  • 200

    Success

  • 400

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

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

List available 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

Authorization

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

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

Query Parameters

  • zone
    Required*
    string

    The ID of the location for which you want to list available flavors. To list available locations, run ibmcloud ks zone ls or use the GET /v2/zones API.

  • provider
    string

    Filters the flavors to match the provider type specified.

Response

Response Body

Flavor[]

Flavor Definition of a flavor / machine type that can be deployed

Status Code

  • 200

    Success

  • 400

    The specified location is invalid. To list available locations, run ibmcloud ks zone ls or use the GET /v2/zones API.

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Key management service instances in the IBM Cloud account are listed.

  • containers-kubernetes.account-key-management-service-instance.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group. To list available resource group IDs, run ibmcloud resource groups.

Response

Response Body

GetKMSInstanceResponse[]

Status Code

  • 200

    Ok. A list of all KMSs in your IBM Cloud Account

  • 401

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

  • 404

    Not found. The specified cluster or worker could not be found. To list the clusters that you have access to, use the GET /vpc/v2/clusters API or run ibmcloud ks cluster ls --provider vpc-classic.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM. Note that to pull the networking or admin configuration files, you must have the Administrator platform role.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The Kubernetes configuration file 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.get

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Refresh-Token
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

  • Accept
    string

    Allowable values: [application/json,application/zip,text/yaml]

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.

  • endpointType
    string

    Default endpoint is the public endpoint if available, private otherwise. Use 'private' to require a private endpoint and 'link' for a Satellite Link endpoint.

  • format
    string

    Default format is json. Other options include yaml, and zip.

  • admin
    boolean

    Retrieve the admin kubeconfig file.

  • network
    boolean

    Retrieve the Calico network config. Requires admin=true and format=zip.

Response

Response Body

ClientKubeConfig

ClientKubeConfig is the kubernetes config file used by kubectl

Status Code

  • 200

    Ok. Returns the cluster's kubeconfig file.

  • 400

    Bad request. The query parameters are either incomplete or in the wrong format.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

List supported operating systems.

Lists supported operating systems for the given configuration.

GET /v2/getOperatingSystems

Auditing

Calling this method generates the following auditing event.

Lists the supported operating systems for the given configuration.

  • cluster-worker-pool-supported-operating-systems.get

Request

Custom Headers

  • Authorization
    Required*
    string

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

Query Parameters

  • provider
    Required*
    string

    The name of the infrastructure provider in which to view supported operating systems. Available options include 'classic', 'vpc-gen2', and 'satellite'.

  • version
    Required*
    string

    The Kubernetes or Openshift version.

  • coreOSEnabled
    boolean

    Whether HyperShift is enabled.

Response

Response Body

OperatingSystem[]

OperatingSystem is the supported OS

Status Code

  • 200

    Ok. The request to list supported operating systems was successfully processed.

  • 400

    Bad Request. Required parameters were not set. You must provide the version and provider query parameters.

  • 401

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

No Sample Response

This method does not specify any sample responses.

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

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The quota for resources such as clusters or worker nodes for the IBM Cloud account is returned.

  • containers-kubernetes.account-quota.get

Request

Custom Headers

  • Authorization
    Required*
    string

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

Response

Response Body

GetQuotaResource[]

GetQuota defines a response when getting quota for an account

Status Code

  • 200

    OK. A list of quota limits for resources per region in the account is returned.

  • 401

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

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

Authorization

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

To get the RBACSync status, you must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The RBAC status of the user was requested.

  • containers-kubernetes.cluster-rbac.status

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the RBACSync status from. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.

Response

Response Body

object

Status Code

  • 200

    Success

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View details of a worker node for cluster.

View detailed information for a worker node in a cluster.

GET /v2/getWorker

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The details of a worker node in the cluster are returned.

  • containers-kubernetes.worker.get

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster?cluster=idOrName API.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the worker node details from. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.

  • worker
    Required*
    string

    The ID of the worker node that you want details for. To list all worker nodes for a cluster, use the GET /v2/getWorkers?cluster=idOrName API or run ibmcloud ks worker ls --cluster <cluster_name_or_ID>.

Response

Response Body

GetWorkerResponse

Status Code

  • 200

    Ok. Detailed information about the worker node is returned.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View details of a worker pool for a cluster.

View detailed information for a worker pool in a cluster.

GET /v2/getWorkerPool

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The details of a worker pool in the cluster are returned.

  • containers-kubernetes.cluster-worker-pool.get

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Region
    string

    If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster?cluster=idOrName API.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the worker node details from. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.

  • workerpool
    Required*
    string

    The ID of the worker pool that you want details for. To list all worker pools for a cluster, use the GET /v2/getWorkerPools?cluster=idOrName API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.

Response

Response Body

GetCombinedWorkerPoolResponse

getCombinedWorkerPoolResponse is a superset of all WorkerPool fields returned by all the v2 get worker(s) operations, regardless of the provider.

Status Code

  • 200

    Ok. Detailed information about the worker pool is returned.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.

  • 500

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

No Sample Response

This method does not specify any sample responses.

List the worker pools in a cluster.

GET /v2/getWorkerPools

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The worker pools for a cluster are listed.

  • containers-kubernetes.cluster-worker-pool.list

Request

Custom Headers

  • Authorization
    Required*
    string

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

  • X-Region
    string

    If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster?cluster=idOrName API.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the worker node details from. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.

Response

Response Body

GetCombinedWorkerPoolResponse[]

getCombinedWorkerPoolResponse is a superset of all WorkerPool fields returned by all the v2 get worker(s) operations, regardless of the provider.

Status Code

  • 200

    Ok. Detailed information about the worker pools is returned.

  • 401

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

  • 404

    Not found. The specified cluster could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.

  • 500

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

No Sample Response

This method does not specify any sample responses.

View all workers for cluster.

View detailed information for all worker nodes in a cluster.

GET /v2/getWorkers

Authorization

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

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The worker nodes for a cluster are listed.

  • containers-kubernetes.cluster-worker.list

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster?cluster=idOrName API.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the worker node details from. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.

  • showDeleted
    string

    true|false Shows deleted workers

Response

Response Body

GetWorkerResponse[]

Status Code

  • 200

    Ok. Details for all workers in the cluster.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Validates user provided entitlement.

Validates whether the provided entitlement value is supported or not.

GET /v2/hasValidEntitlement

Auditing

Calling this method generates the following auditing event.

Validates whether the provided entitlement value is supported or not.

  • account-has-valid-entitlement.get

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group 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

  • entitlement
    Required*
    string

    The entitlement value to check if it is supported.

Response

Response Body

HasValidEntitlementResponse

HasValidEntitlementResponse contains the information if the requested entitlement is supported or not

Status Code

  • 200

    Ok. The entitlement validation request was successfully processed.

  • 400

    The entitlement option can not be set when the stored API key has a subtype. For more information, see 'http://ibm.biz/api-key'.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 500

    Could not connect to the back-end billing validation service. Try again later.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A worker pool is rebalanced.

  • containers-kubernetes.workerpool.rebalance

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Request Body

RebalanceWorkerPool

Fields required to rebalance the worker pool.

Response

Status Code

  • 204

    OK. The request to balance the worker pool was successfully received.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Refresh the Kubernetes master.

Restart the Kubernetes master in the cluster to apply changes to the API server configuration.

POST /v2/refreshMaster

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A cluster master refresh is requested.

  • containers-kubernetes.cluster-master.refresh

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*
RefreshMaster

Input parameters to refresh master. The cluster ID or name is required.

Response

Status Code

  • 204

    Ok. The Master will be put into the desired state.

  • 400

    Bad Request. Check that all headers are present and the cluster ID or name is provided.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster. To list the clusters that you have access to, use the GET /vpc/v2/clusters API or run ibmcloud ks cluster ls --provider vpc-classic.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Removes a dedicated host.

Removes a dedicated host.

POST /v2/removeDedicatedHost

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To remove a dedicated host, you must have the Operator platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.account-dedicated-host.delete

Auditing

Calling this method generates the following auditing event.

A worker pool is deleted.

  • containers-kubernetes.account-dedicated-host.delete

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*
DeleteDedicatedHost

The dedicated host to target in a given dedicated host pool.

Response

Status Code

  • 204

    OK. The request to remove your dedicated host was successfully received.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 500

    Internal Server Error. 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

This method does not specify any sample responses.

Removes a dedicated host pool.

Removes a dedicated host pool.

POST /v2/removeDedicatedHostPool

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To remove a dedicated host pool, you must have the Operator platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.account-dedicated-host-pool.delete

Auditing

Calling this method generates the following auditing event.

A worker pool is deleted.

  • containers-kubernetes.account-dedicated-host-pool.delete

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*
RemoveDedicatedHostPool

The dedicated host pool to target.

Response

Status Code

  • 204

    OK. The request to remove your dedicated host pool was successfully received.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 500

    Internal Server Error. 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

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A worker node is deleted from the cluster.

  • containers-kubernetes.worker.delete

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Request Body

Required*
RemoveWorker

Input parameters to remove a worker node. The cluster and worker node ID parameters are required.

Response

Status Code

  • 204

    Ok. The worker node was successfully removed from your cluster.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    The specified cluster or worker node could not be found. To list the clusters that you have access to, use the GET /v2/clusters API or run ibmcloud ks cluster ls. To list worker nodes in the cluster, use the GET /v2/getWorkers API or run ibmcloud ks worker ls -c <cluster_name>.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A worker pool is deleted.

  • containers-kubernetes.workerpool.delete

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Request Body

Required*
RemoveWorkerPool

The cluster and worker pool to target.

Response

Status Code

  • 204

    OK. The request to remove your worker pool was successfully received.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A zone is deleted from a worker pool.

  • containers-kubernetes.zone.delete

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Request Body

Required*
RemoveWorkerPoolZoneReq

The input parameter to specify the cluster, worker pool, and zone.

Response

Status Code

  • 204

    OK. The request to remove the zone from your worker pool was successfully received..

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A worker pool is resized, to add or decrease the number of worker nodes in the pool.

  • containers-kubernetes.cluster-worker-pool.resize

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Request Body

Required*
ResizeWorkerPool

The resize request.

Response

Status Code

  • 202

    Accepted. The worker pool will be resized to the specified value.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

Kubernetes labels for a worker pool are set. Existing and future worker nodes in the worker pool inherit the label.

  • containers-kubernetes.cluster-worker-pool-label.set

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Request Body

Required*
SetWorkerPoolLabels

Labels to apply to the worker pool and each of its worker nodes. To apply a custom label to the worker pool, set the "state" field to "labels" and fill in the "labels" section with your label key-value pairs. When you apply a label, all existing custom labels are replaced. If you have existing custom labels that you want to keep, include them in your request. To remove a custom label, set the "state" field to "labels" and in the "labels" section, include the same "key" field, but leave the value field blank "". Note that you must not edit the system-provided labels that that come with the worker pool and worker nodes by default, or you might experience unexpected results.

Response

Status Code

  • 204

    OK. The request to set the labels of the worker pool was successfully received.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

Kubernetes taints for a worker pool are set. Existing and future worker nodes in the worker pool inherit the taint.

  • containers-kubernetes.cluster-worker-pool-taint.set

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Request Body

Required*
SetWorkerPoolTaints

Taints to apply to the worker pool and each of its worker nodes. To apply a custom taint to the worker pool, set the "state" field to "taints" and fill in the "taints" section with your taint key-value pairs where the value contains the taint value and the taint effect separated by a ":" with valid taint effects being "NoSchedule", "PreferNoSchedule", and "NoExecute". When you apply a taint, all existing custom taints are replaced. If you have existing custom taints that you want to keep, include them in your request. To remove a custom taint, set the "state" field to "taints" and in the "taints" section, include the same "key" field, but leave the value field blank "".

Response

Status Code

  • 204

    OK. The request to set the taints of the worker pool was successfully received.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Create a 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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

The creation of a cluster is requested.

  • containers-kubernetes.cluster.create

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Refresh-Token
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers.

  • X-Auth-Resource-Group
    string

    The ID of the resource group to create the cluster in. To list available resource groups, run ibmcloud resource groups. If you don't include this header, the cluster is created in the default resource group. After you create a cluster, you cannot change the resource group. Note that if you plan to integrate IBM Cloud services with the cluster, all the resources must be in the same group.

Request Body

Required*
VPCCreateCluster

Input parameter to add a cluster. For more information, see https://ibm.biz/cluster_create_docs

Response

Response Body

CreateClusterResponse

Status Code

  • 201

    Created. The cluster was successfully created in the IBM Cloud account that you are logged in to.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.

  • 409

    Conflict. A cluster with the same name already exists. Choose another name for your cluster.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A worker pool is created in the cluster.

  • containers-kubernetes.cluster-worker-pool.create

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Refresh-Token
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*
v2VPCCreateWorkerPoolRequest

The

Response

Response Body

CreateWorkerpoolResponse

Status Code

  • 201

    Created. The worker pool was successfully created in for the specified cluster.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 409

    Conflict. A worker pool create may already be in progress for the provided cluster. Please wait a few minutes and try again.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A zone is added to a worker pool.

  • containers-kubernetes.cluster-worker-pool-zone.create

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Refresh-Token
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers.

  • X-Auth-Resource-Group
    string

    The ID of the resource group to create the cluster in. To list available resource groups, run ibmcloud resource groups. If you don't include this header, the cluster is created in the default resource group. After you create a cluster, you cannot change the resource group. Note that if you plan to integrate IBM Cloud services with the cluster, all the resources must be in the same group.

Request Body

Required*
CreateWorkerpoolZoneRequest

Input parameters to add zones to the worker pool.

Response

Status Code

  • 201

    OK. The requested zone has been added to the worker pool.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls mycluster.

  • 409

    Conflict. The provided zone already exists in the worker pool.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Get details of a VPC cluster.

Get details of a VPC cluster.

GET /v2/vpc/getCluster

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM. For more required permissions to create a cluster, see 'https://cloud.ibm.com/docs/containers?topic=containers-access_reference'.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Details for a cluster are returned.

  • containers-kubernetes.cluster.get

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • showResources
    string

    To view additional cluster resources like addons, VLANs, subnets, and storage, pass true.

Response

Response Body

GetClusterResponse

Status Code

  • 200

    Success. Detailed cluster information.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

List the VPC clusters that you have access to.

List the VPC clusters that you have access to.

GET /v2/vpc/getClusters

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group to list clusters for. To list available resource groups, run ibmcloud resource groups. If you don't include this header, all the clusters in the account that you have access to are listed.

Query Parameters

  • location
    string

    Specify a location to filter clusters for. To see supported locations, use the GET /v1/locations API or run ibmcloud ks locations.

  • provider
    string

    The name of the provider to filter the clusters by.

Response

Response Body

GetClustersResponse[]

GetClustersResponse cluster response for cluster list

Status Code

  • 200

    Success. A list of clusters that you have access to is returned.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

View subnets for a given VPC.

View details for subnets in a VPC for the given region and provider.

GET /v2/vpc/getSubnets

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The VPC subnets for a cluster are listed.

  • containers-kubernetes.cluster-subnet.list

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

  • provider
    Required*
    string

    The name of the VPC provider.

  • zone
    Required*
    string

    The name of the zone in which to list subnets.

  • vpc
    Required*
    string

    The ID of the VPC.

Response

Response Body

Subnet[]

Subnet provides information about a vpc subnet

Status Code

  • 200

    Ok. A list of all subnets for the given VPC is returned.

  • 400

    Bad Request. The given provider, zone, or VPC is invalid.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

View details of a VPC.

View details of a virtual private cloud (VPC).

GET /v2/vpc/getVPC

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Details for a virtual private cloud (VPC) instance are returned.

  • containers-kubernetes.account-vpc.get

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Region
    Required*
    string

    The region of the VPC. To list regions, run ibmcloud ks regions.

  • X-Auth-Resource-Group
    string

    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

  • provider
    Required*
    string

    The name of the infrastructure provider that the VPC is created in. To list infrastructure providers of a VPC, run ibmcloud ks vpcs or use the GET /v2/vpc/getVPCs API.

  • vpcID
    Required*
    string

    The ID of the VPC. To list the ID of a VPC, run ibmcloud ks vpcs or use the GET /v2/vpc/getVPCs API.

Response

Response Body

GetVPCResponse

GetVPC defines a response when getting a VPC

Status Code

  • 200

    OK. Details of the specified VPC are returned.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

View VPCs for the given provider.

View details for all VPCs in the given provider

GET /v2/vpc/getVPCs

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Virtual private cloud (VPC) instances in the IBM Cloud account are listed.

  • containers-kubernetes.account-vpc.list

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    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

  • provider
    Required*
    string

    The name of the provider in which to list VPCs.

Response

Response Body

VirtualPrivateCloudResponse[]

Using the full name to avoid the linter complaining about stutter.

Status Code

  • 200

    Ok. A list of all VPCs is returned.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified VPC infrastructure provider.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

View details of a worker node for VPC cluster.

View detailed information for a worker node in a VPC cluster.

GET /v2/vpc/getWorker

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

View details of a worker node in the cluster.

  • containers-kubernetes.worker.get

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • worker
    Required*
    string

    The ID of the worker node that you want details for. To list all worker nodes for a cluster, use the GET /v1/clusters/{idOrName}/workers API or run ibmcloud ks worker ls --cluster <cluster_name_or_ID>.

Response

Response Body

GetWorkerResponse

Status Code

  • 200

    Ok. Detailed information about the worker node is returned.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

View details of a worker pool for a VPC cluster.

View detailed information for a worker pool in a VPC cluster.

GET /v2/vpc/getWorkerPool

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The details of a worker pool in the cluster are returned.

  • containers-kubernetes.cluster-worker-pool.get

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Region
    string

    If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • workerpool
    Required*
    string

    The ID of the worker pool that you want details for. To list all worker pools for a cluster, use the GET /v1/clusters/{idOrName}/workerpools API or run ibmcloud ks worker-pool ls --cluster <cluster_name_or_ID>.

Response

Response Body

GetVPCWorkerPoolResponse

Status Code

  • 200

    Ok. Detailed information about the worker pool is returned.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

List the worker pools in a VPC cluster.

GET /v2/vpc/getWorkerPools

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The worker pools for a cluster are listed.

  • containers-kubernetes.cluster-worker-pool.list

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Region
    string

    If you are using the global endpoint, target the Kubernetes Service region. To list available regions, use the GET /v1/regions API or run ibmcloud ks region ls.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

GetVPCWorkerPoolResponse[]

Status Code

  • 200

    Ok. Detailed information about the worker pools is returned.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

View all workers for VPC cluster.

View detailed information for all worker nodes in a VPC cluster.

GET /v2/vpc/getWorkers

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The worker nodes for a cluster are listed.

  • containers-kubernetes.cluster-worker.list

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the worker node details from. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • showDeleted
    string

    true|false Shows deleted workers

  • pool
    string

    The name or ID of the worker pool to filter results for. Run ibmcloud ks worker-pool ls --cluster <cluster name>.

Response

Response Body

GetWorkerResponse[]

Status Code

  • 200

    Ok. Details for all workers in the VPC cluster.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

List available 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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

No IBM Cloud IAM role is required for this operation.

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

Custom Headers

  • Authorization
    string

    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.

  • X-Auth-Refresh-Token
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers.

Query Parameters

  • provider
    string

    The provider for which to list zones. Defaults to vpc-classic.

  • showFlavors
    boolean

    Determines whether to show the flavors for the returned zones.

Response

Response Body

ZoneResponse[]

Zones sortable list of zone responses

Status Code

  • 200

    Success. A list of available zones for a region is returned.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    No zones found for provider. Run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A worker node is removed and another worker node of the same flavor is created in the cluster.

  • containers-kubernetes.worker.replace

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*
ReplaceWorkerRequest

Input parameters to replace a worker node. The cluster and worker node ID parameters are required. The update parameter is optional. To update the worker node to the same major and minor version as the master, set “update” to true.

Response

Status Code

  • 204

    OK. The worker node is being removed and replaced with a new worker node.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster or worker could not be found. To list the clusters that you have access to, use the GET /vpc/v2/clusters API or run ibmcloud ks cluster ls --provider vpc-classic.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

V2DisableImageSecurity

Disable image security enforcement for a cluster

POST /v2/disableImageSecurity

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*
ImageSecurity

Input parameters to specify the name or ID of the cluster that you want to disable image security enforcement in.

Response

Status Code

  • 204

    Ok. The request to update your master node was successfully processed.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

V2EnableImageSecurity

Enable image security enforcement for a cluster

POST /v2/enableImageSecurity

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*
ImageSecurity

Input parameters to specify the name or ID of the cluster that you want to enable image security enforcement in.

Response

Status Code

  • 204

    Ok. The request to update your master node was successfully processed.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To change the Pod Security Policy admission controller configuration, you must have the Administrator platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

The Pod Security Policy admission controller is disabled.

  • containers-kubernetes.cluster-pod-security.disable

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*
DisablePodSecurityPolicyRequest

The cluster to target.

Response

Status Code

  • 204

    OK. The request to disable the Pod Security Policy admission controller was successfully received.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
    Bad Request. Your cluster must run Kubernetes version 1.24 to change the Pod Security Policy admission controller.
    Bad Request. Cannot disable the Pod Security Policy admission controller when the Pod Security admission controller is disabled.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To change the Pod Security Policy admission controller configuration, you must have the Administrator platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

The Pod Security Policy admission controller configuration is updated.

  • containers-kubernetes.cluster-pod-security-policy.enable

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*
EnablePodSecurityPolicyRequest

The cluster to target.

Response

Status Code

  • 204

    OK. The request to enable the Pod Security Policy admission controller was successfully received.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
    Bad Request. Your cluster must run Kubernetes version 1.24 to change the Pod Security Policy admission controller.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

No Sample Response

This method does not specify any sample responses.

View the Pod Security admission control configuration for a cluster.

View the Pod Security admission control configuration for a cluster.

GET /v2/getPodSecurity

Auditing

Calling this method generates the following auditing event.

View the Pod Security admission control configuration for a cluster.

  • containers-kubernetes.cluster-pod-security.get

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the Pod Security admission control configuration for. To list the clusters that you have access to, use the GET /v2/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

PodSecurityResponse

PodSecurityResponse represents the configuration of the cluster PodSecurity admission controller

Status Code

  • 200

    Ok. The request to view the Pod Security admission control configuration was successfully processed.

  • 400

    Bad Request. Required parameters were not set. You must provide the cluster query parameter.
    Bad Request. Pod Security admission is supported only for Kubernetes v1.24 or later clusters.
    Bad Request. Pod Security admission is not supported for Red Hat OpenShift clusters.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

No Sample Response

This method does not specify any sample responses.

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

Auditing

Calling this method generates the following auditing event.

View the Pod Security Policy admission control configuration for a cluster that runs Kubernetes version 1.24.

  • containers-kubernetes.cluster-pod-security-policy.get

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster that you want to get the Pod Security admission control configuration for. To list the clusters that you have access to, use the GET /v2/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

PodSecurityPolicyResponse

PodSecurityPolicyResponse represents the state of the cluster PodSecurityPolicy admission controller

Status Code

  • 200

    Ok. The request to view Pod Security Policy admission control configuration was successfully processed.

  • 400

    Bad Request. Required parameters were not set. You must provide the cluster query parameter.
    Bad Request. Pod Security admission configuration is not supported for OpenShift clusters.
    Bad Request. Your cluster must run Kubernetes version 1.24 to remove the Pod Security admission controller or to change the Pod Security Policy admission controller.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To change the Pod Security admission controller configuration, you must have the Administrator platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

The Pod Security admission controller configuration is removed.

  • containers-kubernetes.cluster-pod-security.remove

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*
RemovePodSecurityRequest

The cluster to target.

Response

Status Code

  • 204

    OK. The request to remove the Pod Security admission controller configuration was successfully received.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
    Bad Request. Your cluster must run Kubernetes version 1.24 to remove the Pod Security admission controller or to change the Pod Security Policy admission controller.
    Bad Request. Cannot disable the Pod Security admission controller when the Pod Security Policy admission controller is disabled.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To change the Pod Security admission controller configuration, you must have the Administrator platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

The Pod Security admission controller configuration is updated.

  • containers-kubernetes.cluster-pod-security.set

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*
SetPodSecurityRequest

The cluster to target.

Response

Status Code

  • 204

    OK. The request to set the Pod Security admission controller configuration was successfully received.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.
    Bad Request. Your cluster must run Kubernetes version 1.24 or later to modify the Pod Security admission configuration.
    Bad Request. Pod Security admission is not supported for Red Hat OpenShift clusters.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

No Sample Response

This method does not specify any sample responses.

Disables a private service endpoint for a cluster.

POST /v2/disablePrivateServiceEndpoint

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

The private service endpoint for a cluster is disabled.

  • containers-kubernetes.cluster-private-service-endpoint.disable

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*
UpdateServiceEndpoint

Input parameters to specify the name or ID of the cluster and which service endpoint to update. Valid service endpoints are public or private.

Response

Status Code

  • 204

    Ok. The request to update your master node was successfully processed.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Disables a public service endpoint for a cluster.

POST /v2/disablePublicServiceEndpoint

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

The public service endpoint for a cluster is disabled.

  • containers-kubernetes.cluster-public-service-endpoint.disable

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*
UpdateServiceEndpoint

Input parameters to specify the name or ID of the cluster and which service endpoint to update. Valid service endpoints are public or private.

Response

Status Code

  • 204

    Ok. The request to update your master node was successfully processed.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Enables the private service endpoint for a cluster.

POST /v2/enablePrivateServiceEndpoint

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

The private service endpoint for a cluster is enabled.

  • containers-kubernetes.cluster-private-service-endpoint.enable

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*
UpdateServiceEndpoint

Input parameters to specify the name or ID of the cluster and which service endpoint to update. Valid service endpoints are public or private.

Response

Status Code

  • 204

    Ok. The request to update your master node was successfully processed.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Enables the public service endpoint for a cluster.

POST /v2/enablePublicServiceEndpoint

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Administrator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.create

Auditing

Calling this method generates the following auditing event.

The public service endpoint for a cluster is enabled.

  • containers-kubernetes.cluster-public-service-endpoint.enable

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*
UpdateServiceEndpoint

Input parameters to specify the name or ID of the cluster and which service endpoint to update. Valid service endpoints are public or private.

Response

Status Code

  • 204

    Ok. The request to update your master node was successfully processed.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Create an image pull secret to IBM Cloud Container Registry in the `default` namespace of the cluster. Note that this API method also requires the Administrator platform role to IBM Cloud Container Registry.

POST /v2/enablePullSecret

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service and Administrator platform role to Container Registry in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

An image pull secret is created in the default namespace of the cluster.

  • containers-kubernetes.cluster-pull-secret.enable

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*
EnablePullSecret

Input parameters to specify the name or ID of the cluster and which to enable pull secrets for.

Response

Status Code

  • 204

    Ok. The request to update your master node was successfully processed.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

No Activity Tracker event is generated for this operation.

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

IKSVersion[]

IKSVersion the IKS version

Status Code

  • 200

    Success. Available container management platform versions for the IBM Cloud Kubernetes Service region are returned.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A worker node is removed and another worker node of the same flavor is created in the cluster.

  • containers-kubernetes.worker.replace

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of a VPC cluster, use the GET /v2/vpc/getCluster?cluster=idOrName API.

Request Body

Required*
ReplaceWorkerRequest

Input parameters to replace a worker.

Response

Status Code

  • 204

    OK. The worker node is being removed and replaced with a new worker node.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster or worker could not be found. To list the VPC clusters that you have access to, use the GET /vpc/v2/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Update the 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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A cluster master update is requested.

  • containers-kubernetes.cluster-master.update

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v1/clusters/idOrName API.

Request Body

Required*
UpdateMaster

Input parameters to specify the name or ID of the cluster, what version to update the master to, and whether to force the update. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Status Code

  • 204

    Ok. The request to update your master node was successfully processed.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Forbidden. The cluster cannot be updated. The master is more than two versions behind the targeted version, which is not supported. Instead, update to a supported version two or less ahead of the current version, or create a new cluster at the targeted version.

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 409

    Conflict. The specified value is already set on the cluster. To list the clusters properties, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To call this endpoint, you must have the Editor platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

A health monitor config was updated.

  • cluster-nlb-dns-monitor.create

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*
HealthMonitorConfiguration

The full health monitoring configuration to overwrite the current configuration with. The configuration is defined in the corresponding provider specific field.

Response

Status Code

  • 204

    Ok. The request to update the health monitor config was successfully processed.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster or NLB subdomain could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*
SecretConfig

Include the NLB subdomain that you want to delete the secret for, and the cluster that the subdomain is in.

Response

Status Code

  • 204

    Deleted. The secret name was successfully deleted for the NLB subdomain.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster, subdomain, or secret could not be found. To list clusters you have access to, run ibmcloud ks cluster ls. To list existing NLB subdomains and associated secret names, run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_id>.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To call this endpoint, you must have the Viewer platform role for the Kubernetes Service in IAM.

  • containers-kubernetes.cluster.update

Auditing

Calling this method generates the following auditing event.

A health monitor config was returned.

  • cluster-nlb-dns-monitor.get

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • nlbSubdomain
    Required*
    string

    The existing NLB subdomain that you want the monitor config for. To list existing NLB subdomains, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.

Response

Response Body

HealthMonitorConfiguration

HealthMonitorConfiguration is a common struct to be used in NLB health monitor related APIs

Status Code

  • 200

    OK. Current monitor config returned.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

Response

Response Body

NlbVPCListConfig[]

V2NlbList response for the get api for vpc clusters

Status Code

  • 200

    Ok. A list of NLB subdomains and associated details is returned for this cluster.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls.

  • nlbSubdomain
    Required*
    string

    The existing NLB subdomain that you want details for. To list existing NLB subdomains, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.

Response

Response Body

NlbVPCListConfig

NlbVPCListConfig single nlb subdomain in list response

Status Code

  • 200

    OK. Details of the NLB subdomain are returned.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    The specified cluster could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Query Parameters

  • controller
    Required*
    string

    To list available locations, use the GET /v2/satellite/getControllers API, or run ibmcloud sat location ls.

  • subdomain
    Required*
    string

    The existing subdomain that you want details for. To list existing subdomains, use the GET /v2/nlb-dns/getSatLocationSubdomains API or run ibmcloud sat location dns ls --cluster <cluster_name_or_ID>.

Response

Response Body

NlbConfig

NlbConfig config for NLB configuration

Status Code

  • 200

    OK. A list of subdomains and associated details is returned for this location. If no list is returned, you can assign hosts to your location and try again.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your IAM and UAA tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Could not find the IBM Cloud Satellite location. To list available locations, use the GET /v2/satellite/getControllers API, or run ibmcloud sat location ls.

  • 500

    Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

List 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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Query Parameters

  • controller
    Required*
    string

    To list available locations, use the GET /v2/satellite/getControllers API, or run ibmcloud sat location ls.

Response

Response Body

NlbVPCListConfig[]

V2NlbList response for the get api for vpc clusters

Status Code

  • 200

    OK. A list of NLB subdomains and associated details is returned for this location. If no list is returned, you can assign hosts to your location and try again.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Could not find the IBM Cloud Satellite location. To list available locations, use the GET /v2/satellite/getControllers API, or run ibmcloud sat location ls.

  • 500

    Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*
SecretConfig

Include the cluster and subdomain for the NLB subdomain that you want to remove the secret from.

Response

Status Code

  • 202

    The cert has been successfully triggered for regeneration.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster, subdomain, or secret could not be found. To list clusters you have access to, run ibmcloud ks cluster ls. To list existing NLB subdomains and relevant secret names, run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_id>.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Refresh-Token
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run ibmcloud iam oauth-tokens. This header may be omitted if you use the POST /v1/credentials API prior to this request.

Request Body

Required*
MSCRegistration

The input parameter to register a Multishift cluster's domains.

Response

Response Body

MSCRegisterResp

type MSCRegisterResp returned once multishift controller domains have been registered

Status Code

  • 200

    Registered. The multishift cluster domains and cname have been successfully registered.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster or NLB subdomain could not be found. To list the clusters that you have access to, use the GET /v1/clusters API or run ibmcloud ks cluster ls. To list existing NLB subdomains for a cluster, use the GET /clusters/{idOrName}/list API or run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_ID>.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*
NlbVPCConfig

Include only the cluster ID, existing lbHostname that you want to replace, and nlbSubdomain of the DNS record that you want to update.

Response

Response Body

NlbVPCConfig

NlbVPCConfig is the request and response body for the v2 vpc apis

Status Code

  • 200

    Ok. The request to update the load balancer hostname was successfully processed.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified VPC cluster, load balancer hostname, or NLB subdomain could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic. To list existing load balancer hostnames in a cluster, run kubectl get svc -n <namespace>. To list existing NLB subdomains, run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_id>.

  • 500

    Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*
NlbVPCConfig

Include the lbHostname parameter that specifies the VPC load balancer hostname that you want to register.

Response

Response Body

NlbVPCConfig

NlbVPCConfig is the request and response body for the v2 vpc apis

Status Code

  • 201

    Created. The NLB subdomain was successfully created and the VPC load balancer hostname is registered with DNS.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified VPC cluster or load balancer hostname could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic. To list existing load balancer hostnames in a cluster, run kubectl get svc -n <namespace>.

  • 500

    Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*
NlbVPCConfig

Include the cluster parameter (required) and the nlbSubdomain parameter (required) for the NLB subdomain that you want to remove the load balancer hostname from.

Response

Status Code

  • 204

    Removed. The load balancer hostname was successfully unregistered from the DNS record for the NLB subdomain.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM or UAA token is invalid or expired. To retrieve your UAA and IAM tokens, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified VPC cluster or NLB subdomain could not be found. To list the VPC clusters that you have access to, use the GET /v2/vpc/getClusters API or run ibmcloud ks cluster ls --provider vpc-classic. To list existing NLB subdomains, run ibmcloud ks nlb-dns ls --cluster <cluster_name_or_id>.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Create a Sysdig monitoring configuration for a cluster.

Create a monitoring configuration for your IBM Cloud Kubernetes Service cluster to automatically collect cluster and pod metrics, and send these metrics to your IBM Cloud Monitoring with Sysdig service instance. This API deploys a Sysdig agent as a Kubernetes daemonset in the ibm-observe namespace of your cluster. The agent collects cluster and pod metrics, such as the worker node CPU and memory usage, and the amount of incoming and outgoing network traffic for your pods. The agent then forwards the metrics to your IBM Cloud Monitoring with Sysdig service instance.

Note: Before you use this API, make sure that you have an existing IBM Cloud Monitoring with Sysdig service instance.

POST /v2/observe/monitoring/createConfig

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Refresh-Token
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json.

Request Body

Required*
ConfigBody

The input parameter to create the configmap for the Sysdig agent. The ingestionKey and privateEndpoint parameters are optional.

Response

Response Body

ConfigResponse

Status Code

  • 201

    Created. The Sysdig monitoring configuration was successfully created for your cluster.

  • 400

    Bad request. The query parameters or the input parameters in the request body are either incomplete or in the wrong format. Make sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve a new IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Unauthorized. The user does not have the correct IAM platform and service roles to complete this operation. Check with your IBM Cloud Administor for the correct permissions`.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Discover a Sysdig agent previously deployed in the cluster.

Discover a Sysdig agent previously deployed in the cluster and create a monitoring configuration for it.

POST /v2/observe/monitoring/discoverAgent

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens. This value is required if the API is invoked through a CURL command.

  • X-Auth-Refresh-Token
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. Required when the API is invoked through a CURL command.

Request Body

Required*
DiscoverConfig

The input parameter to discover a Sysdig agent. The cluster parameter is required.

Response

Response Body

ObsConfig

Status Code

  • 201

    Discovered. The monitoring configuration was successfully created for a discovered agent.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Make sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve a new IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Unauthorized. The user does not have the correct IAM platform and service roles to complete this operation. Check with your IBM Cloud Administor for the correct permissions`.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Show the details of an existing Sysdig monitoring configuration.

Retrieve information about an existing Sysdig monitoring configuration for your cluster. To use this API, you must provide the name or ID of the cluster and the IBM Cloud Monitoring with Sysdig service instance as query parameters in the format /getConfig?cluster={idOrName}\u0026instance={idOrName}.

GET /v2/observe/monitoring/getConfig

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Refresh-Token
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster for which you want to show details of an existing Sysdig monitoring configuration. To list available clusters, run ibmcloud ks cluster ls.

  • instance
    Required*
    string

    The name or ID of the Sysdig service instance that you configured for the cluster. To list available Sysdig service instances, run ibmcloud resource service-instances.

Response

Response Body

ObsConfig

Status Code

  • 200

    Ok. Information about the Sysdig monitoring configuration is returned.

  • 400

    Bad request. One or more query parameters are missing in your API request. Make sure to include all required parameters in your request.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve a new IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Unauthorized. The user does not have the correct IAM platform and service roles to complete this operation. Check with your IBM Cloud Administor for the correct permissions`.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

List all Sysdig monitoring configurations for a cluster.

Retrieve information about all Sysdig monitoring configurations that exist for a cluster. To use the API, you must provide the name or ID of the cluster as a query parameter in the format /getConfigs?cluster={idOrName}.

GET /v2/observe/monitoring/getConfigs

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Refresh-Token
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster for which you want to list existing Sysdig monitoring configurations. To list available clusters, run ibmcloud ks cluster ls.

Response

Response Body

ObsConfig[]

ObsConfigs is an array of all configmaps

Status Code

  • 200

    Ok. Information about existing Sysdig monitoring configurations is returned.

  • 400

    Bad request. The query parameter is missing or unknown query parameters were specified in your API request. Make sure to include all required parameters in your request.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve a new IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Unauthorized. The user does not have the correct IAM platform and service roles to complete this operation. Check with your IBM Cloud Administor for the correct permissions`.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Update a Sysdig monitoring configuration in the cluster.

Update an existing Sysdig monitoring configuration in the cluster. Changes can be made to the monitoring instance connected to the cluster, ingestion key, or use of public or private endpoints for the monitoring instance.

POST /v2/observe/monitoring/modifyConfig

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens. This value is required if the API is invoked through a CURL command.

  • X-Auth-Refresh-Token
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. Required when the API is invoked through a CURL command.

Request Body

Required*
ModifyBody

The input parameter to update the configmap for the Sysdig agent. The cluster and instance parameters are required.

Response

Response Body

ObsConfig

Status Code

  • 201

    Modified. The Sysdig monitoring configuration was successfully modified for your cluster.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Make sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve a new IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Unauthorized. The user does not have the correct IAM platform and service roles to complete this operation. Check with your IBM Cloud Administor for the correct permissions`.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Remove a Sysdig monitoring configuration from a cluster.

Remove an existing Sysdig monitoring configuration from a cluster. When you remove the monitoring configuration, pod and cluster metrics are no longer sent to your IBM Cloud Monitoring with Sysdig service instance. However, existing metrics are still available until your selected retention period ends. To use the API, you must provide the name or ID of the cluster and the Sysdig service instance as query parameters in the format /removeConfig?cluster={idOrName}\u0026instance={idOrName}.

POST /v2/observe/monitoring/removeConfig

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Refresh-Token
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json.

Request Body

Required*
DeleteConfig

The input parameter to remove the configmap from the cluster.

Response

Status Code

  • 200

    Ok. The Sysdig monitoring configuration was successfully removed from the cluster.

  • 400

    Bad request. One or more query parameters are missing or unknown query parameters were specified in your API request. Make sure to include all required parameters in your request.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve a new IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Unauthorized. The user does not have the correct IAM platform and service roles to complete this operation. Check with your IBM Cloud Administor for the correct permissions`.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Viewer platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

The rotation of the COS data of the cluster.

  • containers-kubernetes.cluster-cos-key.rotate

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Refresh-Token
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) refresh token. To retrieve your IAM refresh token, run cat ~/.bluemix/config.json. To use the POST https://iam.cloud.ibm.com/identity/token API to create a token, see https://ibm.biz/iks-tokens for the required request headers.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the cluster is in. To check the resource group ID of the cluster, use the GET /v2/getCluster API.

Query Parameters

  • cluster
    Required*
    string

    The name or ID of the cluster of which you want to rotate the COS data. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.

Response

Status Code

  • 204

    No Content. Indicates that the rotation was successful.

  • 400

    Bad request. The query parameters are either incomplete or in the wrong format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified cluster could not be found. To list the clusters that you have access to, use the GET /v2/getClusters API or run ibmcloud ks cluster ls.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Create an IBM Cloud 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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token.

  • X-Auth-Resource-Group
    string

    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/getController API method.

Request Body

Required*
MultishiftCreateCluster

The configuration details for your Satellite cluster, in JSON format. The "controller" field (required) is the name or ID of the location to deploy the cluster to. The "name" field (required) is the name to give the cluster. The "kubeVersion" field is optional, and defaults to the latest Red Hat OpenShift on IBM Cloud version when not specified.

Response

Response Body

MultishiftCreateClusterResponse

MultishiftCreateCluster create multishift cluster response

Status Code

  • 201

    Created. The cluster was successfully created in the IBM Cloud Satellite location.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.

  • 409

    Conflict. A cluster with the same name already exists. Choose another name for your cluster.

  • 500

    Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token.

  • X-Auth-Resource-Group
    string

    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/getController API method.

Request Body

Required*
v2SatelliteCreateWorkerPoolRequest

The configuration details for your worker pool, in JSON format.

Response

Response Body

CreateWorkerpoolResponse

Status Code

  • 201

    Created. The worker pool was successfully created in the specified cluster.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 409

    Conflict. Another worker pool might be provisioning for the specified cluster. Wait a few minutes and try again.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the GET /v2/satellite/getController API method.

Request Body

Required*
SatelliteWorkerPoolZoneAdd

Input parameters to add zones to the worker pool.

Response

Status Code

  • 201

    OK. The requested zone was added to the worker pool.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified worker pool could not be found. To list all worker pools for a cluster, use the GET /v2/getWorkerPools API or run ibmcloud ks worker-pool ls -c <cluster>.

  • 409

    Conflict. The provided zone already exists in the worker pool.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and your cluster ID, and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the GET /v2/satellite/getController API method.

Response

Response Body

GetClustersResponse[]

GetClustersResponse cluster response for cluster list

Status Code

  • 200

    Success. A list of clusters that you have access to is returned.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 500

    Internal Server Error. IBM Cloud 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

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    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.

  • X-Auth-Supplemental
    Required*
    string

    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.

  • X-Auth-Resource-Group
    string

    The ID of the resource group the cluster is to be created in.

Request Body

Required*
MultishiftCreateCluster

The configuration details for your Satellite cluster, in JSON format. The "controller" field (required) is the name or ID of the location to deploy the cluster to. The "name" field (required) is the name to give the cluster. The "kubeVersion" field is optional, and defaults to the latest Red Hat OpenShift on IBM Cloud version when not specified.

Response

Response Body

MultishiftCreateClusterResponse

MultishiftCreateCluster create multishift cluster response

Status Code

  • 201

    Created. The cluster was successfully created in the IBM Cloud Satellite location.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.

  • 409

    Conflict. A cluster with the same name already exists. Choose another name for your cluster.

  • 500

    Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the GET /v2/satellite/getController API method.

Query Parameters

  • controller
    Required*
    string

    The ID of the location to list services.

Response

Response Body

multishiftClustersResponse[]

MultishiftGetServiceClusters describes a multishift service clusters response

Status Code

  • 200

    Success. A list of Satellite-enabled service clusters that you have access to is returned.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 500

    Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token.

  • X-Auth-Resource-Group
    string

    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.

Request Body

Required*
MultishiftCreateController

The configuration details for your Satellite location, in JSON format.

Response

Response Body

MultishiftCreateControllerResponse

MultishiftCreateController create controller response

Status Code

  • 201

    Created. The location was successfully created in the IBM Cloud account that you are logged in to.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.

  • 409

    Conflict. A location with the same name already exists. Choose another name for your location.

  • 500

    Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the Satellite 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 the GET /v2/satellite/getController API method.

Query Parameters

  • controller
    Required*
    string

    The ID of the location to get information about.

Response

Response Body

MultishiftGetController

MultishiftGetController describes a multishift controller

Status Code

  • 200

    Success. The details of the requested IBM Satellite location are returned.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Could not find the IBM Cloud Satellite location. To list available locations, use the GET /v2/satellite/getControllers API, or run ibmcloud sat location ls.

  • 500

    Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group to filter Satellite locations for. To list available resource group IDs from the command line, run ibmcloud resource groups.

Response

Response Body

MultishiftController[]

MultishiftController describes an individual controller

Status Code

  • 200

    Success. A list of locations that you have access to is returned.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 500

    Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the GET /v2/satellite/getController API method.

Request Body

MultishiftCreateClusterFragment

The IBM Satellite location to remove.

Response

Status Code

  • 204

    OK. The request to remove your IBM Cloud Satellite location was successfully received.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Could not find the IBM Cloud Satellite location. To list available locations, use the GET /v2/satellite/getControllers API, or run ibmcloud sat location ls.

  • 409

    Conflict. Cannot delete an IBM Cloud Satellite location that has active clusters. To list the clusters in the Satellite location, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls.

  • 500

    Internal Server Error. IBM Cloud Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token.

  • X-Auth-Resource-Group
    string

    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/getController API method.

Request Body

Required*
MultishiftCreateAssignment

The configuration details to assign a host to an IBM Cloud Satellite resource, in JSON format. The "cluster" field (required) indicates the name or ID of the IBM Cloud Satellite resource to assign the host. The resource can be the name or ID of the Satellite location itself, or an IBM Cloud Satellite cluster. If "hostID" is specified, that host is assigned if it is available. If a set of "labels" is specified, all the available hosts are scanned to find a host that matches all the labels. If neither "hostID" nor "labels" are specified, a random available host is assigned.

Response

Response Body

MultishiftCreateAssignmentResponse

MultishiftCreateAssignment create multishift assignment response

Status Code

  • 201

    Created. A host was successfully assigned to your IBM Cloud Satellite resource.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.

  • 404

    Could not find the IBM Cloud Satellite location. To list available locations, use the GET /v2/satellite/getControllers API, or run ibmcloud sat location ls.

  • 409

    Conflict. Could not find any available hosts that match your requested host ID or label parameters.

  • 500

    Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token.

  • X-Auth-Resource-Group
    string

    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/getController API method.

Request Body

Required*
MultishiftNodeQueue

The configuration details to create an attachment script for your Satellite location, in JSON format. The "labels" field (required) is a set of key-value pairs to describe your host, such as cpu=4. Later, when you assign a host to IBM Cloud Satellite resources, these labels are used to match your host with your request.

Response

Status Code

  • 201

    Created. The response contains a script that you can run on your host to attach the host to your IBM Cloud Satellite location.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.

  • 404

    Could not find the IBM Cloud Satellite location. To list available locations, use the GET /v2/satellite/getControllers API, or run ibmcloud sat location ls.

  • 500

    Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

  • X-Auth-Resource-Group
    string

    The ID of the resource group that the Satellite location is in. To list the resource group ID of the location, use the GET /v2/satellite/getController API method.

Query Parameters

  • controller
    Required*
    string

    The ID of the location to to retrieve hosts from.

Response

Response Body

MultishiftQueueNode[]

MultishiftQueueNode describes an individual queue node

Status Code

  • 200

    Success. A list of hosts in your IBM Cloud Satellite location is returned.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Could not find the IBM Cloud Satellite location. To list available locations, use the GET /v2/satellite/getControllers API, or run ibmcloud sat location ls.

  • 500

    Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token.

  • X-Auth-Resource-Group
    string

    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/getController API method.

Request Body

Required*
MultishiftRemoveNode

The configuration details to remove a host from an IBM Cloud Satellite location, in JSON format.

Response

Status Code

  • 204

    OK. The host was successfully removed from your IBM Cloud Satellite location.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.

  • 404

    Could not find the host. To list available hosts, use the GET /v2/satellite/hostqueue/getHosts API or run ibmcloud sat host ls.

  • 409

    Conflict. Cannot remove the host because a worker node runs on the host. Remove the worker node and try again.

  • 500

    Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token.

  • X-Auth-Resource-Group
    string

    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/getController API method.

Request Body

Required*
MultishiftUpdateNode

The configuration details to update a host to an IBM Cloud Satellite resource, in JSON format.

Response

Status Code

  • 204

    OK. The host was successfully updated.

  • 400

    Bad request. The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request in JSON format.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 403

    Forbidden. The credentials set for the region and resource group have insufficient permissions for the specified infrastructure provider.

  • 404

    Could not find the host. To list available hosts, use the GET /v2/satellite/hostqueue/getHosts API or run ibmcloud sat host ls.

  • 409

    Conflict. The labels cannot be updated because the host is already assigned to an IBM Cloud Satellite resource, such as a cluster.

  • 500

    Internal Server Error. IBM Cloud Satellite is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

createAttachment

Create volume attachment for a given worker

POST /v2/storage/createAttachment

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

  • X-Auth-Resource-Group-ID
    Required*
    string

    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>.

Request Body

Required*
VPCVolumeAttachmentConfig

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

Response Body

VolumeAttachment

Status Code

  • 201

    Ok. Attach request successfully accepted.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified worker could not be found. To list the workers, use the GET /v2/vpc/getWorkers API or run ibmcloud ks workers --cluster <clusterID or Name>.

  • 500

    Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Detach volume from given worker.

POST /v2/storage/deleteAttachment

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

  • X-Auth-Resource-Group-ID
    string

    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>.

Request Body

Required*
VPCVolumeAttachmentConfig

The config includes ID of the cluster, ID of the worker from which you want to detach volume, and the unique volume attachment ID for the attached volume. To list the clusters that you have access to, run ibmcloud ks clusters. To list all worker nodes for a cluster, run ibmcloud ks workers <cluster_name_or_ID>.

Response

Status Code

  • 201

    Ok. detach request successfully accepted.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified worker could not be found. To list the workers, use the GET /v2/vpc/getWorkers API or run ibmcloud ks workers --cluster <clusterID or Name>.

  • 500

    Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

getAttachment

Get the volume attachment detail for given volume attachment ID

GET /v2/storage/getAttachment

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

  • X-Auth-Resource-Group-ID
    string

    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>.

Query Parameters

  • cluster
    Required*
    string

    The ID or name of the cluster. To list the clusters that you have access to, run ibmcloud ks clusters.

  • worker
    Required*
    string

    The ID of the worker node, whose volume attachments needs to be listed. To list all worker nodes for a cluster, run ibmcloud ks workers <cluster_name_or_ID>.

  • volumeAttachmentID
    Required*
    string

    The unique volume attachment ID for the attached volume

Response

Response Body

VolumeAttachment

Status Code

  • 200

    Ok.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified worker could not be found. To list the workers, use the GET /v2/vpc/getWorkers API or run ibmcloud ks workers --cluster <clusterID or Name>.

  • 500

    Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

getAttachments

Get the volume attachments detail for a given worker

GET /v2/storage/getAttachments

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

  • X-Auth-Resource-Group-ID
    string

    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>.

Query Parameters

  • cluster
    Required*
    string

    The ID or name of the cluster. To list the clusters that you have access to, run ibmcloud ks clusters.

  • worker
    Required*
    string

    The ID of the worker node, whose volume attachments needs to be listed.

Response

Response Body

VolumeAttachmentList

Status Code

  • 200

    Ok.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified worker could not be found. To list the workers, use the GET /v2/vpc/getWorkers API or run ibmcloud ks workers --cluster <clusterID or Name>.

  • 500

    Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Get the details of a storage volume.

GET /v2/storage/getVolume

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

  • X-Auth-Resource-Group-ID
    string

    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>.

Query Parameters

  • volumeID
    Required*
    string

    The unique volume ID. To list the volume ID, use the GET /v2/storage/classic/getVolumes API or run ibmcloud ks storage volume ls classic.

Response

Response Body

Volume

Volume Volume create/update/delete request

Status Code

  • 200

    Ok.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified worker could not be found. To list the workers, use the GET /v2/vpc/getWorkers API or run ibmcloud ks workers --cluster <clusterID or Name>.

  • 500

    Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

List storage volumes for a cluster or for the account if no cluster is provided.

GET /v2/storage/getVolumes

Request

Custom Headers

  • X-Auth-Resource-Group-ID
    Required*
    string

    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>.

  • Authorization
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • cluster
    string

    The ID or name of the classic cluster. To list the clusters that you have access to, run ibmcloud ks cluster ls --provider classic.

  • provider
    string

    Filter the list for a specific infrastructure provider. Supported values are classic, vpc-classic, and vpc-gen2.

  • zone
    string

    The zone to filter volume results by. To list available zones, run ibmcloud ks locations.

Response

Response Body

VolumesList

Status Code

  • 200

    Ok.

  • 401

    Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • 404

    Not found. The specified worker could not be found. To list the workers, use the GET /v2/vpc/getWorkers API or run ibmcloud ks workers --cluster <clusterID or Name>.

  • 500

    Internal Server Error. Kubernetes Service is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Read Satellite Location access in IAM.

  • satellite.location.read

Auditing

Calling this method generates the following auditing event.

A storage capacity expansion request is acknowledged.

  • satellite.storage-configuration.ack-desired-capacity

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*
AckDesiredStorageCapacityRequest

Include the ID of the storage request (request-id), the cluster ID (cluster) and the name or ID of the Satellite location (controller) that the cluster is registered to. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

Response

Status Code

  • 201

    OK. The storage request is created.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    The specified cluster or storage request could not be found. Check the input parameters and try again. Verify the input parameters and retry the request. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Subscription Create access in IAM.

  • satellite.config-subscription.create

Auditing

Calling this method generates the following auditing event.

An assignment is created.

  • satellite.subscription.create

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Request Body

Required*
CreateSubscriptionInputData

Include following parameters to create an assignment:

  1. Name of the assignment (name).
  2. Storage configuration name or ID (config). To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.
  3. The name or ID of the Satellite location (controller). To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllersAPI or run ibmcloud sat location ls.
  4. One or more cluster groups (groups) on which you want to apply the configuration. Note that at least one cluster group is required. To list the cluster groups that you have access to, run ibmcloud sat group ls.
  5. Enable or disable automatic upgrades for the assignment (autoUpgrade="true|false").

Response

Response Body

CreateSubscriptionData

Status Code

  • 200

    OK. An assignment using the storage configuration is created.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified config or cluster group(s) could not be found. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls. To list the Satellite cluster groups you have access to, run ibmcloud sat group ls.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Subscription Create access in IAM.

  • satellite.config-subscription.create

Auditing

Calling this method generates the following auditing event.

An assignment is created for a given cluster.

  • satellite.subscription.create-by-cluster

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Request Body

Required*
CreateSubscriptionByClusterInputData

Include following parameters to create an assignment:

  1. Name of the assignment (name).
  2. Storage configuration name or ID (config). To list the storage configurations for a location that you have access to, use the GET /v2/storage/satellite/getStorageConfigurationsByController API or run ibmcloud sat storage config ls --location LOCATION.
  3. ID of the Satellite cluster or service cluster that you want to apply the configuration to (cluster). To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
  4. The name or ID of the Satellite location (controller). To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllersAPI or run ibmcloud sat location ls.
  5. Enable or disable automatic upgrades for the assignment (autoUpgrade="true|false").

Response

Response Body

CreateSubscriptionData

Status Code

  • 200

    OK. An assignment using the storage configuration is created.

  • 400

    Bad Request. The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified config or cluster or location could not be found. To list the storage configurations for the location that you have access to, use the GET /v2/storage/satellite/getStorageConfigurationsByController API or run ibmcloud sat storage config ls --location LOCATION. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Request Body

Required*
StorageConfigCreateInput

Include a name for the storage configuration (config-name), the storage template name (storage-template-name), version (storage-template-version), required parameters as per the template specified (user-config-parameters, user-secret-parameters, and/or storage-class-parameters) and the Satellite location (location) where you want to use the storage configuration. To list the storage templates and template versions, run ibmcloud sat storage template ls. To list the parameters for a given storage template and template version, run ibmcloud sat storage template get --name=<template-name> --version=<template-version>. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Response

Response Body

CreateConfigurationData

CreateConfigurationData - a single return struct

Status Code

  • 201

    OK. The storage configuration is created.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Configuration Update access in IAM.

  • satellite.config-configuration.update

Auditing

Calling this method generates the following auditing event.

A storage configuration is created.

  • satellite.storage-configuration.create

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Request Body

Required*
StorageConfigCreateInput

Include a name for the storage configuration (config-name); the storage template name (storage-template-name), version (storage-template-version) (optionally; if unspecified, the default storage template version is picked), required parameters as per the template specified (user-config-parameters, user-secret-parameters, and/or storage-class-parameters) and ID of the Satellite location (controller) where you want to use the storage configuration. The update-assignments payload parameter may be ignored.

Enter a storage configuration name that is less than 253 characters long and contains only lowercase letters, numbers, -, or ..

To list the storage templates and template versions that you have access to, run ibmcloud sat storage template ls. To list the parameters for a given storage template and template version, run ibmcloud sat storage template get --name=<template-name> --version=<template-version>. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Response

Response Body

CreateConfigurationData

CreateConfigurationData - a single return struct

Status Code

  • 201

    OK. The storage configuration is created.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

The desired capacity of a storage request is increased.

  • satellite.storage-configuration.expand-desired

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*
ExpandDesiredStorageCapacityRequest

Include the ID of the storage request (request-id), the cluster ID (cluster) on which it is placed, and the desired total capacity (total-capacity). Specify the desired total capacity as a positive integer value in kilobytes (K), megabytes (M), gigabytes (G), terabytes (T) or exabytes (E). For example, specify 100G for 100 GB. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API. To list the Satellite clusters you have access to, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

Response

Status Code

  • 201

    OK. The storage request is created.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    The specified cluster or storage request could not be found. Check the input parameters and try again. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

To get the action, the user must have the Read Satellite Location access or the Viewer platform role to Kubernetes Service in IAM.

  • satellite.location.read

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Assigned storage configuration details is returned.

  • satellite.storage-configuration.get-assigned

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • cluster
    Required*
    string

    ID of the Satellite cluster or service cluster to list the assigned storage configurations for. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.

  • controller
    Required*
    string

    The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite.

Response

Response Body

AppliedStorageConfig[]

AppliedStorageConfig contains the details of an assigned storage config on a cluster A list of AppliedStorageConfig structs is the response for the GetAssignedStorageConfigs query

Status Code

  • 200

    OK. Assigned Satellite storage configurations are listed.

  • 400

    Bad Request. The request failed due to one of the following reasons:

    1. The cluster is missing or the specified cluster is invalid.
    2. The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified cluster or location could not be found. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

View details of an assignment.

View details of an assignment by the assignment UUID.

GET /v2/storage/satellite/getAssignment

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Subscription Read access in IAM.

  • satellite.config-subscription.read

Auditing

Calling this method generates the following auditing event.

The details of assignment are retrieved.

  • satellite.subscription.get

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • uuid
    Required*
    string

    The UUID of the assignment. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

Response

Response Body

Subscription

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

Status Code

  • 200

    OK. Assignment details are returned.

  • 400

    Bad Request. Either the uuid is missing or the specified uuid is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified assignment could not be found. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Subscription Read access in IAM.

  • satellite.config-subscription.read

Auditing

Calling this method generates the following auditing event.

An assignment is retrieved.

  • satellite.subscription.get-by-name

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • name
    Required*
    string

    The name of the assignment. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

Response

Response Body

Subscription

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

Status Code

  • 200

    OK. Assignment details successfully fetched.

  • 400

    Bad Request. Either the name is missing or the specified name is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified assignment could not be found. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Subscription Read access in IAM.

  • satellite.config-subscription.read

Auditing

Calling this method generates the following auditing event.

A list of assignments is retrieved.

  • satellite.subscription.list

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Response

Response Body

Subscription[]

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

Status Code

  • 200

    OK. Assignments are listed.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 500

    Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

To get the action, the user must have the Read Satellite Location access or the Viewer platform role to Kubernetes Service in IAM.

  • satellite.location.read

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

A list of assignments is retrieved by using the cluster ID.

  • satellite.subscription.get-by-clusterid

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • cluster
    Required*
    string

    ID of the Satellite cluster or service cluster to list the storage assignments for. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.

  • controller
    Required*
    string

    The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite.

Response

Response Body

Subscription[]

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

Status Code

  • 200

    OK. Assignments are listed.

  • 400

    Bad Request. The request failed due to one of the following reasons:

    1. The cluster is missing or the specified cluster is invalid. 2.The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified cluster or location could not be found. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

  • 500

    Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Organization Read access in IAM.

  • satellite.config-organization.read

Auditing

Calling this method generates the following auditing event.

An assignment is retrieved by using the associated configuration.

  • satellite.subscription.get-by-config

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • config
    Required*
    string

    The name or ID of the Satellite storage configuration. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.

Response

Response Body

Subscription[]

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

Status Code

  • 200

    OK. Assignments are listed.

  • 400

    Bad Request. Either the config is missing or the specified config is invalid. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified config could not be found. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.

  • 500

    Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Subscription Read access in IAM.

  • satellite.config-subscription.read

Auditing

Calling this method generates the following auditing event.

A list of assignments is retrieved by using a location.

  • satellite.subscription.get-by-controller

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • controller
    Required*
    string

    The name or ID of the Satellite location to list assignments for. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Response

Response Body

Subscription[]

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

Status Code

  • 200

    OK. Assignments are listed.

  • 400

    Bad Request. The controller is missing. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified location could not be found. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

  • 500

    Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

To get the action, the user must have the Read Satellite Location access or the Viewer platform role to Kubernetes Service in IAM.

  • satellite.location.read

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

A list of available storage classes for an assignment is retrieved.

  • satellite.available.classes.get

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • cluster
    Required*
    string

    The ID of the Satellite cluster or service cluster for which available storage classes from assigned Satellite storage configurations are to be listed. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.

  • controller
    Required*
    string

    The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite.

  • volumeType
    string

    Filter the available storage classes by volume type. The supported volume types are file, block and object. If unspecified, available storage classes of all volume types are returned.

  • onlyShowSDS
    boolean

    Specify true or false to view only the available storage classes from software-defined storage (SDS) storage configurations. If unspecified, the default value is true.

Response

Response Body

AvailableStorageClasses

AvailableStorageClasses contains a list of storage class names It is the response for GetAvailableStorageClasses query

Status Code

  • 200

    OK. Available storage classes are listed.

  • 400

    Bad Request. The request failed due to one of the following reasons:

    1. The cluster is missing or the specified cluster is invalid. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
    2. The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
    3. The specified value is an invalid value for parameter volumeType. Supported values for volumeType parameter are: file, block, object.
    4. The specified value is an invalid value for parameter onlyShowSDS. Supported values for onlyShowSDS parameter are: true, false.
  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified cluster or location could not be found. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

List Storage requests on a cluster.

List the storage requests for a cluster in a Satellite location.

GET /v2/storage/satellite/getDesiredStorageConfig

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

To get the action, the user must have the Read Satellite Location access or the Viewer platform role to Kubernetes Service in IAM.

  • satellite.location.read

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

A desired storage configuration is returned.

  • satellite.storage-configuration.get-desired

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Query Parameters

  • cluster
    Required*
    string

    The ID of the cluster where you want to list storage requests. To list the Satellite clusters you have access to, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>. The response body for each storage request contains the request specifications and the following fields:

    1. Theassignment field. This field is initially empty when the storage request is created. When the location administrator assigns a storage configuration to the cluster that matches the storage request, this field is populated with the UUID of the assignment.
    2. A status field in the config section that indicates the status of storage provisioning or assignment. If a storage assignment is created but no action is taken on it, the status is set to pending. If a storage configuration has been assigned to the cluster, the status is set to assigned. If the storage request is deleted, the status is set to deleted.
    3. A status field in the backend section. This field indicates whether the location administrator has acknowledged the request to increase storage capacity. If the storage capacity expansion request is not acknowledged, the status is set to pending. If the request is acknowledged by the location administrator, the status is set to completed.
  • controller
    Required*
    string

    The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

Response

Response Body

GetDesiredStorageConfigResponse[]

GetDesiredStorageConfigResponse is the respose body for getDesiredStorageConfig API

Status Code

  • 201

    OK. Storage requests are listed.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Could not list the IBM Cloud Satellite storage requests. Verify the input parameters and retry the request. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

  • 500

    Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

View details of a Satellite storage configuration.

View the details of a Satellite storage configuration.

GET /v2/storage/satellite/getStorageConfiguration

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Organization Read access in IAM.

  • satellite.config-organization.read

Auditing

Calling this method generates the following auditing event.

A storage configuration is retrieved.

  • satellite.storage-configuration.get

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • name
    Required*
    string

    The name of the storage configuration. To list the storage configurations that you have access to, run ibmcloud sat storage config ls.

  • include-assignments
    boolean

    Specify true to include details of assignment(s) of the specified storage configuration. The default value is false.

Response

Response Body

StorageConfig

Status Code

  • 201

    OK. Storage configuration details are returned.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • location
    string

    The name or ID of the Satellite location to list storage configurations for. If no location is specified, all storage configurations that you have access to in the IBM Cloud account are returned. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Response

Response Body

ListStorageConfigData[]

ListStorageConfigData is the response struct for the list storage configuration APIs i.e. getStorageConfigurations & getStorageConfigurationsByController

Status Code

  • 201

    OK. Storage configurations are listed.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 500

    Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Organization Read access in IAM.

  • satellite.config-organization.read

Auditing

Calling this method generates the following auditing event.

A list of storage configurations is retrieved by using a location.

  • satellite.storage-configuration.get-by-controller

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • controller
    Required*
    string

    The name or ID of the Satellite location to list storage configurations for. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Response

Response Body

ListStorageConfigData[]

ListStorageConfigData is the response struct for the list storage configuration APIs i.e. getStorageConfigurations & getStorageConfigurationsByController

Status Code

  • 201

    OK. Storage configurations are listed.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 500

    Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Read Satellite Location access in IAM.

  • satellite.location.read

Auditing

Calling this method generates the following auditing event.

A storage template is retrieved.

  • satellite.storage-template.get

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • name
    Required*
    string

    The name of the storage template. To list the storage templates that you have access to, use the GET v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.

  • version
    Required*
    string

    The version of the storage template. To list the storage templates that you have access to, use the GET v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.

Response

Response Body

RegisteredStorageVersion

Status Code

  • 200

    OK. Storage template details are returned.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 403

    Forbidden. User is not allowed to use the specified version of the storage template. To list the storage templates that you have access to, use the GET v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.

  • 404

    Not found. The specified storage template name or version could not be found. To list the storage templates that you have access to, use the GET v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.

  • 410

    The specified version of the storage template is unsupported. To list the storage templates that you have access to, use the GET v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Read Satellite Location access in IAM.

  • satellite.location.read

Auditing

Calling this method generates the following auditing event.

A storage template's changelog is retrieved.

  • satellite.storage-template.get-changelog

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Query Parameters

  • name
    string

    The name of the storage template that you want to get the change log for. To list the storage templates that you have access to, use the GET v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls. To get change logs for all storage templates that you have access to, skip this parameter.

Response

Response Body

RevisionLogForVersionResp

Status Code

  • 200

    OK. Change log(s) of the storage template(s) is/are returned.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified storage template could not be found. To list the storage templates that you have access to, use the GET v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.

  • 500

    Internal Server Error. Failed to fetch the changelog for the storage template. Note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

List Satellite storage templates.

List Satellite storage templates.

GET /v2/storage/satellite/getStorageTemplates

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Read Satellite Location access in IAM.

  • satellite.location.read

Auditing

Calling this method generates the following auditing event.

A list of storage templates is retrieved.

  • satellite.storage-template.list

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Response

Response Body

RegisteredStorage[]

Status Code

  • 200

    OK. Storage templates are listed.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 500

    Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Remove an assignment.

Remove an assignment with a given UUID.

DELETE /v2/storage/satellite/removeAssignment

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Subscription Delete access in IAM.

  • satellite.config-subscription.delete

Auditing

Calling this method generates the following auditing event.

An assignment is deleted.

  • satellite.subscription.delete

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • uuid
    Required*
    string

    ID of the assignment. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

  • controller
    Required*
    string

    The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllers API or run ibmcloud sat location ls.

Response

Response Body

RemoveSubscriptionData

Status Code

  • 200

    OK. The assignment is removed.

  • 400

    Bad Request. Either the uuid is missing or the specified uuid is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified assignment could not be found. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A storage request is deleted.

  • satellite.storage-configuration.delete-desired

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • request-id
    Required*
    string

    The ID of the storage request. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API.

  • cluster
    Required*
    string

    The ID of the cluster (cluster) on which the storage request is placed on. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API. To list the Satellite clusters you have access to, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

Response

Response Body

ErrorResponse

ErrorResponse error response to end users

Status Code

  • 201

    OK. The storage configuration is removed.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Configuration Update access in IAM.

  • satellite.config-configuration.update

Auditing

Calling this method generates the following auditing event.

A storage configuration is deleted.

  • satellite.storage-configuration.delete

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • uuid
    Required*
    string

    The UUID of the storage configuration. To list the storage configurations that you have access to, run ibmcloud sat storage config ls. To view the storage assignments associated with a given storage configuration and the storage configuration UUID, run ibmcloud sat config get --config=<storage-configuration-name>.

  • controller
    Required*
    string

    The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllers API or run ibmcloud sat location ls.

  • removeAssignments
    boolean

    Specify true to remove the storage configuration along with the associated assignments. If unspecified, the default value is false.

Response

Status Code

  • 200

    OK. The storage configuration is removed.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Subscription Update access in IAM.

  • satellite.config-subscription.update

Auditing

Calling this method generates the following auditing event.

An assignment is updated.

  • satellite.subscription.update

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Request Body

Required*
SetAssignmentAutoupgradeInputData

The parameters must include:

  1. Storage configuration name or ID (config).
  2. Satellite Location (controller).
  3. Set the autoUpgrade flag to true to enable assignments for automatic upgrades. If unspecified, it is assumed to be false.
  4. Either set All to enable/disable automatic upgrades for all the assignments of the storage configuration or provide the UUIDs to enable/disable automatic upgrades for a set of assignments.

Response

Response Body

SetAssignmentAutoupgradeInputData

Status Code

  • 200

    OK. The assignment(s) is/are enabled/disabled for automatic upgrades.

  • 400

    Bad Request. The request failed due to one of the following reasons:

    1. The config name/uuid is missing or the specified config is invalid. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.
    2. Both the parameters All and UUIDs are provided. Both cannot be provided at the same time.
    3. No assignment(s) provided to enable/disable automatic upgrade. Neither of the parameters All and UUIDs are provided.
    4. The assignment uuid provided in UUIDs parameter is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignmentsByConfig API or run ibmcloud sat storage assignment ls --config config.
  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The request failed due to one of the following reasons:

    1. The specified config could not be found. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.
    2. The specified assignment could not be found. To list the storage assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A desired storage configuration request is created.

  • satellite.storage-configuration.set-desired

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*
SetDesiredStorageConfigRequest

The configuration details for your Satellite storage request. Include the cluster ID (cluster) and the required storage specifications. To list available clusters in the Satellite location, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>. The following storage specifications are supported:

  1. Required: a. Volume type. Specify one of file, block or object. b. Provider. Specify one of the supported providers of storage templates. For a list of supported providers or templates, see https://github.com/IBM/ibm-satellite-storage/blob/develop/config-templates/template_list.json. c. Maximum volume size and total capacity. Specify a positive integer value. Use K for kilobytes, M for megabytes, G for gigabytes, T for terabytes, or E for exabytes. Example: 100G.
  2. Optional parameters. a. Offering type. Specify either sds for software-defined storage or non-sds. b. Volume encryption at rest. This is a boolean value. Specify true or false. c. Volume availability. This is a boolean value. Specify true or false. d. Volume expansion. This is a boolean value. Specify true or false. e. Volume snapshot. This is a boolean value. Specify true or false. f. Storage classes. Include a list of specific storage classes. Note that currently, requested storage classes are not strictly validated while provisioning storage.

See the following example payload for a storage request that specifies the cluster ID, volume type, offering type, provider, volume availability, volume expansion, volume snap shot, and storage classes: {"cluster": "c9l508rw0eo68tnbijrg","storage-requests": {"volume-type": "file","offering-type": "sds","provider": "redhat","volume-availability": "regional","volume-expansion": "true","volume-encryption-at-rest": "true","storageclasses": ["gold"],"volume-snapshot": "false","max-volume-size": "100G","total-capacity": "1T"}}

Response

Status Code

  • 201

    OK. The storage request is created.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Could not find the IBM Cloud Satellite cluster, volume type, available volume, or storage class. Verify the input parameters and try again. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Subscription Update access in IAM.

  • satellite.config-subscription.update

Auditing

Calling this method generates the following auditing event.

An assignment is updated.

  • satellite.subscription.update

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Request Body

Required*
UpdateSubscriptionInputData

The parameters must include the UUID of the assignment (uuid) along with at least one of the following parameters to be updated:

  1. One or more cluster groups (groups) on which you want to apply the configuration. To list the cluster groups that you have access to, run ibmcloud sat group ls.
  2. New name of the assignment (name).
  3. set the updateConfigVersion flag to true for updating an assignment to the latest available storage configuration version. If unspecified, it is assumed to be false. To see if assignment upgrade is available, use the GET /v2/storage/satellite/getAssignment API and look for isAssignmentUpgradeAvailable field in response or run ibmcloud sat storage assignment get --assignment UUID and look for Assignment Upgrade Available field in response.

Response

Response Body

UpdateSubscriptionData

Status Code

  • 200

    OK. The assignment is updated.

  • 400

    Bad Request. The request failed due to one of the following reasons:

    1. The uuid is missing or the specified uuid is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
    2. There is no parameter in the request body to update. Input at least one parameter to be updated.
    3. Storage assignment is already up to date with the latest available storage configuration version. Set the updateConfigVersion flag to false if you want to update at least assignment name or cluster group(s) on which you want to apply the configuration.
    4. 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).
  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified assignment or cluster group(s) could not be found. To list the storage assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls. To list the Satellite cluster groups you have access to, run ibmcloud sat group ls.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Request Body

Required*
StorageConfigUpdateInput

Include the storage template name (storage-template-name) and version (storage-template-version), the name of the existing storage configuration (config-name), the required parameters for the specified template (user-config-parameters, user-secret-parameters, and storage-class-parameters) and the Satellite location (location) where you want to use the storage configuration. To list the storage configurations that you have access to, run ibmcloud sat storage config ls. To view the storage assignments associated with a given storage configuration, run ibmcloud sat config get --config=<storage-configuration-name>. To list the storage templates and template versions, run ibmcloud sat storage template ls. To list the parameters for a given storage template and template version, run ibmcloud sat storage template get --name=<template-name> --version=<template-version>. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Response

Response Body

ErrorResponse

ErrorResponse error response to end users

Status Code

  • 201

    OK. The storage configuration is updated.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Configuration Update access in IAM.

  • satellite.config-configuration.update

Auditing

Calling this method generates the following auditing event.

A storage configuration is updated.

  • satellite.storage-configuration.update

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Request Body

Required*
StorageConfigUpdateInput

Include the name of the storage configuration (config-name) and the name or ID of the relevant Satellite location (controller). To apply the updated storage configuration to this storage configuration's existing assignments, set the update-assignments option to true. If left unspecified, the update-assignments option defaults to false.

If the storage configuration is assigned, only the configuration (user-config-parameters) and secret (user-secret-parameters) parameters that are marked as mutable can be updated. If the storage configuration is not assigned, all parameters can be updated.

If user-defined storage classes are supported, specify the required storage class parameters (storage-class-parameters) for the template that the storage configuration was created from. Note that any existing user-defined storage classes are overwritten by any storage classes specified in this API request's payload. For example, if you intend to define new storage classes and keep the existing storage classes, you must specify the parameters for both the existing and new user-defined storage classes.

To list the storage configurations that you have access to, run ibmcloud sat storage config ls. To view the storage assignments associated with a given storage configuration, run ibmcloud sat config get --config=<storage-configuration-name>. To list the parameters for a given storage template and template version, run ibmcloud sat storage template get --name=<template-name> --version=<template-version>. To list the parameters of existing storage classes, run ibmcloud sat storage config class ls --config=<storage-configuration-name> --show-params. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Response

Response Body

ErrorResponse

ErrorResponse error response to end users

Status Code

  • 201

    OK. The storage configuration is updated.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Configuration Update access in IAM.

  • satellite.config-configuration.update

Auditing

Calling this method generates the following auditing event.

A storage configuration is updated to the latest revision.

  • satellite.storage-configuration.update-revision

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Query Parameters

  • config
    Required*
    string

    The name or UUID of the storage configuration. To list the storage configurations that you have access to, run ibmcloud sat storage config ls.

  • controller
    Required*
    string

    The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllers API or run ibmcloud sat location ls.

  • updateAssignments
    boolean

    Specify true or false to update assignment(s) of the specified storage configuration. The default value is false.

Response

Response Body

ErrorResponse

ErrorResponse error response to end users

Status Code

  • 201

    OK. Updated storage configuration template to latest revision.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 406

    Storage configuration template is already up to date with the latest revision.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Read Satellite Location access in IAM.

  • satellite.location.read

Auditing

Calling this method generates the following auditing event.

A storage capacity expansion request is acknowledged.

  • satellite.storage-configuration.ack-desired-capacity

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*
AckDesiredStorageCapacityRequest

Include the ID of the storage request (request-id), the cluster ID (cluster) and the name or ID of the Satellite location (controller) that the cluster is registered to. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

Response

Status Code

  • 201

    OK. The storage request is created.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    The specified cluster or storage request could not be found. Check the input parameters and try again. Verify the input parameters and retry the request. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Subscription Create access in IAM.

  • satellite.config-subscription.create

Auditing

Calling this method generates the following auditing event.

An assignment is created.

  • satellite.subscription.create

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Request Body

Required*
CreateSubscriptionInputData

Include following parameters to create an assignment:

  1. Name of the assignment (name).
  2. Storage configuration name or ID (config). To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.
  3. The name or ID of the Satellite location (controller). To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllersAPI or run ibmcloud sat location ls.
  4. One or more cluster groups (groups) on which you want to apply the configuration. Note that at least one cluster group is required. To list the cluster groups that you have access to, run ibmcloud sat group ls.
  5. Enable or disable automatic upgrades for the assignment (autoUpgrade="true|false").

Response

Response Body

CreateSubscriptionData

Status Code

  • 200

    OK. An assignment using the storage configuration is created.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified config or cluster group(s) could not be found. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls. To list the Satellite cluster groups you have access to, run ibmcloud sat group ls.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Subscription Create access in IAM.

  • satellite.config-subscription.create

Auditing

Calling this method generates the following auditing event.

An assignment is created for a given cluster.

  • satellite.subscription.create-by-cluster

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Request Body

Required*
CreateSubscriptionByClusterInputData

Include following parameters to create an assignment:

  1. Name of the assignment (name).
  2. Storage configuration name or ID (config). To list the storage configurations for a location that you have access to, use the GET /v2/storage/satellite/getStorageConfigurationsByController API or run ibmcloud sat storage config ls --location LOCATION.
  3. ID of the Satellite cluster or service cluster that you want to apply the configuration to (cluster). To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
  4. The name or ID of the Satellite location (controller). To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllersAPI or run ibmcloud sat location ls.
  5. Enable or disable automatic upgrades for the assignment (autoUpgrade="true|false").

Response

Response Body

CreateSubscriptionData

Status Code

  • 200

    OK. An assignment using the storage configuration is created.

  • 400

    Bad Request. The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified config or cluster or location could not be found. To list the storage configurations for the location that you have access to, use the GET /v2/storage/satellite/getStorageConfigurationsByController API or run ibmcloud sat storage config ls --location LOCATION. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Request Body

Required*
StorageConfigCreateInput

Include a name for the storage configuration (config-name), the storage template name (storage-template-name), version (storage-template-version), required parameters as per the template specified (user-config-parameters, user-secret-parameters, and/or storage-class-parameters) and the Satellite location (location) where you want to use the storage configuration. To list the storage templates and template versions, run ibmcloud sat storage template ls. To list the parameters for a given storage template and template version, run ibmcloud sat storage template get --name=<template-name> --version=<template-version>. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Response

Response Body

CreateConfigurationData

CreateConfigurationData - a single return struct

Status Code

  • 201

    OK. The storage configuration is created.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Configuration Update access in IAM.

  • satellite.config-configuration.update

Auditing

Calling this method generates the following auditing event.

A storage configuration is created.

  • satellite.storage-configuration.create

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Request Body

Required*
StorageConfigCreateInput

Include a name for the storage configuration (config-name); the storage template name (storage-template-name), version (storage-template-version) (optionally; if unspecified, the default storage template version is picked), required parameters as per the template specified (user-config-parameters, user-secret-parameters, and/or storage-class-parameters) and ID of the Satellite location (controller) where you want to use the storage configuration. The update-assignments payload parameter may be ignored.

Enter a storage configuration name that is less than 253 characters long and contains only lowercase letters, numbers, -, or ..

To list the storage templates and template versions that you have access to, run ibmcloud sat storage template ls. To list the parameters for a given storage template and template version, run ibmcloud sat storage template get --name=<template-name> --version=<template-version>. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Response

Response Body

CreateConfigurationData

CreateConfigurationData - a single return struct

Status Code

  • 201

    OK. The storage configuration is created.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

The desired capacity of a storage request is increased.

  • satellite.storage-configuration.expand-desired

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*
ExpandDesiredStorageCapacityRequest

Include the ID of the storage request (request-id), the cluster ID (cluster) on which it is placed, and the desired total capacity (total-capacity). Specify the desired total capacity as a positive integer value in kilobytes (K), megabytes (M), gigabytes (G), terabytes (T) or exabytes (E). For example, specify 100G for 100 GB. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API. To list the Satellite clusters you have access to, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

Response

Status Code

  • 201

    OK. The storage request is created.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    The specified cluster or storage request could not be found. Check the input parameters and try again. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

To get the action, the user must have the Read Satellite Location access or the Viewer platform role to Kubernetes Service in IAM.

  • satellite.location.read

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

Assigned storage configuration details is returned.

  • satellite.storage-configuration.get-assigned

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • cluster
    Required*
    string

    ID of the Satellite cluster or service cluster to list the assigned storage configurations for. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.

  • controller
    Required*
    string

    The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite.

Response

Response Body

AppliedStorageConfig[]

AppliedStorageConfig contains the details of an assigned storage config on a cluster A list of AppliedStorageConfig structs is the response for the GetAssignedStorageConfigs query

Status Code

  • 200

    OK. Assigned Satellite storage configurations are listed.

  • 400

    Bad Request. The request failed due to one of the following reasons:

    1. The cluster is missing or the specified cluster is invalid.
    2. The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified cluster or location could not be found. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

View details of an assignment.

View details of an assignment by the assignment UUID.

GET /v2/storage/satellite/getAssignment

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Subscription Read access in IAM.

  • satellite.config-subscription.read

Auditing

Calling this method generates the following auditing event.

The details of assignment are retrieved.

  • satellite.subscription.get

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • uuid
    Required*
    string

    The UUID of the assignment. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

Response

Response Body

Subscription

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

Status Code

  • 200

    OK. Assignment details are returned.

  • 400

    Bad Request. Either the uuid is missing or the specified uuid is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified assignment could not be found. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Subscription Read access in IAM.

  • satellite.config-subscription.read

Auditing

Calling this method generates the following auditing event.

An assignment is retrieved.

  • satellite.subscription.get-by-name

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • name
    Required*
    string

    The name of the assignment. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

Response

Response Body

Subscription

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

Status Code

  • 200

    OK. Assignment details successfully fetched.

  • 400

    Bad Request. Either the name is missing or the specified name is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified assignment could not be found. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Subscription Read access in IAM.

  • satellite.config-subscription.read

Auditing

Calling this method generates the following auditing event.

A list of assignments is retrieved.

  • satellite.subscription.list

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Response

Response Body

Subscription[]

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

Status Code

  • 200

    OK. Assignments are listed.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 500

    Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

To get the action, the user must have the Read Satellite Location access or the Viewer platform role to Kubernetes Service in IAM.

  • satellite.location.read

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

A list of assignments is retrieved by using the cluster ID.

  • satellite.subscription.get-by-clusterid

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • cluster
    Required*
    string

    ID of the Satellite cluster or service cluster to list the storage assignments for. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.

  • controller
    Required*
    string

    The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite.

Response

Response Body

Subscription[]

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

Status Code

  • 200

    OK. Assignments are listed.

  • 400

    Bad Request. The request failed due to one of the following reasons:

    1. The cluster is missing or the specified cluster is invalid. 2.The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified cluster or location could not be found. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

  • 500

    Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Organization Read access in IAM.

  • satellite.config-organization.read

Auditing

Calling this method generates the following auditing event.

An assignment is retrieved by using the associated configuration.

  • satellite.subscription.get-by-config

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • config
    Required*
    string

    The name or ID of the Satellite storage configuration. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.

Response

Response Body

Subscription[]

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

Status Code

  • 200

    OK. Assignments are listed.

  • 400

    Bad Request. Either the config is missing or the specified config is invalid. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified config could not be found. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.

  • 500

    Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Subscription Read access in IAM.

  • satellite.config-subscription.read

Auditing

Calling this method generates the following auditing event.

A list of assignments is retrieved by using a location.

  • satellite.subscription.get-by-controller

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • controller
    Required*
    string

    The name or ID of the Satellite location to list assignments for. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Response

Response Body

Subscription[]

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

Status Code

  • 200

    OK. Assignments are listed.

  • 400

    Bad Request. The controller is missing. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified location could not be found. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

  • 500

    Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

To get the action, the user must have the Read Satellite Location access or the Viewer platform role to Kubernetes Service in IAM.

  • satellite.location.read

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

A list of available storage classes for an assignment is retrieved.

  • satellite.available.classes.get

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • cluster
    Required*
    string

    The ID of the Satellite cluster or service cluster for which available storage classes from assigned Satellite storage configurations are to be listed. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.

  • controller
    Required*
    string

    The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite.

  • volumeType
    string

    Filter the available storage classes by volume type. The supported volume types are file, block and object. If unspecified, available storage classes of all volume types are returned.

  • onlyShowSDS
    boolean

    Specify true or false to view only the available storage classes from software-defined storage (SDS) storage configurations. If unspecified, the default value is true.

Response

Response Body

AvailableStorageClasses

AvailableStorageClasses contains a list of storage class names It is the response for GetAvailableStorageClasses query

Status Code

  • 200

    OK. Available storage classes are listed.

  • 400

    Bad Request. The request failed due to one of the following reasons:

    1. The cluster is missing or the specified cluster is invalid. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
    2. The specified cluster is neither a Satellite cluster nor a service cluster. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION.
    3. The specified value is an invalid value for parameter volumeType. Supported values for volumeType parameter are: file, block, object.
    4. The specified value is an invalid value for parameter onlyShowSDS. Supported values for onlyShowSDS parameter are: true, false.
  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified cluster or location could not be found. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud ks cluster ls --provider=satellite. To list the service clusters for a location that you have access to, run ibmcloud sat services --location LOCATION. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

List Storage requests on a cluster.

List the storage requests for a cluster in a Satellite location.

GET /v2/storage/satellite/getDesiredStorageConfig

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

To get the action, the user must have the Read Satellite Location access or the Viewer platform role to Kubernetes Service in IAM.

  • satellite.location.read

  • containers-kubernetes.cluster.read

Auditing

Calling this method generates the following auditing event.

A desired storage configuration is returned.

  • satellite.storage-configuration.get-desired

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Query Parameters

  • cluster
    Required*
    string

    The ID of the cluster where you want to list storage requests. To list the Satellite clusters you have access to, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>. The response body for each storage request contains the request specifications and the following fields:

    1. Theassignment field. This field is initially empty when the storage request is created. When the location administrator assigns a storage configuration to the cluster that matches the storage request, this field is populated with the UUID of the assignment.
    2. A status field in the config section that indicates the status of storage provisioning or assignment. If a storage assignment is created but no action is taken on it, the status is set to pending. If a storage configuration has been assigned to the cluster, the status is set to assigned. If the storage request is deleted, the status is set to deleted.
    3. A status field in the backend section. This field indicates whether the location administrator has acknowledged the request to increase storage capacity. If the storage capacity expansion request is not acknowledged, the status is set to pending. If the request is acknowledged by the location administrator, the status is set to completed.
  • controller
    Required*
    string

    The name or ID of the Satellite location that the cluster is registered to. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

Response

Response Body

GetDesiredStorageConfigResponse[]

GetDesiredStorageConfigResponse is the respose body for getDesiredStorageConfig API

Status Code

  • 201

    OK. Storage requests are listed.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Could not list the IBM Cloud Satellite storage requests. Verify the input parameters and retry the request. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

  • 500

    Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

View details of a Satellite storage configuration.

View the details of a Satellite storage configuration.

GET /v2/storage/satellite/getStorageConfiguration

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Organization Read access in IAM.

  • satellite.config-organization.read

Auditing

Calling this method generates the following auditing event.

A storage configuration is retrieved.

  • satellite.storage-configuration.get

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • name
    Required*
    string

    The name of the storage configuration. To list the storage configurations that you have access to, run ibmcloud sat storage config ls.

  • include-assignments
    boolean

    Specify true to include details of assignment(s) of the specified storage configuration. The default value is false.

Response

Response Body

StorageConfig

Status Code

  • 201

    OK. Storage configuration details are returned.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • location
    string

    The name or ID of the Satellite location to list storage configurations for. If no location is specified, all storage configurations that you have access to in the IBM Cloud account are returned. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Response

Response Body

ListStorageConfigData[]

ListStorageConfigData is the response struct for the list storage configuration APIs i.e. getStorageConfigurations & getStorageConfigurationsByController

Status Code

  • 201

    OK. Storage configurations are listed.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 500

    Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Organization Read access in IAM.

  • satellite.config-organization.read

Auditing

Calling this method generates the following auditing event.

A list of storage configurations is retrieved by using a location.

  • satellite.storage-configuration.get-by-controller

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • controller
    Required*
    string

    The name or ID of the Satellite location to list storage configurations for. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Response

Response Body

ListStorageConfigData[]

ListStorageConfigData is the response struct for the list storage configuration APIs i.e. getStorageConfigurations & getStorageConfigurationsByController

Status Code

  • 201

    OK. Storage configurations are listed.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 500

    Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Read Satellite Location access in IAM.

  • satellite.location.read

Auditing

Calling this method generates the following auditing event.

A storage template is retrieved.

  • satellite.storage-template.get

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • name
    Required*
    string

    The name of the storage template. To list the storage templates that you have access to, use the GET v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.

  • version
    Required*
    string

    The version of the storage template. To list the storage templates that you have access to, use the GET v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.

Response

Response Body

RegisteredStorageVersion

Status Code

  • 200

    OK. Storage template details are returned.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 403

    Forbidden. User is not allowed to use the specified version of the storage template. To list the storage templates that you have access to, use the GET v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.

  • 404

    Not found. The specified storage template name or version could not be found. To list the storage templates that you have access to, use the GET v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.

  • 410

    The specified version of the storage template is unsupported. To list the storage templates that you have access to, use the GET v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Read Satellite Location access in IAM.

  • satellite.location.read

Auditing

Calling this method generates the following auditing event.

A storage template's changelog is retrieved.

  • satellite.storage-template.get-changelog

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Query Parameters

  • name
    string

    The name of the storage template that you want to get the change log for. To list the storage templates that you have access to, use the GET v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls. To get change logs for all storage templates that you have access to, skip this parameter.

Response

Response Body

RevisionLogForVersionResp

Status Code

  • 200

    OK. Change log(s) of the storage template(s) is/are returned.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified storage template could not be found. To list the storage templates that you have access to, use the GET v2/storage/satellite/getStorageTemplates API or run ibmcloud sat storage template ls.

  • 500

    Internal Server Error. Failed to fetch the changelog for the storage template. Note the incident ID and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

List Satellite storage templates.

List Satellite storage templates.

GET /v2/storage/satellite/getStorageTemplates

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Read Satellite Location access in IAM.

  • satellite.location.read

Auditing

Calling this method generates the following auditing event.

A list of storage templates is retrieved.

  • satellite.storage-template.list

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Response

Response Body

RegisteredStorage[]

Status Code

  • 200

    OK. Storage templates are listed.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 500

    Internal Server Error. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Remove an assignment.

Remove an assignment with a given UUID.

DELETE /v2/storage/satellite/removeAssignment

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Subscription Delete access in IAM.

  • satellite.config-subscription.delete

Auditing

Calling this method generates the following auditing event.

An assignment is deleted.

  • satellite.subscription.delete

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • uuid
    Required*
    string

    ID of the assignment. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

  • controller
    Required*
    string

    The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllers API or run ibmcloud sat location ls.

Response

Response Body

RemoveSubscriptionData

Status Code

  • 200

    OK. The assignment is removed.

  • 400

    Bad Request. Either the uuid is missing or the specified uuid is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified assignment could not be found. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A storage request is deleted.

  • satellite.storage-configuration.delete-desired

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • request-id
    Required*
    string

    The ID of the storage request. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API.

  • cluster
    Required*
    string

    The ID of the cluster (cluster) on which the storage request is placed on. To list storage requests, use the /v2/satellite/getDesiredStorageConfig API. To list the Satellite clusters you have access to, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

Response

Response Body

ErrorResponse

ErrorResponse error response to end users

Status Code

  • 201

    OK. The storage configuration is removed.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Configuration Update access in IAM.

  • satellite.config-configuration.update

Auditing

Calling this method generates the following auditing event.

A storage configuration is deleted.

  • satellite.storage-configuration.delete

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • uuid
    Required*
    string

    The UUID of the storage configuration. To list the storage configurations that you have access to, run ibmcloud sat storage config ls. To view the storage assignments associated with a given storage configuration and the storage configuration UUID, run ibmcloud sat config get --config=<storage-configuration-name>.

  • controller
    Required*
    string

    The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllers API or run ibmcloud sat location ls.

  • removeAssignments
    boolean

    Specify true to remove the storage configuration along with the associated assignments. If unspecified, the default value is false.

Response

Status Code

  • 200

    OK. The storage configuration is removed.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Subscription Update access in IAM.

  • satellite.config-subscription.update

Auditing

Calling this method generates the following auditing event.

An assignment is updated.

  • satellite.subscription.update

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Request Body

Required*
SetAssignmentAutoupgradeInputData

The parameters must include:

  1. Storage configuration name or ID (config).
  2. Satellite Location (controller).
  3. Set the autoUpgrade flag to true to enable assignments for automatic upgrades. If unspecified, it is assumed to be false.
  4. Either set All to enable/disable automatic upgrades for all the assignments of the storage configuration or provide the UUIDs to enable/disable automatic upgrades for a set of assignments.

Response

Response Body

SetAssignmentAutoupgradeInputData

Status Code

  • 200

    OK. The assignment(s) is/are enabled/disabled for automatic upgrades.

  • 400

    Bad Request. The request failed due to one of the following reasons:

    1. The config name/uuid is missing or the specified config is invalid. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.
    2. Both the parameters All and UUIDs are provided. Both cannot be provided at the same time.
    3. No assignment(s) provided to enable/disable automatic upgrade. Neither of the parameters All and UUIDs are provided.
    4. The assignment uuid provided in UUIDs parameter is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignmentsByConfig API or run ibmcloud sat storage assignment ls --config config.
  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The request failed due to one of the following reasons:

    1. The specified config could not be found. To list the storage configurations that you have access to, use the GET /v2/storage/satellite/getStorageConfigurations API or run ibmcloud sat storage config ls.
    2. The specified assignment could not be found. To list the storage assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Operator platform role to Kubernetes Service in IAM.

  • containers-kubernetes.cluster.operate

Auditing

Calling this method generates the following auditing event.

A desired storage configuration request is created.

  • satellite.storage-configuration.set-desired

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Request Body

Required*
SetDesiredStorageConfigRequest

The configuration details for your Satellite storage request. Include the cluster ID (cluster) and the required storage specifications. To list available clusters in the Satellite location, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>. The following storage specifications are supported:

  1. Required: a. Volume type. Specify one of file, block or object. b. Provider. Specify one of the supported providers of storage templates. For a list of supported providers or templates, see https://github.com/IBM/ibm-satellite-storage/blob/develop/config-templates/template_list.json. c. Maximum volume size and total capacity. Specify a positive integer value. Use K for kilobytes, M for megabytes, G for gigabytes, T for terabytes, or E for exabytes. Example: 100G.
  2. Optional parameters. a. Offering type. Specify either sds for software-defined storage or non-sds. b. Volume encryption at rest. This is a boolean value. Specify true or false. c. Volume availability. This is a boolean value. Specify true or false. d. Volume expansion. This is a boolean value. Specify true or false. e. Volume snapshot. This is a boolean value. Specify true or false. f. Storage classes. Include a list of specific storage classes. Note that currently, requested storage classes are not strictly validated while provisioning storage.

See the following example payload for a storage request that specifies the cluster ID, volume type, offering type, provider, volume availability, volume expansion, volume snap shot, and storage classes: {"cluster": "c9l508rw0eo68tnbijrg","storage-requests": {"volume-type": "file","offering-type": "sds","provider": "redhat","volume-availability": "regional","volume-expansion": "true","volume-encryption-at-rest": "true","storageclasses": ["gold"],"volume-snapshot": "false","max-volume-size": "100G","total-capacity": "1T"}}

Response

Status Code

  • 201

    OK. The storage request is created.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Could not find the IBM Cloud Satellite cluster, volume type, available volume, or storage class. Verify the input parameters and try again. To list the Satellite clusters that you have access to and their respective location name or ID, use the GET /v2/satellite/getClusters API or run ibmcloud sat service ls --location=<location-name-or-ID>.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Subscription Update access in IAM.

  • satellite.config-subscription.update

Auditing

Calling this method generates the following auditing event.

An assignment is updated.

  • satellite.subscription.update

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Request Body

Required*
UpdateSubscriptionInputData

The parameters must include the UUID of the assignment (uuid) along with at least one of the following parameters to be updated:

  1. One or more cluster groups (groups) on which you want to apply the configuration. To list the cluster groups that you have access to, run ibmcloud sat group ls.
  2. New name of the assignment (name).
  3. set the updateConfigVersion flag to true for updating an assignment to the latest available storage configuration version. If unspecified, it is assumed to be false. To see if assignment upgrade is available, use the GET /v2/storage/satellite/getAssignment API and look for isAssignmentUpgradeAvailable field in response or run ibmcloud sat storage assignment get --assignment UUID and look for Assignment Upgrade Available field in response.

Response

Response Body

UpdateSubscriptionData

Status Code

  • 200

    OK. The assignment is updated.

  • 400

    Bad Request. The request failed due to one of the following reasons:

    1. The uuid is missing or the specified uuid is invalid. To list the assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls.
    2. There is no parameter in the request body to update. Input at least one parameter to be updated.
    3. Storage assignment is already up to date with the latest available storage configuration version. Set the updateConfigVersion flag to false if you want to update at least assignment name or cluster group(s) on which you want to apply the configuration.
    4. 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).
  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found. The specified assignment or cluster group(s) could not be found. To list the storage assignments that you have access to, use the GET /v2/storage/satellite/getAssignments API or run ibmcloud sat storage assignment ls. To list the Satellite cluster groups you have access to, run ibmcloud sat group ls.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Request Body

Required*
StorageConfigUpdateInput

Include the storage template name (storage-template-name) and version (storage-template-version), the name of the existing storage configuration (config-name), the required parameters for the specified template (user-config-parameters, user-secret-parameters, and storage-class-parameters) and the Satellite location (location) where you want to use the storage configuration. To list the storage configurations that you have access to, run ibmcloud sat storage config ls. To view the storage assignments associated with a given storage configuration, run ibmcloud sat config get --config=<storage-configuration-name>. To list the storage templates and template versions, run ibmcloud sat storage template ls. To list the parameters for a given storage template and template version, run ibmcloud sat storage template get --name=<template-name> --version=<template-version>. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Response

Response Body

ErrorResponse

ErrorResponse error response to end users

Status Code

  • 201

    OK. The storage configuration is updated.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Configuration Update access in IAM.

  • satellite.config-configuration.update

Auditing

Calling this method generates the following auditing event.

A storage configuration is updated.

  • satellite.storage-configuration.update

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Request Body

Required*
StorageConfigUpdateInput

Include the name of the storage configuration (config-name) and the name or ID of the relevant Satellite location (controller). To apply the updated storage configuration to this storage configuration's existing assignments, set the update-assignments option to true. If left unspecified, the update-assignments option defaults to false.

If the storage configuration is assigned, only the configuration (user-config-parameters) and secret (user-secret-parameters) parameters that are marked as mutable can be updated. If the storage configuration is not assigned, all parameters can be updated.

If user-defined storage classes are supported, specify the required storage class parameters (storage-class-parameters) for the template that the storage configuration was created from. Note that any existing user-defined storage classes are overwritten by any storage classes specified in this API request's payload. For example, if you intend to define new storage classes and keep the existing storage classes, you must specify the parameters for both the existing and new user-defined storage classes.

To list the storage configurations that you have access to, run ibmcloud sat storage config ls. To view the storage assignments associated with a given storage configuration, run ibmcloud sat config get --config=<storage-configuration-name>. To list the parameters for a given storage template and template version, run ibmcloud sat storage template get --name=<template-name> --version=<template-version>. To list the parameters of existing storage classes, run ibmcloud sat storage config class ls --config=<storage-configuration-name> --show-params. To list the Satellite locations that you have access to, run ibmcloud sat location ls.

Response

Response Body

ErrorResponse

ErrorResponse error response to end users

Status Code

  • 201

    OK. The storage configuration is updated.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

To get the action, the user must have the Satellite Config Configuration Update access in IAM.

  • satellite.config-configuration.update

Auditing

Calling this method generates the following auditing event.

A storage configuration is updated to the latest revision.

  • satellite.storage-configuration.update-revision

Request

Custom Headers

  • Authorization
    Required*
    string

    Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Query Parameters

  • config
    Required*
    string

    The name or UUID of the storage configuration. To list the storage configurations that you have access to, run ibmcloud sat storage config ls.

  • controller
    Required*
    string

    The name or ID of the Satellite location. To list the Satellite locations that you have access to, use the GET /v2/satellite/getControllers API or run ibmcloud sat location ls.

  • updateAssignments
    boolean

    Specify true or false to update assignment(s) of the specified storage configuration. The default value is false.

Response

Response Body

ErrorResponse

ErrorResponse error response to end users

Status Code

  • 201

    OK. Updated storage configuration template to latest revision.

  • 401

    Unauthorized. Your IAM token could not be verified. Make sure that you are logged in to IBM Cloud, and then run ibmcloud iam oauth-tokens to retrieve your access tokens.

  • 404

    Not found.

  • 406

    Storage configuration template is already up to date with the latest revision.

  • 500

    Internal Server Error. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

No Sample Response

This method does not specify any sample responses.