Edge Microgateway の操作および構成リファレンス

Edge Microgateway v. 2.5.x

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

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

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

    Edge Microgateway の特定のバージョンにアップグレードするには、アップグレード コマンドでバージョン番号を指定する必要があります。バージョン番号を指定しない場合、最新バージョンがインストールされます。 たとえば、バージョン 2.5.26 にアップグレードするには、次のコマンドを使用します。

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

構成の変更

次の構成ファイルについて知っておく必要があります。

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

このセクションでは、これらのファイルと、その変更について知る必要があることについて説明します。

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

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

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

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

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

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

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

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

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

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

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

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

Edge Microgateway が実行中の場合（ゼロダウンタイム オプション）:

  1. Edge Microgateway 構成を再読み込みします。 
    edgemicro reload -o org_name -e env_name -k key -s secret

    ここで

    • org_name は Edge 組織名です（組織管理者である必要があります）。
    • env_name は組織の環境です（「test」や「prod」など）。
    • key は、configure コマンドによって以前返されたキーです。
    • secret は、configure コマンドによって以前返されたキーです。

    例

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

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

  1. Edge Microgateway を再起動します。 
    edgemicro start -o org_name -e env_name -k key -s secret

    ここで

    • org_name は Edge 組織名です（組織管理者である必要があります）。
    • env_name は組織の環境です（「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 の構成

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

    https://localhost:8000/myapi

Microgateway サーバーで SSL を構成するには、次の手順に従います。

  1. openssl ユーティリティまたは任意の方法を使用して、SSL 証明書と鍵を生成するか、取得します。
  2. Edge Microgateway 構成ファイルに 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
  3. Edge Microgateway を再起動します。編集した構成ファイル（デフォルト ファイルまたはランタイム構成ファイル）に応じて、構成の変更に概説されている手順に従います。

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

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

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

オプション 説明
key ca.key ファイルのパス（PEM 形式）。
cert ca.cert ファイルのパス（PEM 形式）。
pfx 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 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

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

オプション 説明
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 プロキシのカスタマイズ

デフォルトでは、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 を使用して ID を確認するサービスがある場合があります。

ログファイルの管理

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 とログファイルの両方に送信することはできません。

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

info、warn、error の 3 つのログレベルを設定できます。info レベルをおすすめします。すべての API のリクエストとレスポンスが記録され、これがデフォルトとなります。

ログ間隔を変更する方法

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

ログファイル メンテナンスの推奨される運用方法

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

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

ログファイルの命名規則

各 Edge Microgateway インスタンスは、3 種類のログファイルを生成します。

  • api - Edge Microgateway を通過するすべてのリクエストとレスポンスを記録します。API カウンタ（統計情報）とエラーもこのファイルに記録されます。
  • err - stderr に送信されたすべてのものを記録します。
  • out - stdout に送信されたすべてのものを記録します。

命名規則は次のとおりです。

    edgemicro-<Host Name>-<Instance ID>-<Log Type>.log

例:

    edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log
    edgemicro-mymachine-local-MTQzNTg1NDMODAyMQ-err.log
    edgemicro-mymachine-local-mtqzntgndmxodaymq-out.log

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

v2.3.3 で追加

デフォルトでは、ロギング サービスは、ダウンロードされたプロキシ、プロダクト、JSON ウェブトークン（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 - コンテキストによって異なります。ログレベルに対応して、info、warn、または error の値をとる場合があります。統計レコードの場合は stats、警告の場合は warn、エラーの場合は error となります。
  • 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 - コンテキストによって異なります。ログレベルに対応して、info、warn、または error の値をとる場合があります。統計レコードの場合は stats、警告の場合は warn、エラーの場合は error となります。
  • treq - イベントを識別します。この場合は、ターゲット リクエスト。
  • m - ターゲット リクエストで使用される HTTP 動詞。
  • u - ベースパスに続く URL の部分。
  • h - バックエンド ターゲットのホストとポート番号。
  • i - ログエントリの ID。4 つのイベント エントリすべてがこの ID を共有します。

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

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

