Edge Microgateway の操作と構成のリファレンス

現在、Apigee Edge のドキュメントを表示しています。
Apigee X のドキュメントをご確認ください
情報

Edge Microgateway バージョン 3.2.x

このトピックでは、Edge Microgateway を管理および構成する方法について説明します。

インターネットに接続できる場合の Edge Microgateway のアップグレード

このセクションでは、既存の Edge Microgateway インストールをアップグレードする方法について説明します。インターネットに接続せずに運用している場合は、インターネット接続なしで Edge Microgateway をインストールできますか?をご覧ください。

Apigee では、本番環境をアップグレードする前に、新しいバージョンで既存の構成をテストすることをおすすめします。

  1. 次の npm コマンドを実行して、Edge Microgateway の最新バージョンにアップグレードします。
    npm upgrade edgemicro -g

    特定のバージョンの Edge Microgateway をインストールするには、インストール コマンドでバージョン番号を指定する必要があります。たとえば、バージョン 3.2.3 にインストールするには、次のコマンドを使用します。

    npm install edgemicro@3.2.3 -g
  2. バージョン番号を確認します。たとえば、バージョン 3.2.3 をインストールした場合は、次のようになります。
    edgemicro --version
    current nodejs version is v12.5.0
    current edgemicro version is 3.2.3
        
  3. 最後に、edgemicro-auth プロキシの最新バージョンにアップグレードします。
    edgemicro upgradeauth -o $ORG -e $ENV -u $USERNAME

構成の変更

知っておくべき構成ファイルは次のとおりです。

  • デフォルトのシステム構成ファイル
  • 新しく初期化された Edge Microgateway インスタンスのデフォルト構成ファイル
  • 実行中のインスタンスの動的構成ファイル

このセクションでは、これらのファイルと、その変更について知っておくべきことについて説明します。

デフォルトのシステム構成ファイル

Edge Microgateway をインストールすると、デフォルトのシステム構成ファイルが次の場所に配置されます。

prefix/lib/node_modules/edgemicro/config/default.yaml

ここで、prefixnpm 接頭辞ディレクトリです。このディレクトリが見つからない場合は、 Edge Microgateway のインストール場所をご覧ください。

システム構成ファイルを変更する場合は、Edge Microgateway を再初期化、再構成、再起動する必要があります。

edgemicro init
edgemicro configure [params]
edgemicro start [params]

新しく初期化された Edge Microgateway インスタンスのデフォルト構成ファイル

edgemicro init を実行すると、システム構成ファイル(上記の説明)である default.yaml~/.edgemicro ディレクトリに配置されます。

~/.edgemicro の構成ファイルを変更する場合は、Edge Microgateway を再構成して再起動する必要があります。

edgemicro stop
edgemicro configure [params]
edgemicro start [params]

実行中のインスタンスの動的構成ファイル

edgemicro configure [params] を実行すると、~/.edgemicro に動的構成ファイルが作成されます。ファイル名には org-env-config.yaml というパターンを使用します。ここで、orgenv は Apigee Edge の組織名と環境名です。このファイルを使用して構成を変更し、ダウンタイムなしで再読み込みできます。たとえば、プラグインを追加して構成する場合、下記で説明するように、ダウンタイムを発生させずに構成を再読み込みできます。

Edge Microgateway が実行されている場合(ゼロ ダウンタイム オプション):

  1. Edge Microgateway 構成を再読み込みします。
    edgemicro reload -o $ORG -e $ENV -k $KEY -s $SECRET

    ここで

    • $ORG は Edge 組織名です(組織管理者である必要があります)。
    • $ENV は組織の環境です(「test」や「prod」など)。
    • $KEY は、以前に Configure コマンドで返された鍵です。
    • $SECRET は、以前に Configure コマンドで返された鍵です。

    次に例を示します。

    edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \
      -s 05c14356e42ed1...4e34ab0cc824

Edge Microgateway が停止している場合:

  1. Edge Microgateway を再起動します。
    edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET

    ここで

    • $ORG は Edge 組織名です(組織管理者である必要があります)。
    • $ENV は組織の環境です(「test」や「prod」など)。
    • $KEY は、以前に Configure コマンドで返された鍵です。
    • $SECRET は、以前に Configure コマンドで返された鍵です。

    例:

    edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \
      -s 05c1435...e34ab0cc824

以下に構成ファイルの例を示します。構成ファイルの設定の詳細については、Edge Microgateway 構成リファレンスをご覧ください。

edge_config:
  bootstrap: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test
  jwt_public_key: 'https://docs-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://docs-test.apigee.net/edgemicro-auth/products'
edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
headers:
  x-forwarded-for: true
  x-forwarded-host: true
  x-request-id: true
  x-response-time: true
  via: true
oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  verify_api_key_url: 'https://docs-test.apigee.net/edgemicro-auth/verifyApiKey'
analytics:
  uri: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/axpublisher/organization/docs/environment/test

環境変数を設定する

Edge の組織と環境の値、および Edge Microgateway の起動に必要な鍵とシークレットを必要とするコマンドライン インターフェース コマンドは、次の環境変数に格納できます。

  • EDGEMICRO_ORG
  • EDGEMICRO_ENV
  • EDGEMICRO_KEY
  • EDGEMICRO_SECRET

これらの変数の設定は省略可能です。これらを設定すると、コマンドライン インターフェース(CLI)を使用して Edge Microgateway を構成して起動する際に、値を指定する必要はありません。

Edge Microgateway サーバーで SSL を構成する

Apigee Edge Microgateway での TLS の構成については、次の動画をご覧ください。

動画 説明
一方向ノースバウンド TLS を構成する Apigee Edge Microgateway での TLS の構成について学習します。 この動画では、TLS の概要とその重要性を説明し、Edge Microgateway の TLS を紹介します。また、ノースバウンド一方向 TLS の構成方法についても説明します。
双方向ノースバウンド TLS を構成する これは、Apigee Edge Microgateway での TLS の構成に関する 2 番目の動画です。この動画では、ノースバウンド双方向 TLS を構成する方法について説明します。
一方向と双方向のサウスバウンド TLS を構成する Apigee Edge Microgateway での TLS の構成に関するこの 3 番目の動画では、サウスバウンドの一方向 TLS と双方向 TLS の構成方法について説明します。

SSL を使用するように Microgateway サーバーを構成できます。たとえば、SSL が構成されている場合、次のように「https」プロトコルを使用して Edge Microgateway から API を呼び出すことができます。

https://localhost:8000/myapi

Microgateway サーバーで SSL を構成する手順は次のとおりです。

  1. openssl ユーティリティまたは任意の方法で、SSL 証明書と鍵を生成または取得します。
  2. edgemicro:ssl 属性を Edge Microgateway 構成ファイルに追加します。オプションの一覧については、以下の表をご覧ください。例:
    edgemicro:
      ssl:
       key: <absolute path to the SSL key file>
       cert: <absolute path to the SSL cert file>
       passphrase: admin123 #option added in v2.2.2
       rejectUnauthorized: true #option added in v2.2.2
       requestCert: true
  3. Edge Microgateway を再起動します。編集した構成ファイル(デフォルト ファイルまたはランタイム構成ファイル)に応じて、構成の変更で説明されている手順を行います。

SSL を構成した構成ファイルの edgemicro セクションの例を次に示します。

edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
  ssl:
    key: /MyHome/SSL/em-ssl-keys/server.key
    cert: /MyHome/SSL/em-ssl-keys/server.crt
    passphrase: admin123 #option added in v2.2.2
    rejectUnauthorized: true #option added in v2.2.2

サポートされているすべてのサーバー オプションは次のとおりです。

オプション 説明
key ca.key ファイルのパス(PEM 形式)。
cert ca.cert ファイルのパス(PEM 形式)。
pfx クライアントの秘密鍵、証明書、CA 証明書(PFX 形式)を含む pfx ファイルのパス。
passphrase 秘密鍵または PFX のパスフレーズを含む文字列。
ca 信頼できる PEM 形式の証明書のリストを含むファイルのパス。
ciphers 使用する暗号を記述した文字列を「:」で区切って指定します。
rejectUnauthorized true の場合、サーバー証明書は指定された CA のリストと照らし合わせて検証されます。検証が失敗した場合は、エラーが返されます。
secureProtocol 使用する SSL メソッド。たとえば、SSL をバージョン 3 に強制するには、「SSLv3_method」と入力します。
servername SNI(Server Name Indication)TLS 拡張機能のサーバー名。
requestCert 双方向 SSL の場合は true、一方向 SSL の場合は false

クライアント SSL/TLS オプションの使用

ターゲット エンドポイントに接続するときに、Edge Microgateway を TLS または SSL クライアントとして構成できます。Microgateway 構成ファイルで、targets 要素を使用して SSL/TLS オプションを設定します。特定のターゲットを複数指定できます。マルチターゲットの例を以下に示します。

この例では、すべてのホストに適用される設定を示します。

edgemicro:
...
targets:
  ssl:
    client:
      key: /Users/jdoe/nodecellar/twowayssl/ssl/client.key
      cert: /Users/jdoe/nodecellar/twowayssl/ssl/ca.crt
      passphrase: admin123
      rejectUnauthorized: true

この例では、設定は指定したホストにのみ適用されます。

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    ssl:
      client:
        key: /Users/myname/twowayssl/ssl/client.key
        cert: /Users/myname/twowayssl/ssl/ca.crt
        passphrase: admin123
        rejectUnauthorized: true

TLS の例を次に示します。

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    tls:
      client:
        pfx: /Users/myname/twowayssl/ssl/client.pfx
        passphrase: admin123
        rejectUnauthorized: true

複数の特定のターゲットに TLS/SSL 設定を適用する場合は、構成の最初のホストを「空」として指定し、ユニバーサル リクエストを有効にしてから、特定のホストを任意の順序で指定する必要があります。この例では、設定は複数の特定のホストに適用されています。

