Apigee Connect

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

はじめに

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

ハイブリッドランタイムプレーンで実行される主なサービスと Apigee Connect

前提条件

Apigee ハイブリッド 1.2.0 以降。

Apigee Connect をハイブリッドランタイムに追加する

Apigee ハイブリッドバージョン 1.3.0 以降の新規インストールでは、Apigee Connect がデフォルトで有効になっています。そのため、古いバージョンからアップグレードする場合には、これらの手順が必要になります。

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

Apigee Connect と Apigee ハイブリッドを有効にして使用する手順は次のとおりです。

Google Cloud API ライブラリで Apigee Connect API を有効にします。API は Google Cloud（GCP）コンソールまたは gcloud で有効にできます。Google Cloud Console で API を有効にする手順については、ステップ 3: API を有効にするをご覧ください。gcloud を使用して API を有効にするには:
1. gcloud の現在のプロジェクトを、Apigee が有効で Apigee 組織がプロビジョニングされている GCP プロジェクトに設定します。
```
$ gcloud config set project YOUR_GCP_PROJECT_ID
```
  ここで、YOUR_GCP_PROJECT_ID はプロジェクト ID です。
2. Apigee Connect API が有効になっていることを確認します。
```
gcloud services list
```
```
NAME                                 TITLE
apigee.googleapis.com                Apigee API
apigeeconnect.googleapis.com         Apigee Connect API
bigquery.googleapis.com              BigQuery API

...
```
3. 結果に apigeeconnect.googleapis.com が含まれていない場合は、API を有効にします。
```
$ gcloud services enable apigeeconnect.googleapis.com
```

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

必要であれば、MART サービスアカウントのメールアドレスを取得します。

gcloud iam service-accounts list

NAME                          EMAIL                                                 DISABLED
apigee-mart                   apigee-mart@hybrid-example.iam.gserviceaccount.com       False

...

MART サービスアカウントにすでにロールが割り当てられているかどうか確認します。

gcloud projects get-iam-policy YOUR_GCP_PROJECT_ID

...

- members:
  - serviceAccount:apigee-mart@hybrid-example.iam.gserviceaccount.com
  role: roles/apigeeconnect.Agent

...

結果に role: roles/apigeeconnect.Agent が含まれていない場合は、ロールを割り当てます。
```
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 は GCP プロジェクトの ID、YOUR_MART_SERVICE_ACCOUNT_EMAIL は MART サービスアカウントのメールアドレスです。

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

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

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

サービスアカウントの作成で説明されているように、MART サービスアカウントのキーファイルが hybrid_files/service_accounts ディレクトリにあることを確認します。
オーバーライドファイルを開きます。connectAgent:enabled プロパティが true に設定されていない場合や、欠落している場合は、次のスタンザを追加または更新します。
Apigee Connect スタンザは k8sCluster スタンザのすぐ下に配置する必要があります。

この構成では、ダウンロードしたサービスアカウントキーのパスを指定する必要があります。キーは、Apigee Connect エージェントのロールを持つサービスアカウントのものである必要があります。
```
# Apigee Connect Agent
connectAgent:
  enabled: true
  serviceAccountPath: ./service-accounts/MART_SA_KEYFILE.json
```
注: デフォルトでは、connectAgent の replicaCountMin は 1 です。本番環境のデプロイなど、その他のユースケースでは、replicaCountMin を 3 に変更します。例:
```
# Apigee Connect Agent
connectAgent:
  enabled: true
  replicaCountMin: 3
  serviceAccountPath: ./service-accounts/connect_agent_sa_key.json
```
組織で Apigee Connect 機能を有効にします。機能名は features.mart.connect.enabled です。
1. Synchronizer アクセスを有効にするの説明に従って、Apigee ハイブリッドを最初にインストールしたときに使用した、Apigee 組織管理者ロールを持つサービスアカウントキーを探します。これは apigee-org-admin サービスアカウントです。以下で説明するように、このキーは API 呼び出しを行うためのトークンの生成で必要になります。
2. 次の 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 組織管理者のロールを持つサービスアカウントキーのシステム上のパスです。
3. Apigee Connect がすでに有効になっているかどうかを確認します。
```
curl  https://apigee.googleapis.com/v1/organizations/your_org_name \
  -H "Authorization: Bearer $TOKEN"
```
  検索結果を確認します。
```
  "properties": {
    "property": [
      {
        "name": "features.mart.connect.enabled",
        "value": "true"
      },
      {
        "name": "features.hybrid.enabled",
        "value": "true"
      }
    ]
  },
