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

Você está lendo 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 fazer upgrade do Edge Microgateway se você tiver uma conexão com a Internet

Nesta seção, explicamos 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 seguinte comando npm para fazer upgrade para a versão mais recente do Edge Microgateway:

   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 seguinte comando:

   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

Como fazer mudanças de configuração

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

• 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

Nesta seção, vamos falar sobre esses arquivos e o que você precisa saber para mudá-los.

Arquivo de configuração padrão do sistema

Ao instalar 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 esse diretório.

Se você mudar o arquivo de configuração do sistema, precisará reinicializar, reconfigurar e reiniciar o Edge Microgateway:

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

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

Ao executar edgemicro init, o arquivo de configuração do sistema (descrito 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 Edge Microgateway:

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âmica é 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. É possível usar esse arquivo para fazer mudanças de configuração e recarregá-las sem tempo de inatividade. Por exemplo, se você adicionar e configurar um plug-in, poderá recarregar a configuração sem incorrer em inatividade, conforme explicado abaixo.

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

1. Atualize a configuração do Edge Microgateway:

   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 estiver parado:

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 detalhes sobre as configurações do arquivo de configuração, 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 secret necessários para iniciar o Edge Microgateway, podem ser armazenados nestas variáveis de ambiente:

• EDGEMICRO_ORG
• EDGEMICRO_ENV
• EDGEMICRO_KEY
• EDGEMICRO_SECRET

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

Como configurar o SSL no servidor do Edge Microgateway

Assista aos vídeos a seguir para saber como configurar o TLS no Apigee Edge Microgateway:

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

https://localhost:8000/myapi

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

1. Gere ou obtenha um certificado e uma chave SSL usando o utilitário openssl ou o método que preferir.
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 Fazer mudanças na configuração, dependendo do arquivo que você editou: o padrão ou o de configuração de tempo de execução.

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

Usar opções de SSL/TLS do cliente

É possível configurar o Edge Microgateway para ser 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 opções de SSL/TLS. É possível especificar vários destinos específicos. Confira um exemplo de vários destinos abaixo.

Este exemplo fornece 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

Exemplo para TLS:

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

Se você quiser aplicar configurações de TLS/SSL a vários destinos específicos, especifique o primeiro host na configuração como "vazio", o que ativa solicitações universais, e depois 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:

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

Como gerenciar arquivos de registros

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 registros são armazenados

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

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

O diretório em que os arquivos de registro são armazenados é especificado no arquivo de configuração do Edge Microgateway. Consulte também 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 "true" 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 geração de registros

Especifique o nível de registro em log 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 flexibilizar permissões estritas 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 reduzir esse nível de permissão estrito, defina logging:disableStrictLogFile como true. Quando esse atributo é true, o arquivo de registro é criado com o conjunto de permissões de arquivo definido como 0755. Se false ou se o atributo não for fornecido, a permissão será definida como 0600.

Adicionado na v3.2.3.

Exemplo:

edgemicro:
 logging:
   disableStrictLogFile: true

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

À medida que os dados do arquivo de registro se acumulam ao longo do tempo, a Apigee recomenda adotar as seguintes práticas:

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

Convenção de nomenclatura de arquivos de registros

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 dos arquivos de registro

Adicionado na v2.3.3

Por padrão, o serviço de geração de registros omite o JSON de proxies, produtos e o JSON Web Token (JWT) baixados. Se 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 log "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" têm este nome:

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 recebida do cliente
• Solicitação de saída feita 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 tornar os arquivos de registro mais compactos. Confira quatro exemplos de entradas que representam cada um dos quatro eventos. No arquivo de registros, eles aparecem assim (os números das linhas são apenas para referência no documento, não aparecem no arquivo de registros).

(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 geração de registros. Esse valor depende do contexto da transação e do nível de geração de registros definido na configuração edgemicro. Consulte Como definir o nível de geração de registros. 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 de alterações.
• req: identifica o evento. Nesse caso, solicite do cliente.
• m: o verbo HTTP usado na solicitação.
• u: a parte do URL após o basepath.
• h: o host e o número da porta em que o Edge Microgateway está detectando.
• r: o host e a porta remotos 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 usados pelo destino e 4 milissegundos pelo próprio Edge Microgateway.

2. Exemplo de solicitação enviada ao 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 geração de registros. Esse valor depende do contexto da transação e do nível de geração de registros definido na configuração edgemicro. Consulte Como definir o nível de geração de registros. 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 de alterações.
• 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 após o basepath.
• 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 geração de registros. Esse valor depende do contexto da transação e do nível de geração de registros definido na configuração edgemicro. Consulte Como definir o nível de geração de registros. 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 de alterações.
• tres: identifica o evento. Nesse caso, a resposta de destino.
• s: o status da resposta HTTP.
• d: a duração em milissegundos. O tempo gasto na chamada de API 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 geração de registros. Esse valor depende do contexto da transação e do nível de geração de registros definido na configuração edgemicro. Consulte Como definir o nível de geração de registros. 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 de alterações.
• 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 pelo Edge Microgateway.
• i: o ID da entrada de registro. Todas as quatro entradas de evento vão compartilhar esse ID.

Programação de arquivos 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 Práticas recomendadas de manutenção de arquivos de registro.

Mensagens de erro

Algumas entradas de registro vão conter 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 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: none) 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: none) um URL que aponta para o proxy do Edge Microgateway 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 quiser gerenciar cotas pelo proxy edgemicro-auth implantado na sua organização. Se essa propriedade não estiver definida, o endpoint de cota vai usar o endpoint interno do Edge Microgateway por padrão.

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

