Usa Docker para Edge Microgateway

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

En este tema, se explica cómo ejecutar Edge Microgateway en un contenedor de Docker. En los pasos que se abordan en este tema, se supone que tienes conocimientos básicos de Docker, los comandos de Docker y la configuración de Edge Microgateway. Para obtener más información, consulta la documentación de Docker y Edge Microgateway.

Requisitos previos

Antes de ejecutar Edge Microgateway en un contenedor de Docker, debes realizar las siguientes tareas:

  • Configura Edge Microgateway para la organización o el entorno de Apigee:

    edgemicro configure -o your_org -e your_env -u your_username

    Para obtener más detalles sobre la configuración, consulta la Parte 1: Configura Edge Microgateway.

  • Después de realizar los pasos de configuración, busca el archivo de configuración. La ubicación predeterminada es esta:

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

    En el ejemplo anterior, your_org y your_env son la organización y el entorno que usaste cuando ejecutaste el comando edgemicro config. Necesitarás este archivo cuando inicies Edge Microgateway en un contenedor de Docker.

  • Asegúrate de tener las credenciales de clave y secreto que se mostraron cuando ejecutaste el comando edgemicro config. Por ejemplo:

    The following credentials are required to start edge micro
      key: d9c34e1aff68ed969273c016699eabf48780e4f652242e72fc88a43e21252cb0
      secret: 3bc95a71c86a3c8ce04537fbcb788158731t51dfc6cdec13b7c05aa0bd969430
    
  • Antes de iniciar Edge Microgateway en un contenedor de Docker, debes crear (o haber creado) las entidades de Apigee Edge necesarias para realizar llamadas autenticadas de proxy a la API. Estas entidades incluyen un proxy compatible con Edge Microgateway, un producto de API, un desarrollador y una app de desarrollador. Para obtener instrucciones completas, consulta Crea entidades en Apigee Edge.

