关于 API

IBM Cloud Kubernetes Service API 可自动为您的集群配置和管理 IBM Cloud 基础设施资源，以便您的应用拥有为用户提供服务所需的计算、网络和存储资源。

应用程序接口支持不同的基础设施提供商，您可以使用它们创建集群。 有关更多信息，请参阅 基础架构提供者概述。

可以使用第二版 (v2) API 来管理经典集群和 VPC 集群。 v2 API 旨在尽可能避免现有功能中断。 但是，请确保查看 v1 和 v2 API 之间的以下差异。

API 端点前缀

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

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

API 参考文档

v1 API: https://containers.cloud.ibm.com/global/swagger-global-api/

v2 API: https://containers.cloud.ibm.com/global/swagger-global-api/。

API 体系结构样式

v1 API：表示状态传输（REST），专注于您通过 方法（如、、、和 ）交互的资源。HTTP GET POST PUT PATCH DELETE

v2 API：远程过程调用（RPC），仅通过 和 方法进行操作。GET POST HTTP

支持的容器平台

v1 API：使用 API管理您的 基础设施资源，例如 IBM Cloud Kubernetes Service IBM Cloud 社区 和 集群 Kubernetes Red Hat OpenShift 的工作节点。

v2 API: 使用 IBM Cloud Kubernetes Service v2 API 来管理 社区 Kubernetes 和 Red Hat OpenShift VPC 集群的 IBM Cloud 基础架构资源 (例如工作程序节点)。

Kubernetes API

v1 API：要使用 API来管理集群中的 资源（例如Pod或命名空间），请参阅 Kubernetes Kubernetes 使用 API管理集群 Kubernetes。

v2 API: 与 v1 相同; 请参阅 使用 Kubernetes API 处理集群。

基础结构类型支持的 API

v1 API: classic

v2 API: vpc 和 classic

• vpc 提供者旨在支持多个 VPC 子提供者。 受支持的VPC子提供商是 vpc-gen2，它对应于第二代计算资源的VPC集群。
• 特定于提供者的请求在 URL 中具有路径参数，例如 v2/vpc/createCluster。 某些 API 仅可用于特定提供者，例如 GET vlan 适用于经典，GET vpcs 适用于 VPC。
• 如果只想返回指定提供商的响应，则提供商中立的请求可以包含一个您指定的特定提供商主体参数，通常以JSON格式表示，例如 {"provider": "vpc"}。

GET 响应

v1 API：方法用于资源集合（如 ），它返回列表中每个资源的详细信息，与 方法用于单个资源（如 ）相同。GET GET v1/clusters GET GET v1/clusters/{idOrName}

v2 API：为了更快地返回响应，方法（用于资源集合，例如 ）仅返回 方法（用于单个资源，例如 ）中详细描述的信息子集。v2 GET GET v2/clusters GET GET v2/clusters/{idOrName} 一些列表响应包含 provider 属性，用于确定返回的项是适用于经典还是 VPC 基础架构。 例如，GET zones 列表返回的结果中，一些结果（如 mon01）仅在经典基础架构提供者中提供，而另一些结果（如 us-south-01）仅在 VPC 基础架构提供者中提供。

集群、工作程序节点和工作程序池响应

v1 API：响应仅包含特定于经典基础设施提供商的信息，例如 集群和工作程序响应中的VLAN。GET

v2 API：返回的信息因基础架构提供商而异。 对于此类特定于提供者的响应，可以在请求中指定提供者。 例如，VPC 集群不会返回 VLAN 信息，因为它们没有 VLAN。 这些集群会改为返回子网和 CIDR 网络信息。

使用 API 自动部署集群

可以使用 IBM Cloud Kubernetes Service API 来自动创建、部署和管理 Kubernetes 集群。

IBM Cloud Kubernetes Service API 需要您必须在 API 请求中提供的头信息，根据您要使用的 API，这些头信息可以有所不同。 要确定您的API需要哪些标题信息，请参阅 IBM Cloud Kubernetes Service API文档。

