現在、Apigee Edge のドキュメントを表示しています。
Apigee X のドキュメントをご確認ください。 情報
このトピックでは、Docker コンテナで Edge Microgateway を実行する方法について説明します。このトピックの手順は、Docker、Docker コマンド、Edge Microgateway の設定と構成について基本的な知識があることを前提としています。詳細については、Docker と Edge Microgateway のドキュメントをご覧ください。
前提条件
Docker コンテナで Edge Microgateway を実行する前に、次の作業を行う必要があります。
Apigee 組織/環境用に Edge Microgateway を構成します。
edgemicro configure -o your_org -e your_env -u your_username
構成の詳細については、パート 1: Edge Microgateway を構成するをご覧ください。
構成手順を実行したら、構成ファイルを見つけます。デフォルトの場所は次のとおりです。
$HOME/.edgemicro/your_org-your_env-config.yaml
ここで、
your_org
とyour_env
は、edgemicro config
コマンドを実行したときに使用した組織と環境です。このファイルは、Docker コンテナで Edge Microgateway を起動するときに必要になります。edgemicro config
コマンドを実行したときに返された鍵とシークレットの認証情報があることを確認します。例:The following credentials are required to start edge micro key: d9c34e1aff68ed969273c016699eabf48780e4f652242e72fc88a43e21252cb0 secret: 3bc95a71c86a3c8ce04537fbcb788158731t51dfc6cdec13b7c05aa0bd969430
Docker コンテナで Edge Microgateway を起動する前に、認証された API プロキシ呼び出しに必要な Apigee Edge エンティティを作成(または作成済み)する必要があります。これらのエンティティには、Edge Microgateway 対応プロキシ、API プロダクト、デベロッパー、デベロッパー アプリが含まれます。詳しい手順については、Apigee Edge でエンティティを作成するをご覧ください。
Edge Micro を Docker コンテナとして実行する
Edge Microgateway の Docker イメージをダウンロードします。
docker pull gcr.io/apigee-microgateway/edgemicro:latest
次の手順に進む前に、前提条件セクションの手順をすべて完了していることを確認してください。
次のコマンドを実行して、
$HOME/.edgemicro
にある Edge Microgateway 構成ファイルを base64 エンコードします。export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`
ここで、
your_org
とyour_env
は、edgemicro config
コマンドを実行したときに使用した組織と環境です。コマンドの前後に必ずバッククォート(`)を付けてください。例:
export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
Edge Microgateway をコンテナとして実行します。このコマンドでは、コンテナ ランタイムが Edge Microgateway を起動する際に使用するいくつかの環境変数を設定します。
chown -R 100:101 ~/.edgemicro/ \ docker run -P -p 8000:8000 -d --name edgemicro \ -v /var/tmp:/opt/apigee/logs \ -e EDGEMICRO_PROCESSES=1 \ -e EDGEMICRO_ORG=your_org \ -e EDGEMICRO_ENV=your_env \ -e EDGEMICRO_KEY=your_key \ -e EDGEMICRO_SECRET=your_secret \ -e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \ -e "LOG_CONSOLE_OUTPUT_TO_FILE=false" \ -e SERVICE_NAME=edgemicro \ --security-opt=no-new-privileges \ --cap-drop=ALL \ gcr.io/apigee-microgateway/edgemicro:latest
パラメータ
<tr> <td><code>SERVICE_NAME</code></td> <td>If you are on Kubernetes, this parameter is auto-populated. Otherwise, you can set it to anything you wish. If you specify nothing, the service name is set to <code>default</code>.</td> </tr> <tr> <tr> <td><code>DEBUG</code></td> <td>Set to <code>*</code> to enable debugging. </td> </tr> <tr> <td><code>HTTP_PROXY</code> <code>HTTPS_PROXY</code></td> <td>Use when Edge Microgateway is running behind a firewall and the gateway cannot communicate with Apigee Edge. For more information, see <a href="operation-and-configuration-reference-edge-microgateway#settingupedgemicrogatewaybehindacompanyfirewall">Setting up Edge Microgateway behind a company firewall</a>. <p>For example: <code>HTTP_PROXY=http://10.203.0.1:5187/</code></p></td> </tr> <tr> <td><code>NO_PROXY</code></td> <td>A comma delimited list of domains that Edge Microgateway should not proxy to. For more information, see <a href="operation-and-configuration-reference-edge-microgateway#settingupedgemicrogatewaybehindacompanyfirewall">Setting up Edge Microgateway behind a company firewall</a>. <p>For example: <code>localhost,127.0.0.1,localaddress,.localdomain.com</code></p></td> </tr> <tr> <tr> <tr> <td><code>NODE_EXTRA_CA_CERTS</code></td> <td>(Optional) Use this parameter if you are using a CA that's not trusted by default by Node.js. Set the value of this parameter to the path to a file containing one or more trusted certificates in PEM format. For details, see <a href="#tls_certificates">TLS certificates</a>.</td> </tr> <tr> <td><code>--security-opt</code></td> <td>(Optional) Sets desired Docker security options. See <a href="https://docs.docker.com/engine/reference/run/#security-configuration">Security configuration</a> in the Docker documentation.</td> </tr> <tr> <td><code>--cap-drop</code></td> <td>(Optional) Sets limits on Linux capabilities permitted in the container. See <a href="https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities">Runtime privilege and Linux capabilities</a> in the Docker documentation.</td> </tr> </tbody>
パラメータ 説明 -P
公開されているすべてのポートをホストに公開します。Docker run リファレンスもご覧ください。 -p
単一のポートまたはポート範囲を明示的にマッピングします。Docker run リファレンスもご覧ください。 -d
接続解除モードで実行します。Docker run リファレンスもご覧ください。 -v, -- volume
ボリュームのマウントを指定します。Docker コンテナで TLS を使用するように Edge Microgateway を構成する場合、ログファイル ディレクトリをマウントするときにポート 8443 を公開する必要があります。VOLUME [共有ファイルシステム] もご覧ください。Docker コンテナでの TLS の使用もご覧ください。 -w, -- workdir
(省略可) edgemicro.sock
ファイルとedgemicro.pid
ファイルを作成するディレクトリへのパスを指定します。ファイル名のルートedgemicro
は変更できません。デフォルトは現在の作業ディレクトリ パスです。例:
docker run -P -p 8000:8000 -d -w /tmp --name edgemicro
...EDGEMICRO_ORG
Edge Microgateway の構成に使用した Apigee 組織の名前。 EDGEMICRO_ENV
Edge Microgateway の構成に使用した Apigee 環境の名前。 EDGEMICRO_PROCESSES
開始するプロセスの数。 EDGEMICRO_KEY
Edge Microgateway を構成したときに返された鍵。 EDGEMICRO_SECRET
Edge Microgateway を構成したときに返されたシークレット。 EDGEMICRO_CONFIG
base64 エンコードされた Edge Microgateway 構成ファイルを含む変数。 LOG_CONSOLE_OUTPUT_TO_FILE
(ブール値)ログ出力の送信先を指定できます。ログファイル オプションの指定をご覧ください。 例:
chown -R 100:101 ~/.edgemicro/
docker run -P -p 8000:8000 -d --name edgemicro
-v /var/tmp:/opt/apigee/logs
-e EDGEMICRO_PROCESS=1
-e EDGEMICRO_ORG=docs
-e EDGEMICRO_ENV=test
-e EDGEMICRO_KEY=d9c34e1aff68ed969273b016699eabf48780e4f652242e72fc88a23e21252cb0
-e EDGEMICRO_SECRET=3bc95a71c86a3c8ce04137fbcb788158731t51dfc6cdec13b7c05aa0bd969430
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG"
-e SERVICE_NAME=edgemicro
--security-opt=no-new-privileges
--cap-drop=ALL
gcr.io/apigee-microgateway/edgemicroコンテナが実行されていることを確認するには:
docker ps
出力は次のようになります。
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 8b92e082ea9c edgemicro "/tmp/entrypoint.sh" 12 minutes ago Up 12 minutes 0.0.0.0:8000->8000/tcp, 0.0.0.0:32775->8443/tcp edgemicro
ログファイル出力オプションの指定
Edge Microgateway 構成パラメータ to_console を使用すると、ログ情報をログファイルではなく標準出力に送信するように選択できます。手順に沿って Docker コンテナで Edge Microgateway を実行すると、コンテナはデフォルトで stdout とエラー出力をコンテナ内の
${APIGEE_ROOT}/logs/edgemicro.log
にあるファイルにリダイレクトします。ログ情報が
edgemicro.log
に送信されないようにするには、コンテナの実行時にLOG_CONSOLE_OUTPUT_TO_FILE
変数を使用します。次の表に、
to_console
でLOG_CONSOLE_OUTPUT_TO_FILE
を使用した場合のログ出力の動作を示します。to_console: true
LOG_CONSOLE_OUTPUT_TO_FILE=false
- ログファイルの管理で説明されているように、Edge Microgateway ログファイルにログは送信されません。
- ログは
edgemicro.log
ファイルに送信されません。
to_console: true
LOG_CONSOLE_OUTPUT_TO_FILE=true
- ログファイルの管理で説明されているように、Edge Microgateway ログファイルにログは送信されません。
- ログは
edgemicro.log
ファイルに送信されます。
to_console: false
LOG_CONSOLE_OUTPUT_TO_FILE=true
- ログファイルの管理で説明されているように、ログは Edge Microgateway ログファイルに送信されます。
- ログは
edgemicro.log
ファイルに送信されます。
API 呼び出しのテスト
コンテナで Edge Microgateway を起動すると、API 呼び出しが可能になります。 たとえば、API のベースパスが
/hello
の場合は次のとおりです。http://localhost:8000/hello
出力例:
{"error":"missing_authorization","error_description":"Missing Authorization header"}
このレスポンスが表示された場合は、Edge Microgateway が API 呼び出しを正常に処理したことを意味します。ただし、デフォルトでは、Edge Microgateway では認証用の API キーが必要です。次のセクションでは、有効な API キーで API をテストします。
有効な API キーで API をテストする
Edge UI で、前に作成したデベロッパー アプリに移動します。[Developer App] ページでコンシューマ キーを表示してコピーします。この値が API キーとなります。このキーを使用して、認証された API 呼び出しを行います。
次のように
x-api-key
ヘッダーを指定して API を呼び出します。デベロッパー アプリからコピーしたコンシューマ キーの値が API キーになります。デフォルトでは、Edge Microgateway は、次のようにx-api-key
というヘッダーで鍵を渡すことを想定しています。curl -i http://localhost:8000/hello -H "x-api-key:apikey"
例:
curl -i http://localhost:8000/hello -H "x-api-key:PydUKRDGIXRqF2xh4usn1FLHbhGKVIz"
API キーと OAuth トークンを使用して、Edge Microgateway を介して認証された API 呼び出しを行う方法の詳細については、パート 4: Edge Microgateway を保護するをご覧ください。
Edge Microgateway の停止
次の Docker コマンドを使用して、Edge Microgateway を停止します。
docker stop edgemicro
Edge Microgateway の再起動
Edge Microgateway を停止した後、次の Docker コマンドを使用して再起動できます。
docker start edgemicro
Docker コンテナでの TLS の使用
このセクションでは、Docker コンテナで実行する Edge Microgateway に TLS を構成する方法について説明します。受信リクエスト(ノースバウンド方向)に TLS を使用するように Edge Microgateway サーバーを構成し、ターゲット エンドポイントへの送信リクエスト(サウスバウンド方向)の TLS クライアントとして Edge microgateway を構成できます。
証明書ファイルの配置場所
Edge Microgateway を実行している Docker コンテナには、
/opt/apigee/.edgemicro
にマウント ポイントがあります。TLS 証明書を使用するように Edge Microgateway を構成すると、そのマウント ポイントで証明書ファイルを使用できるようになり、Edge Microgateway 構成ファイルで証明書ファイルを参照できます。通常、この構成ファイルは$HOME/.edgemicro
ディレクトリにあり、名前はyour_org-your_env-config.yaml
です。例:... edgemicro: ssl: key: /opt/apigee/.edgemicro/southbound/tls.key cert: /opt/apigee/.edgemicro/southbound/tls.crt ...
Node.js によって信頼されていない CA の使用
Node.js によってデフォルトで信頼されていない認証局(CA)を使用している場合(自己署名証明書を使用する場合など)、コンテナの実行時にパラメータ
NODE_EXTRA_CA_CERTS
を使用することを検討してください。このパラメータを、1 つ以上の信頼できる PEM 形式の証明書を含むファイルのパスに設定します。このパラメータの使用方法については、ノースバウンド TLS の構成方法とサウスバウンド TLS の構成方法の例をご覧ください。
例:
chown -R 100:101 ~/.edgemicro/ \ docker run -P -p 8443:8443 -d --name edgemicro \ -v $HOME/.edgemicro:/opt/apigee/.edgemicro \ -v $HOME/.edgemicro:/opt/apigee/logs \ -e NODE_EXTRA_CA_CERTS=/opt/apigee/.edgemicro/rootca.pem \ -e EDGEMICRO_PORT=8443 \ -e EDGEMICRO_ORG=docs \ -e EDGEMICRO_ENV=test \ -e EDGEMICRO_KEY=ac36574905fb54fdae65fc5433e831bec2680efb98220a355f2e917e52973c \ -e EDGEMICRO_SECRET=aac81dff6c326eaa222d53c15c8841fa78ea863bf4472568c9ce2d80a3bc56 \ -e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \ --link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro
Edge Micro を Docker コンテナとして実行するもご覧ください。
TLS 検証を無効にする
推奨されませんが、コンテナで実行されている Edge Microgateway の TLS 検証を無効にすることもできます。TLS を無効にする機能は、デフォルトで Edge Microgateway Docker コンテナに組み込まれていません。このタスクを行うには、Edge Microgateway 用にカスタマイズされた Docker イメージを作成する必要があります。カスタム イメージを作成して TLS 検証をオフにする一般的な手順を以下に示します。
Edge Microgateway ソース リポジトリのクローンを作成するか、
https://github.com/apigee-internal/microgateway
からダウンロードします。cd
で、ソースコード ディレクトリのmicrogateway/kubernetes/docker/edgemicro
ディレクトリに移動します。例:
cd $HOME/git/microgateway/kubernetes/docker/edgemicro
entrypoint.sh
ファイルを開き、NODE_TLS_REJECT_UNAUTHORIZED
環境変数を受け入れるようにコードを変更します。後でコンテナを実行するときに、この変数の値を指定します。Docker コンテナをビルドします。
docker build -t edgemicro .
コンテナの実行時に、オプション
-e NODE_TLS_REJECT_UNAUTHORIZED = 1
を指定します。例:
chown -R 100:101 ~/.edgemicro/ \ docker run -P -p 8443:8443 -d --name edgemicro \ -v $HOME/.edgemicro:/opt/apigee/.edgemicro \ -v $HOME/.edgemicro:/opt/apigee/logs \ -e NODE_TLS_REJECT_UNAUTHORIZED = 1 \ -e EDGEMICRO_PORT=8443 \ -e EDGEMICRO_ORG=docs \ -e EDGEMICRO_ENV=test \ -e EDGEMICRO_KEY=ac36574905fb54fdae65fc5433e831bec2680efb98220a355f2e917e52973c \ -e EDGEMICRO_SECRET=aac81dff6c326eaa222d53c15c8841fa78ea863bf4472568c9ce2d80a3bc56 \ -e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \ --link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro
例: ノースバウンド TLS の構成方法
このセクションでは、Edge Microgateway サーバーでノースバウンド(受信)TLS 接続を設定する方法について説明します。ノースバウンド TLS を使用すると、クライアントは Edge Microgateway に対して API 呼び出しを行うときに HTTPS を使用できます。次の例では、自己署名証明書を使用しています。
1. Intital のセットアップ手順
- システム上の
openssl.cnf
ファイルを見つけます。例:/etc/ssl/openssl.cnf
- 編集する
opensssl.cnf
ファイルを開きます。 構成ファイルに
req_extensions
が含まれていることを確認します。たとえば、ファイルには次のような情報を含めます。[ req ] ... req_extensions = v3_req ... [ v3_req ] extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment
次のスタンザを
openssl.cnf
に追加して、適切な SNI 属性を生成します。[ alt_names ] DNS.1 = www.example.com DNS.2 = example.com DNS.3 = localhost DNS.4 = localhost.localdomain DNS.5 = 127.0.0.1 DNS.6 = ::1 DNS.7 = fe80::1
opensssl.cnf
ファイルの例:[ req ] distinguished_name = req_distinguished_name attributes = req_attributes req_extensions = v3_req [ v3_req ] extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment [ req_distinguished_name ] countryName = Country Name (2 letter code) countryName_min = 2 countryName_max = 2 stateOrProvinceName = State or Province Name (full name) localityName = Locality Name (eg, city) 0.organizationName = Organization Name (eg, company) organizationalUnitName = Organizational Unit Name (eg, section) commonName = Common Name (eg, fully qualified host name) commonName_max = 64 emailAddress = Email Address emailAddress_max = 64 [ req_attributes ] challengePassword = A challenge password challengePassword_min = 4 challengePassword_max = 20 [ alt_names ] DNS.1 = www.example.com DNS.2 = example.com DNS.3 = localhost DNS.4 = localhost.localdomain DNS.5 = 127.0.0.1 DNS.6 = ::1 DNS.7 = fe80::1
Edge Microgateway の初期化と構成をまだ行っていない場合は、前提条件セクションの手順に従って初期化と構成を行います。完了すると、Edge Microgateway 対応プロキシ、API プロダクト、デベロッパー、デベロッパー アプリが作成されているはずです。また、
edgemicro configure
コマンドを実行して、鍵とシークレットを受け取ったことも必要です。
2. 自己署名証明書を生成する
次に、TLS の確立に必要な証明書と鍵を生成します。
cd
で$HOME/.edgemicro
ディレクトリに移動します。次の bash スクリプトを作成します。任意の名前を付けることができます。例:
keygen.sh
。#!/bin/bash # generate ca openssl genrsa -out rootca.key 2048 openssl req -x509 -new -nodes -key rootca.key -sha256 -days 1024 -out rootca.pem # generate key openssl genrsa -out tls.key 2048 openssl req -new -key tls.key -out tls.csr # sign cert openssl x509 -req -in tls.csr -CA rootca.pem -CAkey rootca.key -CAcreateserial -out tls.crt -days 1024 -sha256 -extensions 'v3_req' -extfile path/openssl.cnf
bash ファイルで、
openssl.cnf
ファイルのパスが正しいことを確認します。bash ファイルを実行します。証明書の情報を求めるメッセージが表示されます。共通名には
localhost
を使用します。次のファイルが作成されていることを確認します。
rootca.key
rootca.pem
tls.key
tls.csr
rootca.srl
tls.crt
3. Edge Microgateway 構成ファイルを編集する
エディタで Edge Micro 構成ファイルを開きます。例:
vi $HOME/.edgemicro/myorg-test-config.yaml
edgemicro
スタンザを次のように編集します。ここでは、port
属性とssl
属性を変更しています。edge_config: ... edgemicro: port: 8443 max_connections: 1000 config_change_poll_interval: 600 ssl: key: /opt/apigee/.edgemicro/tls.key cert: /opt/apigee/.edgemicro/tls.crt passphrase: admin123 rejectUnauthorized: true requestCert: false logging: ...
次のコマンドを実行して、
$HOME/.edgemicro
にある Edge Microgateway 構成ファイルを base64 エンコードします。export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`
ここで、
your_org
とyour_env
は、edgemicro config
コマンドを実行したときに使用した組織と環境です。コマンドの前後に必ずバッククォート(`)を付けてください。例:
export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
Edge Micro を Docker コンテナとして実行するもご覧ください。
4. コンテナを実行する
次のコマンドを実行して、Edge Microgateway で Docker コンテナを実行します。
chown -R 100:101 ~/.edgemicro/ \ docker run -P -p 8443:8443 -d --name edgemicro \ -v path_to_your_edgemicro_dir:/opt/apigee/.edgemicro \ -v path_to_your_logs_dir:/opt/apigee/logs \ -e NODE_EXTRA_CA_CERTS=/opt/apigee/.edgemicro/rootca.pem \ -e EDGEMICRO_PORT=8443 \ -e EDGEMICRO_ORG=$EDGEMICRO_ORG \ -e EDGEMICRO_ENV=$EDGEMICRO_ENV \ -e EDGEMICRO_KEY=$EDGEMICRO_KEY \ -e EDGEMICRO_SECRET=$EDGEMICRO_SECRET \ -e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \ gcr.io/apigee-microgateway/edgemicro:latest
このコマンドで使用されている次のパラメータは、Docker コンテナとして Edge Micro を実行するで説明されている基本的なコマンドとは異なります。
port
が8443
に設定されている。- 鍵ファイルと証明書ファイルをマウントするために、ボリューム マウントを使用します。
NODE_EXTRA_CA_CERTS
変数は、カスタム CA を追加するために使用されます(自己署名証明書の場合は必要に応じて)。
5. TLS 構成をテストする
次の cURL コマンドを実行して設定をテストします。コマンドでは、ベースパスと API キーに置き換えます。次の例では、
rootca.pem
が配置されているディレクトリにいることと、作成したプロキシのベースパスが/hello
であることを前提としています。curl -v https://localhost:8443/hello --cacert rootca.pem \ -H "x-api-key: Az82fdnfONVCOOE4NKhajxAboDgA3FAo"
詳細な cURL 出力には、TLS handshake の各ステップが表示されます。HTTP 200 レスポンスが返された場合、構成は成功です。
* Trying ::1...ey:Az82fdnfONVCOOE4NKhajxAboDgA3FAo" * TCP_NODELAY set * Connected to localhost (::1) port 8443 (#0) * ALPN, offering h2 * ALPN, offering http/1.1 * Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH * successfully set certificate verify locations: * CAfile: rootca.pem CApath: none * TLSv1.2 (OUT), TLS handshake, Client hello (1): * TLSv1.2 (IN), TLS handshake, Server hello (2): * TLSv1.2 (IN), TLS handshake, Certificate (11): * TLSv1.2 (IN), TLS handshake, Server key exchange (12): * TLSv1.2 (IN), TLS handshake, Server finished (14): * TLSv1.2 (OUT), TLS handshake, Client key exchange (16): * TLSv1.2 (OUT), TLS change cipher, Client hello (1): * TLSv1.2 (OUT), TLS handshake, Finished (20): * TLSv1.2 (IN), TLS change cipher, Client hello (1): * TLSv1.2 (IN), TLS handshake, Finished (20): * SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256 * ALPN, server accepted to use http/1.1 * Server certificate: * subject: C=US; ST=CO; L=Boulder; O=Docs; OU=Docs; CN=localhost; emailAddress=docs@apigee.com * start date: Dec 14 22:35:28 2018 GMT * expire date: Oct 3 22:35:28 2021 GMT * common name: localhost (matched) * issuer: C=US; ST=CO; L=Boulder; O=Docs; OU=Docs; CN=localhost; emailAddress=docs@apigee.com * SSL certificate verify ok. > GET /hello HTTP/1.1 > Host: localhost:8443 > User-Agent: curl/7.54.0 > Accept: */* > x-api-key:Az82fdnfaONVCOE4NKhajxAboDA3FAo > < HTTP/1.1 200 OK < x-powered-by: Apigee < access-control-allow-origin: * < x-frame-options: ALLOW-FROM RESOURCE-URL < x-xss-protection: 1 < x-content-type-options: nosniff < content-type: text/plain; charset=utf-8 < etag: W/"d-GHB1ZrJKk/wdVTdB/jgBsw" < date: Fri, 14 Dec 2018 22:43:13 GMT < via: 1.1 google < alt-svc: clear < x-response-time: 1325 < Connection: keep-alive < Transfer-Encoding: chunked < * Connection #0 to host localhost left intact Hello, Guest!
例: サウスバウンド TLS の構成方法
このセクションでは、Edge Microgateway サーバーとバックエンド ターゲット アプリケーション間のサウスバウンド(送信)TLS 接続を設定する方法について説明します。次の例では、自己署名証明書を使用しています。
1. 初期設定のステップ
- システム上の
openssl.cnf
ファイルを見つけます。例:/etc/ssl/openssl.cnf
- 編集する
opensssl.cnf
ファイルを開きます。 構成ファイルに
req_extensions
が含まれていることを確認します。たとえば、ファイルには次のような情報を含めます。[ req ] ... req_extensions = v3_req ... [ v3_req ] extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment
次のスタンザを
openssl.cnf
に追加して、適切な SNI 属性を生成します。[ alt_names ] DNS.1 = helloworld DNS.2 = localhost DNS.3 = localhost.localdomain DNS.4 = 127.0.0.1 DNS.5 = ::1 DNS.6 = fe80::1
opensssl.cnf
ファイルの例:[ req ] distinguished_name = req_distinguished_name attributes = req_attributes req_extensions = v3_req [ v3_req ] extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment [ req_distinguished_name ] countryName = Country Name (2 letter code) countryName_min = 2 countryName_max = 2 stateOrProvinceName = State or Province Name (full name) localityName = Locality Name (eg, city) 0.organizationName = Organization Name (eg, company) organizationalUnitName = Organizational Unit Name (eg, section) commonName = Common Name (eg, fully qualified host name) commonName_max = 64 emailAddress = Email Address emailAddress_max = 64 [ req_attributes ] challengePassword = A challenge password challengePassword_min = 4 challengePassword_max = 20 [ alt_names ] DNS.1 = helloworld DNS.2 = localhost DNS.3 = localhost.localdomain DNS.4 = 127.0.0.1 DNS.5 = ::1 DNS.6 = fe80::1
edgemicro configure
コマンドを実行します。edgemicro configure -o your_org -e your_env -u your_username
構成の詳細については、パート 1: Edge Microgateway を構成するをご覧ください。
edgemicro configure
から返された鍵とシークレットの認証情報をコピーします。コンテナを実行するには、これらの値が必要です。例:The following credentials are required to start edge micro key: d9c34e1aff68ed969273c016699eabf48780e4f652242e72fc88a43e21252cb0 secret: 3bc95a71c86a3c8ce04537fbcb788158731t51dfc6cdec13b7c05aa0bd969430
2. Node.js ターゲット アプリケーションを作成する
cd
で.edgemicro
ディレクトリに移動します。次の bash スクリプトを作成します。任意の名前を付けることができます。例:
keygen.sh
。#!/bin/bash # generate ca openssl genrsa -out rootca.key 2048 openssl req -x509 -new -nodes -key rootca.key -sha256 -days 1024 -out rootca.pem # generate key openssl genrsa -out tls.key 2048 openssl req -new -key tls.key -out tls.csr # sign cert openssl x509 -req -in tls.csr -CA rootca.pem -CAkey rootca.key -CAcreateserial -out tls.crt -days 1024 -sha256 -extensions 'v3_req' -extfile path/openssl.cnf
bash ファイルで、
openssl.cnf
ファイルのパスが正しいことを確認します。bash ファイルを実行します。証明書の情報を求めるメッセージが表示されます。共通名には
hellworld
を使用します。次のファイルが作成されていることを確認します。
rootca.key
rootca.pem
tls.key
tls.csr
rootca.srl
tls.crt
server.js
という名前の新しいファイルを作成します。'use strict'; const express = require('express'); const https = require('https'); const fs = require('fs'); const options = { key: fs.readFileSync("tls.key"), cert: fs.readFileSync("tls.crt") }; // Constants const PORT = 9443; const HOST = '0.0.0.0'; // App const app = express(); app.get('/', (req, res) => { res.send('Hello world\n'); }); https.createServer(options, app).listen(PORT);
server.js
と同じディレクトリにpackage.json
ファイルを作成します。例:{ "name": "helloworld", "version": "1.0.0", "description": "", "main": "server.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1", "start": "node server.js" }, "author": "", "license": "ISC", "dependencies": { "express": "^4.16.4", "fs": "0.0.1-security", "https": "^1.0.0" } }
npm install
を実行して依存関係を取得します。server.js
と同じディレクトリに新しい Dockerfile を作成します。ここで、WORKDIR
は Node.js アプリのルートへのパスです。FROM node:8-alpine WORKDIR path-to-your-node-app COPY package*.json ./ RUN npm install COPY . . EXPOSE 9443 CMD [ "npm", "start" ]
Docker イメージをビルド
docker build -t helloworld .
サンプルアプリを起動します。
docker run -P -p 9443:9443 --name helloworld helloworld
3. Apigee Edge でエンティティを作成する
次の設定で Edge Microgateway 対応プロキシを作成します。詳細については、Edge で Edge Microgateway 対応 API プロキシを作成するをご覧ください。
- プロキシ名:
edgemicro_local
- リビジョン:
1
- ベースパス:
/local
- ターゲット:
https://helloworld:9443
- プロキシ名:
API プロダクトを作成します。詳しくは、商品を作成するをご覧ください。
デベロッパーを作成します。詳しくは、デベロッパーを作成するをご覧ください。
デベロッパー アプリを作成する。詳細については、デベロッパー アプリを作成するをご覧ください。
4. コンテナを実行する
エディタで Edge Micro 構成ファイルを開きます。例:
vi $HOME/.edgemicro/myorg-test-config.yaml
edgemicro
スタンザを次のように編集します。ここでは、port
属性とssl
属性を変更しています。edge_config: ... edgemicro: port: 8443 max_connections: 1000 config_change_poll_interval: 600 ssl: key: /opt/apigee/.edgemicro/tls.key cert: /opt/apigee/.edgemicro/tls.crt passphrase: admin123 rejectUnauthorized: true requestCert: false logging: ...
次のコマンドを実行して、
$HOME/.edgemicro
にある Edge Microgateway 構成ファイルを base64 エンコードします。export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`
ここで、
your_org
とyour_env
は、edgemicro config
コマンドを実行したときに使用した組織と環境です。コマンドの前後に必ずバッククォート(`)を付けてください。例:
export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
次のコマンドを実行して、Docker コンテナで Edge Microgateway を起動します。
chown -R 100:101 ~/.edgemicro/ \ docker run -P -p 8443:8443 -d --name edgemicro \ -v path_to_your_edgemicro_dir:/opt/apigee/.edgemicro \ -v path_to_your_logs_dir:/opt/apigee/logs \ -e EDGEMICRO_PORT=8443 \ -e EDGEMICRO_ORG=$EDGEMICRO_ORG \ -e EDGEMICRO_ENV=$EDGEMICRO_ENV \ -e EDGEMICRO_KEY=$EDGEMICRO_KEY \ -e EDGEMICRO_SECRET=$EDGEMICRO_SECRET \ -e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \ --link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro
5. TLS 構成をテストする
次の cURL コマンドを実行して設定をテストします。これらは、Microgateway 対応プロキシに使用したベースパスと、Apigee Edge で作成したデベロッパー アプリから取得した API キーに置き換えます。例:
curl https://localhost:8443/local -k -H "x-api-key: xxxx" -v
次のエラーが表示されます。
... * subject: C=CA; ST=Ontario; L=Toronto; O=Google Canada; OU=Google Cloud Platform; CN=edgemicro; emailAddress=srinandans@google.com * start date: Dec 10 02:12:22 2018 GMT * expire date: Sep 29 02:12:22 2021 GMT * issuer: C=CA; ST=Ontario; L=Toronto; O=Google Canada; OU=Google Cloud Platform; CN=edgemicro; emailAddress=srinandans@google.com * SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway. > GET /local HTTP/1.1 > Host: localhost:8443 > User-Agent: curl/7.54.0 > Accept: */* > x-api-key: 9fVC65pFj8LrmlPmVyxFjx4KgAHTxqSd > < HTTP/1.1 502 Bad Gateway < Date: Wed, 12 Dec 2018 05:25:01 GMT < Connection: keep-alive < Content-Length: 93 < * Connection #0 to host localhost left intact {"message":"unable to verify the first certificate","code":"UNABLE_TO_VERIFY_LEAF_SIGNATURE"}
Edge Microgateway を再実行します。ただし、今回は
NODE_EXTRA_CA_CERTS
変数を追加します。chown -R 100:101 ~/.edgemicro/ \ docker run -P -p 8443:8443 -d --name edgemicro \ -v path_to_your_edgemicro_dir:/opt/apigee/.edgemicro \ -v path_to_your_logs_dir:/opt/apigee/logs \ -e NODE_EXTRA_CA_CERTS=/opt/apigee/.edgemicro/rootca.pem \ -e EDGEMICRO_PORT=8443 \ -e EDGEMICRO_ORG=$EDGEMICRO_ORG \ -e EDGEMICRO_ENV=$EDGEMICRO_ENV \ -e EDGEMICRO_KEY=$EDGEMICRO_KEY \ -e EDGEMICRO_SECRET=$EDGEMICRO_SECRET \ -e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \ --link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro
次の cURL コマンドを実行します。ベースパスと API キーは、前と同じように置き換えてください。例:
curl https://localhost:8443/local -k -H "x-api-key: xxxx" -v
出力を確認します。成功すると、HTTP 200 ステータス レスポンスが返されます。
... > GET /local HTTP/1.1 > Host: localhost:8443 > User-Agent: curl/7.54.0 > Accept: */* > x-api-key: 9fVC65pFj8LrmlPmVyxFjx4KgAHTxqSd > < HTTP/1.1 200 OK < x-powered-by: Express < content-type: text/html; charset=utf-8 < etag: W/"c-M6tWOb/Y57lesdjQuHeB1P/qTV0" < date: Wed, 12 Dec 2018 05:49:28 GMT < x-response-time: 421 < Connection: keep-alive < Transfer-Encoding: chunked < Hello world
カスタム プラグインの追加
カスタム プラグインを作成することで、Microgateway に新しい機能を追加できます。カスタム プラグインを使用すると、Microgateway を通過するリクエストやレスポンスをプログラムで操作できます。
Docker コンテナで実行されている Edge Microgateway インスタンスにプラグインをデプロイする方法は 2 つあります。
このセクションの残りの部分は、標準の Edge Microgateway 設定のためのプラグインの作成と構成に精通していることを前提としています。そうでない場合は、カスタム プラグインを開発するをご覧ください。
オプション A: plugins ディレクトリをボリュームにマウントする
(v.2.5.27 で追加)ボリューム マウントを使用してプラグインを追加する手順は、Edge Microgateway にカスタム プラグインを追加するために必要な手順と似ています。Docker コンテナを実行するときに、ローカル システム(ボリューム)の plugins ディレクトリをコンテナのマウント ポイント(
/opt/apigee/plugins
)にマウントできます。その後、Edge Microgateway 構成ファイルでローカル ボリューム ディレクトリを指定します。Docker のマウント ポイントを使用してカスタム プラグインを含める方法を、次の手順に示します。
Edge Microgateway を停止します。
edgemicro stop
カスタム プラグイン用のディレクトリを作成します。たとえば、
$HOME/edgemicro/custom/plugins
カスタム プラグイン ディレクトリを Edge Microgateway 構成ファイルに追加します。例:
plugins: dir: $HOME/edgemicro/custom/plugins sequence: - oauth - response-uppercase ````
シンプルなプラグインを作成するの手順に沿ってプラグインを作成し、テストします。プラグインのコードは必ず適切なディレクトリ構造に配置してください。例:
custom | |-- plugins | |- response-uppercase | |- index.js | |- package.json |- request-headers | | - index.js | - package.json
次のようなコマンドで Docker コンテナを実行します。ここで、
-v
オプションを使用して Docker ボリュームに plugins ディレクトリをマウントします。次のコマンドの例では、カスタム プラグインが配置されているプラグイン ディレクトリ$HOME/edgemicro/custom/plugins
がコンテナのマウント ポイント/opt/apigee/plugins
にマッピングされています。chown -R 100:101 ~/.edgemicro/ \ docker run -P -p 8000:8000 -d --name edgemicro \ -v /var/tmp:/opt/apigee/logs \ -v $HOME/edgemicro/custom/plugins:/opt/apigee/plugins \ -e EDGEMICRO_PROCESSES=1 \ -e EDGEMICRO_ORG=jdoe \ -e EDGEMICRO_ENV=test \ -e EDGEMICRO_KEY=39c4b561100cd7f258768d1072f3e1d7c17b5f36a18fe89972bb5c9ce7e58fb \ -e EDGEMICRO_SECRET=f5f9e239a38b4e6cc99c2aa067716a84aebdcff9580a7925fc500e402b1a5fa \ -e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \ -e SERVICE_NAME=edgemicro \ --security-opt=no-new-privileges \ --cap-drop=ALL gcr.io/apigee-microgateway/edgemicro:latest
API を呼び出してプラグインをテストします。
詳細については、VOLUME [共有ファイルシステム] をご覧ください。
オプション B: プラグインをコンテナに組み込む
このオプションでは、プラグインをコンテナに組み込みます。
1. プラグインをパッケージ化する
シンプルなプラグインを作成するの手順に沿ってプラグインを作成し、テストします。
プラグインのコードを適切なディレクトリ構造に配置します。プラグイン ディレクトリは、設定された構造に従う必要があります。次の例は従う必要がある構造を示しています。ここで、
response-uppercase
とrequest-headers
は、カスタム プラグイン コードを含むフォルダの名前です(これらは単なる例であり、フォルダ名は異なる場合があります)。plugin | |-- plugins | |- response-uppercase | |- index.js | |- package.json |- request-headers | | - index.js | - package.json
cd
でplugin
フォルダに移動します。plugin
フォルダで、plugins
フォルダ全体を zip 圧縮します。zip -r plugins.zip plugins/
2. Docker イメージを作成する
次に、Dockerfile を作成して、プラグイン コードを Edge Microgateway イメージに追加します。
- zip ファイルと同じディレクトリに、
Dockerfile
という名前の新しいファイルを作成します。 次のコードを
Dockerfile
に追加し、ファイルを保存します。USER root RUN apk update && \ apk upgrade && \ apk add zipapk add zip && \ mkdir /opt/apigee/customplugins && \ chown apigee:apigee /opt/apigee/customplugins COPY plugins.zip /opt/apigee/customplugins RUN su - apigee -c "unzip /opt/apigee/customplugins/plugins.zip -d /opt/apigee/customplugins" EXPOSE 8000 EXPOSE 8443 USER apigee ENTRYPOINT ["entrypoint"]
プラグインを含む新しい Edge Microgateway Docker イメージを作成します。
docker build -t image-name .
例:
docker build -t edgemicroplugins .
3. Edge Microgateway 構成を更新する
プラグインがパッケージ化されたので、Edge Microgateway 構成ファイルに追加する必要があります。
エディタで Edge Microgateway 構成ファイルを開きます。
$HOME/.edgemicro/org-env-config.yaml
例:
vi $HOME/.edgemicro/myorg-test-config.yaml
プラグイン ディレクトリを構成ファイルに追加します。次の例では、
dir
属性にプラグイン コード(Dockerfile で指定した)の場所を指定しています。プラグイン ディレクトリの名前も指定する必要があります。以下の例では、response-uppercase
です。edgemicro: ... plugins: dir: /opt/apigee/plugins sequence: - oauth - response-uppercase
4. microgateway を起動する
最後に、コンテナで microgateway を起動する必要があります。
次のコマンドを実行して、
$HOME/.edgemicro
にある Edge Microgateway 構成ファイルを base64 エンコードします。export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`
ここで、
your_org
とyour_env
は、edgemicro config
コマンドを実行したときに使用した組織と環境です。コマンドの前後に必ずバッククォート(`)を付けてください。例:
export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
Edge Microgateway をコンテナとして実行します。このコマンドでは、コンテナ ランタイムが Edge Microgateway を起動する際に使用するいくつかの環境変数を設定します。
docker run -P -p 8000:8000 -d --name edgemicroplugins \ -e EDGEMICRO_PLUGIN_DIR=/opt/apigee/customplugins/plugins \ -e EDGEMICRO_ORG=your_org \ -e EDGEMICRO_ENV=your_env \ -e EDGEMICRO_KEY=your_key \ -e EDGEMICRO_SECRET=your_secret \ -e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \ -e SERVICE_NAME=edgemicroplugins image_name
例:
docker run -P -p 8000:8000 -d --name edgemicroplugins \ -e EDGEMICRO_PLUGIN_DIR=/opt/apigee/customplugins/plugins \ -e EDGEMICRO_ORG=docs \ -e EDGEMICRO_ENV=test \ -e EDGEMICRO_KEY=d9c34e1aff68ed969273b016699eabf48780e4f652242e72fc88a23e21252cb0 \ -e EDGEMICRO_SECRET=3bc95a71c86a3c8ce04137fbcb788158731t51dfc6cdec13b7c05aa0bd969430 \ -e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \ -e SERVICE_NAME=edgemicroplugins edgemicroplugins
API を呼び出してプラグインをテストします。
プラグイン コードの実行をテストするために、次のように API を呼び出し、出力が想定どおりであることを確認します。
curl -i http://localhost:8000/hello -H "x-api-key:apikey"
たとえば、
response-uppercase
プラグインから次のようなレスポンスが返されます。curl -i http://localhost:8000/hello -H "x-api-key:PydUKRDGIXRqF2xh4usn1FLHbhGKVIz" HELLO, WORLD!