Apigee とハイブリッドでのネイティブ Envoy の使用例

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge ドキュメントを表示する

この例では、Envoy を Kubernetes クラスタ内ではなく、ローカルにインストールして実行し、Apigee Adapter for Envoy を使用する方法を示します。このドキュメントの例は、Apigee と Apigee ハイブリッドの両方のインストールに使用できます。

API プロキシ呼び出しは、ネイティブアプリケーションとして実行される Envoy を経由します。Apigee は、API プロダクトやデベロッパーアプリの作成などの API 管理サービスを提供します。Envoy は、アダプタのリモートサービスを介して Apigee 管理プレーンと通信します。また、アダプタは分析データを Apigee に push します。このデータは Apigee Analytics で確認できます。

前提条件

始める前に、次のことを行います。
スタートガイドの説明にあるように、Apigee Adapter for Envoy Remote Service とコマンドラインインターフェース（CLI）をダウンロードしてインストールします。
Google Cloud SDK がインストールされていることを確認します。SDK には `gcloud` コマンドラインツールが含まれています。
`kubectl` がインストールされていることを確認します。

gcloud の構成を確認する

gcloud 構成が、Apigee 組織に関連付けられた Google Cloud プロジェクトに設定されていることを確認します。
現在の設定を一覧表示するには:gcloud config もご覧ください。
```
gcloud config list
```
必要に応じて、次のコマンドを使用して正しい Google Cloud プロジェクト ID を設定します。
```
gcloud config set project project-id
```
Google Cloud プロジェクトの Google Cloud SDK（gcloud）で認証する必要があります。gcloud auth login もご覧ください。
```
gcloud auth login
```

Apigee をプロビジョニングする

このステップでは、Remote Service CLI を使用して Apigee に Apigee Adapter for Envoy アセットをプロビジョニングします。プロビジョニングコマンドでは、Apigee アダプタの操作に使用する API プロキシをデプロイし、Apigee に証明書を設定して、リモートサービスでシステムから Apigee に安全に接続するために使用する認証情報を生成します。

$CLI_HOME ディレクトリに移動します。
```
cd $CLI_HOME
```
（省略可）デフォルトでは、アダプタは分析データを Apigee に送信するための権限を確保するために Google Cloud プロジェクトのデフォルトのサービスアカウント認証情報を検索します。デフォルトのサービスアカウント認証情報を使用しない場合は、サービスアカウントを作成して、プロビジョニングコマンドでそのキーを参照します。サービスアカウントには apigee.analyticsAgent ロールが必要です。手順については、サービスアカウントの作成と管理をご覧ください。

次の環境変数を作成します。これらの変数は、プロビジョニングスクリプトのパラメータとして使われます。

export ORG=organization_name
export ENV=environment_name
export RUNTIME=host_alias_url
export NAMESPACE=hybrid_runtime_namespace  ## Apigee hybrid only
export AX_SERVICE_ACCOUNT=analytics_service_account  ## Optional

ここで

変数	説明
`organization_name`	Apigee 組織の名前。
`environment_name`	組織内の環境の名前。
`host_alias_url`	Apigee ハイブリッドの場合は、ハイブリッド構成で定義された仮想ホストの `hostAlias` が含まれる URL。 Apigee の場合は、環境を含む環境グループのホスト名。環境グループは、Apigee UI の [Admin] > [Environments] > [Groups] で確認できます。注: URL は `https://` で始める必要があります。例: `https://apitest.mydomain.net`
`hybrid_runtime_namepace`	（Apigee ハイブリッドのみ）ハイブリッドランタイムコンポーネントがデプロイされる名前空間。注: ハイブリッドデプロイのデフォルトの名前空間は `apigee` です。
`analytics_service_account`	（省略可）`Apigee Analytics Agent` ロールを割り当てられた Google Cloud サービスアカウントキーの JSON ファイルへのパス。このパラメータの詳細については、Provision コマンドをご覧ください。

Apigee 組織に関連付けられた Google Cloud プロジェクトのオーナーでない場合は、Google Cloud ユーザーアカウントに Apigee 組織管理者のロール、または API 作成者とデプロイ担当者のロールの両方を付与してください。リソースに対するアクセス権の付与、変更、取り消しをご覧ください。

アクセストークンを取得します。

TOKEN=$(gcloud auth print-access-token);echo $TOKEN

