ESPv2 を使用した Cloud Run for Anthos での Endpoints のスタートガイド

このページでは、Cloud Run for Anthos の Cloud Endpoints を設定する方法について説明します。Endpoints は Extensible Service Proxy V2 ベータ版(ESPv2 ベータ版)API ゲートウェイとして使用します。Cloud Run for Anthos 向けに API 管理機能を提供するには、GKE クラスタで実行中の Cloud Run for Anthos にビルド済みの ESPv2 ベータ版コンテナをデプロイします。

この設定では、ESPv2 ベータ版がサービスに対するすべてのリクエストを傍受し、必要なチェック(認証など)を行ってから、該当するサービスを呼び出します。サービスが応答すると、ESPv2 ベータ版はテレメトリーを収集して報告します。

Endpoints の概要については、Endpoints についてEndpoints アーキテクチャをご覧ください。

タスクリスト

次のタスクリストを参照しながら、チュートリアルを実施してください。このチュートリアルを完了するには、すべてのタスクを行う必要があります。

  1. Google Cloud プロジェクトを作成する。独自の Cloud Run for Anthos をデプロイしていない場合は、サンプルのサービスをデプロイします。始める前にをご覧ください。

  2. Cloud Run for Anthos を有効にした GKE クラスタを作成する。

  3. Cloud Run for Anthos サービスのサンプルをデプロイする

  4. Endpoints API を記述する OpenAPI ドキュメントを作成し、Cloud Run for Anthos サービスへのルートを構成する。Endpoints を構成するをご覧ください。

  5. OpenAPI ドキュメントをデプロイして、マネージド サービスを作成します。Endpoints 構成をデプロイするをご覧ください。

  6. Endpoints サービス構成で新しい ESPv2 ベータ版 Docker イメージをビルドする。新しい ESPv2 ベータ版イメージをビルドするをご覧ください。

  7. 新しい ESPv2 ベータ版 Cloud Run for Anthos イメージをデプロイする。ESPv2 ベータ版 Cloud Run イメージをデプロイするをご覧ください。

  8. ESPv2 ベータ版 Cloud Run for Anthos サービスへのドメイン マッピングを作成する。

  9. API にリクエストを送信して構成をテストする。

  10. サービスに対するアクティビティを追跡します。API の活動を追跡するをご覧ください。

  11. クリーンアップ

準備

  1. Google アカウントにログインします。

    Google アカウントをまだお持ちでない場合は、新しいアカウントを登録します。

  2. Cloud Console のプロジェクト セレクタページで、Cloud プロジェクトを選択または作成します。

    プロジェクト セレクタのページに移動

  3. Google Cloud プロジェクトに対して課金が有効になっていることを確認します。プロジェクトに対して課金が有効になっていることを確認する方法を学習する

  4. 後で必要になるため、プロジェクト ID をメモしておきます。このページでは以降、このプロジェクト ID を ESP_PROJECT_ID とします。
  5. Cloud SDK をダウンロードしてインストールします
  6. デプロイしたサンプル サービスにリクエストを送信する場合は、cURL をインストールします。

gcloud コマンドラインを設定する

Cloud Run for Anthos for Anthos の gcloud コマンドラインを設定するには:

  1. データとサービスへのアクセスを Cloud SDK に対して承認していることを確認します。

    1. ログインします。

      gcloud auth login

    2. 表示された新しいブラウザタブで、ESPv2 ベータ版を Cloud Run for Anthos にデプロイするために作成した Google Cloud プロジェクトで、編集者またはオーナーのロールが割り当てられているアカウントを選択します。

  2. インストールした gcloud コンポーネントをアップデートします。

    gcloud components update
  3. プラットフォームを gke に設定し、gcloud のデフォルト プロジェクト設定を先ほど作成したものに設定します。

    gcloud config set run/platform gke
    gcloud config set project ESP_PROJECT_ID

    ESP_PROJECT_ID は、作成したプロジェクトのプロジェクト ID に置き換えます。

  4. 新しいクラスタに必要なゾーンを設定します。GKE がサポートされていれば、どのゾーンでも使用できます。次に例を示します。

    gcloud config set compute/zone ZONE

    ZONE は、実際のゾーンに置き換えます。たとえば、us-central1-a を使用します。GKE でサポートされている任意のゾーンを使用できます。

  5. プロジェクトで次の API を有効にします。これは、クラスタの作成や、コンテナのビルドと Google Container レジストリへのパブリッシュで必要になります。

    gcloud services enable container.googleapis.com containerregistry.googleapis.com cloudbuild.googleapis.com

Cloud Run for Anthos を有効にした GKE クラスタを作成する

