Apigee Connect の使用（ベータ版）

このセクションでは、Hybrid 管理プレーンとランタイムプレーンの MART サービスとの間の通信に Apigee Connect（ベータ版）を使用する方法について説明します。

はじめに

Apigee Connect を使用すると、インターネット上で MART エンドポイントを公開しなくても、Apigee Hybrid 管理プレーンをランタイムプレーンの MART サービスに安全に接続できます。Apigee Connect を使用する場合は、ホストエイリアスと承認済み DNS 証明書を使用して MART Ingress ゲートウェイを構成する必要はありません。

Apigee Connect を示す、Hybrid ランタイムプレーンで実行される主なサービス

前提条件

Apigee Connect を設定する前に、Apigee Hybrid バージョン 1.2.0 以降をインストールして構成する必要があります。

Apigee Hybrid を初めてインストールする場合は、Apigee Hybrid のドキュメントのインストール手順に従ってください。
現在 Apigee Hybrid バージョン 1.1.x を使用している場合は、インストールをバージョン 1.2.0 にアップグレードしてから続行してください。アップグレード手順については、Apigee Hybrid のアップグレードをご覧ください。

Apigee Connect を Hybrid ランタイムに追加する

このセクションでは、Apigee Hybrid 1.2.0 以降をインストールまたはアップグレードしていることを前提としています。

Apigee Connect が構成され有効になっている場合、MART Ingress は無視されます。管理プレーンは、必ず Apigee Connect を使用して MART に接続します。Hybrid ランタイムプレーン間のすべての MART トラフィックは、安全な Apigee Connect 接続を経由します。

Apigee Connect と Apigee Hybrid を有効にして使用する手順は次のとおりです。

Google Cloud API ライブラリで Apigee Connect API を有効にします。API は Google Cloud（GCP）Console または gcloud で有効にできます。Google Cloud Console で API を有効にする手順については、ステップ 3: API を有効にするをご覧ください。gcloud を使用して API を有効にするには:
```
$ gcloud config set project YOUR_GCP_PROJECT_ID
$ gcloud services enable apigeeconnect.googleapis.com
```
ここで、YOUR_GCP_PROJECT_ID は、Apigee が有効になっていて、Apigee 組織がプロビジョニングされている GCP プロジェクトと同じです。

Apigee Hybrid インストール手順のサービスアカウントの作成の手順で作成した MART サービスアカウントに Apigee Connect エージェントのロールを追加します。

$ gcloud projects add-iam-policy-binding YOUR_GCP_PROJECT_ID
--member serviceAccount:YOUR_MART_SERVICE_ACCOUNT_EMAIL --role roles/apigeeconnect.Agent

ここで、YOUR_GCP_PROJECT_ID は、Apigee が有効になっていて、Apigee 組織がプロビジョニングされている GCP プロジェクトと同じです。YOUR_MART_SERVICE_ACCOUNT_EMAIL は、MART サービスアカウント名です。名前はメールアドレスの形式です。例: apigee-mart@my-project.iam.gserviceaccount.com。

Apigee Connect エージェントのロールは事前定義されていて、次の権限が割り当てられています。

権限	説明
`apigeeconnect.endpoints.connect`	これは、Apigee Connect エージェントを設定するための権限です。

GCP Console または API を使用してアクセス権を付与する方法については、以下をご覧ください。

