ESP をローカルまたは別のプラットフォームで実行する

このページでは、ローカルマシン、別のクラウド プロバイダ(Amazon Web Services(AWS)など)、または Google Cloud Platform(GCP)上にはない Kubernetes クラスタで Extensible Service Proxy(ESP)のインスタンスを構成して実行する方法を説明します。

ESP は、Linux や macOS のパソコン上、または仮想マシン(VM)上で実行可能です。Microsoft Windows はサポートされていません。アプリケーションと ESP を同じホストにデプロイすることも、異なるホストにデプロイすることもできます。ESP のローカル インスタンスをホストすると、次のことが可能になります。

  • 本番環境プラットフォームにデプロイする前に ESP を試す。
  • 構成されたセキュリティ設定が適切に動作することや、指標やログが [エンドポイント] の [サービス] ページに想定どおりに表示されることを検証する。

前提条件

前提として、このページでは次の点を想定しています。

  • ESP コンテナをローカルにデプロイする場合、または VM にデプロイする場合は、Docker がインストール済みである。詳しくは、Docker のインストールをご覧ください。

  • API をローカルにデプロイ済みであるか、ESP を実行するホストに到達可能なホストにデプロイ済みである。

  • API のマネージド サービスを作成するように Cloud Endpoints を構成済みで、その構成をデプロイ済みである。

ESP でテストするための API が必要な場合は、オプション: サンプル API の使用のサンプルコードを構成してデプロイできます。API をすでに構成してデプロイしている場合は、サービス アカウントの作成に進んでください。

オプション: サンプル API の使用

このセクションでは、Python バージョンの Endpoints 用 getting-started サンプルをローカルで構成してデプロイする方法を説明します。このセクションの手順は、ESP でテストするための API がない場合にのみ行ってください。

Cloud Endpoints getting-started のサンプルは、他の言語でも用意されています。目的の言語の getting-started サンプルがある GitHub の場所については、サンプルページをご覧ください。サンプルの README.md に記載されているローカル実行の手順を行った後、このセクションの手順に沿って Endpoints を構成してデプロイします。

必要なソフトウェアを入手する

Python 開発環境をまだ設定していない場合は、Python 開発環境の設定をご覧ください。次のものがインストールされていることを確認します。

サンプルコードを取得する

  1. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples
    
  2. サンプルコードが入っているディレクトリに移動します。

    cd python-docs-samples/endpoints/getting-started
    

エンドポイントを構成する

  1. サンプルコードのディレクトリで openapi.yaml 構成ファイルを開きます。

    swagger: "2.0"
    info:
      description: "A simple Google Cloud Endpoints API example."
      title: "Endpoints Example"
      version: "1.0.0"
    host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"
  2. host フィールドの YOUR-PROJECT-ID をご使用の GCP プロジェクト ID で置き換えます。

  3. openapi.yaml ファイルを保存します。

Endpoints 構成をデプロイする

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

  1. Cloud SDK を更新します。

    gcloud components update
    
  2. Cloud SDK(gcloud)が GCP にある対象のデータとサービスにアクセスできるよう許可されていることを確認します。

    gcloud auth login
    

    表示された新しいブラウザタブで、アカウントを選択します。

  3. ご使用のプロジェクト ID をデフォルト プロジェクトとして設定します。

    gcloud config set project YOUR-PROJECT-ID
    

    YOUR-PROJECT-ID は、openapi.yaml ファイルで指定した GCP プロジェクトのプロジェクト ID で置き換えます。

  4. 構成をデプロイします。

    gcloud endpoints services deploy openapi.yaml
    

Service Management は、openapi.yaml ファイル内の host フィールドで指定されたテキストを使用して、新しい Endpoints サービスを echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog という名前で作成し(存在しない場合)、OpenAPI 構成ファイルに基づいてそのサービスを構成します。

Service Management でサービスの作成と構成が行われるとき、情報がターミナルに出力されます。openapi.yaml ファイル内のパスが API キーを要求していない、という警告は無視してかまいません。正常に完了すると、次のようにサービス構成 ID とサービス名が括弧付きで表示されます。

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

上の例では、2017-02-13r0 がサービス構成 ID で、echo-api.endpoints.example-project-12345.cloud.goog がサービス名です。

