IBM Cloud Docs
设置 API

设置 API

您可以使用 IBM Cloud® Kubernetes Service API 创建和管理您的社区 Kubernetes 或 Red Hat OpenShift 集群。 要使用 CLI，请参阅设置 CLI。

关于 API

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

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

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

API 端点前缀
v1 应用程序接口：https://containers.cloud.ibm.com/global/v1
v2 应用程序接口：https://containers.cloud.ibm.com/global/v2
v3 应用程序接口：https://containers.cloud.ibm.com/global/v3
API 参考文档
v1 和 v2 API
v3 应用程序接口。
API 体系结构样式
v1 API：表示状态传输 (REST)：侧重于通过 HTTP 方法进行交互的资源，如 GET, POST, PUT, PATCH 和 DELETE。
v2 API：远程过程调用 (RPC)，只通过 GET 和 POST HTTP 方法进行操作。
支持的容器平台
v1 API：使用 IBM Cloud Kubernetes Service API 管理 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：要使用 Kubernetes API 管理集群内的 Kubernetes 资源，如 pod 或命名空间，请参阅 使用 Kubernetes API 管理集群。
v2 API: 与 v1 相同; 请参阅 使用 Kubernetes API 处理集群。
基础结构类型支持的 API
v1 应用程序接口：classic
v2 API: vpc 和 classic
  • vpc 提供者旨在支持多个 VPC 子提供者。 支持的 VPC 子提供程序是 vpc-gen2，它对应于第 2 代计算资源的 VPC 群集。
  • 特定于提供者的请求在 URL 中具有路径参数，例如 v2/vpc/createCluster。 某些 API 仅可用于特定提供者，例如 GET vlan 适用于经典，GET vpcs 适用于 VPC。
  • 如果只想返回指定提供商的响应，中性提供商请求可以包含一个由您指定的特定提供商主体参数（通常为 JSON 格式，如 {"provider": "vpc"} ）。
GET 响应
v1 API：针对资源集合（如 GET v1/clusters ）的 GET 方法与针对单个资源（如 GET v1/clusters/{idOrName} ）的 GET 方法返回列表中每个资源的详细信息相同。
v2 API：为了更快地返回响应，针对资源集合（如 GET v2/clusters ）的 v2 GET 方法只返回针对单个资源（如 GET v2/clusters/{idOrName} ）的 GET 方法中详细说明的信息子集。 一些列表响应包含 provider 属性，用于确定返回的项是适用于经典还是 VPC 基础架构。 例如，GET zones 列表返回的结果中，一些结果（如 mon01）仅在经典基础架构提供者中提供，而另一些结果（如 us-south-01）仅在 VPC 基础架构提供者中提供。
集群、工作程序节点和工作程序池响应
v1 API：响应只包括传统基础架构提供商特有的信息，如 GET 集群中的 VLAN 和工作者响应。
v2 应用程序接口：返回的信息因基础设施提供商而异。 对于此类特定于提供者的响应，可以在请求中指定提供者。 例如，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 令牌。

未联合的标识
  • 生成 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 用户名和密码： 您可以按照本主题中的步骤全自动创建 IBM Cloud IAM 访问令牌。