1436403888651 - UNIX の日付スタンプ

  • info - コンテキストによって異なります。ログレベルに対応して、info、warn、または error の値をとる場合があります。統計レコードの場合は stats、警告の場合は warn、エラーの場合は error となります。
  • tres - イベントを識別します。この場合は、ターゲット レスポンス。
  • s - HTTP レスポンス ステータス。
  • d - 期間（ミリ秒）。ターゲットによる API 呼び出しに要した時間。
  • i - ログエントリの ID。4 つのイベント エントリすべてがこの ID を共有します。

4. クライアントに対する送信レスポンスのサンプル

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

1436403888651 - UNIX の日付スタンプ

  • info - コンテキストによって異なります。ログレベルに対応して、info、warn、または error の値をとる場合があります。統計レコードの場合は stats、警告の場合は warn、エラーの場合は error となります。
  • res - イベントを識別します。この場合は、クライアントへのレスポンス。
  • s - HTTP レスポンス ステータス。
  • d - 期間（ミリ秒）。これは、ターゲット API で使用された時間と Edge Microgateway 自体で使用された時間を含む、API 呼び出しに要した合計時間です。
  • i - ログエントリの ID。4 つのイベント エントリすべてがこの ID を共有します。

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

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

Edge Microgateway 構成リファレンス

構成ファイルの場所

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

edge_config 属性

これらの設定は、Edge Microgateway インスタンスと Apigee Edge との間の対話を構成するために使用します。

  • bootstrap: （デフォルト: なし）Apigee Edge で実行されている Edge Microgateway 固有のサービスを指す URL。Edge Microgateway はこのサービスを使用して Apigee Edge と通信します。この URL は、公開鍵 / 秘密鍵のペアを生成するコマンド edgemicro genkeys を実行すると返されます。詳細については、Edge Microgateway の設定と構成をご覧ください。
  • jwt_public_key: （デフォルト: なし）Apigee Edge にデプロイされている Edge Microgateway プロキシを指す URL。このプロキシは、署名されたアクセス トークンをクライアントに発行するための認証エンドポイントとして機能します。この URL は、プロキシをデプロイするコマンド edgemicro configure を実行すると返されます。詳細については、Edge Microgateway の設定と構成をご覧ください。

edgemicro 属性

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

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

    res.statusCode = 429; // Too many requests
  • max_connections_hard: （デフォルト: -1）Edge Microgateway が受信できる同時リクエストの最大数。これを超えると接続がシャットダウンされます。この設定は、サービス拒否攻撃を阻止するためのものです。通常、max_connections より大きい数値に設定します。
  • logging:
    • level: （デフォルト: error）
      • info - Edge Microgateway インスタンスを通過するすべてのリクエストとレスポンスを記録します。
      • warn - 警告メッセージのみを記録します。
      • error - エラー メッセージのみを記録します。
    • dir: （デフォルト: /var/tmp）ログファイルが保存されるディレクトリ。
    • stats_log_interval: （デフォルト: 60）統計レコードが api ログファイルに書き込まれる間隔（秒単位）。
    • rotate_interval: （デフォルト: 24）ログファイルがローテーションされる間隔（時間単位）。
  • plugins: プラグインは 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 で追加）

headers 属性

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

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

oauth 属性

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

  • allowNoAuthorization: （デフォルト: false）true に設定した場合、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: true に設定した場合、すべての API は API キーを含む x-api-key ヘッダー（またはカスタムの場所）を保持する必要があります。（下位互換性を維持したまま）API キー セキュリティ モデルのみを許可できます。（2.4.x で追加）
  • gracePeriod: このパラメータは、システム クロックと、JWT 認可トークンで指定された Not Before（nbf）または Issued At（iat）時刻の間のわずかな相違が原因で発生するエラーを防止します。このような相違を許容する秒数をこのパラメータに設定します。（2.5.7 で追加）

プラグイン固有の属性

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

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

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

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