```
4. 結果で、features..mart.connect.enabled が true に設定されていない場合は、次の Apigee API を呼び出し、組織で Apigee Connect を有効にします。
```
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 ハイブリッドをアップグレードする場合は、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 エージェントを起動します。
上記の手順のいずれかで変更を行った場合は、次のコマンドを使用して Apigee Connect エージェントを起動します。
```
 $APIGEECTL_HOME/apigeectl apply -f your_overrides_file.yaml --org
```

注: Apigee Connect が有効な場合、mart 構成スタンザには serviceAccountPath の値のみを含める必要があります。その他の値は無視され、省略できます。

mart:
  hostAlias: "mart.apigee-hybrid-docs.net"  # ignored when Apigee Connect is enabled.
  serviceAccountPath: ./service-accounts/example-project-apigee-mart.json
  sslCertPath: ./certs/fullchain.pem  # ignored when Apigee Connect is enabled.
  sslKeyPath: ./certs/privkey.key  # ignored when Apigee Connect is enabled.

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

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

DATA_READ ConnectionService.ListConnections

DATA_WRITE Tether.Egress

Apigee ハイブリッドで監査ログを表示する方法については、監査ログ情報をご覧ください。

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

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

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

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

インストールのテスト

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

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

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

次に例を示します。

"2020-07-31 04:59:52,321 org: env: target: action: context-id: mode: pool-1-thread-1 INFO.
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"

認証トークンを更新します。

export TOKEN=$(gcloud auth application-default print-access-token)

Apigee API を呼び出して、apigee-mart エンドポイントに接続する使用可能なストリームを表示します。

curl -s https://apigeeconnect.googleapis.com/v1/projects/YOUR_GCP_PROJECT_ID/endpoints/apigee_mart/connections \
  -H "Authorization: Bearer $TOKEN"

{
  "connections": [
    {
      "endpoint": "projects/865098068308/endpoints/apigee_mart",
      "cluster": {
        "name": "apigee-connect-test-cluster2",
        "region": "australia-southeast1"
      },
      "streamCount": 4
    },
    {
      "endpoint": "projects/865098068308/endpoints/apigee_mart",
      "cluster": {
        "name": "apigee-connect-test-cluster",
        "region": "us-central1"
      },
      "streamCount": 2
    }
  ]
}

Apigee Connect エージェントログを確認します。

kubectl logs -n namespace apigee-connect-agent-YOUR_GCP_PROJECT_ID-<....>

次のログは、Apigee Connect エージェントが起動して正常に通信していることを示します。

I0719 11:56:10.765526 2314949 main.go:47] Agent's flag values below
I0719 11:56:10.765928 2314949 main.go:50] "alsologtostderr" : false
I0719 11:56:10.765940 2314949 main.go:50] "cluster_name" : testABC
I0719 11:56:10.765947 2314949 main.go:50] "cluster_region" : us-west2
I0719 11:56:10.765953 2314949 main.go:50] "cpu_profile_enabled" : false
I0719 11:56:10.765959 2314949 main.go:50] "http_client_timeout" : 2m0s
I0719 11:56:10.765966 2314949 main.go:50] "http_port" : 7070
I0719 11:56:10.765972 2314949 main.go:50] "http_server" : false
I0719 11:56:10.765978 2314949 main.go:50] "insecure_ssl" : false
I0719 11:56:10.765984 2314949 main.go:50] "local_cert" :
I0719 11:56:10.765990 2314949 main.go:50] "log_backtrace_at" : :0
I0719 11:56:10.766001 2314949 main.go:50] "log_dir" :
I0719 11:56:10.766007 2314949 main.go:50] "logtostderr" : true
I0719 11:56:10.766012 2314949 main.go:50] "mem_profile_enabled" : false
I0719 11:56:10.766018 2314949 main.go:50] "project" : projects/apigee-connect-hybrid-prod
I0719 11:56:10.766025 2314949 main.go:50] "resource_id" :
I0719 11:56:10.766031 2314949 main.go:50] "server_addr" : apigeeconnect.googleapis.com:443
I0719 11:56:10.766036 2314949 main.go:50] "server_cert" : ./server.crt
I0719 11:56:10.766042 2314949 main.go:50] "server_key" : ./server.key
I0719 11:56:10.766047 2314949 main.go:50] "stderrthreshold" : 2
I0719 11:56:10.766054 2314949 main.go:50] "target_server" : http://127.0.0.1/
I0719 11:56:10.766059 2314949 main.go:50] "tether_endpoint" : APIGEE_MART
I0719 11:56:10.766065 2314949 main.go:50] "v" : 0
I0719 11:56:10.766072 2314949 main.go:50] "vmodule" :
I0719 11:56:10.845441 2314949 agent.go:400] successfully initiated http client
I0719 11:56:10.845772 2314949 agent.go:728] starting metrics http server at ":7070"
I0719 11:56:11.231959 2314949 agent.go:245] listening on tether 6407043920806543360
I0719 11:58:11.346544 2314949 agent.go:245] listening on tether 2101602677040349184
I0719 12:00:11.461084 2314949 agent.go:245] listening on tether 9109203697228840960
I0719 12:02:11.583743 2314949 agent.go:245] listening on tether 8978599308035096576
I0719 12:02:40.325633 2314949 agent.go:255] tether id 6407043920806543360 is closed