リモートサービスプロキシを Apigee にプロビジョニングします。コマンド出力は、後のステップで使用する構成ファイルにリダイレクトされます。
アップグレードする場合: 既存の Apigee Adapter for Envoy をアップグレードする場合は、--force-proxy-install フラグを provision コマンドに追加する必要があります。
このフラグによって、Apigee プロキシは最新のプロキシに置き換えられます。
アップグレードしない場合は、このコマンドを使用して Apigee をプロビジョニングします。Apigee ハイブリッドにプロビジョニングする場合は、必ず --namespace $NAMESPACE パラメータを追加してください。
```
./apigee-remote-service-cli provision --organization $ORG --environment $ENV \
     --runtime $RUNTIME --analytics-sa $AX_SERVICE_ACCOUNT --token $TOKEN > config.yaml
```
アップグレードする場合は、--force-proxy-install フラグを指定したこのコマンドを使用して Apigee をプロビジョニングします。Apigee ハイブリッドにプロビジョニングする場合は、必ず --namespace $NAMESPACE パラメータを追加してください。
```
./apigee-remote-service-cli provision --force-proxy-install --organization $ORG --environment $ENV \
     --runtime $RUNTIME --analytics-sa $AX_SERVICE_ACCOUNT --token $TOKEN > config.yaml
```

config.yaml ファイルの内容を確認します。次のようになります。

# Configuration for apigee-remote-service-envoy (platform: Google Cloud)
# generated by apigee-remote-service-cli provision on 2020-11-20 02:49:28
apiVersion: v1
kind: ConfigMap
metadata:
  name: apigee-remote-service-envoy
  namespace: apigee
data:
  config.yaml: |
    tenant:
      remote_service_api: https://apitest.mydomain.com/remote-service
      org_name: my-org
      env_name: test
    analytics:
      collection_interval: 10s
    auth:
      jwt_provider_key: https://apitest.mydomain.com/remote-service/token
---
apiVersion: v1
kind: Secret
metadata:
  name: my-org-new-test-policy-secret
  namespace: apigee
type: Opaque
data:
  remote-service.crt: eyJrZXlzIjpbeyJrdHkiOiJSU0EiLCJhbGci...
  remote-service.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURS...
  remote-service.properties: a2lkPTIwMjAtMDctMDZ...
---
apiVersion: v1
kind: Secret
metadata:
  name: my-org-new-test-analytics-secret
  namespace: apigee
type: Opaque
data:
  client_secret.json: ewogICJ0eXBlIjogInNlcnZ...
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: apigee-remote-service-envoy
  namespace: apigee

`apigee-remote-service-envoy` を実行する

リモートサービスは、ネイティブバイナリとして実行することも、Docker で実行することもできます。

サービスをネイティブで実行する

プロビジョニングコマンドから出力された構成ファイルを使用して、サービスバイナリを実行します。

$REMOTE_SERVICE_HOME/apigee-remote-service-envoy -c config_file_path/config.yaml

Docker でサービスを実行する

Docker イメージはリリースタグ付きで公開されます。このインストールでは、最新バージョンを使用してください。次の 3 つのイメージのバリエーションから選択できます。

バリエーション	イメージ
Google distroless	`google/apigee-envoy-adapter:v2.0.3`
Ubuntu	`google/apigee-envoy-adapter:v2.0.3-ubuntu`
Boring Crypto を含む Ubuntu	`google/apigee-envoy-adapter:v2.0.3-boring`

たとえば、ボリュームマウントを介してローカルの config.yaml を /config.yaml として利用できる状態でスクラッチイメージを実行するには、次のコマンドを使用します。

docker run -v ./config.yaml:/config.yaml google/apigee-envoy-adapter:v2.0.3

注: Docker イメージは root 以外のユーザーとして実行されます。config.yaml ファイルの読み取り権限が付与されていることを確認します。

Envoy 構成ファイルのサンプルを作成する

CLI を使用してサンプルの Envoy 構成ファイルを生成します。

$ENVOY_HOME ディレクトリ内にいることを確認します。
使用可能な構成テンプレートを一覧表示します。
```
$CLI_HOME/apigee-remote-service-cli samples templates
```
サンプルコマンドを実行します。TEMPLATE は、サポートされている Envoy テンプレートのいずれかに置き換えます。
```
$CLI_HOME/apigee-remote-service-cli samples create --template TEMPLATE -c ./config.yaml
```
このコマンドにより、./samples/envoy-config.yaml ファイルが作成されます。

