Referencia de operación y configuración de Edge Microgateway

Estás viendo la documentación de Apigee Edge.
Ir a la documentación de Apigee X. info

Edge Microgateway v. 2.5.x

En este tema, se analiza cómo administrar y configurar Edge Microgateway.

Actualiza Edge Microgateway si tienes conexión a Internet

1. Ejecuta el siguiente comando npm para actualizar a la versión más reciente de Edge Microgateway:

   npm upgrade edgemicro -g

   Para actualizar a una versión específica de Edge Microgateway, debes especificar el número de versión en el comando de actualización. Si no especificas el número de versión, se instalará la versión más reciente. Por ejemplo, para actualizar a la versión 2.5.26, usa el siguiente comando:

   npm upgrade edgemicro@2.5.26 -g

2. Verifica el número de versión. Por ejemplo, si instalaste la versión 2.5.26, haz lo siguiente:

   edgemicro --version
   current nodejs version is v8.9.0
   current edgemicro version is 2.5.26
       

3. Por último, actualiza a la versión más reciente del proxy edgemicro-auth:

   edgemicro upgradeauth -o org_name -e env_name -u username

Realiza cambios en la configuración

Los archivos de configuración que debes conocer son los siguientes:

• Archivo de configuración predeterminada del sistema
• Archivo de configuración predeterminado para una instancia de Edge Microgateway recién inicializada
• Archivo de configuración dinámica para instancias en ejecución

En esta sección, se analizan estos archivos y lo que necesitas saber para cambiarlos.

Archivo de configuración predeterminada del sistema

Cuando instalas Edge Microgateway, se coloca un archivo de configuración del sistema predeterminado aquí:

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

Donde prefix es el directorio de prefijo npm. Consulta Dónde se instala Edge Microgateway si no puedes encontrar este directorio.

Si cambias el archivo de configuración del sistema, debes reinicializar, volver a configurar y reiniciar Edge Microgateway:

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

Archivo de configuración predeterminado para las instancias de Edge Microgateway inicializadas recientemente

Cuando ejecutas edgemicro init, el archivo de configuración del sistema (descrito anteriormente), default.yaml, se coloca en el directorio ~/.edgemicro.

Si cambias el archivo de configuración en ~/.edgemicro, debes volver a configurar y reiniciar Edge Microgateway:

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

Archivo de configuración dinámica para instancias en ejecución

Cuando ejecutas edgemicro configure [params], se crea un archivo de configuración dinámico en ~/.edgemicro. El archivo se nombra según este patrón: org-env-config.yaml, en el que org y env son los nombres de tu organización y entorno de Apigee Edge. Puedes usar este archivo para realizar cambios en la configuración y, luego, volver a cargarlos sin tiempo de inactividad. Por ejemplo, si agregas y configuras un complemento, puedes volver a cargar la configuración sin que se produzca ningún tiempo de inactividad, como se explica a continuación.

Si Edge Microgateway se está ejecutando (opción sin tiempo de inactividad):

1. Vuelve a cargar la configuración de Edge Microgateway:

   edgemicro reload -o org_name -e env_name -k key -s secret

   Donde:

   • org_name es el nombre de tu organización de Edge (debes ser administrador de la organización).
   • env_name es un entorno de tu organización (como "test" o "prod").
   • key es la clave que devolvió antes el comando configure.
   • secret es la clave que devolvió antes el comando configure.

   Por ejemplo:

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

Si se detiene Edge Microgateway, haz lo siguiente:

1. Reinicia Edge Microgateway:

   edgemicro start -o org_name -e env_name -k key -s secret

   Donde:

   • org_name es el nombre de tu organización de Edge (debes ser administrador de la organización).
   • env_name es un entorno de tu organización (como "test" o "prod").
   • key es la clave que devolvió antes el comando configure.
   • secret es la clave que devolvió antes el comando configure.

   Por ejemplo:

   edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \
     -s 05c1435...e34ab0cc824

Este es un ejemplo de un archivo de configuración. Para obtener detalles sobre la configuración del archivo de configuración, consulta la Referencia de configuración de Edge Microgateway.

edge_config:
  bootstrap: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test
  jwt_public_key: 'https://docs-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://docs-test.apigee.net/edgemicro-auth/products'
edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
headers:
  x-forwarded-for: true
  x-forwarded-host: true
  x-request-id: true
  x-response-time: true
  via: true
oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  verify_api_key_url: 'https://docs-test.apigee.net/edgemicro-auth/verifyApiKey'
analytics:
  uri: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/axpublisher/organization/docs/environment/test

Configura variables de entorno

Los comandos de la interfaz de línea de comandos que requieren valores para tu organización y entorno de Edge, y la clave y el secreto necesarios para iniciar Edge Microgateway se pueden almacenar en estas variables de entorno:

• EDGEMICRO_ORG
• EDGEMICRO_ENV
• EDGEMICRO_KEY
• EDGEMICRO_SECRET

Establecer estas variables es opcional. Si las configuras, no tienes que especificar sus valores cuando usas la interfaz de línea de comandos (CLI) para configurar e iniciar Edge Microgateway.

Configura SSL en el servidor de Edge Microgateway

Puedes configurar el servidor de Microgateway para que use SSL. Por ejemplo, con SSL configurado, puedes llamar a las APIs a través de Edge Microgateway con el protocolo "https", de la siguiente manera:

https://localhost:8000/myapi

Para configurar SSL en el servidor de Microgateway, sigue estos pasos:

1. Genera u obtén un certificado y una clave SSL con la utilidad openssl o el método que prefieras.
2. Agrega el atributo edgemicro:ssl al archivo de configuración de Edge Microgateway. Para obtener una lista completa de las opciones, consulta la siguiente tabla. Por ejemplo:
   

   edgemicro:
     ssl:
      key: <absolute path to the SSL key file>
      cert: <absolute path to the SSL cert file>
      passphrase: admin123 #option added in v2.2.2
      rejectUnauthorized: true #option added in v2.2.2
      requestCert: true

3. Reinicia Edge Microgateway. Sigue los pasos que se describen en Realiza cambios de configuración según el archivo de configuración que editaste: el archivo predeterminado o el archivo de configuración del entorno de ejecución.

Este es un ejemplo de la sección edgemicro del archivo de configuración, con SSL configurado:

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

A continuación, se muestra una lista de todas las opciones de servidor admitidas:

Usa las opciones de SSL/TLS del cliente

Puedes configurar Edge Microgateway para que sea un cliente TLS o SSL cuando se conecte a extremos de destino. En el archivo de configuración de Microgateway, usa el elemento targets para establecer las opciones de SSL/TLS.

En este ejemplo, se proporcionan parámetros de configuración que se aplicarán a todos los hosts:

edgemicro:
...
targets:
  ssl:
    client:
      key: /Users/jdoe/nodecellar/twowayssl/ssl/client.key
      cert: /Users/jdoe/nodecellar/twowayssl/ssl/ca.crt
      passphrase: admin123
      rejectUnauthorized: true

En este ejemplo, la configuración se aplica solo al host especificado:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    ssl:
      client:
        key: /Users/myname/twowayssl/ssl/client.key
        cert: /Users/myname/twowayssl/ssl/ca.crt
        passphrase: admin123
        rejectUnauthorized: true

