API のセットアップ

IBM Cloud® Kubernetes Service API を使用して、コミュニティー Kubernetes クラスターまたは Red Hat OpenShift クラスターを作成および管理できます。 CLI を使用するには、CLI のセットアップを参照してください。

API について

IBM Cloud Kubernetes Service API は、ユーザーにサービスを提供するために必要なコンピュート、ネットワーキング、およびストレージのリソースをアプリが得られるように、クラスターの IBM Cloud インフラストラクチャー・リソースのプロビジョニングと管理を自動化します。

このAPIは、クラスタを作成するために利用可能なさまざまなインフラストラクチャプロバイダーに対応しています。 詳しくは、 インフラストラクチャー・プロバイダーの概要 を参照してください。

バージョン 2 (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: GET、POST、PUT、PATCH、DELETE などの HTTP メソッドを介して対話するリソースに焦点を当てた Representational State Transfer (REST)。
v2 API: HTTP メソッド GET および POST のみを介したアクションに焦点を当てたリモート・プロシージャー・コール (RPC)。
サポート対象のコンテナー・プラットフォーム
v1 API: IBM Cloud Kubernetes Service API を使用して、コミュニティー Kubernetes クラスターと Red Hat OpenShift クラスターの両方の IBM Cloud インフラストラクチャー・リソース (ワーカー・ノードなど) を管理します。
v2 API: IBM Cloud Kubernetes Service v2 API を使用して、コミュニティー Kubernetes クラスターと Red Hat OpenShift VPC クラスターの両方の IBM Cloud インフラストラクチャー・リソース (ワーカー・ノードなど) を管理します。
Kubernetes API
v1 API: Kubernetes API を使用してクラスター内の Kubernetes リソース (ポッドや名前空間など) を管理するには、Kubernetes API を使用したクラスターの操作を参照してください。
v2 API: v1 と同じです。Kubernetes API を使用したクラスターの操作を参照してください。
サポートされる API (インフラストラクチャー・タイプ別)
v1 API: classic
v2 API: vpc および classic
  • vpc プロバイダーは、複数の VPC サブプロバイダーをサポートするように設計されています。 サポートされる VPC サブプロバイダーは vpc-gen2 であり、これは第 2 世代コンピュート・リソースの VPC クラスターに対応します。
  • プロバイダー固有の要求の URL には、v2/vpc/createCluster などのようにパス・パラメーターが含まれます。 一部の API は、特定のプロバイダーでのみ使用できます。例えば、クラシック用の GET vlan や VPC 用の GET vpcs などがあります。
  • 指定したプロバイダーの応答だけを返させたい場合は、プロバイダーに依存しない要求に、プロバイダー固有の本体パラメーター (通常は {"provider": "vpc"} のような JSON 形式で指定します) を指定することができます。
GET 応答
v1 API: リソース (GET v1/clusters など) の集合用の GET メソッドは、リスト内の各リソースについて、個々のリソース (GET v1/clusters/{idOrName} など) 用の GET メソッドと同じ詳細情報を返します。
v2 API: 応答をより迅速に返すために、リソース (GET v2/clusters など) のコレクション用の v2 GET メソッドは、個々のリソース (GET v2/clusters/{idOrName}など) 用の GET メソッドで詳述される情報のサブセットのみを返します。 一部のリスト応答には、返された項目がクラシック・インフラストラクチャーと VPC インフラストラクチャーのどちらに該当するかを示すプロバイダー・プロパティーが含まれています。 例えば、GET zones リストでは、クラシック・インフラストラクチャー・プロバイダーでのみ利用できる mon01 のような結果が返されることもあれば、VPC インフラストラクチャー・プロバイダーでのみ利用できる us-south-01 のような結果が返されることもあります。
クラスター、ワーカー・ノード、およびワーカー・プールの応答
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 IAM (ID およびアクセス管理) トークン (クラスターの作成に使用した IBM Cloud アカウント ID が入っているもの) を渡す必要があります。 IBM Cloud での認証方法に応じて、IBM Cloud IAM トークンの作成を自動化するための次のオプションから選択できます。

非フェデレーテッド ID
  • 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 ユーザー名とパスワード: このトピックに記載されたステップに従って、IBM Cloud IAM アクセス・トークンの作成を完全に自動化できます。
統合 ID
  • IBM Cloud API キーを生成: IBM Cloud API キーは、生成対象の IBM Cloud アカウントに依存します。 同じ IBM Cloud IAM トークン内で IBM Cloud API キーを別のアカウント ID と組み合わせることはできません。 IBM Cloud API キーの基となっているアカウント以外のアカウントを使用して作成されたクラスターにアクセスするには、そのアカウントにログインして新しい API キーを生成する必要があります。
  • ワンタイム・パスコードを使用: ワンタイム・パスコードを使用して IBM Cloud で認証を行う場合、IBM Cloud IAM トークンの作成を完全に自動化することはできません。ワンタイム・パスコードを取得するには、Web ブラウザーと手動で対話する必要があるためです。 IBM Cloud IAM トークンの作成を完全に自動化するには、代わりに IBM Cloud API キーを作成する必要があります。
  • 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"
}

    IBM Cloud のIAMトークンは、API出力の「 access_token 」フィールドで確認できます。 次のステップでさらにヘッダー情報を取得するため、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= は、ユーザー名 bx とパスワード bx の URL エンコード許可に相当します。
    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の出力結果において、「 IBM Cloud 」のIAMトークンは「 access_token 」フィールドに、「 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. サポートされているAPIのリストは、 IBM Cloud Kubernetes Service APIドキュメントをご覧ください。

