Referência de operações e configurações do Edge Microgateway

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

Edge Microgateway v. 3.2.x

Neste tópico, explicamos como gerenciar e configurar o Edge Microgateway.

Como atualizar o Edge Microgateway se você tiver uma conexão de Internet

Esta seção explica como fazer upgrade de uma instalação atual do Edge Microgateway. Se você estiver operando sem uma conexão de Internet, consulte Posso instalar o Edge Microgateway sem uma conexão de Internet?.

A Apigee recomenda testar a configuração atual com a nova versão antes de fazer upgrade do ambiente de produção.

1. Execute o comando npm abaixo para fazer upgrade para a versão mais recente da microgateway do Edge:

   npm upgrade edgemicro -g

   Para instalar uma versão específica do Edge Microgateway, especifique o número da versão no comando de instalação. Por exemplo, para instalar a versão 3.2.3, use o comando abaixo:

   npm install edgemicro@3.2.3 -g

2. Confira o número da versão. Por exemplo, se você instalou a versão 3.2.3:

   edgemicro --version
   current nodejs version is v12.5.0
   current edgemicro version is 3.2.3
       

3. Por fim, faça upgrade para a versão mais recente do proxy edgemicro-auth:

   edgemicro upgradeauth -o $ORG -e $ENV -u $USERNAME

Fazer mudanças de configuração

Os arquivos de configuração que você precisa conhecer são:

• Arquivo de configuração padrão do sistema
• Arquivo de configuração padrão para uma instância do Edge Microgateway recém-inicializada
• Arquivo de configuração dinâmica para instâncias em execução

Esta seção discute esses arquivos e o que você precisa saber sobre como fazer alterações neles.

Arquivo de configuração padrão do sistema

Quando você instala o Edge Microgateway, um arquivo de configuração do sistema padrão é colocado aqui:

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

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

Se você mudar o arquivo de configuração do sistema, será necessário inicializar, reconfigurar e reiniciar a microgateway Edge:

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

Arquivo de configuração padrão para instâncias do Edge Microgateway recém-inicializadas

Quando você executa edgemicro init, o arquivo de configuração do sistema (descrição acima), default.yaml, é colocado no diretório ~/.edgemicro.

Se você mudar o arquivo de configuração em ~/.edgemicro, será necessário reconfigurar e reiniciar o microgateway do Edge:

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

Arquivo de configuração dinâmica para instâncias em execução

Quando você executa edgemicro configure [params], um arquivo de configuração dinâmico é criado em ~/.edgemicro. O arquivo é nomeado de acordo com este padrão: org-env-config.yaml, em que org e env são os nomes da organização e do ambiente do Apigee Edge. Você pode usar esse arquivo para fazer mudanças de configuração e recarregar sem tempo de inatividade. Por exemplo, se você adicionar e configurar um plug-in, será possível recarregar a configuração sem incorrer em nenhum tempo de inatividade, conforme explicado abaixo.

Se o Edge Microgateway estiver em execução (opção de tempo de inatividade zero):

1. Atualize a configuração da microgateway de borda:

   edgemicro reload -o $ORG -e $ENV -k $KEY -s $SECRET

   Em que:

   • $ORG é o nome da sua organização do Edge. Você precisa ser um administrador da organização.
   • $ENV é um ambiente na sua organização, como "test" ou "prod".
   • $KEY é a chave retornada anteriormente pelo comando de configuração.
   • $SECRET é a chave retornada anteriormente pelo comando de configuração.

   Por exemplo:

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

Se o Edge Microgateway for interrompido:

1. Reinicie o Edge Microgateway:

   edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET

   Em que:

   • $ORG é o nome da sua organização do Edge. Você precisa ser um administrador da organização.
   • $ENV é um ambiente na sua organização, como "test" ou "prod".
   • $KEY é a chave retornada anteriormente pelo comando de configuração.
   • $SECRET é a chave retornada anteriormente pelo comando de configuração.

   Exemplo:

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

Confira um exemplo de arquivo de configuração. Para saber mais sobre as configurações do arquivo, consulte a referência de configuração do 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

Como definir variáveis de ambiente

Os comandos da interface de linha de comando que exigem valores para sua organização e ambiente do Edge, além da chave e do segredo necessários para iniciar o microgateway do Edge, podem ser armazenados nestas variáveis de ambiente:

• EDGEMICRO_ORG
• EDGEMICRO_ENV
• EDGEMICRO_KEY
• EDGEMICRO_SECRET

A configuração dessas variáveis é opcional. Se você definir esses valores, não será necessário especificar os valores deles ao usar a interface de linha de comando (CLI) para configurar e iniciar o Edge Microgateway.

Como configurar o SSL no servidor do microgateway do Edge

Assista aos vídeos abaixo para saber como configurar o TLS no microgateway do Apigee Edge:

É possível configurar o servidor da Microgateway para usar o SSL. Por exemplo, com o SSL configurado, é possível chamar APIs pelo Microgateway do Edge com o protocolo "https", assim:

https://localhost:8000/myapi

Para configurar o SSL no servidor da Microgateway, siga estas etapas:

1. Gere ou receba um certificado e uma chave SSL usando o utilitário openssl ou o método de sua preferência.
2. Adicione o atributo edgemicro:ssl ao arquivo de configuração do Edge Microgateway. Para uma lista completa de opções, consulte a tabela abaixo. Por exemplo:
   

   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. Reinicie o Edge Microgateway. Siga as etapas descritas em Como fazer alterações de configuração, dependendo do arquivo de configuração que você editou: o padrão ou o de execução.

Confira um exemplo da seção edgemicro do arquivo de configuração, com 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

Confira uma lista de todas as opções de servidor compatíveis:

Como usar as opções SSL/TLS do cliente

É possível configurar o Edge Microgateway como um cliente TLS ou SSL ao se conectar a endpoints de destino. No arquivo de configuração do Microgateway, use o elemento targets para definir as opções de SSL/TLS. É possível especificar vários destinos específicos. Confira um exemplo de vários destinos abaixo.

Este exemplo fornece as configurações que serão aplicadas a todos os 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

Neste exemplo, as configurações são aplicadas apenas ao 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

Confira um exemplo de TLS:

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

No caso de aplicação de configurações de TLS/SSL a várias metas específicas, especifique o primeiro host na configuração como "vazio", o que ativa as solicitações universais. Em seguida, especifique hosts específicos em qualquer ordem. Neste exemplo, as configurações são aplicadas a vários hosts específicos:

targets:
 - host:   ## Note that this value must be "empty"
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       passphrase: admin123
       rejectUnauthorized: true
 - host: 'myserver1.example.com'
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       rejectUnauthorized: true
 - host: 'myserver2.example.com'
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       rejectUnauthorized: true

Confira uma lista de todas as opções de cliente compatíveis:

Como personalizar o proxy edgemicro-auth

Por padrão, o Edge Microgateway usa um proxy implantado no Apigee Edge para autenticação OAuth2. Esse proxy é implantado quando você executa edgemicro configure pela primeira vez. É possível mudar a configuração padrão desse proxy para adicionar suporte a declarações personalizadas a um JSON Web Token (JWT), configurar a expiração do token e gerar tokens de atualização. Para mais detalhes, consulte a página edgemicro-auth no GitHub.

Como usar um serviço de autenticação personalizado

Por padrão, o Edge Microgateway usa um proxy implantado no Apigee Edge para autenticação OAuth2. Esse proxy é implantado quando você executa edgemicro configure pela primeira vez. Por padrão, o URL desse proxy é especificado no arquivo de configuração do microgateway do Edge da seguinte maneira:

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

Se você quiser usar seu próprio serviço personalizado para processar a autenticação, mude o valor authUri no arquivo de configuração para apontar para seu serviço. Por exemplo, você pode ter um serviço que usa LDAP para verificar a identidade.

Gerenciar arquivos de registro

O Edge Microgateway registra informações sobre cada solicitação e resposta. Os arquivos de registro fornecem informações úteis para depuração e solução de problemas.

Onde os arquivos de registro são armazenados

Por padrão, os arquivos de registro são armazenados em /var/tmp.

Como mudar o diretório de arquivos de registro padrão

O diretório em que os arquivos de registro são armazenados é especificado no arquivo de configuração do Edge Microgateway. Consulte também Como fazer alterações na configuração.

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

Mude o valor dir para especificar um diretório de arquivo de registro diferente.