Este es un ejemplo de TLS:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    tls:
      client:
        pfx: /Users/myname/twowayssl/ssl/client.pfx
        passphrase: admin123
        rejectUnauthorized: true

A continuación, se incluye una lista de todas las opciones de cliente compatibles:

Personaliza el proxy edgemicro-auth

De forma predeterminada, Edge Microgateway usa un proxy implementado en Apigee Edge para la autenticación de OAuth2. Este proxy se implementa cuando ejecutas edgemicro configure por primera vez. Puedes cambiar la configuración predeterminada de este proxy para agregar compatibilidad con reclamaciones personalizadas a un token web JSON (JWT), configurar el vencimiento del token y generar tokens de actualización. Para obtener más detalles, consulta la página edgemicro-auth en GitHub.

Usa un servicio de autenticación personalizado

De forma predeterminada, Edge Microgateway usa un proxy implementado en Apigee Edge para la autenticación de OAuth2. Este proxy se implementa cuando ejecutas edgemicro configure por primera vez. De forma predeterminada, la URL de este proxy se especifica en el archivo de configuración de Edge Microgateway de la siguiente manera:

authUri: https://myorg-myenv.apigee.net/edgemicro-auth

Si quieres usar tu propio servicio personalizado para controlar la autenticación, cambia el valor de authUri en el archivo de configuración para que apunte a tu servicio. Por ejemplo, puedes tener un servicio que use LDAP para verificar la identidad.

Administra archivos de registro

Edge Microgateway registra información sobre cada solicitud y respuesta. Los archivos de registro proporcionan información útil para depurar y solucionar problemas.

Dónde se almacenan los archivos de registro

De forma predeterminada, los archivos de registro se almacenan en /var/tmp.

Cómo cambiar el directorio predeterminado del archivo de registro

El directorio en el que se almacenan los archivos de registro se especifica en el archivo de configuración de Edge Microgateway. Consulta también Realiza cambios en la configuración.

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Cambia el valor de dir para especificar un directorio de archivos de registro diferente.

Envía registros a la consola

Puedes configurar el registro para que la información se envíe a la salida estándar en lugar de a un archivo de registro. Establece la marca to_console como verdadera de la siguiente manera:

edgemicro:
  logging:
    to_console: true

Con este parámetro de configuración, los registros se enviarán a la salida estándar. Actualmente, no puedes enviar registros a stdout y a un archivo de registro.

Cómo establecer el nivel de registro

Puedes establecer estos niveles de registro: info, warn y error. Se recomienda el nivel de información. Registra todas las solicitudes y respuestas de la API, y es el valor predeterminado.

Cómo cambiar los intervalos de registro

Puedes configurar estos intervalos en el archivo de configuración de Edge Microgateway. Consulta también Realiza cambios en la configuración.

Los atributos configurables son los siguientes:

• stats_log_interval: (predeterminado: 60) Es el intervalo, en segundos, en el que se escribe el registro de estadísticas en el archivo de registro de la API.
• rotate_interval: (predeterminado: 24) Es el intervalo, en horas, en el que se rotan los archivos de registro. Por ejemplo:

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Prácticas recomendadas para el mantenimiento de archivos de registro

A medida que los datos de los archivos de registro se acumulan con el tiempo, Apigee recomienda que adoptes las siguientes prácticas:

• Debido a que los archivos de registro pueden ser bastante grandes, asegúrate de que el directorio de archivos de registro tenga espacio suficiente. Consulta las siguientes secciones: Dónde se almacenan los archivos de registro y Cómo cambiar el directorio predeterminado de los archivos de registro.
• Borra o mueve los archivos de registro a un directorio de archivo independiente al menos una vez a la semana.
• Si tu política es borrar registros, puedes usar el comando de la CLI edgemicro log -c para quitar (limpiar) los registros más antiguos.

Convención de nomenclatura de archivos de registro

Cada instancia de Edge Microgateway produce tres tipos de archivos de registro:

• api: Registra todas las solicitudes y respuestas que fluyen a través de Edge Microgateway. Los contadores de la API (estadísticas) y los errores también se registran en este archivo.
• err: Registra todo lo que se envía a stderr.
• out: Registra todo lo que se envía a stdout.

Esta es la convención de nomenclatura:

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

Por ejemplo:

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

Acerca del contenido de los archivos de registro

Se agregó en la versión 2.3.3

De forma predeterminada, el servicio de registro omite el JSON de los proxies, los productos y el token web JSON (JWT) descargados. Si deseas enviar estos objetos a los archivos de registro, configura la variable de entorno DEBUG=* cuando inicies Edge Microgateway. Por ejemplo:

DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456

Contenido del archivo de registro "api"

El archivo de registro "api" contiene información detallada sobre el flujo de solicitudes y respuestas a través de Edge Microgateway. Los archivos de registro "api" tienen nombres como este:

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

Para cada solicitud realizada a Edge Microgateway, se capturan cuatro eventos en el archivo de registro "api":

• Solicitud entrante del cliente
• Solicitud saliente realizada al destino
• Respuesta entrante del destino
• Respuesta saliente al cliente

Cada una de estas entradas independientes se representa en una notación abreviada para ayudar a que los archivos de registro sean más compactos. Aquí hay cuatro entradas de ejemplo que representan cada uno de los cuatro eventos. En el archivo de registro, se ven de la siguiente manera (los números de línea son solo de referencia en el documento, no aparecen en el archivo de registro).

(1) 1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
(2) 1436403888665 info treq m=GET, u=/, h=127.0.0.18080, i=0
(3) 1436403888672 info tres s=200, d=7, i=0
(4) 1436403888676 info res s=200, d=11, i=0

Analicemos cada uno de ellos:

1. Ejemplo de solicitud entrante del cliente:

1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0

• 1436403888651: Marca de fecha de Unix
• info: Depende del contexto. Puede ser info, warn o error, según el nivel de registro. Puede ser stats para un registro de estadísticas, warn para advertencias o error para errores.
• req: Identifica el evento. En este caso, la solicitud proviene del cliente.
• m: Es el verbo HTTP que se usó en la solicitud.
• u: Es la parte de la URL que sigue a la ruta de acceso base.
• h: Es el host y el número de puerto en el que escucha Edge Microgateway.
• r: El host y el puerto remotos en los que se originó la solicitud del cliente.
• i: Es el ID de la solicitud. Las cuatro entradas de eventos compartirán este ID. A cada solicitud se le asigna un ID de solicitud único. Correlacionar los registros por ID de solicitud puede proporcionar información valiosa sobre la latencia del destino.
• d: Es la duración en milisegundos desde que Edge Microgateway recibió la solicitud. En el ejemplo anterior, la respuesta del destino para la solicitud 0 se recibió después de 7 milisegundos (línea 3) y la respuesta se envió al cliente después de 4 milisegundos adicionales (línea 4). En otras palabras, la latencia total de la solicitud fue de 11 milisegundos, de los cuales el destino tardó 7 milisegundos y Edge Microgateway tardó 4 milisegundos.

2. Muestra de la solicitud saliente realizada al destino:

1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0