要向 IBM Cloud Kubernetes Service 进行认证，必须提供包含创建集群的 IBM Cloud 帐户标识且使用 IBM Cloud 凭证生成的 IBM Cloud Identity and Access Management (IAM) 令牌。 根据您向 IBM Cloud 进行认证的方式，可以在下列选项之间进行选择，以自动创建 IBM Cloud IAM 令牌。

您还可以使用 API swagger JSON文件生成一个客户端，作为自动化工作的一部分与API进行交互。

未联合的标识

• 生成 IBM Cloud API 密钥: 作为使用 IBM Cloud 用户名和密码的替代方法，您可以 使用 IBM Cloud API 密钥。IBM Cloud API 密钥依赖于为其生成的 IBM Cloud 帐户。 您不能在同一 IBM Cloud IAM令牌中将您的 IBM Cloud API密钥与另一个账户ID合并。 要访问使用非 IBM Cloud API 密钥所基于的帐户创建的集群，必须登录该帐户以生成新的 API 密钥。
• IBM Cloud 用户名和密码：您可以按照本主题中的步骤完全自动创建您的 IAM访问令牌。IBM Cloud

联合标识

• 生成 IBM Cloud API 密钥: IBM Cloud API 密钥 依赖于为其生成的 IBM Cloud 帐户。 您不能在同一 IBM Cloud IAM令牌中将您的 IBM Cloud API密钥与另一个账户ID合并。 要访问使用非 IBM Cloud API 密钥所基于的帐户创建的集群，必须登录该帐户以生成新的 API 密钥。
• 使用一次性密码：如果您使用 IBM Cloud 通过一次性密码进行身份验证，则无法完全自动创建您的 IBM Cloud IAM令牌，因为要获取一次性密码，需要手动与您的网络浏览器进行交互。 要完全自动化 IBM Cloud IAM 令牌的创建，必须改为创建 IBM Cloud API 密钥。

1. 创建 IBM Cloud IAM 访问令牌。 包含在请求中的主体信息根据您使用的 IBM Cloud 认证方法而有所不同。

   POST https://iam.cloud.ibm.com/identity/token
   

   头

   • Content-Type: application/x-www-form-urlencoded
   • Yng6Yng= Yng6Yng= 等于 编码的 URL用户名bx 和密码bx 的授权。

   IBM Cloud 用户名和密码的主体

   • grant_type: password
   • response_type: cloud_iam uaa
   • username：您的 IBM Cloud 用户名。
   • password：您的 IBM Cloud 密码。
   • uaa_client_id: cf
   • uaa_client_secret: 添加 uaa_client_secret 密钥，不指定任何值。

   IBM Cloud API 密钥的主体

   • grant_type: urn:ibm:params:oauth:grant-type:apikey
   • response_type: cloud_iam uaa
   • apikey：您的 IBM Cloud API 密钥
   • uaa_client_id: cf
   • uaa_client_secret: 添加 uaa_client_secret 密钥，不指定任何值。

   IBM Cloud 一次性通行码的主体

   • grant_type: urn:ibm:params:oauth:grant-type:passcode
   • response_type: cloud_iam uaa
   • passcode：您的 IBM Cloud 一次性密码。 运行 ibmcloud login --sso，并按照 CLI 输出中的指示信息，使用 Web 浏览器来检索一次性密码。
   • uaa_client_id: cf
   • uaa_client_secret: 添加 uaa_client_secret 密钥，不指定任何值。

   以下示例显示了先前请求的输出。

   {
   "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"
   }
   
   

   您可以在API输出的 access_token 字段中找到 IBM Cloud IAM令牌。 请记下 IBM Cloud IAM 令牌以在后续步骤中用于检索更多头信息。

