Cómo usar complementos

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

Edge Microgateway v. 3.1.5 y versiones posteriores

Público

Este tema está dirigido a los operadores de Edge Microgateway que desean usar complementos existentes instalados con la microgateway. También se analizan en detalle los complementos de detención de picos y de cuotas (ambos se incluyen con la instalación). Si eres desarrollador y quieres crear complementos nuevos, consulta Cómo desarrollar complementos personalizados.

¿Qué es un complemento de Edge Microgateway?

Un complemento es un módulo de Node.js que agrega funcionalidad a Edge Microgateway. Los módulos de complementos siguen un patrón coherente y se almacenan en una ubicación conocida por Edge Microgateway, lo que permite que el microgateway los descubra y cargue automáticamente. Edge Microgateway incluye varios complementos existentes, y también puedes crear complementos personalizados, como se explica en Cómo desarrollar complementos personalizados.

Complementos existentes incluidos en Edge Microgateway

En la instalación, se proporcionan varios complementos existentes con Edge Microgateway. Entre ellas, se incluyen las siguientes:

Complemento Habilitado de forma predeterminada Descripción
Analytics Sí Envía datos de estadísticas de Edge Microgateway a Apigee Edge.
oauth Sí Agrega la validación de tokens de OAuth y claves de API a Edge Microgateway. Consulta Cómo configurar Edge Microgateway.
cuota No Aplica cuotas a las solicitudes a Edge Microgateway. Utiliza Apigee Edge para almacenar y administrar las cuotas. Consulta Cómo usar el complemento de cuotas.
spikearrest No Protege contra picos de tráfico y ataques DoS. Consulta Cómo usar el complemento Spike Arrest.
header-uppercase No Un proxy de muestra comentado que se diseñó como guía para ayudar a los desarrolladores a escribir complementos personalizados. Consulta el complemento de muestra de Edge Microgateway.
accumulate-request No Acumula los datos de la solicitud en un solo objeto antes de pasar los datos al siguiente controlador en la cadena de complementos. Es útil para escribir complementos de transformación que necesitan operar en un solo objeto de contenido de solicitud acumulado.
accumulate-response No Acumula los datos de respuesta en un solo objeto antes de pasar los datos al siguiente controlador en la cadena de complementos. Es útil para escribir complementos de transformación que necesitan operar en un solo objeto de contenido de respuesta acumulado.
transform-uppercase No Transforma los datos de la solicitud o la respuesta. Este complemento representa una implementación de práctica recomendada de un complemento de transformación. El complemento de ejemplo realiza una transformación trivial (convierte los datos de la solicitud o la respuesta a mayúsculas); sin embargo, se puede adaptar fácilmente para realizar otros tipos de transformaciones, como de XML a JSON.
json2xml No Transforma los datos de la solicitud o la respuesta según los encabezados accept o content-type. Para obtener más detalles, consulta la documentación del complemento en GitHub.
quota-memory No Aplica cuotas a las solicitudes a Edge Microgateway. Almacena y administra cuotas en la memoria local.
healthcheck No Devuelve información sobre el proceso de Edge Microgateway, como el uso de memoria, el uso de CPU, etcétera. Para usar el complemento, llama a la URL /healthcheck en tu instancia de Edge Microgateway. Este complemento está diseñado para ser un ejemplo que puedes usar para implementar tu propio complemento de verificación de estado.

Dónde encontrar complementos existentes

Los complementos existentes incluidos en Edge Microgateway se encuentran aquí, donde [prefix] es el directorio de prefijo npm. Consulta Dónde se instala Edge Microgateway si no puedes encontrar este directorio.

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins

Cómo agregar y configurar complementos

Sigue este patrón para agregar y configurar complementos:

  1. Detén Edge Microgateway.
  2. Abre un archivo de configuración de Edge Microgateway. Para obtener más información, consulta Cómo realizar cambios en la configuración.
  3. Agrega el complemento al elemento plugins:sequence del archivo de configuración de la siguiente manera. Los complementos se ejecutan en el orden en que aparecen en esta lista.
edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
     level: info
     dir: /var/tmp
     stats_log_interval: 60
  plugins:
     dir: ../plugins
     sequence:   
     - oauth
     - plugin-name
  1. Configura el complemento. Algunos complementos tienen parámetros opcionales que puedes configurar en el archivo de configuración. Por ejemplo, puedes agregar la siguiente estrofa para configurar el complemento spike arrest. Consulta Cómo usar el complemento de detención de picos para obtener más información. 
    edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - spikearrest
spikearrest:
   timeUnit: minute
   allow: 10
  1. Guarda el archivo.
  2. Reinicia o vuelve a cargar Edge Microgateway, según el archivo de configuración que editaste.