...

ハイブリッド UI で、API プロダクト、デベロッパー、デベロッパーアプリを作成します。次に、プロキシに複数の API 呼び出しを行います。

リクエストの処理中に生成された Connect Agent のログは、正常性やエラーの確認に役立ちます。

kubectl logs -n namespace apigee-connect-agent-YOUR_GCP_PROJECT_ID-<....>

INFO: 2020/04/13 03:29:08 "961ff385-600a-427a-8864-ba066ff42330": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200
INFO: 2020/04/13 03:29:08 Attempting to send response 961ff385-600a-427a-8864-ba066ff42330 on
tether 16734438331890270208
INFO: 2020/04/13 03:29:09 "e2fc0492-6e78-4c58-972b-7de8258b9e86": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200
INFO: 2020/04/13 03:29:09 Attempting to send response e2fc0492-6e78-4c58-972b-7de8258b9e86 on
tether 12483040283652521984
INFO: 2020/04/13 03:29:10 "1ab3023b-b763-4b91-bf4f-ca8c02f62e50": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200
INFO: 2020/04/13 03:29:10 Attempting to send response 1ab3023b-b763-4b91-bf4f-ca8c02f62e50 on
tether 12483040283652521984
INFO: 2020/04/13 03:29:12 "1fa3e3c3-a36e-4ff1-b2d3-5cf14f2f8fdd": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200
INFO: 2020/04/13 03:29:12 Attempting to send response 1fa3e3c3-a36e-4ff1-b2d3-5cf14f2f8fdd on
tether 16734438331890270208
INFO: 2020/04/13 03:29:13 "09b7ef9d-f53d-466a-a174-e88fc7e5286d": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200
INFO: 2020/04/13 03:29:13 Attempting to send response 09b7ef9d-f53d-466a-a174-e88fc7e5286d on
tether 16734438331890270208
INFO: 2020/04/13 03:29:14 "c2ce8b73-8faf-4a05-88d9-24fb2bf45552": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200
INFO: 2020/04/13 03:29:14 Attempting to send response c2ce8b73-8faf-4a05-88d9-24fb2bf45552 on
tether 12483040283652521984
INFO: 2020/04/13 03:29:15 "fdc3bac5-2b83-4b57-a28d-d8b455dae71e": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200
INFO: 2020/04/13 03:29:15 Attempting to send response fdc3bac5-2b83-4b57-a28d-d8b455dae71e on
tether 12483040283652521984
INFO: 2020/04/13 03:29:16 "260026a9-f578-4447-a1d2-d8e49cf181d8": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200
INFO: 2020/04/13 03:29:16 Attempting to send response 260026a9-f578-4447-a1d2-d8e49cf181d8 on
tether 12483040283652521984
INFO: 2020/04/13 03:29:17 "bf3d74a1-94ae-4041-892f-56f1ed9c9cff": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200
INFO: 2020/04/13 03:29:17 Attempting to send response bf3d74a1-94ae-4041-892f-56f1ed9c9cff on
tether 16734438331890270208
INFO: 2020/04/13 03:29:18 "6d017278-3b7a-40fb-9c63-7c34320e7df1": received response from target
"apigee-mart-apigee-connect-hybrid-prod.apigee.svc.cluster.local:8843", status code: 200

IAM 権限拒否エラーによる Connect Agent の失敗が原因で発生したログは、エージェントのクラッシュを引き起こします。

F0719 12:34:33.128565 2326128 tether.go:29] failed to register stream with Apigee Connect, got
'PermissionDenied': rpc error: code = PermissionDenied desc = Permission denied on resource '//
apigeeconnect.googleapis.com/projects/apigee-connect-hybrid-prod/endpoints/APIGEE_MART' (or it
may not exist).

F0719 12:34:33.128565 2326128 tether.go:29] failed to register stream with Apigee Connect, got
'PermissionDenied': rpc error: code = PermissionDenied desc = Permission denied on resource pro
ject apigee-connect-hybrid-prod.

Apigee Connect の削除

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