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
    • 許可: 基本 Yng6Yng= Yng6Yng= URL でエンコードされた、 ユーザー名bx とパスワードbx の認証情報と同じです。
    IBM Cloud ユーザー名とパスワードの本文
    • grant_type: password
    • response_type: cloud_iam uaa
    • username: IBM Cloud ユーザー名。
    • password: IBM Cloud パスワード。
    • uaa_client_id: cf
    • uaa_client_secret: uaa_client_secret キーは値を指定せずに追加します。
    IBM Cloud API キーの本文
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • response_type: cloud_iam uaa
    • apikey: IBM Cloud API キー
    • uaa_client_id: cf
    • uaa_client_secret: uaa_client_secret キーは値を指定せずに追加します。
    IBM Cloud ワンタイム・パスコードの本文
    • grant_type: urn:ibm:params:oauth:grant-type:passcode
    • response_type: cloud_iam uaa
    • passcode: IBM Cloud ワンタイム・パスコード。 ibmcloud login --sso を実行し、CLI 出力の説明に従って、Web ブラウザーを使用してワンタイム・パスコードを取得します。
    • uaa_client_id: cf
    • uaa_client_secret: uaa_client_secret キーは値を指定せずに追加します。

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

    {
"access_token": "<iam_access_token>",
"refresh_token": "<iam_refresh_token>",
"uaa_token": "<uaa_token>",
"uaa_refresh_token": "<uaa_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 フィールドから取得したIAMトークンである IBM Cloud に置き換えます。 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
    • response_type: cloud_iam uaa
    • username: IBM Cloud ユーザー名。
    • password: IBM Cloud パスワード。
    • uaa_client_ID: cf
    • uaa_client_secret: uaa_client_secret キーは値を指定せずに追加します。
    • bss_account: 前の手順で取得した IBM Cloud アカウント ID。
    IBM Cloud API キーの本文
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • response_type: cloud_iam uaa
    • apikey: IBM Cloud API キー。
    • uaa_client_ID: cf
    • uaa_client_secret: uaa_client_secret キーは値を指定せずに追加します。
    • bss_account: 前の手順で取得した IBM Cloud アカウント ID。
    IBM Cloud ワンタイム・パスコードの本文
    • grant_type: urn:ibm:params:oauth:grant-type:passcode
    • response_type: cloud_iam uaa
    • passcode: IBM Cloud パスコード。
    • uaa_client_ID: cf
    • uaa_client_secret:
    • bss_account: 前の手順で取得した IBM Cloud アカウント ID。 uaa_client_secret キーは値を指定せずに追加します。

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

    {
    "access_token": "<iam_token>",
    "refresh_token": "<iam_refresh_token>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expiration": 1493747503
}

    IBM Cloud のIAMトークンは access_token に、リフレッシュトークンは refresh_token フィールドのAPI出力に表示されます。

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

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

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

以下の手順では、Kubernetes マスターのパブリック・クラウド・サービス・エンドポイントに接続するために、クラスターのパブリック・ネットワーク・アクセスが必要です。

  1. API を使用したクラスターのデプロイメントの自動化の手順に従って、IBM Cloud IAM アクセス・トークン、リフレッシュ・トークン、Kubernetes API 要求を実行するクラスターの ID、クラスターが配置されている IBM Cloud Kubernetes Service リージョンを取得します。

  2. 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 エンコード許可に相当します。
    • 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 要求からの出力を示しています。

    {
"delegated_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 URL でエンコードされた、ユーザー名 とパスワード の認証情報と同じです。 kube kube
    • 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. 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": {
    ...}

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

  6. 前に取得した 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"
}

  7. 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 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
    • response_type: cloud_iam uaa
    • refresh_token: IBM Cloud IAM リフレッシュ・トークン。
    • uaa_client_ID: cf
    • uaa_client_secret:
    • bss_account: IBM Cloud アカウント ID。 uaa_client_secret キーは値を指定せずに追加します。
    IBM Cloud API キー使用時の本体
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • response_type: cloud_iam uaa
    • apikey: IBM Cloud API キー。
    • uaa_client_ID: cf
    • uaa_client_secret: uaa_client_secret キーは値を指定せずに追加します。

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

    {
    "access_token": "<iam_token>",
    "refresh_token": "<iam_refresh_token>",
    "uaa_token": "<uaa_token>",
    "uaa_refresh_token": "<uaa_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 トークンもリフレッシュします。