Usar plug-ins

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

Edge Microgateway v. 3.2.x

Público-alvo

Este tópico é destinado a operadores do Edge Microgateway que querem usar plug-ins instalados com o microgateway. Ele também discute em detalhes os plug-ins de interrupção de picos e de cota, que estão incluídos na instalação. Se você é um desenvolvedor que quer criar novos plug-ins, consulte Desenvolver plug-ins personalizados.

O que é um plug-in do Edge Microgateway?

Um plug-in é um módulo Node.js que adiciona funcionalidade ao Edge Microgateway. Os módulos de plug-in seguem um padrão consistente e são armazenados em um local conhecido pelo Edge Microgateway, permitindo que o microgateway os descubra e carregue automaticamente. O Edge Microgateway inclui vários plug-ins existentes, e você também pode criar plug-ins personalizados, conforme explicado em Desenvolver plug-ins personalizados.

Plug-ins atuais incluídos no Edge Microgateway

Vários plug-ins atuais são fornecidos com o Edge Microgateway na instalação. Dentre eles:

Onde encontrar plug-ins

Os plug-ins agrupados com o Edge Microgateway estão localizados aqui, em que [prefix] é o diretório de prefixo npm. Consulte Onde o Edge Microgateway está instalado? se não conseguir localizar esse diretório.

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

Adicionar e configurar plug-ins

Siga este padrão para adicionar e configurar plug-ins:

1. Pare o Edge Microgateway.
2. Abra um arquivo de configuração do Edge Microgateway. Para mais detalhes, consulte Fazer mudanças de configuração para opções.
3. Adicione o plug-in ao elemento plugins:sequence do arquivo de configuração da seguinte maneira: Os plug-ins são executados na ordem em que aparecem nessa 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

4. Configure o plug-in. Alguns plug-ins têm parâmetros opcionais que podem ser configurados no arquivo de configuração. Por exemplo, adicione a seguinte estrofe para configurar o plug-in de controle de picos. Consulte Como usar o plug-in de contenção de picos para mais informações.

   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

5. Salve o arquivo.
6. Reinicie ou recarregue o Edge Microgateway, dependendo do arquivo de configuração editado.

Configuração específica do plug-in

É possível substituir os parâmetros do plug-in especificados no arquivo de configuração criando uma configuração específica do plug-in neste diretório:

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

em que [prefix] é o diretório de prefixo npm. Consulte Onde o Edge Microgateway está instalado? se não conseguir localizar esse diretório.

plugins/<plugin_name>/config/default.yaml. Por exemplo, você pode colocar esse bloco em plugins/spikearrest/config/default.yaml, e ele vai substituir qualquer outra configuração.

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

Usar o plug-in de contenção de picos

O plug-in de detenção de pico protege contra picos de tráfego. Ele limita o número de solicitações processadas por uma instância do Edge Microgateway.

Como adicionar o plug-in de controle de pico

Consulte Adicionar e configurar plug-ins.

Exemplo de configuração para controle 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

Opções de configuração para controle de picos

• timeUnit: a frequência com que a janela de execução do controle de picos é redefinida. Os valores válidos são "second" ou "minute".
• allow: o número máximo de solicitações a serem permitidas durante o timeUnit. Consulte também Se você estiver executando vários processos do Edge Micro.
• bufferSize: (opcional, padrão = 0) se bufferSize > 0, o controle de picos armazenará esse número de solicitações em um buffer. Assim que a próxima "janela" de execução ocorrer, as solicitações em buffer serão processadas primeiro. Consulte também Adicionar um buffer.

Como funciona a detenção de pico?

Pense na detenção de pico como uma maneira de proteger contra picos de tráfego, e não como uma forma de limitar o tráfego a um número específico de solicitações. Suas APIs e back-end podem lidar com uma determinada quantidade de tráfego, e a política de detenção de pico ajuda a reduzir o tráfego para os valores gerais que você quer.

O comportamento da detenção de pico de ambiente de execução é diferente do que você espera ver dos valores literais por minuto ou por segundo inseridos.

Por exemplo, digamos que você especifique uma taxa de 30 solicitações por minuto, assim:

spikearrest:
   timeUnit: minute
   allow: 30

