Apigee ハイブリッドでの Apigee Adapter for Envoy の使用

このページの内容は Apigee と Apigee ハイブリッドに該当します。

Apigee Edge のドキュメントはこちらをご覧ください。

この例では、Apigee ハイブリッドデプロイで Apigee Adapter for Envoy を使用する方法を示します。

前提条件

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

概要

この例では、Apigee ハイブリッドで Apigee Adapter for Envoy を使用する方法について説明します。この例では、Apigee ハイブリッドがデプロイされているクラスタと同じ Kubernetes クラスタに、シンプルな HTTP サービスをデプロイします。次に、Apigee でこのサービスに対する API 呼び出しを管理するように、Apigee Adapter for Envoy を構成します。

次の図は、Apigee ハイブリッドインテグレーションの基本アーキテクチャを示しています。

管理プレーン、ランタイムプレーン、GCP サービスなどの Apigee ハイブリッド環境に統合された Envoy Adapter の概要図

Istio サービスメッシュ内の Istio サイドカーとして、対象の HTTP サービスで Envoy プロキシがデプロイされます。サイドカーは対象のサービスとの間の API トラフィックを処理し、Remote Service と通信します。Remote Service は、ハイブリッド管理プレーンとも通信して、API プロダクトとプロキシ情報を取得します。

gcloud の構成を確認する

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

Apigee ハイブリッドのプロビジョニング

このステップでは、Remote Service CLI を使用して remote-service API プロキシとともにハイブリッドをプロビジョニングします。また、プロビジョニングコマンドは Apigee に証明書を設定し、リモートサービスが Apigee に安全に接続するために使用する認証情報を生成します。

$CLI_HOME ディレクトリに移動します。
```
cd $CLI_HOME
```
Apigee ハイブリッド組織に関連付けられた GCP プロジェクトのオーナーでない場合は、GCP ユーザーアカウントに Apigee 組織管理者ロールを付与するか、API 作成者ロールとデプロイ担当者ロールの両方を付与してください。
リソースへのアクセス権の付与、変更、取り消しをご覧ください。
次のコマンドを実行して、アクセストークンを取得します。
```
TOKEN=$(gcloud auth print-access-token);echo $TOKEN
```

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

export ORG=organization_name
export ENV=environment_name
export RUNTIME=host_alias_url
export NAMESPACE=hybrid_runtime_namespace
export AX_SERVICE_ACCOUNT=analytics_service_account

ここで

変数	説明
`organization_name`	Apigee ハイブリッドインストールのための Apigee 組織の名前。
`environment_name`	Apigee ハイブリッド組織内の環境の名前。
`host_alias_url`	ハイブリッド構成で定義された仮想ホストの `hostAlias` が含まれる URL。先頭は `https://` でなければなりません。例: `https://apitest.apigee-hybrid-docs.net`
`hybrid_runtime_namepace`	ハイブリッドランタイムコンポーネントがデプロイされる名前空間。注: ハイブリッドデプロイのデフォルトの名前空間は `apigee` です。
`analytics_service_account`	`Apigee Analytics Agent` ロールを割り当てられた Google Cloud サービスアカウントキーの JSON ファイルへのパス。このパラメータの詳細については、Provision コマンドをご覧ください。

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

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

# Configuration for apigee-remote-service-envoy (platform: GCP)
# 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.example.com/remote-service
      org_name: hybrid-gke
      env_name: test
    analytics:
      collection_interval: 10s
    auth:
      jwt_provider_key: https://apitest.example.com/remote-service/token
---
apiVersion: v1
kind: Secret
metadata:
  name: hybrid-gke-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: hybrid-gke-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

サービス構成（プロビジョニングコマンドによるファイル出力）をクラスタに適用します。
```
kubectl apply -f $CLI_HOME/config.yaml
```

プロキシと証明書を検証します。次のように有効な JSON が返されます。

curl -i $RUNTIME/remote-service/certs

出力は次のようになります。

{
    "keys": [
        {
            "alg": "RS256",
            "e": "AQAB",
            "kid": "2020-05-11T11:32:26-06:00",
            "kty": "RSA",
            "n": "0v-nbTQyAmtVZ-wZRP0ZPIbrVaX91YO9JZ9xCQPb4mOdOSS7yKfTDJGg0KM130sGVYBvR76alN8
            fhrrSDEG5VXG8YYMqPXarwRC7MRJWocCQ_ECYrjDD0_Q018M2HyXZYSd8fhAogi9mVUYsEmCKqJH53Dh1
            jqsHOQzBLKsX0iDO9hEZNFtjbX0UCbSxsUlmBCub7Uj2S-PahA6DEQOMhQjZM7bBMtkTMpFmaJ_RZTmow
            BHP57qMna17R8wHD4kUsO2u_-3HHs5PSj1NrEYoVU2dwLQw0GlkB__ZWeFgXTqot81vb-PmoM9YxwoZrm
            TcHdljugWy_s7xROPzTod0uw"
        }
    ]
}

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

apigee-remote-service-cli samples create コマンドを使用してサンプル構成ファイルを生成します。

この例では、次の生成ファイルが必要です。

httpbin.yaml - HTTP サービスのデプロイ構成。
apigee-envoy-adapter.yaml - Remote Service for Envoy のデプロイ構成。
envoyfilter-sidecar.yaml - EnvoyFilter をインストールする構成。デフォルトの名前空間にインストールする構成。

