Apigee Edge のドキュメントを表示しています。
Apigee X のドキュメントに移動。 情報
Edge CIDR v. 3.3.x
このトピックでは、Edge CIDR を管理および構成する方法について説明します。
インターネット接続を利用できる場合の Edge Dataprep のアップグレード
このセクションでは、既存の Edge Dataprep インストールをアップグレードする方法について説明します。インターネットに接続せずに運用する場合は、インターネット接続なしで Edge Dataprep をインストールできますか?をご覧ください。
本番環境をアップグレードする前に、新しいバージョンで既存の構成をテストすることをおすすめします。
- 次の
npm
コマンドを実行して、Edge CIDR の最新バージョンにアップグレードします。npm upgrade edgemicro -g
Edge CIDR の特定のバージョンをインストールするには、インストール コマンドでバージョン番号を指定する必要があります。たとえば、バージョン 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 CIDR インスタンスのデフォルト構成ファイル
- 実行中のインスタンスの動的構成ファイル
このセクションでは、これらのファイルと、その変更について知っておくべきことについて説明します。
デフォルトのシステム構成ファイル
Edge Dataprep をインストールすると、デフォルトのシステム構成ファイルが次の場所に配置されます。
prefix/lib/node_modules/edgemicro/config/default.yaml
ここで、prefix は npm
接頭辞ディレクトリです。このディレクトリが見つからない場合は、
Edge CIDR のインストール場所をご覧ください。
システム構成ファイルを変更する場合は、Edge CIDR を再初期化、再構成、再起動する必要があります。
edgemicro initedgemicro configure [params]
edgemicro start [params]
新しく初期化された Edge CIDR インスタンスのデフォルト構成ファイル
edgemicro init
を実行すると、上記のシステム構成ファイル(default.yaml
)が ~/.edgemicro
ディレクトリに配置されます。
~/.edgemicro
で構成ファイルを変更する場合は、Edge CIDR を再構成して再起動する必要があります。
edgemicro stopedgemicro configure [params]
edgemicro start [params]
実行中のインスタンスの動的構成ファイル
edgemicro configure [params]
を実行すると、動的構成ファイルが ~/.edgemicro
に作成されます。ファイル名は org-env-config.yaml
のパターンになります。ここで、org と env は Apigee Edge の組織名と環境名です。このファイルを使用して構成を変更し、ダウンタイムなしで再読み込みできます。たとえば、プラグインを追加して構成した場合、以下で説明するように、ダウンタイムを発生させずに構成を再読み込みできます。
Edge CIDR が実行されている場合(ゼロ ダウンタイム オプション):
- Edge Dataprep の構成を再読み込みします。
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 VMs が停止している場合:
- Edge Dataprep を再起動します。
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 CIDR 構成リファレンスをご覧ください。
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 Dataprep の起動に必要な鍵とシークレットを必要とするコマンドライン インターフェース コマンドは、次の環境変数に格納できます。
EDGEMICRO_ORG
EDGEMICRO_ENV
EDGEMICRO_KEY
EDGEMICRO_SECRET
これらの変数の設定は省略可能です。設定すると、コマンドライン インターフェース(CLI)を使用して Edge Dataprep を構成して起動する際に、それらの値を指定する必要はありません。
Edge CIDR サーバーで SSL を構成する
Apigee Edge Dataprep での TLS の構成については、次の動画をご覧ください。
動画 | 説明 |
---|---|
上り(内向き)一方向 TLS を構成する | Apigee Edge VMs での TLS の構成について説明します。 この動画では、TLS の概要とその重要性について説明し、Edge CIDR での TLS の概要、ノースバウンド一方向 TLS の構成方法について説明します。 |
上り(内向き)双方向 TLS を構成する | これは、Apigee Edge Dataprep での TLS の構成に関する 2 番目の動画です。この動画では、ノースバウンド双方向 TLS を構成する方法について説明します。 |
下り方向の一方向 TLS と双方向 TLS を構成する | Apigee Edge VMs での TLS の構成に関する 3 番目の動画では、下り方向の一方向 TLS と双方向 TLS の構成方法について説明します。 |
SSL を使用するように CIDR サーバーを構成できます。たとえば、SSL が構成されている場合、次のように「https」プロトコルを使用して Edge CIDR を介して API を呼び出すことができます。
https://localhost:8000/myapi
CIDR を CIDR サーバーで構成するには、次の手順に従います。
- openssl ユーティリティまたは任意の方法を使用して、SSL 証明書と鍵を生成または取得します。
- Edge CIDR 構成ファイルに
edgemicro:ssl
属性を追加します。オプションの一覧については、以下の表をご覧ください。次に例を示します。
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 Dataprep を再起動します。編集した構成ファイル(デフォルト ファイルまたはランタイム構成ファイル)に応じて、構成の変更で説明されている手順を行います。
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 メソッド。たとえば、SSL を強制的にバージョン 3 にするには、SSLv3_method を使用します。 |
servername |
SNI(Server Name Indication)TLS 拡張のサーバー名。 |
requestCert |
双方向 SSL の場合は true、一方向 SSL の場合は false |
クライアント SSL/TLS オプションの使用
ターゲット エンドポイントに接続するときに、Edge CIDR を TLS または SSL クライアントとして構成できます。Dataprep の構成ファイルで、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 |
PFX 形式のクライアントの秘密鍵、証明書、CA 証明書を含む 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 プロキシのカスタマイズ
デフォルトでは、Apigee Edge にデプロイされたプロキシが Edge Dataprep によって OAuth2 認証に使用されます。このプロキシは、最初に edgemicro configure
を実行したときにデプロイされます。このプロキシのデフォルト構成を変更して、カスタム クレームのサポートを JSON Web Token(JWT)に追加し、トークンの有効期限を構成して、更新トークンを生成できます。詳しくは、GitHub の edgemicro-auth ページをご覧ください。
カスタム認証サービスの使用
デフォルトでは、Apigee Edge にデプロイされたプロキシが Edge Dataprep によって OAuth2 認証に使用されます。このプロキシは、最初に edgemicro configure
を実行したときにデプロイされます。デフォルトでは、このプロキシの URL は Edge CIDR 構成ファイルで次のように指定されています。
authUri: https://myorg-myenv.apigee.net/edgemicro-auth
独自のカスタム サービスを使用して認証を処理する場合は、サービスを指すように構成ファイルの authUri
値を変更します。たとえば、LDAP を使用して ID を確認するサービスがあるとします。
ログファイルの管理
Edge CIDR は、各リクエストとレスポンスに関する情報を記録します。ログファイルは、デバッグやトラブルシューティングに有用な情報を提供します。
ログファイルの保存場所
デフォルトでは、ログファイルは /var/tmp
に保存されます。
デフォルトのログファイル ディレクトリを変更する方法
ログファイルが保存されるディレクトリは、Edge CIDR 構成ファイルに指定されます。構成の変更もご覧ください。
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 CIDR 構成ファイルで構成できます。構成の変更もご覧ください。
構成可能な属性は次のとおりです。
- 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 CIDR は、ファイル権限レベルを 0600 に設定してアプリケーション ログファイル(api-log.log
)を生成します。この権限レベルでは、外部アプリケーションまたはユーザーはログファイルを読み取ることはできません。この厳格な権限レベルを緩和するには、logging:disableStrictLogFile
を true
に設定します。この属性が true
の場合、ログファイルは 0755 に設定されたファイル権限で作成されます。false
の場合、または属性が指定されていない場合、権限はデフォルトで 0600 になります。
v3.2.3 で追加されました。
次に例を示します。
edgemicro: logging: disableStrictLogFile: true
ログファイルの適切なメンテナンス方法
ログファイルのデータは時間の経過とともに蓄積するため、次の方法を採用することをおすすめします。
- ログファイルは非常に大きくなる可能性があるため、ログファイル ディレクトリに十分な容量があることを確認してください。ログファイルが保存される場所とデフォルトのログファイル ディレクトリを変更する方法をご覧ください。
- 少なくとも週に 1 回、ログファイルを削除するか、別のアーカイブ ディレクトリに移動します。
- ポリシーでログを削除する場合は、CLI コマンド
edgemicro log -c
を使用して古いログを削除(クリーンアップ)できます。
ログファイルの命名規則
各 Edge VMs インスタンスは、.log
という拡張子を持つログファイルを生成します。ログファイルの命名規則は次のとおりです。
edgemicro-HOST_NAME-INSTANCE_ID-api.log
次に例を示します。
edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log
ログファイルの内容について
v2.3.3 で追加
デフォルトでは、ロギング サービスでは、ダウンロードされたプロキシ、プロダクト、JSON Web Token(JWT)の JSON が省略されます。これらのオブジェクトをコンソールに出力するには、Edge Dataprep の起動時にコマンドライン フラグ DEBUG=*
を設定します。次に例を示します。
DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456
「api」ログファイルの内容
「api」ログファイルには、Edge CIDR を介したリクエストとレスポンスのフローに関する詳細情報が含まれます。「api」ログファイルの名前は次のようになります。
edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log
Edge Dataprep に対して行われたリクエストごとに、次の 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 CIDR がリッスンしているホストとポート番号。
- r - クライアント リクエスト送信元のリモートホストとポート。
- i - リクエスト ID。4 つのイベントエントリすべてでこの ID が共有されます。各リクエストには一意のリクエスト ID が割り当てられます。ログレコードをリクエスト ID に関連付けることで、ターゲットのレイテンシに関する貴重な分析情報を得ることができます。
- d - Edge CIDR がリクエストを受信してからの期間(ミリ秒)。上記の例では、リクエスト 0 に対するターゲットのレスポンスは 7 ミリ秒後に受信され(3 行目)、レスポンスはさらに 4 ミリ秒後にクライアントに送信されています(4 行目)。つまり、リクエスト レイテンシの合計は 11 ミリ秒で、このうち 7 ミリ秒がターゲットで、4 ミリ秒が Edge CIDR 自体で費やされています。
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 CIDR 自体にかかった時間を含む、API 呼び出しにかかった合計時間です。
- i - ログエントリの ID。4 つのイベント エントリすべてでこの ID が共有されます。
ログファイルのスケジュール
ログファイルは、rotate_interval 構成属性で指定された間隔でローテーションされます。ローテーション間隔が終了するまで、エントリは同じログファイルに追加され続けます。ただし、Edge CIDR は再起動されるたびに新しい UID を受け取り、この UID を持つ新しいログファイルのセットを作成します。ログファイルの適切なメンテナンス方法もご覧ください。
エラー メッセージ
一部のログエントリにエラー メッセージが含まれることがあります。エラーがどこで、なぜ発生したかを特定するには、Edge Migrate のエラー リファレンスをご覧ください。
Edge Dataprep の構成リファレンス
構成ファイルの場所
このセクションで説明する構成属性は、Edge CIDR 構成ファイル内にあります。構成の変更もご覧ください。
Edge_config 属性
これらの設定は、Edge CIDR インスタンスと Apigee Edge との間のインタラクションを構成するために使用します。
- bootstrap: (デフォルト: なし)Apigee Edge で実行されている Edge CIDR 固有のサービスを指す URL。Edge Dataprep は、このサービスを使用して Apigee Edge と通信します。公開鍵/秘密鍵のペアを生成するコマンド
edgemicro genkeys
を実行すると、この URL が返されます。詳細については、Edge CIDR の設定と構成をご覧ください。 - jwt_public_key: (デフォルト: なし)Apigee Edge にデプロイされている Edge Dataprep プロキシを指す URL。このプロキシは、署名付きアクセス トークンをクライアントに発行するための認証エンドポイントとして機能します。この URL は、プロキシをデプロイするコマンド edgemicro configure の実行時に返されます。詳細については、Edge CIDR の設定と構成をご覧ください。
- quotaUri: 組織にデプロイされた
edgemicro-auth
プロキシを介して割り当てを管理する場合は、この構成プロパティを設定します。このプロパティが設定されていない場合、割り当てエンドポイントはデフォルトで内部の Edge CIDR エンドポイントになります。edge_config: quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth
Edgemicro 属性
これらの設定により、Edge CIDR プロセスが構成されます。
- port: (デフォルト: 8000)Edge CIDR プロセスがリッスンするポート番号。
- max_connections: (デフォルト: -1)Edge CIDR が受信できる同時受信接続の最大数を指定します。この数を超えると、次のステータスが返されます。
res.statusCode = 429; // Too many requests
- max_connections_hard: (デフォルト: -1)接続をシャットダウンする前に Edge Dataprep が受信できる同時リクエストの最大数。この設定は、サービス拒否攻撃を阻止することを目的としています。通常、max_connections より大きい数に設定します。
-
logging:
-
level:(デフォルト: error)
- info - (推奨)Edge CIDR インスタンスを通過するすべてのリクエストとレスポンスをログに記録します。
- warn - 警告メッセージのみをログに記録します。
- error - エラー メッセージのみをログに記録します。
- debug - デバッグ メッセージを情報、警告、エラー メッセージとともにログに記録します。
- trace - エラーのトレース情報を、情報、警告、エラー メッセージとともにログに記録します。
- none - ログファイルを作成しません。
- dir: (デフォルト: /var/tmp)ログファイルが保存されるディレクトリ。
- stats_log_interval: (デフォルト: 60)統計レコードが API ログファイルに書き込まれる間隔(秒単位)。
- rotate_interval: (デフォルト: 24)ログファイルがローテーションされる間隔(時間単位)。
-
level:(デフォルト: error)
- plugins: プラグインは、Edge CIDR に機能を追加します。プラグインの開発について詳しくは、カスタム プラグインを開発するをご覧ください。
- dir: ./gateway ディレクトリから ./plugins ディレクトリへの相対パス、または絶対パス。
- シーケンス: Edge CIDR インスタンスに追加するプラグイン モジュールのリスト。モジュールはここで指定された順序で実行されます。
-
debug: Edge VMs プロセスにリモート デバッグを追加します。
- port: リッスンするポート番号。たとえば、このポートでリッスンするように IDE デバッガを設定します。
- args: デバッグ プロセスの引数。例:
args --nolazy
- config_change_poll_interval: (デフォルト: 600 秒)Edge Dataprep は、新しい構成を定期的に読み込み、変更があれば再読み込みを実行します。このポーリングにより、Edge で行われた変更(プロダクト、Microgateway 対応プロキシの変更など)と、ローカル構成ファイルに対する変更が取得されます。
- disable_config_poll_interval: (デフォルト: false)自動変更ポーリングをオフにするには、true に設定します。
- request_timeout: ターゲット リクエストのタイムアウトを設定します。タイムアウトは秒単位に設定されます。タイムアウトが発生すると、Edge CIDR は 504 ステータス コードを返します。(v2.4.x で追加)。
- keep_alive_timeout: このプロパティを使用すると、Edge CIDR のタイムアウト(ミリ秒単位)を設定できます。(デフォルト: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 CIDR)とターゲット サーバー間の接続が早期に閉じた場合の Edge CIDR の動作を制御できます。
値 説明 デフォルト on_target_response_abort
が指定されていない場合、デフォルトの動作として、エラーを表示せずにレスポンスが切り捨てられます。ログファイルには、targetResponse aborted
と 502 レスポンス コードとともに警告メッセージが表示されます。appendErrorToClientResponseBody
カスタムエラー TargetResponseAborted
がクライアントに返されます。ログファイルには、targetResponse aborted
と 502 レスポンス コードとともに警告メッセージが表示されます。また、エラーTargetResponseAborted
はメッセージTarget response ended prematurely.
とともにログに記録されます。abortClientRequest
Edge Dataprep はリクエストを中止し、ログファイルに警告( TargetResponseAborted
と 502 リクエスト ステータス コード)が書き込まれます。
例:
edgemicro: on_target_response_abort: appendErrorToClientResponseBody | abortClientRequest
ヘッダー属性
これらの設定は、特定の 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 CIDR でクライアント認証がどのように適用されるかが構成されます。
- allowNoAuthorization: (デフォルト: false)true に設定すると、API 呼び出しは Authorization ヘッダーをまったく持たずに Edge Dataprep を通過できます。Authorization ヘッダーを要求するには、これを false に設定します(デフォルト)。
- allowInvalidAuthorization: (デフォルト: false)true に設定すると、Authorization ヘッダーで渡されたトークンが無効または期限切れになっても、API 呼び出しの通過が許可されます。有効なトークンを要求するには、これを false に設定します(デフォルト)。
- authorization-header: (デフォルト: Authorization: Bearer)Edge CIDR にアクセス トークンを送信するために使用されるヘッダー。ターゲットが他の目的で Authorization ヘッダーを使用する必要がある場合は、デフォルトを変更できます。
- api-key-header: (デフォルト: x-api-key)API キーを Edge Dataprep に渡すために使用されるヘッダーまたはクエリ パラメータの名前。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 Dataprep インスタンスが処理する microgateway 対応プロキシをフィルタできます。Edge Dataprep は、起動すると、関連付けられている組織内のすべての 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 CIDR がダウンロードして処理する API プロダクトの数を制限します。ダウンロードされたプロダクトをフィルタするには、Edge CIDR の *.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 CIDR を構成した組織/環境の edgemicro_auth プロキシを選択します。
- [Develop] タップで、エディタで JavaCallout ポリシーを開きます。
- 属性名のカンマ区切りリストを含むキー
products.filter.attributes
を使用してカスタム属性を追加します。いずれかのカスタム属性名を含むプロダクトのみが Edge Dataprep に返されます。 - カスタム属性
products.filter.env.enable
をfalse
に設定すると、プロダクトが現在の環境で有効になっているかどうかを確認するチェックを無効にすることもできます。(デフォルトは true です)。 - (Private Cloud のみ)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 CIDR が分析データを Apigee に送信する頻度を制御します。
- bufferSize(省略可): 最も古いレコードの削除を開始する前に、バッファが保持できる分析レコードの最大数。デフォルト: 10000
- batchSize(省略可): Apigee に送信される分析レコードのバッチの最大サイズ。デフォルト: 500
- flushInterval(省略可): Apigee に送信される分析レコードのバッチの各フラッシュ間のミリ秒数。デフォルト: 5000
次に例を示します。
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 呼び出しの分離
Edge Analytics ダッシュボードに個別のプロキシとして表示されるように、特定の API パスを分離するように分析プラグインを構成できます。たとえば、実際の API プロキシ呼び出しと混同しないよう、ヘルスチェック API をダッシュボードで分離できます。アナリティクス ダッシュボードでは、分離されたプロキシは次の命名パターンに従います。
edgemicro_proxyname-health
次の図は、アナリティクス ダッシュボードで 2 つの分離されたプロキシ(edgemicro_hello-health
と edgemicro_mock-health
)を示しています。
これらのパラメータを使用して、アナリティクス ダッシュボードで相対パスと絶対パスを別々のプロキシとして分離します。
- relativePath(省略可): アナリティクス ダッシュボードで分離する相対パスを指定します。たとえば、
/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 VMs を設定する
Apigee Edge との通信に HTTP プロキシを使用する
バージョン 3.1.2 で追加されました。
Edge Dataprep と 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 CIDR がプロキシしないドメインのカンマ区切りリストを指定できます。これらの変数の詳細については、https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables をご覧ください。
- Edge Dataprep を再起動します。
ターゲット通信に HTTP プロキシを使用する
バージョン 3.1.2 で追加されました。
Edge Dataprep とバックエンド ターゲット間の通信に 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 CIDR は 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 CIDR は HTTP CONNECT メソッドを使用して、単一の TCP 接続で HTTP リクエストをトンネリングします。(後述するように、プロキシを構成する環境変数が TLS を有効にしている場合も同様です)。デフォルト:
- Edge Dataprep を再起動します。
Maven 対応プロキシでのワイルドカードの使用
edgemicro_*(Microgateway 対応)プロキシのベースパスで 1 つ以上の「*」ワイルドカードを使用できます。たとえば、ベースパスを /team/*/members にすると、新しいチームをサポートするために新しい API プロキシを作成しなくても、クライアントは https://[host]/team/blue/members と https://[host]/team/green/members を呼び出すことができます。/**/
はサポートされていないことに注意してください。
重要: Apigee では、ベースパスの最初の要素としてワイルドカード「*」を使用できません。たとえば、/*/
検索はサポートされていません。
JWT 鍵のローテーション
JWT を最初に生成した後、Edge で暗号化された KVM に保存されている公開鍵/秘密鍵のペアの変更が必要になることがあります。新しい鍵ペアを生成するこのプロセスは、鍵のローテーションと呼ばれます。
Edge Dataprep で 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 に格納されている情報を使用します。microgateway
という KVM は、最初に Edge Dataprep を設定(構成)したときに作成され、キーが入力されています。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 の値に関連付けられ、鍵のローテーションをサポートするために使用されます。この値は秘密鍵の kid と同じです。
-
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
ファイルに追加します。ここで、使用するマイクロゲートウェイを構成したのと同じ組織と環境を指定する必要があります。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 CIDR に返します。次の例では、各キーに一意の「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 CIDR インスタンスで使用可能になりました。トークンの署名からマイクロゲートウェイ インスタンスの更新までの遅延により、すべてのインスタンスが最新公開鍵を受け取るまで、最新の鍵で署名されたトークンは拒否されます。
複数の 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 組織内のすべてのプロキシが、名前の接頭辞「edgemicro_」で始まるすべてのプロキシをダウンロードします。このデフォルトを変更して、名前がパターンと一致するプロキシをダウンロードできます。
- 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 CIDR はこのプロダクト構成をサポートしています。
デバッグとトラブルシューティング
デバッガへの接続
Edge Dataprep は、node-inspector などのデバッガで実行できます。これは、カスタム プラグインのトラブルシューティングとデバッグに役立ちます。
- Edge Dataprep をデバッグモードで再起動します。これを行うには、
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 CIDR コードのステップ実行、ブレークポイントの設定、式の監視などを行えるようになりました。
デバッグモードに関連する標準の Node.js フラグを指定できます。たとえば、--nolazy
は非同期コードのデバッグに役立ちます。
ログファイルの確認
問題が発生した場合は、ログファイルで実行の詳細とエラー情報を確認してください。詳しくは、ログファイルの管理をご覧ください。
API キー セキュリティの使用
API キーは、Edge CIDR にリクエストを送信するクライアントを認証するシンプルなメカニズムです。API キーは、Edge CIDR 認証プロキシを含む Apigee Edge プロダクトからコンシューマ キー(クライアント ID とも呼ばれます)の値をコピーすることで取得できます。
鍵のキャッシュ保存
API キーは署名なしトークンと交換され、キャッシュに保存されます。キャッシュ保存を無効にするには、Edge CIDR への受信リクエストに 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 CIDR の保護をご覧ください。
アップストリーム レスポンス コードを有効にする
デフォルトでは、レスポンスが 200 ステータスでない場合、oauth
プラグインは 4xx エラー ステータス コードのみを返します。この動作は、エラーに応じて常に正確な 4xx または 5xx コードを返すように変更できます。
この機能を有効にするには、oauth.useUpstreamResponse: true
プロパティを Edge CIDR 構成に追加します。次に例を示します。
oauth: allowNoAuthorization: false allowInvalidAuthorization: false gracePeriod: 10 useUpstreamResponse: true
OAuth2 トークン セキュリティの使用
このセクションでは、OAuth2 アクセス トークンと更新トークンを取得する方法について説明します。アクセス トークンは、Microgateway を通じて安全な API 呼び出しを行うために使用されます。更新トークンは、新しいアクセス トークンを取得するために使用されます。
アクセス トークンの取得方法
このセクションでは、edgemicro-auth
プロキシを使用してアクセス トークンを取得する方法について説明します。
edgemicro token
CLI コマンドを使用してアクセス トークンを取得することもできます。CLI の詳細については、トークンの管理をご覧ください。
API 1: 本文パラメータとして認証情報を送信する
URL 内の組織名と環境名を置き換え、本文のパラメータ client_id と client_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 認証ヘッダーで認証情報を送信する
クライアント認証情報を基本認証ヘッダーとして送信し、grant_type
をフォーム パラメータとして送信します。このコマンドの形式については、RFC 6749: OAuth 2.0 認可フレームワークでも説明されています。
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 の
/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" }
永久モニタリング
構成ファイルのエンドポイントの指定
複数の Edge CIDR インスタンスを実行している場合は、それらの構成を 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 CIDR で使用される 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 Dataprep をスタンドアロン モードで実行する
Edge Dataprep は、Apigee Edge の依存関係から完全に切断して実行できます。スタンドアロン モードと呼ばれるこのシナリオでは、インターネット接続なしで Edge Dataprep を実行し、テストできます。
次の機能は Apigee Edge への接続を必要とするため、スタンドアロン モードでは動作しません。
- OAuth と API キー
- 割り当て
- 分析
一方、カスタム プラグインと Spike Arrest は、Apigee Edge への接続を必要としないため、正常に動作します。さらに、extauth
という新しいプラグインを使用すると、スタンドアロン モードで JWT を使用してマイクロゲートウェイへの API 呼び出しを認可できます。
ゲートウェイの構成と起動
Edge Dataprep をスタンドアロン モードで実行するには:
$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 は、構成ファイル名で使用した「組織」名です。
- $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 を検証します。次のセクションでは、JWT を取得し、エラーなしで API 呼び出しを許可します。
例: 認可トークンの取得
次の例は、Apigee Edge の Edge CIDR JWT エンドポイント(edgemicro-auth/jwkPublicKeys
)から JWT を取得する方法を示しています。このエンドポイントは、Edge CIDR の標準の設定と構成を行う際にデプロイされます。Apigee エンドポイントから JWT を取得するには、最初に Edge の標準設定を行い、インターネットに接続する必要があります。Apigee エンドポイントは例を示すことのみを目的にここで使用され、必須ではありません。必要に応じて、別の JWT トークン エンドポイントを使用することもできます。その場合は、そのエンドポイント用に提供されている API を使用して JWT を取得する必要があります。
次の手順では、edgemicro-auth/jwkPublicKeys
エンドポイントを使用してトークンを取得する方法について説明します。
edgemicro-auth
プロキシを Apigee Edge 上の組織/環境にデプロイするには、Edge CIDR の標準の設定と構成を行う必要があります。この手順を以前に実施している場合は、繰り返す必要はありません。- Edge Dataprep を Apigee Cloud にデプロイした場合は、このエンドポイントから JWT を取得できるように、インターネットに接続する必要があります。
-
Edge Dataprep を停止します。
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 Dataprep を再起動します。次に例を示します。
edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
-
認可エンドポイントから JWT トークンを取得します。
edgemicro-auth/jwkPublicKeys
エンドポイントを使用しているため、次の CLI コマンドを使用できます。
Edge Dataprep の JWT を生成するには、edgemicro token
コマンドまたは API を使用します。次に例を示します。
edgemicro token get -o your_org -e your_env \ -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy
ここで
- your_org は、以前に Edge CIDR を構成した 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":"" }
ローカル プロキシモードの使用
ローカル プロキシモードでは、Apigee Edge に Microgateway 対応プロキシをデプロイする必要はありません。代わりに、Microgateway を起動するときに、ローカル プロキシ名、ベースパス、ターゲット URL を指定して「ローカル プロキシ」を構成します。microgateway への API 呼び出しは、ローカル プロキシのターゲット URL に送信されます。その他の点では、ローカル プロキシモードの動作は、Edge CIDR の通常モードでの実行とまったく同じです。認証は、Spike Arrest や割り当ての適用、カスタム プラグインなどと同様に機能します。
ユースケースと例
ローカル プロキシモードは、1 つのプロキシのみを Edge CIDR インスタンスに関連付ける必要がある場合に便利です。たとえば、Edge CIDR をサイドカー プロキシとして Kubernetes に挿入し、Microgateway と Service がそれぞれ 1 つの Pod で実行され、Microgateway がコンパニオン サービスとの間のトラフィックを管理できます。次の図は、Edge microgateway が Kubernetes クラスタでサイドカー プロキシとして機能するこのアーキテクチャを示しています。各 microgateway インスタンスは、コンパニオン サービス上の 1 つのエンドポイントとのみ通信します。
このスタイルのアーキテクチャの利点は、Edge Migrate では、Kubernetes クラスタなどのコンテナ環境にデプロイされた個々のサービスに対して API 管理が提供されることです。
ローカル プロキシモードの構成
ローカル プロキシモードで動作するように Edge Dataprep を構成するには、次の操作を行います。
edgemicro init
を実行してローカル構成環境を設定します。この構成は、通常の Edge CIDR 構成とまったく同じです。Edge CIDR の構成もご覧ください。- Edge CIDR の一般的な設定手順と同様に、
edgemicro configure
を実行します。次に例を示します。edgemicro configure -o your_org -e your_env -u your_apigee_username
このコマンドは、edgemicro-auth ポリシーを Edge にデプロイし、Microgateway の起動に必要な鍵とシークレットを返します。詳しくは、Edge CIDR の構成をご覧ください。
- Apigee Edge で、次の必須構成要件を使用して API プロダクトを作成します(他のすべての構成は必要に応じて管理できます)。
- プロダクトに edgemicro-auth プロキシを追加する必要があります。このプロキシは、
edgemicro configure
の実行時に自動的にデプロイされました。 - リソースパスを指定する必要があります。プロダクトに
/**
パスを追加することをおすすめします。詳細については、リソースパスの動作を構成するをご覧ください。Edge ドキュメントの API プロダクトを作成するもご覧ください。
- プロダクトに edgemicro-auth プロキシを追加する必要があります。このプロキシは、
Apigee Edge で、デベロッパーを作成することも、必要に応じて既存のデベロッパーを使用することもできます。詳細については、Edge 管理 UI を使用したデベロッパーの追加をご覧ください。
- Apigee Edge で、デベロッパー アプリを作成します。作成した API プロダクトをアプリに追加する必要があります。詳細については、Edge 管理 UI でアプリを登録するをご覧ください。
- Edge Dataprep がインストールされているマシンで、次の環境変数の値を「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 の使用方法について説明します。Synchronizer は、Apigee Edge から構成データを取得してローカルの Redis データベースに書き込むことで、Edge microgteway の復元性を向上させるオプション機能です。Synchronizer インスタンスが動作していると、異なるノードで実行されている他の Edge CIDR インスタンスは、このデータベースから直接構成を取得できます。
Syncrhonizer 機能は現在、Redis 5.0.x で動作するようにサポートされています。
Synchronizer とは
Synchronizer は、Edge Migrate にある程度の復元力を提供します。これにより、Edge CIDR のすべてのインスタンスが同じ構成を使用し、インターネットに障害が発生しても、Edge CIDR インスタンスを正常に起動して実行できます。
デフォルトでは、Apigee Edge インスタンスが Apigee Edge と通信して、API プロキシや API プロダクトの構成などの構成データを取得して更新できる必要があります。 Edge とのインターネット接続が切断されても、最新の構成データがキャッシュに保存されるため、Microgateway インスタンスは引き続き機能します。ただし、新しい microgateway インスタンスは、明確な接続がないと起動できません。さらに、インターネットの中断により、1 つ以上の microgateway インスタンスが他のインスタンスと同期されていない構成情報で実行される可能性があります。
Edge Dataprep Synchronizer は、Edge CIDR インスタンスが API プロキシの起動と処理に必要な構成データを取得するための代替メカニズムを提供します。Apigee Edge の呼び出しから取得される構成データには、jwk_public_keys
呼び出し、jwt_public_key
呼び出し、ブートストラップ呼び出し、API プロダクト呼び出しなどがあります。Synchronizer により、異なるノードで実行されているすべての Edge CIDR インスタンスが正常に起動し、Edge CIDR と Apigee Edge 間のインターネット接続が中断しても同期状態を維持できます。
Synchronizer は、特別に構成された Edge CIDR のインスタンスです。その唯一の目的は、Apigee Edge をポーリングし(タイミングは構成可能)、構成データを取得し、ローカルの Redis データベースに書き込むことです。Synchronizer インスタンス自体は API プロキシ トラフィックを処理できません。異なるノードで実行されている Edge Migrate の他のインスタンスは、Apigee Edge ではなく Redis データベースから構成データを取得するように構成できます。すべてのマイクロゲートウェイ インスタンスは、ローカル データベースから構成データを pull するため、インターネットに障害が発生しても、API リクエストを起動して処理できます。
Synchronizer インスタンスの構成
Synchronizer として使用する Edge Dataprep インストールの 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 CIDR インスタンスを起動します。Apigee Edge のポーリングを開始し、ダウンロードした構成データを Redis データベースに保存します。
通常の Edge CIDR インスタンスの構成
Synchronizer を実行した状態で、API プロキシ トラフィックを処理する通常の microgateway インスタンスを実行するように追加の Edge CIDR ノードを構成できます。ただし、これらのインスタンスは、構成データを Apigee Edge ではなく Redis データベースから取得するように構成します。
次の構成を、追加の Edge CIDR ノードの org-env/config.yaml
ファイルに追加します。synchronizerMode
プロパティが 0
に設定されていることに注意してください。このプロパティは、API プロキシ トラフィックを処理する通常の Edge CIDR インスタンスとして動作するインスタンスを設定し、インスタンスは 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 CIDR は標準モードで動作します。 1 の場合、Synchronizer として動作するように Edge CIDR インスタンスを起動します。このモードでは、インスタンスは Apigee Edge から構成データを pull し、ローカルの Redis データベースに保存します。このインスタンスは API プロキシ リクエストを処理できません。このインスタンスは、Apigee Edge をポーリングして構成データを確認し、ローカル データベースに書き込むことのみを目的としています。次に、他の microgateway インスタンスがデータベースから読み取るように構成する必要があります。 |
edge_config.redisBasedConfigCache |
true または false | true の場合、Edge CIDR インスタンスは、Apigee Edge ではなく Redis データベースから構成データを取得します。Redis データベースは、Synchronizer が書き込み用に構成されているデータベースと同じである必要があります。Redis データベースが使用できない場合、またはデータベースが空の場合、Microgateway は既存の cache-config.yaml ファイルで構成を検索します。false(デフォルト)の場合、Edge CIDR インスタンスは通常どおり Apigee Edge から構成データを取得します。 |
edgemicro.config_change_poll_interval |
時間間隔(秒) | Synchronizer が Apigee Edge からデータを pull するポーリング間隔を指定します。 |
プラグインの除外 URL の設定
指定した 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>