设置 API

Red Hat® OpenShift® on IBM Cloud® 与 IBM Cloud Kubernetes Service 共享相同的应用编程接口 (API)，因此您可以使用相同的方法来一致地创建和管理您的社区 Kubernetes 或 Red Hat OpenShift 集群。 要使用 CLI，请参阅设置 CLI。

关于 API

Red Hat OpenShift on IBM Cloud API 可自动为您的集群配置和管理 IBM Cloud 基础设施资源，从而确保您的应用拥有为服务用户所需的计算、网络和存储资源。

该 API 支持各种可供您用于创建集群的基础设施提供商。 有关更多信息，请参阅 基础架构提供者概述。

可以使用第二版 (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：使用 Red Hat OpenShift on IBM Cloud API来管理您的 IBM Cloud 基础设施资源（例如工作节点），用于 社区版 Kubernetes 和 Red Hat OpenShift 集群。
v2 API: 使用 Red Hat OpenShift on IBM Cloud v2 API 来管理 社区 Kubernetes 和 Red Hat OpenShift VPC 集群的 IBM Cloud 基础架构资源 (例如工作程序节点)。
Red Hat OpenShift API
v1 API: 要使用 Red Hat OpenShift API 来管理集群中的 Red Hat OpenShift 和 Kubernetes 资源 (例如 pod 或名称空间)，必须通过交换 IBM Cloud API 密钥以获取 Red Hat OpenShift 访问令牌来登录。 请参阅 使用 API 密钥登录到集群。
v2 API: 与 v1 相同; 请参阅 使用 API 密钥登录到集群。
基础结构类型支持的 API
v1 应用程序接口：classic
v2 API: vpc 和 classic
  • vpc 提供者旨在支持多个 VPC 子提供者。 支持的 VPC 子提供商为 vpc-gen2，该 VPC 子提供商对应于第 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 API：返回的信息因基础设施提供商而异。 对于此类特定于提供者的响应，可以在请求中指定提供者。 例如，VPC 集群不会返回 VLAN 信息，因为它们没有 VLAN。 这些集群会改为返回子网和 CIDR 网络信息。

使用 API 自动部署集群

您可以使用 Red Hat OpenShift on IBM Cloud API，自动完成 Red Hat OpenShift 集群的创建、部署和管理。

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

要向 Red Hat OpenShift on IBM Cloud 进行认证，必须提供包含创建集群的 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 API 密钥与同一 IBM Cloud IAM 令牌中的另一个账户 ID 结合使用。 要访问使用非 IBM Cloud API 密钥所基于的帐户创建的集群，必须登录该帐户以生成新的 API 密钥。
  • IBM Cloud 用户名和密码： 您可以按照本主题中的步骤，完全自动化地创建您的 IBM Cloud IAM 访问令牌。
联合标识
  • 生成 IBM Cloud API 密钥: IBM Cloud API 密钥 依赖于为其生成的 IBM Cloud 帐户。 您不能将您的 IBM Cloud API 密钥与同一 IBM Cloud IAM 令牌中的另一个账户 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= 等于用户名 bx 和密码 bx 的 URL 编码授权。
    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 替换为您在上一步骤中从 API 输出结果的 access_token 字段中获取的 IBM Cloud 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= 等于用户名 bx 和密码 bx 的 URL 编码授权。
    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 集群。 用于列出经典集群的示例请求。 

    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. 查看 Red Hat OpenShift on IBM Cloud API 文档，查找支持的 API 列表。

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

使用 API 刷新 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. 使用上一步中的令牌，继续使用 Red Hat OpenShift on IBM Cloud API 文档。