Ejecuta Edge Micro como un contenedor de Docker

  1. Descarga la imagen de Docker para Edge Microgateway:

    docker pull gcr.io/apigee-microgateway/edgemicro:latest
  2. Antes de continuar con los siguientes pasos, asegúrate de haber completado todos los pasos de la sección Requisitos previos.

  3. Ejecuta el siguiente comando para codificar en base64 el archivo de configuración de Edge Microgateway ubicado en $HOME/.edgemicro:

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

    En el ejemplo anterior, your_org y your_env son la organización y el entorno que usaste cuando ejecutaste el comando edgemicro config.

    Recuerda colocar comillas simples (`) alrededor del comando. Por ejemplo:

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
  4. Ejecuta Edge Microgateway como contenedor. Con el comando, se configuran varias variables de entorno que usa el entorno de ejecución del contenedor para iniciar 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

    Parámetros

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

    Parámetro Descripción
    -P Publica todos los puertos expuestos en el host. Consulta también la referencia de ejecución de Docker.
    -p Asigna de forma explícita un solo puerto o rango de puertos. Consulta también la referencia de ejecución de Docker.
    -d Se ejecuta en modo desconectado. Consulta también la referencia de ejecución de Docker.
    -v, -- volume Especifica una activación de volumen. Ten en cuenta que si configuras Edge Microgateway para usar TLS en el contenedor de Docker, debes exponer el puerto 8443 si activas el directorio de archivos de registro. Consulta también VOLUME [sistemas de archivos compartidos]. Consulta también Cómo usar TLS en el contenedor de Docker.
    -w, -- workdir Opcional: Especifica la ruta de acceso al directorio en el que se deben crear los archivos edgemicro.sock y edgemicro.pid. No puedes modificar la raíz del nombre de archivo edgemicro. El valor predeterminado es la ruta de acceso actual del directorio de trabajo.

    Ejemplo:

    docker run -P -p 8000:8000 -d -w /tmp --name edgemicro 
    ...
    EDGEMICRO_ORG El nombre de la organización de Apigee que usaste para configurar Edge Microgateway.
    EDGEMICRO_ENV El nombre del entorno de Apigee que usaste para configurar Edge Microgateway.
    EDGEMICRO_PROCESSES La cantidad de procesos que se deben iniciar.
    EDGEMICRO_KEY La clave que se mostró cuando configuraste Edge Microgateway.
    EDGEMICRO_SECRET El secreto que se mostró cuando configuraste Edge Microgateway.
    EDGEMICRO_CONFIG Una variable que contiene el archivo de configuración de Edge Microgateway codificado en base64.
    LOG_CONSOLE_OUTPUT_TO_FILE (Booleano) Te permite especificar adónde se envía el resultado del registro. Consulta Especifica las opciones de archivo de registro.

    Por ejemplo:

    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. Para verificar que el contenedor se esté ejecutando, sigue estos pasos:

      docker ps

      Deberías ver un resultado similar al siguiente:

      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
      

    Especifica las opciones de salida del archivo de registro

    El parámetro de configuración de Edge Microgateway to_console te permite elegir enviar información de registro a la salida estándar en lugar de a un archivo de registro. Si sigues los pasos para ejecutar Edge Microgateway en un contenedor de Docker, el contenedor redirecciona de forma predeterminada stdout y la salida de error a un archivo ubicado en el contenedor en la ubicación: ${APIGEE_ROOT}/logs/edgemicro.log.

    Para evitar que la información de registro se envíe a edgemicro.log, usa la variable LOG_CONSOLE_OUTPUT_TO_FILE cuando ejecutes el contenedor.

    En la siguiente tabla, se describe el comportamiento de los resultados del registro cuando usas LOG_CONSOLE_OUTPUT_TO_FILE con to_console:

    to_console: true

    LOG_CONSOLE_OUTPUT_TO_FILE=false

    • No se enviarán registros al archivo de registro de Edge Microgateway, como se describe en Administra archivos de registro.
    • No se enviarán los registros al archivo edgemicro.log.
    to_console: true

    LOG_CONSOLE_OUTPUT_TO_FILE=true

    • No se enviarán registros al archivo de registro de Edge Microgateway, como se describe en Administra archivos de registro.
    • Los registros se enviarán al archivo edgemicro.log.
    to_console: false

    LOG_CONSOLE_OUTPUT_TO_FILE=true

    • Los registros se enviarán al archivo de registro de Edge Microgateway, como se describe en Administra archivos de registro.
    • Los registros se enviarán al archivo edgemicro.log.

    Prueba una llamada a la API

    Después de iniciar Edge Microgateway en el contenedor, puedes realizar llamadas a la API. Por ejemplo, si la ruta base de tu API es /hello, haz lo siguiente:

    http://localhost:8000/hello

    Resultado de muestra:

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

    Si ves esta respuesta, significa que Edge Microgateway maneja correctamente la llamada a la API. Sin embargo, de forma predeterminada, Edge Microgateway requiere una clave de API para la autenticación. En la siguiente sección, probarás la API con una clave de API válida.

    Prueba una API con una clave de API válida

    En la IU de Edge, navega a la app de desarrollador que creaste anteriormente. En la página de la app para desarrolladores, muestra la clave de consumidor y cópiala. Este valor es la clave de API. Usarás esta clave para hacer llamadas autenticadas a la API.

    Llama a la API con el encabezado x-api-key como se indica a continuación. El valor de la clave de consumidor que copiaste de la app para desarrolladores es la clave de API. De forma predeterminada, Edge Microgateway espera que pases la clave en un encabezado llamado x-api-key, como el siguiente:

    curl -i http://localhost:8000/hello -H "x-api-key:apikey"

    Por ejemplo:

    curl -i http://localhost:8000/hello -H "x-api-key:PydUKRDGIXRqF2xh4usn1FLHbhGKVIz"

    Si deseas obtener más información para realizar llamadas a la API autenticadas a través de Edge Microgateway con claves de API y tokens de OAuth, consulta la Parte 4: Secure Edge Microgateway.

    Detén Edge Microgateway

    Usa el siguiente comando de Docker para detener Edge Microgateway:

    docker stop edgemicro
    

    Reinicia Edge Microgateway

    Después de detener Edge Microgateway, puedes reiniciarlo con este comando de Docker:

    docker start edgemicro
    

    Usa TLS en el contenedor de Docker

    En esta sección, se explica cómo configurar TLS para Edge Microgateway que se ejecuta en un contenedor de Docker. Puedes configurar el servidor de Edge Microgateway para usar TLS en las solicitudes entrantes (dirección hacia el norte) y puedes configurar Edge Microgateway como cliente de TLS para las solicitudes salientes a los extremos de destino (dirección hacia el sur).

    Dónde colocar los archivos de certificado

    El contenedor de Docker que ejecuta Edge Microgateway tiene un punto de activación en /opt/apigee/.edgemicro. Cuando configuras Edge Microgateway para usar certificados TLS, puedes hacer que los archivos de certificados estén disponibles en ese punto de activación y hacer referencia a ellos en el archivo de configuración de Edge Microgateway. Por lo general, este archivo de configuración se encuentra en el directorio $HOME/.edgemicro y se llama your_org-your_env-config.yaml. Por ejemplo:

    ...
    edgemicro:
      ssl:
       key: /opt/apigee/.edgemicro/southbound/tls.key
       cert: /opt/apigee/.edgemicro/southbound/tls.crt
    ...
    

    Uso de una CA que no sea de confianza para Node.js

    Si usas una autoridad certificadora (CA) que Node.js no confía de forma predeterminada (como en el caso de un certificado autofirmado), considera usar el parámetro NODE_EXTRA_CA_CERTS cuando ejecutes el contenedor.

    Establece este parámetro en la ruta de acceso a un archivo que contenga uno o más certificados de confianza en formato PEM. Para ver cómo se usa este parámetro, consulta los ejemplos Cómo configurar la TLS con dirección norte y Cómo configurar TLS con sentido sur.

    Por ejemplo:

    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
    

    Consulta también Ejecuta Edge Micro como un contenedor de Docker.

    Desactiva la validación de TLS

    Aunque no se recomienda, en algunos casos, es posible que desees inhabilitar la validación de TLS para Edge Microgateway que se ejecuta en un contenedor. La capacidad para inhabilitar TLS no está integrada en el contenedor de Docker de Edge Microgateway de forma predeterminada. A fin de realizar la tarea, debes crear una imagen de Docker personalizada para Edge Microgateway. A continuación, se incluyen instrucciones generales para compilar la imagen personalizada y desactivar la validación TLS.

    1. Clona o descarga el repositorio de código fuente de Edge Microgateway desde https://github.com/apigee-internal/microgateway.

    2. cd al directorio microgateway/kubernetes/docker/edgemicro en el directorio del código fuente.

      Por ejemplo:

      cd $HOME/git/microgateway/kubernetes/docker/edgemicro
      
    3. Abre el archivo entrypoint.sh y modifica el código para aceptar la variable de entorno NODE_TLS_REJECT_UNAUTHORIZED. Más adelante, cuando ejecutes el contenedor, especificarás un valor para esta variable.

    4. Compila el contenedor de Docker:

      docker build -t edgemicro .
      
    5. Cuando ejecutes el contenedor, especifica la opción -e NODE_TLS_REJECT_UNAUTHORIZED = 1. Por ejemplo:

    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
    

    Ejemplo: Cómo configurar TLS con dirección norte

    En esta sección, se explica cómo configurar una conexión TLS con dirección norte (entrante) en el servidor de Edge Microgateway. La TLS con el norte en la red permite que los clientes usen HTTPS cuando realizan llamadas a la API a Edge Microgateway. En el siguiente ejemplo, se usan certificados autofirmados.

    1. Pasos de configuración iniciales

    1. Ubica el archivo openssl.cnf en tu sistema. Por ejemplo, /etc/ssl/openssl.cnf
    2. Abre el archivo opensssl.cnf para editarlo.
    3. Asegúrate de que los req_extensions estén presentes en tu archivo de configuración. Por ejemplo, deberías tener información similar a la siguiente en tu archivo:

      [ req ]
      ...
      req_extensions          = v3_req
      ...
      
      [ v3_req ]
      extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
      basicConstraints = CA:FALSE
      keyUsage = nonRepudiation, digitalSignature, keyEncipherment
      
    4. Agrega la siguiente estrofa a openssl.cnf para generar los atributos de SNI correctos:

      [ 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
      

      Archivo opensssl.cnf de ejemplo:

      [ 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. Sigue los pasos que se indican en la sección Requisitos previos para inicializar y configurar Edge Microgateway, si aún no lo hiciste. Cuando aún no lo hiciste, deberías haber creado un proxy compatible con Edge Microgateway, un producto de API, un desarrollador y una app de desarrollador. Además, debes ejecutar el comando edgemicro configure y recibir una clave y un secreto.

    2. Genera certificados autofirmados

    A continuación, genera los certificados y las claves que necesitarás para establecer TLS:

    1. cd al directorio $HOME/.edgemicro.
    2. Crea la siguiente secuencia de comandos Bash. Puedes asignarle el nombre que desees. Por ejemplo: 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. En el archivo Bash, asegúrate de que la ruta de acceso al archivo openssl.cnf sea correcta.

    4. Ejecuta el archivo Bash. Se te solicitará información del certificado. Asegúrate de usar localhost para el nombre común.

    5. Comprueba que se hayan creado los siguientes archivos:

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

    3. Edita el archivo de configuración de Edge Microgateway

    1. Abre el archivo de configuración de Edge Micro en un editor. Por ejemplo:

      vi $HOME/.edgemicro/myorg-test-config.yaml
      
    2. Edita la estrofa edgemicro como se indica a continuación. Ten en cuenta que realizas cambios en los atributos port y 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. Ejecuta el siguiente comando para codificar en base64 el archivo de configuración de Edge Microgateway ubicado en $HOME/.edgemicro:

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

      En el ejemplo anterior, your_org y your_env son la organización y el entorno que usaste cuando ejecutaste el comando edgemicro config.

      Recuerda colocar comillas simples (`) alrededor del comando. Por ejemplo:

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

    Consulta también Ejecuta Edge Micro como un contenedor de Docker.

    4. Ejecuta el contenedor

    1. Ejecuta el siguiente comando para ejecutar el contenedor de Docker con 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 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. Ten en cuenta que los siguientes parámetros se usan en el comando; difieren del comando básico descrito en Ejecuta Edge Micro como un contenedor de Docker.

      • El valor de port es 8443.
      • Se usa una activación de volumen para activar los archivos de claves y certificados.
      • La variable NODE_EXTRA_CA_CERTS se usa para agregar una AC personalizada (según sea necesario en el caso de los certificados autofirmados).

    5. Prueba la configuración de TLS

    1. Ejecuta el siguiente comando cURL para probar la configuración. Sustituye tu ruta base y clave de API en el comando. En el siguiente ejemplo, se supone que estás en el directorio en el que se encuentra rootca.pem y que el proxy que creaste tiene la ruta base /hello:

      curl -v https://localhost:8443/hello --cacert rootca.pem \
      -H "x-api-key: Az82fdnfONVCOOE4NKhajxAboDgA3FAo"
      
    2. El resultado detallado de cURL muestra cada paso del protocolo de enlace TLS. Si ves una respuesta HTTP 200, significa que la configuración se realizó correctamente:

      *   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!
      

    Ejemplo: Cómo configurar TLS con sentido sur

    En esta sección, se explica cómo configurar una conexión TLS con dirección sur (saliente) entre el servidor de Edge Microgateway y una aplicación de destino de backend. En el siguiente ejemplo, se usan certificados autofirmados.

    1. Pasos iniciales para la configuración

    1. Ubica el archivo openssl.cnf en tu sistema. Por ejemplo, /etc/ssl/openssl.cnf
    2. Abre el archivo opensssl.cnf para editarlo.
    3. Asegúrate de que los req_extensions estén presentes en tu archivo de configuración. Por ejemplo, deberías tener información similar a la siguiente en tu archivo:

      [ req ]
      ...
      req_extensions          = v3_req
      ...
      
      [ v3_req ]
      extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
      basicConstraints = CA:FALSE
      keyUsage = nonRepudiation, digitalSignature, keyEncipherment
      
    4. Agrega la siguiente estrofa a openssl.cnf para generar los atributos de SNI correctos:

      [ 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
      

      Archivo opensssl.cnf de ejemplo:

      [ 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. Ejecuta el comando edgemicro configure:

      edgemicro configure -o your_org -e your_env -u your_username

      Para obtener más detalles sobre la configuración, consulta la Parte 1: Configura Edge Microgateway.

    6. Copia las credenciales de clave y secreto que se mostraron desde edgemicro configure. Los necesitarás para ejecutar el contenedor. Por ejemplo:

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

    2. Crea una aplicación de destino de Node.js

    1. cd al directorio .edgemicro.

    2. Crea la siguiente secuencia de comandos Bash. Puedes asignarle el nombre que desees. Por ejemplo: 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. En el archivo Bash, asegúrate de que la ruta de acceso al archivo openssl.cnf sea correcta.

    4. Ejecuta el archivo Bash. Se te solicitará información del certificado. Asegúrate de usar hellworld para el nombre común.

    5. Comprueba que se hayan creado los siguientes archivos:

      • rootca.key
      • rootca.pem
      • tls.key
      • tls.csr
      • rootca.srl
      • tls.crt
    6. Crea un archivo nuevo llamado server.js de la siguiente manera:

      '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. Crea un archivo package.json en el mismo directorio que server.js. Por ejemplo:

      {
        "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. Ejecuta npm install para obtener las dependencias.

    9. Crea un Dockerfile nuevo en el mismo directorio que server.js, en el que WORKDIR es la ruta a la raíz de tu app de 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. Compila la imagen de Docker:

      docker build -t helloworld . 
      
    11. Inicia la app de ejemplo:

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

    3. Crear entidades en Apigee Edge

    1. Crea un proxy compatible con Edge Microgateway con esta configuración. Para obtener más información, consulta Crea un proxy de API compatible con Edge Microgateway en Edge.

      • Nombre de proxy: edgemicro_local
      • Revisión: 1
      • Ruta base: /local
      • Destino: https://helloworld:9443
    2. Crear un producto de API Para obtener más detalles, consulta Cómo crear un producto.

    3. Crea un desarrollador. Para obtener detalles, consulta Cómo crear un desarrollador.

    4. Crea una app de desarrollador. Para obtener más información, consulta Cómo crear una app de desarrollador.

    4. Ejecuta el contenedor

    1. Abre el archivo de configuración de Edge Micro en un editor. Por ejemplo:

      vi $HOME/.edgemicro/myorg-test-config.yaml
      
    2. Edita la estrofa edgemicro como se indica a continuación. Ten en cuenta que realizas cambios en los atributos port y 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. Ejecuta el siguiente comando para codificar en base64 el archivo de configuración de Edge Microgateway ubicado en $HOME/.edgemicro:

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

      En el ejemplo anterior, your_org y your_env son la organización y el entorno que usaste cuando ejecutaste el comando edgemicro config.

      Recuerda colocar comillas simples (`) alrededor del comando. Por ejemplo:

      export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
    4. Ejecuta el siguiente comando para iniciar Edge Microgateway en el contenedor de 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 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. Prueba la configuración de TLS

    1. Ejecuta el siguiente comando cURL para probar la configuración. Sustituye la ruta base que usaste en el proxy compatible con micropuertas de enlace y la clave de API que obtuviste de la app de desarrollador que creaste en Apigee Edge. Por ejemplo:

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

      Deberías ver este error:

      ...
      *  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. Vuelve a ejecutar Edge Microgateway, pero esta vez agrega la variable 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. Ejecuta el siguiente comando de cURL. Sustituye tu ruta base y clave de API como antes. Por ejemplo:

      curl https://localhost:8443/local -k -H "x-api-key: xxxx" -v
      
    4. Verifica el resultado. Si la operación es exitosa, recibirás una respuesta de estado 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
      

    Cómo agregar un complemento personalizado

    Puedes agregar funciones y capacidades nuevas a la micropuerta de enlace si escribes complementos personalizados. Los complementos personalizados te permiten interactuar de manera programática con las solicitudes y respuestas que fluyen a través de la micropuerta de enlace.

    Tienes dos opciones para implementar complementos en una instancia de Edge Microgateway que se ejecuta en un contenedor de Docker:

    En el resto de esta sección, se supone que estás familiarizado con la escritura y la configuración de complementos para una configuración estándar de Edge Microgateway. De lo contrario, consulta Cómo desarrollar complementos personalizados.

    Opción A: Activa el directorio de complementos en un volumen

    Los pasos para agregar complementos mediante la activación de volumen son similares a los necesarios a fin de agregar cualquier complemento personalizado a Edge Microgateway (agregado en la versión v.2.5.27). Cuando ejecutas el contenedor de Docker, puedes activar el directorio de complementos en tu sistema local (el volumen) en el punto de activación del contenedor, que es /opt/apigee/plugins. Luego, debes especificar el directorio de volumen local en el archivo de configuración de Edge Microgateway.

    En los siguientes pasos, se ilustra cómo usar un punto de activación de Docker para incluir complementos personalizados.

    1. Detén Edge Microgateway:

      edgemicro stop
      
    2. Crea un directorio para tus complementos personalizados. Por ejemplo, crea

      $HOME/edgemicro/custom/plugins
      
    3. Agrega el directorio del complemento personalizado al archivo de configuración de Edge Microgateway. Por ejemplo:

        plugins:
          dir: $HOME/edgemicro/custom/plugins
          sequence:
            - oauth
            - response-uppercase
        ````
      
    4. Escribe y prueba el complemento según las instrucciones que se indican en Cómo escribir un complemento simple. Asegúrate de colocar el código del complemento en la estructura de directorio adecuada. Por ejemplo:

      custom
        |
        |-- plugins
          |
          |- response-uppercase
          |     |- index.js
          |     |- package.json
          |- request-headers
          |     | - index.js
                | - package.json
      
    5. Ejecuta el contenedor de Docker con un comando similar al siguiente, en el que usas la opción -v para activar el directorio de complementos en el volumen de Docker. En el siguiente comando de ejemplo, el directorio de complementos $HOME/edgemicro/custom/plugins (donde se encuentra el complemento personalizado) se asigna al punto de activación /opt/apigee/plugins del contenedor:

      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. Llama a tu API para probar el complemento.

    Para obtener más información, consulta VOLUME [sistemas de archivos compartidos].

    Opción B: Compila los complementos en el contenedor

    En esta opción, compilarás los complementos en tu contenedor.

    1. Cómo empaquetar los complementos

    1. Escribe y prueba el complemento según las instrucciones que se indican en Cómo escribir un complemento simple.

    2. Coloca el código del complemento en la estructura de directorio adecuada. Los directorios de complementos deben seguir una estructura establecida. En el siguiente ejemplo, se muestra la estructura que debes seguir, en la que response-uppercase y request-headers son los nombres de las carpetas que contienen código de complemento personalizado (estos nombres son solo ejemplos; los nombres de tus carpetas pueden diferir):

      plugin
        |
        |-- plugins
          |
          |- response-uppercase
          |     |- index.js
          |     |- package.json
          |- request-headers
          |     | - index.js
                | - package.json
      
    3. cd a la carpeta plugin.

    4. En la carpeta plugin, comprime toda la carpeta plugins:

      zip -r plugins.zip plugins/

    2. Crear una imagen de Docker

    A continuación, crea un Dockerfile para agregar el código del complemento a una imagen de Edge Microgateway.

    1. En el mismo directorio en el que se encuentra el archivo ZIP, crea un archivo nuevo llamado Dockerfile.
    2. Agrega el siguiente código a Dockerfile y guarda el archivo:

      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. Crea una imagen de Docker nueva de Edge Microgateway con los complementos:

      docker build -t image-name .
      

      Por ejemplo:

      docker build -t edgemicroplugins .
      

    3. Actualiza la configuración de Edge Microgateway

    Ahora que los complementos están empaquetados, debes agregarlos al archivo de configuración de Edge Microgateway.

    1. Abre el archivo de configuración de Edge Microgateway en un editor:

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

      Por ejemplo:

      vi $HOME/.edgemicro/myorg-test-config.yaml
    2. Agrega el directorio del complemento al archivo de configuración. En el siguiente ejemplo, el atributo dir especifica la ubicación del código del complemento (que especificaste en el Dockerfile). También debes especificar el nombre del directorio del complemento, que en el siguiente ejemplo es response-uppercase.

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

    4. Inicia la micropuerta de enlace

    Por último, debes iniciar la micropuerta de enlace en el contenedor.

    1. Ejecuta el siguiente comando para codificar en base64 el archivo de configuración de Edge Microgateway ubicado en $HOME/.edgemicro:

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

      En el ejemplo anterior, your_org y your_env son la organización y el entorno que usaste cuando ejecutaste el comando edgemicro config.

      Recuerda colocar comillas simples (`) alrededor del comando. Por ejemplo:

      export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
    2. Ejecuta Edge Microgateway como contenedor. Con el comando, se configuran varias variables de entorno que usa el entorno de ejecución del contenedor para iniciar 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

      Por ejemplo:

      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. Llama a tu API para probar el complemento:

      Llama a tu API y verifica que el resultado sea el esperado para probar que se ejecute el código del complemento:

      curl -i http://localhost:8000/hello -H "x-api-key:apikey"

      Por ejemplo, el complemento response-uppercase puede mostrar una respuesta como la siguiente:

      curl -i http://localhost:8000/hello -H "x-api-key:PydUKRDGIXRqF2xh4usn1FLHbhGKVIz"
        HELLO, WORLD!