ローカル サーバーを起動する

  1. virtualenv を作成してアクティブ化し、アプリケーションの依存関係をインストールします。

    virtualenv env
    source env/bin/activate
    pip install -r requirements.txt
    
  2. サーバーを開始します。

    python main.py
    
  3. 別のターミナル ウィンドウを開き、curl を使用してリクエストを送信します。

    curl --request POST \
        --header "content-type:application/json" \
        --data '{"message":"hello world"}' \
        http://localhost:8080/echo
    

    API によって送信メッセージがエコーバックされ、次のようなレスポンスが返されます。

    {
      "message": "hello world"
    }
    

サービス アカウントの作成

ESP で API を管理するには、Service Infrastructure のサービスが必要です。これらのサービスを呼び出すには、ESP でアクセス トークンを使用する必要があります。GKE、Compute Engine、App Engine フレキシブル環境などの GCP 環境に ESP をデプロイすると、ESP により、GCP メタデータ サービスを介してアクセス トークンが取得されます。

ローカル デスクトップ、オンプレミスの Kubernetes クラスタ、別のクラウド プロバイダなど、GCP 以外の環境に ESP をデプロイする場合は、秘密鍵が含まれているサービス アカウントの JSON ファイルを ESP に指定する必要があります。ESP はサービス アカウントを使用してアクセス トークンを生成し、API の管理に必要なサービスを呼び出します。

GCP Console または gcloud コマンドライン ツールを使用すると、サービス アカウントと秘密鍵ファイルを作成して、サービス アカウントに以下の役割を割り当てることができます。

Console

  1. GCP Console で [サービス アカウント] ページを開きます。

    [サービス アカウント] ページに移動

  2. [プロジェクトの選択] をクリックします。
  3. API が作成されたプロジェクトを選択し、[開く] をクリックします。
  4. [+ サービス アカウントを作成] をクリックします。
  5. [サービス アカウント名] 項目に、サービス アカウントの名前を入力します。
  6. [作成] をクリックします。
  7. [役割を選択] をクリックし、[サービス管理] > [サービス コントローラ] の順に選択します。
  8. [+ 別の役割を追加] をクリックします。
  9. [役割を選択] をクリックし、[Cloud Trace] > [Cloud Trace エージェント] の順に選択します。
  10. [続行] をクリックします。
  11. [+ キーを作成] をクリックします。
  12. 右側のパネルの [キーのタイプ] で、デフォルト タイプである [JSON] を使用します。
  13. [作成] をクリックします。
  14. ダイアログで [閉じる] をクリックします。
  15. [完了] をクリックします。

これで、サービス アカウントが作成され、その秘密鍵が JSON ファイルにダウンロードされます。

gcloud

  1. 次のコマンドを入力して、GCP プロジェクトのプロジェクト ID を表示します。

    gcloud projects list
    
  2. 次のコマンドの PROJECT_ID の部分を API が含まれているプロジェクトに置き換えて、デフォルトのプロジェクトに設定します。

    gcloud config set project PROJECT_ID
    
  3. Cloud SDK(gcloud)が GCP にある対象のデータとサービスにアクセスできるよう許可されていることを確認します。

    gcloud auth login
    

    アカウントが複数ある場合は、API が含まれている GCP プロジェクトで使用されているアカウントを選択してください。gcloud auth list を実行すると、選択したアカウントがプロジェクトの有効なアカウントとして表示されます。

  4. サービス アカウントを作成するには次のコマンドを実行します。SERVICE_ACCOUNT_NAMEMy Service Account は使用する名前と表示名に置き換えます。

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
      --display-name "My Service Account"
    

    このコマンドは、サービス アカウントのメールアドレスを次の形式で割り当てます。

    SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    

    このメールアドレスは、後で実行するコマンドで必要になります。

  5. サービス アカウントのキーファイルを作成します。

    gcloud iam service-accounts keys create ~/service-account-creds.json \
      --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    
  6. サービス コントローラの役割を追加します。

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
        --role roles/servicemanagement.serviceController
    
  7. Cloud Trace エージェントの役割を追加して、Stackdriver Trace を有効にします。

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
        --role roles/cloudtrace.agent
    