targets:
 - host:   ## Note that this value must be "empty"
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       passphrase: admin123
       rejectUnauthorized: true
 - host: 'myserver1.example.com'
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       rejectUnauthorized: true
 - host: 'myserver2.example.com'
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       rejectUnauthorized: true

サポートされているすべてのクライアント オプションは次のとおりです。

オプション 説明
pfx クライアントの秘密鍵、証明書、CA 証明書(PFX 形式)を含む pfx ファイルのパス。
key ca.key ファイルのパス(PEM 形式)。
passphrase 秘密鍵または PFX のパスフレーズを含む文字列。
cert ca.cert ファイルのパス(PEM 形式)。
ca 信頼できる PEM 形式の証明書のリストを含むファイルのパス。
ciphers 使用する暗号を記述した文字列を「:」で区切って指定します。
rejectUnauthorized true の場合、サーバー証明書は指定された CA のリストと照らし合わせて検証されます。検証が失敗した場合は、エラーが返されます。
secureProtocol 使用する SSL メソッド。たとえば、SSL をバージョン 3 に強制するには、「SSLv3_method」と入力します。
servername SNI(Server Name Indication)TLS 拡張機能のサーバー名。

edgemicro-auth プロキシのカスタマイズ

デフォルトでは、Edge Microgateway は Apigee Edge にデプロイされたプロキシを OAuth2 認証に使用します。 このプロキシは、最初に edgemicro configure を実行したときにデプロイされます。このプロキシのデフォルト構成を変更して、JSON Web Token(JWT)にカスタム クレームのサポートを追加し、トークンの有効期限を構成して更新トークンを生成できます。詳しくは、GitHub の edgemicro-auth ページをご覧ください。

カスタム認証サービスの使用

デフォルトでは、Edge Microgateway は Apigee Edge にデプロイされたプロキシを OAuth2 認証に使用します。 このプロキシは、最初に edgemicro configure を実行したときにデプロイされます。デフォルトでは、このプロキシの URL は Edge Microgateway 構成ファイルで次のように指定されています。

authUri: https://myorg-myenv.apigee.net/edgemicro-auth

独自のカスタム サービスを使用して認証を処理する場合は、サービスを指すように構成ファイルの authUri 値を変更します。たとえば、LDAP を使用して本人確認を行うサービスがあるとします。

ログファイルの管理

Edge Microgateway により、各リクエストとレスポンスに関する情報がログに記録されます。ログファイルは、デバッグとトラブルシューティングに役立つ情報を提供します。

ログファイルの保存場所

デフォルトでは、ログファイルは /var/tmp に保存されます。

デフォルトのログファイル ディレクトリを変更する方法

ログファイルが保存されるディレクトリは、Edge Microgateway 構成ファイルで指定します。構成の変更もご覧ください。

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

dir の値を変更して、別のログファイル ディレクトリを指定します。

コンソールにログを送信する

ログ情報がログファイルではなく標準出力に送信されるように、ロギングを構成できます。次のように to_console フラグを true に設定します。

edgemicro:
  logging:
    to_console: true

この設定では、ログは標準出力に送信されます。現時点では、stdout とログファイルの両方にログを送信することはできません。

ロギングレベルを設定する方法

edgemicro 構成で使用するログレベルを指定します。ログレベルとその説明の完全なリストについては、edgemicro 属性をご覧ください。

たとえば、次の構成では、ロギングレベルを debug に設定します。

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: debug
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

ログ間隔を変更する方法

これらの間隔は Edge Microgateway 構成ファイルで構成できます。構成の変更もご覧ください。

構成可能な属性は次のとおりです。

  • stats_log_interval: (デフォルト: 60)統計情報レコードが API ログファイルに書き込まれる間隔(秒単位)。
  • rotate_interval: (デフォルト: 24)ログファイルをローテーションする間隔(時間単位)。例:
edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

ログファイルの厳密な権限を緩和する方法

デフォルトでは、Edge Microgateway は、ファイル権限レベルを 0600 に設定してアプリケーション ログファイル(api-log.log)を生成します。この権限レベルでは、外部アプリやユーザーはログファイルを読み取ることができません。この厳密な権限レベルを緩和するには、logging:disableStrictLogFiletrue に設定します。この属性を true にすると、ファイル権限が 0755 に設定されたログファイルが作成されます。false の場合、または属性が指定されていない場合、権限はデフォルトで 0600 に設定されます。

v3.2.3 で追加されました。

次に例を示します。

edgemicro:
 logging:
   disableStrictLogFile: true

ログファイルのメンテナンスのおすすめの方法

ログファイルデータは時間の経過とともに蓄積されるため、次の方法を採用することをおすすめします。

  • ログファイルは非常に大きくなる可能性があるため、ログファイル ディレクトリに十分な空き容量があることを確認してください。以降のログファイルの保存場所デフォルトのログファイル ディレクトリを変更する方法をご覧ください。
  • 少なくとも 1 週間に 1 回、ログファイルを削除するか、別のアーカイブ ディレクトリに移動してください。
  • ポリシーでログを削除する場合は、CLI コマンド edgemicro log -c を使用して古いログを削除(クリーンアップ)できます。

ログファイルの命名規則

各 Edge Microgateway インスタンスは、.log 拡張子が付いたログファイルを生成します。ログファイルの命名規則は次のとおりです。

edgemicro-HOST_NAME-INSTANCE_ID-api.log

次に例を示します。

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log

ログファイルの内容について

v2.3.3 で追加

デフォルトでは、このロギング サービスは、ダウンロードされたプロキシ、プロダクト、JSON Web Token(JWT)の JSON を省略します。これらのオブジェクトをコンソールに出力する場合は、Edge Microgateway を起動するときにコマンドライン フラグ DEBUG=* を設定します。例:

DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456

「api」ログファイルの内容

「api」ログファイルには、Edge Microgateway を介したリクエストとレスポンスのフローに関する詳細情報が含まれています。「api」ログファイルの名前は次のようになります。

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

Edge Microgateway に対するリクエストごとに、4 つのイベントが「api」ログファイルにキャプチャされます。

  • クライアントからの受信リクエスト
  • ターゲットへの送信リクエスト
  • ターゲットからの受信レスポンス
  • クライアントへの発信レスポンス

ログファイルをよりコンパクトにするため、これらの個別のエントリは省略表記で表されます。ここでは、4 つのイベントのそれぞれを表す 4 つのサンプル エントリを示します。ログファイルには、次のようになります(行番号はドキュメント内での参照用であり、ログファイルには含まれていません)。

(1) 1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
(2) 1436403888665 info treq m=GET, u=/, h=127.0.0.18080, i=0
(3) 1436403888672 info tres s=200, d=7, i=0
(4) 1436403888676 info res s=200, d=11, i=0

1 つずつ見ていきましょう。

1. クライアントからの受信リクエストの例:

1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
  • 1436403888651 - Unix 日付スタンプ
  • info - ロギングレベル。この値は、トランザクションのコンテキストと、edgemicro 構成で設定されているロギングレベルによって異なります。ロギングレベルを設定する方法をご覧ください。統計レコードの場合、レベルは stats に設定されます。統計情報レコードは、stats_log_interval 構成で設定された間隔で報告されます。ログ間隔を変更する方法もご覧ください。
  • req - イベントを識別します。この場合はクライアントからのリクエストです。
  • m - リクエストで使用される HTTP 動詞。
  • u - URL のベースパスに続く部分。
  • h - Edge Microgateway がリッスンしているホストとポート番号。
  • r - クライアント リクエスト送信元のリモートホストとポート。
  • i - リクエスト ID。4 つのイベント エントリすべてでこの ID を共有します。各リクエストには一意のリクエスト ID が割り当てられます。ログレコードをリクエスト ID と関連付けることで、ターゲットのレイテンシに関する有益な情報を得ることができます。
  • d - Edge Microgateway がリクエストを受信してからの期間(ミリ秒)。上記の例では、リクエスト 0 に対するターゲットのレスポンスは 7 ミリ秒後に受信され(3 行目)、さらに 4 ミリ秒後にレスポンスがクライアントに送信されました(4 行目)。つまり、リクエスト レイテンシの合計は 11 ミリ秒で、このうち 7 ミリ秒はターゲットで、4 ミリ秒は Edge Microgateway 自体で使用されました。

2. ターゲットに対する送信リクエストのサンプル:

1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0
  • 1436403888651 - Unix 日付スタンプ
  • info - ロギングレベル。この値は、トランザクションのコンテキストと、edgemicro 構成で設定されているロギングレベルによって異なります。ロギングレベルを設定する方法をご覧ください。統計レコードの場合、レベルは stats に設定されます。統計情報レコードは、stats_log_interval 構成で設定された間隔で報告されます。ログ間隔を変更する方法もご覧ください。
  • treq - イベントを識別します。ここでは、ターゲット リクエストです。
  • m - ターゲット リクエストで使用される HTTP 動詞。
  • u - URL のベースパスに続く部分。
  • h - バックエンド ターゲットのホストとポート番号。
  • i - ログエントリの ID。4 つのイベント エントリすべてでこの ID を共有します。

3. ターゲットからの受信レスポンスのサンプル

1436403888672 info tres s=200, d=7, i=0

1436403888651 - Unix 日付スタンプ

  • info - ロギングレベル。この値は、トランザクションのコンテキストと、edgemicro 構成で設定されているロギングレベルによって異なります。ロギングレベルを設定する方法をご覧ください。統計レコードの場合、レベルは stats に設定されます。統計情報レコードは、stats_log_interval 構成で設定された間隔で報告されます。ログ間隔を変更する方法もご覧ください。
  • tres - イベントを識別します。この場合、目標回答数を指定します。
  • s - HTTP レスポンス ステータス。
  • d - 期間(ミリ秒単位)。ターゲットによる API 呼び出しにかかった時間。
  • i - ログエントリの ID。4 つのイベント エントリすべてでこの ID を共有します。