Enviar registros para o console

É possível configurar o registro para que as informações sejam enviadas para a saída padrão em vez de um arquivo de registro. Defina a flag to_console como verdadeira da seguinte maneira:

edgemicro:
  logging:
    to_console: true

Com essa configuração, os registros serão enviados para a saída padrão. No momento, não é possível enviar registros para stdout e para um arquivo de registro.

Como definir o nível de registro

Especifique o nível de registro a ser usado na configuração edgemicro. Para uma lista completa de níveis de registro e as descrições deles, consulte Atributos do edgemicro.

Por exemplo, a configuração a seguir define o nível de geração de registros como debug:

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

Como mudar os intervalos de registro

É possível configurar esses intervalos no arquivo de configuração do Edge Microgateway. Consulte também Como fazer alterações na configuração.

Os atributos configuráveis são:

• stats_log_interval: (padrão: 60) intervalo, em segundos, em que o registro de estatísticas é gravado no arquivo de registro da API.
• rotate_interval: (padrão: 24) intervalo, em horas, em que os arquivos de registro são alternados. Exemplo:

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

Como relaxar as permissões rígidas de arquivos de registro

Por padrão, o Edge Microgateway gera o arquivo de registro do aplicativo (api-log.log) com o nível de permissão do arquivo definido como 0600. Esse nível de permissão não permite que aplicativos ou usuários externos leiam o arquivo de registro. Para relaxar esse nível de permissão, defina logging:disableStrictLogFile como true. Quando esse atributo é true, o arquivo de registro é criado com a permissão de arquivo definida como 0755. Se false ou se o atributo não for fornecido, a permissão padrão será 0600.

Adicionado na v3.2.3.

Exemplo:

edgemicro:
 logging:
   disableStrictLogFile: true

Boas práticas de manutenção de arquivos de registro

Como os dados do arquivo de registro se acumulam ao longo do tempo, a Apigee recomenda que você adote as seguintes práticas:

• Como os arquivos de registro podem ficar muito grandes, verifique se o diretório de arquivos de registro tem espaço suficiente. Consulte as seções Onde os arquivos de registro são armazenados e Como mudar o diretório de arquivos de registro padrão.
• Exclua ou mova os arquivos de registro para um diretório de arquivo separado pelo menos uma vez por semana.
• Se a sua política for excluir registros, use o comando edgemicro log -c da CLI para remover (limpar) registros mais antigos.

Convenção de nomenclatura de arquivos de registro

Cada instância do Edge Microgateway produz um arquivo de registro com uma extensão .log. A convenção de nomenclatura para arquivos de registro é a seguinte:

edgemicro-HOST_NAME-INSTANCE_ID-api.log

Exemplo:

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log

Sobre o conteúdo do arquivo de registro

Adicionado na v2.3.3

Por padrão, o serviço de registro omite o JSON de proxies, produtos e o JSON Web Token (JWT) baixados. Se você quiser gerar esses objetos no console, defina a flag de linha de comando DEBUG=* ao iniciar o Edge Microgateway. Exemplo:

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

Conteúdo do arquivo de registro "api"

O arquivo de registro "api" contém informações detalhadas sobre o fluxo de solicitações e respostas pelo Edge Microgateway. Os arquivos de registro "api" são nomeados assim:

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

Para cada solicitação feita ao Edge Microgateway, quatro eventos são capturados no arquivo de registro "api":

• Solicitação de entrada do cliente
• Solicitação enviada para o destino
• Resposta recebida do destino
• Resposta enviada ao cliente