2. 检索要使用的 IBM Cloud 帐户的标识。 将 TOKEN 替换为 IBM Cloud，即您在上一步骤中从API输出的 access_token 字段中获取的IAM令牌。 在 API 输出中，可以在 resources.metadata.guid 字段中找到 IBM Cloud 帐户的标识。

   GET https://accounts.cloud.ibm.com/coe/v2/accounts
   

   头

   • Content-Type: application/json
   • Authorization: bearer TOKEN
   • Accept: application/json

   以下示例显示了之前请求的输出。

   {
   "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>",
   

3. 生成新的 IBM Cloud IAM 令牌，该令牌包含您的 IBM Cloud 凭证和要使用的帐户标识。

   如果使用的是 IBM Cloud API 密钥，那么必须使用为其创建 API 密钥的 IBM Cloud 帐户标识。 要访问其他账户中的群组，请登录该账户并创建一个基于该账户的 IBM Cloud API密钥。

   POST https://iam.cloud.ibm.com/identity/token
   

   头

   • Content-Type: application/x-www-form-urlencoded
   • Authorization: Basic Yng6Yng= Yng6Yng= 等于 编码的 URL用户名bx 和密码bx 的授权。

   IBM Cloud 用户名和密码的主体

   • grant_type: password
   • response_type: cloud_iam uaa
   • username：您的 IBM Cloud 用户名。
   • password：您的 IBM Cloud 密码。
   • uaa_client_ID: cf
   • uaa_client_secret: 添加 密钥，不指定任何值。uaa_client_secret
   • bss_account：在上一步中检索到的 IBM Cloud 帐户标识。

   IBM Cloud API 密钥的主体

   • grant_type: urn:ibm:params:oauth:grant-type:apikey
   • response_type: cloud_iam uaa
   • apikey：您的 IBM Cloud API 密钥。
   • uaa_client_ID: cf
   • uaa_client_secret: 添加 密钥，不指定任何值。uaa_client_secret
   • bss_account：在上一步中检索到的 IBM Cloud 帐户标识。

   IBM Cloud 一次性通行码的主体

   • grant_type: urn:ibm:params:oauth:grant-type:passcode
   • response_type: cloud_iam uaa
   • passcode：您的 IBM Cloud 密码。
   • uaa_client_ID: cf
   • uaa_client_secret:
   • bss_account：在上一步中检索到的 IBM Cloud 帐户标识。 添加 uaa_client_secret 密钥，不指定任何值。

   以下示例显示 API 请求的输出。

   {
       "access_token": "<iam_token>",
       "refresh_token": "<iam_refresh_token>",
       "token_type": "Bearer",
       "expires_in": 3600,
       "expiration": 1493747503
   }
   
   

   您可以在API输出的 access_token 字段中找到 IBM Cloud IAM令牌，在 refresh_token 字段中找到刷新令牌。

4. 列出帐户中的所有经典或 VPC 集群。 如果要 针对集群运行 Kubernetes API 请求，请确保记下要使用的集群的名称或标识。 用于列出经典集群的示例请求。

   GET https://containers.cloud.ibm.com/global/v2/classic/getClusters
   

   头

   Authorization: bearer <iam_token>

   用于列出 VPC 集群的示例命令。

   GET https://containers.cloud.ibm.com/global/v2/vpc/getClusters?provider=vpc-gen2
   

   头

   Authorization: IBM Cloud IAM 访问令牌 (bearer <iam_token>)。

5. 查看 IBM Cloud Kubernetes Service API文档，获取支持的API列表。

使用 API 实现自动化时，请确保依赖于来自 API 的响应，而不是这些响应中的文件。 例如，集群上下文的 Kubernetes 配置文件可能会发生更改，因此在使用 GET /v1/clusters/{idOrName}/config 调用时，请勿基于此文件的特定内容构建自动化。

通过 Kubernetes API 使用集群

您可以使用 Kubernetes API 与 IBM Cloud Kubernetes Service 中的集群进行交互。

以下说明要求集群中的公共网络访问权限，以便连接到您的 Kubernetes 主机的公共云服务终端。

1. 执行使用 API 自动部署集群中的步骤，以检索 IBM Cloud IAM 访问令牌、刷新令牌、要运行 Kubernetes API 请求的集群的标识以及集群所在的 IBM Cloud Kubernetes Service 区域。

2. 检索 IBM Cloud IAM 委派的刷新令牌。

   POST https://iam.cloud.ibm.com/identity/token
   

   头

   • Content-Type: application/x-www-form-urlencoded
   • Authorization: Basic Yng6Yng= 其中，等于 Yng6Yng= 用户名 bx 和密码 bx 的 编码授权。URL
   • cache-control: no-cache

   正文

   • delegated_refresh_token_expiry: 600
   • receiver_client_ids: kube
   • response_type: delegated_refresh_token
   • refresh_token：IBM Cloud IAM 刷新令牌。
   • grant_type: refresh_token

   以下示例显示了先前 API 请求的输出。

   {
   "delegated_refresh_token": <delegated_refresh_token>
   }
   

3. 使用上一步中委派的刷新令牌来检索 IBM Cloud IAM 标识、IAM 访问权和 IAM 刷新令牌。 在您的API输出中，您可以在 id_token 字段中找到IAM ID令牌，在 access_token 字段中找到IAM访问令牌，在 refresh_token 字段中找到IAM刷新令牌。

   POST https://iam.cloud.ibm.com/identity/token
   

   头

   • Content-Type: application/x-www-form-urlencoded
   • Authorization: Basic a3ViZTprdWJl a3ViZTprdWJl 等于 编码的用户名 和密码 的授权。URL kube kube
   • cache-control: no-cache

   正文

   • refresh_token：IBM Cloud IAM 委派的刷新令牌。
   • grant_type: urn:ibm:params:oauth:grant-type:delegated-refresh-token

   以下示例显示了先前 API 请求的输出。

   {
   "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"
   }
   

4. 使用IAM访问令牌和集群名称或ID，为您的 Kubernetes 主服务器检索默认服务端点的 URL。 URL 您可以在API输出的 masterURL API输出的

   如果仅为集群启用了公共云服务端点或仅启用了私有云服务端点，那么将为 masterURL 列出该端点。 如果同时为集群启用了公共云服务端点和私有云服务端点，那么缺省情况下会列出 masterURL 的公共云服务端点。 要使用私有云服务终端，请在输出的 privateServiceEndpointURL 字段中找到 URL。

   GET https://containers.cloud.ibm.com/global/v2/getCluster?cluster=<cluster_name_or_ID>
   

   头

   • Authorization：IBM Cloud IAM 访问令牌。

   路径

   • <cluster_name_or_ID>: 在 使用 API 自动部署集群 中使用 GET https://containers.cloud.ibm.com/global/v2/classic/getClusters 或 GET https://containers.cloud.ibm.com/global/v2/vpc/getClusters?provider=vpc-gen2 API 检索的集群的名称或标识。

   以下示例显示了公共云服务端点请求的输出。

   ...
   "etcdPort": "31593",
   "masterURL": "https://c2.us-south.containers.cloud.ibm.com:30422",
   "ingress": {
       ...}
   

   以下示例显示私有云服务端点请求的输出。

   ...
   "etcdPort": "31593",
   "masterURL": "https://c2.private.us-south.containers.cloud.ibm.com:30422",
   "ingress": {
       ...}
   

5. 要使用私有云服务端点，必须首先 使用可从 VPN 连接路由到私有网络的负载均衡器 IP 来公开私有云服务端点。

6. 使用先前检索到的 IAM 标识令牌，针对集群运行 Kubernetes API 请求。 例如，列出集群中运行的 Kubernetes 版本。

   如果在 API 测试框架中启用了 SSL 证书验证，请确保禁用此功能。

   GET <masterURL>/version
   

   头

   • Authorization: bearer <id_token>

   路径

   • <masterURL>：您在上一步骤中检索到的 Kubernetes 主机的服务端点。

   以下示例显示了先前 API 请求的输出。

   {
   "major": "1",
   "minor": "1.32",
   "gitVersion": "v1.32+IKS",
   "gitCommit": "c35166bd86eaa91d17af1c08289ffeab3e71e11e",
   "gitTreeState": "clean",
   "buildDate": "2019-03-21T10:08:03Z",
   "goVersion": "go1.11.5",
   "compiler": "gc",
   "platform": "linux/amd64"
   }
   

7. 查看 Kubernetes API文档，获取最新 Kubernetes 版本支持的API列表。 确保使用与集群的 Kubernetes 版本相匹配的 API 文档。 如果您使用的不是最新版本的 Kubernetes，请在 URL 后面附上您的版本。 例如，要访问 V1.12 的 API 文档，请添加 v1.12。

使用应用程序编程接口（API）刷新IAM访问令牌并获取新的刷新令牌

通过 API 发出的每个 IBM Cloud Identity and Access Management (IAM) 访问令牌都会在 1 小时后到期。 必须定期刷新访问令牌才可确保对 IBM Cloud API 的访问权。 您可以使用相同的步骤来获取新的刷新令牌。

开始之前，请确保您拥有可用于请求新访问令牌的 IBM Cloud IAM 刷新令牌或 IBM Cloud API 密钥。

• **刷新令牌：**遵循使用 IBM Cloud API 自动执行集群创建和管理过程中的指示信息。
• API密钥：请按以下步骤获取 IBM Cloud API密钥，方法如下。
  1. 在菜单栏中，单击**管理 ** > 访问权 (IAM)。
  2. 单击用户页面，然后选择您自己。
  3. 在 API 密钥窗格中，单击创建 IBM Cloud API 密钥。
  4. 输入 API 密钥的名称和描述，然后单击创建。
  5. 单击显示以查看生成的 API 密钥。
  6. 复制 API 密钥，以便可以将其用于检索新的 IBM Cloud IAM 访问令牌。

如果要创建 IBM Cloud IAM 令牌或要获取新的刷新令牌，请执行以下步骤。

1. 使用刷新令牌或 IBM Cloud API 密钥来生成新的 IBM Cloud IAM 访问令牌。

   POST https://iam.cloud.ibm.com/identity/token
   

   头

   • Content-Type: application/x-www-form-urlencoded
   • Authorization: Basic Yng6Yng=：其中，Yng6Yng= 等于用户名 bx 和密码 bx 的 URL 编码授权。

   使用刷新令牌时的主体

   • grant_type: refresh_token
   • response_type: cloud_iam uaa
   • refresh_token:：IBM Cloud IAM 刷新令牌。
   • uaa_client_ID: cf
   • uaa_client_secret:
   • bss_account:：您的 IBM Cloud 帐户标识。 添加 uaa_client_secret 密钥，不指定任何值。

   使用 IBM Cloud API 密钥时的主体

   • grant_type: urn:ibm:params:oauth:grant-type:apikey
   • response_type: cloud_iam uaa
   • apikey:：您的 IBM Cloud API 密钥。
   • uaa_client_ID: cf
   • uaa_client_secret: 添加 密钥，不指定任何值。uaa_client_secret

   以下示例显示了先前 API 请求的输出。

   {
       "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
   }
   
   

   您可以在 access_token 中找到新的 IBM Cloud IAM令牌，在API输出的 refresh_token 字段中找到刷新令牌。

2. 使用上一步中的令牌继续使用 IBM Cloud Kubernetes Service API文档。

使用 CLI 刷新 IBM Cloud IAM 访问令牌并获取新的刷新令牌

您可以使用命令行来 设置集群上下文，下载 Kubernetes 集群的 kubeconfig 文件，并生成 IBM Cloud Identity and Access Management (IAM) 标识令牌和刷新令牌以提供认证。

您可以使用 IBM Cloud IAM 来更改令牌和会话的缺省到期时间。

Kubeconfig 会话 (session)

在启动新的 CLI 会话时，或者在会话到期 (例如，缺省值为 24 小时之后) 之后，必须重置集群上下文。

标识令牌

通过 CLI 发出的每个 IAM 标识令牌都将在设置的时间段 (例如 20 分钟) 后到期。 标识令牌到期时，会向令牌提供程序发送刷新令牌以刷新标识令牌。 这将刷新您的认证，随后您可以继续对集群运行命令。

刷新令牌

刷新令牌将在设置的时间段 (例如 30 天) 后到期，或者管理员将撤销令牌。 如果刷新令牌过期，则无法刷新ID令牌，也无法继续在CLI中运行命令。 您可以发送电子邮件至 ibmcloud ks cluster config --cluster <cluster_name>，获取新的刷新令牌。 此命令还会刷新标识令牌。