Configuración específica del complemento

Puedes anular los parámetros del complemento especificados en el archivo de configuración creando una configuración específica del complemento en este directorio:

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins/config

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

plugins/<plugin_name>/config/default.yaml. Por ejemplo, puedes colocar este bloque en plugins/spikearrest/config/default.yaml, y anulará cualquier otro parámetro de configuración.

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

Cómo usar el complemento de detención de picos

El complemento SpikeArrest protege contra los aumentos repentinos de tráfico. Limita la cantidad de solicitudes que procesa una instancia de Edge Microgateway.

Cómo agregar el complemento de protección contra aumentos de tráfico

Consulta Cómo agregar y configurar complementos.

Configuración de muestra para la detención de picos

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - spikearrest
spikearrest:
   timeUnit: minute
   allow: 10
   bufferSize: 5

Opciones de configuración para la protección contra picos

  • timeUnit: Con qué frecuencia se restablece la ventana de ejecución de la detención de picos. Los valores válidos son segundo o minuto.
  • allow: Es la cantidad máxima de solicitudes que se permiten durante el período timeUnit. Consulta también Si ejecutas varios procesos de Edge Microgateway.
  • bufferSize: (opcional, valor predeterminado = 0) Si bufferSize > 0, la protección contra picos almacena esta cantidad de solicitudes en un búfer. Tan pronto como se produzca la siguiente "ventana" de ejecución, se procesarán primero las solicitudes almacenadas en búfer. Consulta también Cómo agregar un búfer.

¿Cómo funciona Spike Arrest?

Piensa en SpikeArrest como una forma de protección general acerca de los aumentos repentinos de tráfico en lugar de limitar el tráfico a una cantidad específica de solicitudes. Tus APIs y backend pueden controlar una cierta cantidad de tráfico, y la política de SpikeArrest te ayuda a reducir el tráfico a las cantidades generales que deseas.

El comportamiento de SpikeArrest del entorno de ejecución es distinto a lo que podrías esperar de los valores literales por minuto o por segundo que ingresas.

Por ejemplo, supongamos que especificas una frecuencia de 30 solicitudes por minuto, de la siguiente manera:

spikearrest:
   timeUnit: minute
   allow: 30

En las pruebas, podrías pensar que podrías enviar 30 solicitudes en 1 segundo, siempre que estén dentro de un minuto. Pero esa no es la forma en que la política aplica la configuración. Si lo piensas, 30 solicitudes en un período de 1 segundo se podrían considerar un pequeño aumento en algunos entornos.

¿Qué ocurre entonces? Para evitar un comportamiento similar al aumento repentino de actividad, SpikeArrest ajusta el tráfico permitido cuando divide la configuración en intervalos más pequeños, de la siguiente manera:

Tarifas por minuto

Las tarifas por minuto se suman a los intervalos de solicitudes permitidas de segundos. Por ejemplo, 30 solicitudes por minuto se mitigan de la siguiente manera:

60 segundos (1 minuto) / 30 = intervalos de 2 segundos, o aproximadamente 1 solicitud permitida cada 2 segundos. Una segunda solicitud dentro de 2 segundos fallará. Además, fallará la solicitud 31 en un minuto.

Tarifas por segundo

Las tarifas por segundo se suman a las solicitudes permitidas en intervalos de milisegundos. Por ejemplo, 10 solicitudes por segundo se mitigan de la siguiente manera:

1,000 milisegundos (1 segundo) / 10 = intervalos de 100 milisegundos, o aproximadamente 1 solicitud permitida cada 100 milisegundos . Una segunda solicitud dentro de los 100 ms fallarán. Además, fallará la solicitud 11 en un segundo.

Cuando se supera el límite

Si la cantidad de solicitudes supera el límite dentro del intervalo de tiempo especificado, la protección contra aumentos repentinos devuelve este mensaje de error con un estado HTTP 503:

{"error": "spike arrest policy violated"}

Cómo agregar un búfer

Tienes la opción de agregar un búfer a la política. Supongamos que estableces el búfer en 10. Verás que la API no devuelve un error de inmediato cuando superas el límite de detención de picos. En cambio, las solicitudes se almacenan en búfer (hasta la cantidad especificada) y se procesan tan pronto como está disponible la siguiente ventana de ejecución adecuada. El valor predeterminado de bufferSize es 0.

Si ejecutas varios procesos de Edge Microgateway