分析の push 頻度の構成

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

edgemicro_proxyname-health

次の図は、Analytics ダッシュボード内で分離された 2 つのプロキシ、edgemicro_hello-health と edgemicro_mock-health を示しています。

これらのパラメータを使用して、Analytics ダッシュボードで、相対パスと絶対パスが個別のプロキシとして分離されるようにします。

  • relativePath（オプション）: Analytics ダッシュボードで分離する相対パスを指定します。たとえば、/healthcheck を指定した場合、パス /healthcheck を含むすべての API 呼び出しが、ダッシュボードで edgemicro_proxyname-health として表示されます。このフラグは、プロキシのベースパスを無視することに注意してください。ベースパスを含むフルパスに基づいて分離するには、proxyPath フラグを使用します。
  • proxyPath（オプション）: Analytics ダッシュボードで分離する API プロキシのフルパスを、プロキシのベースパスを含めて指定します。たとえば、/mocktarget/healthcheck を指定した場合（/mocktarget はプロキシのベースパス）、パス /mocktarget/healthcheck を含むすべての API 呼び出しが、ダッシュボードで edgemicro_proxyname-health として表示されます。

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

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

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

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

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

v2.4.x でサポート

Edge Microgateway がファイアウォールの内側にインストールされている場合、ゲートウェイは Apigee Edge と通信できないことがあります。この場合、検討できる 2 つのオプションがあります。

オプション 1:

最初のオプションは、Microgateway 構成ファイルで edgemicro: proxy_tunnel オプションを true に設定することです。

    edge_config:

        proxy: http://10.224.16.85:3128
        proxy_tunnel: true

proxy_tunnel が true の場合、Edge Microgateway は HTTP CONNECT メソッドを使用して、単一の TCP 接続を介して HTTP リクエストをトンネリングします（プロキシを構成するための環境変数で TLS が有効になっている場合も同様です）。

オプション 2:

2 番目のオプションは、プロキシを指定し、Microgateway 構成ファイルで proxy_tunnel を false に設定することです。次に例を示します。

    edge_config:
         proxy: http://10.224.16.85:3128
         proxy_tunnel: false

この場合、変数 HTTP_PROXY、HTTPS_PROXY、NO_PROXY を設定して、使用する各 HTTP プロキシのホスト、または Edge Microgateway プロキシを処理しないホストを制御できます。

NO_PROXY には、カンマ区切りリストとして、Edge Microgateway によるプロキシの対象としないドメインを設定できます。次に例を示します。

    export NO_PROXY='localhost,localhost:8080'

HTTP_PROXY と HTTPS_PROXY は、Edge Microgateway がメッセージを送信できる HTTP プロキシ エンドポイントに設定します。次に例を示します。

    export HTTP_PROXY='http://localhost:3786'

    export HTTPS_PROXY='https://localhost:3786'

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

関連情報

Apigee コミュニティの会社のファイアウォールの内側に Edge Microgateway を設定する方法

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

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

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

JWT 鍵のローテーション

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

Edge Microgateway が JWT を使用する方法

JSON ウェブトークン（JWT）は、RFC7519 で説明されているトークン標準です。JWT では、一連のクレームに署名することができ、JWT の受信者はこれを確実に確認できます。

Edge Microgateway は JWT を OAuth セキュリティの署名なしトークンとして使用します。Edge Microgateway 用の OAuth トークンを生成すると、JWT が返されます。その後、API 呼び出しの Authorization ヘッダーで JWT を使用できます。次に例を示します。

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

新しい JWT の生成

Edge Microgateway 用の JWT は、edgemicro token コマンドまたは API を使用して生成できます。次に例を示します。

edgemicro token get -o docs -e test -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

このコマンドは、API 呼び出しの検証に使用できる JWT を生成するように Apigee Edge に要求します。-i パラメータと -s パラメータは、Apigee Edge 組織のデベロッパー アプリのコンシューマ ID とコンシューマ シークレットの値です。

管理 API を使用して JWT を生成することもできます。