Atributos do edgemicro

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

• port: (padrão: 8000) o número da porta em que o processo do Edge Microgateway fica à espera.
• max_connections: (padrão: -1) especifica o número máximo de conexões de entrada simultâneas que o Edge Microgateway pode receber. Se esse número for excedido, o seguinte status 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 foi criada para impedir ataques de negação de serviço. Normalmente, defina um número maior que max_connections.
• logging:
  • level: (padrão: error)
    • info: (recomendado) registra todas as solicitações e respostas que passam 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 para erros, além de mensagens de informações, avisos e erros.
    • none: não cria um arquivo de registros.
  • 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 alternados.

• plugins: os plug-ins adicionam funcionalidades ao Edge Microgateway. Para mais detalhes 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.
• sequence: uma lista de módulos de plug-in a serem adicionados à sua instância do Edge Microgateway. Os módulos serão executados na ordem em que forem especificados aqui.

• debug : adiciona depuração remota ao processo do Edge Microgateway.
  • port: 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 Edge Microgateway carrega uma nova configuração periodicamente e executa uma recarga se algo mudar. A pesquisa detecta todas as mudanças feitas no Edge (em produtos, proxies compatíveis com microrrede etc.) e 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: 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 do Node.js nas solicitações. O padrão é 5 segundos a mais que o tempo definido com edgemicro.keep_alive_timeout. Essa configuração padrão impede que balanceadores de carga ou proxies descartem a conexão por engano. (Adicionado na v3.1.1)

• noRuleMatchAction: (string) a ação a ser tomada (permitir ou negar o acesso) se a regra de correspondência especificada no plug-in accesscontrol não for resolvida (não houver correspondência). 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 é fornecido, o plug-in de análise funciona normalmente. Consulte os atributos do edgemicro para mais detalhes. (Adicionado na v3.1.8).

  Exemplo:

  edgemicro
    enableAnalytics=false|true

• on_target_response_abort: esse atributo permite controlar o comportamento do Edge Microgateway 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 Edge Microgateway cancela a solicitação e um aviso é gravado nos arquivos de registro: TargetResponseAborted com o código de status de solicitação 502.

Exemplo:

edgemicro:
 on_target_response_abort: appendErrorToClientResponseBody | abortClientRequest

atributos de cabeçalho

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

• x-forwarded-for: (padrão: true) defina como "false" para impedir que os cabeçalhos x-forwarded-for sejam transmitidos ao destino. Se um cabeçalho x-forwarded-for estiver na solicitação, o valor dele será definido como o valor client-ip no Edge Analytics.
• x-forwarded-host: (padrão: true) defina como "false" para impedir que os cabeçalhos x-forwarded-host sejam transmitidos ao destino.
• x-request-id: (padrão: true) defina como "false" para evitar que os cabeçalhos x-request-id sejam transmitidos ao destino.
• x-response-time: (padrão: true) defina como "false" para impedir que os cabeçalhos x-response-time sejam transmitidos ao destino.
• via: (padrão: true) defina como "false" para impedir que os cabeçalhos "via" sejam transmitidos ao 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 "true", as chamadas de API poderão 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 "true", as chamadas de API poderão ser transmitidas se o token transmitido no cabeçalho de autorização for inválido ou tiver expirado. Defina como "false" 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 em casos em que o destino precisa usar o cabeçalho de autorização 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 "true", o cabeçalho de autorização enviado na solicitação será transmitido ao destino (preservado).
• allowOAuthOnly: se definido como "true", todas as APIs precisarão ter um cabeçalho de autorização com um token de acesso do portador. Permite usar 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ê autorize apenas o modelo de segurança de 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 "Not Before" (nbf) ou "Issued At" (iat) especificados no token de autorização JWT. Defina esse parâmetro como o número de segundos a serem permitidos para essas discrepâncias. (Adicionado na versão 2.5.7)