La cantidad de solicitudes permitidas depende de la cantidad de procesos de trabajo de Edge Micro que se ejecutan. La detención de picos calcula la cantidad permitida de solicitudes por proceso de trabajo. De forma predeterminada, la cantidad de procesos de Edge Micro es igual a la cantidad de CPU en la máquina en la que se instaló Edge Micro. Sin embargo, puedes configurar la cantidad de procesos de trabajo cuando inicias Edge Micro con la opción --processes en el comando start. Por ejemplo, si deseas que la protección contra aumentos repentinos se active con 100 solicitudes en un período determinado y, si inicias Edge Microgateway con la opción --processes 4, establece allow: 25 en la configuración de protección contra aumentos repentinos. En resumen, la regla general es establecer el parámetro de configuración allow en el valor "cantidad deseada de detenciones de picos / cantidad de procesos".

Cómo usar el complemento de cuotas

Una cuota especifica la cantidad de mensajes de solicitud que una app puede enviar a una API durante una hora, un día, una semana o un mes. Cuando una app alcanza su límite de cuota, se rechazan las llamadas a la API posteriores. Consulta también ¿Cuál es la diferencia entre Spike Arrest y la cuota?.

Agrega el complemento de cuotas

Consulta Cómo agregar y configurar complementos.

Configuración del producto en Apigee Edge

Configuras las cuotas en la IU de Apigee Edge, donde configuras los productos de API. Debes saber qué producto contiene el proxy compatible con microgateways que deseas limitar con una cuota. Este producto se debe agregar a una app para desarrolladores. Cuando realices llamadas a la API que se autentiquen con claves en la app para desarrolladores, se aplicará la cuota a esas llamadas a la API.

  1. Accede a tu cuenta de organización de Apigee Edge.
  2. En la IU de Edge, abre el producto asociado con el proxy compatible con la puerta de enlace de microservicios al que deseas aplicar la cuota.
    1. En la IU, selecciona Productos en el menú Publicar.
    2. Abre el producto que contiene la API a la que quieres aplicar la cuota.
    3. Haz clic en Editar.
    4. En el campo Cuota, especifica el intervalo de cuota. Por ejemplo, 100 solicitudes cada minuto. O 50,000 solicitudes cada 2 horas

  1. Haz clic en Guardar.
  2. Asegúrate de que el producto se agregue a una app para desarrolladores. Necesitarás las claves de esta app para realizar llamadas a la API autenticadas.

Configuración de muestra para la cuota

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota

Opciones de configuración de la cuota

Para configurar el complemento de cuotas, agrega el elemento quotas a tu archivo de configuración, como se muestra en el siguiente ejemplo: 

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota
quotas:
    bufferSize:
      hour: 20000
      minute: 500
      month: 1
      default: 10000
    useDebugMpId: true
    failOpen: true
...
Opción Descripción
bufferSize

(Número entero) La configuración de bufferSize te permite ajustar la frecuencia con la que Edge Microgateway sincroniza su recuento de cuotas con Apigee Edge. Para comprender bufferSize, considera el siguiente ejemplo de configuración: 

quotas:
 bufferSize:
  minute: 500
  default: 10000
 useDebugMpId: true
 failOpen: true

De forma predeterminada, el microgateway sincroniza su contador de cuota con Apigee Edge cada 5 segundos si el intervalo de cuota se establece en "minuto". La configuración anterior indica que, si el intervalo de cuota se establece en el producto de la API como "minuto", Edge Microgateway se sincronizará con Edge para obtener el recuento de cuota actual después de cada 500 solicitudes o después de 5 segundos, lo que ocurra primero. Para obtener más información, consulta Cómo se cuentan las cuotas.

Las unidades de tiempo permitidas son: minute, hour, day, week, month y default.

failOpen Cuando esta función está habilitada, si se produce un error de procesamiento de la cuota o si la solicitud de "aplicación de cuota" a Edge no actualiza los contadores de cuota remotos, la cuota se procesará solo en función de los recuentos locales hasta que se produzca la próxima sincronización remota de la cuota. En ambos casos, se establece una marca quota-failed-open en el objeto de solicitud.

Para habilitar la función de "fail open" de la cuota, establece la siguiente configuración: 

edgemicro:
...
quotas:
  failOpen: true
 …
useDebugMpId Establece esta marca en true para habilitar el registro del ID del MP (procesador de mensajes) en las respuestas de cuota.

Para usar esta función, debes establecer la siguiente configuración: 

edgemicro:
...
quotas:
  useDebugMpId: true
...

Cuando se establece useDebugMpId, las respuestas de cuota de Edge contendrán el ID de MP y Edge Microgateway las registrará. Por ejemplo: 

{
    "allowed": 20,
    "used": 3,
    "exceeded": 0,
    "available": 17,
    "expiryTime": 1570748640000,
    "timestamp": 1570748580323,
    "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
}
useRedis Si se configura como true, el complemento usa Redis para el almacén de respaldo de la cuota. Para obtener más información, consulta Cómo usar un almacén de respaldo de Redis para la cuota.