コマンドの詳細については、gcloud iam service-accounts をご覧ください。

コンテナでの ESP の実行

このセクションでは、ESP コンテナをデプロイする方法を説明します。使用する手順は、ESP コンテナをデプロイする場所によって異なります。

ローカルまたは別のプラットフォームの Docker コンテナで ESP を実行する

  1. サービス アカウントの秘密鍵が格納されている JSON ファイルの名前を service-account-creds.json に変更して、(ファイルを別のディレクトリにダウンロードした場合は)$HOME/Downloads/ にコピーします。これにより、フルパス名が下記の docker run コマンドの --service_account_key の値と一致します。

  2. 以下の docker run コマンドに含まれる YOUR_SERVICE_NAMEご使用のサービス名で置き換えます。

Linux

sudo docker run \
    --detach \
    --name="esp" \
    --net="host" \
    --volume=$HOME/Downloads:/esp \
    --publish=8082 \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=YOUR_SERVICE_NAME \
    --rollout_strategy=managed \
    --http_port=8082 \
    --backend=localhost:8080 \
    --service_account_key=/esp/service-account-creds.json
  

macOS

Docker の --net="host" オプションは macOS では機能しません。代わりに、ホストからコンテナへの明示的なポート マッピングを行う必要があり、--net="host"--publish 8082:8082 に置き換えます。また、localhost を macOS 専用の特別な DNS 名である docker.for.mac.localhost に置き換える必要があります。詳しくは、Docker ドキュメントのユースケースと回避策をご覧ください。

sudo docker run \
    --detach \
    --name="esp" \
    --publish=8082:8082 \
    --volume=$HOME/Downloads:/esp \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=YOUR_SERVICE_NAME \
    --rollout_strategy=managed \
    --http_port=8082 \
    --backend=docker.for.mac.localhost:8080 \
    --service_account_key=/esp/service-account-creds.json
  

別のプラットフォーム

sudo docker run \
    --detach \
    --name="esp" \
    --net="host" \
    --volume=$HOME/Downloads:/esp \
    --publish=8082 \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=YOUR_SERVICE_NAME \
    --rollout_strategy=managed \
    --http_port=8082 \
    --backend=IP_Address:PORT \
    --service_account_key=/esp/service-account-creds.json
  

次の表に、上記のコマンドで使用している Docker オプションを示します。この例で使用している ESP オプションについては、ESP 起動オプションをご覧ください。

オプション 説明
--detach この Docker オプションは、コンテナを接続解除モードで起動します。そのため、コンテナはバックグラウンドで実行されます。
--name="esp" この Docker オプションは、扱いやすい名前をコンテナに対して指定します。たとえば、コンテナからのログを表示する場合は、docker logs esp のように実行できます。
--net="host" この Docker オプションは、Docker コンテナがホストマシンと同じネットワーク構成を使用することを指定します。これにより、Docker コンテナがホストマシン上の localhost を呼び出せるようにします。このオプションは、macOS 上で ESP をローカル実行する場合には機能しません。
--publish=8082:8082 macOS で ESP をローカルで実行する場合は、この Docker オプションを --net="host" の代わりに使用して、ホストからコンテナへの明示的なポート マッピングを行います。
--volume=
$HOME/Downloads:/esp
この Docker オプションは、ローカル ディレクトリ $HOME/Downloads をコンテナ内の /esp ディレクトリにマッピングします。このマッピングは --service_account_key ESP オプションで使用されます。

Kubernetes クラスタのコンテナで ESP を実行する

このセクションでは、GCP 上にない Kubernetes クラスタに ESP をデプロイする方法を説明します。