API を自動化に使用する場合には、API からの応答に含まれるファイルに依存するのではなく、API からの応答を使用してください。 例えば、クラスター・コンテキストの Kubernetes 構成ファイルは変更される可能性があるため、GET /v1/clusters/{idOrName}/config 呼び出しを使用する場合は、このファイルの具体的な内容に基づいて自動化をビルドしないでください。

Kubernetes API を使用したクラスターの処理

IBM Cloud Kubernetes Service では、 Kubernetes API を使用してクラスタを操作することができます。

以下の手順では、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 これは、ユーザー名「 kube 」とパスワード「 kube 」に対する、 URL 形式でエンコードされた認証情報に相当します。
    Body
    • 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. 現在のIDでクラスタにアクセスする前に、以下のリクエストを実行する必要があります。

    POST https://containers.cloud.ibm.com/global/v2/applyRBAC
    ヘッダー
    Authorization: bearer <TOKEN> IBM Cloud のIAMアクセストークン
    Body
    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 マスターのデフォルト・サービス・エンドポイントの URL を取得します。 API 出力の masterURL で URL を確認できます。

    クラスターでパブリック・クラウド・サービス・エンドポイントのみ、またはプライベート・クラウド・サービス・エンドポイントのみを有効にした場合は、masterURL にはこのエンドポイントがリストされます。 クラスターでパブリック・クラウド・サービス・エンドポイントとプライベート・クラウド・サービス・エンドポイントの両方を有効にした場合は、masterURL にはデフォルトでパブリック・クラウド・サービス・エンドポイントがリストされます。 代わりにプライベート・クラウド・サービス・エンドポイントを使用するには、出力の privateServiceEndpointURL フィールド内でその URL を見つけます。

    GET https://containers.cloud.ibm.com/global/v2/getCluster?cluster=<cluster_name_or_ID>
    ヘッダー
    • Authorization: IBM Cloud IAM アクセス・トークン。
    パス

    以下の例は、パブリック・クラウド・サービス・エンドポイント要求の出力を示しています。

    ...
"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 IAM (ID およびアクセス管理) アクセス・トークンは、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
    Body
    • 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"
}

    新しい IBM Cloud IAMトークンは、API出力の「 access_token 」フィールドで確認できます。

  2. 前の手順で取得したトークンを使用して、 IBM Cloud Kubernetes Service APIのドキュメントの操作を続けてください。