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は、クラスタを作成するために利用可能なさまざまなインフラストラクチャ・プロバイダをサポートしている。 詳しくは、 インフラストラクチャー・プロバイダーの概要 を参照してください。

バージョン 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: Red Hat OpenShift on IBM Cloud API を使用して、コミュニティー Kubernetes クラスターと Red Hat OpenShift クラスターの両方の IBM Cloud インフラストラクチャー・リソース (ワーカー・ノードなど) を管理します。
v2 API: Red Hat OpenShift on IBM Cloud v2 API を使用して、コミュニティー Kubernetes クラスターと Red Hat OpenShift VPC クラスターの両方の IBM Cloud インフラストラクチャー・リソース (ワーカー・ノードなど) を管理します。
Red Hat OpenShift API
v1 APIを使用します： Red Hat OpenShift API を使用してクラスタ内の Red Hat OpenShift および Kubernetes リソース（ポッドやネームスペースなど）を管理するには、 IBM Cloud API キーと Red Hat OpenShift アクセストークンを交換してログインする必要があります。 API キーを使用したクラスターへのログインを参照してください。
v2 API: v1と同じです。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 を使用したクラスターのデプロイメントの自動化

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 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
}

    IBM Cloud IAMトークンはAPI出力の access_token 、リフレッシュトークンは 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. サポートされているAPIのリストは、 Red Hat OpenShift on IBM Cloud APIドキュメントをご覧ください。

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

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. 前のステップで取得したトークンを使用して、 Red Hat OpenShift on IBM Cloud API ドキュメントの作業を続行します。