Durante os testes, talvez você ache que possa enviar 30 solicitações em um segundo, desde que tenham ocorrido em um minuto. Mas não é assim que a política aplica a configuração. Se você pensar nisso, 30 solicitações dentro de um período de um segundo podem ser consideradas um pequeno pico em alguns ambientes.

O que realmente acontece? Para evitar comportamentos parecidos com os picos, a detenção de pico nivela o tráfego permitido dividindo as configurações em intervalos menores, da seguinte forma:

Taxas por minuto

As taxas por minuto são simplificadas em intervalos de segundos permitidos para solicitações. Por exemplo, 30 solicitações por minuto ficam mais tranquilas assim:

60 segundos (1 minuto) / 30 = intervalos de 2 segundos, ou cerca de 1 solicitação permitida a cada 2 segundos. Uma segunda solicitação dentro de 2 segundos vai falhar. Além disso, uma 31ª solicitação em um minuto vai falhar.

Tarifas por segundo

As taxas por segundo são simplificadas em solicitações permitidas em intervalos de milissegundos. Por exemplo, 10 solicitações/segundo ficam mais tranquilas assim:

1.000 milissegundos (1 segundo) / 10 = intervalos de 100 milissegundos ou cerca de uma solicitação permitida a cada 100 milissegundos. Uma segunda solicitação em 100 ms falhará. Além disso, uma 11ª solicitação em um segundo vai falhar.

Quando o limite é excedido

Se o número de solicitações exceder o limite no intervalo de tempo especificado, a interrupção de picos vai retornar esta mensagem de erro com um status HTTP 503:

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

Adicionar um intervalo

Você pode adicionar um buffer à política. Digamos que você defina o buffer como 10. A API não retorna um erro imediatamente quando você excede o limite de controle de picos. Em vez disso, as solicitações são armazenadas em buffer (até o número especificado) e processadas assim que a próxima janela de execução adequada estiver disponível. O bufferSize padrão é 0.

Se você estiver executando vários processos do Edge Micro

O número de solicitações permitidas depende da quantidade de processos de worker do Edge Micro em execução. O controle de picos calcula o número permitido de solicitações por processo de worker. Por padrão, o número de processos do Edge Micro é igual ao número de CPUs na máquina em que ele está instalado. No entanto, é possível configurar o número de processos de worker ao iniciar o Edge Micro usando a opção --processes no comando start. Por exemplo, se você quiser que a proteção contra picos seja acionada com 100 solicitações em um determinado período e iniciar o Edge Microgateway com a opção --processes 4, defina allow: 25 na configuração de proteção contra picos. Em resumo, a regra prática é definir o parâmetro de configuração allow como o valor "contagem de contenção de picos desejada / número de processos".

Como usar o plug-in de cota

Uma cota especifica o número de mensagens de solicitação que um app pode enviar para uma API ao longo de uma hora, dia, semana ou mês. Quando um app atinge o limite da cota, as chamadas de API subsequentes são rejeitadas. Consulte também Qual é a diferença entre detenção de pico e cota?

Adicionar o plug-in de cota

Consulte Adicionar e configurar plug-ins.

Configuração de produtos no Apigee Edge

As cotas são configuradas na interface do Apigee Edge, onde você configura os produtos de API. Você precisa saber qual produto contém o proxy compatível com microrrede que você quer limitar com uma cota. Esse produto precisa ser adicionado a um app de desenvolvedor. Quando você faz chamadas de API autenticadas usando chaves no app de desenvolvedor, a cota é aplicada a essas chamadas.

1. Faça login na conta da organização do Apigee Edge.
2. Na interface do Edge, abra o produto associado ao proxy compatível com microrrede a que você quer aplicar a cota.
   1. Na interface, selecione Produtos no menu "Publicar".
   2. Abra o produto que contém a API a que você quer aplicar a cota.
   3. Clique em Editar.
   4. No campo "Cota", especifique o intervalo de cota. Por exemplo, 100 solicitações a cada minuto. Ou 50.000 solicitações a cada duas horas.
      
      

3. Clique em Salvar.
4. Verifique se o produto foi adicionado a um app de desenvolvedor. Você vai precisar das chaves desse app para fazer chamadas de API autenticadas.

Exemplo de configuração de cota

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

Opções de configuração para cota

Para configurar o plug-in de cota, adicione o elemento quotas ao arquivo de configuração, conforme mostrado no exemplo a seguir:

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

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

edgemicro:
...
quotas:
  failOpen: true

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

