Apigee Edge のドキュメントを表示しています。
Apigee X のドキュメントをご覧ください。
Edge Microgateway v 3.3.x
このトピックでは、Edge Microgateway を管理および構成する方法について説明します。
インターネット接続がある場合の Edge Microgateway のアップグレード
このセクションでは、Edge Microgateway の既存のインストールをアップグレードする方法について説明します。インターネットに接続せずに動作している場合は、インターネットに接続せずに Edge Microgateway をインストールすることはできますか?をご覧ください。
本番環境をアップグレードする前に、新しいバージョンで既存の構成をテストすることをおすすめします。
- 次の
npm
コマンドを実行して、Edge Edge の最新バージョンにアップグレードします。npm upgrade edgemicro -g
特定のバージョンの Edge Microgateway をインストールするには、インストール コマンドでバージョン番号を指定する必要があります。たとえば、バージョン 3.2.3 にインストールするには、次のコマンドを使用します。
npm install edgemicro@3.2.3 -g
- バージョン番号を確認します。たとえば、バージョン 3.2.3 をインストールした場合:
edgemicro --version current nodejs version is v12.5.0 current edgemicro version is 3.2.3
- 最後に、edgemicro-auth プロキシの最新バージョンにアップグレードします。
edgemicro upgradeauth -o $ORG -e $ENV -u $USERNAME
構成の変更
知っておくべき構成ファイルは次のとおりです。
- デフォルトのシステム構成ファイル
- 新しく初期化された Edge Microgateway インスタンスのデフォルト構成ファイル
- インスタンスを実行するための動的構成ファイル
このセクションでは、これらのファイルと変更について知っておく必要があります。
デフォルトのシステム構成ファイル
Edge Microgateway をインストールすると、デフォルトのシステム構成ファイルが次の場所に配置されます。
prefix/lib/node_modules/edgemicro/config/default.yaml
ここで、prefix は npm
プレフィックス ディレクトリです。このディレクトリが見つからない場合は、
Edge Microgateway がインストールされている場所をご覧ください。
システム構成ファイルを変更する場合は、Edge Microgateway を再初期化、再構成、再起動する必要があります。
edgemicro initedgemicro configure [params]
edgemicro start [params]
新しく初期化された Edge Microgateway インスタンスのデフォルトの構成ファイル
edgemicro init
を実行すると、上記のシステム構成ファイル(default.yaml
)が ~/.edgemicro
ディレクトリに配置されます。
~/.edgemicro
の構成ファイルを変更する場合は、Edge Microgateway を再構成して再起動する必要があります。
edgemicro stopedgemicro configure [params]
edgemicro start [params]
インスタンスを実行するための動的構成ファイル
edgemicro configure [params]
を実行すると、動的構成ファイルが ~/.edgemicro
に作成されます。ファイル名は org-env-config.yaml
というパターンになります。ここで、org と env は Apigee Edge の組織名と環境名です。このファイルを使用して構成を変更し、ダウンタイムなしで再読み込みできます。たとえば、プラグインを追加して構成する場合は、以下で説明するように、ダウンタイムを発生させずに構成を再読み込みできます。
Edge Microgateway が実行されている場合(ゼロ ダウンタイム オプション):
- 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 が停止している場合:
- 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 を構成する方法について説明します。 |
SSL を使用するように Microgateway サーバーを構成できます。たとえば、SSL が構成されている場合は、次のように「https://」プロトコルを使用して Edge Microgateway を介して API を呼び出すことができます。
https://localhost:8000/myapi
Microgateway サーバーで SSL を構成する手順は次のとおりです。
- openssl ユーティリティまたは任意の方法を使用して、SSL 証明書と鍵を生成または取得します。
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
- 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 |
PFX 形式のクライアントの秘密鍵、証明書、CA 証明書を含む pfx ファイルのパス。 |
passphrase |
秘密鍵または PFX のパスフレーズを含む文字列。 |
ca |
信頼できる証明書のリスト(PEM 形式)を含むファイルのパス。 |
ciphers |
使用する暗号を記述する文字列。「:」で区切ります。 |
rejectUnauthorized |
true の場合、サーバー証明書は指定された CA のリストに対して検証されます。検証で不合格になると、エラーが返されます。 |
secureProtocol |
使用する SSL メソッド。たとえば、SSLv3_method を使用して SSL をバージョン 3 に強制します。 |
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 設定を適用する場合は、構成の最初のホストを「empty」として指定する必要があります。これにより、ユニバーサル リクエストが有効になり、任意のホストを任意の順序で指定できます。この例では、設定が複数の特定のホストに適用されます。
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 |
PFX 形式のクライアントの秘密鍵、証明書、CA 証明書を含む pfx ファイルのパス。 |
key |
ca.key ファイルのパス(PEM 形式)。 |
passphrase |
秘密鍵または PFX のパスフレーズを含む文字列。 |
cert |
ca.cert ファイルのパス(PEM 形式)。 |
ca |
信頼できる証明書のリスト(PEM 形式)を含むファイルのパス。 |
ciphers |
使用する暗号を記述する文字列。「:」で区切ります。 |
rejectUnauthorized |
true の場合、サーバー証明書は指定された CA のリストに対して検証されます。検証で不合格になると、エラーが返されます。 |
secureProtocol |
使用する SSL メソッド。たとえば、SSLv3_method を使用して SSL をバージョン 3 に強制します。 |
servername |
SNI(Server Name Indication)TLS 拡張のサーバー名。 |
edgemicro-auth プロキシのカスタマイズ
デフォルトでは、Edge Microgateway は Apigee Edge にデプロイされたプロキシを使用して OAuth2 認証を行います。このプロキシは、最初に edgemicro configure
を実行したときにデプロイされます。このプロキシのデフォルト構成を変更して、JSON ウェブトークン(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:disableStrictLogFile
を true
に設定します。この属性が 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 呼び出しにかかった合計時間です。ターゲット API と Edge Edge 自体の所要時間の合計も含まれます。
- 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 固有のサービスを指す 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 より大きい値に設定します。
-
ロギング:
-
level:(デフォルト: error)
- info - (推奨)Edge Microgateway インスタンスを通過するすべてのリクエストとレスポンスをログに記録します。
- warn - 警告メッセージのみを記録します。
- error - エラー メッセージのみが記録されます。
- debug - デバッグ メッセージと情報、警告、エラー メッセージをログに記録します。
- trace - エラーのトレース情報、情報メッセージ、警告メッセージ、エラー メッセージをログに記録します。
- none - ログファイルを作成しません。
- dir:(デフォルト: /var/tmp)ログファイルが格納されるディレクトリ。
- stats_log_interval:(デフォルト: 60)統計情報レコードが API ログファイルに書き込まれる間隔(秒)。
- rotate_interval:(デフォルト: 24)ログファイルがローテーションされる間隔(時間)。
-
level:(デフォルト: error)
- プラグイン: プラグインは Edge Microgateway に機能を追加します。プラグインの開発の詳細については、カスタム プラグインを開発するをご覧ください。
- 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
ヘッダー属性
これらの設定により、特定の HTTP ヘッダーの処理方法が構成されます。
- x-forwarded-for:(デフォルト: true)x-forwarded-for ヘッダーがターゲットに渡されないようにするには、false に設定します。x 転送ヘッダーがリクエストに含まれている場合、その値は 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)経由ヘッダーがターゲットに渡されないようにするには、false に設定します。
OAuth 属性
これらの設定は、Edge Microgateway によるクライアント認証の適用方法を構成します。
- allowNoAuthorization:(デフォルト: false)True に設定した場合、API 呼び出しは Authorization ヘッダーを一切使用せずに 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 -- すべての API で x-api-key ヘッダー(またはカスタム ロケーション)を API キーとともに持つ必要があります。下位互換性を維持しながら、API キーのセキュリティ モデルのみを許可できます。(2.4.x で追加)
- gracePeriod -- このパラメータを使用すると、システム クロックと、JWT 認証トークンで指定された Not After(nbf)または Issued At(iat)時刻との間のわずかな差異に起因するエラーを防ぐことができます。このパラメータには、このような不一致を許可する秒数を設定します。(2.5.7 で追加)
プラグイン固有の属性
各プラグインの構成可能な属性について詳しくは、プラグインの使用をご覧ください。
プロキシのフィルタリング
Edge Microgateway インスタンスが処理する Microgateway 対応プロキシをフィルタできます。Edge Microgateway を起動すると、関連付けられている組織内のすべての Microgateway 対応プロキシがダウンロードされます。Microgateway が処理するプロキシを制限するには、次の構成を使用します。たとえば、次のような構成の場合、Microgateway が処理するプロキシは edgemicro_proxy-1
、edgemicro_proxy-2
、edgemicro_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":[ ] } ] }
カスタム属性による商品のフィルタリング
カスタム属性に基づいて商品をフィルタリングするには:
- Edge UI で、Edge Microgateway を構成した組織/環境の edgemicro_auth プロキシを選択します。
- [Develop] タップで、エディタ内の Java コールアウト ポリシーを開きます。
- キー
products.filter.attributes
を含むカスタム属性を追加し、属性名のカンマ区切りリストを指定します。カスタム属性名のいずれかを含む商品のみが Edge Microgateway に返されます。 - 必要に応じて、カスタム属性
products.filter.env.enable
をfalse
に設定することで、現在の環境でプロダクトが有効になっているかどうかを確認するチェックを無効にできます。(デフォルトは true)。 - (プライベート クラウドのみ)Edge for Private Cloud を使用している場合は、プロパティ
org.noncps
をtrue
に設定して、CPS 以外の環境のプロダクトを pull します。
次に例を示します。
<?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>
分析の push 頻度の構成
次の構成パラメータを使用して、Edge Microgateway が Apigee に分析データを送信する頻度を制御します。
- bufferSize(省略可): 最も古いレコードの削除を開始するまでに、バッファで保持できる分析レコードの最大数。デフォルト: 10000
- batchSize(省略可): Apigee に送信される分析レコードのバッチの最大サイズ。デフォルト: 500
- flushInterval(省略可): Apigee に送信される分析レコードのバッチのフラッシュ間隔(ミリ秒単位)。デフォルト: 5,000
次に例を示します。
analytics: bufferSize: 15000 batchSize: 1000 flushInterval: 6000
分析データのマスキング
次の構成を使用すると、リクエストパスの情報が Edge Analytics に表示されません。リクエスト URI やリクエストパスをマスクするように、Microgateway 構成に次のコードを追加します。URI は、リクエストのホスト名とパスの部分から構成されます。
analytics: mask_request_uri: 'string_to_mask' mask_request_path: 'string_to_mask'
Edge Analytics での API 呼び出しの分離
特定の API パスを分離し、Edge Analytics ダッシュボードに別のプロキシとして表示されるように、分析プラグインを構成できます。たとえば、ヘルスチェック API を実際の API プロキシ呼び出しと混同しないように、ダッシュボードで分離できます。アナリティクス ダッシュボードで、分離されたプロキシは次の命名パターンに従います。
edgemicro_proxyname-health
次の図では、アナリティクス ダッシュボードに 2 つの分離されたプロキシ(edgemicro_hello-health
と edgemicro_mock-health
)を示します。
アナリティクス ダッシュボードの相対パスと絶対パスを別々のプロキシとして分離するには、次のパラメータを使用します。
- 相対パス(省略可): アナリティクス ダッシュボードで分離する相対パスを指定します。たとえば、
/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 プロキシを使用する手順は次のとおりです。
- 環境変数
HTTP_PROXY
、HTTPS_PROXY
、NO_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 をご覧ください。
- Edge Microgateway を再起動します。
ターゲット通信に HTTP プロキシを使用する
バージョン 3.1.2 で追加されました。
Edge Microgateway とバックエンド ターゲット間の通信に HTTP プロキシを使用する手順は次のとおりです。
- 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 プロキシをバイパスするターゲット ホスト URL を 1 つ以上カンマ区切りで指定します。このプロパティが設定されていない場合は、NO_PROXY 環境変数を使用して、バイパスするターゲット URL を指定します。
- enabled: true かつ
proxy.url
が設定されている場合、HTTP プロキシにproxy.url
値が使用されます。true に設定されていて、proxy.url
が設定されていない場合は、Apigee Edge との通信に HTTP プロキシを使用するで説明されているように、HTTP プロキシ環境変数HTTP_PROXY
とHTTPS_PROXY
で指定されたプロキシを使用します。
例:
edgemicro: proxy: tunnel: true url: 'http://localhost:3786' bypass: 'localhost','localhost:8080' # target hosts to bypass the proxy. enabled: true
- tunnel:(省略可)true の場合、Edge Microgateway は HTTP CONNECT メソッドを使用して、単一の TCP 接続で HTTP リクエストをトンネリングします。(このプロキシを構成するための環境変数が TLS 対応かどうかについては、後述のとおりです)。デフォルト:
- Edge Microgateway を再起動します。
Microgateway 対応プロキシでのワイルドカードの使用
edgemicro_*(Microgateway 対応)プロキシのベースパスに 1 つ以上の「*」ワイルドカードを使用できます。たとえば、/team/*/members のベースパスを使用すると、クライアントは新しいチームをサポートするために新しい API プロキシを作成しなくても、https://[host]/team/blue/members と https://[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 の値に関連付けられており、鍵のローテーションのサポートに使用されます。この値は、秘密鍵の子と同じです。
-
public_key1 - 最新の(最後に作成された)公開鍵。
鍵のローテーションを行うと、既存の鍵の値がマップで置き換えられ、古い公開鍵を保持するために新しい鍵が追加されます。次に例を示します。
-
public_key2_kid - 古い公開鍵 ID。この鍵は public_key2 の値に関連付けられており、鍵のローテーションのサポートに使用されます。
-
public_key2 - 古い公開鍵。
検証用に提示された JWT は、新しい公開鍵を使用して検証されます。検証で不合格だった場合は、JWT が期限切れになるまで(たとえば、token_expiry* の間隔で、デフォルトで 30 分)古い公開鍵が使用されます。このように、API トラフィックを直ちに中断することなく、鍵を「ローテーション」できます。
鍵のローテーション方法
このセクションでは、鍵のローテーションを行う方法について説明します。
- KVM をアップグレードするには、
edgemicro upgradekvm
コマンドを使用します。このコマンドの実行について詳しくは、KVM のアップグレードをご覧ください。この手順は 1 度だけ行います。 - edgemicro-oauth プロキシをアップグレードするには、
edgemicro upgradeauth
コマンドを使用します。このコマンドの詳細については、 edgemicro-auth プロキシのアップグレードをご覧ください。この手順は 1 度だけ行います。 ~/.edgemicro/org-env-config.yaml
ファイルに次の行を追加します。このファイルでは、使用する Microgateway を構成したのと同じ組織と環境を指定する必要があります。jwk_public_keys: 'https://$ORG-$ENV.apigee.net/edgemicro-auth/jwkPublicKeys'
鍵のローテーション コマンドを実行して鍵をローテーションします。このコマンドの詳細については、鍵のローテーションをご覧ください。
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" } ] }
「前」の遅延を構成する
バージョン 3.1.5 以前では、rotatekey
コマンドで生成された新しい秘密鍵はすぐに有効になり、生成された新しいトークンは新しい秘密鍵で署名されていました。ただし、Microgateway 構成が更新されると、10 分ごとに(デフォルトでは)新しい公開鍵が Edge Microgateway インスタンスで利用可能になります。トークン署名とマイクロゲートウェイ インスタンスの更新の間の遅延のため、最新の鍵で署名されたトークンは、すべてのインスタンスが最新の公開鍵を受け取るまで拒否されます。
複数のマイクロゲートウェイ インスタンスが存在する場合、トークンの検証がすべてのインスタンスで更新され、別のインスタンスでは失敗するため、公開鍵ラグがステータス 403 で断続的なランタイム エラーを引き起こすことがあります。
バージョン 3.1.6 以降では、rotatekey
コマンドで新しいフラグを指定すると、新しい秘密鍵が有効になるまでに遅延を指定できます。これにより、すべてのマイクロゲートウェイ インスタンスが更新され、新しい公開鍵を受け取るための時間を確保できます。新しいフラグ --nbf
は「not before」を表します。
このフラグには、遅延する分単位の整数値を指定します。
次の例では、遅延が 15 分に設定されています。
edgemicro rotatekey -o docs -e test \ -k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \ -s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47 \ --nbf 15
遅延は config_change_poll_internal
構成の設定(デフォルトでは 10 分)より長く設定することをおすすめします。edgemicro 属性もご覧ください。
ダウンロードしたプロキシのフィルタリング
デフォルトでは、Edge Microgateway は、名前に接頭辞「edgemicro_」で始まる Edge 組織内のすべてのプロキシをダウンロードします。このデフォルトを変更して、名前がパターンに一致するプロキシをダウンロードできます。
- Edge Micro 構成ファイル
~/.edgemicro/org-env-config.yaml
を開きます。 - 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 などのデバッガで実行できます。これは、カスタム プラグインのトラブルシューティングやデバッグで役立ちます。
- 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
- デバッガを起動し、デバッグ プロセスのポート番号をリッスンするように設定します。
- これで、Edge Microgateway コードのステップ実行、ブレークポイントの設定、ウォッチ式の設定などを行えるようになりました。
デバッグモードに関連する標準の Node.js フラグを指定できます。たとえば、--nolazy
は非同期コードのデバッグに役立ちます。
ログファイルを確認する
問題が発生した場合は、ログファイルで詳細とエラー情報を確認してください。詳しくは、ログファイルの管理をご覧ください。
API キーのセキュリティを使用する
API キーは、Edge Microgateway にリクエストを行うクライアントを認証するシンプルなメカニズムを提供します。API キーを取得するには、Edge Microgateway 認証プロキシを含む Apigee Edge プロダクトからコンシューマ キー(クライアント ID とも呼ばれます)の値をコピーします。
鍵のキャッシュ保存
API キーは署名なしトークンと交換され、キャッシュに保存されます。キャッシュを無効にするには、Edge バックエンドへの受信リクエストに 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 の組織名と環境名を実際の ID で置き換え、Apigee Edge のデベロッパー アプリから取得したコンシューマ ID とコンシューマ シークレットの値を client_id と client_secret の本文パラメータに置き換えます。
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 Auth ヘッダーで認証情報を送信する
クライアント認証情報を Basic 認証ヘッダーとして、grant_type
をフォーム パラメータとして送信します。このコマンド フォームについては、RFC 6749: 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
権限付与タイプで行う必要があります。手順は次のとおりです。
/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" }
- 更新トークンを使用して新しい API にアクセスし、同じ 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 Dataprep には、forever.json ファイルがあり、これを使用して Edge Microgateway を再起動する回数と間隔を制御できます。このファイルでは、forever-monitor と呼ばれる Forever サービスを構成します。このサービスはプログラムで Forever を管理します。
forever.json ファイルは Edge Microgateway のルート インストール ディレクトリにあります。 Edge Microgateway がインストールされている場所をご覧ください。構成オプションの詳細については、永久モニタリングのドキュメントをご覧ください。
edgemicro forever
コマンドには、forever.json
ファイルの場所(-f
フラグ)を指定し、Forever モニタリング プロセス(-a
フラグ)を開始または停止できるフラグが含まれます。次に例を示します。
edgemicro forever -f ~/mydir/forever.json -a start
詳細については、CLI リファレンスの永久モニタリングをご覧ください。
構成ファイルのエンドポイントの指定
複数の 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 アルゴリズムを使用して送信前にデータをバッファします。nodelay
を true
に設定すると、この動作が無効になります(データは 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 キー
- 割り当て
- アナリティクス
一方、カスタム プラグインとスパイク停止は Apigee Edge への接続を必要としないため、正常に動作します。また、extauth
という新しいプラグインを使用すると、スタンドアロン モードで JWT を使用してマイクロゲートウェイへの API 呼び出しを承認できます。
ゲートウェイの構成と起動
Edge Microgateway をスタンドアロン モードで実行するには:
- 構成ファイル
$HOME/.edgemicro/$ORG
を作成します。-
$ENV-config.yaml次に例を示します。
vi $HOME/.edgemicro/foo-bar-config.yaml
- 次のコードをファイルに貼り付けます。
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
- 次の環境変数を値「1」でエクスポートします。
export EDGEMICRO_LOCAL=1
- 次の
start
コマンドを実行します。ここで、ローカル プロキシをインスタンス化するための値を指定します。edgemicro start -o $ORG -e $ENV -a $LOCAL_PROXY_NAME \ -v $LOCAL_PROXY_VERSION -t $TARGET_URL -b $BASE_PATH
ここで
- $ORG は、構成ファイル名で使用した「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 /
- 構成をテストします。
curl http://localhost:8000/echo { "error" : "missing_authorization" }
extauth
プラグインはfoo-bar-config.yaml
ファイルに含まれているため、「missing_authorization」エラーが発生します。このプラグインは、API 呼び出しの Authorization ヘッダーに存在する必要がある JWT を検証します。次のセクションでは、API 呼び出しをエラーなしで通過させる JWT を取得します。
例: 認証トークンの取得
次の例は、Apigee Edge(edgemicro-auth/jwkPublicKeys
)の Edge Microgateway JWT エンドポイントから JWT を取得する方法を示しています。このエンドポイントは、Edge Microgateway の標準設定と構成を実行したときにデプロイされます。Apigee エンドポイントから JWT を取得するには、まず標準の Edge Microgateway を設定してから、インターネットに接続する必要があります。ここで Apigee エンドポイントを例として紹介します。これは必須ではありません。必要に応じて、別の JWT トークン エンドポイントを使用することもできます。これを行う場合は、そのエンドポイントに提供されている API を使用して JWT を取得する必要があります。
次の手順では、edgemicro-auth/jwkPublicKeys
エンドポイントを使用してトークンを取得する方法について説明します。
- Apigee Edge で組織/環境に
edgemicro-auth
プロキシをデプロイするには、Edge Microgateway の標準設定と構成を実行する必要があります。この手順をすでに完了している場合は、繰り返す必要はありません。 - Edge Microgateway を Apigee Cloud にデプロイした場合は、このエンドポイントから JWT を取得できるようにインターネットに接続する必要があります。
-
Edge Microgateway を停止します。
edgemicro stop
- 前に作成した構成ファイル(
$HOME/.edgemicro
/org-env-config.yaml
)で、extauth:publickey_url
属性に Apigee Edge 組織または環境のedgemicro-auth/jwkPublicKeys
エンドポイントを指定します。例:extauth: publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'
-
前と同様に、構成ファイル名に使用した組織または環境の名前を使用して Edge Microgateway を再起動します。次に例を示します。
edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
-
認可エンドポイントから JWT トークンを取得します。
edgemicro-auth/jwkPublicKeys
エンドポイントを使用しているため、次の CLI コマンドを使用できます。
edgemicro token
コマンドまたは API を使用して、Edge Microgateway の JWT を生成できます。次に例を示します。
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 対応プロキシをデプロイする必要はありません。代わりに、Microgateway を起動する際に、ローカル プロキシ名、ベースパス、ターゲット URL を指定して「ローカル プロキシ」を構成します。Microgateway に対する API 呼び出しはローカル プロキシのターゲット URL に送信されます。それ以外の点では、ローカル プロキシモードは通常の動作で Edge Microgateway を実行する場合とまったく同じように動作します。認証は、スパイク停止と割り当ての適用、カスタム プラグインなどと同様に機能します。
ユースケースと例
ローカル プロキシモードは、1 つのプロキシを Edge Microgateway インスタンスに関連付ける必要がある場合に役立ちます。たとえば、Edge Microgateway をサイドカー プロキシとして Kubernetes に挿入できます。この場合、microgateway と Service がそれぞれ単一の Pod で実行され、Microgateway がコンパニオン サービス間のトラフィックを管理します。次の図は、Edge Microgateway が Kubernetes クラスタ内のサイドカー プロキシとして機能するアーキテクチャを示しています。各 Microgateway インスタンスは、コンパニオン サービスの 1 つのエンドポイントとのみ通信します。
このタイプのアーキテクチャの利点は、Edge Microgateway がコンテナ クラスタ(Kubernetes クラスタなど)にデプロイされた個々のサービスの API 管理を提供していることです。
ローカル プロキシモードの構成
ローカル プロキシモードで実行するように Edge Microgateway を構成するには、次の手順を行います。
edgemicro init
を実行して、EdgeEdge の標準設定と同じようにローカル構成環境を設定します。Edge Microgateway の構成もご覧ください。- 一般的な Edge Microgateway 設定手順と同様に、
edgemicro configure
を実行します。例:edgemicro configure -o your_org -e your_env -u your_apigee_username
このコマンドは、Edge に edgemicro-auth ポリシーをデプロイし、Microgateway の起動に必要な鍵とシークレットを返します。詳しくは、Edge Microgateway の構成をご覧ください。
- Apigee Edge で、次の必須構成要件を使用して API プロダクトを作成します。その他の構成はすべて必要に応じて管理できます。
- プロダクトに edgemicro-auth プロキシを追加する必要があります。このプロキシは
edgemicro configure
の実行時に自動的にデプロイされています。 - リソースパスを指定する必要があります。Apigee では、このパスをプロダクトに追加することをおすすめします。
/**
詳細については、リソースパスの動作を構成するをご覧ください。Edge ドキュメントの API プロダクトを作成するもご覧ください。
- プロダクトに edgemicro-auth プロキシを追加する必要があります。このプロキシは
Apigee Edge でデベロッパーを作成するか、必要に応じて既存のデベロッパーを使用することもできます。詳細については、Edge 管理 UI を使用したデベロッパーの追加をご覧ください。
- Apigee Edge でデベロッパー アプリを作成します。作成した API プロダクトをアプリに追加する必要があります。詳しくは、Edge 管理 UI でアプリを登録するをご覧ください。
- Edge Microgateway がインストールされているマシンで、値「1」の次の環境変数をエクスポートします。
export EDGEMICRO_LOCAL_PROXY=1
- 次の
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 を使用して Apigee Edge から構成データを取得してローカルの Redis データベースに書き込むことで、Edge Microgteway の復元力を高めるオプション機能を使用する方法について説明します。Synchronizer インスタンスが実行されている場合、異なるノードで実行されている他の Edge Microgateway インスタンスは、このデータベースから直接構成を取得できます。
現在、syncrhonizer 機能は Redis 5.0.x でサポートされています。
シンクロナイザーとは何ですか。
Synchronizer は、Edge Microgateway のレベルの復元力を提供します。これにより、Edge Microgateway のすべてのインスタンスが同じ構成を使用するようになり、インターネットの障害が発生した場合でも Edge Microgateway インスタンスが正常に起動して実行できます。
デフォルトでは、Edge Microgateway インスタンスは、Apigee Edge と通信して API プロキシや API プロダクト構成などの構成データを取得、更新できる必要があります。Edge とのインターネット接続が切断された場合でも、最新の構成データがキャッシュされるため、Microgateway インスタンスは機能し続けます。ただし、新しいマイクロゲートウェイ インスタンスは、明確な接続がなければ起動できません。さらに、インターネットの中断により、1 つ以上のマイクロゲートウェイ インスタンスが他のインスタンスと同期しない構成情報を使用して実行される可能性があります。
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 インスタンスはローカル データベースから構成データを pull するため、インターネットの障害が発生した場合でも 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 の使用をサポートするために、次の構成プロパティが追加されました。
属性 | 値 | 説明 |
---|---|---|
edge_config.synchronizerMode |
0 または 1 | 0(デフォルト)の場合、Edge Microgateway は標準モードで動作します。 1 の場合、Edge Microgateway インスタンスを起動して、シンクロナイザとして動作します。このモードでは、インスタンスが Apigee Edge から構成データを pull し、ローカル Redis データベースに保存します。このインスタンスは API プロキシ リクエストを処理できません。目的は Apigee Edge をポーリングして構成データを探し、ローカル データベースに書き込むことだけです。さらに、他のマイクロゲートウェイ インスタンスをデータベースから読み取るように構成する必要があります。 |
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 を構成する
Microgateway は、指定した URL のプラグインの処理をスキップするように構成できます。これらの「除外」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
プラグインはスキップされます。
環境変数値を使用して構成属性を設定する
構成ファイル内のタグを使用して環境変数を指定できます。指定した環境変数タグが、実際の環境変数値に置き換えられます。置換はメモリにのみ保存され、元の構成ファイルまたはキャッシュ ファイルには保存されません。
この例では、属性 key
が TARGETS_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>