4. クライアントへの送信レスポンスのサンプル

1436403888676 info res s=200, d=11, i=0

1436403888651 - Unix 日付スタンプ

  • info - ロギングレベル。この値は、トランザクションのコンテキストと、edgemicro 構成で設定されているロギングレベルによって異なります。ロギングレベルを設定する方法をご覧ください。統計レコードの場合、レベルは stats に設定されます。統計情報レコードは、stats_log_interval 構成で設定された間隔で報告されます。ログ間隔を変更する方法もご覧ください。
  • res - イベントを識別します。この場合、クライアントへのレスポンス。
  • s - HTTP レスポンス ステータス。
  • d - 期間(ミリ秒単位)。これは、ターゲット API にかかった時間と Edge Microgateway 自体でかかった時間を含む、API 呼び出しにかかった合計時間です。
  • i - ログエントリの ID。4 つのイベント エントリすべてでこの ID を共有します。

ログファイルのスケジュール

ログファイルは、rotate_interval 構成属性で指定された間隔でローテーションされます。ローテーション間隔が終了するまで、エントリは同じログファイルに継続的に追加されます。ただし、Edge Microgateway が再起動されるたびに、新しい UID を受け取り、この UID を持つ新しいログファイルのセットを作成します。ログファイルの適切なメンテナンス方法もご覧ください。

エラー メッセージ

一部のログエントリにはエラー メッセージが含まれます。エラーがどこで、なぜ発生するのかを特定するには、Edge Microgateway エラー リファレンスをご覧ください。

Edge Microgateway 構成リファレンス

構成ファイルの場所

このセクションで説明する構成属性は、Edge Microgateway 構成ファイルにあります。構成の変更もご覧ください。

edge_config 属性

これらの設定は、Edge Microgateway インスタンスと Apigee Edge の間のインタラクションを構成するために使用されます。

  • bootstrap: (デフォルト: なし)Apigee Edge で実行されている Edge Microgateway 固有のサービスを指す URL。Edge Microgateway は、このサービスを使用して Apigee Edge と通信します。公開鍵/秘密鍵のペアを生成するコマンド edgemicro genkeys を実行すると、この URL が返されます。詳細については、Edge Microgateway の設定と構成をご覧ください。
  • jwt_public_key: (デフォルト: なし)Apigee Edge にデプロイされている Edge Microgateway プロキシを指す URL。このプロキシは、署名付きアクセス トークンをクライアントに発行するための認証エンドポイントとして機能します。プロキシをデプロイするコマンド edgemicro Configure を実行すると、この URL が返されます。詳細については、Edge Microgateway の設定と構成をご覧ください。
  • quotaUri: 組織にデプロイされた edgemicro-auth プロキシを介して割り当てを管理する場合は、この構成プロパティを設定します。このプロパティが設定されていない場合、割り当てエンドポイントはデフォルトで内部 Edge Microgateway エンドポイントになります。
    edge_config:
      quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth
    

edgemicro 属性

これらの設定では、Edge Microgateway プロセスを構成します。

  • port: (デフォルト: 8000)Edge Microgateway プロセスがリッスンするポート番号。
  • max_connections: (デフォルト: -1)Edge Microgateway が受信できる同時受信接続の最大数を指定します。この数を超えると、次のステータスが返されます。

    res.statusCode = 429; // Too many requests
  • max_connections_hard: (デフォルト: -1)接続をシャットダウンする前に Edge Microgateway が受信できる同時リクエストの最大数。この設定は、サービス拒否攻撃を阻止するためのものです。通常は、max_connections よりも大きな数に設定します。
  • logging:
    • level:(デフォルト: error)
      • info - (推奨)Edge Microgateway インスタンスを通過するすべてのリクエストとレスポンスをログに記録します。
      • warn - 警告メッセージのみをログに記録します。
      • error - エラー メッセージのみをログに記録します。
      • debug - デバッグ メッセージを、情報、警告、エラー メッセージとともにログに記録します。
      • trace - エラーのトレース情報を、情報、警告、エラー メッセージとともにログに記録します。
      • none - ログファイルを作成しません。
    • dir: (デフォルト: /var/tmp)ログファイルが保存されるディレクトリ。
    • stats_log_interval: (デフォルト: 60)統計情報レコードが API ログファイルに書き込まれる間隔(秒単位)。
    • rotate_interval: (デフォルト: 24)ログファイルをローテーションする間隔(時間単位)。
  • dir: ./gateway ディレクトリから ./plugins ディレクトリへの相対パスまたは絶対パス。
  • sequence: Edge Microgateway インスタンスに追加するプラグイン モジュールのリスト。モジュールはここで指定された順序で実行されます。
  • debug: Edge Microgateway プロセスにリモート デバッグを追加します。
    • port: リッスンするポート番号。たとえば、このポートでリッスンするように IDE デバッガを設定します。
    • args: デバッグ プロセスへの引数。例: args --nolazy
  • config_change_poll_interval: (デフォルト: 600 秒)Edge Microgateway は定期的に新しい構成を読み込み、変更があった場合は再読み込みを実行します。このポーリングにより、Edge で行われた変更(プロダクト、Microgateway 対応プロキシなどに対する変更)と、ローカル構成ファイルに対する変更が取得されます。
  • disable_config_poll_interval:(デフォルト: false)自動変更ポーリングをオフにするには、true に設定します。
  • request_timeout: ターゲット リクエストのタイムアウトを設定します。タイムアウトは秒単位で設定します。タイムアウトが発生すると、Edge Microgateway は 504 ステータス コードを返します。(v2.4.x で追加)
  • keep_alive_timeout: このプロパティを使用すると、Edge Microgateway のタイムアウト(ミリ秒単位)を設定できます。(デフォルト:5 秒)(v3.0.6 で追加)
  • headers_timeout: この属性は、HTTP パーサーが完全な HTTP ヘッダーを受信するのを待機する時間(ミリ秒単位)を制限します。

    例:

    edgemicro:
      keep_alive_timeout: 6000
      headers_timeout: 12000

    内部的には、このパラメータによってリクエストに Node.js の Server.headersTimeout 属性が設定されます。(デフォルト: edgemicro.keep_alive_timeout で設定された時間より 5 秒長い。このデフォルトの設定により、ロードバランサまたはプロキシが誤って接続が切断されることがなくなります)。(v3.1.1 で追加)

  • noRuleMatchAction:(文字列)accesscontrol プラグインで指定された一致ルールが解決されない(一致しない)場合に実行するアクション(アクセスを許可または拒否)。有効な値: ALLOW または DENY デフォルト: ALLOW(追加: v3.1.7)
  • enableAnalytics: (デフォルト: true)属性を false に設定して、分析プラグインを読み込まないようにします。この場合、Apigee Edge Analytics の呼び出しは行われません。true に設定する場合、またはこの属性を指定しない場合、アナリティクス プラグインは通常どおりに動作します。詳しくは、edgemicro 属性をご覧ください。(v3.1.8 で追加)。

    例:

    edgemicro
      enableAnalytics=false|true
  • on_target_response_abort: この属性を使用すると、クライアント(Edge Microgateway)とターゲット サーバー間の接続が早期に終了した場合の Edge Microgateway の動作を制御できます。
    説明
    デフォルト on_target_response_abort が指定されていない場合、デフォルトの動作として、エラーを表示せずにレスポンスが切り捨てられます。ログファイルでは、targetResponse aborted と 502 レスポンス コードとともに警告メッセージが表示されます。
    appendErrorToClientResponseBody カスタムエラー TargetResponseAborted がクライアントに返されます。ログファイルでは、targetResponse aborted と 502 レスポンス コードとともに警告メッセージが表示されます。さらに、エラー TargetResponseAborted がメッセージ Target response ended prematurely. とともにログに記録されます。
    abortClientRequest Edge Microgateway がリクエストを中止し、ログファイル TargetResponseAborted に 502 リクエストのステータス コードを含む警告が書き込まれます。

例:

edgemicro:
 on_target_response_abort: appendErrorToClientResponseBody | abortClientRequest

header 属性

これらの設定は、特定の HTTP ヘッダーの処理方法を構成します。

  • x-forwarded-for: (デフォルト: true)x-forwarded-for ヘッダーがターゲットに渡されないようにするには、false に設定します。リクエストに x-forwarded-for ヘッダーがある場合、その値は Edge Analytics の client-ip 値に設定されます。
  • x-forwarded-host: (デフォルト: true)x-forwarded-host ヘッダーがターゲットに渡されないようにするには、false に設定します。
  • x-request-id: (デフォルト: true)x-request-id ヘッダーがターゲットに渡されないようにするには、false に設定します。
  • x-response-time: (デフォルト: true)x-response-time ヘッダーがターゲットに渡されないようにするには、false に設定します。
  • via: (デフォルト: true)via ヘッダーがターゲットに渡されないようにするには、false に設定します。

OAuth 属性