• 1436403888651: Marca de fecha de Unix
• info: Depende del contexto. Puede ser info, warn o error, según el nivel de registro. Puede ser stats para un registro de estadísticas, warn para advertencias o error para errores.
• treq: Identifica el evento. En este caso, target.request.
• m: Es el verbo HTTP que se usa en la solicitud de destino.
• u: Es la parte de la URL que sigue a la ruta de acceso base.
• h: Es el host y el número de puerto del destino de backend.
• i: Es el ID de la entrada de registro. Las cuatro entradas de eventos compartirán este ID.

3. Muestra de la respuesta entrante del destino

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

1436403888651: Marca de fecha de Unix

• info: Depende del contexto. Puede ser info, warn o error, según el nivel de registro. Puede ser stats para un registro de estadísticas, warn para advertencias o error para errores.
• tres: Identifica el evento. En este caso, la respuesta de destino.
• s: Es el estado de la respuesta HTTP.
• d: Es la duración en milisegundos. Es el tiempo que tarda el destino en realizar la llamada a la API.
• i: Es el ID de la entrada de registro. Las cuatro entradas de eventos compartirán este ID.

4. Ejemplo de respuesta saliente al cliente

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

1436403888651: Marca de fecha de Unix

• info: Depende del contexto. Puede ser info, warn o error, según el nivel de registro. Puede ser stats para un registro de estadísticas, warn para advertencias o error para errores.
• res: Identifica el evento. En este caso, responde al cliente.
• s: Es el estado de la respuesta HTTP.
• d: Es la duración en milisegundos. Es el tiempo total que tarda la llamada a la API, incluido el tiempo que tarda la API de destino y el tiempo que tarda Edge Microgateway.
• i: Es el ID de la entrada de registro. Las cuatro entradas de eventos compartirán este ID.

Programa del archivo de registro

Los archivos de registro se rotan en el intervalo especificado por el atributo de configuración rotate_interval. Se seguirán agregando entradas al mismo archivo de registro hasta que venza el intervalo de rotación. Sin embargo, cada vez que se reinicia Edge Microgateway, recibe un UID nuevo y crea un conjunto nuevo de archivos de registro con este UID. Consulta también Prácticas recomendadas para el mantenimiento de archivos de registro.

Mensajes de error

Algunas entradas de registro contendrán mensajes de error. Para identificar dónde y por qué se producen los errores, consulta la referencia de errores de Edge Microgateway.

Referencia de configuración de Edge Microgateway

Ubicación del archivo de configuración

Los atributos de configuración que se describen en esta sección se encuentran en el archivo de configuración de Edge Microgateway. Consulta también Realiza cambios en la configuración.

Atributos de edge_config

Esta configuración se usa para configurar la interacción entre la instancia de Edge Microgateway y Apigee Edge.

• bootstrap: (predeterminado: ninguno) Es una URL que apunta a un servicio específico de Edge Microgateway que se ejecuta en Apigee Edge. Edge Microgateway usa este servicio para comunicarse con Apigee Edge. Esta URL se devuelve cuando ejecutas el comando para generar el par de claves pública/privada: edgemicro genkeys. Consulta Configura Edge Microgateway para obtener más detalles.
• jwt_public_key: (predeterminado: ninguno) Es una URL que apunta al proxy de Edge Microgateway que se implementa en Apigee Edge. Este proxy funciona como un extremo de autenticación para emitir tokens de acceso firmados a los clientes. Esta URL se muestra cuando ejecutas el comando para implementar el proxy: edgemicro configure. Consulta Configura Edge Microgateway para obtener más detalles.

atributos de edgemicro

Esta configuración establece el proceso de Edge Microgateway.

• port: (predeterminado: 8000) Es el número de puerto en el que escucha el proceso de Edge Microgateway.
• max_connections: (predeterminado: -1) Especifica la cantidad máxima de conexiones entrantes simultáneas que puede recibir Edge Microgateway. Si se supera este número, se devuelve el siguiente estado:
  
  res.statusCode = 429; // Too many requests
  
• max_connections_hard: (predeterminado: -1) Es la cantidad máxima de solicitudes simultáneas que Edge Microgateway puede recibir antes de cerrar la conexión. Este parámetro de configuración tiene como objetivo frustrar los ataques de denegación del servicio. Por lo general, se establece en un número mayor que max_connections.
• logging:
  • level: (predeterminado: error)
    • info: Registra todas las solicitudes y respuestas que fluyen a través de una instancia de Edge Microgateway.
    • warn: Solo registra mensajes de advertencia.
    • error: Solo registra mensajes de error.
  • dir: (predeterminado: /var/tmp) Es el directorio en el que se almacenan los archivos de registro.
  • stats_log_interval: (predeterminado: 60) Es el intervalo, en segundos, en el que se escribe el registro de estadísticas en el archivo de registro de la API.
  • rotate_interval: (predeterminado: 24) Es el intervalo, en horas, en el que se rotan los archivos de registro.

• complementos: Los complementos agregan funcionalidad a Edge Microgateway. Para obtener detalles sobre el desarrollo de complementos, consulta Desarrolla complementos personalizados.

• dir: Es una ruta de acceso relativa del directorio ./gateway al directorio ./plugins o una ruta de acceso absoluta.
• sequence: Es una lista de módulos de complemento que se agregarán a tu instancia de Edge Microgateway. Los módulos se ejecutarán en el orden en que se especifican aquí.

• debug: Agrega la depuración remota al proceso de Edge Microgateway.
  • port: Es el número de puerto en el que se escuchará. Por ejemplo, configura el depurador de tu IDE para que escuche en este puerto.
  • args: Son los argumentos para el proceso de depuración. Por ejemplo: args --nolazy
    
• config_change_poll_interval: (predeterminado: 600 segundos) Edge Microgateway carga una configuración nueva de forma periódica y ejecuta una recarga si se produce algún cambio. El sondeo recoge cualquier cambio realizado en Edge (cambios en los productos, proxies compatibles con microgateway, etc.) y los cambios realizados en el archivo de configuración local.
  
• disable_config_poll_interval: (predeterminado: false) Se establece en true para desactivar el sondeo de cambios automático.
• request_timeout: Establece un tiempo de espera para las solicitudes de destino. El tiempo de espera se establece en segundos. Si se produce un tiempo de espera, Edge Microgateway responde con un código de estado 504. (Se agregó la versión 2.4.x)

atributos de encabezados

Estos parámetros de configuración determinan cómo se tratan ciertos encabezados HTTP.

• x-forwarded-for: (predeterminado: true) Se establece en false para evitar que los encabezados x-forwarded-for se pasen al destino. Ten en cuenta que, si hay un encabezado x-forwarded-for en la solicitud, su valor se establecerá en el valor client-ip en Edge Analytics.
• x-forwarded-host: (predeterminado: true) Se establece en false para evitar que los encabezados x-forwarded-host se pasen al destino.
• x-request-id: (predeterminado: true) Se establece en false para evitar que los encabezados x-request-id se pasen al destino.
• x-response-time: (predeterminado: true) Se establece en false para evitar que se pasen los encabezados x-response-time al destino.
• via: (el valor predeterminado es verdadero) Se establece en falso para evitar que los encabezados via se pasen al destino.

atributos de oauth

Estos parámetros configuran cómo Edge Microgateway aplica la autenticación del cliente.