API を Endpoints で管理させるには、API コンテナと同じ Kubernetes ポッドに ESP コンテナをデプロイします。API と ESP を実行するポッドのセットは、Kubernetes サービス内でラベルセレクタ(たとえば app: my-api)を使用してグループ化されます。この Kubernetes サービスで指定されたアクセス ポリシーに基づいて、クライアント リクエストがプロキシポートに負荷分散されます。

  1. サービス アカウントの秘密鍵が格納されている JSON ファイルの名前を service-account-creds.json に変更して、(ファイルを別のディレクトリにダウンロードした場合は)$HOME/Downloads/ にコピーします。このようにすることで、フルパス名が次のステップで使用するコマンドと一致します。

  2. 次のコマンドを実行して Kubernetes secret を作成し、その secret を Kubernetes ボリュームとしてマウントします。

    kubectl create secret generic service-account-creds \
    --from-file=$HOME/Downloads/service-account-creds.json
    

    成功すると、「secret "service-account-creds" created」というメッセージが表示されます。

  3. Kubernetes 構成ファイル内に次のコードを追加します。YOUR_APP_NAME は API の名前で置き換え、YOUR_SERVICE_NAMEサービスの名前で置き換えてください。

    spec:
    replicas: 1
    template:
      metadata:
        labels:
          app: "YOUR_APP_NAME"
      spec:
        volumes:
          - name: service-account-creds
            secret:
              secretName: service-account-creds
              containers:
          - name: esp
            image: gcr.io/endpoints-release/endpoints-runtime:1
            args: [
              "--http_port=8082",
              "--backend=127.0.0.1:8081",
              "--service=YOUR_SERVICE_NAME",
              "--rollout_strategy=managed",
              "--service_account_key=/etc/nginx/creds/service-account-creds.json"
            ]
            ports:
              - containerPort: 8080
            volumeMounts:
              - mountPath: /etc/nginx/creds
                name: service-account-creds
                readOnly: true
    

    この例で使用している ESP オプションについては、ESP 起動オプションをご覧ください。

  4. ESP を Kubernetes にデプロイします。YOUR_CONFIGURATION_FILE は、Kubernetes 構成ファイルの名前で置き換えます。

    kubectl apply -f YOUR_CONFIGURATION_FILE
    

リクエストを送信する

サービス アカウント ファイルが正しいことやポートが正しくマッピングされていることを確認するには、API にリクエストを送信し、リクエストが ESP 経由で送信されていることを確認します。次のコマンドを実行して、ESP ログを表示できます。

sudo docker logs esp

次の例では、サンプル API にリクエストを送信します。サンプル API を使用していない場合は、同様のテストを実行することをおすすめします。

ポート 8082 でリクエストを受信するように ESP コンテナが構成されています。http://localhost:8080 でサーバーに直接リクエストを送信すると、リクエストは ESP をバイパスします。たとえば、次のようになります。

リクエスト:

    curl --request POST \
      --header "content-type:application/json" \
      --data '{"message":"hello world"}' \
      http://localhost:8080/echo

レスポンス:

    {
      "message": "hello world"
    }

ESP を通過するリクエストを http://localhost:8082 に送信し、API キーを送信しない場合、このリクエストは ESP によって拒否されます。たとえば、次のようになります。

リクエスト:

    curl --request POST \
      --header "content-type:application/json" \
      --data '{"message":"hello world"}' \
      http://localhost:8082/echo

レスポンス:

    {
     "code": 16,
     "message": "Method doesn't allow unregistered callers (callers without
      established identity). Please use API Key or other form of API consumer
      identity to call this API.",
     "details": [
      {
       "@type": "type.googleapis.com/google.rpc.DebugInfo",
       "stackEntries": [],
       "detail": "service_control"
      }
     ]
    }

API キーを使用して API をテストするには:

  1. API の認証情報ページで API キーを作成します。

    [認証情報] ページに移動

  2. [認証情報を作成] をクリックし、[API キー] を選択します。

  3. キーをコピーし、以下の環境変数ステートメントに貼り付けます。

    export KEY=AIza...
    
  4. キーを使用してリクエストを送信します。

    curl --request POST \
      --header "content-type:application/json" \
      --data '{"message":"hello world"}' \
      http://localhost:8082/echo?key=$KEY
    

    成功すると、次のレスポンスが表示されます。

    {
      "message": "hello world"
    }
    

クリーンアップ

docker ツールを使用して、esp Docker コンテナをシャットダウンして削除します。

sudo docker stop esp
sudo docker rm esp

デプロイしたサービス構成をクリーンアップする方法については、API と API インスタンスを削除するをご覧ください。

次のステップ

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

OpenAPI を使用した Cloud Endpoints
ご不明な点がありましたら、Google のサポートページをご覧ください。