これらの設定では、Edge Microgateway でクライアント認証を適用する方法を構成します。

  • allowNoAuthorization: (デフォルト: false)true に設定すると、Authorization ヘッダーなしで API 呼び出しが Edge Microgateway を通過できるようになります。Authorization ヘッダーを要求するには、これを false に設定します(デフォルト)。
  • allowInvalidAuthorization: (デフォルト: false)true に設定すると、Authorization ヘッダーで渡されたトークンが無効または期限切れの場合でも API 呼び出しで通過できます。有効なトークンを要求するには、これを false に設定します(デフォルト)。
  • authorization-header: (デフォルト: Authorization: Bearer)アクセス トークンを Edge Microgateway に送信するために使用されるヘッダー。ターゲットが他の目的で Authorization ヘッダーを使用する必要がある場合は、このデフォルトを変更できます。
  • api-key-header: (デフォルト: x-api-key)API キーを Edge Microgateway に渡すために使用されるヘッダーまたはクエリ パラメータの名前。API キーを使用するもご覧ください。
  • keep-authorization-header: (デフォルト: false)true に設定すると、リクエストで送信された Authorization ヘッダーがターゲットに渡されます(保持されます)。
  • allowOAuthOnly: true に設定すると、すべての API が署名なしアクセス トークンを含む Authorization ヘッダーを送信する必要があります。下位互換性を維持しながら、OAuth セキュリティ モデルのみを許可できます。(2.4.x で追加)
  • allowAPIKeyOnly -- true に設定すると、すべての API に API キーを含む x-api-key ヘッダー(またはカスタムの場所)が必要です。これにより、(下位互換性を維持しながら)API キー セキュリティ モデルのみを許可できます。(2.4.x で追加)
  • gracePeriod -- このパラメータは、システム クロックと、JWT 認証トークンで指定された Not before(nbf)または Issued At(iat)時刻とのわずかな不一致によって発生するエラーを防ぐのに役立ちます。このような不一致に対応するため、このパラメータに秒数を設定します。(2.5.7 で追加)

プラグイン固有の属性

各プラグインで構成可能な属性の詳細については、プラグインの使用をご覧ください。

プロキシのフィルタリング

Edge Microgateway インスタンスが処理する microgateway 対応プロキシをフィルタリングできます。Edge Microgateway が起動すると、関連付けられている組織内のすべての microgateway 対応プロキシがダウンロードされます。次の構成を使用して、Microgateway が処理するプロキシを制限します。たとえば、この構成では、Microgateway が処理するプロキシを edgemicro_proxy-1edgemicro_proxy-2edgemicro_proxy-3 の 3 つに制限します。

edgemicro:
  proxies:
  - edgemicro_proxy-1
  - edgemicro_proxy-2
  - edgemicro_proxy-3

商品を名前でフィルタリングする

次の構成を使用して、Edge Microgateway がダウンロードして処理する API プロダクトの数を制限します。ダウンロードしたプロダクトをフィルタするには、Edge Microgateway の *.config.yaml ファイルにリストされている /products API に productnamefilter クエリ パラメータを追加します。例:

edge_config:
  bootstrap: >-
    https://edgemicroservices.apigee.net/edgemicro/bootstrap/organization/willwitman/environment/test
  jwt_public_key: 'https://myorg-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://myorg-test.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24'

クエリ パラメータの値は、正規表現の形式で指定し、URL エンコードする必要があります。たとえば、正規表現 ^[Ee]dgemicro.*$ は、「edgemicro-test-1」、「edgemicro_demo」、「Edgemicro_New_Demo」などの名前を検出します。クエリ パラメータで使用するのに適した URL エンコード値は %5E%5BEe%5Ddgemicro.%2A%24 です。

次のデバッグ出力は、フィルタされた商品のみがダウンロードされたことを示しています。

