IBM Cloud Docs
API のセットアップ

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
API リファレンス資料
v1 API: https://containers.cloud.ibm.com/global/swagger-global-api/
v2 API: https://containers.cloud.ibm.com/global/swagger-global-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 トークンの作成を自動化するための次のオプションから選択できます。

API swagger JSONファイルを使用して、自動化作業の一部としてAPIと対話できるクライアントを生成することもできる。

非フェデレーテッド 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 キーを作成する必要があります。

  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
}

    IBM Cloud IAMトークンはAPI出力の 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 アクセス・トークン、リフレッシュ・トークン、Kubernetes API 要求を実行するクラスターの ID、クラスターが配置されている IBM Cloud Kubernetes Service リージョンを取得します。

  2. IBM Cloud IAMリフレッシュトークンとIAMアクセストークンを取得する。

    POST https://iam.cloud.ibm.com/identity/token
    ヘッダー
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic Yng6Yng=``Yng6Yng= は、ユーザー名 bx とパスワード bx の URL エンコード許可に相当します。
    • cache-control: no-cache
    Body
    • delegated_refresh_token_expiry: 600
    • receiver_client_ids: kube
    • response_type: delegated_refresh_token
    • refresh_token: IBM Cloud IAM リフレッシュ・トークン。
    • grant_type: refresh_token

    以下の例は、直前の API 要求からの出力を示しています。

    {
"access_token": <access_token>
"refresh_token": <delegated_refresh_token>
}

  3. 前の手順の委任リフレッシュ・トークンを使用して、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
    • cache-control: no-cache
    Body
    • refresh_token: IBM Cloud IAM 委任リフレッシュ・トークン。
    • grant_type: urn:ibm:params:oauth:grant-type:delegated-refresh-token

    以下の例は、直前の API 要求からの出力を示しています。

    {
"access_token": "<iam_access_token>",
"id_token": "<iam_id_token>",
"refresh_token": "<iam_refresh_token>",
"token_type": "Bearer",
"expires_in": 3600,
"expiration": 1553629664,
"scope": "ibm openid containers-kubernetes"
}

  4. 現在のIDでクラスタにアクセスする前に、以下のリクエストを実行する必要があります。

    POST https://containers.test.cloud.ibm.com/global/v2/applyRBAC
    ヘッダー
    Authorization: bearer <TOKEN> IBM Cloud IAM アクセストークン
    Body
    cluster: <cluster_name_or_ID>

  5. RBACの同期は非同期なので、同期が完了するまで以下のリクエストを実行することに注意。

    GET https://containers.test.cloud.ibm.com/global/v2/getRBACStatus?cluster=<cluster_name_or_ID>