Cada uma dessas entradas separadas é representada em uma notação abreviada para ajudar a compactar os arquivos de registro. Confira quatro exemplos de entradas que representam cada um dos quatro eventos. No arquivo de registro, eles têm esta aparência (os números de linha são apenas para referência no documento, eles não aparecem no arquivo 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

Vamos analisar cada um deles:

1. Exemplo de solicitação recebida do cliente:

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

• 1436403888651: carimbo de data/hora do Unix
• info: o nível de registro. Esse valor depende do contexto da transação e do nível de registro definido na configuração edgemicro. Consulte Como definir o nível de registro. Para registros de estatísticas, o nível é definido como stats. Os registros de estatísticas são informados em um intervalo regular definido com a configuração stats_log_interval. Consulte também Como mudar os intervalos de registro.
• req: identifica o evento. Nesse caso, solicite do cliente.
• m: o verbo HTTP usado na solicitação.
• u: é a parte do URL que segue o caminho base.
• h: o host e o número da porta em que o Edge Microgateway está detectando.
• r: o host remoto e a porta em que a solicitação do cliente foi originada.
• i: o ID da solicitação. Todas as quatro entradas de evento vão compartilhar esse ID. Cada solicitação recebe um ID exclusivo. A correlação de registros de log por ID de solicitação pode fornecer insights valiosos sobre a latência do destino.
• d: a duração em milissegundos desde que a solicitação foi recebida pelo Edge Microgateway. No exemplo acima, a resposta do destino para a solicitação 0 foi recebida após 7 milissegundos (linha 3), e a resposta foi enviada ao cliente após mais 4 milissegundos (linha 4). Em outras palavras, a latência total da solicitação foi de 11 milissegundos, dos quais 7 milissegundos foram tomados pelo destino e 4 milissegundos pelo próprio microgateway do Edge.

2. Exemplo de solicitação enviada para o destino:

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

• 1436403888651: carimbo de data/hora do Unix
• info: o nível de registro. Esse valor depende do contexto da transação e do nível de registro definido na configuração edgemicro. Consulte Como definir o nível de registro. Para registros de estatísticas, o nível é definido como stats. Os registros de estatísticas são informados em um intervalo regular definido com a configuração stats_log_interval. Consulte também Como mudar os intervalos de registro.
• treq: identifica o evento. Nesse caso, a solicitação de destino.
• m: o verbo HTTP usado na solicitação de destino.
• u: é a parte do URL que segue o caminho base.
• h: o host e o número da porta do destino de back-end.
• i: o ID da entrada de registro. Todas as quatro entradas de evento vão compartilhar esse ID.

3. Exemplo de resposta recebida do destino

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

1436403888651: carimbo de data/hora do Unix

• info: o nível de registro. Esse valor depende do contexto da transação e do nível de registro definido na configuração edgemicro. Consulte Como definir o nível de registro. Para registros de estatísticas, o nível é definido como stats. Os registros de estatísticas são informados em um intervalo regular definido com a configuração stats_log_interval. Consulte também Como mudar os intervalos de registro.
• tres: identifica o evento. Nesse caso, a resposta de destino.
• s: o status da resposta HTTP.
• d: é a duração em milissegundos. O tempo que a chamada de API leva para ser processada pelo destino.
• i: o ID da entrada de registro. Todas as quatro entradas de evento vão compartilhar esse ID.

4. Exemplo de resposta enviada ao cliente

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

1436403888651: carimbo de data/hora do Unix

• info: o nível de registro. Esse valor depende do contexto da transação e do nível de registro definido na configuração edgemicro. Consulte Como definir o nível de registro. Para registros de estatísticas, o nível é definido como stats. Os registros de estatísticas são informados em um intervalo regular definido com a configuração stats_log_interval. Consulte também Como mudar os intervalos de registro.
• res: identifica o evento. Nesse caso, a resposta ao cliente.
• s: o status da resposta HTTP.
• d: é a duração em milissegundos. Esse é o tempo total gasto pela chamada de API, incluindo o tempo gasto pela API de destino e o tempo gasto pelo próprio Microgateway do Edge.
• i: o ID da entrada de registro. Todas as quatro entradas de evento vão compartilhar esse ID.

Programação do arquivo de registro

Os arquivos de registro são alternados no intervalo especificado pelo atributo de configuração rotate_interval. As entradas vão continuar sendo adicionadas ao mesmo arquivo de registro até que o intervalo de rotação expire. No entanto, sempre que o Edge Microgateway é reiniciado, ele recebe um novo UID e cria um novo conjunto de arquivos de registro com esse UID. Consulte também Boas práticas de manutenção de arquivos de registro.

Mensagens de erro

Algumas entradas de registro contêm mensagens de erro. Para ajudar a identificar onde e por que os erros ocorrem, consulte a referência de erros do Edge Microgateway.

Referência de configuração do Edge Microgateway

Local do arquivo de configuração

Os atributos de configuração descritos nesta seção estão localizados no arquivo de configuração do Edge Microgateway. Consulte também Como fazer alterações na configuração.

Atributos edge_config

Essas configurações são usadas para configurar a interação entre a instância do Edge Microgateway e o Apigee Edge.

• bootstrap (padrão: nenhum): um URL que aponta para um serviço específico do Edge Microgateway em execução no Apigee Edge. O Edge Microgateway usa esse serviço para se comunicar com o Apigee Edge. Esse URL é retornado quando você executa o comando para gerar o par de chaves pública/privada: edgemicro genkeys. Consulte Como configurar e configurar o Edge Microgateway para mais detalhes.
• jwt_public_key: (padrão: nenhum) um URL que aponta para o proxy do microgateway do Edge implantado no Apigee Edge. Esse proxy serve como um endpoint de autenticação para emitir tokens de acesso assinados para clientes. Esse URL é retornado quando você executa o comando para implantar o proxy: edgemicro configure. Consulte Como configurar e configurar o Edge Microgateway para mais detalhes.
• quotaUri: defina essa propriedade de configuração se você quiser gerenciar cotas pelo proxy edgemicro-auth implantado na sua organização. Se essa propriedade não estiver definida, o endpoint de cota será definido como o endpoint interno da microgateway do Edge.

  edge_config:
    quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth
  

atributos do Edgemicro

Essas configurações configuram o processo do Edge Microgateway.

• porta (padrão: 8000): o número da porta em que o processo do microgateway do Edge escuta.
• max_connections: (padrão: -1) especifica o número máximo de entradas simultâneas que o Edge Microgateway pode receber. Se esse número for excedido, o status a seguir será retornado:
  
  res.statusCode = 429; // Too many requests
  
• max_connections_hard: (padrão: -1) é o número máximo de solicitações simultâneas que o Edge Microgateway pode receber antes de encerrar a conexão. Essa configuração tem o objetivo de impedir ataques de negação de serviço. Normalmente, defina um número maior que max_connections.
• Registro:
  • level: (padrão: error)
    • info: (recomendado) registra todas as solicitações e respostas que fluem por uma instância do Edge Microgateway.
    • warn: registra apenas mensagens de aviso.
    • error: registra apenas mensagens de erro.
    • debug: registra mensagens de depuração com mensagens de informação, aviso e erro.
    • trace: registra informações de rastreamento de erros com mensagens de informações, avisos e erros.
    • none: não cria um arquivo de registro.
  • dir: (padrão: /var/tmp) o diretório em que os arquivos de registro são armazenados.
  • stats_log_interval: (padrão: 60) intervalo, em segundos, em que o registro de estatísticas é gravado no arquivo de registro da API.
  • rotate_interval: (padrão: 24) intervalo, em horas, em que os arquivos de registro são girados.

• Plug-ins: eles adicionam funcionalidades ao Edge Microgateway. Para saber mais sobre o desenvolvimento de plug-ins, consulte Desenvolver plug-ins personalizados.

• dir: um caminho relativo do diretório ./gateway para o diretório ./plugins ou um caminho absoluto.
• sequência: uma lista de módulos de plug-in a serem adicionados à instância do Edge Microgateway. Os módulos serão executados na ordem especificada aqui.

• debug : adiciona a depuração remota ao processo do Edge Microgateway.
  • porta: o número da porta a ser detectada. Por exemplo, defina o depurador do ambiente de desenvolvimento integrado para detectar nessa porta.
  • args: argumentos para o processo de depuração. Por exemplo: args --nolazy
    
• config_change_poll_interval:: (padrão: 600 segundos) o microgateway do Edge carrega uma nova configuração periodicamente e executa uma recarga se algo mudar. A pesquisa detecta todas as mudanças feitas no Edge (mudanças em produtos, proxies compatíveis com microgateway etc.), bem como mudanças feitas no arquivo de configuração local.
  
• disable_config_poll_interval: (padrão: false) defina como true para desativar a pesquisa automática de mudanças.
• request_timeout: define um tempo limite para solicitações de destino. O tempo limite é definido em segundos. Se ocorrer um tempo limite, o Edge Microgateway vai responder com um código de status 504. (Adicionado v2.4.x)
• keep_alive_timeout: essa propriedade permite definir o tempo limite do Edge Microgateway (em milissegundos). (Padrão: 5 segundos) (Adicionado na v3.0.6)
• headers_timeout: esse atributo limita a quantidade de tempo (em milissegundos) que o analisador HTTP vai esperar para receber os cabeçalhos HTTP completos.

  Exemplo:

  edgemicro:
    keep_alive_timeout: 6000
    headers_timeout: 12000

  Internamente, o parâmetro define o atributo Server.headersTimeout Node.js nas solicitações. Padrão: 5 segundos a mais do que o tempo definido com edgemicro.keep_alive_timeout. Essa configuração padrão impede que balanceadores de carga ou proxies percam a conexão por engano. (Adicionado na v3.1.1)

• noRuleMatchAction: (String) a ação a ser tomada (permitir ou negar acesso) se a regra de correspondência especificada no plug-in accesscontrol não for resolvida (não corresponder). Valores válidos: ALLOW ou DENY Padrão: ALLOW (Adicionado: v3.1.7)
• enableAnalytics: (padrão: true) defina o atributo como false para impedir que o plug-in do Google Analytics seja carregado. Nesse caso, nenhuma chamada para a análise do Apigee Edge será feita. Se definido como true ou quando esse atributo não for fornecido, o plug-in do Google Analytics vai funcionar normalmente. Consulte atributos do edgemicro para mais detalhes. (Adicionado na v3.1.8).

  Exemplo:

  edgemicro
    enableAnalytics=false|true

• on_target_response_abort: esse atributo permite controlar como o Edge Microgateway se comporta se a conexão entre o cliente (Edge Microgateway) e o servidor de destino for fechada prematuramente.

  Valor	Descrição
  Padrão	Se on_target_response_abort não for especificado, o comportamento padrão será truncar a resposta sem mostrar um erro. Nos arquivos de registro, uma mensagem de aviso é mostrada com targetResponse aborted e um código de resposta 502.
  appendErrorToClientResponseBody	O erro personalizado TargetResponseAborted é retornado ao cliente. Nos arquivos de registro, uma mensagem de aviso é mostrada com targetResponse aborted e um código de resposta 502. Além disso, o erro TargetResponseAborted é registrado com a mensagem Target response ended prematurely.
  abortClientRequest	O microgateway do Edge aborta a solicitação, e um aviso é gravado nos arquivos de registro: TargetResponseAborted com o código de status da solicitação 502.

Exemplo:

edgemicro:
 on_target_response_abort: appendErrorToClientResponseBody | abortClientRequest

atributos de headers

Essas configurações definem como determinados cabeçalhos HTTP são tratados.

• x-forwarded-for: (padrão: verdadeiro) defina como falso para impedir que os cabeçalhos x-forwarded-for sejam transmitidos para o destino. Se um cabeçalho x-forwarded-for estiver na solicitação, o valor dele será definido como o valor de client-ip no Edge Analytics.
• x-forwarded-host: (padrão: verdadeiro) defina como falso para impedir que os cabeçalhos x-forwarded-host sejam transmitidos ao destino.
• x-request-id: (padrão: true) defina como false para impedir que os cabeçalhos x-request-id sejam transmitidos ao destino.
• x-response-time: (padrão: verdadeiro) defina como falso para impedir que cabeçalhos x-response-time sejam transmitidos ao destino.
• via: (padrão: verdadeiro) defina como falso para impedir que os cabeçalhos via sejam transmitidos para o destino.

Atributos do oauth

Essas configurações definem como a autenticação do cliente é aplicada pelo Edge Microgateway.

• allowNoAuthorization: (padrão: false) se definido como verdadeiro, as chamadas de API são permitidas para passar pelo Edge Microgateway sem nenhum cabeçalho de autorização. Defina como false para exigir um cabeçalho de autorização (padrão).
• allowInvalidAuthorization: (padrão: false) se definido como verdadeiro, as chamadas de API poderão ser transmitidas se o token transmitido no cabeçalho "Authorization" for inválido ou expirado. Defina como falso para exigir tokens válidos (padrão).
• authorization-header: (padrão: Authorization: Bearer) o cabeçalho usado para enviar o token de acesso ao Edge Microgateway. Talvez você queira mudar o padrão nos casos em que o destino precisa usar o cabeçalho "Authorization" para outra finalidade.
• api-key-header: (padrão: x-api-key) o nome do cabeçalho ou parâmetro de consulta usado para transmitir uma chave de API ao Edge Microgateway. Consulte também Como usar uma chave de API.
• keep-authorization-header: (padrão: false) se definido como verdadeiro, o cabeçalho de autorização enviado na solicitação é transmitido para o destino (ele é preservado).
• allowOAuthOnly: se definido como "true", todas as APIs precisam ter um cabeçalho de autorização com um token de acesso do portador. Permite que você permita apenas o modelo de segurança OAuth, mantendo a compatibilidade com versões anteriores. (Adicionado na versão 2.4.x)
• allowAPIKeyOnly: se definido como "true", todas as APIs precisam ter um cabeçalho x-api-key (ou um local personalizado) com uma chave de API.Permite que você use apenas o modelo de segurança da chave de API, mantendo a compatibilidade com versões anteriores. (Adicionado na versão 2.4.x)
• gracePeriod: esse parâmetro ajuda a evitar erros causados por pequenas discrepâncias entre o relógio do sistema e os horários de validade (nbf) ou de emissão (iat) especificados no token de autorização do JWT. Defina esse parâmetro como o número de segundos para permitir essas discrepâncias. (Adicionado na versão 2.5.7)

Atributos específicos do plug-in

Consulte o artigo "Como usar plug-ins" para conferir detalhes sobre os atributos configuráveis de cada plug-in.

Como filtrar proxies

É possível filtrar quais proxies compatíveis com o microgateway uma instância do Edge Microgateway vai processar. Quando o Edge Microgateway é iniciado, ele faz o download de todos os proxies compatíveis com o microgateway na organização a que ele está associado. Use a configuração a seguir para limitar quais proxies a microgateway vai processar. Por exemplo, esta configuração limita os proxies que o microgateway processará a três: edgemicro_proxy-1, edgemicro_proxy-2 e edgemicro_proxy-3:

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

Como filtrar produtos por nome

Use a configuração a seguir para limitar o número de produtos de API que o Edge Microgateway faz o download e processa. Para filtrar os produtos transferidos por download, adicione o parâmetro de consulta productnamefilter à API /products listada no arquivo *.config.yaml do microgateway do Edge. Exemplo:

edge_config:
  bootstrap: >-
    https://edgemicroservices.apigee.net/edgemicro/bootstrap/organization/willwitman/environment/test
  jwt_public_key: 'https://myorg-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://myorg-test.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24'

O valor do parâmetro de consulta precisa ser especificado no formato de expressão regular e ter codificação de URL. Por exemplo, o regex ^[Ee]dgemicro.*$ captura nomes como: "edgemicro-test-1" , "edgemicro_demo" e "Edgemicro_New_Demo". O valor codificado do URL, adequado para uso no parâmetro de consulta, é: %5E%5BEe%5Ddgemicro.%2A%24.

A saída de depuração a seguir mostra que apenas os produtos filtrados foram transferidos por download:

...
2020-05-27T03:13:50.087Z [76060] [microgateway-config network] products download from https://gsc-demo-prod.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24 returned 200 OK
...
....
....
{
   "apiProduct":[
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590549037549,
         "createdBy":"k***@g********m",
         "displayName":"test upper case in name",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590549037549,
         "lastModifiedBy":"k***@g********m",
         "name":"Edgemicro_New_Demo",
         "proxies":[
            "catchall"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590548328998,
         "createdBy":"k***@g********m",
         "displayName":"edgemicro test 1",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590548328998,
         "lastModifiedBy":"k***@g********m",
         "name":"edgemicro-test-1",
         "proxies":[
            "Lets-Encrypt-Validation-DoNotDelete"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[
            "/",
            "/**"
         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1558182193472,
         "createdBy":"m*********@g********m",
         "displayName":"Edge microgateway demo product",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1569077897465,
         "lastModifiedBy":"m*********@g********m",
         "name":"edgemicro_demo",
         "proxies":[
            "edgemicro-auth",
            "edgemicro_hello"
         ],
         "quota":"600",
         "quotaInterval":"1",
         "quotaTimeUnit":"minute",
         "scopes":[

         ]
      }
   ]
}

Filtrar produtos por atributos personalizados

Para filtrar produtos com base em atributos personalizados:

1. Na interface do Edge, selecione o proxy edgemicro_auth na organização/ambiente em que você configurou o Edge Microgateway.
2. Na guia "Desenvolvimento", abra a política JavaCallout no editor.
3. Adicione um atributo personalizado com a chave products.filter.attributes e uma lista de nomes de atributos separados por vírgulas. Somente os produtos que contêm qualquer um dos nomes de atributo personalizado serão retornados ao Edge Microgateway.
4. Se quiser, desative a verificação para conferir se o produto está ativado para o ambiente atual definindo o atributo personalizado products.filter.env.enable como false. O padrão é "true".
5. (Somente nuvem privada) Se você estiver usando o Edge para nuvem privada, defina a propriedade org.noncps como true para extrair produtos para ambientes que não são CPS.

Exemplo:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
    <DisplayName>JavaCallout</DisplayName>
    <FaultRules/>
    <Properties>
        <Property name="products.filter.attributes">attrib.one, attrib.two</Property>
        <Property name="products.filter.env.enable">false</Property>
        <Property name="org.noncps">true</Property>
    </Properties>
    <ClassName>io.apigee.microgateway.javacallout.Callout</ClassName>
    <ResourceURL>java://micro-gateway-products-javacallout-2.0.0.jar</ResourceURL>
</JavaCallout>

Como filtrar produtos por status de revogação

Os produtos de API têm três códigos de status: "Pendente", "Aprovado" e "Revogado". Uma nova propriedade chamada allowProductStatus foi adicionada à política de variáveis JWT do proxy edgemicro-auth. Para usar essa propriedade e filtrar os produtos da API listados no JWT:

1. Abra o proxy edgemicro-auth no editor de proxy da Apigee.
2. Adicione a propriedade allowProductStatus ao XML da política SetJWTVariables e especifique uma lista separada por vírgulas de códigos de status para filtrar. Por exemplo, para filtrar por status Pendente e Revogado:

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <Javascript timeLimit="20000" async="false" continueOnError="false"
       enabled="true" name="Set-JWT-Variables">
       <DisplayName>Set JWT Variables</DisplayName>
       <FaultRules/>
       <Properties>
           <Property name="allowProductStatus">Pending,Revoked</Property>
       </Properties>
       <ResourceURL>jsc://set-jwt-variables.js</ResourceURL>
   </Javascript>

   Se você quiser que apenas os produtos Aprovados sejam listados, defina a propriedade da seguinte maneira:

   <Property name="allowProductStatus">Approved</Property>

3. Salve o proxy.

   Se a tag Property não estiver presente, os produtos com todos os códigos de status serão listados no JWT.

   Para usar essa nova propriedade, é necessário fazer upgrade do proxy edgemicro-auth.

Como configurar a frequência de envio do Analytics

Use estes parâmetros de configuração para controlar a frequência com que o Edge Microgateway envia dados de análise para o Apigee:

• bufferSize (opcional): o número máximo de registros de análise que o buffer pode conter antes de começar a descartar os registros mais antigos. Padrão: 10.000
• batchSize (opcional): o tamanho máximo de um lote de registros de análise enviados à Apigee. Padrão: 500
• flushInterval (opcional): o número de milissegundos entre cada limpeza de um lote de registros de análise enviados ao Apigee. Padrão: 5.000

Exemplo:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

Como mascarar dados de análise

A configuração a seguir impede que as informações do caminho da solicitação apareçam no Google Analytics. Adicione o seguinte à configuração do microgateway para mascarar o URI e/ou o caminho da solicitação. O URI consiste nas partes de nome de host e caminho da solicitação.

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

Como segregar chamadas de API no Edge Analytics

É possível configurar o plug-in de análise para segregar um caminho de API específico para que ele apareça como um proxy separado nos painéis do Edge Analytics. Por exemplo, é possível segregar uma API de verificação de integridade no painel para evitar confusão com chamadas de proxy de API reais. No painel do Google Analytics, os proxies segregados seguem este padrão de nomenclatura:

edgemicro_proxyname-health

A imagem a seguir mostra dois proxies segregados no painel de análise: edgemicro_hello-health e edgemicro_mock-health:

Use estes parâmetros para separar caminhos relativos e absolutos no painel do Google Analytics como proxies separados:

• relativePath (opcional): especifica um caminho relativo para segregar no painel do Google Analytics. Por exemplo, se você especificar /healthcheck, todas as chamadas de API que contiverem o caminho /healthcheck vão aparecer no painel como edgemicro_proxyname-health. Essa flag ignora o caminho base do proxy. Para segregar com base em um caminho completo, incluindo o caminho de base, use a flag proxyPath.
• proxyPath (opcional): especifica um caminho de proxy de API completo, incluindo o caminho base do proxy, para segregar no painel de análise. Por exemplo, se você especificar /mocktarget/healthcheck, em que /mocktarget é o caminho base do proxy, todas as chamadas de API com o caminho /mocktarget/healthcheck vão aparecer no painel como edgemicro_proxyname-health.

Por exemplo, na configuração a seguir, qualquer caminho de API que contenha /healthcheck será segregado pelo plug-in de análise. Isso significa que /foo/healthcheck e /foo/bar/healthcheck serão separados como um proxy separado chamado edgemicro_proxyname-health no painel de análise.

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

Na configuração a seguir, qualquer API com o caminho de proxy /mocktarget/healthcheck será segregada como um proxy separado chamado edgemicro_proxyname-health no painel de análise.

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

Como configurar o Edge Microgateway atrás de um firewall da empresa

Usar um proxy HTTP para se comunicar com o Apigee Edge

Adicionado na versão 3.1.2.

Para usar um proxy HTTP na comunicação entre o Edge Microgateway e o Apigee Edge, faça o seguinte:

1. Defina as variáveis de ambiente HTTP_PROXY, HTTPS_PROXY e NO_PROXY. Essas variáveis controlam os hosts de cada proxy HTTP que você quer usar para se comunicar com o Apigee Edge ou quais hosts não devem processar a comunicação com o Apigee Edge. Exemplo:

   export HTTP_PROXY='http://localhost:3786'
   export HTTPS_PROXY='https://localhost:3786'
   export NO_PROXY='localhost,localhost:8080'

   NO_PROXY pode ser uma lista delimitada por vírgulas de domínios que o Edge Microgateway não deve usar como proxy.

   Para mais informações sobre essas variáveis, consulte https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables.

2. Reinicie o Edge Microgateway.

Usar um proxy HTTP para comunicação de destino

Adicionado na versão 3.1.2.

Para usar um proxy HTTP na comunicação entre o Edge Microgateway e os destinos de back-end, faça o seguinte:

1. Adicione a seguinte configuração ao arquivo de configuração da microgateway:

   edgemicro:
     proxy:
       tunnel: true | false
       url: proxy_url
       bypass: target_host # target hosts to bypass the proxy.
       enabled: true | false

   Em que:

   • Túnel (opcional): quando verdadeiro, o Edge Microgateway usa o método HTTP CONNECT para encaminhar solicitações HTTP por uma única conexão TCP. O mesmo acontece se as variáveis de ambiente, conforme mencionado abaixo, para configurar o proxy estiverem ativadas para TLS. Padrão: false
   • url: o URL do proxy HTTP.
   • bypass (opcional): especifica um ou mais URLs de host de destino separados por vírgulas que precisam ignorar o proxy HTTP. Se essa propriedade não estiver definida, use a variável de ambiente NO_PROXY para especificar quais URLs de destino serão ignorados.
   • ativado: se verdadeiro e proxy.url estiver definido, use o valor proxy.url para o proxy HTTP. Se for verdadeiro e proxy.url não estiver definido, use os proxies especificados nas variáveis de ambiente do proxy HTTP HTTP_PROXY e HTTPS_PROXY, conforme descrito em Usar um proxy HTTP para comunicação com o Apigee Edge.

   Exemplo:

   edgemicro:
     proxy:
       tunnel: true
       url: 'http://localhost:3786'
       bypass: 'localhost','localhost:8080' # target hosts to bypass the proxy.
       enabled: true

2. Reinicie o Edge Microgateway.

Como usar caracteres curinga em proxies compatíveis com o Microgateway

É possível usar um ou mais caracteres curinga "*" no caminho de base de um proxy edgemicro_* (compatível com Microgateway). Por exemplo, um caminho de base /team/*/members permite que os clientes chamem https://[host]/team/blue/members e https://[host]/team/green/members sem que você precise criar novos proxies de API para dar suporte a novas equipes. Observe que /**/ não é compatível.

Importante:o Apigee NÃO é compatível com o uso de um caractere curinga "*" como o primeiro elemento de um caminho base. Por exemplo, isto NÃO é compatível: pesquisa /*/.

Como fazer a rotação de chaves JWT

Em algum momento depois de gerar um JWT inicial, talvez seja necessário mudar o par de chaves pública/privada armazenado no KVM criptografado do Edge. Esse processo de geração de um novo par de chaves é chamado de rotação de chaves.

Como o Edge Microgateway usa JWTs

O JSON Web Token (JWT) é um padrão de token descrito na RFC7519. O JWT oferece uma maneira de assinar um conjunto de declarações, que podem ser verificadas de maneira confiável pelo destinatário do JWT.

É possível gerar um JWT usando a CLI e usá-lo no cabeçalho de autorização das chamadas de API em vez de uma chave de API. Exemplo:

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

Para informações sobre como gerar JWTs com a CLI, consulte Gerar um token.

O que é a rotação de chaves?

Em algum momento depois de gerar um JWT inicial, talvez seja necessário mudar o par de chaves pública/privada armazenado no KVM criptografado do Edge. Esse processo de geração de um novo par de chaves é chamado de rotação de chaves. Quando você faz a rotação, um novo par de chaves privada/pública é gerado e armazenado na KVM "microgateway" na organização/ambiente do Apigee Edge. Além disso, a chave pública antiga é mantida com o valor original do ID da chave.

Para gerar um JWT, o Edge usa as informações armazenadas no KVM criptografado. Uma KVM chamada microgateway foi criada e preenchida com chaves quando você configurou o Edge Microgateway. As chaves no KVM são usadas para assinar e criptografar um JWT.

As chaves do KVM incluem:

• private_key: a chave privada RSA mais recente (criada mais recentemente) usada para assinar JWTs.

• public_key: o certificado mais recente (criado mais recentemente) usado para verificar JWTs assinados com a private_key.

• private_key_kid: o ID da chave privada mais recente (criada mais recentemente). Esse ID de chave está associado ao valor private_key e é usado para oferecer suporte à rotação de chaves.

• public_key1_kid: o ID da chave pública mais recente (criada mais recentemente). Essa chave é associada ao valor public_key1 e é usada para oferecer suporte à rotação de chaves. Esse valor é igual ao da chave privada.

• public_key1: a chave pública mais recente (criada mais recentemente).

Quando você realiza a rotação de chaves, os valores de chaves atuais são substituídos no mapa, e novas chaves são adicionadas para manter as chaves públicas antigas. Exemplo:

• public_key2_kid: o ID da chave pública antiga. Essa chave está associada ao valor public_key2 e é usada para oferecer suporte à rotação de chaves.

• public_key2: a chave pública antiga.

Os JWTs apresentados para verificação serão verificados usando a nova chave pública. Se a verificação falhar, a chave pública antiga será usada até que o JWT expire (após o intervalo de token_expiry*, padrão de 30 minutos). Dessa forma, é possível "girar" as chaves sem interromper imediatamente o tráfego da API.

Como fazer a rotação de chaves

Esta seção explica como realizar uma rotação de chaves.

1. Para fazer upgrade da KVM, use o comando edgemicro upgradekvm. Para mais detalhes sobre como executar esse comando, consulte Atualização do KVM. Você só precisa fazer essa etapa uma vez.
2. Para fazer upgrade do proxy edgemicro-oauth, use o comando edgemicro upgradeauth. Para saber como executar esse comando, consulte Como fazer upgrade do proxy edgemicro-auth. Você só precisa fazer essa etapa uma vez.
3. Adicione a linha a seguir ao arquivo ~/.edgemicro/org-env-config.yaml, em que você precisa especificar a mesma organização e o mesmo ambiente que configurou para o microgateway:

   jwk_public_keys: 'https://$ORG-$ENV.apigee.net/edgemicro-auth/jwkPublicKeys'

4. Execute o comando de rotação de chaves para fazer a rotação. Para mais detalhes sobre esse comando, consulte Como fazer rotação de chaves.

   edgemicro rotatekey -o $ORG -e $ENV -k $KEY -s $SECRET

   Exemplo:

   edgemicro rotatekey -o docs -e test \
   -k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
   -s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47
   

Após a rotação de chaves, o Edge retorna várias chaves para o Edge Microgateway. No exemplo abaixo, cada chave tem um valor "kid" (ID da chave) exclusivo. O microgateway usa essas chaves para validar os tokens de autorização. Se a validação do token falhar, o microgateway vai verificar se há uma chave mais antiga no conjunto de chaves e tentará essa chave. O formato das chaves retornadas é a chave JSON da Web (JWK). Leia mais sobre esse formato no 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"
    }
  ]
}

Configurar um atraso "não antes de"

Nas versões 3.1.5 e anteriores, a nova chave privada gerada pelo comando rotatekey entrava em vigor imediatamente, e os novos tokens gerados eram assinados com a nova chave privada. No entanto, a nova chave pública só estava disponível para instâncias do Edge Microgateway a cada 10 minutos (por padrão) quando a configuração do microgateway era atualizada. Devido a esse atraso entre a assinatura do token e a atualização da instância do microgateway, os tokens assinados com a chave mais recente eram rejeitados até que todas as instâncias recebessem a chave pública mais recente.

Nos casos em que há várias instâncias de microgateway, o atraso da chave pública às vezes resultava em erros intermitentes de execução com o status 403, porque a validação do token era transmitida em uma instância, mas falhava em outra até que todas fossem atualizadas.

A partir da versão 3.1.6, uma nova flag no comando rotatekey permite especificar um atraso para que a nova chave privada entre em vigor, tempo para que todas as instâncias de microgateway sejam atualizadas e recebam a nova chave pública. A nova flag é --nbf, que significa "não antes". Essa flag recebe um valor inteiro, o número de minutos de atraso.

No exemplo abaixo, o atraso é definido como 15 minutos:

edgemicro rotatekey -o docs -e test \
-k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
-s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47 \
--nbf 15

Uma boa prática é definir o atraso para mais do que a configuração config_change_poll_internal, que é de 10 minutos por padrão. Consulte também os atributos de edgemicro.

Como filtrar proxies transferidos

Por padrão, o Edge Microgateway faz o download de todos os proxies na sua organização de Edge que começam com o prefixo de nomenclatura "edgemicro_". É possível mudar esse padrão para fazer o download de proxies cujos nomes correspondem a um padrão.

1. Abra o arquivo de configuração do Edge Micro: ~/.edgemicro/org-env-config.yaml
2. Adicione o elemento proxyPattern em edge_config. Por exemplo, o padrão a seguir fará o download de proxies como edgemicro_foo, edgemicro_fast e edgemicro_first.

   edge_config:
   …
   proxyPattern: edgemicro_f*

Como especificar produtos sem proxies de API

No Apigee Edge, é possível criar um produto de API que não contém proxies de API. Essa configuração permite que uma chave de API associada a esse produto funcione com qualquer proxy implantado na sua organização. A partir da versão 2.5.4, o Edge Microgateway oferece suporte a essa configuração de produto.

Como depurar e solucionar problemas

Como se conectar a um depurador

É possível executar o Edge Microgateway com um depurador, como o node-inspector. Isso é útil para resolver problemas e depurar plug-ins personalizados.

1. Reinicie o Edge Microgateway no modo de depuração. Para fazer isso, adicione DEBUG=* ao início do comando start:

   DEBUG=* edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET

   Para direcionar a saída de depuração para um arquivo, use este comando:

   export DEBUG=* nohup edgemicro start \
   -o $ORG -e $ENV -k $KEY -s $SECRET 2>&1 | tee /tmp/file.log

2. Inicie o depurador e configure-o para detectar o número da porta do processo de depuração.
3. Agora é possível percorrer o código do Edge Microgateway, definir pontos de interrupção, observar expressões e assim por diante.

É possível especificar flags padrão do Node.js relacionadas ao modo de depuração. Por exemplo, --nolazy ajuda na depuração de código assíncrono.

Como verificar arquivos de registro

Se você tiver problemas, examine os arquivos de registro para conferir detalhes de execução e informações de erro. Para mais detalhes, consulte Gerenciar arquivos de registro.

Como usar a segurança da chave de API

As chaves de API oferecem um mecanismo simples para autenticar clientes que fazem solicitações para o Edge Microgateway. É possível copiar o valor da chave do consumidor (também chamada de ID do cliente) de um produto do Apigee Edge que inclui o proxy de autenticação do microgateway do Edge.

Armazenamento em cache de chaves

As chaves de API são trocadas por tokens de portador, que são armazenados em cache. É possível desativar o armazenamento em cache definindo o cabeçalho Cache-Control: no-cache nas solicitações recebidas para a microgateway Edge.

Como usar uma chave de API

É possível transmitir a chave de API em uma solicitação de API como um parâmetro de consulta ou em um cabeçalho. Por padrão, o nome do cabeçalho e do parâmetro de consulta são x-api-key.

Exemplo de parâmetro de consulta:

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

Exemplo de cabeçalho:

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

Como configurar o nome da chave de API

Por padrão, x-api-key é o nome usado para o cabeçalho da chave de API e o parâmetro de consulta. É possível mudar esse padrão no arquivo de configuração, conforme explicado em Como fazer mudanças na configuração. Por exemplo, para mudar o nome para apiKey:

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

Neste exemplo, o parâmetro de consulta e o nome do cabeçalho são alterados para apiKey. O nome x-api-key não vai mais funcionar em nenhum dos casos. Consulte também Como fazer mudanças na configuração.

Exemplo:

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

Para mais informações sobre o uso de chaves de API com solicitações de proxy, consulte Secure Edge Microgateway.

Ativar códigos de resposta upstream

Por padrão, o plug-in oauth retorna apenas códigos de status de erro 4xx se a resposta não for um status 200. É possível mudar esse comportamento para que ele sempre retorne o código 4xx ou 5xx exato, dependendo do erro.

Para ativar esse recurso, adicione a propriedade oauth.useUpstreamResponse: true à configuração do Edge Microgateway. Exemplo:

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  gracePeriod: 10
  useUpstreamResponse: true

Como usar a segurança de token OAuth2

Esta seção explica como receber tokens de acesso e de atualização do OAuth2. Os tokens de acesso são usados para fazer chamadas de API seguras pelo microgateway. Os tokens de atualização são usados para receber novos tokens de acesso.

Como receber um token de acesso

Esta seção explica como usar o proxy edgemicro-auth para receber um token de acesso.

Também é possível receber um token de acesso usando o comando edgemicro token da CLI. Para detalhes sobre a CLI, consulte Gerenciar tokens.

API 1: enviar credenciais como parâmetros do corpo

Substitua os nomes da sua organização e do ambiente no URL e substitua os valores de ID e chave secreta do consumidor recebidos de um app de desenvolvedor no Apigee Edge pelos parâmetros de corpo client_id e 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: enviar credenciais em um cabeçalho de autenticação básica

Envie as credenciais do cliente como um cabeçalho de autenticação básica e o grant_type como um parâmetro de formulário. Esse formulário de comando também é discutido no RFC 6749: o framework de autorização OAuth 2.0.

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"

Exemplo de saída

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

Como receber um token de atualização

Para receber um token de atualização, faça uma chamada de API para o endpoint /token do proxy edgemicro-auth. É OBRIGATÓRIO fazer essa chamada de API com o tipo de concessão password. As etapas a seguir explicam o processo.

1. Receba um token de acesso e atualização com a API /token. O tipo de concessão é 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"
   }'

   A API retorna um token de acesso e um token de atualização. A resposta será semelhante a esta. Os valores expires_in são números inteiros e são especificados em segundos.

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

2. Agora é possível usar o token de atualização para receber um novo token de acesso chamando o endpoint /refresh da mesma API. Exemplo:

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

   A API retorna um novo token de acesso. A resposta será semelhante a esta:

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

Monitoramento contínuo

O Forever é uma ferramenta do Node.js que reinicia automaticamente um app Node.js caso o processo seja interrompido ou apresente um erro. O Edge Microgateway tem um arquivo forever.json que pode ser configurado para controlar quantas vezes e com que intervalos o Edge Microgateway precisa ser reiniciado. Esse arquivo configura um serviço Forever chamado forever-monitor, que gerencia o Forever de forma programática.

O arquivo forever.json pode ser encontrado no diretório raiz de instalação do Edge Microgateway. Consulte Onde o Edge Microgateway está instalado. Para saber mais sobre as opções de configuração, consulte a documentação do forever-monitor.

O comando edgemicro forever inclui flags que permitem especificar o local do arquivo forever.json (a flag -f) e iniciar/parar o processo de monitoramento Forever (a flag -a). Exemplo:

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

Para mais informações, consulte a seção Monitoramento Forever na referência da CLI.

Como especificar um endpoint de arquivo de configuração

Se você executar várias instâncias do Edge Microgateway, poderá gerenciar as configurações delas em um único local. Para fazer isso, especifique um endpoint HTTP em que o Edge Micro possa fazer o download do arquivo de configuração. É possível especificar esse endpoint ao iniciar o Edge Micro usando a flag -u.

Exemplo:

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

em que o endpoint mgconfig retorna o conteúdo do arquivo de configuração. Esse é o arquivo que, por padrão, fica localizado em ~/.edgemicro e tem a convenção de nomenclatura: org-env-config.yaml.

Como desativar o armazenamento em buffer de dados de conexão TCP

É possível usar o atributo de configuração nodelay para desativar o armazenamento em buffer de dados para conexões TCP usadas pelo Edge Microgateway.

Por padrão, as conexões TCP usam o algoritmo Nagle para armazenar dados em buffer antes de enviá-los. Definir nodelay como true desativa esse comportamento (os dados são disparados imediatamente sempre que socket.write() é chamado). Consulte também a documentação do Node.js para mais detalhes.

Para ativar o nodelay, edite o arquivo de configuração do Edge Micro da seguinte maneira:

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

Como executar o Edge Microgateway no modo independente

É possível executar o Edge Microgateway desconectado completamente de qualquer dependência do Apigee Edge. Esse cenário, chamado de modo autônomo, permite executar e testar o Edge Microgateway sem uma conexão de Internet.

No modo independente, os recursos a seguir não funcionam, porque exigem conexão com o Apigee Edge:

• OAuth e chave de API
• Cota
• Analytics

Por outro lado, os plug-ins personalizados e a detecção de picos funcionam normalmente, porque não exigem uma conexão com o Apigee Edge. Além disso, um novo plug-in chamado extauth permite autorizar chamadas de API para o microgateway com um JWT no modo independente.

Como configurar e iniciar o gateway

Para executar o Edge Microgateway no modo independente:

1. Crie um arquivo de configuração com o seguinte nome: $HOME/.edgemicro/$ORG-$ENV-config.yaml

   Exemplo:

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

2. Cole o código a seguir no arquivo:

   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

3. Exporte a seguinte variável de ambiente com o valor "1":

   export EDGEMICRO_LOCAL=1

4. Execute o comando start abaixo, em que você fornece valores para instanciar o proxy local:

   edgemicro start -o $ORG -e $ENV -a $LOCAL_PROXY_NAME \
     -v $LOCAL_PROXY_VERSION -t $TARGET_URL -b $BASE_PATH

   Em que:

   • $ORG é o nome da "org" que você usou no arquivo de configuração.
   • $ENV é o nome "env" usado no nome do arquivo de configuração.
   • $LOCAL_PROXY_NAME é o nome do proxy local que será criado. Use qualquer nome.
   • $LOCAL_PROXY_VERSION é o número da versão do proxy.
   • $TARGET_URL é o URL do destino do proxy. O destino é o serviço que o proxy chama.
   • $BASE_PATH é o caminho base do proxy. Esse valor precisa começar com uma barra (/). Para um caminho de base raiz, especifique apenas uma barra, por exemplo, "/".

   Exemplo:

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

5. Testar a configuração.

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

   Como o plug-in extauth está no arquivo foo-bar-config.yaml, você recebe um erro "missing_authorization". Esse plug-in valida um JWT que precisa estar presente no cabeçalho de autorização da chamada de API. Na próxima seção, você vai receber um JWT que permitirá que as chamadas de API sejam concluídas sem o erro.

Exemplo: como conseguir um token de autorização

O exemplo a seguir mostra como receber um JWT do endpoint JWT da Edge Microgateway no Apigee Edge (edgemicro-auth/jwkPublicKeys). Esse endpoint é implantado quando você realiza uma configuração e configuração padrão da Edge Microgateway. Para receber o JWT do endpoint do Apigee, primeiro faça a configuração padrão do Edge Microgateway e se conecte à Internet. O endpoint da Apigee é usado aqui apenas para fins de exemplo e não é obrigatório. Você pode usar outro endpoint de token JWT, se quiser. Se você fizer isso, vai precisar receber o JWT usando a API fornecida para esse endpoint.

As etapas a seguir explicam como conseguir um token usando o endpoint edgemicro-auth/jwkPublicKeys:

1. É necessário realizar uma configuração padrão do Edge Microgateway para implantar o proxy edgemicro-auth na sua organização/ambiente no Apigee Edge. Se você já fez essa etapa, não é necessário repeti-la.
2. Se você implantou o Edge Microgateway no Apigee Cloud, é necessário estar conectado à Internet para conseguir um JWT desse endpoint.
3. Parar o Edge Microgateway:

   edgemicro stop

4. No arquivo de configuração que você criou anteriormente ($HOME/.edgemicro/org-env-config.yaml), aponte o atributo extauth:publickey_url para o endpoint edgemicro-auth/jwkPublicKeys na organização/ambiente do Apigee Edge. Exemplo:

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

5. Reinicie o Edge Microgateway como fez anteriormente, usando os nomes de org/env que você usou no nome do arquivo de configuração. Exemplo:

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

6. Receba um token JWT do endpoint de autorização. Como você está usando o endpoint edgemicro-auth/jwkPublicKeys, é possível usar este comando da CLI:

É possível gerar um JWT para o Edge Microgateway usando o comando edgemicro token ou uma API. Exemplo:

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

Em que:

• your_org é o nome da organização da Apigee que você configurou anteriormente para o Edge Microgateway.
• your_env é um ambiente na organização.
• A opção i especifica a chave do consumidor de um app de desenvolvedor que tem um produto que inclui o proxy edgemicro-auth.
• A opção s especifica a chave secreta do consumidor de um app de desenvolvedor que tem um produto que inclui o proxy edgemicro-auth.

Esse comando solicita que o Apigee Edge gere um JWT que pode ser usado para verificar chamadas de API.

Testar a configuração independente

Para testar a configuração, chame a API com o token adicionado no cabeçalho de autorização da seguinte maneira:

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

Exemplo:

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

Exemplo de saída:

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

Como usar o modo de proxy local

No modo de proxy local, o Edge Microgateway não exige que um proxy compatível com microgateway seja implantado no Apigee Edge. Em vez disso, configure um "proxy local" fornecendo um nome, um caminho base e um URL de destino do proxy local ao iniciar o microgateway. As chamadas de API para o microgateway são enviadas ao URL de destino do proxy local. Em todos os outros aspectos, o modo de proxy local funciona exatamente da mesma forma que a execução do Edge Microgateway no modo normal. A autenticação funciona da mesma forma, assim como a detecção de picos e a aplicação de cotas, plug-ins personalizados e assim por diante.

Caso de uso e exemplo

O modo de proxy local é útil quando você só precisa associar um único proxy a uma instância do Edge Microgateway. Por exemplo, é possível injetar o Edge Microgateway no Kubernetes como um proxy de sidecar, em que um microgateway e um serviço são executados em um único pod, e o microgateway gerencia o tráfego para e do serviço complementar. A figura a seguir ilustra essa arquitetura em que o Edge Microgateway funciona como um proxy secundário em um cluster do Kubernetes. Cada instância de microgateway se comunica apenas com um único endpoint no serviço complementar:

Um dos benefícios desse estilo de arquitetura é que o Edge Microgateway oferece gerenciamento de API para serviços individuais implantados em um ambiente de contêiner, como um cluster do Kubernetes.

Como configurar o modo de proxy local

Para configurar o Edge Microgateway para execução no modo de proxy local, siga estas etapas:

1. Execute edgemicro init para configurar o ambiente de configuração local, exatamente como você faria em uma configuração típica do Edge Microgateway. Consulte também Configurar o Edge Microgateway.
2. Execute edgemicro configure, como faria em um procedimento de configuração típico do Edge Microgateway. Exemplo:

   edgemicro configure -o your_org -e your_env -u your_apigee_username

   Esse comando implanta a política edgemicro-auth no Edge e retorna uma chave e um secret que serão necessários para iniciar o microgateway. Se precisar de ajuda, consulte Configurar o Edge Microgateway.

3. No Apigee Edge, crie um produto de API com os seguintes requisitos de configuração obrigatórios (você pode gerenciar todas as outras configurações como quiser):
   • É necessário adicionar o proxy edgemicro-auth ao produto. Esse proxy foi implantado automaticamente quando você executou edgemicro configure.
   • É necessário informar um caminho de recurso. A Apigee recomenda adicionar este caminho ao produto: /**. Para saber mais, consulte Como configurar o comportamento do caminho do recurso. Consulte também Criar produtos de API na documentação do Edge.

4. No Apigee Edge, crie um desenvolvedor ou use um desenvolvedor existente, se quiser. Para receber ajuda, consulte Como adicionar desenvolvedores usando a interface de gerenciamento do Edge.

5. No Apigee Edge, crie um app de desenvolvedor. É necessário adicionar o produto de API que você acabou de criar ao app. Para obter ajuda, consulte Como registrar um app na IU de gerenciamento do Apigee Edge.
6. Na máquina em que o Edge Microgateway está instalado, exporte a seguinte variável de ambiente com o valor "1".

   export EDGEMICRO_LOCAL_PROXY=1

7. Execute o seguinte comando 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

   Em que:

   • your_org é sua organização da Apigee.
   • your_environment é um ambiente na sua organização.
   • your_key é a chave que foi retornada quando você executou edgemicro configure.
   • your_secret é o secret que foi retornado quando você executou edgemicro configure.
   • local_proxy_name é o nome do proxy local que será criado.
   • local_proxy_version é o número da versão do proxy.
   • target_url é o URL do destino do proxy (o serviço que o proxy vai chamar).
   • base_path é o caminho base do proxy. Esse valor precisa começar com uma barra (/). Para um caminho de base raiz, especifique apenas uma barra, por exemplo, "/".

   Exemplo:

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

Como testar a configuração

É possível testar a configuração do proxy local chamando o endpoint do proxy. Por exemplo, se você especificou um caminho base de /echo, chame o proxy da seguinte maneira:

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

Essa chamada inicial de API gerou um erro porque você não forneceu uma chave de API válida. Você pode encontrar a chave no app para desenvolvedores criado anteriormente. Abra o app na interface do Edge, copie a chave de consumidor e use essa chave da seguinte maneira:

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

Exemplo:

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

Exemplo de saída:

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

Como usar o sincronizador

Esta seção explica como usar o sincronizador, um recurso opcional que melhora a resiliência do Edge Microgateway, permitindo que ele extraia dados de configuração do Apigee Edge e os grave em um banco de dados Redis local. Com uma instância de sincronizador em execução, outras instâncias do Edge Microgateway em execução em nós diferentes podem recuperar a configuração diretamente desse banco de dados.

No momento, o recurso de sincronização tem suporte para o Redis 5.0.x.

O que é o sincronizador?

O sincronizador oferece um nível de resiliência para o Edge Microgateway. Isso ajuda a garantir que todas as instâncias do Edge Microgateway usem a mesma configuração e que, no caso de uma interrupção da Internet, as instâncias do Edge Microgateway possam ser inicializadas e executadas corretamente.

Por padrão, as instâncias do Edge Microgateway precisam se comunicar com o Apigee Edge para extrair e atualizar os dados de configuração, como proxy de API e configurações de produtos de API. Se a conexão de Internet com o Edge for interrompida, as instâncias de microgateway poderão continuar funcionando porque os dados de configuração mais recentes são armazenados em cache. No entanto, novas instâncias de microgateway não podem ser iniciadas sem uma conexão clara. Além disso, é possível que uma interrupção da Internet resulte em uma ou mais instâncias de microgateway em execução com informações de configuração fora de sincronia com outras instâncias.

O sincronizador do Edge Microgateway oferece um mecanismo alternativo para instâncias do Edge Microgateway extraírem dados de configuração necessários para inicializar e processar o tráfego de proxy de API. Os dados de configuração recuperados das chamadas para o Apigee Edge incluem: a chamada jwk_public_keys, a chamada jwt_public_key, a chamada de inicialização e a chamada de produtos de API. O sincronizador permite que todas as instâncias do Edge Microgateway em execução em nós diferentes sejam iniciadas corretamente e permaneçam sincronizadas, mesmo que a conexão de Internet entre o Edge Microgateway e o Apigee Edge seja interrompida.

O sincronizador é uma instância configurada especialmente do Edge Microgateway. O único objetivo é consultar o Apigee Edge (o tempo é configurável), extrair dados de configuração e gravar em um banco de dados Redis local. A própria instância do sincronizador não pode processar o tráfego do proxy da API. Outras instâncias do Edge Microgateway em execução em nós diferentes podem ser configuradas para extrair dados de configuração do banco de dados Redis em vez de do Apigee Edge. Como todas as instâncias de microgateway extraem os dados de configuração do banco de dados local, elas podem inicializar e processar solicitações de API mesmo em caso de interrupção da Internet.

Como configurar uma instância do sincronizador

Adicione a seguinte configuração ao arquivo org-env/config.yaml da instalação do Edge Microgateway que você quer usar como sincronizador:

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

Exemplo:

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

Por fim, salve o arquivo de configuração e inicie a instância do Edge Microgateway. Ele vai começar a consultar o Apigee Edge e armazenar os dados de configuração transferidos no banco de dados Redis.

Como configurar instâncias regulares do Edge Microgateway

Com o sincronizador em execução, é possível configurar outros nós do Edge Microgateway para executar instâncias regulares de microgateway que processam o tráfego do proxy de API. No entanto, você configura essas instâncias para extrair os dados de configuração do banco de dados Redis, em vez de do Apigee Edge.

Adicione a seguinte configuração ao arquivo org-env/config.yaml de cada nó de microgateway do Edge. A propriedade synchronizerMode está definida como 0. Essa propriedade define a instância para operar como uma instância normal do microgateway do Edge que processa o tráfego do proxy da API. A instância vai receber os dados de configuração do banco de dados Redis.

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

Exemplo:

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

Propriedades de configuração

As propriedades de configuração a seguir foram adicionadas para oferecer suporte ao uso do sincronizador:

Como configurar URLs de exclusão para plug-ins

É possível configurar o microgateway para pular o processamento de plug-ins para URLs especificados. Você pode configurar esses URLs de "exclusão" globalmente (para todos os plug-ins) ou para plug-ins específicos.

Exemplo:

...
edgemicro:
  ...
  plugins:
    excludeUrls: '/hello,/proxy_one' # global exclude urls
    sequence:
      - oauth
      - json2xml
      - quota
json2xml:
  excludeUrls: '/hello/xml'  # plugin level exclude urls
...

Neste exemplo, os plug-ins não processam chamadas de proxy de API recebidas com os caminhos /hello ou /proxy_one. Além disso, o plug-in json2xml será ignorado para APIs com /hello/xml no caminho.

Como definir atributos de configuração com valores de variáveis de ambiente

É possível especificar variáveis de ambiente usando tags no arquivo de configuração. As tags de variáveis de ambiente especificadas são substituídas pelos valores reais das variáveis de ambiente. As substituições são armazenadas apenas na memória, e não nos arquivos de configuração ou de cache originais.

Neste exemplo, o atributo key é substituído pelo valor da variável de ambiente TARGETS_SSL_CLIENT_KEY e assim por diante.

targets:
  - ssl:
      client:
        key: <E>TARGETS_SSL_CLIENT_KEY</E>
        cert: <E>TARGETS_SSL_CLIENT_CERT</E>
        passphrase: <E>TARGETS_SSL_CLIENT_PASSPHRASE</E>

Neste exemplo, a tag <n> é usada para indicar um valor inteiro. Somente números inteiros positivos são aceitos.

edgemicro:
  port: <E><n>EMG_PORT</n></E>

Neste exemplo, a tag <b> é usada para indicar um valor booleano ( ou seja, verdadeiro ou falso).

quotas:
  useRedis: <E><b>EMG_USE_REDIS</b></E>