...
2020-05-27T03:13:50.087Z [76060] [microgateway-config network] products download from https://gsc-demo-prod.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24 returned 200 OK
...
....
....
{
   "apiProduct":[
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590549037549,
         "createdBy":"k***@g********m",
         "displayName":"test upper case in name",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590549037549,
         "lastModifiedBy":"k***@g********m",
         "name":"Edgemicro_New_Demo",
         "proxies":[
            "catchall"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590548328998,
         "createdBy":"k***@g********m",
         "displayName":"edgemicro test 1",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590548328998,
         "lastModifiedBy":"k***@g********m",
         "name":"edgemicro-test-1",
         "proxies":[
            "Lets-Encrypt-Validation-DoNotDelete"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[
            "/",
            "/**"
         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1558182193472,
         "createdBy":"m*********@g********m",
         "displayName":"Edge microgateway demo product",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1569077897465,
         "lastModifiedBy":"m*********@g********m",
         "name":"edgemicro_demo",
         "proxies":[
            "edgemicro-auth",
            "edgemicro_hello"
         ],
         "quota":"600",
         "quotaInterval":"1",
         "quotaTimeUnit":"minute",
         "scopes":[

         ]
      }
   ]
}

カスタム属性による商品のフィルタリング

カスタム属性に基づいて商品をフィルタするには:

  1. Edge UI で、Edge Microgateway を構成した組織/環境にある edgemicro_auth プロキシを選択します。
  2. [Develop] タップで、エディタで JavaCallout ポリシーを開きます。
  3. 属性名のカンマ区切りリストを指定し、キー products.filter.attributes を含むカスタム属性を追加します。いずれかのカスタム属性名を含むプロダクトのみが Edge Microgateway に返されます。
  4. カスタム属性 products.filter.env.enablefalse に設定することで、プロダクトが現在の環境に対して有効になっているかどうかを確認する確認を無効にすることもできます。(デフォルトは true です)。
  5. (Private Cloud のみ)Edge for Private Cloud を使用している場合、CPS 以外の環境でプロダクトを pull するには、プロパティ org.noncpstrue に設定します。
  6. 例:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
        <DisplayName>JavaCallout</DisplayName>
        <FaultRules/>
        <Properties>
            <Property name="products.filter.attributes">attrib.one, attrib.two</Property>
            <Property name="products.filter.env.enable">false</Property>
            <Property name="org.noncps">true</Property>
        </Properties>
        <ClassName>io.apigee.microgateway.javacallout.Callout</ClassName>
        <ResourceURL>java://micro-gateway-products-javacallout-2.0.0.jar</ResourceURL>
    </JavaCallout>
    
    このフィルタはプロダクト名フィルタと併用できます。

分析のプッシュ頻度の構成

次の構成パラメータを使用して、Edge Microgateway が Apigee に分析データを送信する頻度を制御します。

  • bufferSize(省略可): 最も古いレコードの削除を開始する前にバッファが保持できる分析レコードの最大数。デフォルト: 10,000
  • batchSize(省略可): Apigee に送信される分析レコードのバッチの最大サイズ。デフォルト: 500
  • flushInterval(省略可): Apigee に送信される分析レコードのバッチの各フラッシュの間隔(ミリ秒単位)。デフォルト: 5,000

例:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

分析データのマスキング

次の構成では、リクエストパスの情報が Edge Analytics に表示されません。microgateway の構成に以下を追加して、リクエスト URI やリクエストパスをマスクします。URI は、リクエストのホスト名とパスの部分で構成されます。

analytics:
  mask_request_uri: 'string_to_mask'
  mask_request_path: 'string_to_mask'

Edge Analytics での API 呼び出しの分離

特定の API パスを分離するように分析プラグインを構成すると、Edge Analytics ダッシュボードで個別のプロキシとして表示されるようになります。たとえば、実際の API プロキシ呼び出しと混同しないように、ダッシュボードでヘルスチェック API を分離できます。Analytics ダッシュボードでは、分離されたプロキシは次の命名パターンに従います。

edgemicro_proxyname-health

次の画像は、アナリティクス ダッシュボードで 2 つの分離されたプロキシ(edgemicro_hello-healthedgemicro_mock-health)を示しています。

これらのパラメータを使用すると、アナリティクス ダッシュボードで相対パスと絶対パスを別々のプロキシとして分離できます。

  • relativePath(省略可): Analytics ダッシュボードで分離する相対パスを指定します。たとえば、/healthcheck を指定すると、パス /healthcheck を含むすべての API 呼び出しが、ダッシュボードに edgemicro_proxyname-health として表示されます。このフラグはプロキシのベースパスを無視します。ベースパスを含むフルパスに基づいて分離するには、proxyPath フラグを使用します。
  • proxyPath(省略可): アナリティクス ダッシュボードで分離する、プロキシのベースパスを含む完全な API プロキシパスを指定します。たとえば、/mocktarget/healthcheck/mocktarget はプロキシのベースパス)を指定すると、パス /mocktarget/healthcheck を含むすべての API 呼び出しは、ダッシュボードに edgemicro_proxyname-health として表示されます。

たとえば、次の構成では、/healthcheck を含む API パスは、分析プラグインによって分離されます。つまり、/foo/healthcheck/foo/bar/healthcheck は、分析ダッシュボードで edgemicro_proxyname-health という別のプロキシとして分離されます。

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  relativePath: /healthcheck

次の構成では、プロキシパスが /mocktarget/healthcheck の API は、分析ダッシュボードで edgemicro_proxyname-health という別のプロキシとして分離されます。

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  proxyPath: /mocktarget/healthcheck

会社のファイアウォールの内側で Edge Microgateway を設定する

Apigee Edge との通信に HTTP プロキシを使用する

バージョン 3.1.2 で追加されました。

Edge Microgateway と Apigee Edge 間の通信に HTTP プロキシを使用するには、次の操作を行います。

  1. 環境変数 HTTP_PROXYHTTPS_PROXYNO_PROXY を設定します。これらの変数は、Apigee Edge との通信に使用する各 HTTP プロキシのホスト、または Apigee Edge との通信を処理しないホストを制御します。次に例を示します。
    export HTTP_PROXY='http://localhost:3786'
    export HTTPS_PROXY='https://localhost:3786'
    export NO_PROXY='localhost,localhost:8080'

    NO_PROXY には、Edge Microgateway がプロキシしないドメインのカンマ区切りのリストを指定できます。

    これらの変数の詳細については、https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables をご覧ください。

  2. Edge Microgateway を再起動します。

ターゲットの通信に HTTP プロキシを使用する

バージョン 3.1.2 で追加されました。

Edge Microgateway とバックエンド ターゲット間の通信に HTTP プロキシを使用するには、次の操作を行います。

  1. microgateway 構成ファイルに次の構成を追加します。
    edgemicro:
      proxy:
        tunnel: true | false
        url: proxy_url
        bypass: target_host # target hosts to bypass the proxy.
        enabled: true | false

    ここで

    • tunnel: (省略可)true の場合、Edge Microgateway は HTTP CONNECT メソッドを使用して、単一の TCP 接続で HTTP リクエストをトンネリングします。(後述のように、プロキシを構成する環境変数で TLS が有効になっている場合も同様です)。デフォルト: false
    • url: HTTP プロキシの URL。
    • bypass: (省略可)HTTP プロキシをバイパスする 1 つ以上のターゲット ホスト URL をカンマ区切りで指定します。このプロパティが設定されていない場合は、NO_PROXY 環境変数を使用してバイパスするターゲット URL を指定します。
    • enabled: true で proxy.url が設定されている場合、HTTP プロキシに proxy.url の値を使用します。true と proxy.url が設定されていない場合は、Apigee Edge との通信に HTTP プロキシを使用するで説明されているように、HTTP プロキシ環境変数 HTTP_PROXYHTTPS_PROXY で指定されたプロキシを使用します。

    次に例を示します。

    edgemicro:
      proxy:
        tunnel: true
        url: 'http://localhost:3786'
        bypass: 'localhost','localhost:8080' # target hosts to bypass the proxy.
        enabled: true

  2. Edge Microgateway を再起動します。

Microgateway 対応プロキシでのワイルドカードの使用

edgemicro_*(Microgateway 対応)プロキシのベースパスには、1 つ以上の「*」ワイルドカードを使用できます。たとえば、ベースパスを /team/*/members にすると、新しいチームをサポートするために新しい API プロキシを作成しなくても、クライアントは https://[host]/team/blue/membershttps://[host]/team/green/members を呼び出せます。/**/ はサポートされていないことに注意してください。

重要: Apigee では、ベースパスの最初の要素としてワイルドカード「*」を使用できません。たとえば、/*/ 検索はサポートされていません。

JWT 鍵のローテーション

JWT を最初に生成した後、Edge の暗号化された KVM に格納されている公開鍵/秘密鍵のペアの変更が必要になることがあります。新しい鍵ペアを生成するこのプロセスは、鍵のローテーションと呼ばれます。

Edge Microgateway による JWT の使用

JSON Web Token(JWT)は RFC7519 で説明されているトークン標準です。JWT を使用すると、一連のクレームに署名できます。JWT の受信者はこれらのクレームを確実に確認できます。

CLI を使用して JWT を生成し、API キーの代わりに API 呼び出しの Authorization ヘッダーで使用できます。例:

curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"

CLI を使用して JWT を生成する方法については、トークンを生成するをご覧ください。

鍵のローテーションとは

JWT を最初に生成した後、Edge の暗号化された KVM に格納されている公開鍵/秘密鍵のペアの変更が必要になることがあります。新しい鍵ペアを生成するこのプロセスは、鍵のローテーションと呼ばれます。鍵をローテーションすると、新しい秘密鍵と公開鍵のペアが生成され、Apigee Edge 組織 / 環境の microgateway KVM に保存されます。また、古い公開鍵は元の鍵 ID 値とともに保持されます。

JWT を生成するために、Edge は暗号化された KVM に保存されている情報を使用します。Edge Microgateway を最初に設定(構成)したときに、microgateway という KVM が作成され、鍵が設定されました。KVM の鍵は、JWT の署名と暗号化に使用されます。

KVM キーには次のものがあります。

  • private_key - JWT の署名に使用される最新の(最近作成された)RSA 秘密鍵。

  • public_key - private_key で署名された JWT の検証に使用される最新の(最近作成された)証明書。

  • private_key_kid - 最新の(最近作成された)秘密鍵 ID。この鍵 ID は private_key の値に関連付けられ、鍵のローテーションをサポートするために使用されます。

  • public_key1_kid - 最新の(最近作成された)公開鍵 ID。この鍵は public_key1 値に関連付けられ、鍵のローテーションをサポートするために使用されます。この値は秘密鍵の kids と同じです。

  • public_key1 - 最新の(最近作成された)公開鍵。

鍵のローテーションを行うと、マップ内の既存の鍵の値が置き換えられ、古い公開鍵を保持するために新しい鍵が追加されます。例:

  • public_key2_kid - 古い公開鍵の ID。この鍵は public_key2 値に関連付けられ、鍵のローテーションをサポートするために使用されます。

  • public_key2 - 古い公開鍵。

検証用に提示された JWT は、新しい公開鍵を使用して検証されます。検証が失敗した場合、JWT の有効期限が切れるまで(token_expiry* 間隔の後、デフォルトは 30 分)、古い公開鍵が使用されます。このようにして、API トラフィックをすぐに中断することなく、鍵を「ローテーション」できます。

鍵のローテーション方法

このセクションでは、鍵のローテーションを行う方法について説明します。

  1. KVM をアップグレードするには、edgemicro upgradekvm コマンドを使用します。このコマンドの実行の詳細については、KVM のアップグレードをご覧ください。この手順が必要なのは 1 回だけです。
  2. edgemicro-oauth プロキシをアップグレードするには、edgemicro upgradeauth コマンドを使用します。このコマンドの実行の詳細については、 edgemicro-auth プロキシのアップグレードをご覧ください。この手順が必要なのは 1 回だけです。
  3. 次の行を ~/.edgemicro/org-env-config.yaml ファイルに追加します。ここで、使用するマイクロゲートウェイを構成したのと同じ組織と環境を指定する必要があります。
    jwk_public_keys: 'https://$ORG-$ENV.apigee.net/edgemicro-auth/jwkPublicKeys'
  4. 鍵のローテーション コマンドを実行して、鍵をローテーションします。このコマンドの詳細については、鍵のローテーションをご覧ください。

    edgemicro rotatekey -o $ORG -e $ENV -k $KEY -s $SECRET

    例:

    edgemicro rotatekey -o docs -e test \
    -k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
    -s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47
    

鍵のローテーション後、Edge は複数の鍵を Edge Microgateway に返します。次の例では、各キーに一意の「kid」(キー ID)値があります。その後、Microgateway はこれらの鍵を使用して認証トークンを検証します。トークンの検証で不合格だった場合、Microgateway は鍵セットに古い鍵があるかどうかを確認し、その鍵を試します。返される鍵の形式は JSON Web Key(JWK)です。この形式については、RFC 7517 をご覧ください。

{
  "keys": [
    {
      "kty": "RSA",
      "n": "nSl7R_0wKLiWi6cO3n8aOJwYGBtinq723Jgg8i7KKWTSTYoszOjgGsJf_MX4JEW1YCScwpE5o4o8ccQN09iHVTlIhk8CNiMZNPipClmRVjaL_8IWvMQp1iN66qy4ldWXzXnHfivUZZogCkBNqCz7VSC5rw2Jf57pdViULVvVDGwTgf46sYveW_6h8CAGaD0KLd3vZffxIkoJubh0yMy0mQP3aDOeIGf_akeZeZ6GzF7ltbKGd954iNTiKmdm8IKhz6Y3gLpC9iwQ-kex_j0CnO_daHl1coYxUSCIdv4ziWIeM3dmjQ5_2dEvUDIGG6_Az9hTpNgPE5J1tvrOHAmunQ",
      "e": "AQAB",
      "kid": "2"
    },
    {
      "kty": "RSA",
      "n": "8BKwzx34BMUcHwTuQtmp8LFRCMxbkKg_zsWD6eOMIUTAsORexTGJsTy7z-4aH0wJ3fT-3luAAUPLBQwGcuHo0P1JnbtPrpuYjaJKSZOeIMOnlryJCspmv-1xG4qAqQ9XaZ9C97oecuj7MMoNwuaZno5MvsY-oi5B_gqED3vIHUjaWCErd4reONyFSWn047dvpE6mwRhZbcOTkAHT8ZyKkHISzopkFg8CD-Mij12unxA3ldcTV7yaviXgxd3eFSD1_Z4L7ZRsDUukCJkJ-8qY2-GWjewzoxl-mAW9D1tLK6qAdc89yFem3JHRW6L1le3YK37-bs6b2a_AqJKsKm5bWw",
      "e": "AQAB",
      "kid": "1"
    }
  ]
}

「not before」遅延を設定する

バージョン 3.1.5 以前では、rotatekey コマンドによって生成された新しい秘密鍵はすぐに有効になり、生成された新しいトークンは新しい秘密鍵で署名されました。ただし、新しい公開鍵は、Microgateway 構成が更新されたときにのみ、10 分ごと(デフォルト)で Edge Microgateway インスタンスで使用可能になりました。トークンの署名から microgateway インスタンスが更新されるまでに時間がかかるため、すべてのインスタンスが最新の鍵を受け取るまで、最新の鍵で署名されたトークンは拒否されます。

複数の microgateway インスタンスが存在する場合、公開鍵のラグにより、ステータス 403 の断続的なランタイム エラーが発生することがあります。トークンの検証は 1 つのインスタンスでは合格するが、すべてのインスタンスが更新されるまで別のインスタンスでは失敗するためです。

バージョン 3.1.6 以降では、rotatekey コマンドの新しいフラグを使用して、新しい秘密鍵が有効になるまでの遅延を指定できます。これにより、すべての microgateway インスタンスを更新して新しい公開鍵を受け取るための時間を確保できます。新しいフラグは --nbf で、「not before」を表します。このフラグには、遅延時間(分)を示す整数値を指定します。

次の例では、遅延を 15 分に設定しています。

edgemicro rotatekey -o docs -e test \
-k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
-s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47 \
--nbf 15

この遅延は、config_change_poll_internal 構成の設定(デフォルトでは 10 分)より長く設定することをおすすめします。edgemicro 属性もご覧ください。

ダウンロードしたプロキシのフィルタリング

デフォルトでは、Edge Microgateway は、Edge 組織内の、名前の接頭辞「edgemicro_」で始まるすべてのプロキシをダウンロードします。このデフォルトを変更して、名前がパターンと一致するプロキシをダウンロードできます。

  1. Edge Micro 構成ファイル(~/.edgemicro/org-env-config.yaml)を開きます。
  2. edge_config に proxyPattern 要素を追加します。たとえば、次のパターンでは、edgemicro_foo、edgemicro_fast、edgemicro_first などのプロキシがダウンロードされます。
    edge_config:
    …
    proxyPattern: edgemicro_f*

API プロキシのないプロダクトの指定

Apigee Edge では、API プロキシを含まない API プロダクトを作成できます。このプロダクト構成により、そのプロダクトに関連付けられた API キーを、組織にデプロイされたすべてのプロキシで機能させることができます。バージョン 2.5.4 より、Edge Microgateway はこのプロダクト構成をサポートしています。

デバッグとトラブルシューティング

デバッガに接続する

Edge Microgateway は、node-inspector などのデバッガで実行できます。これは、カスタム プラグインのトラブルシューティングとデバッグに役立ちます。

  1. Edge Microgateway をデバッグモードで再起動します。これを行うには、start コマンドの先頭に DEBUG=* を追加します。
    DEBUG=* edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET

    デバッグ出力をファイルに転送するには、次のコマンドを使用します。

    export DEBUG=* nohup edgemicro start \
    -o $ORG -e $ENV -k $KEY -s $SECRET 2>&1 | tee /tmp/file.log

  2. デバッガを起動し、デバッグ プロセス用のポート番号をリッスンするよう設定します。
  3. Edge Microgateway コードのステップ実行、ブレークポイントの設定、式の監視などを行えるようになりました。

デバッグモードに関連する標準の Node.js フラグを指定できます。たとえば、--nolazy は非同期コードのデバッグに役立ちます。

ログファイルの確認

問題が発生した場合は、ログファイルで実行の詳細とエラー情報を確認してください。詳しくは、ログファイルの管理をご覧ください。

API キー セキュリティの使用

API キーは、Edge Microgateway にリクエストを行うクライアントを認証するシンプルなメカニズムを提供します。API キーは、Edge Microgateway 認証プロキシを含む Apigee Edge プロダクトからコンシューマ キー(クライアント ID とも呼ばれます)の値をコピーすることで取得できます。

鍵のキャッシュ保存

API キーは署名なしトークンと交換され、キャッシュに保存されます。キャッシュ保存を無効にするには、Edge Microgateway への受信リクエストに Cache-Control: no-cache ヘッダーを設定します。

API キーの使用

API キーは、API リクエストでクエリ パラメータまたはヘッダーとして渡すことができます。デフォルトでは、ヘッダー パラメータとクエリ パラメータ名はどちらも x-api-key です。

クエリ パラメータの例:

curl http://localhost:8000/foobar?x-api-key=JG616Gjz7xs4t0dvpvVsGdI49G34xGsz

ヘッダーの例:

curl http://localhost:8000/foobar -H "x-api-key:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

API キー名を設定する

デフォルトでは、x-api-key は API キーヘッダーとクエリ パラメータの両方に使用される名前です。このデフォルト値は、構成の変更で説明されているように、構成ファイルで変更できます。たとえば、名前を apiKey に変更するには、次のようにします。

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  api-key-header: apiKey

この例では、クエリ パラメータとヘッダー名の両方が apiKey に変更されます。どちらの場合も、x-api-key という名前は使用できなくなります。構成の変更もご覧ください。

例:

curl http://localhost:8000/foobar -H "apiKey:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

プロキシ リクエストで API キーを使用する方法については、 Edge Microgateway の保護をご覧ください。

アップストリーム レスポンス コードを有効にする

デフォルトでは、レスポンスが 200 ステータスでない場合、oauth プラグインは 4xx エラー ステータス コードのみを返します。この動作を変更すると、エラーに応じて常に正確な 4xx または 5xx コードを返すことができます。

この機能を有効にするには、Edge Microgateway 構成に oauth.useUpstreamResponse: true プロパティを追加します。次に例を示します。

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  gracePeriod: 10
  useUpstreamResponse: true

OAuth2 トークン セキュリティの使用

このセクションでは、OAuth2 アクセス トークンと更新トークンを取得する方法について説明します。アクセス トークンは、Microgateway を介して安全な API 呼び出しを行うために使用されます。更新トークンは、新しいアクセス トークンを取得するために使用されます。

アクセス トークンの取得方法

このセクションでは、edgemicro-auth プロキシを使用してアクセス トークンを取得する方法について説明します。

edgemicro token CLI コマンドを使用してアクセス トークンを取得することもできます。CLI の詳細については、トークンの管理をご覧ください。

API 1: 本文パラメータとして認証情報を送信する

この URL に含まれる組織名と環境名を実際の値に置き換えます。本文パラメータの client_idclient_secret は、実際の Apigee Edge のデベロッパー アプリから取得したコンシューマ ID とコンシューマ シークレットの値に置き換えます。

curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \
-d '{"grant_type": "client_credentials", "client_id": "your_client_id", \
"client_secret": "your_client_secret"}' -H "Content-Type: application/json"

API 2: Basic 認証ヘッダーで認証情報を送信する

クライアントの認証情報を Basic 認証ヘッダーとして、grant_type をフォーム パラメータとして送信します。このコマンドの形式については、RFC 6749: The OAuth 2.0 Authorization Framework でも説明されています。

http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \
-d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"

出力例

API が JSON レスポンスを返します。token プロパティと access_token プロパティに違いはありません。どちらを使用しても構いません。expires_in は秒単位で指定される整数値です。
{
"token": "eyJraWQiOiIxIiwidHlwIjoi",
"access_token": "eyJraWQiOiIxIiwid",
"token_type": "bearer",
"expires_in": 1799
}

更新トークンの取得方法

更新トークンを取得するには、edgemicro-auth プロキシの /token エンドポイントに対して API 呼び出しを行います。この API 呼び出しは password 権限付与タイプを使用して行う必要があります。以下でそのプロセスを順番に説明します。

  1. /token API を使用して、アクセス トークンと更新トークンを取得します。権限付与タイプは password です。
    curl -X POST \
      https://your_organization-your_environment.apigee.net/edgemicro-auth/token \
      -H 'Content-Type: application/json' \
      -d '{
       "client_id":"mpK6l1Bx9oE5zLdifoDbF931TDnDtLq",
       "client_secret":"bUdDcFgv3nXffnU",
       "grant_type":"password",
       "username":"mpK6lBx9RoE5LiffoDbpF931TDnDtLq",
       "password":"bUdD2FvnMsXffnU"
    }'

    API がアクセス トークンと更新トークンを返します。レスポンスは次のようになります。expires_in の値は整数で、秒単位で指定します。

    {
        "token": "your-access-token",
        "access_token": "your-access-token",
        "token_type": "bearer",
        "expires_in": 108,
        "refresh_token": "your-refresh-token",
        "refresh_token_expires_in": 431,
        "refresh_token_issued_at": "1562087304302",
        "refresh_token_status": "approved"
    }
  2. これで、更新トークンを使用して新しいアクセス トークンを取得できるようになりました。それには、同じ API の /refresh エンドポイントを呼び出します。次に例を示します。
    curl -X POST \
      https://willwitman-test.apigee.net/edgemicro-auth/refresh \
      -H 'Content-Type: application/json' \
      -d '{
       "client_id":"mpK6l1Bx9RoE5zLifoDbpF931TDnDtLq",
       "client_secret":"bUdDc2Fv3nMXffnU",
       "grant_type":"refresh_token",
       "refresh_token":"your-refresh-token"
    }'

    API から新しいアクセス トークンが返されます。レスポンスは次のようになります。

    {
        "token": "your-new-access-token"
        }

常時モニタリング

Forever は、プロセスが停止した場合やエラーが発生した場合に Node.js アプリを自動的に再起動する Node.js ツールです。Edge Microgateway には、Edge Microgateway を再起動する回数と間隔を制御するように構成できる forever.json ファイルがあります。このファイルは、forever-monitor と呼ばれる Forever サービスを構成します。このサービスは、Forever をプログラムで管理します。

forever.json ファイルは、Edge Microgateway ルート インストール ディレクトリにあります。 Edge Microgateway のインストール場所をご覧ください。構成オプションの詳細については、forever-monitor のドキュメントをご覧ください。

edgemicro forever コマンドには、forever.json ファイルの場所の指定(-f フラグ)と、Forever モニタリング プロセスの開始/停止(-a フラグ)を行うフラグが含まれます。例:

edgemicro forever -f ~/mydir/forever.json -a start

詳細については、CLI リファレンスの Forever モニタリングをご覧ください。

構成ファイル エンドポイントの指定

複数の Edge Microgateway インスタンスを実行している場合、1 つの場所から構成を管理できます。これを行うには、Edge Micro が構成ファイルをダウンロードできる HTTP エンドポイントを指定します。このエンドポイントは、Edge Micro を起動するときに -u フラグを使用して指定できます。

例:

edgemicro start -o jdoe -e test -u http://mylocalserver/mgconfig -k public_key -s secret_key

ここで、mgconfig エンドポイントは構成ファイルの内容を返します。このファイルは、デフォルトでは ~/.edgemicro にあり、命名規則 org-env-config.yaml です。

TCP 接続データ バッファリングの無効化

nodelay 構成属性を使用して、Edge Microgateway で使用される TCP 接続のデータ バッファリングを無効にできます。

デフォルトでは、TCP 接続は Nagle アルゴリズムを使用してデータをバッファリングしてからデータを送信します。nodelaytrue に設定すると、この動作が無効になります(socket.write() が呼び出されるたびにデータがすぐに送信されます)。詳細については、Node.js のドキュメントもご覧ください。

nodelay を有効にするには、次のように Edge Micro 構成ファイルを編集します。

edgemicro:
  nodelay: true
  port: 8000
  max_connections: 1000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Edge Microgateway をスタンドアロン モードで実行する

Edge Microgateway は、Apigee Edge の依存関係から完全に切断して実行できます。スタンドアロン モードと呼ばれるこのシナリオでは、インターネット接続なしで Edge Microgateway を実行してテストできます。

スタンドアロン モードでは、Apigee Edge への接続が必要なため、次の機能は動作しません。

  • OAuth と API キー
  • 割り当て
  • アナリティクス

一方、カスタム プラグインと Spike Arrest は、Apigee Edge への接続を必要としないため、正常に動作します。また、extauth という新しいプラグインを使用すると、スタンドアロン モードのときに、JWT を使用して microgateway への API 呼び出しを認可できます。

ゲートウェイの構成と起動

Edge Microgateway をスタンドアロン モードで実行するには:

  1. 次のような名前の構成ファイルを作成します。$HOME/.edgemicro/$ORG-$ENV-config.yaml

    例:

    vi $HOME/.edgemicro/foo-bar-config.yaml
  2. 次のコードをファイルに貼り付けます。
    edgemicro:
      port: 8000
      max_connections: 1000
      config_change_poll_interval: 600
      logging:
        level: error
        dir: /var/tmp
        stats_log_interval: 60
        rotate_interval: 24
      plugins:
        sequence:
          - extauth
          - spikearrest
    headers:
      x-forwarded-for: true
      x-forwarded-host: true
      x-request-id: true
      x-response-time: true
      via: true
    extauth:
      publickey_url: https://www.googleapis.com/oauth2/v1/certs
    spikearrest:
      timeUnit: second
      allow: 10
      buffersize: 0
  3. 値「1」の次の環境変数をエクスポートします。
    export EDGEMICRO_LOCAL=1
  4. 次の start コマンドを実行します。ここで、ローカル プロキシをインスタンス化するための値を指定します。
    edgemicro start -o $ORG -e $ENV -a $LOCAL_PROXY_NAME \
      -v $LOCAL_PROXY_VERSION -t $TARGET_URL -b $BASE_PATH

    ここで

    • $ORG は、構成ファイル名で使用した「組織」名です。
    • $ENV は、構成ファイル名に使用した「env」名です。
    • $LOCAL_PROXY_NAME は、作成するローカル プロキシの名前です。任意の名前を使用できます。
    • $LOCAL_PROXY_VERSION は、プロキシのバージョン番号です。
    • $TARGET_URL は、プロキシのターゲットの URL です。(ターゲットはプロキシが呼び出すサービスです)。
    • $BASE_PATH は、プロキシのベースパスです。値の最初にスラッシュを付ける必要があります。ルートのベースパスの場合は、スラッシュのみを指定します(「/」など)。

    例:

    edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
  5. 構成をテストします。
    curl http://localhost:8000/echo  { "error" : "missing_authorization" }

    extauth プラグインは foo-bar-config.yaml ファイルに含まれているため、「missing_authorization」エラーが発生します。このプラグインは、API 呼び出しの Authorization ヘッダーに存在する必要がある JWT を検証します。次のセクションでは、エラーなしで API 呼び出しを許可する JWT を取得します。

例: 認可トークンの取得

次の例は、Apigee Edge の Edge Microgateway JWT エンドポイント(edgemicro-auth/jwkPublicKeys)から JWT を取得する方法を示しています。このエンドポイントは、Edge Microgateway の標準の設定と構成を行うときにデプロイされます。Apigee エンドポイントから JWT を取得するには、まず Edge Microgateway の標準の設定を行い、インターネットに接続する必要があります。Apigee エンドポイントは例を示す目的でのみ使用され、必須ではありません。必要に応じて、別の JWT トークン エンドポイントを使用できます。その場合は、そのエンドポイントに提供されている API を使用して JWT を取得する必要があります。

edgemicro-auth/jwkPublicKeys エンドポイントを使用してトークンを取得する手順は次のとおりです。

  1. edgemicro-auth プロキシを Apigee Edge 上の組織/環境にデプロイするには、Edge Microgateway の標準の設定と構成を行う必要があります。以前にこの手順を行った場合は、繰り返す必要はありません。
  2. Edge Microgateway を Apigee Cloud にデプロイした場合は、このエンドポイントから JWT を取得するためにインターネットに接続する必要があります。
  3. Edge Microgateway を停止します。
    edgemicro stop
  4. 前に作成した構成ファイル($HOME/.edgemicro/orgenv-config.yaml)で、extauth:publickey_url 属性を Apigee Edge 組織/環境の edgemicro-auth/jwkPublicKeys エンドポイントを指定します。次に例を示します。
    extauth:
      publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'
  5. 構成ファイル名で使用した org/env 名を使用して、以前に行ったように Edge Microgateway を再起動します。次に例を示します。
    edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
  6. 認可エンドポイントから JWT トークンを取得します。edgemicro-auth/jwkPublicKeys エンドポイントを使用しているため、次の CLI コマンドを使用できます。

Edge Microgateway 用の JWT を生成するには、edgemicro token コマンドまたは API を使用します。例:

edgemicro token get -o your_org -e your_env \
  -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

ここで

  • your_org は、以前に Edge Microgateway を構成した Apigee 組織の名前です。
  • your_env は組織内の環境です。
  • i オプションは、edgemicro-auth プロキシを含むプロダクトを持つデベロッパー アプリのコンシューマ キーを指定します。
  • s オプションは、edgemicro-auth プロキシを含むプロダクトを持つデベロッパー アプリのコンシューマ シークレットを指定します。

このコマンドは、API 呼び出しの検証に使用できる JWT を生成するように Apigee Edge に要求します。

トークンを生成するもご覧ください。

スタンドアロン構成をテストする

構成をテストするには、次のように Authorization ヘッダーにトークンを追加して API を呼び出します。

curl http://localhost:8000/echo -H "Authorization: Bearer your_token

例:

curl http://localhost:8000/echo -H "Authorization: Bearer eyJraWQiOiIxIiwidHlwIjo...iryF3kwcDWNv7OQ"

出力例:

{
   "headers":{
      "user-agent":"curl/7.54.0",
      "accept":"*/*",
      "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
      "client_received_start_timestamp":"1535134472699",
      "x-authorization-claims":"eyJhdDbiO...M1OTE5MTA1NDkifQ==",
      "target_sent_start_timestamp":"1535134472702",
      "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
      "x-forwarded-proto":"http",
      "x-forwarded-host":"localhost:8000",
      "host":"mocktarget.apigee.net",
      "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
      "via":"1.1 localhost, 1.1 google",
      "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
      "connection":"Keep-Alive"
   },
   "method":"GET",
   "url":"/",
   "body":""
}