Atributos específicos do plug-in

Consulte "Usar plug-ins" para detalhes sobre atributos configuráveis de cada plug-in.

Como filtrar proxies

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

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

Filtrar produtos por nome

Use a configuração a seguir para limitar o número de produtos de API que o Edge Microgateway baixa e processa. Para filtrar os produtos baixados, adicione o parâmetro de consulta productnamefilter à API /products listada no arquivo *.config.yaml do Edge Microgateway. 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'

Observação: o valor do parâmetro de consulta precisa ser especificado no formato de expressão regular e codificado para uso em URLs. Por exemplo, a expressão regular ^[Ee]dgemicro.*$ captura nomes como: "edgemicro-test-1" , "edgemicro_demo" e "Edgemicro_New_Demo". O valor codificado por 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 baixados:

...
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 "Develop", abra a política JavaCallout no editor.
3. Adicione um atributo personalizado com a chave products.filter.attributes e uma lista separada por vírgulas de nomes de atributos. Somente produtos que contêm um dos nomes de atributos personalizados serão retornados ao Edge Microgateway.
4. Você pode desativar a verificação para saber se o produto está ativado no ambiente atual definindo o atributo personalizado products.filter.env.enable como false. O padrão é "true".
5. (Somente nuvem privada) Se você estiver no Edge para nuvem privada, defina a propriedade org.noncps como true para extrair produtos de ambientes que não são do 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>

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 Definir variáveis JWT no proxy edgemicro-auth. Para usar essa propriedade e filtrar os produtos de 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 Revogada:

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

Configurar a frequência de push do Google Analytics

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

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

Exemplo:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

Mascaramento de dados de análise

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

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

Como separar chamadas de API no Edge Analytics

É possível configurar o plug-in de análise para separar 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 separar uma API de verificação de integridade no painel para evitar confusão com chamadas reais de proxy de API. No painel do Analytics, os proxies segregados seguem este padrão de nomenclatura:

edgemicro_proxyname-health

A imagem a seguir mostra dois proxies segregados no painel do Google Analytics: 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 basepath do proxy. Para fazer a segregação com base em um caminho completo, incluindo o caminho base, use a flag proxyPath.
• proxyPath (opcional): especifica um caminho completo do proxy de API, 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 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 corporativo

Usar um proxy HTTP para comunicação 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 comunicação 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 de domínios delimitada por vírgulas para os quais o Edge Microgateway não deve fazer 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 do microgateway:

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

   Em que:

   • tunnel: (opcional) quando definido como "true", o Edge Microgateway usa o método HTTP CONNECT para tunelar solicitações HTTP em uma única conexão TCP. O mesmo vale se as variáveis de ambiente, conforme mencionado abaixo, para configurar o proxy estiverem com TLS ativado. 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 devem 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 ignorar.
   • enabled: se for "true" e proxy.url estiver definido, use o valor proxy.url para o proxy HTTP. Se for "true" e proxy.url não estiver definido, use os proxies especificados nas variáveis de ambiente de 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 base de um proxy edgemicro_* (compatível com o microgateway). Por exemplo, um caminho base de /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 na KVM criptografada 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

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 forma 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 é 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 na KVM criptografada 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 seu valor de ID de chave original.

Para gerar um JWT, o Edge usa informações armazenadas na KVM criptografada. Um KVM chamado microgatewayfoi criado e preenchido com chaves quando você configurou inicialmente 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 está associada ao valor public_key1 e é usada para oferecer suporte à rotação de chaves. Esse valor é igual ao kid da chave privada.

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

Quando você faz a rotação de chaves, os valores de chave 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 token_expiry*, padrão de 30 minutos). Assim, é possível "alternar" as chaves sem interromper imediatamente o tráfego da API.

Como fazer a rotação de chaves

Nesta seção, explicamos como fazer uma rotação de chaves.