curl -i -X POST "http://org-env.apigee.net/edgemicro-auth/token" \
      -H "Content-Type: application/json" \
      -d '{
        "client_id": "your consumer key",
        "client_secret": "your consumer secret",
        "grant_type": "client_credentials"
      }'

ここで

  • org は Edge 組織名です（組織管理者である必要があります）。
  • env は組織の環境です（「test」や「prod」など）。
  • client_id は、以前に作成したデベロッパー アプリのコンシューマ ID です。
  • client_secret は、以前に作成したデベロッパー アプリのコンシューマ シークレットです。

鍵のローテーションとは

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 の値に関連付けられ、鍵のローテーションをサポートするために使用されます。この値は秘密鍵の kid と同じです。

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

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

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

  • public_key2 - 古い公開鍵。

検証のために提示された JWT は、新しい公開鍵を使用して検証されます。検証に失敗した場合は、期限が切れるまで（30 分後）古い公開鍵が使用されます。この方法では、API トラフィックをすぐに中断することなく、鍵をローテーションできます。

鍵をローテーションする方法

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

Edge Microgateway インスタンスを 2.5.2 以前のバージョンで構成した場合

Edge Microgateway インスタンスを 2.5.2 以前のバージョンで構成した場合は、次の 2 つのコマンドを実行して KVM と認証ポリシーをアップグレードする必要があります。

upgradekvm -o org -e env -u username

このコマンドについて詳しくは、KVM のアップグレードをご覧ください。

次のコマンドは、Edge Microgateway の構成時に Apigee 組織にデプロイされた edgemicro-oauth プロキシをアップグレードします。このプロキシは、トークンの生成に必要なサービスを提供します。

upgradeauth -o org -e env -u username

このコマンドについて詳しくは、edgemicro-auth プロキシのアップグレードをご覧ください。

鍵のローテーション

~/.edgemicro/org-env-config.yaml ファイルに次の行を追加します。ここでは、使用する Microgateway で構成した同じ組織と環境を指定する必要があります。

jwk_public_keys: 'https://org-env.apigee.net/edgemicro-auth/jwkPublicKeys'

鍵のローテーション コマンドを実行して、鍵をローテーションします。このコマンドについて詳しくは、鍵のローテーションをご覧ください。

edgemicro rotatekey -o org -e env -u username -k kid_value

例:

    edgemicro rotatekey -o jdoe -e test -u jdoe@google.com -k 2
    current nodejs version is v6.9.1
    current edgemicro version is 2.5.7
    password:
    Checking if private key exists in the KVM...
    Checking for certificate...
    Found Certificate
    Generating New key/cert pair...
    Extract new public key
    Key Rotation successfully completed!

-k パラメータは、鍵 ID（kid）を指定します。この ID は、特定の鍵を照合するために使用されます。Edge Microgateway は、この値を使用して、鍵のローテーション中に鍵のセットから選択します。詳細については、JSON ウェブキー仕様のセクション 4.5 をご覧ください。

鍵のローテーション後、Edge は複数の鍵を Edge Microgateway に返します。次の例では、各鍵に固有の「kid」（鍵 ID）値が設定されています。Microgateway では、これらの鍵を使用して認可トークンを検証します。トークンの検証に失敗した場合、Microgateway は鍵セットに古い鍵があるかどうかを調べ、その鍵を試します。返される鍵の形式は JSON ウェブキー（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"
        }
      ]
    }

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

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

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

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

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

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

デバッガへの接続

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

  1. Edge Microgateway をデバッグモードで再起動します。そのためには、start コマンドの先頭に DEBUG=* を追加します。次に例を示します。 
    DEBUG=* edgemicro start -o  myorg -e test -k
          db4e9e8a95aa7fabfdeacbb1169d0a8cbe42bec19c6b98129e02 -s
          6e56af7c1b26dfe93dae78a735c8afc9796b077d105ae5618ce7ed
  2. デバッガを起動し、デバッグ プロセスのポート番号で待機するように設定します。
  3. Edge Microgateway コードのステップ実行、ブレークポイントの設定、式の監視などができるようになりました。

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

