设置 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 基础设施资源,使应用程序拥有为用户提供服务所需的计算、网络和存储资源。
应用程序接口支持不同的基础架构提供商,供您创建群集。 有关更多信息,请参阅 基础架构提供者概述。
可以使用第二版 (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
- API 参考文档
- v1 应用程序接口:
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 管理 基础设施资源,如 Red Hat OpenShift on IBM Cloud 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
,它对应于第 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
v2GET
GET v2/clusters/{idOrName}
GET
一些列表响应包含 provider 属性,用于确定返回的项是适用于经典还是 VPC 基础架构。 例如,GET zones
列表返回的结果中,一些结果(如mon01
)仅在经典基础架构提供者中提供,而另一些结果(如us-south-01
)仅在 VPC 基础架构提供者中提供。 - 集群、工作程序节点和工作程序池响应
- v1 API:响应只包括传统基础架构提供商特有的信息,如 集群中的 VLAN 和工作者响应。
GET
- v2 应用程序接口:返回的信息因基础设施提供商而异。 对于此类特定于提供者的响应,可以在请求中指定提供者。 例如,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 令牌。
您还可以使用 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 密钥。
-
创建 IBM Cloud IAM 访问令牌。 包含在请求中的主体信息根据您使用的 IBM Cloud 认证方法而有所不同。
POST https://iam.cloud.ibm.com/identity/token
- 头
-
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Yng6Yng=
其中 等于 -encoded authorization for usernameYng6Yng=
URLbx 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 令牌以在后续步骤中用于检索更多头信息。 -
检索要使用的 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>",
-
生成新的 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=
其中 等于 -encoded authorization for usernameYng6Yng=
URLbx 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
字段中找到刷新令牌。 -
列出帐户中的所有经典或 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>
)。
-
查看 Red Hat OpenShift on IBM Cloud API 文档,查找支持的 API 列表。
使用 API 实现自动化时,请确保依赖于来自 API 的响应,而不是这些响应中的文件。 例如,集群上下文的 Kubernetes 配置文件可能会发生更改,因此在使用 GET /v1/clusters/{idOrName}/config
调用时,请勿基于此文件的特定内容构建自动化。
刷新 IAM 访问令牌并通过 API 获取新的刷新令牌
通过 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 密钥。
- 在菜单栏中,单击**管理 ** > 访问权 (IAM)。
- 单击用户页面,然后选择您自己。
- 在 API 密钥窗格中,单击创建 IBM Cloud API 密钥。
- 输入 API 密钥的名称和描述,然后单击创建。
- 单击显示以查看生成的 API 密钥。
- 复制 API 密钥,以便可以将其用于检索新的 IBM Cloud IAM 访问令牌。
如果要创建 IBM Cloud IAM 令牌或要获取新的刷新令牌,请执行以下步骤。
-
使用刷新令牌或 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=
等于 URL-编码的用户名 bx 和密码 bx 的授权。
- 使用刷新令牌时的主体
-
grant_type: refresh_token
refresh_token:
:IBM Cloud IAM 刷新令牌。bss_account:
:您的 IBM Cloud 帐户标识。
- 使用 IBM Cloud API 密钥时的主体
-
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 }
您可以在
access_token
中找到新的 IBM Cloud IAM 令牌,并在 API 输出的refresh_token
字段中找到刷新令牌。 -
使用上一步中的令牌,继续使用 Red Hat OpenShift on IBM Cloud API 文档。
使用 CLI 刷新 IBM Cloud IAM 访问令牌并获取新的刷新令牌
您可以使用命令行来 设置集群上下文,下载 Red Hat OpenShift 集群的 kubeconfig
文件,并生成 IBM Cloud Identity and Access Management (IAM) 标识令牌和刷新令牌以提供认证。
您可以使用 IBM Cloud IAM 来更改令牌和会话的缺省到期时间。
Kubeconfig
会话 (session)- 在启动新的 CLI 会话时,或者在会话到期 (例如,缺省值为 24 小时之后) 之后,必须重置集群上下文。
- 标识令牌
- 通过 CLI 发出的每个 IAM 标识令牌都将在设置的时间段 (例如 20 分钟) 后到期。 标识令牌到期时,会向令牌提供程序发送刷新令牌以刷新标识令牌。 这将刷新您的认证,随后您可以继续对集群运行命令。
- 刷新令牌
- 刷新令牌将在设置的时间段 (例如 30 天) 后到期,或者管理员将撤销令牌。 如果刷新令牌过期,则无法刷新 ID 令牌,也就无法继续在 CLI 中运行命令。 您可以通过运行
ibmcloud oc cluster config --cluster <cluster_name>
获取新的刷新令牌。 此命令还会刷新标识令牌。