ローカル プロキシモードの使用

ローカル プロキシモードでは、Edge Microgateway で Apigee Edge に microgateway 対応プロキシをデプロイする必要はありません。代わりに、Microsoft の起動時にローカル プロキシ名、ベースパス、ターゲット URL を指定して、「ローカル プロキシ」を構成します。microgateway への API 呼び出しはローカル プロキシのターゲット URL に送信されます。それ以外の点では、ローカル プロキシモードの動作は、Edge Microgateway を通常モードで実行する場合とまったく同じです。認証は、Spike Arrest、割り当ての適用、カスタム プラグインなどと同様に機能します。

ユースケースと例

ローカル プロキシモードは、1 つのプロキシのみを Edge Microgateway インスタンスに関連付ける必要がある場合に便利です。たとえば、Edge Microgateway をサイドカー プロキシとして Kubernetes に挿入できます。この場合、Microgateway と Service はそれぞれ 1 つの Pod で実行され、Microgateway はコンパニオン サービスとの間のトラフィックを管理します。次の図は、Edge microgateway が Kubernetes クラスタでサイドカー プロキシとして機能するアーキテクチャを示しています。各 microgateway インスタンスは、コンパニオン サービスの 1 つのエンドポイントとのみ通信します。

サイドカーとしての Edgemicro