{
    "allowed": 20,
    "used": 3,
    "exceeded": 0,
    "available": 17,
    "expiryTime": 1570748640000,
    "timestamp": 1570748580323,
    "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
}

Como as cotas são contadas

Por padrão, o microgateway sincroniza o contador de cota com o Apigee Edge a cada 5 segundos se o intervalo de cota estiver definido como "minuto". Se o intervalo for definido como um nível maior que "minuto", como "semana" ou "mês", o período de atualização padrão será de 1 minuto.

É importante observar que você especifica intervalos de cota nos produtos de API definidos no Apigee Edge. Os intervalos de cota especificam quantos pedidos são permitidos por minuto, hora, dia, semana ou mês. Por exemplo, o produto A pode ter um intervalo de cota de 100 solicitações por minuto,e o produto B pode ter um intervalo de cota de 10.000 solicitações por hora.

A configuração YAML do plug-in quota do Edge Microgateway não define o intervalo de cota. Em vez disso, ela oferece uma maneira de ajustar a frequência com que uma instância local do Edge Microgateway sincroniza a contagem de cota com o Apigee Edge.

Por exemplo, suponha que haja três produtos de API definidos no Apigee Edge com os seguintes intervalos de cota especificados:

• O produto A tem uma cota de 100 solicitações por minuto.
• O produto B tem uma cota de 5.000 solicitações por hora.
• O produto C tem uma cota de 1.000.000 de solicitações por mês.

Com essas configurações de cota em mente, como o plug-in quota do Edge Microgateway deve ser configurado? A prática recomendada é configurar o Edge Microgateway com intervalos de sincronização menores que os intervalos de cota definidos nos produtos de API. Exemplo:

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

Essa configuração define os seguintes intervalos de sincronização para os produtos de API descritos anteriormente:

• O produto A está definido como o intervalo "minuto". O Edge Microgateway será sincronizado com o Edge após a 50ª solicitação ou 5 segundos, o que ocorrer primeiro.
• O produto B é definido como o intervalo "hora". O Edge Microgateway será sincronizado com o Edge após a cada 2.000 solicitações ou 1 minuto, o que ocorrer primeiro.
• O produto C está definido para o intervalo "mês". O Edge Microgateway será sincronizado com o Edge após cada solicitação ou a cada 1 minuto, o que ocorrer primeiro.

Sempre que uma instância do microrrecurso sincroniza com o Edge, a contagem de cota do microrrecurso é definida como a contagem de cota recuperada.

Com as configurações de bufferSize, é possível ajustar como o contador de cotas é sincronizado com o Edge. Em situações de tráfego intenso, as configurações de bufferSize permitem que o contador de buffer seja sincronizado antes que a sincronização padrão baseada em tempo seja acionada.

Noções básicas sobre o escopo da cota

A contagem de cota tem escopo para um ambiente em uma organização. Para alcançar esse escopo, o Edge Microgateway cria um identificador de cota que é uma combinação de "org + env + appName + productName".

Como usar um armazenamento de apoio do Redis para cota

Para usar um armazenamento de apoio do Redis para cota, use a mesma configuração usada para o recurso Synchronizer. Confira a seguir a configuração básica necessária para usar o Redis no armazenamento de cota:

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

quotas:
  useRedis: true

Como testar o plug-in de cota

Quando a cota é excedida, um status HTTP 403 é retornado ao cliente, junto com a seguinte mensagem:

{"error": "exceeded quota"}

Qual é a diferença entre a detenção de pico e a cota?

É importante escolher a ferramenta certa para o trabalho. As políticas de cota configuram o número de mensagens de solicitação que um app cliente pode enviar para uma API ao longo de uma hora, dia, semana ou mês. A política de cotas impõe limites de consumo aos apps cliente ao manter um contador distribuído que limita as solicitações recebidas.

Use uma política de cota para aplicar contratos comerciais ou SLAs a desenvolvedores e parceiros, em vez de aplicar ao gerenciamento de tráfego operacional. Por exemplo, uma cota pode ser usada para limitar o tráfego de um serviço sem custo financeiro, enquanto permite o acesso total a clientes pagantes.

Use a retenção de pico para se proteger contra picos repentinos no tráfego da API. Normalmente, a contenção de picos é usada para evitar possíveis ataques de DDoS ou outros ataques maliciosos.