サンプルを生成するには:

$CLI_HOME ディレクトリに移動します。
次のコマンドを実行してファイルを生成します。
```
./apigee-remote-service-cli samples create -c ./config.yaml
```
注: デフォルトでは、このコマンドは Istio 1.6 テンプレートを使用してファイルを生成します。Istio 1.7 の場合は、フラグ --template istio-1.7 を指定します。
次のファイルは ./samples ディレクトリを出力します。
```
ls samples
apigee-envoy-adapter.yaml envoyfilter-sidecar.yaml httpbin.yaml request-authentication.yaml
```

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

クラスタにテストサービスをデプロイする

このステップでは、Apigee ハイブリッドがデプロイされているクラスタと同じクラスタに、シンプルな HTTP リクエスト / レスポンステストサービスをデプロイします。

クラスタの default 名前空間で Istio インジェクションを有効にします。後のステップで、同じクラスタに Envoy サイドカーをデプロイします。Istio インジェクションを有効にすると、サイドカーデプロイメントが可能になります。この例では、default Namespace を使用し、後続のすべての手順がこのケースに該当すると想定しています。
オープンソースの Istio を使用している場合:
```
kubectl label namespace default istio-injection=enabled --overwrite
```
ASM を使用している場合:
```
kubectl label namespace default istio-injection- istio.io/rev=REVISION --overwrite
```
シンプルな httpbin サービスをデフォルトの名前空間のクラスタに適用します。
```
kubectl apply -f $CLI_HOME/samples/httpbin.yaml
```
ここで、サービスをテストします。クラスタで動作している curl サービスを起動し、ターミナルを開きます。
```
kubectl run -it curl --image=curlimages/curl --restart=Never -- sh
```

クラスタ内からサービスを呼び出してテストします。

curl -i httpbin.default.svc.cluster.local/headers

成功すると、ステータス 200 が表示され、サービスはヘッダーのリストを返します。次に例を示します。

HTTP/1.1 200 OK
server: envoy
date: Tue, 12 May 2020 17:09:01 GMT
content-type: application/json
content-length: 328
access-control-allow-origin: *
access-control-allow-credentials: true
x-envoy-upstream-service-time: 7

{
  "headers": {
    "Accept": "*/*",
    "Content-Length": "0",
    "Host": "httpbin.default.svc.cluster.local",
    "User-Agent": "curl/7.70.0-DEV",
    "X-B3-Parentspanid": "69f88bc3e322e157",
    "X-B3-Sampled": "0",
    "X-B3-Spanid": "8dd725f30e393d8b",
    "X-B3-Traceid": "38093cd817ad30a569f88bc3e322e157"
  }
}

ヒント: curl クライアントを実行したままにし、シェルを開いたままにします。この値は、後のステップで使用します。

Remote Service for Envoy を実行する

このステップでは、Apigee ハイブリッドがインストールされているサービスメッシュ内で Remote Service for Envoy のクライアントを起動します。このサービスは、ターゲットサービスにインストールされている Istio サイドカーにエンドポイントを提供します。また、httpbin サービスを使用してサイドカーをインストールします。

Apigee Remote Service をサービスメッシュに適用します。
```
kubectl apply -f $CLI_HOME/samples/apigee-envoy-adapter.yaml
```
EnvoyFilter をデフォルトの名前空間の Istio サイドカーに適用します。EnvoyFilter は、httpbin サイドカーが Apigee Remote Service と通信できるようにします。
```
kubectl apply -f $CLI_HOME/samples/envoyfilter-sidecar.yaml
```

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

クラスタへのテストサービスのデプロイのステップで開いた curl シェルに戻り、httpbin サービスを呼び出します。
```
curl -i httpbin.default.svc.cluster.local/headers
```
現在、サービスは Apigee によって管理されており、API キーが指定されていないため、次のエラーが返されます。
```
curl -i httpbin.default.svc.cluster.local/headers
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 キーを取得する方法に説明されているとおりに、API プロダクトを構成し、API キーを取得します。

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

export APIKEY=YOUR_API_KEY
curl -i httpbin.default.svc.cluster.local/headers -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": "kyOTalNNLMPfOSy6rnVeclmVSL6pA2zS",
    "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": "kyOTalNNLMPfOSy6rnVeclmVSL6pA2zS",
    "X-Apigee-Developeremail": "jdoe@example.com",
    "X-Apigee-Environment": "envoy",
    "X-Apigee-Organization": "acme-org",
    "X-Apigee-Scope": "",
    "X-B3-Parentspanid": "1476f9a2329bbdfa",
    "X-B3-Sampled": "0",
    "X-B3-Spanid": "1ad5c19bfb4bc96f",
    "X-B3-Traceid": "6f329a34e8ca07811476f9a2329bbdfa"
  }
}

次のステップ

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

API キーを取得する方法の説明に沿って API プロダクトを構成した場合、割り当て上限は 1 分あたり 5 件のリクエストに設定されています。httpbin サービスを複数回呼び出して割り当てをトリガーするようにします。割り当てが枯渇すると、HTTP ステータス 403 エラーが返されます。
Edge UI で Apigee Analytics にアクセスします。[分析] > [API 指標] > [API プロキシパフォーマンス] の順に移動します。
API 呼び出しを認証するために、JWT トークンを生成して使用します。
CLI を使用して、トークンの管理、作成し、バインディングを制御します。CLI の詳細については、リファレンスをご覧ください。