このアーキテクチャ スタイルの利点は、Edge Microgateway が Kubernetes クラスタなどのコンテナ環境にデプロイされた個々のサービスの API 管理を提供することです。

ローカル プロキシ モードの構成

ローカル プロキシ モードで実行するように Edge Microgateway を構成するには、次の操作を行います。

  1. Edge Microgateway の通常の設定とまったく同じように、edgemicro init を実行してローカル構成環境を設定します。Edge Microgateway の構成もご覧ください。
  2. Edge Microgateway の一般的な設定手順と同様に edgemicro configure を実行します。次に例を示します。
    edgemicro configure -o your_org -e your_env -u your_apigee_username

    このコマンドは、edgemicro-auth ポリシーを Edge にデプロイし、Microgateway の起動に必要な鍵とシークレットを返します。ヘルプが必要な場合は、Edge Microgateway の構成をご覧ください。

  3. Apigee Edge で API プロダクトを作成し、次の必須構成要件を設定します(他の構成はすべて必要に応じて管理できます)。
    • プロダクトに edgemicro-auth プロキシを追加する必要があります。このプロキシは、edgemicro configure を実行したときに自動的にデプロイされました。
    • リソースパスを指定する必要があります。プロダクトへのパス /** を追加することをおすすめします。詳細については、リソースパスの動作の構成をご覧ください。Edge ドキュメントの API プロダクトを作成するもご覧ください。
  4. Apigee Edge で、デベロッパーを作成します。または、必要に応じて既存のデベロッパーを使用することもできます。詳しくは、Edge 管理 UI を使用したデベロッパーの追加をご覧ください。

  5. Apigee Edge で、デベロッパー アプリを作成します。作成した API プロダクトをアプリに追加する必要があります。詳細については、Edge 管理 UI でアプリを登録するをご覧ください。
  6. Edge Microgateway がインストールされているマシンで、値「1」の次の環境変数をエクスポートします。
    export EDGEMICRO_LOCAL_PROXY=1
  7. start コマンドを実行します。
    edgemicro start -o your_org -e your_environment -k your_key -s your_secret \
        -a local_proxy_name -v local_proxy_version -t target_url -b base_path

    ここで

    • your_org は Apigee 組織です。
    • your_environment は組織内の環境です。
    • your_key は、edgemicro configure を実行したときに返された鍵です。
    • your_secret は、edgemicro configure を実行したときに返されたシークレットです。
    • local_proxy_name は、作成するローカル プロキシの名前です。
    • local_proxy_version は、プロキシのバージョン番号です。
    • target_url は、プロキシのターゲット(プロキシが呼び出すサービス)の URL です。
    • base_path は、プロキシのベースパスです。値の最初にスラッシュを付ける必要があります。ルートのベースパスの場合は、スラッシュのみを指定します(「/」など)。

    例:

    edgemicro start -o your_org -e test -k 7eb6aae644cbc09035a...d2eae46a6c095f \
      -s e16e7b1f5d5e24df...ec29d409a2df853163a -a proxy1 -v 1 \
      -t http://mocktarget.apigee.net -b /echo

構成のテスト

ローカル プロキシ構成をテストするには、プロキシ エンドポイントを呼び出します。たとえば、/echo のベースパスを指定した場合は、次のようにプロキシを呼び出すことができます。

curl  http://localhost:8000/echo
{
  "error" : "missing_authorization",
  "error_description" : "Missing Authorization header"
}

有効な API キーが指定されていないため、この最初の API 呼び出しでエラーが発生しました。キーは、以前に作成したデベロッパー アプリで確認できます。Edge UI でアプリを開き、コンシューマ キーをコピーして、次のように使用します。

curl  http://localhost:8000/echo -H 'x-api-key:your_api_key'

例:

curl  http://localhost:8000/echo -H "x-api-key:DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP"

出力例:

{
  "headers":{
    "user-agent":"curl/7.54.0",
    "accept":"*/*",
    "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
    "client_received_start_timestamp":"1535134472699",
    "x-authorization-claims":"eyJhdWQiOi...TQ0YmUtOWNlOS05YzM1OTE5MTA1NDkifQ==",
    "target_sent_start_timestamp":"1535134472702",
    "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
    "x-forwarded-proto":"http",
    "x-forwarded-host":"localhost:8000",
    "host":"mocktarget.apigee.net",
    "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
    "via":"1.1 localhost, 1.1 google",
    "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
    "connection":"Keep-Alive"
  },
  "method":"GET",
  "url":"/",
  "body":""
}

