設定 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 API：https://containers.cloud.ibm.com/global/v1
v2 API：https://containers.cloud.ibm.com/global/v2
v3 API：https://containers.cloud.ibm.com/global/v3
API 參考資料文件
v1 和 v2 API
v3 API.
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: 針對 社群 Kubernetes 和 Red Hat OpenShift VPC 叢集，使用 Red Hat OpenShift on IBM Cloud v2 API 來管理 IBM Cloud 基礎架構資源 (例如工作者節點)。
Red Hat OpenShift API
v1 API: 若要使用 Red Hat OpenShift API 來管理叢集內的 Red Hat OpenShift 及 Kubernetes 資源 (例如 Pod 或 Pod)，您必須透過將 IBM Cloud API 金鑰交換為 Red Hat OpenShift 存取記號來登入。 請參閱 使用 API 金鑰登入叢集。
v2 API: 與 v1 相同; 請參閱 使用 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：回應只包括經典基礎結構提供者特有的資訊，例如 GET 群集中的 VLAN 和 Worker 回應。
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 帳戶 ID 的 IBM Cloud Identity and Access Management (IAM) 記號。 取決於您向 IBM Cloud 進行鑑別的方式，您可以在下列選項之間進行選擇，以自動建立 IBM Cloud IAM 記號。

未聯合 ID
  • 產生 IBM Cloud API 金鑰： 除了使用 IBM Cloud 使用者名稱和密碼之外，您還可以使用 IBM Cloud API 金鑰。IBM Cloud API 金鑰取決於所產生的 IBM Cloud 帳戶。 您不能將 IBM Cloud API 金鑰與不同的帳號 ID 結合在同一 IBM Cloud IAM 令牌中。 若要存取使用您 IBM Cloud API 金鑰根據帳戶以外之帳戶建立的叢集，您必須登入帳戶才能產生新的 API 金鑰。
  • IBM Cloud 使用者名稱和密碼： 您可以依照本主題中的步驟，完全自動建立 IBM Cloud IAM 存取代碼。
聯合 ID
  • 產生 IBM Cloud API 金鑰: IBM Cloud API 金鑰 與為其產生的 IBM Cloud 帳戶相依。 您不能將 IBM Cloud API 金鑰與不同的帳號 ID 結合在同一 IBM Cloud IAM 令牌中。 若要存取使用您 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 編碼的使用者名稱 bx 和密碼 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 帳戶 ID。 將 TOKEN 改為 IBM Cloud IAM 令牌，該令牌是您在上一步中從 API 輸出的 access_token 欄位中擷取的。 在 API 輸出中，您可以在 resources.metadata.guid 欄位中找到 IBM Cloud 帳戶的 ID。

    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 認證及您要使用之帳戶 ID 的新 IBM Cloud IAM 記號。

    如果您使用 IBM Cloud API 金鑰，則必須使用為其建立 API 金鑰的 IBM Cloud 帳戶 ID。 若要存取其他帳戶中的群集，請登入此帳戶，並建立基於此帳戶的 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
    • username:您的 IBM Cloud 用戶名。
    • password：您的 IBM Cloud 密碼。
    • bss_account：您在前一個步驟中擷取的 IBM Cloud 帳戶 ID。
    IBM Cloud API 金鑰的內文
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey：您的 IBM Cloud API 金鑰。
    • bss_account：您在前一個步驟中擷取的 IBM Cloud 帳戶 ID。
    IBM Cloud 一次性密碼的內文
    • grant_type: urn:ibm:params:oauth:grant-type:passcode
    • passcode：您的 IBM Cloud 密碼。
    • bss_account：您在前一個步驟中擷取的 IBM Cloud 帳戶 ID。

    下列範例顯示 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) 存取記號都會在一個小時後到期。 必須定期重新整理存取記號才可確保對 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 文件。