| copyright | lastupdated | keywords | subcollection | ||
|---|---|---|---|---|---|
|
2021-04-28 |
kubernetes, iks, ibmcloud, ic, ks, kubectl, api |
containers |
{:DomainName: data-hd-keyref="APPDomain"} {:DomainName: data-hd-keyref="DomainName"} {:android: data-hd-operatingsystem="android"} {:api: .ph data-hd-interface='api'} {:apikey: data-credential-placeholder='apikey'} {:app_key: data-hd-keyref="app_key"} {:app_name: data-hd-keyref="app_name"} {:app_secret: data-hd-keyref="app_secret"} {:app_url: data-hd-keyref="app_url"} {:authenticated-content: .authenticated-content} {:beta: .beta} {:c#: data-hd-programlang="c#"} {:cli: .ph data-hd-interface='cli'} {:codeblock: .codeblock} {:curl: .ph data-hd-programlang='curl'} {:deprecated: .deprecated} {:dotnet-standard: .ph data-hd-programlang='dotnet-standard'} {:download: .download} {:external: target="_blank" .external} {:faq: data-hd-content-type='faq'} {:fuzzybunny: .ph data-hd-programlang='fuzzybunny'} {:generic: data-hd-operatingsystem="generic"} {:generic: data-hd-programlang="generic"} {:gif: data-image-type='gif'} {:go: .ph data-hd-programlang='go'} {:help: data-hd-content-type='help'} {:hide-dashboard: .hide-dashboard} {:hide-in-docs: .hide-in-docs} {:important: .important} {:ios: data-hd-operatingsystem="ios"} {:java: .ph data-hd-programlang='java'} {:java: data-hd-programlang="java"} {:javascript: .ph data-hd-programlang='javascript'} {:javascript: data-hd-programlang="javascript"} {:new_window: target="_blank"} {:note .note} {:note: .note} {:objectc data-hd-programlang="objectc"} {:org_name: data-hd-keyref="org_name"} {:php: data-hd-programlang="php"} {:pre: .pre} {:preview: .preview} {:python: .ph data-hd-programlang='python'} {:python: data-hd-programlang="python"} {:route: data-hd-keyref="route"} {:row-headers: .row-headers} {:ruby: .ph data-hd-programlang='ruby'} {:ruby: data-hd-programlang="ruby"} {:runtime: architecture="runtime"} {:runtimeIcon: .runtimeIcon} {:runtimeIconList: .runtimeIconList} {:runtimeLink: .runtimeLink} {:runtimeTitle: .runtimeTitle} {:screen: .screen} {:script: data-hd-video='script'} {:service: architecture="service"} {:service_instance_name: data-hd-keyref="service_instance_name"} {:service_name: data-hd-keyref="service_name"} {:shortdesc: .shortdesc} {:space_name: data-hd-keyref="space_name"} {:step: data-tutorial-type='step'} {:subsection: outputclass="subsection"} {:support: data-reuse='support'} {:swift: .ph data-hd-programlang='swift'} {:swift: data-hd-programlang="swift"} {:table: .aria-labeledby="caption"} {:term: .term} {:tip: .tip} {:tooling-url: data-tooling-url-placeholder='tooling-url'} {:troubleshoot: data-hd-content-type='troubleshoot'} {:tsCauses: .tsCauses} {:tsResolve: .tsResolve} {:tsSymptoms: .tsSymptoms} {:tutorial: data-hd-content-type='tutorial'} {:ui: .ph data-hd-interface='ui'} {:unity: .ph data-hd-programlang='unity'} {:url: data-credential-placeholder='url'} {:user_ID: data-hd-keyref="user_ID"} {:vbnet: .ph data-hd-programlang='vb.net'} {:video: .video}
{: #cs_api_install}
You can use the {{site.data.keyword.containerlong}} API to create and manage your community Kubernetes or {{site.data.keyword.openshiftshort}} clusters. To use the CLI, see Setting up the CLI. {: shortdesc}
{: #api_about}
The {{site.data.keyword.containerlong_notm}} API automates the provisioning and management of {{site.data.keyword.cloud_notm}} infrastructure resources for your clusters so that your apps have the compute, networking, and storage resources that they need to serve your users. {: shortdesc}
The API is versioned to support the different infrastructure providers that are available for you to create clusters. For more information, see Overview of Classic and VPC infrastructure providers.
You can use the version two (v2) API to manage both classic and VPC clusters. The v2 API is designed to avoid breaking existing functionality when possible. However, make sure that you review the following differences between the v1 and v2 API.
| Area | v1 API | v2 API |
|---|---|---|
| API endpoint prefix | https://containers.cloud.ibm.com/global/v1 |
https://containers.cloud.ibm.com/global/v2 |
| API reference docs | [`https://containers.cloud.ibm.com/global/swagger-global-api/` ](https://containers.cloud.ibm.com/global/swagger-global-api/#/) | [`https://containers.cloud.ibm.com/global/swagger-global-api/` ](https://containers.cloud.ibm.com/global/swagger-global-api/#/) |
| API architectural style | Representational state transfer (REST) that focuses on resources that you interact with through HTTP methods such as `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`. | Remote procedure calls (RPC) that focus on actions through only `GET` and `POST` HTTP methods. |
| Supported container platforms | Use the {{site.data.keyword.containerlong_notm}} API to manage your {{site.data.keyword.cloud_notm}} infrastructure resources, such as worker nodes, for **both community Kubernetes and {{site.data.keyword.openshiftshort}} clusters**. | Use the {{site.data.keyword.containerlong_notm}} `v2` API to manage your {{site.data.keyword.cloud_notm}} infrastructure resources, such as worker nodes, for **both community Kubernetes and {{site.data.keyword.openshiftshort}} VPC clusters**. |
| Kubernetes API | To use the Kubernetes API to manage Kubernetes resources within the cluster, such as pods or namespaces, see [Working with your cluster by using the Kubernetes API](#kube_api). | Same as `v1`; see [Working with your cluster by using the Kubernetes API](#kube_api). |
| Supported infrastructure providers | `classic` | `vpc` and `classic`
|
| `GET` responses | The `GET` method for a collection of resources (such as `GET v1/clusters`) returns the same details for each resource in the list as a `GET` method for an individual resource (such as `GET v1/clusters/{idOrName}`). | To return responses faster, the v2 `GET` method for a collection of resources (such as `GET v2/clusters`) returns only a subset of information that is detailed in a `GET` method for an individual resource (such as `GET v2/clusters/{idOrName}`).
Some list responses include a providers property to identify whether the returned item applies to classic or VPC infrastructure. For example, the `GET zones` list returns some results such as `mon01` that are available only in the classic infrastructure provider, while other results such as `us-south-01` are available only in the VPC infrastructure provider. |
| Cluster, worker node, and worker-pool responses | Responses include only information that is specific to the classic infrastructure provider, such as the VLANs in `GET` cluster and worker responses. | The information that is returned varies depending on the infrastructure provider. For such provider-specific responses, you can specify the provider in your request. For example, VPC clusters do not return VLAN information since they do not have VLANs. Instead, they return subnet and CIDR network information. |
{: #cs_api}
You can use the {{site.data.keyword.containerlong_notm}} API to automate the creation, deployment, and management of your Kubernetes clusters. {: shortdesc}
The {{site.data.keyword.containerlong_notm}} API requires header information that you must provide in your API request and that can vary depending on the API that you want to use. To determine what header information is needed for your API, see the {{site.data.keyword.containerlong_notm}} API documentation{: external}.
To authenticate with {{site.data.keyword.containerlong_notm}}, you must provide an {{site.data.keyword.cloud_notm}} Identity and Access Management (IAM) token that is generated with your {{site.data.keyword.cloud_notm}} credentials and that includes the {{site.data.keyword.cloud_notm}} account ID where the cluster was created. Depending on the way you authenticate with {{site.data.keyword.cloud_notm}}, you can choose between the following options to automate the creation of your {{site.data.keyword.cloud_notm}} IAM token.
You can also use the API swagger JSON file{: external} to generate a client that can interact with the API as part of your automation work. {: tip}
| {{site.data.keyword.cloud_notm}} ID | My options |
|---|---|
| Unfederated ID |
|
| Federated ID |
|
| {: caption="ID types and options" caption-side="top"} | |
| {: summary="ID types and options with the input parameter in column 1 and the value in column 2."} |
-
Create your {{site.data.keyword.cloud_notm}} IAM access token. The body information that is included in your request varies based on the {{site.data.keyword.cloud_notm}} authentication method that you use.
POST https://iam.cloud.ibm.com/identity/token{: codeblock}
Input parameters to get IAM tokens. Input parameters Values Header - Content-Type: application/x-www-form-urlencoded
- Authorization: Basic Yng6Yng=
**Note**: `Yng6Yng=` equals the URL-encoded authorization for the username **bx** and the password **bx**.
Body for {{site.data.keyword.cloud_notm}} username and password - `grant_type: password`
- `response_type: cloud_iam uaa`
- `username`: Your {{site.data.keyword.cloud_notm}} username.
- `password`: Your {{site.data.keyword.cloud_notm}} password.
- `uaa_client_id: cf`
- `uaa_client_secret:`
**Note**: Add the `uaa_client_secret` key with no value specified.
Body for {{site.data.keyword.cloud_notm}} API keys - `grant_type: urn:ibm:params:oauth:grant-type:apikey`
- `response_type: cloud_iam uaa`
- `apikey`: Your {{site.data.keyword.cloud_notm}} API key
- `uaa_client_id: cf`
- `uaa_client_secret:`
**Note**: Add the `uaa_client_secret` key with no value specified.
Body for {{site.data.keyword.cloud_notm}} one-time passcode - `grant_type: urn:ibm:params:oauth:grant-type:passcode`
- `response_type: cloud_iam uaa`
- `passcode`: Your {{site.data.keyword.cloud_notm}} one-time passcode. Run `ibmcloud login --sso` and follow the instructions in your CLI output to retrieve your one-time passcode by using your web browser.
- `uaa_client_id: cf`
- `uaa_client_secret:`
**Note**: Add the `uaa_client_secret` key with no value specified.
Example output for using an API key:
{ "access_token": "<iam_access_token>", "refresh_token": "<iam_refresh_token>", "uaa_token": "<uaa_token>", "uaa_refresh_token": "<uaa_refresh_token>", "token_type": "Bearer", "expires_in": 3600, "expiration": 1493747503 "scope": "ibm openid" }{: screen}
You can find the {{site.data.keyword.cloud_notm}} IAM token in the access_token field of your API output. Note the {{site.data.keyword.cloud_notm}} IAM token to retrieve additional header information in the next steps.
-
Retrieve the ID of the {{site.data.keyword.cloud_notm}} account that you want to work with. Replace
<iam_access_token>with the {{site.data.keyword.cloud_notm}} IAM token that you retrieved from the access_token field of your API output in the previous step. In your API output, you can find the ID of your {{site.data.keyword.cloud_notm}} account in the resources.metadata.guid field.GET https://accounts.cloud.ibm.com/coe/v2/accounts{: codeblock}
Input parameters to get an {{site.data.keyword.cloud_notm}} account ID. Input parameters Values Headers - `Content-Type: application/json`
- `Authorization: bearer `
- `Accept: application/json`
Example output:
{ "next_url": null, "total_results": 5, "resources": [ { "metadata": { "guid": "<account_ID>", "url": "/coe/v2/accounts/<account_ID>", "created_at": "2016-09-29T02:49:41.842Z", "updated_at": "2018-08-16T18:56:00.442Z", "anonymousId": "1111a1aa1a1111a1aa11aa11111a1111" }, "entity": { "name": "<account_name>", ...{: screen}
-
Generate a new {{site.data.keyword.cloud_notm}} IAM token that includes your {{site.data.keyword.cloud_notm}} credentials and the account ID that you want to work with.
If you use an {{site.data.keyword.cloud_notm}} API key, you must use the {{site.data.keyword.cloud_notm}} account ID the API key was created for. To access clusters in other accounts, log into this account and create an {{site.data.keyword.cloud_notm}} API key that is based on this account. {: note}
POST https://iam.cloud.ibm.com/identity/token{: codeblock}
Input parameters to get IAM tokens. Input parameters Values Header - `Content-Type: application/x-www-form-urlencoded`
- `Authorization: Basic Yng6Yng=`
**Note**: `Yng6Yng=` equals the URL-encoded authorization for the username **bx** and the password **bx**.
Body for {{site.data.keyword.cloud_notm}} username and password - `grant_type: password`
- `response_type: cloud_iam uaa`
- `username`: Your {{site.data.keyword.cloud_notm}} username.
- `password`: Your {{site.data.keyword.cloud_notm}} password.
- `uaa_client_ID: cf`
- `uaa_client_secret:`
**Note**: Add the `uaa_client_secret` key with no value specified. - `bss_account`: The {{site.data.keyword.cloud_notm}} account ID that you retrieved in the previous step.
Body for {{site.data.keyword.cloud_notm}} API keys - `grant_type: urn:ibm:params:oauth:grant-type:apikey`
- `response_type: cloud_iam uaa`
- `apikey`: Your {{site.data.keyword.cloud_notm}} API key.
- `uaa_client_ID: cf`
- `uaa_client_secret:`
**Note**: Add the `uaa_client_secret` key with no value specified. - `bss_account`: The {{site.data.keyword.cloud_notm}} account ID that you retrieved in the previous step.
Body for {{site.data.keyword.cloud_notm}} one-time passcode - `grant_type: urn:ibm:params:oauth:grant-type:passcode`
- `response_type: cloud_iam uaa`
- `passcode`: Your {{site.data.keyword.cloud_notm}} passcode.
- `uaa_client_ID: cf`
- `uaa_client_secret:`
**Note**: Add the `uaa_client_secret` key with no value specified. - `bss_account`: The {{site.data.keyword.cloud_notm}} account ID that you retrieved in the previous step.
Example output:
{ "access_token": "<iam_token>", "refresh_token": "<iam_refresh_token>", "token_type": "Bearer", "expires_in": 3600, "expiration": 1493747503 }{: screen}
You can find the {{site.data.keyword.cloud_notm}} IAM token in the access_token and the refresh token in the refresh_token field of your API output.
-
List all classic or VPC clusters in your account. If you want to run Kubernetes API requests against a cluster, make sure to note the name or ID of the cluster that you want to work with.
-
Classic:
GET https://containers.cloud.ibm.com/global/v2/classic/getClusters{: codeblock}
Input parameters to work with the {{site.data.keyword.containerlong_notm}} API. Input parameters Values Header - `Authorization: bearer `
-
VPC:
GET https://containers.cloud.ibm.com/global/v2/vpc/getClusters?provider=vpc-gen2{: codeblock}
Input parameters to work with the {{site.data.keyword.containerlong_notm}} API. Input parameters Values Header `Authorization`: Your {{site.data.keyword.cloud_notm}} IAM access token (`bearer `).
- Review the {{site.data.keyword.containerlong_notm}} API documentation{: external} to find a list of supported APIs.
When you use the API for automation, be sure to rely on the responses from the API, not files within those responses. For example, the Kubernetes configuration file for your cluster context is subject to change, so do not build automation based on specific contents of this file when you use the GET /v1/clusters/{idOrName}/config call.
{: note}
{: #kube_api}
You can use the Kubernetes API{: external} to interact with your cluster in {{site.data.keyword.containerlong_notm}}. For authentication details, see {{site.data.keyword.cloud_notm}} IAM issuer details for RBAC users. {: shortdesc}
The following instructions require public network access in your cluster to connect to the public cloud service endpoint of your Kubernetes master. {: note}
-
Follow the steps in Automating cluster deployments with the API to retrieve your {{site.data.keyword.cloud_notm}} IAM access token, refresh token, the ID of the cluster where you want to run Kubernetes API requests, and the {{site.data.keyword.containerlong_notm}} region where your cluster is located.
-
Retrieve an {{site.data.keyword.cloud_notm}} IAM delegated refresh token.
POST https://iam.cloud.ibm.com/identity/token{: codeblock}
Input parameters to get an IAM delegated refresh token. Input parameters Values Header - `Content-Type: application/x-www-form-urlencoded`
- `Authorization: Basic Yng6Yng=`
**Note**: `Yng6Yng=` equals the URL-encoded authorization for the username **bx** and the password **bx**. - `cache-control: no-cache`
Body - `delegated_refresh_token_expiry: 600`
- `receiver_client_ids: kube`
- `response_type: delegated_refresh_token`
- `refresh_token`: Your {{site.data.keyword.cloud_notm}} IAM refresh token.
- `grant_type: refresh_token`
Example output:
{ "delegated_refresh_token": <delegated_refresh_token> }{: screen}
-
Retrieve an {{site.data.keyword.cloud_notm}} IAM ID, IAM access, and IAM refresh token by using the delegated refresh token from the previous step. In your API output, you can find the IAM ID token in the id_token field, the IAM access token in the access_token field, and the IAM refresh token in the refresh_token field.
POST https://iam.cloud.ibm.com/identity/token{: codeblock}
Input parameters to get IAM ID and IAM access tokens. Input parameters Values Header - `Content-Type: application/x-www-form-urlencoded`
- `Authorization: Basic a3ViZTprdWJl`
**Note**: `a3ViZTprdWJl` equals the URL-encoded authorization for the username **`kube`** and the password **`kube`**. - `cache-control: no-cache`
Body - `refresh_token`: Your {{site.data.keyword.cloud_notm}} IAM delegated refresh token.
- `grant_type: urn:ibm:params:oauth:grant-type:delegated-refresh-token`
Example output:
{ "access_token": "<iam_access_token>", "id_token": "<iam_id_token>", "refresh_token": "<iam_refresh_token>", "token_type": "Bearer", "expires_in": 3600, "expiration": 1553629664, "scope": "ibm openid containers-kubernetes" }{: screen}
-
Retrieve the URL of the default service endpoint for your Kubernetes master by using the IAM access token and the name or ID of your cluster. You can find the URL in the
masterURLof your API output.
If only the public cloud service endpoint or only the private cloud service endpoint is enabled for your cluster, that endpoint is listed for the masterURL. If both the public and private cloud service endpoints are enabled for your cluster, the public cloud service endpoint is listed by default for the masterURL. To use the private cloud service endpoint instead, find the URL in the privateServiceEndpointURL field of the output.
{: note}
GET https://containers.cloud.ibm.com/global/v2/getCluster?cluster=<cluster_name_or_ID>
{: codeblock}
| Input parameters | Values |
|---|---|
| Header | `Authorization`: Your {{site.data.keyword.cloud_notm}} IAM access token. |
| Path | ``: The name or ID of your cluster that you retrieved with the `GET https://containers.cloud.ibm.com/global/v2/classic/getClusters` or `GET https://containers.cloud.ibm.com/global/v2/vpc/getClusters?provider=vpc-gen2` API in [Automating cluster deployments with the API](#cs_api). |
Example output for a public cloud service endpoint:
...
"etcdPort": "31593",
"masterURL": "https://c2.us-south.containers.cloud.ibm.com:30422",
"ingress": {
...
{: screen}
Example output for a private cloud service endpoint:
...
"etcdPort": "31593",
"masterURL": "https://c2.private.us-south.containers.cloud.ibm.com:30422",
"ingress": {
...
{: screen}
-
To use a private cloud service endpoint, you must first expose the private cloud service endpoint with a load balancer IP that is routable from your VPN connection into the private network.
-
Run Kubernetes API requests against your cluster by using the IAM ID token that you retrieved earlier. For example, list the Kubernetes version that runs in your cluster.
If you enabled SSL certificate verification in your API test framework, make sure to disable this feature. {: tip}
GET <masterURL>/version{: codeblock}
Input parameters to view the Kubernetes version that runs in your cluster. Input parameters Values Header `Authorization: bearer ` Path ``: The service endpoint of your Kubernetes master that you retrieved in the previous step. Example output:
{ "major": "1", "minor": "1.20.6", "gitVersion": "v1.20.6+IKS", "gitCommit": "c35166bd86eaa91d17af1c08289ffeab3e71e11e", "gitTreeState": "clean", "buildDate": "2019-03-21T10:08:03Z", "goVersion": "go1.11.5", "compiler": "gc", "platform": "linux/amd64" }{: screen}
-
Review the Kubernetes API documentation{: external} to find a list of supported APIs for the latest Kubernetes version. Make sure to use the API documentation that matches the Kubernetes version of your cluster. If you do not use the latest Kubernetes version, append your version at the end of the URL. For example, to access the API documentation for version 1.12, add
v1.12.
Refreshing {{site.data.keyword.cloud_notm}} IAM access tokens and obtaining new refresh tokens with the API
{: #cs_api_refresh}
Every {{site.data.keyword.cloud_notm}} Identity and Access Management (IAM) access token that is issued via the API expires after one hour. You must refresh your access token regularly to assure access to the {{site.data.keyword.cloud_notm}} API. You can use the same steps to obtain a new refresh token. {: shortdesc}
Before you begin, make sure that you have an {{site.data.keyword.cloud_notm}} IAM refresh token or an {{site.data.keyword.cloud_notm}} API key that you can use to request a new access token.
- Refresh token: Follow the instructions in Automating the cluster creation and management process with the {{site.data.keyword.cloud_notm}} API.
- API key: Retrieve your {{site.data.keyword.cloud_notm}} API key as follows.
- From the menu bar, click Manage > Access (IAM).
- Click the Users page and then select yourself.
- In the API keys pane, click Create an IBM Cloud API key.
- Enter a Name and Description for your API key and click Create.
- Click Show to see the API key that was generated for you.
- Copy the API key so that you can use it to retrieve your new {{site.data.keyword.cloud_notm}} IAM access token.
Use the following steps if you want to create an {{site.data.keyword.cloud_notm}} IAM token or if you want to obtain a new refresh token.
-
Generate a new {{site.data.keyword.cloud_notm}} IAM access token by using the refresh token or the {{site.data.keyword.cloud_notm}} API key.
POST https://iam.cloud.ibm.com/identity/token{: codeblock}
Input parameters for a new {{site.data.keyword.cloud_notm}} IAM token Input parameters Values Header - `Content-Type: application/x-www-form-urlencoded`
- `Authorization: Basic Yng6Yng=`
**Note:** `Yng6Yng=` equals the URL-encoded authorization for the username **bx** and the password **bx**.
Body when using the refresh token - `grant_type: refresh_token`
- `response_type: cloud_iam uaa`
- `refresh_token:` Your {{site.data.keyword.cloud_notm}} IAM refresh token.
- `uaa_client_ID: cf`
- `uaa_client_secret:`
- `bss_account:` Your {{site.data.keyword.cloud_notm}} account ID.
Body when using the {{site.data.keyword.cloud_notm}} API key - `grant_type: urn:ibm:params:oauth:grant-type:apikey`
- `response_type: cloud_iam uaa`
- `apikey:` Your {{site.data.keyword.cloud_notm}} API key.
- `uaa_client_ID: cf`
- `uaa_client_secret:`
Example API output:
{ "access_token": "<iam_token>", "refresh_token": "<iam_refresh_token>", "uaa_token": "<uaa_token>", "uaa_refresh_token": "<uaa_refresh_token>", "token_type": "Bearer", "expires_in": 3600, "expiration": 1493747503 }{: screen}
You can find your new {{site.data.keyword.cloud_notm}} IAM token in the access_token, and the refresh token in the refresh_token field of your API output.
-
Continue working with the {{site.data.keyword.containerlong_notm}} API documentation{: external} by using the token from the previous step.
Refreshing {{site.data.keyword.cloud_notm}} IAM access tokens and obtaining new refresh tokens with the CLI
{: #cs_cli_refresh}
You can use the command line to set the cluster context, download the kubeconfig file for your Kubernetes cluster, and generate an {{site.data.keyword.cloud_notm}} Identity and Access Management (IAM) ID token and a refresh token to provide authentication.
{: shortdesc}
You can use {{site.data.keyword.cloud_notm}} IAM{: external} to change the default expiration times for your tokens and sessions. {: tip}
Kubeconfig session: When you start a new CLI session or after the session expires such as after the default of 24 hours, you must reset the cluster context.
ID token: Every IAM ID token that is issued via the CLI expires after a set period of time, such as 20 minutes. When the ID token expires, the refresh token is sent to the token provider to refresh the ID token. Your authentication is refreshed, and you can continue to run commands against your cluster.
Refresh token: Refresh tokens expire after a set period of time, such as 30 days, or if the administrator revokes the token. If the refresh token is expired, the ID token cannot be refreshed, and you are not able to continue running commands in the CLI. You can get a new refresh token by running ibmcloud ks cluster config --cluster <cluster_name>. This command also refreshes your ID token.