サービスアカウントの作成で説明されているように、MART サービスアカウントのキーファイルが hybrid_files/service_accounts ディレクトリにあることを確認します。
オーバーライドファイルを開き、次のスタンザを追加します。この構成では、ダウンロードしたサービスアカウントキーへのパスを指定する必要があります。キーは、Apigee Connect エージェントのロールを持つサービスアカウントのものである必要があります。
```
# Apigee Connect Agent
connectAgent:
  enabled: true
  serviceAccountPath: ./service-accounts/connect_agent_sa_key.json
```
見出し k8sCluster の下にスタンザを追加します。次に例を示します。
```
k8sCluster:
  name: your_cluster_name
  region: your_cluster_region

# Apigee Connect Agent
connectAgent:
  enabled: true
  serviceAccountPath: ./service-accounts/connect_agent_sa_key.json
```
注: デフォルトでは、connectAgent の replicaCountMin は 1 です。本番環境デプロイなど、その他のユースケースでは、replicaCountMin を 3 に変更します。例:
```
# Apigee Connect Agent
connectAgent:
  enabled: true
  replicaCountMin: 3
  serviceAccountPath: ./service-accounts/connect_agent_sa_key.json
```
Synchronizer アクセスを有効にするの説明に従って、Apigee Hybrid をインストールしたときにダウンロードした Apigee 組織管理者のロールを持つサービスアカウントキーを見つけます。このキーは、以下で説明するように、API 呼び出しを行うために必要なトークンを生成するために必要です。
次の 2 つのコマンドを実行して、トークンを取得します。
```
$ export GOOGLE_APPLICATION_CREDENTIALS=org-admin-service-account-file
$ export TOKEN=$(gcloud auth application-default print-access-token)
```
ここで、org-admin-service-account-file は、Apigee 組織管理者のロールでダウンロードしたサービスアカウントキーへのシステム上のパスです。
組織で Apigee Connect を有効にするには、次の Apigee API を呼び出します。
```
curl -v -X PUT \
   https://apigee.googleapis.com/v1/organizations/your_org_name \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
  "name" : "your_org_name",
  "properties" : {
    "property" : [ {
      "name" : "features.hybrid.enabled",
      "value" : "true"
    }, {
      "name" : "features.mart.connect.enabled",
      "value" : "true"
    } ]
  }
}'
```
注: リクエスト本文に元の MART エンドポイントプロパティを残すことをおすすめします。そうしないと、元の MART 構成プロパティが失われます。Apigee Connect を有効にすると、MART サーバーエンドポイントの構成は無視されます。管理プレーンは、MART サービスエンドポイントではなく、Apigee Connect を介して MART サーバーに接続します。
ヒント: 既存の Apigee Hybrid インストールをアップグレードする場合は、Apigee Connect の使用を停止し、MART Istio Ingress エンドポイントを直接使用するように戻すことができます。これを行うには、MART サービスエンドポイントの名前と値のペアを次のように指定します。
```
$ curl -v -X PUT \
   https://apigee.googleapis.com/v1/organizations/your_org_name \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
  "name" : "your_org_name",
  "properties" : {
    "property" : [ {
      "name" : "features.hybrid.enabled",
      "value" : "true"
    }, {
      "name" : "features.mart.server.endpoint",
      "value" : "https://HOST_ALIAS_DNS"
    }, {
      "name" : "features.mart.connect.enabled",
      "value" : "true"
    } ]
  }
}'
```
クラスタで Apigee Connect エージェントを起動します。
```
$ apigeectl apply -f your_overrides_file.yaml -c connect-agent
```

注: Apigee Connect を有効にすると、次の例のような元のインストールで指定した mart 構成スタンザは無視されます。ただし、mart スタンザはオーバーライドファイルに存在する必要があります。削除しないでください。Apigee Connect がベータ版である間は、MART にアクセスするための既存の方法が引き続きサポートされるため、MART 構成が存在する必要があります。

mart:
  hostAlias: "mart.apigee-hybrid-docs.net"
  serviceAccountPath: ./service-accounts/example-project-apigee-mart.json
  sslCertPath: ./certs/fullchain.pem
  sslKeyPath: ./certs/privkey.key

Apigee Connect エージェントのログを確認します。エラーが報告されていなければ、アップグレードに成功しています。
```
$ kubectl logs -n namespace apigee-connect-agent-pod-name
```
Apigee Connect エージェントは次のログカテゴリを報告します。