• allowNoAuthorization: (predeterminado: false) Si se establece en true, las llamadas a la API pueden pasar por Edge Microgateway sin ningún encabezado de autorización. Establece este valor en false para requerir un encabezado de autorización (predeterminado).
• allowInvalidAuthorization: (predeterminado: falso) Si se establece como verdadero, se permite que las llamadas a la API pasen si el token que se pasa en el encabezado de autorización no es válido o venció. Establece este valor en falso para requerir tokens válidos (predeterminado).
• authorization-header: (predeterminado: Authorization: Bearer) Es el encabezado que se usa para enviar el token de acceso a Edge Microgateway. Es posible que desees cambiar el valor predeterminado en los casos en que el destino deba usar el encabezado de autorización para algún otro propósito.
• api-key-header: (predeterminado: x-api-key) Es el nombre del encabezado o parámetro de consulta que se usa para pasar una clave de API a Edge Microgateway. Consulta también Cómo usar una clave de API.
• keep-authorization-header: (predeterminado: false) Si se establece en true, el encabezado Authorization enviado en la solicitud se pasa al destino (se conserva).
• allowOAuthOnly: Si se establece como verdadero, cada API debe tener un encabezado de autorización con un token de acceso del portador. Te permite admitir solo el modelo de seguridad de OAuth (mientras se mantiene la retrocompatibilidad). (Se agregó la versión 2.4.x)
• allowAPIKeyOnly: Si se establece como verdadero, cada API debe tener un encabezado x-api-key (o una ubicación personalizada) con una clave de API.Te permite admitir solo el modelo de seguridad de clave de API (mientras se mantiene la retrocompatibilidad). (Se agregó en la versión 2.4.x)
• gracePeriod: Este parámetro ayuda a evitar errores causados por discrepancias leves entre el reloj del sistema y las horas de No antes de (nbf) o Emitido en (iat) especificadas en el token de autorización de JWT. Establece este parámetro en la cantidad de segundos que se permitirán para esas discrepancias. (Se agregó la versión 2.5.7)

Atributos específicos del complemento

Consulta Usa complementos para obtener detalles sobre los atributos configurables de cada complemento.

Proxies de filtrado

Puedes filtrar qué proxies compatibles con microgateway procesará una instancia de Edge Microgateway. Cuando se inicia Edge Microgateway, se descargan todos los proxies compatibles con Microgateway en la organización con la que está asociado. Usa la siguiente configuración para limitar los proxies que procesará la micropuerta de enlace. Por ejemplo, esta configuración limita los proxies que procesará la micropuerta de enlace a tres: edgemicro_proxy-1, edgemicro_proxy-2 y edgemicro_proxy-3:

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

Configura la frecuencia de envío de estadísticas

Usa estos parámetros de configuración para controlar la frecuencia con la que Edge Microgateway envía datos de estadísticas a Apigee:

• bufferSize (opcional): Es la cantidad máxima de registros de estadísticas que puede contener el búfer antes de comenzar a descartar los registros más antiguos. Valor predeterminado: 10000
• batchSize (opcional): Es el tamaño máximo de un lote de registros de estadísticas enviados a Apigee. Predeterminado: 500
• flushInterval (opcional): Es la cantidad de milisegundos entre cada vaciado de un lote de registros de estadísticas enviados a Apigee. Valor predeterminado: 5000

Por ejemplo:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

Enmascara datos de estadísticas

La siguiente configuración evita que la información de la ruta de acceso de la solicitud aparezca en las estadísticas de Edge. Agrega lo siguiente a la configuración de microgateway para enmascarar el URI de solicitud o la ruta de acceso de la solicitud. Ten en cuenta que el URI consta de las partes del nombre de host y de la ruta de acceso de la solicitud.

analytics:
  mask_request_uri: 'string_to_mask'
  mask_request_path: 'string_to_mask'

Separa las llamadas a la API en Edge Analytics

Puedes configurar el complemento de estadísticas para segregar una ruta de acceso de API específica de modo que aparezca como un proxy independiente en los paneles de Edge Analytics. Por ejemplo, puedes separar una API de verificación de estado en el panel para evitar confundirla con llamadas reales al proxy de API. En el panel de Analytics, los proxies segregados siguen este patrón de nombres:

edgemicro_proxyname-health

En la siguiente imagen, se muestran dos proxies segregados en el panel de Analytics: edgemicro_hello-health y edgemicro_mock-health:

Usa estos parámetros para separar las rutas de acceso relativas y absolutas en el panel de Analytics como proxies independientes:

• relativePath (opcional): Especifica una ruta de acceso relativa para segregar en el panel de Analytics. Por ejemplo, si especificas /healthcheck, todas las llamadas a la API que contengan la ruta de acceso /healthcheck aparecerán en el panel como edgemicro_proxyname-health. Ten en cuenta que esta marca ignora la ruta de acceso base del proxy. Para segregar en función de una ruta de acceso completa, incluida la ruta de acceso base, usa la marca proxyPath.
• proxyPath (opcional): Especifica una ruta de acceso completa del proxy de API, incluida la ruta de acceso base del proxy, para segregar en el panel de estadísticas. Por ejemplo, si especificas /mocktarget/healthcheck, en el que /mocktarget es la ruta de acceso base del proxy, todas las llamadas a la API con la ruta de acceso /mocktarget/healthcheck aparecerán en el panel como edgemicro_proxyname-health.

Por ejemplo, en la siguiente configuración, el complemento de estadísticas separará cualquier ruta de API que contenga /healthcheck. Esto significa que /foo/healthcheck y /foo/bar/healthcheck se segregarán como un proxy independiente llamado edgemicro_proxyname-health en el panel de estadísticas.

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

En la siguiente configuración, cualquier API con la ruta de proxy /mocktarget/healthcheck se separará como un proxy independiente llamado edgemicro_proxyname-health en el panel de estadísticas.

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

Configura Edge Microgateway detrás de un firewall de la empresa

Compatible con la versión 2.4.x

Si Edge Microgateway se instala detrás de un firewall, es posible que la puerta de enlace no pueda comunicarse con Apigee Edge. En este caso, puedes considerar dos opciones:

Opción 1:

La primera opción es establecer la opción edgemicro: proxy_tunnel en verdadero en el archivo de configuración de microgateway:

edge_config:

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

Cuando proxy_tunnel es true, Edge Microgateway usa el método HTTP CONNECT para tunelizar solicitudes HTTP a través de una sola conexión TCP. (Lo mismo ocurre si las variables de entorno para configurar el proxy tienen habilitado TLS).

Opción 2:

La segunda opción es especificar un proxy y establecer proxy_tunnel en false en el archivo de configuración de microgateway. Por ejemplo:

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

En este caso, puedes configurar las siguientes variables para controlar los hosts de cada proxy HTTP que quieras usar o qué hosts no deben controlar los proxies de Edge Microgateway: HTTP_PROXY, HTTPS_PROXY y NO_PROXY.

Puedes configurar NO_PROXY como una lista de dominios delimitada por comas a los que Edge Microgateway no debe enviar proxy. Por ejemplo:

export NO_PROXY='localhost,localhost:8080'

Establece HTTP_PROXY y HTTPS_PROXY en el extremo del proxy HTTP al que Edge Microgateway puede enviarle mensajes. Por ejemplo:

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

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

