設定 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 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 帳戶 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 金鑰與同一 IBM Cloud IAM 憑證中的其他帳戶 ID 結合使用。 若要存取使用您 IBM Cloud API 金鑰根據帳戶以外之帳戶建立的叢集，您必須登入帳戶才能產生新的 API 金鑰。
  • IBM Cloud 使用者名稱和密碼： 您可以依照本主題中的步驟，完全自動化建立您的 IBM Cloud IAM 存取憑證。
聯合 ID
  • 產生 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= 等同於使用 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 替換為您從上一步驟 API 輸出中的 access_token 欄位所取得的 IBM Cloud IAM 憑證。 在 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 文件。