Información sobre cómo se cuentan las cuotas

De forma predeterminada, el microgateway sincroniza su contador de cuota con Apigee Edge cada 5 segundos si el intervalo de cuota se establece en "minuto". Si el intervalo se establece en un nivel superior a "minuto", como "semana" o "mes", el período de actualización predeterminado es de 1 minuto.

Es importante tener en cuenta que debes especificar los intervalos de cuota en los productos de API que se definen en Apigee Edge. Los intervalos de cuota especifican cuántas solicitudes se permiten por minuto, hora, día, semana o mes. Por ejemplo, el producto A podría tener un intervalo de cuota de 100 solicitudes por minuto y el producto B podría tener un intervalo de cuota de 10,000 solicitudes por hora.

La configuración en YAML del complemento quota de Edge Microgateway no establece el intervalo de la cuota, sino que proporciona una forma de ajustar la frecuencia con la que una instancia local de Edge Microgateway sincroniza su recuento de cuotas con Apigee Edge.

Por ejemplo, supongamos que hay tres productos de API definidos en Apigee Edge con los siguientes intervalos de cuota especificados:

  • El producto A tiene una cuota de 100 solicitudes por minuto.
  • El producto B tiene una cuota de 5,000 solicitudes por hora.
  • El producto C tiene una cuota de 1,000,000 de solicitudes por mes.

Teniendo en cuenta esos parámetros de configuración de cuotas, ¿cómo se debería configurar el complemento quota de Edge Microgateway? La práctica recomendada es configurar Edge Microgateway con intervalos de sincronización más bajos que los intervalos de cuota definidos en los productos de API. Por ejemplo: 

quotas:
    bufferSize:
      hour: 2000
      minute: 50
      month: 1
      default: 10000

Esta configuración define los siguientes intervalos de sincronización para los productos de API descritos anteriormente:

  • El producto A se establece en el intervalo "minuto". Edge Microgateway se sincronizará con Edge después de cada 50ª solicitud o cada 5 segundos, lo que ocurra primero.
  • El producto B se establece en el intervalo "hora". Edge Microgateway se sincronizará con Edge después de cada solicitud número 2,000 o cada 1 minuto, lo que ocurra primero.
  • El producto C está configurado en el intervalo "mes". Edge Microgateway se sincronizará con Edge después de cada solicitud o cada 1 minuto, lo que ocurra primero.

Cada vez que una instancia de microgateway se sincroniza con Edge, el recuento de cuotas del microgateway se establece en el recuento de cuotas recuperado.

La configuración de bufferSize te permite ajustar la forma en que el contador de cuotas se sincroniza con Edge. En situaciones de tráfico alto, la configuración de bufferSize permite que el contador del búfer se sincronice antes de que se active la sincronización predeterminada basada en el tiempo.

Información sobre el alcance de la cuota

El recuento de cuotas se limita a un entorno de una organización. Para lograr este alcance, Edge Microgateway crea un identificador de cuota que es una combinación de "org + env + appName + productName".

Usa un almacén de respaldo de Redis para la cuota

Para usar un almacén de respaldo de Redis para la cuota, usa la misma configuración que se usa para la función de Synchronizer. A continuación, se muestra la configuración básica necesaria para usar Redis para el almacenamiento de cuotas: 

edgemicro:
  redisHost: localhost
  redisPort: 6379
  redisDb: 2
  redisPassword: codemaster

quotas:
  useRedis: true
Para obtener detalles sobre los parámetros de edgemicro.redis*, consulta Cómo usar el sincronizador.

Prueba el complemento de cuotas

Cuando se excede la cuota, se devuelve un estado HTTP 403 al cliente, junto con el siguiente mensaje:

{"error": "exceeded quota"}

¿Cuál es la diferencia entre Spike Arrest y la cuota?

Es importante elegir la herramienta adecuada para el trabajo que se debe realizar. Las políticas de cuotas configuran la cantidad de mensajes de solicitud que una app cliente puede enviar a una API en el transcurso de una hora, un día, una semana o un mes. La política de cuotas aplica límites de consumo a las apps cliente manteniendo un recuento distribuido que registra las solicitudes entrantes.

Usa una política de cuotas para aplicar contratos comerciales o ANS con desarrolladores y socios, en lugar de hacerlo para la administración del tráfico operativo. Por ejemplo, una cuota podría usarse para limitar el tráfico de un servicio gratuito, a la vez que permite el acceso completo a los clientes que pagan.

Usa Spike Arrest para protegerte contra los aumentos repentinos en el tráfico de API. Por lo general, la detención de picos se usa para evitar posibles ataques DDoS o de otro tipo.