Para obtener más información sobre estas variables, consulta https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables

Consulta también

Cómo configurar Edge Microgateway detrás de un firewall de la empresa en la comunidad de Apigee.

Usa comodines en proxies compatibles con Microgateway

Puedes usar uno o más comodines "*" en la ruta de acceso base de un proxy edgemicro_* (compatible con Microgateway). Por ejemplo, una ruta de acceso base de /team/*/members permite que los clientes llamen a https://[host]/team/blue/members y https://[host]/team/green/members sin que tengas que crear proxies de API nuevos para admitir equipos nuevos. Ten en cuenta que no se admite /**/.

Importante: Apigee NO admite el uso de un comodín "*" como el primer elemento de una ruta de acceso base. Por ejemplo, NO se admite lo siguiente: búsqueda de /*/.

Rota claves de JWT

En algún momento después de generar un JWT, es posible que debas cambiar el par de claves pública y privada almacenado en el KVM encriptado de Edge. Este proceso de generación de un par de claves nuevo se denomina rotación de claves.

Cómo Edge Microgateway usa JWT

El token web JSON (JWT) es un estándar de token que se describe en RFC7519. El JWT proporciona una forma de firmar un conjunto de reclamaciones, que el destinatario del JWT puede verificar de manera confiable.

Edge Microgateway usa JWT como tokens del portador para la seguridad de OAuth. Cuando generas un token de OAuth para Edge Microgateway, recibes un JWT. Luego, puedes usar el JWT en el encabezado de autorización de las llamadas a la API. Por ejemplo:

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

Genera un JWT nuevo

Puedes generar un JWT para Edge Microgateway con el comando edgemicro token o una API. Por ejemplo:

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

Este comando le pide a Apigee Edge que genere un JWT que, luego, se puede usar para verificar las llamadas a la API. Los parámetros -i y -s son el ID del consumidor y los valores de secreto de una app para desarrolladores en tu organización de Apigee Edge.

También puedes generar un JWT con la API de administración:

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

Donde:

• org es el nombre de tu organización de Edge (debes ser administrador de la organización).
• env es un entorno de tu organización (como "test" o "prod").
• client_id es el ID de consumidor en la app para desarrolladores que creaste antes.
• client_secret es el secreto de consumidor en la app para desarrolladores que creaste antes.

¿Qué es la rotación de claves?

En algún momento después de generar un JWT, es posible que debas cambiar el par de claves pública y privada almacenado en el KVM encriptado de Edge. Este proceso de generación de un par de claves nuevo se denomina rotación de claves. Cuando rotas las claves, se genera un nuevo par de claves pública/privada y se almacena en el KVM de "microgateway" en tu organización o entorno de Apigee Edge. Además, se conserva la clave pública anterior junto con su valor de ID de clave original.

Para generar un JWT, Edge usa la información almacenada en la KVM encriptada. Se creó un KVM llamado microgateway y se propagó con claves cuando configuraste Edge Microgateway por primera vez. Las claves del KVM se usan para firmar y encriptar un JWT.

Las claves de KVM incluyen las siguientes:

• private_key: Es la clave privada RSA más reciente (creada más recientemente) que se usa para firmar los JWT.

• public_key: Es el certificado más reciente (creado más recientemente) que se usa para verificar los JWT firmados con la private_key.

• private_key_kid: Es el ID de la clave privada más reciente (creada más recientemente). Este ID de clave se asocia con el valor private_key y se usa para admitir la rotación de claves.

• public_key1_kid: Es el ID de la clave pública más reciente (creada más recientemente). Esta clave se asocia con el valor public_key1 y se usa para admitir la rotación de claves. Este valor es el mismo que el kid de la clave privada.

• public_key1: Es la clave pública más reciente (creada más recientemente).

Cuando realizas la rotación de claves, los valores de clave existentes se reemplazan en el mapa y se agregan claves nuevas para conservar las claves públicas anteriores. Por ejemplo:

• public_key2_kid: Es el ID de la clave pública anterior. Esta clave se asocia con el valor public_key2 y se usa para admitir la rotación de claves.

• public_key2: Es la clave pública anterior.

Los JWT que se presenten para la verificación se verificarán con la clave pública nueva. Si falla la verificación, se usará la clave pública anterior hasta que venza (después de 30 minutos). De esta manera, puedes "rotar" las claves sin interrumpir de inmediato el tráfico de la API.

Cómo realizar la rotación de claves

En esta sección, se explica cómo realizar una rotación de claves.

Si configuraste tu instancia de Edge Microgateway antes de la versión 2.5.2

Si configuraste tu instancia de Edge Microgateway antes de la versión 2.5.2, debes ejecutar los siguientes dos comandos para actualizar el KVM y la política de autenticación:

upgradekvm -o org -e env -u username

Para obtener más información sobre este comando, consulta Actualiza el KVM.

El siguiente comando actualiza el proxy edgemicro-oauth que se implementó en tu organización de Apigee cuando configuraste Edge Microgateway. Este proxy proporciona los servicios necesarios para generar tokens.

upgradeauth -o org -e env -u username

Para obtener más información sobre este comando, consulta Actualiza el proxy edgemicro-auth.

Rota las claves

Agrega la siguiente línea a tu archivo ~/.edgemicro/org-env-config.yaml, en el que debes especificar la misma organización y el mismo entorno que configuraste para que use la micropuerta de enlace:

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

Ejecuta el comando de rotación de claves para rotar las claves. (Para obtener más información sobre este comando, consulta Rota claves).

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

Por ejemplo:

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

El parámetro -k especifica un ID de clave (kid). Este ID se usa para hacer coincidir una clave específica. Edge Microgateway usa este valor para elegir entre un conjunto de claves durante la rotación de claves. Para obtener más información, consulta la sección 4.5 de la especificación de la clave web JSON.

Después de la rotación de claves, Edge devuelve varias claves a Edge Microgateway. Ten en cuenta que, en el siguiente ejemplo, cada clave tiene un valor de "kid" (ID de clave) único. Luego, la micropuerta de enlace usa estas claves para validar los tokens de autorización. Si la validación del token falla, el microgateway busca si hay una clave más antigua en el conjunto de claves y la prueba. El formato de las claves devueltas es JSON Web Key (JWK). Puedes leer sobre este formato en RFC 7517.

{
  "keys": [
    {
      "kty": "RSA",
      "n": "nSl7R_0wKLiWi6cO3n8aOJwYGBtinq723Jgg8i7KKWTSTYoszOjgGsJf_MX4JEW1YCScwpE5o4o8ccQN09iHVTlIhk8CNiMZNPipClmRVjaL_8IWvMQp1iN66qy4ldWXzXnHfivUZZogCkBNqCz7VSC5rw2Jf57pdViULVvVDGwTgf46sYveW_6h8CAGaD0KLd3vZffxIkoJubh0yMy0mQP3aDOeIGf_akeZeZ6GzF7ltbKGd954iNTiKmdm8IKhz6Y3gLpC9iwQ-kex_j0CnO_daHl1coYxUSCIdv4ziWIeM3dmjQ5_2dEvUDIGG6_Az9hTpNgPE5J1tvrOHAmunQ",
      "e": "AQAB",
      "kid": "2"
    },
    {
      "kty": "RSA",
      "n": "8BKwzx34BMUcHwTuQtmp8LFRCMxbkKg_zsWD6eOMIUTAsORexTGJsTy7z-4aH0wJ3fT-3luAAUPLBQwGcuHo0P1JnbtPrpuYjaJKSZOeIMOnlryJCspmv-1xG4qAqQ9XaZ9C97oecuj7MMoNwuaZno5MvsY-oi5B_gqED3vIHUjaWCErd4reONyFSWn047dvpE6mwRhZbcOTkAHT8ZyKkHISzopkFg8CD-Mij12unxA3ldcTV7yaviXgxd3eFSD1_Z4L7ZRsDUukCJkJ-8qY2-GWjewzoxl-mAW9D1tLK6qAdc89yFem3JHRW6L1le3YK37-bs6b2a_AqJKsKm5bWw",
      "e": "AQAB",
      "kid": "1"
    }
  ]
}

Filtra los proxies descargados

De forma predeterminada, Edge Microgateway descarga todos los proxies de tu organización de Edge que comienzan con el prefijo de nombre "edgemicro_". Puedes cambiar este valor predeterminado para descargar proxies cuyos nombres coincidan con un patrón.

1. Abre el archivo de configuración de Edge Micro: ~/.edgemicro/org-env-config.yaml
2. Agrega el elemento proxyPattern en edge_config. Por ejemplo, el siguiente patrón descargará proxies como edgemicro_foo, edgemicro_fast y edgemicro_first.

   edge_config:
   …
   proxyPattern: edgemicro_f*

Especifica productos sin proxies de API

En Apigee Edge, puedes crear un producto de API que no contenga ningún proxy de API. Esta configuración del producto permite que una clave de API asociada con ese producto funcione con cualquier proxy implementado en tu organización. A partir de la versión 2.5.4, Edge Microgateway admite esta configuración de producto.

Depuración y solución de problemas

Cómo conectarse a un depurador

Puedes ejecutar Edge Microgateway con un depurador, como node-inspector. Esto es útil para solucionar problemas y depurar complementos personalizados.

1. Reinicia Edge Microgateway en modo de depuración. Para ello, agrega DEBUG=* al comienzo del comando start. Por ejemplo:

   DEBUG=* edgemicro start -o  myorg -e test -k
         db4e9e8a95aa7fabfdeacbb1169d0a8cbe42bec19c6b98129e02 -s
         6e56af7c1b26dfe93dae78a735c8afc9796b077d105ae5618ce7ed

2. Inicia el depurador y configúralo para que escuche en el número de puerto del proceso de depuración.
3. Ahora puedes recorrer el código de Edge Microgateway, establecer puntos de interrupción, observar expresiones, etcétera.

Puedes especificar marcas estándar de Node.js relacionadas con el modo de depuración. Por ejemplo, --nolazy ayuda a depurar código asíncrono.

Verifica los archivos de registro

Si tienes problemas, asegúrate de examinar los archivos de registro para obtener detalles de la ejecución y la información de los errores. Para obtener más información, consulta Administra archivos de registro.

Usa la seguridad de claves de API

Las claves de API proporcionan un mecanismo simple para autenticar a los clientes que realizan solicitudes a Edge Microgateway. Puedes obtener una clave de API copiando el valor de la clave de consumidor (también llamada ID de cliente) de un producto de Apigee Edge que incluya el proxy de autenticación de Edge Microgateway.

Almacenamiento en caché de claves

Las claves de API se intercambian por tokens del portador, que se almacenan en caché. Para inhabilitar el almacenamiento en caché, configura el encabezado Cache-Control: no-cache en las solicitudes entrantes a Edge Microgateway.

Usa una clave de API

Puedes pasar la clave de API en una solicitud a la API como un parámetro de consulta o en un encabezado. De forma predeterminada, el nombre del encabezado y del parámetro de consulta es x-api-key.

Ejemplo de parámetro de consulta:

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

Ejemplo del encabezado:

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

Configura el nombre de la clave de API

De forma predeterminada, x-api-key es el nombre que se usa para el encabezado de la clave de API y el parámetro de consulta. Puedes cambiar este valor predeterminado en el archivo de configuración, como se explica en Realiza cambios en la configuración. Por ejemplo, para cambiar el nombre a apiKey, haz lo siguiente:

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

En este ejemplo, tanto el parámetro de consulta como el nombre del encabezado se cambian a apiKey. El nombre x-api-key ya no funcionará en ninguno de los casos. Consulta también Realiza cambios en la configuración.

Por ejemplo:

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

Para obtener más información sobre el uso de claves de API con solicitudes de proxy, consulta Protege Edge Microgateway.

Usa la seguridad de tokens de OAuth2

En esta sección, se explica cómo obtener tokens de acceso y de actualización de OAuth2. Los tokens de acceso se usan para realizar llamadas seguras a la API a través de microgateway. Los tokens de actualización se usan para obtener nuevos tokens de acceso.

Cómo obtener un token de acceso

En esta sección, se explica cómo usar el proxy edgemicro-auth para obtener un token de acceso.

También puedes obtener un token de acceso con el comando de la CLI de edgemicro token. Para obtener detalles sobre la CLI, consulta Administra tokens.

API 1

Sustituye los nombres de tu organización y entorno en la URL, y sustituye los valores de ID de consumidor y secreto de consumidor obtenidos de una app de desarrollador en Apigee Edge por los parámetros del cuerpo client_id y client_secret:

curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \
-d '{"grant_type": "client_credentials", "client_id": "your_client_id", \
"client_secret": "your_client_secret"}' -H "Content-Type: application/json"

API 2

http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \
-d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"

Resultado de muestra

{
"token": "eyJraWQiOiIxIiwidHlwIjoi",
"access_token": "eyJraWQiOiIxIiwid",
"token_type": "bearer",
"expires_in": "108000"
}

Cómo obtener un token de actualización

Para obtener un token de actualización, realiza una llamada a la API al extremo /token del proxy edgemicro-auth. DEBES realizar esta llamada a la API con el tipo de permiso password. En los siguientes pasos, se explica el proceso.

1. Obtén un token de acceso y de actualización con la API de /token. Ten en cuenta que el tipo de permiso es password:

   curl -X POST \
     https://your_organization-your_environment.apigee.net/edgemicro-auth/token \
     -H 'Content-Type: application/json' \
     -d '{
      "client_id":"mpK6l1Bx9oE5zLdifoDbF931TDnDtLq",
      "client_secret":"bUdDcFgv3nXffnU",
      "grant_type":"password",
      "username":"mpK6lBx9RoE5LiffoDbpF931TDnDtLq",
      "password":"bUdD2FvnMsXffnU"
   }'

   La API devuelve un token de acceso y un token de actualización. La respuesta es similar a la siguiente:

   {
       "token": "your-access-token",
       "access_token": "your-access-token",
       "token_type": "bearer",
       "expires_in": "108000",
       "refresh_token": "your-refresh-token",
       "refresh_token_expires_in": "431999",
       "refresh_token_issued_at": "1562087304302",
       "refresh_token_status": "approved"
   }

2. Ahora puedes usar el token de actualización para obtener un token de acceso nuevo llamando al extremo /refresh de la misma API. Por ejemplo:

   curl -X POST \
     https://willwitman-test.apigee.net/edgemicro-auth/refresh \
     -H 'Content-Type: application/json' \
     -d '{
      "client_id":"mpK6l1Bx9RoE5zLifoDbpF931TDnDtLq",
      "client_secret":"bUdDc2Fv3nMXffnU",
      "grant_type":"refresh_token",
      "refresh_token":"your-refresh-token"
   }'

   La API devuelve un nuevo token de acceso. La respuesta es similar a la siguiente:

   {
       "token": "your-new-access-token"
       }

Supervisión continua

Forever es una herramienta de Node.js que reinicia automáticamente una app de Node.js en caso de que el proceso se detenga o tenga un error. Edge Microgateway tiene un archivo forever.json que puedes configurar para controlar cuántas veces y con qué intervalos se debe reiniciar Edge Microgateway. Este archivo configura un servicio de Forever llamado forever-monitor, que administra Forever de manera programática.

Puedes encontrar el archivo forever.json en el directorio de instalación raíz de Edge Microgateway. Consulta Dónde se instala Edge Microgateway. Para obtener detalles sobre las opciones de configuración, consulta la documentación de forever-monitor.

El comando edgemicro forever incluye marcas que te permiten especificar la ubicación del archivo forever.json (la marca -f) y, además, iniciar o detener el proceso de supervisión de Forever (la marca -a). Por ejemplo:

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

Para obtener más información, consulta Supervisión continua en la referencia de la CLI.

Especifica un extremo de archivo de configuración

Si ejecutas varias instancias de Edge Microgateway, es posible que desees administrar sus configuraciones desde una sola ubicación. Para ello, especifica un extremo HTTP en el que Edge Micro pueda descargar su archivo de configuración. Puedes especificar este extremo cuando inicias Edge Micro con la marca -u.

Por ejemplo:

edgemicro start -o jdoe -e test -u http://mylocalserver/mgconfig -k public_key -s secret_key

donde el extremo mgconfig devuelve el contenido de tu archivo de configuración. Este es el archivo que, de forma predeterminada, se encuentra en ~/.edgemicro y tiene la convención de nombres: org-env-config.yaml.

Inhabilita el almacenamiento en búfer de datos de conexión TCP

Puedes usar el atributo de configuración nodelay para inhabilitar el almacenamiento en búfer de datos en las conexiones TCP que usa Edge Microgateway.

De forma predeterminada, las conexiones TCP usan el algoritmo de Nagle para almacenar datos en el búfer antes de enviarlos. Si configuras nodelay como true, se inhabilita este comportamiento (los datos se activarán de inmediato cada vez que se llame a socket.write()). Consulta también la documentación de Node.js para obtener más detalles.

Para habilitar nodelay, edita el archivo de configuración de Edge Micro de la siguiente manera:

edgemicro:
  nodelay: true
  port: 8000
  max_connections: 1000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Ejecuta Edge Microgateway en modo independiente

Puedes ejecutar Edge Microgateway desconectado por completo de cualquier dependencia de Apigee Edge. Esta situación, llamada modo independiente, te permite ejecutar y probar Edge Microgateway sin una conexión a Internet.

En el modo independiente, las siguientes funciones no funcionan, ya que requieren conexión a Apigee Edge:

• OAuth y clave de API
• Cuota
• Analytics

Por otro lado, los complementos personalizados y el control de aumentos de tráfico funcionan con normalidad, ya que no requieren una conexión a Apigee Edge. Además, un complemento nuevo llamado extauth te permite autorizar llamadas a la API a la micropuerta de enlace con un JWT mientras estás en modo independiente.

Configura e inicia la puerta de enlace

Para ejecutar Edge Microgateway en modo independiente, sigue estos pasos:

1. Asegúrate de tener instalada la versión 2.5.25 o posterior de Edge Microgateway. De lo contrario, debes ejecutar el siguiente comando para actualizar a la versión más reciente:

   npm install -g edgemicro

   Si necesitas ayuda, consulta Instala Edge Microgateway.

2. Crea un archivo de configuración con el siguiente nombre: $HOME/.edgemicro/org_name-env_name-config.yaml

   Por ejemplo:

   vi $HOME/.edgemicro/foo-bar-config.yaml

3. Pega el siguiente código en el archivo:

   edgemicro:
     port: 8000
     max_connections: 1000
     config_change_poll_interval: 600
     logging:
       level: error
       dir: /var/tmp
       stats_log_interval: 60
       rotate_interval: 24
     plugins:
       sequence:
         - extauth
         - spikearrest
   headers:
     x-forwarded-for: true
     x-forwarded-host: true
     x-request-id: true
     x-response-time: true
     via: true
   extauth:
     publickey_url: https://www.googleapis.com/oauth2/v1/certs
   spikearrest:
     timeUnit: second
     allow: 10
     buffersize: 0

4. Exporta la siguiente variable de entorno con el valor "1":

   export EDGEMICRO_LOCAL=1

5. Ejecuta el siguiente comando start, en el que proporcionas valores para crear una instancia del proxy local:

   edgemicro start -o org_name -e environment_name -a local_proxy_name \
     -v local_proxy_version -t target_url -b base_path

   Donde:

   • your_org es el nombre de la "organización" que usaste en el nombre del archivo de configuración.
   • your_environment es el nombre de "env" que usaste en el nombre del archivo de configuración.
   • local_proxy_name es el nombre del proxy local que se creará. Puedes usar cualquier nombre que desees.
   • local_proxy_version es el número de versión del proxy.
   • target_url es la URL del destino del proxy. (El destino es el servicio al que llama el proxy).
   • base_path es la ruta de acceso base del proxy. Este valor debe comenzar con una barra diagonal. Para una ruta de acceso base raíz, especifica solo una barra diagonal, por ejemplo, "/".

   Por ejemplo:

   edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /

6. Probar la configuración

   curl http://localhost:8000/echo  { "error" : "missing_authorization" }

   Debido a que el complemento extauth está en el archivo foo-bar-config.yaml, recibes un error "missing_authorization". Este complemento valida un JWT que debe estar presente en el encabezado Authorization de la llamada a la API. En la siguiente sección, obtendrás un JWT que permitirá que las llamadas a la API se realicen sin el error.

Ejemplo: Obtén un token de autorización

En el siguiente ejemplo, se muestra cómo obtener un JWT del extremo de JWT de Edge Microgateway en Apigee Edge (edgemicro-auth/jwkPublicKeys). Este extremo se implementa cuando realizas una configuración estándar de Edge Microgateway. Para obtener el JWT del extremo de Apigee, primero debes realizar la configuración estándar de Edge Microgateway y conectarte a Internet. El extremo de Apigee se usa aquí solo con fines de ejemplo y no es obligatorio. Si lo deseas, puedes usar otro extremo de token JWT. Si lo haces, deberás obtener el JWT con la API proporcionada para ese extremo.

En los siguientes pasos, se explica cómo obtener un token con el extremo edgemicro-auth/jwkPublicKeys:

1. Debes realizar una configuración estándar de Edge Microgateway para implementar el proxy edgemicro-auth en tu organización o entorno en Apigee Edge. Si ya realizaste este paso, no es necesario que lo repitas.
2. Si implementaste Edge Microgateway en Apigee Cloud, debes estar conectado a Internet para poder obtener un JWT de este extremo.
3. Detén Edge Microgateway:

   edgemicro stop

4. En el archivo de configuración que creaste antes ($HOME/.edgemicro/org-env-config.yaml), dirige el atributo extauth:publickey_url al extremo edgemicro-auth/jwkPublicKeys en tu organización o entorno de Apigee Edge. Por ejemplo:

   extauth:
     publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'

5. Reinicia Edge Microgateway como lo hiciste antes, con los nombres de organización y entorno que usaste en el nombre del archivo de configuración. Por ejemplo:

   edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /

6. Obtén un token JWT del extremo de autorización. Como usas el extremo edgemicro-auth/jwkPublicKeys, puedes usar este comando de la CLI:

Puedes generar un JWT para Edge Microgateway con el comando edgemicro token o una API. Por ejemplo:

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

Donde:

• your_org es el nombre de tu organización de Apigee para la que configuraste Edge Microgateway con anterioridad.
• your_env es un entorno de la organización.
• La opción i especifica la clave de consumidor de una app para desarrolladores que tiene un producto que incluye el proxy edgemicro-auth.
• La opción s especifica el secreto del consumidor de una app de desarrollador que tiene un producto que incluye el proxy edgemicro-auth.

Este comando le pide a Apigee Edge que genere un JWT que, luego, se puede usar para verificar las llamadas a la API.

Prueba la configuración independiente

Para probar la configuración, llama a la API con el token agregado en el encabezado Authorization de la siguiente manera:

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

Ejemplo:

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

Resultado de ejemplo:

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

Usa el modo de proxy local

En el modo de proxy local, Edge Microgateway no requiere que se implemente un proxy compatible con Microgateway en Apigee Edge. En su lugar, debes configurar un "proxy local" proporcionando un nombre de proxy local, una ruta de acceso base y una URL de destino cuando inicies Microgateway. Luego, las llamadas a la API para el microgateway se envían a la URL de destino del proxy local. En todos los demás aspectos, el modo de proxy local funciona exactamente igual que la ejecución de Edge Microgateway en su modo normal. La autenticación funciona de la misma manera, al igual que la detención de aumentos repentinos y la aplicación de cuotas, los complementos personalizados, etcétera.

Caso de uso y ejemplo

El modo de proxy local es útil cuando solo necesitas asociar un proxy único con una instancia de Edge Microgateway. Por ejemplo, puedes insertar Edge Microgateway en Kubernetes como un proxy sidecar, en el que un microgateway y un servicio se ejecutan en un solo Pod, y en el que el microgateway administra el tráfico hacia y desde su servicio complementario. En la siguiente figura, se ilustra esta arquitectura en la que Edge Microgateway funciona como un proxy sidecar en un clúster de Kubernetes. Cada instancia de micropuerta de enlace se comunica solo con un extremo en su servicio complementario:

Un beneficio de este estilo de arquitectura es que Edge Microgateway proporciona administración de APIs para servicios individuales implementados en un entorno de contenedores, como un clúster de Kubernetes.

Configura el modo de proxy local

Para configurar Edge Microgateway de modo que se ejecute en el modo de proxy local, sigue estos pasos:

1. Asegúrate de tener instalada la versión 2.5.25 o posterior de Edge Microgateway. De lo contrario, debes ejecutar el siguiente comando para actualizar a la versión más reciente:

   npm install -g edgemicro

   Si necesitas ayuda, consulta Instala Edge Microgateway.

2. Ejecuta edgemicro init para configurar tu entorno de configuración local, tal como lo harías en una configuración típica de Edge Microgateway. Consulta también Configura Edge Microgateway.
3. Ejecuta edgemicro configure, como lo harías en un procedimiento de configuración típico de Edge Microgateway. Por ejemplo:

   edgemicro configure -o your_org -e your_env -u your_apigee_username

   Este comando implementa la política edgemicro-auth en Edge y devuelve una clave y un secreto que necesitarás para iniciar la micropuerta de enlace. Si necesitas ayuda, consulta Configura Edge Microgateway.

4. En Apigee Edge, crea un producto de API con los siguientes requisitos de configuración obligatorios (puedes administrar todas las demás configuraciones como desees):
   • Debes agregar el proxy edgemicro-auth al producto. Este proxy se implementó automáticamente cuando ejecutaste edgemicro configure.
   • Debes proporcionar una ruta de acceso al recurso. Apigee recomienda agregar esta ruta de acceso al producto: /**. Para obtener más información, consulta Configura el comportamiento de la ruta de acceso del recurso. Consulta también Crea productos de API en la documentación de Edge.

5. En Apigee Edge, crea un desarrollador o, si lo deseas, puedes usar uno existente. Para obtener ayuda, consulta Agrega desarrolladores con la IU de administración de Edge.

6. En Apigee Edge, crea una app de desarrollador. Debes agregar el producto de API que acabas de crear a la app. Para obtener ayuda, consulta Registra una app en la IU de administración de Edge.
7. En la máquina en la que está instalado Edge Microgateway, exporta la siguiente variable de entorno con el valor "1".

   export EDGEMICRO_LOCAL_PROXY=1

8. Ejecuta el siguiente comando de start:

   edgemicro start -o your_org -e your_environment -k your_key -s your_secret \
       -a local_proxy_name -v local_proxy_version -t target_url -b base_path

   Donde:

   • your_org es tu organización de Apigee.
   • your_environment es un entorno de tu organización.
   • your_key es la clave que se devolvió cuando ejecutaste edgemicro configure.
   • your_secret es el secreto que se devolvió cuando ejecutaste edgemicro configure.
   • local_proxy_name es el nombre del proxy local que se creará.
   • local_proxy_version es el número de versión del proxy.
   • target_url es la URL del destino del proxy (el servicio al que llamará el proxy).
   • base_path es la ruta de acceso base del proxy. Este valor debe comenzar con una barra diagonal. Para una ruta de acceso base raíz, especifica solo una barra diagonal, por ejemplo, "/".

   Por ejemplo:

   edgemicro start -o your_org -e test -k 7eb6aae644cbc09035a...d2eae46a6c095f \
     -s e16e7b1f5d5e24df...ec29d409a2df853163a -a proxy1 -v 1 \
     -t http://mocktarget.apigee.net -b /echo

Prueba la configuración

Para probar la configuración del proxy local, llama al extremo del proxy. Por ejemplo, si especificaste una ruta de acceso base de /echo, puedes llamar al proxy de la siguiente manera:

curl  http://localhost:8000/echo
{
  "error" : "missing_authorization",
  "error_description" : "Missing Authorization header"
}

Esta llamada a la API inicial produjo un error porque no proporcionaste una clave de API válida. Puedes encontrar la clave en la app de desarrollador que creaste antes. Abre la app en la IU de Edge, copia la clave de consumidor y úsala de la siguiente manera:

curl  http://localhost:8000/echo -H 'x-api-key:your_api_key'

Por ejemplo:

curl  http://localhost:8000/echo -H "x-api-key:DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP"

Resultado de ejemplo:

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