Usar plug-ins

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

Edge Microgateway v. 3.0.x

Público-alvo

Este tópico é destinado a operadores do Edge Microgateway que querem usar plug-ins existentes que são instalados com o microgateway. Ele também discute os plug-ins de detenção de picos e de cotas em detalhes (ambos 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 também é possível criar plug-ins personalizados, conforme explicado em Desenvolver plug-ins personalizados.

Plug-ins incluídos no Edge Microgateway

Vários plug-ins são fornecidos com o Edge Microgateway na instalação. Estes incluem:

Onde encontrar plug-ins

Os plug-ins incluídos no Edge Microgateway estão localizados aqui, em que [prefix] é o npm diretório de prefixo. Consulte Onde o Edge Microgateway está instalado se você não conseguir localizar esse diretório.

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

Como 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, conforme mostrado abaixo. 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, é possível adicionar a seguinte seção para configurar o plug-in de detenção de picos. Consulte Usar o plug-in de detençã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 que você editou.

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 você não conseguir localizar esse diretório.

plugins/<plugin_name>/config/default.yaml. Por exemplo, é possível 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 detenção de picos

O plug-in de detenção de picos 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 detenção de picos

Consulte Como adicionar e configurar plug-ins.

Configuração de amostra para detenção 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 detenção de picos

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

Como a detenção de picos funciona?

Pense na detenção de picos 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 processar uma determinada quantidade de tráfego, e a política de detenção de picos ajuda a suavizar o tráfego para as quantidades gerais desejadas.

O comportamento de detenção de picos no ambiente de execução difere 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

No teste, você pode pensar que pode enviar 30 solicitações em 1 segundo, desde que elas cheguem em um minuto. Mas não é assim que a política aplica a configuração. Se você pensar nisso, 30 solicitações em um período de 1 segundo podem ser consideradas um mini pico em alguns ambientes.

O que realmente acontece? Para evitar comportamentos semelhantes a picos, a detenção de picos suaviza o tráfego permitido dividindo as configurações em intervalos menores, da seguinte maneira:

Taxas por minuto

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

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

Taxas por segundo

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

1.000 milissegundos (1 segundo) / 10 = intervalos de 100 milissegundos ou cerca de 1 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 falhará.

Quando o limite é excedido

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

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

Como adicionar um buffer

Você tem a opção de adicionar um buffer à política. Digamos que você defina o buffer como 10. A API não retornará um erro imediatamente quando você exceder o limite de detenção de picos. Em vez disso, as solicitações são armazenadas em buffer (até o número especificado) e as solicitações armazenadas em buffer são processadas assim que a próxima janela de execução apropriada 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 do número de processos de trabalho do Edge Micro em execução. A detenção de picos calcula o número permitido de solicitações por processo de trabalho. Por padrão, o número de processos do Edge Micro é igual ao número de CPUs na máquina em que o Edge Micro está instalado. No entanto, é possível configurar o número de processos de trabalho ao iniciar o Edge Micro usando a --processes opção no start comando. Por exemplo, se você quiser que a detenção de picos seja acionada em 100 solicitações em um determinado período, e se você iniciar o Edge Microgateway com a opção --processes 4, defina allow: 25 na configuração de detenção de picos. Em resumo, a regra prática é definir o parâmetro de configuração allow config como o valor "contagem de detenção de picos desejada / número de processos".

Usar o plug-in de cota

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

Como adicionar o plug-in de cota

Consulte Como adicionar e configurar plug-ins.

Configuração do produto no Apigee Edge

Você configura cotas na interface do Apigee Edge, onde configura produtos de API. É necessário saber qual produto contém o proxy baseado no microgateway que você quer limitar com uma cota. Esse produto precisa ser adicionado a um app do desenvolvedor. Quando você faz chamadas de API autenticadas usando chaves no app do desenvolvedor, a cota é aplicada a essas chamadas de API.

1. Faça login na sua conta da organização do Apigee Edge.
2. Na interface do Edge, abra o produto associado ao proxy baseado no microgateway ao qual você quer aplicar a cota.
   1. Na interface, selecione Produtos no menu "Publicar".
   2. Abra o produto que contém a API à qual 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 2 horas.
      
      

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

Configuração de amostra para 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
  useRedis: true
  redisHost: localhost
  redisPort: 6379
  redisDb: 1
...

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

Entender o escopo da cota

A contagem de cotas é definida para um produto de API. Se um app do desenvolvedor tiver vários produtos, a cota será definida para cada um deles individualmente. Para alcançar esse escopo, o Edge Microgateway cria um identificador de cota que é uma combinação de "appName + productName".

Testar o plug-in de cota

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

{"error": "exceeded quota"}

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

É importante escolher a ferramenta certa para o trabalho em questão. As políticas de cota configuram o número de mensagens de solicitação que um app cliente pode enviar a uma API durante uma hora, um dia, uma semana ou um mês. A política de cota aplica limites de consumo em apps cliente, mantendo um contador distribuído que totaliza 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, permitindo acesso total para clientes pagantes.

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