設定 API

您可以使用 IBM Cloud® Kubernetes Service API 來建立和管理您的社群 Kubernetes 或 Red Hat OpenShift 叢集。 若要使用 CLI，請參閱設定 CLI。

關於 API

IBM Cloud Kubernetes Service 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：使用 IBM Cloud Kubernetes Service API 來管理您的 IBM Cloud 基礎架構資源（例如工作節點），適用於社群版 Kubernetes 及 Red Hat OpenShift 叢集。
v2 API: 針對 社群 Kubernetes 及 Red Hat OpenShift VPC 叢集，使用 IBM Cloud Kubernetes Service v2 API 來管理 IBM Cloud 基礎架構資源 (例如工作者節點)。
Kubernetes API
v1 API：若要使用 Kubernetes API 來管理叢集內的 Kubernetes 資源（例如 Pod 或命名空間），請參閱 《使用 Kubernetes API 管理您的叢集》。
v2 API: 與 v1 相同; 請參閱 使用 Kubernetes 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 自動化進行叢集部署

您可以使用 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 帳戶 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 叢集。 如果您想要 針對叢集執行 Kubernetes API 要求，請務必記下您要使用之叢集的名稱或 ID。 列出「標準」叢集的範例要求。 

    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 來使用叢集

您可以使用 Kubernetes API 來與您的叢集進行互動，詳情請參閱 IBM Cloud Kubernetes Service。

以下說明要求您的叢集必須具備對公共網路的存取權限，才能連線至您的 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 等於 -encoded 授權的使用者名稱 和密碼。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 master 的預設服務端點 URL。 URL 您可以在 masterURL 處。

    如果您的叢集只啟用公用雲端服務端點或專用雲端服務端點，則會針對 masterURL 列出該端點。 如果針對叢集同時啟用公用及專用雲端服務端點，則依預設會列出 masterURL 的公用雲端服務端點。 若要改用私有雲服務端點，請在輸出的 privateServiceEndpointURL 欄位中找到 URL。

    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 所擷取叢集的名稱或 ID。

    下列範例顯示公用雲端服務端點要求的輸出。

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

  2. 若要使用專用雲端服務端點，您必須先 使用可從 VPN 連線遞送至專用網路的負載平衡器 IP 來公開專用雲端服務端點。

  3. 使用您稍早擷取的 IAM ID 記號，針對您的叢集執行 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"
		}
	]
 }

  4. 請參閱 Kubernetes API 文件，以查閱最新版 Kubernetes 所支援的 API 清單。 請確定使用符合叢集之 Kubernetes 版本的 API 文件。 若您未使用最新版的 Kubernetes，請在 URL 的末尾加上您的版本號。 例如，若要存取 1.12 版的 API 文件，請新增 v1.12。

透過 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. 請使用上一步驟取得的存取憑證，繼續參閱 IBM Cloud Kubernetes Service API 文件。