監査ログのカテゴリオペレーション

DATA_READ ConnectionService.ListConnections

DATA_WRITE Tether.Egress

Apigee Hybrid で監査ログを表示する方法については、監査ログ情報をご覧ください。

監査ログのカテゴリ	オペレーション
DATA_READ	`ConnectionService.ListConnections`
DATA_WRITE	`Tether.Egress`

このアップグレードで、Hybrid ランタイムプレーンは Apigee Connect を介して管理プレーンと通信するようになります。

インストールをテストします。

Apigee Connect の削除もご覧ください。

インストールのテスト

Apigee Hybrid UI を開きます。
デベロッパーと、以前に作成したデベロッパーアプリが UI に表示されていることを確認します。これらのエンティティは MART サーバーからクエリされるため、管理プレーンとランタイムプレーン間の通信が正しく構成されている場合にのみ表示されます。

リクエストが MART Ingress ではなく Apigee Connect を経由していることを確認するには、MART サーバーのログをチェックします。apigee-connect-agent-1.0 という名前の Apigee Connect エージェントのエントリが表示されます。

$ kubectl logs -n apigee apigee-mart-orgname-rc101-q72tl -c apigee-mart | grep connect

例:

"2019-12-11 04:59:52,321 org: env: target: action: context-id: mode: pool-1-thread-1 INFO MART_AUDITLOG - MartAuditListener.eventOccurred() : Type:Audit edge-gaambo-controlplane@system.gserviceaccount.com 1576040392317 /v1/organizations/apigee-connect-hybrid-prod/developers/ count=100&expand=true&startKey=4ee9e8f7-12b2-4cde-bf10-32d991469876 200 GET apigee-connect-hybrid-prod 10.40.11.3 10.40.0.5 apigee-connect-agent-1.0 null"

Hybrid UI で、API プロダクト、デベロッパー、デベロッパーアプリを作成します。次に、MART サービスログをチェックして、エンティティがランタイムプレーンに送信されたことを確認します。たとえば、次のログエントリは、foo-product という API プロダクトが受信されたことを示しています。

$ kubectl logs -n apigee apigee-mart-orgname-rc101-q72tl -c apigee-mart

2019-12-16 22:15:29,572 org: env: target: action: context-id: mode: pool-1-thread-1 INFO  MART_AUDITLOG - MartAuditListener.eventOccurred() : Type:Audit edge-gaambo-controlplane@system.gserviceaccount.com 1576534529566 /v1/organizations/myorg/apiproducts/foo-product/ -NA- 201 CREATE myorg 10.16.1.61  10.16.1.64 apigee-connect-agent-1.0 null

2019-12-16 22:15:30,412 org: env: target: action: context-id: mode: pool-1-thread-1 INFO  MART_AUDITLOG - MartAuditListener.eventOccurred() : Type:Audit edge-gaambo-controlplane@system.gserviceaccount.com 1576534530407 /v1/organizations/myorg/apps/ apiProduct=foo-product&expand=false 200 GET myorg 10.16.1.61  10.16.1.64 apigee-connect-agent-1.0 null

プロキシの作成とデプロイの説明に従って、新しいプロキシを作成してデプロイします。
API キーを要求して API プロキシを保護するの手順に従って、API キー検証を使用してプロキシを構成します。ランタイムは、Apigee Connect を介して管理プレーンから API キーを検証するために必要なデータを取得します。したがって、API キー検証が機能していれば、Apigee Connect は正しく機能しています。また、Apigee Connect のログでデータ転送のレポートを確認することもできます。

Apigee Connect の削除

Apigee Connect のデプロイを削除した場合、Pod のステータスは最大 7 分間「終了」状態のままになります。これは、予想される時間です。Apigee Connect エージェントは、既存の接続を即時停止するのではなく、有効期限が切れるまで待ちます。この遅延により、処理中のリクエストが失われないようにします。