Synchronizer の使用

このセクションでは、Synchronizer の使用方法について説明します。Synchronizer は、Apigee Edge から構成データを取得してローカルの Redis データベースに書き込むことで、Edge Microgteway の復元性を向上させるオプション機能です。Synchronizer インスタンスが実行中の場合、別のノードで実行されている他の Edge Microgateway インスタンスは、このデータベースから直接構成を取得できます。

Syncrhonizer 機能は現在、Redis 5.0.x での動作がサポートされています。

Synchronizer とは何ですか?

Synchronizer は、Edge Microgateway に一定の復元力を提供します。これにより、Edge Microgateway のすべてのインスタンスで同じ構成が使用されるようになります。また、インターネットに障害が発生した場合でも、Edge Microgateway インスタンスを適切に起動して実行できます。

デフォルトでは、Edge Microgateway インスタンスは、API プロキシや API プロダクト構成などの構成データを取得して更新するために、Apigee Edge と通信できる必要があります。Edge とのインターネット接続が中断されても、最新の構成データがキャッシュに保存されるため、Microgateway インスタンスは引き続き機能できます。ただし、明確な接続がないと新しい microgateway インスタンスは起動できません。また、インターネットの中断により、他のインスタンスと同期されていない構成情報で 1 つ以上の microgateway インスタンスが実行される可能性もあります。

Edge Microgateway Synchronizer は、Edge Microgateway インスタンスが API プロキシ トラフィックの起動と処理に必要な構成データを取得するための代替メカニズムを提供します。Apigee Edge への呼び出しから取得される構成データには、jwk_public_keys 呼び出し、jwt_public_key 呼び出し、ブートストラップ呼び出し、API プロダクト呼び出しが含まれます。Synchronizer を使用すると、異なるノードで実行されているすべての Edge Microgateway インスタンスが正常に起動し、Edge Microgateway と Apigee Edge 間のインターネット接続が中断しても同期を維持できます。

Synchronizer は、特別に構成された Edge Microgateway のインスタンスです。Apigee Edge をポーリングし(タイミングは構成可能)、構成データを取得してローカルの Redis データベースに書き込むだけです。Synchronizer インスタンス自体は API プロキシ トラフィックを処理できません。別のノードで実行されている Edge Microgateway の他のインスタンスは、Apigee Edge ではなく Redis データベースから構成データを取得するように構成できます。すべての microgateway インスタンスは、構成データをローカル データベースから取得するため、インターネット障害が発生した場合でも、起動して API リクエストを処理できます。

Synchronizer インスタンスを構成する

Synchronizer として使用する Edge Microgateway インストールの org-env/config.yaml ファイルに次の構成を追加します。

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

次に例を示します。

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true
オプション 説明
redisHost Redis インスタンスが実行されているホスト。デフォルト: 127.0.0.1
redisPort Redis インスタンスのポート。デフォルト: 6379
redisDb 使用する Redis DB。デフォルト: 0
redisPassword データベースのパスワード。

最後に、構成ファイルを保存して Edge Microgateway インスタンスを起動します。Apigee Edge に対するポーリングと、ダウンロードした構成データの Redis データベースへの保存が開始されます。

通常の Edge Microgateway インスタンスの構成

Synchronizer が実行されている状態で、API プロキシ トラフィックを処理する通常の microgateway インスタンスを実行するように追加の Edge Microgateway ノードを構成できます。ただし、これらのインスタンスは、Apigee Edge ではなく Redis データベースから構成データを取得するように構成します。

次の構成を、追加の各 Edge Microgateway ノードの org-env/config.yaml ファイルに追加します。synchronizerMode プロパティが 0 に設定されていることに注意してください。このプロパティは、API プロキシ トラフィックを処理する通常の Edge Microgateway インスタンスとして動作するようにインスタンスを設定し、インスタンスは Redis データベースから構成データを取得します。

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

次に例を示します。

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

構成プロパティ

Synchronizer の使用をサポートするために、次の構成プロパティが追加されました。

属性 Values 説明
edge_config.synchronizerMode 0 または 1

0(デフォルト)の場合、Edge Microgateway は標準モードで動作します。

1 の場合、Edge Microgateway インスタンスを起動し、Synchronizer として動作させます。このモードでは、インスタンスは Apigee Edge から構成データを pull し、ローカルの Redis データベースに保存します。このインスタンスは API プロキシ リクエストを処理できません。このインスタンスは、Apigee Edge をポーリングして構成データを確認し、ローカル データベースに書き込むだけです。次に、他の microgateway インスタンスをデータベースから読み取るように構成する必要があります。

edge_config.redisBasedConfigCache true または false true の場合、Edge Microgateway インスタンスは、Apigee Edge ではなく Redis データベースから構成データを取得します。Redis データベースは、Synchronizer が書き込みに構成されているデータベースと同じである必要があります。Redis データベースが使用できない場合、またはデータベースが空の場合、Microgateway は既存の cache-config.yaml ファイルで構成を探します。

false(デフォルト)の場合、Edge Microgateway インスタンスは通常どおり Apigee Edge から構成データを取得します。

edgemicro.config_change_poll_interval 時間間隔(秒) Synchronizer が Apigee Edge からデータを pull するポーリング間隔を指定します。

プラグインの除外 URL の設定

指定した URL に対してプラグインの処理をスキップするように microgateway を構成できます。この「除外」URL は、すべてのプラグインに対してグローバルに構成することも、特定のプラグインに対して構成することもできます。

次に例を示します。

...
edgemicro:
  ...
  plugins:
    excludeUrls: '/hello,/proxy_one' # global exclude urls
    sequence:
      - oauth
      - json2xml
      - quota
json2xml:
  excludeUrls: '/hello/xml'  # plugin level exclude urls
...

この例では、プラグインはパス /hello または /proxy_one を含む受信 API プロキシ呼び出しを処理しません。また、パスに /hello/xml を含む API では、json2xml プラグインがスキップされます。

環境変数値を使用した構成属性の設定

環境変数は、構成ファイル内のタグを使用して指定できます。指定した環境変数タグは、実際の環境変数値に置き換えられます。置換はメモリにのみ保存され、元の構成ファイルやキャッシュ ファイルには保存されません。

この例では、属性 keyTARGETS_SSL_CLIENT_KEY 環境変数の値に置き換えられます。

targets:
  - ssl:
      client:
        key: <E>TARGETS_SSL_CLIENT_KEY</E>
        cert: <E>TARGETS_SSL_CLIENT_CERT</E>
        passphrase: <E>TARGETS_SSL_CLIENT_PASSPHRASE</E>

この例では、<n> タグを使用して整数値を示します。正の整数のみがサポートされます。

edgemicro:
  port: <E><n>EMG_PORT</n></E>

この例では、<b> タグはブール値(true または false)を示すために使用されます。

quotas:
  useRedis: <E><b>EMG_USE_REDIS</b></E>