使用適用於 Edge Microgateway 的 Docker

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

本主題說明如何在 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 之前，您需要建立 (或已建立) Apigee Edge 實體，才能進行已驗證的 API Proxy 呼叫。這些實體包括 Edge Microgateway 感知的 Proxy、API 產品、開發人員和開發人員應用程式。如需完整操作說明，請參閱「在 Apigee Edge 上建立實體」。

以 Docker 容器形式執行 Edge Micro

  1. 下載 Edge Microgateway 的 Docker 映像檔：

    docker pull gcr.io/apigee-microgateway/edgemicro:latest

  2. 繼續進行後續步驟前，請務必先完成「必要條件」一節中的所有步驟。

  3. 執行下列指令，以 base64 編碼位於 $HOME/.edgemicro 的 Edge Microgateway 設定檔：

    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`

  4. 以容器形式執行 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 執行參考資料。
    -p 明確對應單一通訊埠或通訊埠範圍。另請參閱 Docker 執行參考資料。
    -d 以分離模式執行。另請參閱 Docker 執行參考資料。
    -v, -- volume 指定磁碟區掛接項目。請注意，如果在 Docker 容器中設定 Edge Microgateway 使用 TLS，則必須掛接記錄檔目錄，並公開通訊埠 8443。另請參閱「VOLUME [shared filesystems]」。另請參閱「在 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

    1. 如要確認容器正在執行：

      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 變數。

    下表說明搭配使用 LOG_CONSOLE_OUTPUT_TO_FILE 和 to_console 時的記錄輸出行為：

    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 的 basepath 是 /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 中，前往先前建立的開發人員應用程式。在「開發人員應用程式」頁面中，顯示並複製「消費者金鑰」。這個值是 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"

    如要進一步瞭解如何透過 Edge Microgateway，使用 API 金鑰和 OAuth 權杖發出經過驗證的 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。您可以將 Edge Microgateway 伺服器設為使用 TLS 處理傳入要求 (北向)，也可以將 Edge Microgateway 設為 TLS 用戶端，處理傳送至目標端點的要求 (南向)。

    憑證檔案的放置位置

    執行 Edge Microgateway 的 Docker 容器在 /opt/apigee/.edgemicro 上有掛接點。 將 Edge Microgateway 設定為使用 TLS 憑證時，您可以在該掛接點提供憑證檔案，並在 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

    如果您使用的憑證授權單位 (CA) 並非 Node.js 預設信任的對象 (例如自行簽署的憑證)，請考慮在執行容器時使用 NODE_EXTRA_CA_CERTS 參數。

    將這個參數設為檔案路徑，其中包含一或多個 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

    另請參閱以 Docker 容器形式執行 Edge Microgateway。

    關閉 TLS 驗證

    雖然不建議這麼做，但在某些情況下，您可能會想為在容器中執行的 Edge Microgateway 停用 TLS 驗證。Edge Microgateway Docker 容器預設不會內建停用 TLS 的功能。如要完成這項工作，您必須為 Edge Microgateway 建立自訂 Docker 映像檔。以下是建構自訂映像檔及關閉 TLS 驗證的一般操作說明。

    1. 從 https://github.com/apigee-internal/microgateway 複製或下載 Edge Microgateway 來源存放區。

    2. cd 原始碼目錄中的 microgateway/kubernetes/docker/edgemicro 目錄。

      例如：

      cd $HOME/git/microgateway/kubernetes/docker/edgemicro

    3. 開啟 entrypoint.sh 檔案並修改程式碼，接受 NODE_TLS_REJECT_UNAUTHORIZED 環境變數。稍後執行容器時，您將指定這個變數的值。

    4. 建構 Docker 容器：

      docker build -t edgemicro .

    5. 執行容器時，請指定 -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. 初始設定步驟

    1. 在系統中找出 openssl.cnf 檔案。例如：/etc/ssl/openssl.cnf。
    2. 開啟 opensssl.cnf 檔案進行編輯。

    3. 請確認設定檔中是否含有 req_extensions。舉例來說，檔案中應包含類似下列的資訊：

      [ req ]
...
req_extensions          = v3_req
...

[ v3_req ]
extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

    4. 在 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

    5. 如果尚未初始化及設定 Edge Microgateway，請按照「必要條件」一節中的步驟操作。完成後，您應該已建立 Edge Microgateway 感知的 Proxy、API 產品、開發人員和開發人員應用程式。此外，您也應該已執行 edgemicro configure 指令，並收到金鑰和密碼。

    2. 產生自行簽署的憑證

    接著，產生建立 TLS 時所需的憑證和金鑰：

    1. cd $HOME/.edgemicro 目錄。

    2. 建立下列 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

    3. 在 bash 檔案中，確認 openssl.cnf 檔案的路徑正確無誤。

    4. 執行 bash 檔案。系統會提示您輸入憑證資訊。請務必使用 localhost 做為通用名稱。

    5. 確認是否已建立下列檔案：

      • rootca.key
      • rootca.pem
      • tls.key
      • tls.csr
      • rootca.srl
      • tls.crt

    3. 編輯 Edge Microgateway 設定檔

    1. 在編輯器中開啟 Edge Micro 設定檔。例如：

      vi $HOME/.edgemicro/myorg-test-config.yaml

    2. 按照下列方式編輯 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:
...

    3. 執行下列指令，以 base64 編碼位於 $HOME/.edgemicro 的 Edge Microgateway 設定檔：

      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」。

    4. 執行容器

    1. 執行下列指令，使用 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

    2. 請注意指令中使用的下列參數，這些參數與「以 Docker 容器形式執行 Edge Microgateway」一節中說明的基本指令不同。

      • port 設為 8443。
      • 磁碟區掛接用於掛接金鑰和憑證檔案。
      • NODE_EXTRA_CA_CERTS 變數用於新增自訂 CA (自行簽署憑證時需要)。

    5. 測試 TLS 設定

    1. 執行下列 cURL 指令，測試設定。將指令中的 basepath 和 API 金鑰替換成您的值。以下範例假設您位於 rootca.pem 所在的目錄，且您建立的 Proxy 具有 /hello 的 basepath：

      curl -v https://localhost:8443/hello --cacert rootca.pem \
-H "x-api-key: Az82fdnfONVCOOE4NKhajxAboDgA3FAo"

    2. 詳細的 cURL 輸出會顯示 TLS 交握的每個步驟。如果看到 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. 初始設定步驟

    1. 在系統中找出 openssl.cnf 檔案。例如：/etc/ssl/openssl.cnf。
    2. 開啟 opensssl.cnf 檔案進行編輯。

    3. 請確認設定檔中是否含有 req_extensions。舉例來說，檔案中應包含類似下列的資訊：

      [ req ]
...
req_extensions          = v3_req
...

[ v3_req ]
extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

    4. 在 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

    5. 執行 edgemicro configure 指令：

      edgemicro configure -o your_org -e your_env -u your_username

      如要進一步瞭解設定，請參閱「第 1 部分：設定 Edge Microgateway」。

    6. 複製 edgemicro configure 傳回的金鑰和密鑰憑證。您需要這些值才能執行容器。例如：

      The following credentials are required to start edge micro
  key: d9c34e1aff68ed969273c016699eabf48780e4f652242e72fc88a43e21252cb0
  secret: 3bc95a71c86a3c8ce04537fbcb788158731t51dfc6cdec13b7c05aa0bd969430

    2. 建立 Node.js 目標應用程式

    1. cd .edgemicro目錄。

    2. 建立下列 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

    3. 在 bash 檔案中，確認 openssl.cnf 檔案的路徑正確無誤。

    4. 執行 bash 檔案。系統會提示您輸入憑證資訊。請務必使用 hellworld 做為通用名稱。

    5. 確認是否已建立下列檔案：

      • rootca.key
      • rootca.pem
      • tls.key
      • tls.csr
      • rootca.srl
      • tls.crt

    6. 建立名為 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);

    7. 在 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"
  }
}

    8. 執行 npm install 取得依附元件。

    9. 在與 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" ]

    10. 建構 Docker 映像檔：

      docker build -t helloworld .

    11. 啟動範例應用程式：

      docker run -P -p 9443:9443 --name helloworld helloworld

    3. 在 Apigee Edge 建立實體

    1. 使用下列設定建立 Edge Microgateway 感知的 Proxy。詳情請參閱「在 Edge 上建立 Edge Microgateway 感知的 API Proxy」。

      • Proxy 名稱：edgemicro_local
      • 修訂：1
      • Basepath：/local
      • 目標：https://helloworld:9443

    2. 建立 API 產品。詳情請參閱「建立產品」一文。

    3. 建立開發人員。詳情請參閱「建立開發人員」一文。

    4. 建立開發人員應用程式。詳情請參閱建立開發人員應用程式

    4. 執行容器

    1. 在編輯器中開啟 Edge Micro 設定檔。例如：

      vi $HOME/.edgemicro/myorg-test-config.yaml

    2. 按照下列方式編輯 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:
...

    3. 執行下列指令，以 base64 編碼位於 $HOME/.edgemicro 的 Edge Microgateway 設定檔：

      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`

    4. 執行下列指令，在 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 設定

    1. 執行下列 cURL 指令，測試設定。請代入您在微閘感知 Proxy 中使用的 basepath，以及從 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"}

    2. 重新執行 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

    3. 執行下列 cURL 指令。如先前所述，請代入您的 basepath 和 API 金鑰。例如：

      curl https://localhost:8443/local -k -H "x-api-key: xxxx" -v

    4. 檢查輸出內容。成功時，您會收到 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

    新增自訂外掛程式

    您可以編寫自訂外掛程式，為微型閘道新增功能。透過自訂外掛程式，您可以透過程式輔助方式，與流經微型閘道的請求和回應互動。

    如要將外掛程式部署至 Docker 容器中執行的 Edge Microgateway 執行個體，有兩種做法：

    本節的其餘部分假設您已熟悉如何為標準 Edge Microgateway 設定編寫及設定外掛程式。如果沒有，請參閱「開發自訂外掛程式」。

    方法 A：將外掛程式目錄掛接至磁碟區

    (2.5.27 版新增) 透過磁碟區掛接新增外掛程式的步驟，與在 Edge Microgateway 中新增任何自訂外掛程式的步驟類似。執行 Docker 容器時，您可以在容器掛接點 (即 /opt/apigee/plugins) 掛接本機系統上的外掛程式目錄 (磁碟區)。然後在 Edge Microgateway 設定檔中指定本機磁碟區目錄。

    下列步驟說明如何使用 Docker 掛接點加入自訂外掛程式。

    1. 停止 Edge Microgateway：

      edgemicro stop

    2. 為自訂外掛程式建立目錄。舉例來說，建立

      $HOME/edgemicro/custom/plugins

    3. 將自訂外掛程式目錄新增至 Edge Microgateway 設定檔。例如：

        plugins:
    dir: $HOME/edgemicro/custom/plugins
    sequence:
      - oauth
      - response-uppercase
  ````

    4. 按照「撰寫簡單的外掛程式」中的指示，編寫及測試外掛程式。請務必將外掛程式碼放在正確的目錄結構中。例如：

      custom
  |
  |-- plugins
    |
    |- response-uppercase
    |     |- index.js
    |     |- package.json
    |- request-headers
    |     | - index.js
          | - package.json

    5. 執行類似下列的指令，啟動 Docker 容器，並使用 -v 選項將外掛程式目錄掛接至 Docker 磁碟區。在下列範例指令中，外掛程式目錄 $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

    6. 呼叫 API 來測試外掛程式。

    詳情請參閱「VOLUME [shared filesystems]」。

    方法 B：將外掛程式建構至容器

    在這個選項中，您會將外掛程式建構到容器中。

    1. 封裝外掛程式

    1. 按照「撰寫簡單的外掛程式」中的指示，編寫及測試外掛程式。

    2. 將外掛程式碼放在適當的目錄結構中。外掛程式目錄必須遵循特定結構。以下範例顯示您必須遵循的結構，其中 response-uppercase 和 request-headers 是包含自訂外掛程式碼的資料夾名稱 (這些名稱僅為範例，您的資料夾名稱可能不同)：

      plugin
  |
  |-- plugins
    |
    |- response-uppercase
    |     |- index.js
    |     |- package.json
    |- request-headers
    |     | - index.js
          | - package.json

    3. cd至 plugin 資料夾。

    4. 在 plugin 資料夾中，將整個 plugins 資料夾壓縮成 ZIP 檔案：

      zip -r plugins.zip plugins/

    2. 建立 Docker 映像檔

    接著，請建立 Dockerfile，將外掛程式程式碼新增至 Edge Microgateway 映像檔。

    1. 在 ZIP 檔案所在的目錄中，建立名為 Dockerfile 的新檔案。

    2. 將下列程式碼新增至 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"]

    3. 使用外掛程式建立新的 Edge Microgateway Docker 映像檔：

      docker build -t image-name .

      例如：

      docker build -t edgemicroplugins .

    3. 更新 Edge Microgateway 設定

    外掛程式封裝完成後，您需要將外掛程式新增至 Edge Microgateway 設定檔。

    1. 在編輯器中開啟 Edge Microgateway 設定檔：

      $HOME/.edgemicro/org-env-config.yaml

      例如：

      vi $HOME/.edgemicro/myorg-test-config.yaml

    2. 將外掛程式目錄新增至設定檔。在下列範例中，dir 屬性會指定外掛程式碼的位置 (您在 Dockerfile 中指定的位置)。您也必須指定外掛程式目錄的名稱，在以下範例中為 response-uppercase。

      edgemicro:
  ...
  plugins:
    dir: /opt/apigee/plugins
    sequence:
      - oauth
      - response-uppercase

    4. 啟動微型閘道

    最後，您必須在容器中啟動微型閘道。

    1. 執行下列指令，以 base64 編碼位於 $HOME/.edgemicro 的 Edge Microgateway 設定檔：

      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`

    2. 以容器形式執行 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

    3. 呼叫 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!