联合标识
  • 生成 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 密钥。
  • API 密钥： 要生成您的 IBM Cloud API 密钥的步骤如下
    1. 在菜单栏中，单击**管理 ** > 访问权 (IAM)。
    2. 单击用户页面，然后选择您自己。
    3. 在 API 密钥窗格中，单击创建 IBM Cloud API 密钥。
    4. 输入 API 密钥的名称和描述，然后单击创建。
    5. 单击显示以查看生成的 API 密钥。
    6. 复制 API 密钥，以便可以将其用于检索新的 IBM Cloud IAM 访问令牌。

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

    POST https://iam.cloud.ibm.com/identity/token
    头
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic Yng6Yng= 其中 Yng6Yng= 等于 URL-encoded authorization for username bx and password bx。
    IBM Cloud 用户名和密码的主体
    • grant_type: password
    • username:您的 IBM Cloud 用户名。
    • password：您的 IBM Cloud 密码。
    IBM Cloud API 密钥的主体
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey：您的 IBM Cloud API 密钥
    IBM Cloud 一次性通行码的主体
    • grant_type: urn:ibm:params:oauth:grant-type:passcode
    • passcode：您的 IBM Cloud 一次性密码。 运行 ibmcloud login --sso，并按照 CLI 输出中的指示信息，使用 Web 浏览器来检索一次性密码。

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

    {
"access_token": "<iam_access_token>",
"refresh_token": "<iam_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 IAM 令牌，该令牌是您在上一步中从 API 输出的 access_token 字段中获取的。 在 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-encoded authorization for username bx and password bx。
    IBM Cloud 用户名和密码的主体
    • grant_type: password
    • username:您的 IBM Cloud 用户名。
    • password：您的 IBM Cloud 密码。
    • bss_account：在上一步中检索到的 IBM Cloud 帐户标识。
    IBM Cloud API 密钥的主体
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey：您的 IBM Cloud API 密钥。
    • bss_account：在上一步中检索到的 IBM Cloud 帐户标识。
    IBM Cloud 一次性通行码的主体
    • grant_type: urn:ibm:params:oauth:grant-type:passcode
    • passcode：您的 IBM Cloud 密码。
    • bss_account：在上一步中检索到的 IBM Cloud 帐户标识。

    以下示例显示 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 使用集群

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

以下说明要求在群集中使用公共网络访问，以连接到 Kubernetes 主站的公共云服务端点。

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

  2. 使用 IBM Cloud API 密钥检索 IBM Cloud IAM ID、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
    正文
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey:：您的 IBM Cloud API 密钥。

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

    {
"access_token": "<iam_access_token>",
"id_token": "<iam_id_token>",
"refresh_token": "<iam_refresh_token>",
"token_type": "Bearer",
"expires_in": 3600,
"expiration": 1553629664,
"refresh_token_expiration": 1761334993,
"scope": "ibm openid containers-kubernetes"
}

    或者，使用 ibmcloud ks cluster config --cluster <cluster_name> --output json CLI 命令将显示 id_token 和 refresh_token。

  3. 在使用当前身份访问群集之前，您必须运行以下请求。

    POST https://containers.cloud.ibm.com/global/v2/applyRBAC
    头
    Authorization: bearer <TOKEN> 您的 IAM 访问令牌 IBM Cloud
    正文
    cluster: <cluster_name_or_ID>

  4. 请注意，RBAC 同步是异步的，因此请运行以下请求，直到同步完成。

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

-H“授权：$”{BEARER2}

    Header
    :   `Authorization: bearer <TOKEN>` Your IBM Cloud IAM access token

    Example response. Ensure the output shows `synchronized:true`.

    ```json {: screen}
    {"synchronized":true,"error":false}
    ```



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

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

   ```sh {: codeblock}
   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": {
    ...}

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

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

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

    GET <masterURL>/api
    头
    • Authorization: bearer <id_token>
    路径
    • <masterURL>:在上一步中获取的 Kubernetes 主站的服务端点。

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

    {
	"kind": "APIVersions",
	"versions": [
		"v1"
	],
	"serverAddressByClientCIDRs": [
		{
			"clientCIDR": "0.0.0.0/0",
			"serverAddress": "xxx.xx.x.x:xxxx"
		}
	]
 }

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

使用应用程序接口刷新 IAM 访问令牌

通过 API 发出的每个 IBM Cloud Identity and Access Management (IAM) 访问令牌都会在 1 小时后到期。 必须定期刷新访问令牌才可确保对 IBM Cloud API 的访问权。

在开始之前，请确保您有 IBM Cloud API 密钥，可以用来请求新的访问令牌。

如果要获取新的 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
    正文
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey:：您的 IBM Cloud API 密钥。

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

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

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

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