詳しくは、サンプルコマンドをご覧ください。

Envoy プロキシをインストールして実行する

Envoy プロキシをインストールして実行する手順は次のとおりです。

Envoy バイナリをダウンロードするか、ビルドします。
httpbin.org サービス用に以前に生成したサンプル構成ファイルを使用して Envoy を実行します。
```
envoy -c ./samples/envoy-config.yaml
```

インストールをテストする

API キーを取得する方法に説明されているとおりに、API プロダクトを構成し、API キーを取得します。
API キーなしで httpbin サービスを呼び出します。
```
curl -i http://localhost:8080/headers -H "HOST:httpbin.org"
```
注:HOST ヘッダーを追加し、API プロダクトで設定したリモートサービスホストに設定する必要があります。

現在、サービスは Apigee によって管理されており、API キーが指定されていないため、次のエラーが返されます。
```
curl -i http://localhost:8080/headers -H "HOST:httpbin.org"
HTTP/1.1 403 Forbidden
date: Tue, 12 May 2020 17:51:36 GMT
server: envoy
content-length: 0
x-envoy-upstream-service-time: 11
```

キーを使用して API 呼び出しを行います。

export APIKEY=YOUR_API_KEY
curl -i http://localhost:8080/headers -H "HOST:httpbin.org" -H "x-api-key: $APIKEY"

呼び出しはステータス 200 で成功となり、レスポンスでヘッダーのリストを返します。次に例を示します。

curl -i httpbin.default.svc.cluster.local/headers -H "x-api-key: kyOTalNNLMPfOSy6rnVeclmVSL6pA2zS"
HTTP/1.1 200 OK
server: envoy
date: Tue, 12 May 2020 17:55:34 GMT
content-type: application/json
content-length: 828
access-control-allow-origin: *
access-control-allow-credentials: true
x-envoy-upstream-service-time: 301

{
  "headers": {
    "Accept": "*/*",
    "Content-Length": "0",
    "Host": "httpbin.default.svc.cluster.local",
    "User-Agent": "curl/7.70.0-DEV",
    "X-Api-Key": "kyOTalNNLMPfOSy6rneclmVSL6pA2zS",
    "X-Apigee-Accesstoken": "",
    "X-Apigee-Api": "httpbin.default.svc.cluster.local",
    "X-Apigee-Apiproducts": "httpbin",
    "X-Apigee-Application": "httpbin",
    "X-Apigee-Authorized": "true",
    "X-Apigee-Clientid": "kyOTalNNLMPfOSy6rVeclmVSL6pA2zS",
    "X-Apigee-Developeremail": "user@mydomain.com",
    "X-Apigee-Environment": "test",
    "X-Apigee-Organization": "my-org",
    "X-Apigee-Scope": "",
    "X-B3-Parentspanid": "1476f9a2329bbdfa",
    "X-B3-Sampled": "0",
    "X-B3-Spanid": "1ad5c19bfb4bc96f",
    "X-B3-Traceid": "6f329a34e8ca07811476f9a2329bbdfa"
  }
}

Apigee Envoy アダプタをアンインストールする

Apigee Envoy アダプタのインストールを削除するには:

Envoy アダプタを実行するよう選択した場所（ネイティブまたは Docker）で、それを削除します。
Apigee 環境から remote-service プロキシと remote-token プロキシを削除します。API プロキシの削除をご覧ください。
Envoy アダプタのユースケースで使用されている未使用の API プロダクトまたはオペレーションを削除します。API プロダクトの削除をご覧ください。

次のステップ

現在、httpbin サービスへの API トラフィックは Apigee で管理されています。次のような機能を探して試すことができます。

Edge UI で Apigee Analytics にアクセスします。[Analyze] > [API Metrics] > [API Proxy Performance] に移動します。
リファレンスの CLI オプションを確認します。

Apigee とハイブリッドでのネイティブ Envoy の使用例

前提条件

gcloud の構成を確認する

Apigee をプロビジョニングする

apigee-remote-service-envoy を実行する

サービスをネイティブで実行する

Docker でサービスを実行する

Envoy 構成ファイルのサンプルを作成する

Envoy プロキシをインストールして実行する

インストールをテストする

Apigee Envoy アダプタをアンインストールする

次のステップ

`apigee-remote-service-envoy` を実行する