1. Para fazer upgrade da KVM, use o comando edgemicro upgradekvm. Para mais detalhes sobre a execução desse comando, consulte Fazer upgrade do KVM. Você só precisa fazer isso uma vez.
2. Para fazer upgrade do proxy edgemicro-oauth, use o comando edgemicro upgradeauth. Para detalhes sobre a execução desse comando, consulte Como fazer upgrade do proxy edgemicro-auth. Você só precisa fazer isso uma vez.
3. Adicione a seguinte linha 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 usar:

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

4. Execute o comando de rotação de chaves para girar as chaves. 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 a seguir, cada chave tem um valor "kid" (ID da chave) exclusivo. Em seguida, o microgateway usa essas chaves para validar tokens de autorização. Se a validação do token falhar, o microrreceptáculo vai verificar se há uma chave mais antiga no conjunto de chaves e tentar usá-la. O formato das chaves retornadas é JSON Web Key (JWK). Leia sobre esse formato na RFC 7517 (em inglês).

{
  "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 "not before"

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 ela. No entanto, a nova chave pública só era disponibilizada para instâncias do Edge Microgateway a cada 10 minutos (por padrão) quando a configuração do microgateway era atualizada. Devido a essa defasagem entre a assinatura do token e a atualização da instância do microrgateway, os tokens assinados com a chave mais recente seriam rejeitados até que todas as instâncias recebessem a chave pública mais recente.

Em casos em que há várias instâncias de microrrede, o atraso da chave pública às vezes resultava em erros de execução intermitentes com status 403, porque a validação do token era aprovada em uma instância, mas falhava em outra até que todas as instâncias 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 do microrgateway sejam atualizadas e recebam a nova chave pública. A nova flag é --nbf, que significa "não antes de". Essa flag recebe um valor inteiro, o número de minutos a serem atrasados.

No exemplo a seguir, o atraso é definido como 15 minutos:

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

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

Filtrar proxies baixados

Por padrão, o Edge Microgateway baixa todos os proxies na sua organização do Edge que começam com o prefixo de nomenclatura "edgemicro_". É possível mudar esse padrão para baixar proxies cujos nomes correspondam 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*

Especificar produtos sem proxies de API

No Apigee Edge, é possível criar um produto de API que não contenha 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 é compatível com 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 solucionar 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 a 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 registros

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

Como usar a segurança de chaves de API

As chaves de API oferecem um mecanismo simples para autenticar clientes que fazem solicitações ao Edge Microgateway. Para conseguir uma chave de API, copie o valor da chave do consumidor (também chamada de ID do cliente) de um produto do Apigee Edge que inclua o proxy de autenticação do Edge Microgateway.

Armazenamento de chaves em cache

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

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 cabeçalho e o nome 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"

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 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 alterações na configuração.

Exemplo:

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

Para mais informações sobre como usar chaves de API com solicitações de proxy, consulte Proteger o 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 do 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 microrgateway. Os tokens de atualização são usados para receber novos tokens de acesso.

Como conseguir um token de acesso

Nesta seção, explicamos 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 de corpo

Substitua os nomes da organização e do ambiente no URL e os valores de ID e chave secreta do consumidor obtidos 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. Essa forma de comando também é discutida na RFC 6749: The OAuth 2.0 Authorization Framework.

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. Você PRECISA 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 de 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 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 permanente

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

O arquivo forever.json está no diretório raiz de instalação do Edge Microgateway. Consulte Onde o Edge Microgateway está instalado?. Para detalhes 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 (flag -f) e iniciar/parar o processo de monitoramento do Forever (flag -a). Exemplo:

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

Para mais informações, consulte Monitoramento permanente na referência da CLI.

Como especificar um endpoint de arquivo de configuração

Se você executar várias instâncias do Edge Microgateway, talvez queira gerenciar as configurações em um único local. Para isso, especifique um endpoint HTTP em que o Edge Microgateway 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, está localizado em ~/.edgemicro e tem a convenção de nomenclatura: org-env-config.yaml.

Desativar o armazenamento em buffer de dados de conexão TCP

Você pode usar o atributo de configuração nodelay para desativar o buffer de dados em conexões TCP usadas pelo Edge Microgateway.

Por padrão, as conexões TCP usam o algoritmo de 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

Executar o Edge Microgateway no modo independente

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

No modo independente, os seguintes recursos 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 prevençã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 microrreceptáculo 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 seguinte comando start, 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 "organização" que você usou no nome do arquivo de configuração.
   • $ENV é o nome do "env" que você usou no nome do arquivo de configuração.
   • $LOCAL_PROXY_NAME é o nome do proxy local que será criado. Use o nome que quiser.
   • $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 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 feitas sem o erro.

Exemplo: como conseguir um token de autorização

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

As etapas a seguir explicam como receber 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 isso, não precisa repetir.
2. Se você implantou o Edge Microgateway no Apigee Cloud, precisa estar conectado à Internet para receber 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 sua 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 antes, usando os nomes de organização/ambiente 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, use 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 sua organização da Apigee em que você configurou 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 pede ao Apigee Edge para gerar 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, você configura um "proxy local" fornecendo um nome, um caminho base e um URL de destino ao iniciar o microgateway. As chamadas de API para o microrrecurso 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 restriçã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 arquivo secundário, em que um microgateway e um serviço são executados em um único pod, e em que o microgateway gerencia o tráfego para e do serviço associado. 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 benefício 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 ser executado no modo de proxy local, siga estas etapas:

1. Execute edgemicro init para configurar o ambiente de configuração local, exatamente como 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 típico de configuração 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 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):
   • Você precisa adicionar o proxy edgemicro-auth ao produto. Esse proxy foi implantado automaticamente quando você executou edgemicro configure.
   • Você precisa fornecer um caminho de recurso. A Apigee recomenda adicionar este caminho ao produto: /**. Para saber mais, consulte 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 já existente, se quiser. Para receber ajuda, consulte 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 ajuda, consulte Registrar um app na IU de gerenciamento do 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 retornada quando você executou edgemicro configure.
   • your_secret é o secret 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 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 de proxy. Por exemplo, se você especificou um caminho base de /echo, é possível chamar o proxy da seguinte maneira:

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

Essa chamada de API inicial gerou um erro porque você não forneceu uma chave de API válida. Você pode encontrar a chave no app para desenvolvedores que criou antes. Abra o app na interface do Edge, copie a chave de consumidor e use-a 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 capacidade de recuperação do Edge Microgateway, permitindo que ele recupere dados de configuração do Apigee Edge e os grave em um banco de dados Redis local. Com uma instância do sincronizador em execução, outras instâncias do Edge Microgateway executadas em nós diferentes podem recuperar a configuração diretamente desse banco de dados.

No momento, o recurso de sincronizador é compatível com 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 cada instância do Edge Microgateway use a mesma configuração e que, em caso de interrupção da Internet, as instâncias do Edge Microgateway possam ser iniciadas e executadas corretamente.

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

O sincronizador do Edge Microgateway oferece um mecanismo alternativo para que as instâncias do Edge Microgateway recuperem os dados de configuração necessários para iniciar e processar o tráfego de proxy de API. Os dados de configuração recuperados de chamadas para o Apigee Edge incluem: a chamada jwk_public_keys, a chamada jwt_public_key, a chamada de bootstrap e a chamada de produtos de API. O sincronizador permite que todas as instâncias do Edge Microgateway em execução em diferentes nós 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 especialmente configurada do Edge Microgateway. O único propósito dele é fazer polling do Apigee Edge (o tempo é configurável), recuperar 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 de API. Outras instâncias do Edge Microgateway em execução em nós diferentes podem ser configuradas para recuperar dados de configuração do banco de dados Redis em vez do Apigee Edge. Como todas as instâncias do microrreceptáculo extraem os dados de configuração do banco de dados local, elas podem ser iniciadas e processar solicitações de API mesmo em caso de interrupção da Internet.

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 fazer pesquisas com o Apigee Edge e armazenar os dados de configuração baixados 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 do microgateway que processam o tráfego do proxy de API. No entanto, você configura essas instâncias para receber os dados de configuração do banco de dados Redis em vez do Apigee Edge.

Adicione a seguinte configuração ao arquivo org-env/config.yaml de cada nó adicional do Edge Microgateway. Observe que a propriedade synchronizerMode está definida como 0. Essa propriedade define a instância para operar como uma instância normal do Edge Microgateway que processa o tráfego de proxy de 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 seguintes propriedades de configuração foram adicionadas para oferecer suporte ao uso do sincronizador:

Como configurar URLs de exclusão para plug-ins

É possível configurar o microgateway para ignorar o processamento de plug-ins em URLs especificados. Esses URLs de exclusão podem ser configurados 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ável 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 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. Apenas 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>