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 ハイブリッドを有効にして使用する手順は次のとおりです。

  1. 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
  2. Apigee ハイブリッド インストール手順のサービス アカウントの作成手順で作成した MART サービス アカウントに、Apigee Connect エージェントのロールを追加します。
    1. 必要であれば、MART サービス アカウントのメールアドレスを取得します。
      gcloud iam service-accounts list
      NAME                          EMAIL                                                 DISABLED
      apigee-mart                   apigee-mart@hybrid-example.iam.gserviceaccount.com       False
      
      ...
    2. MART サービス アカウントにすでにロールが割り当てられているかどうか確認します。
      gcloud projects get-iam-policy YOUR_GCP_PROJECT_ID
      ...
      
      - members:
        - serviceAccount:apigee-mart@hybrid-example.iam.gserviceaccount.com
        role: roles/apigeeconnect.Agent
      
      ...
    3. 結果に 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 を使用して権限を付与する方法については、以下をご覧ください。

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

    Apigee Connect スタンザは k8sCluster スタンザのすぐ下に配置する必要があります。

    この構成では、ダウンロードしたサービス アカウント キーのパスを指定する必要があります。キーは、Apigee Connect エージェントのロールを持つサービス アカウントのものである必要があります。

    # Apigee Connect Agent
    connectAgent:
      enabled: true
      serviceAccountPath: ./service-accounts/MART_SA_KEYFILE.json
    # Apigee Connect Agent
    connectAgent:
      enabled: true
      replicaCountMin: 3
      serviceAccountPath: ./service-accounts/connect_agent_sa_key.json
  5. 組織で 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.enabledtrue に設定されていない場合は、次の 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"
          } ]
        }
      }'

  6. クラスタで Apigee Connect エージェントを起動します。

    上記の手順のいずれかで変更を行った場合は、次のコマンドを使用して Apigee Connect エージェントを起動します。

     $APIGEECTL_HOME/apigeectl apply -f your_overrides_file.yaml --org

  7. 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.
  8. Apigee Connect エージェントのログを確認します。エラーが報告されていなければ、アップグレードに成功しています。
    kubectl logs -n namespace apigee-connect-agent-pod-name

    Apigee Connect エージェントは次のログカテゴリを報告します。
    監査ログのカテゴリ オペレーション
    DATA_READ ConnectionService.ListConnections
    DATA_WRITE Tether.Egress
    Apigee ハイブリッドで監査ログを表示する方法については、監査ログ情報をご覧ください。
  9. このアップグレードにより、ハイブリッド ランタイム プレーンは Apigee Connect を介して管理プレーンと通信するようになります。

  10. インストールをテストします

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

インストールのテスト

  1. Apigee ハイブリッド UI を開きます。
  2. UI に、デベロッパーと以前に作成したデベロッパー アプリが表示されていることを確認します。これらのエンティティは、MART サーバーからクエリされるため、管理プレーンとランタイム プレーン間の通信が正しく構成されている場合にのみ表示されます。
  3. リクエストが 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"
  4. 認証トークンを更新します。
    export TOKEN=$(gcloud auth application-default print-access-token)
  5. 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
        }
      ]
    }
  6. Apigee Connect エージェント ログを確認します。
    kubectl logs -n namespace apigee-connect-agent-YOUR_GCP_PROJECT_ID-<....>

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

    I0719 11.66:10.765526 2314949 main.go:47] Agent's flag values below
    I0719 11.66:10.765928 2314949 main.go:50] "alsologtostderr" : false
    I0719 11.66:10.765940 2314949 main.go:50] "cluster_name" : testABC
    I0719 11.66:10.765947 2314949 main.go:50] "cluster_region" : us-west2
    I0719 11.66:10.765953 2314949 main.go:50] "cpu_profile_enabled" : false
    I0719 11.66:10.765959 2314949 main.go:50] "http_client_timeout" : 2m0s
    I0719 11.66:10.765966 2314949 main.go:50] "http_port" : 7070
    I0719 11.66:10.765972 2314949 main.go:50] "http_server" : false
    I0719 11.66:10.765978 2314949 main.go:50] "insecure_ssl" : false
    I0719 11.66:10.765984 2314949 main.go:50] "local_cert" :
    I0719 11.66:10.765990 2314949 main.go:50] "log_backtrace_at" : :0
    I0719 11.66:10.766001 2314949 main.go:50] "log_dir" :
    I0719 11.66:10.766007 2314949 main.go:50] "logtostderr" : true
    I0719 11.66:10.766012 2314949 main.go:50] "mem_profile_enabled" : false
    I0719 11.66:10.766018 2314949 main.go:50] "project" : projects/apigee-connect-hybrid-prod
    I0719 11.66:10.766025 2314949 main.go:50] "resource_id" :
    I0719 11.66:10.766031 2314949 main.go:50] "server_addr" : apigeeconnect.googleapis.com:443
    I0719 11.66:10.766036 2314949 main.go:50] "server_cert" : ./server.crt
    I0719 11.66:10.766042 2314949 main.go:50] "server_key" : ./server.key
    I0719 11.66:10.766047 2314949 main.go:50] "stderrthreshold" : 2
    I0719 11.66:10.766054 2314949 main.go:50] "target_server" : http://127.0.0.1/
    I0719 11.66:10.766059 2314949 main.go:50] "tether_endpoint" : APIGEE_MART
    I0719 11.66:10.766065 2314949 main.go:50] "v" : 0
    I0719 11.66:10.766072 2314949 main.go:50] "vmodule" :
    I0719 11.66:10.845441 2314949 agent.go:400] successfully initiated http client
    I0719 11.66:10.845772 2314949 agent.go:728] starting metrics http server at ":7070"
    I0719 11.66:11.231.69 2314949 agent.go:245] listening on tether 6407043920806543360
    I0719 11.68: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.683743 2314949 agent.go:245] listening on tether 8978599308035096576
    I0719 12:02:40.325633 2314949 agent.go:255] tether id 6407043920806543360 is closed
    
    ...
  7. ハイブリッド 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 エージェントは、既存の接続を即時停止するのではなく、有効期限が切れるまで待ちます。この遅延により、処理中のリクエストが失われないようにします。