クラスタを作成して Cloud Run for Anthos on Google Cloud 用に有効にするには:

  1. 次のコマンドで新しいクラスタを作成します。

    gcloud container clusters create CLUSTER_NAME \
      --addons=HttpLoadBalancing,CloudRun \
      --machine-type=n1-standard-4 \
      --num-nodes=3 \
      --enable-stackdriver-kubernetes

    CLUSTER_NAME は、クラスタに付ける名前で置き換えます。

    これらの手順では、クラスタの自動スケーリングを有効にしてクラスタのサイズを変更することはできませんが、Cloud Run for Anthos on Google Cloud ではクラスタ内のインスタンスが自動スケーリングされます。

  2. クラスタの作成が完了するまで待機します。作成プロセス中に、次のようなメッセージが表示されます。

    Creating cluster CLUSTER_NAME...done.
    Created [https://container.googleapis.com/v1/projects/ESP_PROJECT_ID/zones/ZONE/clusters/CLUSTER_NAME].

    また、出力には、出力の NODE_VERSION 列のクラスタのバージョンも示されます。たとえば、1.15.11-gke.11.14.10-gke.27 です。このドキュメントの後半で使用するので、クラスタのバージョンをメモしておいてください。

  3. gcloud コマンドラインを使用するときに指定しなくても済むように、新しいクラスタとクラスタのロケーションを gcloud のデフォルトに設定します。

    gcloud config set run/cluster CLUSTER_NAME
    gcloud config set run/cluster_location ZONE
  4. 次のコマンドを使用して、新しいクラスタの詳細を表示します。

    gcloud container clusters describe CLUSTER_NAME
  5. 次のコマンドを使用して、クラスタの認証情報を取得します。

    gcloud container clusters get-credentials CLUSTER_NAME

サンプル Cloud Run for Anthos コンテナをデプロイする

作成したクラスタに「hello」Cloud Run for Anthos サンプル コンテナをデプロイするには:

  1. Cloud Run に移動します

  2. [サービスを作成] をクリックします。

  3. 開発プラットフォームとして [Cloud Run for Anthos] を選択します。

  4. [使用可能なクラスタ] プルダウン メニューで、先ほど作成したクラスタを選択します。

  5. サービス名として hello を使用します。他の名前を使用することもできますが、その場合は以降もその名前を使用してください。以降の説明では、hello を使用するものとします。

  6. [接続] で [内部] を選択して、サービスが外部からアクセスできないようにします。

  7. [次へ] をクリックして、サービス作成フォームの 2 ページ目に進みます。

  8. [コンテナ イメージの URL] として gcr.io/cloudrun/hello を指定します。

  9. [作成] をクリックしてイメージを Cloud Run for Anthos にデプロイし、デプロイの完了を待ちます。

    完了したら、[リビジョン] 画面が表示されます。デプロイされたサービスの URL は次のとおりです。

    http://hello.default.svc.cluster.local

    内部サービスを作成すると、GKE は DNS 名を作成します。これは外部リクエストではなく、クラスタ内から発生したリクエストに対してのみ解決できます。クラスタ外からこのリンクにアクセスすることはできません。詳細については、Cloud Run サービスをご覧ください。

  10. cURL を使用してサービスが正しく動作していることを確認するには、デスクトップからクラスタへのトンネルを設定します。これらの手順を表示するには、[リビジョン] 画面で URL の右側にある アイコンをクリックします。

    リビジョン画面。

  11. パネルが開き、内部サービスへのアクセスに使用する 2 つのコマンドが表示されます。最初のコマンドは 2 番目のコマンドで使用されるポート転送を設定するため、これらのコマンドは 2 つの個別のターミナル ウィンドウで実行する必要があります。

    cURL コマンドを実行すると、サービスからの出力が次の形式で表示されます。

    <!doctype html>
    <html lang=en>
    <head>
    <meta charset=utf-8>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Congratulations | Cloud Run</title> 
    ...

エンドポイントの作成

OpenAPI 仕様 v2.0 に基づいて、バックエンド サービスの surface と認証要件を記述する OpenAPI ドキュメントを用意する必要があります。また、ESPv2 ベータ版がサービスを呼び出すために必要な情報を取得できるよう、このドキュメントには各サービスの URL を設定した Google 固有のフィールドも追加する必要があります。OpenAPI を初めて使用する場合は、OpenAPI の概要で詳細をご覧ください。

OpenAPI 仕様のホスト フィールドの設定について

OpenAPI 仕様の host フィールドで、Cloud Run for Anthos サービスへのアクセスに使用する Endpoints サービス名を指定します。Endpoints サービス名は、ドメイン名の形式です。

API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog

Endpoints サービス名はドメイン名に対応しているため、名前は次のルールに従う必要があります。

  • 使用できるのは小文字、数字、ピリオド、ダッシュのみです。
  • ダッシュで始めることはできません。
  • アンダースコアを含めることはできません。

例:

hello-api.endpoints.ESP_PROJECT_ID.cloud.goog

OpenAPI 仕様の作成

  1. openapi-run-anthos.yaml という名前のテキスト ファイルを作成します

  2. Cloud Run for Anthos バックエンド サービスは、openapi-run-anthos.yaml ファイルの先頭にある x-google-backend 定義で定義されます。例:

    swagger: '2.0'
    info:
      title: Cloud Endpoints + Cloud Run
      description: Sample API on Cloud Endpoints with a Cloud Run backend
      version: 1.0.0
    host: API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
    x-google-endpoints:
    - name: API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
      target: "INGRESS-IP"
    schemes:
      - https
    produces:
      - application/json
    x-google-backend:
      address: http://hello.default.svc.cluster.local
      disable_auth: true
    paths:
      /hello:
        get:
          summary: Greet a user
          operationId: hello
          responses:
            '200':
              description: A successful response
              schema:
                type: string

    yaml 形式ではインデントが重要です。たとえば、host フィールドは info と同じレベルにする必要があります。

  3. host フィールドに、Cloud Run for Anthos サービスへのアクセスに使用する Endpoints API のドメイン名を次の形式で指定します。

    API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog

    例:

    hello-api.endpoints.ESP_PROJECT_ID.cloud.goog
  4. x-google-endpoints 拡張機能は、cloud.goog ドメインにある Endpoints サービスの DNS エントリを次の形式で登録します。

    x-google-endpoints:
      - name: "API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog"
      target: "IP_ADDRESS"

    IP_ADDRESS は、クラスタの istio-ingress サービスの IP です。この IP アドレスを確認するには、次のようにします。

    1. Cloud Console で Google Kubernetes Engine ページに移動します。

      Google Kubernetes Engine に移動

    2. 左側のナビゲーション パネルで、[Services と Ingress] をクリックして、サービスのリストを表示します。

    3. クラスタ バージョンが 1.15.3-gke.19 以降、1.14.3-gke.12 以降、1.13.10-gke.8 以降のいずれかに相当する場合は、下方向にスクロールして istio-ingress サービスを表示します。それ以外のクラスタ バージョンの場合は、istio-ingressgateway サービスまで下にスクロールします。

    4. ロードバランサの横に表示されている外部 IP アドレスをコピーします。このとき、ポート設定(表示されている場合)は省きます。たとえば、IP が XX.XXX.XX.XXX:15020 の場合、:15020 は省略します。表示されている他の IP アドレスは無視してください。

  5. x-google-backend セクションの address フィールドで、Cloud Run for Anthos の「hello」サービスの内部 DNS 名を指定し、このサービスに対する認証を無効にします。これは、ESPv2 ベータ版から Cloud Run for Anthos サービスへの呼び出しがクラスタ内から内部呼び出しとして行われるために必要です。したがって、認証は必要ありません。

  6. openapi-run-anthos.yaml ファイルの title プロパティの値をメモします。

    title: Cloud Endpoints + Cloud Run 
  7. title プロパティの値は、構成をデプロイした後の Endpoints サービスの名前になります。

  8. OpenAPI ドキュメントを保存します。

Endpoints に必要な OpenAPI ドキュメントのフィールドについては、Endpoints を構成するをご覧ください。

Endpoints 構成をデプロイする

Endpoints 構成をデプロイするには、gcloud endpoints services deploy コマンドを使用します。このコマンドを実行すると、Service Management を使用してマネージド サービスが作成されます。

Endpoints 構成をデプロイするには:

  1. OpenAPI ドキュメントが格納されているディレクトリに移動します。

  2. 構成をアップロードしてマネージド サービスを作成します。

    gcloud endpoints services deploy openapi-run-anthos.yaml \
      --project ESP_PROJECT_ID

    これにより、openapi-run-anthos.yaml ファイルの host フィールドに指定した名前で、新しい Endpoints サービスが作成されます。Endpoints サービスは OpenAPI ドキュメントに従って構成されています。

    Service Management でサービスの作成と構成が行われるとき、情報がターミナルに出力されます。デプロイが完了すると、次のようなメッセージが表示されます。

    Service Configuration [CONFIG_ID] uploaded for service [API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog]

    CONFIG_ID は、デプロイによって作成される一意の Endpoints サービス構成 ID です。例:

    Service Configuration [2019-02-01r0] uploaded for service [hello-api.endpoints.ESP_PROJECT_ID.cloud.goog] 

    サービス構成 ID は、日付スタンプとそれに続くリビジョン番号で構成されます。同じ日に openapi-run-anthos.yaml を再度デプロイすると、サービス構成 ID のリビジョン番号が増分されます。Cloud Console で [Endpoints] の [サービス] ページを開くと、サービス構成とデプロイの履歴を確認できます。

    エラー メッセージが表示された場合は、Endpoints 構成のデプロイのトラブルシューティングをご覧ください。

必要なサービスの確認

Endpoints と ESP を使用するには、少なくとも次の Google サービスの有効化が必要です。
名前 タイトル
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API
endpoints.googleapis.com Google Cloud Endpoints

ほとんどの場合、gcloud endpoints services deploy コマンドによってこれらの必須サービスが有効化されます。ただし、以下の状況では、gcloud コマンドは正常に完了しますが、必須サービスが有効になりません。

  • Terraform などのサードパーティのアプリケーションを使用していて、上記のサービスを含めていない場合。

  • 上記のサービスが明示的に無効にされている既存の Google Cloud プロジェクトに Endpoints 構成をデプロイした場合。

必要なサービスが有効になっていることを確認するには、次のコマンドを実行します。

gcloud services list

必要なサービスが表示されない場合は、次のコマンドを使用してサービスを有効にします。

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com

Endpoints サービスも有効にします。

gcloud services enable ENDPOINTS_SERVICE_NAME

ENDPOINTS_SERVICE_NAME を確認するには、次のいずれかを行います。

  • Endpoints 構成をデプロイ後、Cloud Console の [Endpoints] ページに移動します。[サービス名] 列に、考えられる ENDPOINTS_SERVICE_NAME のリストが表示されます。

  • OpenAPI の場合、ENDPOINTS_SERVICE_NAME は OpenAPI 仕様の host フィールドで指定したものです。gRPC の場合、ENDPOINTS_SERVICE_NAME は gRPC Endpoints 構成の name フィールドで指定したものです。

gcloud コマンドの詳細については、gcloud サービスをご覧ください。

新しい ESPv2 ベータ版 Cloud Run for Anthos イメージをビルドする

新しい ESPv2 ベータ版 Docker イメージに Endpoints サービス構成をビルドします。このイメージを作成したら、それをクラスタにデプロイできます。

新しい ESPv2 ベータ版 Docker イメージにサービス構成をビルドするには:

  1. gcloud SDK がインストールされているローカルマシンにこのスクリプトをダウンロードし、次のように実行します。

    chmod +x gcloud_build_image
    ./gcloud_build_image -s API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog \
    -c CONFIG_ID -p ESP_PROJECT_ID

    このスクリプトは、gcloud コマンドを使用してサービス構成をダウンロードし、新しい ESPv2 ベータ版イメージにサービス構成を組み込み、新しいイメージをプロジェクトのコンテナ レジストリにアップロードします。このスクリプトは、ESPv2 ベータ版の最新リリースを自動的に使用し、対象のリリースは出力イメージ名で ESP_VERSION として表されます。出力イメージは次の場所にアップロードされます。

    gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID

ESPv2 ベータ版 Cloud Run for Anthos イメージをデプロイする

ESPv2 ベータ版 Cloud Run for Anthos サービスのイメージをクラスタにデプロイします。

  1. 新しいイメージで ESPv2 ベータ版 Cloud Run for Anthos サービスをデプロイします。

    gcloud run deploy ESP_V2_SERVICE_NAME \
      --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID" \
      --platform gke \
      --project=ESP_PROJECT_ID

    ESP_PROJECT_ID には、ESPv2 ベータ版サービスに使用する名前を指定します。この例では、ESP_V2_SERVICE_NAMEespv2 に設定します。

  2. CORS を有効にするなどの追加の ESPv2 ベータ版起動オプションを使用するように Endpoints を構成する場合は、引数を ESPv2_ARGS 環境変数に渡すことができます。

    gcloud run deploy ESP_V2_SERVICE_NAME \
      --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID" \
      --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
      --platform gke \
      --project ESP_PROJECT_ID

    使用可能なオプション、複数のオプションの指定方法など、ESPv2_ARGS 環境変数の詳細と設定例については、Extensible Service Proxy V2 ベータ版のフラグをご覧ください。

ESPv2 ベータ版サービスは外部サービスとしてデプロイされるため、次の形式の cURL コマンドを使用してアクセスできます。

curl -H "Host: espv2.default.example.com" http://IP_ADDRESS

ここで、IP_ADDRESS は、クラスタの istio-ingress サービスの IP アドレスです。

この cURL コマンドを表示するには、デプロイされた ESPv2 ベータ版 Cloud Run for Anthos サービスの [リビジョン] 画面で、ESPv2 ベータ版 URL の右側にある IMAGE アイコンをクリックします。

ESPv2 ベータ版サービスを介して Endpoints サービスに対して API 呼び出しを行えるようになりました。たとえば、/hello のパスを使用して Endpoints サービスにリクエストを送信するには、次の形式を使用します。

curl -H "Host: espv2.default.example.com" http://IP_ADDRESS/hello

ただし、Endpoints サービスへのすべてのリクエストで host ヘッダーを指定するのはユーザー フレンドリーではありません。次のセクションでは、ドメイン サービスを設定して、ESPv2 ベータ版を介して Endpoints サービスを簡単に呼び出せるようにします。

ESPv2 ベータ版 Cloud Run for Anthos サービスにドメイン マッピングを作成する

リクエスト時に host ヘッダーを省略できるようにするには、ESPv2 ベータ版サービスのドメイン マッピングを追加します。

  1. Cloud Run に移動します

  2. [カスタムドメインの管理] を選択します。

  3. [マッピングを追加] を選択します。

  4. プルダウンから、[サービス ドメイン マッピングを追加] を選択します。

  5. [マッピングを追加] のポップアップの [マッピング先のサービスを選択] フィールドで、ESPv2 ベータ版サービスを選択します。

  6. [ドメイン名を入力] フィールドに、Endpoints を介して Cloud Run for Anthos サービスにアクセスするために使用するドメイン名を指定します。例:

    API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog

    ここで、API_NAME は Endpoints API の名前です。この例では、「hello-api」を使用できます。

    hello-api.endpoints.ESP_PROJECT_ID.cloud.goog

  7. [続行] をクリックします。マッピングの概要が表示されます。

  8. [完了] を選択してマッピングを保存します。

API にリクエストを送信する

cURL を使用して HTTP リクエストを API に送信します。

curl -X GET "http://hello-api.endpoints.ESP_PROJECT_ID.cloud.goog/hello"

正常なレスポンスが返されなかった場合は、レスポンス エラーのトラブルシューティングをご覧ください。

HTTPS を使用するように Endpoints API を構成する

Cloud Run for Anthos on Google Cloud での自動 TLS サポートはデフォルトでは無効になっています。この例では、ESPv2 ベータ版を介して Endpoints API にアクセスする際に、HTTP を使用して呼び出しを行います。

HTTPS を使用してリクエストをサポートするように ESPv2 ベータ版を構成できます。内部バックエンド サービスである「hello」ではなく、外部サービスである ESPv2 ベータ版で HTTPS サポートを構成します。

ESPv2 ベータ版で HTTPS をサポートするには、次の手順を行う必要があります。

  1. ドメインを所有している。ドメインをお持ちでない場合は、Google または別のドメイン ベンダーからドメインを取得します。

  2. ESPv2 ベータ版サービスのドメイン マッピングを作成し、ドメイン マッピング ページの手順に沿って DNS レコードを更新する。

    Google Domains からドメインを取得した場合は、そのドメインを DNS サーバーとして使用します。それ以外の場合は、Cloud DNS または任意の DNS サーバーを使用します。Google Domains のドメインを使用するのが最も簡単な方法です。

  3. Endpoints OpenAPI 仕様:

    1. host フィールドを *.cloud.goog ではなくドメインを参照するように設定します。

    2. x-google-endpoints タグとその 2 つの子プロパティを削除します。

詳細な手順とチュートリアルについては、HTTPS 証明書と自動 TLS 証明書を有効にするをご覧ください。

API の活動を追跡する

  1. Cloud Console で [エンドポイント] の [サービス] ページに移動して、API のアクティビティ グラフを確認します。

    Endpoints のアクティビティ グラフを表示

    グラフにリクエストが反映されるまでしばらくかかります。

  2. [ログビューア] ページで API のリクエストログを確認します。

    Endpoints のリクエストログを表示

API のデベロッパー ポータルを作成する

Cloud Endpoints Portal を使用してデベロッパー ポータルを作成できます。デベロッパー ポータルとは、サンプル API の操作に使用できるウェブサイトです。詳細については、Cloud Endpoints Portal の概要をご覧ください。

クリーンアップ

このクイックスタートで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、次の手順に従います。

このチュートリアルで使用したサービスを停止するには、API と API インスタンスを削除するをご覧ください。

次のステップ