为 Edge Microgate 使用 Docker

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档
信息

本主题介绍如何在 Docker 容器中运行 Edge Microgate。本主题中介绍的步骤假定您对 Docker、Docker 命令以及 Edge Microgate 设置和配置有基本的了解。如需了解详情,请参阅 DockerEdge Microgate 文档。

前提条件

在 Docker 容器中运行 Edge Microgate 之前,您必须执行以下任务:

  • 为您的 Apigee 组织/环境配置 Edge Microgate:

    edgemicro configure -o your_org -e your_env -u your_username

    如需详细了解配置,请参阅第 1 部分:配置 Edge Microgate

  • 执行配置步骤后,找到配置文件。默认位置如下:

    $HOME/.edgemicro/your_org-your_env-config.yaml

    其中,your_orgyour_env 是您运行 edgemicro config 命令时使用的组织和环境。在 Docker 容器中启动 Edge Microgate 时,您需要用到此文件。

  • 请确保您拥有运行 edgemicro config 命令时返回的密钥和密钥凭据。例如:

    The following credentials are required to start edge micro
      key: d9c34e1aff68ed969273c016699eabf48780e4f652242e72fc88a43e21252cb0
      secret: 3bc95a71c86a3c8ce04537fbcb788158731t51dfc6cdec13b7c05aa0bd969430
    
  • 在 Docker 容器中启动 Edge Microgate 之前,您需要创建(或已创建)进行经过身份验证的 API 代理调用所需的 Apigee Edge 实体。这些实体包括 Edge Microgate 感知代理、API 产品、开发者和开发者应用。如需查看完整说明,请参阅在 Apigee Edge 上创建实体