-H "Authorization: $ " {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 を見つけます。
   {: note}

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

  1. プライベート・クラウド・サービス・エンドポイントを使用するには、最初に VPN 接続からプライベート・ネットワークにルーティング可能なロード・バランサー IP を使用して、プライベート・クラウド・サービス・エンドポイントを公開する必要があります。

  2. 前に取得した IAM ID トークンを使用して、クラスターに対して Kubernetes API 要求を実行します。 例えば、クラスターで実行されている Kubernetes バージョンをリストします。

    API テスト・フレームワークで SSL 証明書検査を有効にしている場合は、この機能を必ず無効にしてください。

    GET <masterURL>/version
    ヘッダー
    • Authorization: bearer <id_token>
    パス
    • <masterURL>: 前のステップで取得した、Kubernetes マスターのサービス・エンドポイント。

    以下の例は、直前の API 要求の出力を示しています。

    {
"major": "1",
"minor": "1.32",
"gitVersion": "v1.32+IKS",
"gitCommit": "c35166bd86eaa91d17af1c08289ffeab3e71e11e",
"gitTreeState": "clean",
"buildDate": "2019-03-21T10:08:03Z",
"goVersion": "go1.11.5",
"compiler": "gc",
"platform": "linux/amd64"
}

  3. 最新の Kubernetes バージョンでサポートされている API のリストは、 Kubernetes API ドキュメントをご覧ください。 必ず、ご使用のクラスターの Kubernetes バージョンに一致する API 資料を使用してください。 最新 Kubernetes バージョンを使用しない場合は、URL の末尾にバージョンを追加します。 例えば、バージョン 1.12 の API 資料にアクセスするには、v1.12 を追加します。

IAM アクセストークンのリフレッシュと、API を使用した新しいリフレッシュトークンの取得

API を介して発行されるすべての IBM Cloud IAM (ID およびアクセス管理) アクセス・トークンは、1 時間後に有効期限が切れます。 IBM Cloud API へのアクセスを確保するには、アクセス・トークンを定期的にリフレッシュする必要があります。 同じ手順を使用して、新しいリフレッシュ・トークンを取得できます。

まず始めに、新しいアクセス・トークンを要求するために使用できる IBM Cloud IAM リフレッシュ・トークンまたは IBM Cloud API キーを用意してください。

  • リフレッシュ・トークン: IBM Cloud API を使用したクラスターの作成と管理のプロセスの自動化 の説明に従います。
  • API キー: 次のように IBM Cloud API キーを取得します。
    1. メニュー・バーから、「管理」 > **「アクセス (IAM)」**をクリックします。
    2. **「ユーザー」**ページをクリックして、自分を選択します。
    3. **「API キー」ペインで、「IBM Cloud API キーの作成」**をクリックします。
    4. API キーの**「名前」と「説明」を入力し、「作成」**をクリックします。
    5. **「表示」**をクリックして、生成された API キーを確認します。
    6. API キーをコピーして、新しい IBM Cloud IAM アクセス・トークンを取得できるようにします。

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
    • Authorization: Basic Yng6Yng=: Yng6Yng= は、ユーザー名 bx およびパスワード bx の URL エンコード許可に相当します。
    リフレッシュ・トークン使用時の本体
    • grant_type: refresh_token
    • refresh_token: IBM Cloud IAM リフレッシュ・トークン。
    • bss_account: IBM Cloud アカウント ID。
    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
}

    新しい IBM Cloud IAM トークンは access_token に、リフレッシュトークンは API 出力の refresh_token フィールドにあります。

  2. 前のステップで取得したトークンを使用して、 IBM Cloud Kubernetes Service API ドキュメントの作業を続行します。

CLI を使用した IBM Cloud IAM アクセス・トークンのリフレッシュと新しいリフレッシュ・トークンの取得

認証を行えるように、コマンド・ラインを使用して、クラスター・コンテキストを設定し、Kubernetes クラスターの kubeconfig ファイルをダウンロードし、IBM CloudID およびアクセス管理 (IAM) の ID トークンとリフレッシュ・トークンを生成することができます。

IBM Cloud IAM を使用して、トークンとセッションのデフォルトの有効期限を変更できます。

Kubeconfig セッション
新しい CLI セッションを開始するときや、セッションの有効期限が切れた後 (デフォルトの 24 時間後など) には、クラスター・コンテキストをリセットする必要があります。
ID トークン
CLI を使用して発行される IAM ID トークンはすべて、設定された期間 (20 分など) 後に有効期限が切れます。 ID トークンの有効期限が切れると、リフレッシュ・トークンがトークン・プロバイダーに送信され、ID トークンがリフレッシュされます。 認証がリフレッシュされ、クラスターに対して引き続きコマンドを実行できるようになります。
リフレッシュ・トークン
リフレッシュ・トークンは、設定された期間 (30 日など) 後、または管理者がトークンを取り消した場合に有効期限が切れます。 リフレッシュ・トークンの有効期限が切れると、ID トークンはリフレッシュできず、CLI でコマンドの実行を続けることができません。 ibmcloud ks cluster config --cluster <cluster_name> を実行して、新しいリフレッシュ・トークンを取得できます。 このコマンドは ID トークンもリフレッシュします。