ログファイルの確認

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

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

API キーでは、Edge Microgateway にリクエストを行うクライアントを簡単に認証できます。API キーを取得するには、Edge Microgateway 認証プロキシを含む Apigee Edge プロダクトからコンシューマ キー（クライアント ID とも呼ばれる）の値をコピーします。

キーのキャッシュ保存

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

API キーの使用

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

クエリ パラメータの例:

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

ヘッダーの例:

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

API キー名の構成

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

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

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

例:

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

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

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

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

Forever モニタリング

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

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

edgemicro forever コマンドには、forever.json ファイルの場所を指定できるフラグ（-f フラグ）と、Forever モニタリング プロセスを開始 / 停止できるフラグ（-a フラグ）が含まれています。次に例を示します。

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

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

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

複数の Edge Microgateway インスタンスを実行する場合、単一の場所から構成を管理できます。そのためには、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 キー
  • 割り当て
  • Analytics

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

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

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

  1. Edge Microgateway バージョン 2.5.25 以降がインストールされていることを確認してください。インストールされていない場合は、次のコマンドを実行して最新のバージョンにアップグレードする必要があります。 
    npm install -g edgemicro

    詳しくは、Edge Microgateway のインストールをご覧ください。

  2. $HOME/.edgemicro/org_name-env_name-config.yaml という名前の構成ファイルを作成します。

    例:

    vi $HOME/.edgemicro/foo-bar-config.yaml
  3. 次のコードをファイルに貼り付けます。 
        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
  4. 値「1」の次の環境変数をエクスポートします。 
    export EDGEMICRO_LOCAL=1
  5. 次の start コマンドを実行します。ここでは、ローカル プロキシをインスタンス化するための値を指定します。 
    edgemicro start -o org_name -e environment_name -a local_proxy_name \
      -v local_proxy_version -t target_url -b base_path

    ここで

    • your_org は、構成ファイル名で使用した「組織」名です。
    • your_environment は、構成ファイル名で使用した「環境」名です。
    • 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 /
  6. 構成をテストします。 
    curl http://localhost:8000/echo  { "error" : "missing_authorization" }

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

例: 認可トークンの取得

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

次の手順では、edgemicro-auth/jwkPublicKeys エンドポイントを使用してトークンを取得する方法を説明します。

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

Edge Microgateway 用の JWT は、edgemicro token コマンドまたは API を使用して生成できます。次に例を示します。

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

ここで

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

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

トークンの生成もご覧ください。

スタンドアロン構成のテスト

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

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

例:

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

出力例:

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

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

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

ユースケースと例

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

サイドカーとしての Edgemicro

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

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

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

  1. Edge Microgateway バージョン 2.5.25 以降がインストールされていることを確認してください。インストールされていない場合は、次のコマンドを実行して最新のバージョンにアップグレードする必要があります。 
    npm install -g edgemicro

    詳しくは、Edge Microgateway のインストールをご覧ください。

  2. edgemicro init を実行して、Edge Microgateway の標準の設定での場合と同様に、ローカル構成環境を設定します。Edge Microgateway の構成もご覧ください。
  3. Edge Microgateway の標準の設定手順と同様に edgemicro configure を実行します。次に例を示します。 
    edgemicro configure -o your_org -e your_env -u your_apigee_username

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

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

  5. Apigee Edge で、デベロッパーを作成するか、必要に応じて既存のデベロッパーを使用します。方法については、Edge 管理 UI を使ってデベロッパーを追加するをご覧ください。

  6. Apigee Edge で、デベロッパー アプリを作成します。作成した API プロダクトをアプリに追加する必要があります。方法については、Edge 管理 UI でアプリを登録するをご覧ください。
  7. Edge Microgateway がインストールされているマシンで、値「1」の次の環境変数をエクスポートします。 
    export EDGEMICRO_LOCAL_PROXY=1
  8. 次の 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":""
    }