将 Edge Micro 作为 Docker 容器运行

  1. 下载适用于 Edge Microgate 的 Docker 映像:

    docker pull gcr.io/apigee-microgateway/edgemicro:latest
  2. 在继续执行后续步骤之前,请确保您已执行前提条件部分中的所有步骤。

  3. 运行以下命令,对 $HOME/.edgemicro 中的 Edge Microgate 配置文件进行 base64 编码:

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`

    其中,your_orgyour_env 是您运行 edgemicro config 命令时使用的组织和环境。

    请务必在命令前后加上反引号 (`)。例如:

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
  4. 将 Edge Microgate 作为容器运行。该命令设置多个环境变量,供容器运行时用于启动 Edge Microgate:

    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 指定卷装载。请注意,如果您将 Edge Microgate 配置为在 Docker 容器中使用 TLS,则必须在装载日志文件目录时公开端口 8443。另请参阅 VOLUME [共享文件系统]。另请参阅在 Docker 容器中使用 TLS
    -w, -- workdir (可选)指定应在其中创建 edgemicro.sockedgemicro.pid 文件的目录的路径。您无法修改文件名根目录 edgemicro。默认为当前工作目录路径。

    示例:

    docker run -P -p 8000:8000 -d -w /tmp --name edgemicro 
    ...
    EDGEMICRO_ORG 您用于配置 Edge Microgate 的 Apigee 组织的名称。
    EDGEMICRO_ENV 您用于配置 Edge Microgate 的 Apigee 环境的名称。
    EDGEMICRO_PROCESSES 要启动的进程数。
    EDGEMICRO_KEY 配置 Edge Microgate 时返回的密钥。
    EDGEMICRO_SECRET 配置 Edge Microgate 时返回的密钥。
    EDGEMICRO_CONFIG 包含 base64 编码的 Edge Microgate 配置文件的变量。
    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 Microgate 配置参数 to_console,您可以选择将日志信息发送到标准输出文件,而不是发送到日志文件。如果您按照相关步骤在 Docker 容器中运行 Edge Microgate,该容器默认会将 stdout 和错误输出重定向到位于该容器内的一个文件:${APIGEE_ROOT}/logs/edgemicro.log

    为防止将日志信息发送到 edgemicro.log,请在运行容器时使用 LOG_CONSOLE_OUTPUT_TO_FILE 变量。

    下表介绍了将 LOG_CONSOLE_OUTPUT_TO_FILEto_console 搭配使用时的日志输出行为:

    to_console: true

    LOG_CONSOLE_OUTPUT_TO_FILE=false

    • 管理日志文件中所述,系统不会向 Edge Microgate 日志文件发送任何日志。
    • 日志不会发送到 edgemicro.log 文件。
    to_console: true

    LOG_CONSOLE_OUTPUT_TO_FILE=true

    • 管理日志文件中所述,系统不会向 Edge Microgate 日志文件发送任何日志。
    • 日志将发送到 edgemicro.log 文件。
    to_console: false

    LOG_CONSOLE_OUTPUT_TO_FILE=true

    • 管理日志文件中所述,日志将发送到 Edge Microgate 日志文件。
    • 日志将发送到 edgemicro.log 文件。

    测试 API 调用

    在容器中启动 Edge Microgate 后,您可以对其进行 API 调用。例如,如果 API 的基本路径是 /hello

    http://localhost:8000/hello

    示例输出:

    {"error":"missing_authorization","error_description":"Missing Authorization header"}
    

    如果您看到此响应,则表示 Edge Microgate 已成功处理 API 调用。但是,默认情况下,Edge Microgate 需要 API 密钥进行身份验证。在下一部分中,您将使用有效的 API 密钥测试 API。

    使用有效的 API 密钥测试 API

    在 Edge 界面中,转到您之前创建的开发者应用。在“开发者应用”页面中,显示并复制使用方密钥。此值就是 API 密钥。您将使用此密钥进行经过身份验证的 API 调用。

    使用 x-api-key 标头调用 API,如下所示。您从开发者应用中复制的使用方键值就是 API 密钥。默认情况下,Edge Microgate 要求您在名为 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 Microgate 进行经过身份验证的 API 调用,请参阅第 4 部分:安全 Edge Microgate

    停止 Edge Microgate

    使用以下 Docker 命令停止 Edge Microgate:

    docker stop edgemicro
    

    重启 Edge Microgate

    停止 Edge Microgate 后,您可以使用以下 Docker 命令将其重启:

    docker start edgemicro
    

    在 Docker 容器中使用 TLS

    本部分介绍如何为 Docker 容器中运行的 Edge Microgate 配置 TLS。您可以将 Edge Microgate 服务器配置为对传入请求使用 TLS(北向方向),而将 Edge Microgate 配置为发送到目标端点的传出请求(南向方向)的 TLS 客户端。

    证书文件的存放位置

    运行 Edge Microgate 的 Docker 容器在 /opt/apigee/.edgemicro 上有一个装载点。将 Edge Microgate 配置为使用 TLS 证书时,您可以在该装载点上提供证书文件,并在 Edge Microgate 配置文件中引用它们。此配置文件通常位于 $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

    请将此参数设置为包含一个或多个 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 Microgate 停用 TLS 验证。默认情况下,Edge Microgate Docker 容器中不会内置停用 TLS 的功能。如需完成该任务,您必须为 Edge Microgate 创建自定义 Docker 映像。以下是构建自定义映像和关闭 TLS 验证的常规说明。

    1. https://github.com/apigee-internal/microgateway 克隆或下载 Edge Microgate 源代码库。

    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 Microgate 服务器上设置北向(传入)TLS 连接。北向 TLS 允许客户端在对 Edge Microgate 进行 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 Microgate(如果您尚未这样做)。完成后,您应该已经创建了一个 Edge Microgate 感知代理、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 Microgate 配置文件

    1. 在编辑器中打开 Edge Micro 配置文件。例如:

      vi $HOME/.edgemicro/myorg-test-config.yaml
      
    2. 按如下方式修改 edgemicro 节。请注意,您将更改 portssl 属性:

      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. 执行以下命令,对位于 $HOME/.edgemicro 中的 Edge Microgate 配置文件进行 base64 编码:

      export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`

      其中,your_orgyour_env 是您运行 edgemicro config 命令时使用的组织和环境。

      请务必在命令前后加上反引号 (`)。例如:

      export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`

    另请参阅将 Edge Micro 作为 Docker 容器运行

    4. 运行容器

    1. 执行以下命令以使用 Edge Microgate 运行 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. 请注意命令中使用的以下参数;这些参数与将 Edge Micro 作为 Docker 容器运行中所述的基本命令不同。

      • port 设置为 8443
      • 卷装载用于装载密钥和证书文件。
      • NODE_EXTRA_CA_CERTS 变量用于添加自定义 CA(在自签名证书的情况下需要)。

    5. 测试 TLS 配置

    1. 执行以下 c网址 命令以测试设置。在命令中替换基本路径和 API 密钥。以下示例假定您位于 rootca.pem 所在的目录中,并且您创建的代理具有基本路径 /hello

      curl -v https://localhost:8443/hello --cacert rootca.pem \
      -H "x-api-key: Az82fdnfONVCOOE4NKhajxAboDgA3FAo"
      
    2. 详细的 c网址 输出显示了 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 Microgate 服务器和后端目标应用之间设置南向(传出)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 Microgate

    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 Microgate 感知型代理。如需了解详情,请参阅在 Edge 上创建 Edge Microgate 感知型 API 代理

      • 代理名称:edgemicro_local
      • 修订版本:1
      • 基本路径:/local
      • 目标:https://helloworld:9443
    2. 创建 API 产品。如需了解详情,请参阅创建商品

    3. 创建开发者。有关详情,请参阅创建开发者

    4. 创建开发者应用。如需了解详情,请参阅创建开发者应用

    4. 运行容器

    1. 在编辑器中打开 Edge Micro 配置文件。例如:

      vi $HOME/.edgemicro/myorg-test-config.yaml
      
    2. 按如下方式修改 edgemicro 节。请注意,您将更改 portssl 属性:

      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. 执行以下命令,对位于 $HOME/.edgemicro 中的 Edge Microgate 配置文件进行 base64 编码:

      export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`

      其中,your_orgyour_env 是您运行 edgemicro config 命令时使用的组织和环境。

      请务必在命令前后加上反引号 (`)。例如:

      export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
    4. 运行以下命令,以在 Docker 容器中启动 Edge Microgate。

      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. 执行以下 c网址 命令以测试设置。请将您在微网关感知型代理中使用的基本路径以及从您在 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 Microgate,但这次请添加 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. 执行以下 c网址 命令。和之前一样替换您的基本路径和 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 Microgate 实例:

    本部分的其余内容假定您熟悉为标准 Edge Microgate 设置编写和配置插件的方法。如果没有,请参阅开发自定义插件

    方法 A:在卷上装载插件目录

    (在 v.2.5.27 中添加)通过卷装载添加插件的步骤与将任何自定义插件添加到 Edge Microgate 所需的步骤类似。运行 Docker 容器时,您可以将本地系统上的插件目录(卷)装载到容器装载点(即 /opt/apigee/plugins)上。然后,您可以在 Edge Microgate 配置文件中指定本地卷目录。

    以下步骤说明了如何使用 Docker 装载点来包含自定义插件。

    1. 停止 Edge Microgate:

      edgemicro stop
      
    2. 为您的自定义插件创建一个目录。例如,

      $HOME/edgemicro/custom/plugins
      
    3. 将自定义插件目录添加到 Edge Microgate 配置文件。例如:

        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 以测试插件。

    如需了解详情,请参阅卷 [共享文件系统]

    方法 B:将插件构建到容器中

    在此方案中,您可以将插件构建到容器中。

    1. 打包插件

    1. 按照编写一个简单的插件中的说明编写并测试您的插件。

    2. 将插件代码放置在适当的目录结构中。插件目录必须遵循设定的结构。以下示例展示了您必须遵循的结构,其中 response-uppercaserequest-headers 是包含自定义插件代码的文件夹的名称(这些名称仅作为示例,您的文件夹名称可能有所不同):

      plugin
        |
        |-- plugins
          |
          |- response-uppercase
          |     |- index.js
          |     |- package.json
          |- request-headers
          |     | - index.js
                | - package.json
      
    3. cdplugin 文件夹。

    4. plugin 文件夹中,压缩整个 plugins 文件夹:

      zip -r plugins.zip plugins/

    2. 创建 Docker 映像

    接下来,创建一个 Dockerfile,以将插件代码添加到 Edge Microgate 映像。

    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 Microgate Docker 映像:

      docker build -t image-name .
      

      例如:

      docker build -t edgemicroplugins .
      

    3. 更新 Edge Microgate 配置

    现在,这些插件已打包,您需要将其添加到 Edge Microgate 配置文件中。

    1. 在编辑器中打开 Edge Microgate 配置文件:

      $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. 运行以下命令,对 $HOME/.edgemicro 中的 Edge Microgate 配置文件进行 base64 编码:

      export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`

      其中,your_orgyour_env 是您运行 edgemicro config 命令时使用的组织和环境。

      请务必在命令前后加上反引号 (`)。例如:

      export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
    2. 将 Edge Microgate 作为容器运行。该命令设置多个环境变量,供容器运行时用于启动 Edge Microgate:

      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!