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

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. informações

Edge Microgateway v. 3.3.x

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

Como fazer upgrade do Edge Microgateway se você tiver uma conexão de Internet

Nesta seção, explicamos como fazer upgrade de uma instalação 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, você precisa especificar o número da versão no comando de instalação. Por exemplo, para instalar para 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 na 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 recém-inicializada do Edge Microgateway
• 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.

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

Se você alterar 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 recém-inicializadas do Edge Microgateway

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

Se você alterar o arquivo de configuração em ~/.edgemicro, precisará 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 seus nomes de ambiente e organização do Apigee Edge. É possível usar esse arquivo para fazer alterações na configuração e recarregá-las com inatividade zero. Por exemplo, se você adicionar e configurar um plug-in, poderá recarregar a configuração sem causar inatividade, conforme explicado abaixo.

Se o Edge Microgateway estiver em execução (opção sem inatividade):

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 de 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. Reiniciar o Edge Microgateway:

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

   Em que:

   • $ORG é o nome da sua organização de Edge (você precisa ser um administrador da organização).
   • $ENV é um ambiente na organização, como "teste" 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. Saiba mais sobre as definições do arquivo de configuração em 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

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 configuração dessas variáveis é opcional. Se você configurá-los, não precisará 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 Edge Microgateway

Assista os vídeos a seguir para saber mais sobre a configuração do TLS no Apigee Edge Microgateway:

Video	Descrição
Configurar o TLS unidirecional no norte	Saiba como configurar o TLS no Apigee Edge Microgateway. Este vídeo fornece uma visão geral do TLS e sua importância, apresenta o TLS no Edge Microgateway e demonstra como configurar o TLS unidirecional da direção norte.
Configurar o TLS bidirecional de sentido norte	Este é o segundo vídeo sobre como configurar o TLS no Apigee Edge Microgateway. Este vídeo explica como configurar o TLS bidirecional de sentido norte.
Configurar o TLS unidirecional e bidirecional	Este terceiro vídeo sobre como configurar o TLS no Apigee Edge Microgateway explica como configurar o TLS de 1 e 2 vias para o sul.

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

https://localhost:8000/myapi

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

1. Gere ou consiga um certificado SSL e uma chave 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 Como fazer alterações na configuração, dependendo do arquivo de configuração editado: o arquivo padrão ou o arquivo de configuração do ambiente de execução.

Veja 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

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

Opção	Descrição
key	Caminho para um arquivo ca.key (no formato PEM).
cert	Caminho para um arquivo ca.cert (no formato PEM).
pfx	Caminho para um arquivo pfx que contém a chave privada, o certificado e os certificados de CA do cliente no formato PFX.
passphrase	String com a senha longa da chave privada ou PFX.
ca	Caminho para um arquivo que contém uma lista de certificados confiáveis no formato PEM.
ciphers	Uma string que descreve as criptografias a serem usadas, separadas por um ":".
rejectUnauthorized	Se verdadeiro, o certificado do servidor será verificado em relação à lista de CAs fornecidas. Se a verificação falhar, será retornado um erro.
secureProtocol	O método SSL a ser usado. Por exemplo, SSLv3_method para forçar o SSL para a versão 3.
servername	O nome do servidor para a extensão TLS de SNI (Indicação de Nome do Servidor).
requestCert	verdadeiro para SSL bidirecional; falso para SSL unidirecional

Como usar opções 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 Microgateway, use o elemento de destino para definir as opções de SSL/TLS. É possível especificar vários destinos específicos. Confira abaixo um exemplo de destinos múltiplos.

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

Quando você quiser aplicar configurações de TLS/SSL a vários destinos específicos, será preciso determinar o primeiro host na configuração como "empty", o que ativa as solicitações universais, e especificar 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

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

Opção	Descrição
pfx	Caminho para um arquivo pfx que contém a chave privada, o certificado e os certificados de CA do cliente no formato PFX.
key	Caminho para um arquivo ca.key (no formato PEM).
passphrase	String com a senha longa da chave privada ou PFX.
cert	Caminho para um arquivo ca.cert (no formato PEM).
ca	Caminho para um arquivo que contém uma lista de certificados confiáveis no formato PEM.
ciphers	Uma string que descreve as criptografias a serem usadas, separadas por um ":".
rejectUnauthorized	Se verdadeiro, o certificado do servidor será verificado em relação à lista de CAs fornecidas. Se a verificação falhar, será retornado um erro.
secureProtocol	O método SSL a ser usado. Por exemplo, SSLv3_method para forçar o SSL para a versão 3.
servername	O nome do servidor para a extensão TLS de SNI (Indicação de Nome do Servidor).

Como personalizar o proxy Edgemicro-auth

Por padrão, o Edge Microgateway usa um proxy implantado no Apigee Edge para a autenticação OAuth2. Esse proxy é implantado quando você executa edgemicro configure inicialmente. Você pode alterar a configuração padrão desse proxy para adicionar suporte a declarações personalizadas para um JSON Web Token (JWT), configurar a expiração do token e gerar tokens de atualização. Para saber 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 a autenticação OAuth2. Esse proxy é implantado quando você executa edgemicro configure inicialmente. 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 lidar com a autenticação, altere 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 registro

O Edge Microgateway registra informações sobre cada solicitação e resposta. Os arquivos de registros oferecem 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 alterar o diretório do arquivo de registros padrão

O diretório em que os arquivos de registros 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

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

Enviar registros para o console

É possível configurar a geração de registros para que as informações de registro sejam enviadas para a saída padrão e não para um arquivo de registros. 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. Atualmente, não é possível enviar registros para stdout e para um arquivo de registro.

Como definir o nível de geração de registros

Você especifica o nível de registro a ser usado na configuração edgemicro. Para conferir uma lista completa dos níveis de registro e as descrições deles, consulte Atributos 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 alterar 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, quando o registro de estatísticas é gravado no arquivo de registros da API.
• rotate_interval: (padrão: 24) intervalo, em horas, quando os arquivos de registros são girados. 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 permissões estritas de arquivos de registro

Por padrão, o Edge Microgateway gera o arquivo de registros 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 autoriza que aplicativos externos ou usuários leiam o arquivo de registros. Para relaxar esse nível de permissão rigoroso, defina logging:disableStrictLogFile como true. Quando esse atributo é true, o arquivo de registros é criado com a permissão definida como 0755. Se for false ou se o atributo não for fornecido, o padrão da permissão será 0600.

Adicionado na v3.2.3.

Exemplo:

edgemicro:
 logging:
   disableStrictLogFile: true

Práticas recomendadas de manutenção de arquivos de registros

À medida que os dados do arquivo de registros são acumulados ao longo do tempo, a Apigee recomenda que você adote as seguintes práticas:

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

Convenção de nomenclatura do arquivo de registros

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

edgemicro-HOST_NAME-INSTANCE_ID-api.log

Exemplo:

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log

Sobre o conteúdo do arquivo de registros

Adicionado em: 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) salvos. Se você quiser enviar esses objetos para o console, defina a sinalização 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 registros "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 recebida 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 tornar os arquivos de registros mais compactos. Aqui estão quatro entradas de amostra que representam cada um dos quatro eventos. No arquivo de registro, eles têm a seguinte aparência (os números de linha são apenas para referência no documento, eles 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 um a um:

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 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 do 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 alterar intervalos de registro.
• req: identifica o evento. Nesse caso, faça a solicitação do cliente.
• m: o verbo HTTP usado na solicitação.
• u: a parte do URL após o caminho de base.
• h: o host e o número da porta em que o Edge Microgateway está detectando.
• r: o host remoto e a porta de origem da solicitação do cliente.
• i: o ID da solicitação. As quatro entradas de evento compartilharão esse ID. Cada solicitação recebe um ID exclusivo. A correlação de registros de registro pelo ID da 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 sete milissegundos (linha 3), e a resposta foi enviada ao cliente após mais quatro milissegundos (linha 4). Em outras palavras, a latência total da solicitação foi de 11 milissegundos, dos quais 7 milissegundos foram obtidos pelo destino e 4 milissegundos pelo próprio Edge Microgateway.

2. Exemplo de solicitação de saída feita ao destino:

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

• 1436403888651: carimbo de data 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 do 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 alterar intervalos de registro.
• treq: identifica o evento. Neste caso, a solicitação de destino.
• m: o verbo HTTP usado na solicitação de destino.
• u: a parte do URL após o caminho de base.
• h: o host e o número da porta do destino do back-end.
• i: o ID da entrada de registro. As quatro entradas de evento compartilharão esse ID.

3. Exemplo de resposta recebida do destino

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

1436403888651: carimbo de data 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 do 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 alterar intervalos de registro.
• tres: identifica o evento. Nesse caso, a resposta desejada.
• s: o status da resposta HTTP.
• d: a duração em milissegundos. O tempo gasto para a chamada de API pelo destino.
• i: o ID da entrada de registro. As quatro entradas de evento compartilharão esse ID.

4. Exemplo de resposta enviada ao cliente

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

1436403888651: carimbo de data 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 do 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 alterar 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 pelo próprio Edge Microgateway.
• i: o ID da entrada de registro. As quatro entradas de evento compartilharão esse ID.

Programação do arquivo de registros

Os arquivos de registros são girados 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 registros com esse UID. Consulte também Práticas recomendadas de manutenção de arquivos de registros.

Mensagens de erro

Algumas entradas de registro conterão 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 definir 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 instalar e configurar o Edge Microgateway para mais detalhes.
• jwt_public_key: (padrão: nenhum) 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 aos clientes. Esse URL é retornado quando você executa o comando para implantar o proxy: edgemicro configure. Consulte Como instalar e configurar o Edge Microgateway para mais detalhes.
• quotaUri: defina esta propriedade de configuração se você quiser gerenciar cotas por meio do proxy edgemicro-auth que foi implantado na sua organização. Se essa propriedade não for definida, o endpoint de cota será padronizado como o endpoint interno do Edge Microgateway.

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

Atributos do Edgemicro

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

• porta: (padrão: 8000) o número da porta em que o processo do Edge Microgateway detecta.
• 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 vai 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. O objetivo dessa configuração é frustrar ataques de negação de serviço. Normalmente, defina-o como um número maior que max_connections.
• geração de registros:
  • level: (padrão: erro)
    • 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, além de mensagens de informações, de aviso e de erro.
    • trace - registra informações de rastreamento para erros, além de informações, avisos e mensagens de erro.
    • 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, quando o registro de estatísticas é gravado no arquivo de registros da API.
  • rotate_interval: (padrão: 24) intervalo, em horas, quando os arquivos de registros são girados.

• Plug-ins: adicionam funcionalidades ao Edge Microgateway. Para 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.
• sequência: 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 a depuração remota ao processo do Edge Microgateway.
  • port: o número da porta a ser detectada. Por exemplo, configure o depurador de ambientes 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 atualização se algo for alterado. A pesquisa seleciona todas as mudanças feitas no Edge (mudanças em produtos, proxies com reconhecimento de microgateway etc.), bem como as feitas no arquivo de configuração local.
  
• disable_config_poll_interval: (padrão: false) defina como true para desativar a pesquisa de mudança automática.
• request_timeout: define um tempo limite para solicitações de destino. O tempo limite é definido em segundos. Se o tempo limite for atingido, o Edge Microgateway responderá com um código de status 504. (adicionada a v2.4.x).
• keep_alive_timeout: essa propriedade permite definir o tempo limite do Edge Microgateway (em milissegundos). (Padrão: 5 segundos) (adicionada v3.0.6)
• headers_timeout: esse atributo limita o tempo (em milissegundos) que o analisador de HTTP aguardará 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. Padrão: 5 segundos a mais do que o tempo definido com edgemicro.keep_alive_timeout. Essa configuração padrão impede que os balanceadores de carga ou proxies descartem a conexão de maneira incorreta. (Adicionada v3.1.1)

• noRuleMatchAction: (string) a ação a ser realizada (permitir ou negar acesso) se a regra de correspondência especificada no plug-in accesscontrol não for resolvida (não tem 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 de análise 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 de análise funcionará normalmente. Consulte os atributos da Edgemicro para ver mais detalhes. A v3.1.8 foi adicionada.

  Exemplo:

  edgemicro
    enableAnalytics=false|true

• on_target_response_abort: este 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 exibir um erro. Nos arquivos de registros, uma mensagem de aviso é exibida com targetResponse aborted e o código de resposta 502.
  appendErrorToClientResponseBody	O erro personalizado TargetResponseAborted é retornado ao cliente. Nos arquivos de registros, uma mensagem de aviso é exibida com targetResponse aborted e o 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 registros: TargetResponseAborted com o código de status da solicitação 502.

Exemplo:

edgemicro:
 on_target_response_abort: appendErrorToClientResponseBody | abortClientRequest

atributos "headers"

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

• x-forwarded-for: (padrão: true) defina como falso para evitar que x-forwarded-for cabeçalhos sejam passados para o destino. Observe que, 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: true) defina como "false" para evitar que os cabeçalhos x-forwarded-host sejam transmitidos para o destino.
• x-request-id: (padrão: true) defina como "false" para evitar que os cabeçalhos x-request-id sejam transmitidos para o destino.
• x-response-time: (padrão: true) defina como "false" para evitar que os cabeçalhos x-response-time sejam transmitidos para o destino.
• via: (padrão: true) defina como "false" para evitar que os cabeçalhos sejam transmitidos para o destino.

Atributos 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 terão permissão para passar pelo Edge Microgateway sem nenhum cabeçalho de autorização. Defina como falso para exigir um cabeçalho de autorização (padrão).
• allowInvalidAuthorization: (padrão: false) se definido como verdadeiro, as chamadas de API terão permissão para passar se o token passado no cabeçalho de autorização for inválido ou tiver expirado. Defina como falso para exigir tokens válidos (padrão).
• autorização-header: (padrão: Authorization: Bearer) o cabeçalho usado para enviar o token de acesso para o Edge Microgateway. Altere o padrão nos casos em que o destino precisa usar o cabeçalho de autorização para algum outro fim.
• 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 para o Edge Microgateway. Consulte também Como usar uma chave de API.
• keep-autorização-header: (padrão: false) se definido como verdadeiro, o cabeçalho de autorização enviado na solicitação é passado para o destino (ele é preservado).
• allowOAuthOnly: se definido como verdadeiro, todas as APIs precisarão ter um cabeçalho de autorização com um token de acesso do portador. Permite permitir apenas o modelo de segurança OAuth, mantendo a compatibilidade com versões anteriores. (Adicionado 2.4.x)
• allowAPIKeyOnly: se definida como verdadeira, cada API precisa ter um cabeçalho x-api-key (ou um local personalizado) com uma chave de API.Permite apenas o modelo de segurança da chave de API, mantendo a compatibilidade com versões anteriores. (Adicionado 2.4.x)
• gracePeriod: este parâmetro ajuda a evitar erros causados por pequenas discrepâncias entre o relógio do seu sistema e os horários "Não antes" (nbf) ou "Emitido em" (iat) especificados no token de autorização JWT. Defina esse parâmetro como o número de segundos para permitir essas discrepâncias. (Adicionado 2.5.7)

Atributos específicos do plug-in

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

Como filtrar proxies

É possível filtrar quais proxies com reconhecimento de microgateway uma instância do Edge Microgateway processará. Quando o Edge Microgateway é iniciado, ele faz o download de todos os proxies com reconhecimento de microgateway na organização a que está associado. Use a configuração a seguir para limitar quais proxies o microgateway processará. Por exemplo, essa configuração limita os proxies que o microgateway processará em 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 transfere e processa. Para filtrar os produtos transferidos por download, 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'

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

         ]
      }
   ]
}

Como filtrar produtos por atributos personalizados

Para filtrar produtos com base em atributos personalizados, faça o seguinte:

1. Na interface do Edge, selecione o proxy edgemicro_auth na organização/ambiente em que você configurou o Edge Microgateway.
2. No toque de desenvolvimento, abra a política Java callout no editor.
3. Adicione um atributo personalizado com a chave products.filter.attributes usando uma lista separada por vírgulas de nomes de atributos. Somente produtos que contenham qualquer um dos nomes de atributos personalizados serão retornados para o Edge Microgateway.
4. Opcionalmente, é possível desativar a verificação para ver 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 no Edge para nuvem privada, defina a propriedade org.noncps como true para extrair produtos para ambientes nã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>

Configurar a frequência de envio de análise

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

Como mascarar dados de análise

A configuração a seguir impede que as informações do caminho de solicitação apareçam na análise de borda. Adicione o seguinte à configuração do microgateway para mascarar o URI e/ou o caminho da solicitação. O URI consiste nas partes do nome do host e do 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 específico da API 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 confundi-la com chamadas de proxy de API reais. No painel do Analytics, os proxies segregados seguem este padrão de nomenclatura:

edgemicro_proxyname-health

A imagem a seguir mostra dois proxies separados no painel do Google Analytics: edgemicro_hello-health e edgemicro_mock-health:

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

• relativePath (opcional): especifica um caminho relativo a ser separado no painel do Analytics. Por exemplo, se você especificar /healthcheck, todas as chamadas de API que contiverem o caminho /healthcheck aparecerão no painel como edgemicro_proxyname-health. Essa sinalização ignora o caminho base do proxy. Para separar com base em um caminho completo, incluindo o de base, use a sinalização proxyPath.
• proxyPath (opcional): especifica um caminho completo de proxy de API, incluindo o caminho base do proxy, para separar 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 aparecerão no painel como edgemicro_proxyname-health.

Por exemplo, na configuração a seguir, qualquer caminho de API que contenha /healthcheck será separado 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 do 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

Configurar o Edge Microgateway por trás de um firewall da empresa

Usar um proxy HTTP para comunicação com o Apigee Edge

Adicionado na versão 3.1.2.

Para usar um proxy HTTP para a 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 podem processar a comunicação com o Apigee Edge. Por exemplo:

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

   Observe que NO_PROXY pode ser uma lista de domínios delimitados por vírgulas que não podem ser usados como proxy do Edge Microgateway.

   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 para 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 verdadeiro, o Edge Microgateway usa o método HTTP CONNECT para encapsular solicitações HTTP em uma única conexão TCP. O mesmo acontece se as variáveis de ambiente usadas na configuração do proxy estiverem ativadas para TLS, conforme mencionado abaixo. Padrão: false
   • url: o URL do proxy HTTP.
   • bypass: (opcional) especifica um ou mais URLs de host de destino separados por vírgula que devem ignorar o proxy HTTP. Se essa propriedade não for definida, use a variável de ambiente NO_PROXY para especificar quais URLs de destino devem ser ignorados.
   • enabled: se "true" 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 HTTP_PROXY e HTTPS_PROXY do proxy HTTP, 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 Microgateway

É possível usar um ou mais caracteres curinga "*" no caminho base de um proxy edgemicro_* (com reconhecimento de 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: a Apigee NÃO aceita o uso de um caractere curinga "*" como o primeiro elemento de um caminho base. Por exemplo, NÃO é possível usar esta pesquisa: /*/.

Como fazer a rotação de chaves JWT

Em algum momento depois de gerar um JWT inicial, pode ser necessário alterar o par de chaves pública/privada armazenado na KVM criptografada pelo 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 em RFC7519. O JWT oferece uma maneira de assinar um conjunto de declarações, que podem ser verificadas pelo destinatário do JWT de maneira confiável.

É 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, pode ser necessário alterar o par de chaves pública/privada armazenado na KVM criptografada pelo Edge. Esse processo de geração de um novo par de chaves é chamado de rotação de chaves. Quando você faz a rotação de chaves, 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 do ID da chave original.

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

As chaves 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 (criado mais recentemente). Esse ID 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 (criado mais recentemente). Essa chave está associada ao valor public_key1 e é usada para dar suporte à rotação de chaves. Esse valor é igual ao da chave privada filha.

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

Ao realizar a rotação de chaves, as chaves-valor atuais são substituídas no mapa e novas chaves são adicionadas para manter as antigas. Exemplo:

• public_key2_kid: o ID da chave pública antiga. Essa chave está associada ao valor public_key2 e é usada para dar 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 vai ser usada até o JWT expirar (após o intervalo token_expiry*, padrão de 30 minutos). Dessa forma, é 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 realizar uma rotação de chaves.

1. Para fazer upgrade da KVM, use o comando edgemicro upgradekvm. Para detalhes sobre como executar esse comando, consulte Como fazer upgrade da KVM. Você só precisa fazer essa etapa uma vez.
2. Para fazer upgrade do proxy edgemicro-oauth, use o comando edgemicro upgradeauth. Para detalhes sobre 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 o microgateway para usar:

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

4. Execute o comando de rotação para alternar as chaves. Para 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. Observe que, 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 microgateway verifica se há uma chave mais antiga no conjunto de chaves e tenta essa chave. O formato das chaves retornadas é JSON Web Key (JWK). Leia sobre esse formato na RFC 7517 (link 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"
    }
  ]
}

Como configurar um atraso "não antes"

Para as versões 3.1.5 e anteriores, a nova chave privada gerada pelo comando rotatekey entrou em vigor imediatamente, e os novos tokens gerados foram assinados com ela. No entanto, a nova chave pública só foi disponibilizada para instâncias do Edge Microgateway a cada 10 minutos (por padrão) quando a configuração do microgateway foi 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.

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

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

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

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

Recomendamos que o atraso seja maior do que a definição de configuração config_change_poll_internal, que é de 10 minutos por padrão. Consulte também atributos daedgemicro.

Filtragem de proxies baixados

Por padrão, o Edge Microgateway faz o download de todos os proxies na sua organização do Edge que começam com o prefixo de nomenclatura "edgemicro_". É possível alterar esse padrão para fazer o download de proxies com nomes que 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 contenha proxies de API. Essa configuração de produto 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 do 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 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, expressões de monitoramento e assim por diante.

É possível especificar sinalizações 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 ver os detalhes de execução e as informações de erro. Para mais detalhes, consulte Como gerenciar arquivos de registro.

Como usar a segurança da chave de API

As chaves de API fornecem 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 cliente (também chamada de ID do cliente) de um produto do Apigee Edge que inclui o proxy de autenticação do Edge Microgateway.

Armazenamento de chaves em cache

As chaves de API são trocadas por tokens do portador, que são armazenados em cache. Para desativar o armazenamento em cache, defina o cabeçalho Cache-Control: no-cache nas solicitações recebidas para o Edge Microgateway.

Como usar uma chave de API

Você pode 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 alterar esse padrão no arquivo de configuração, conforme explicado em Como fazer alterações na configuração. Por exemplo, altere 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 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 vai retornar 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 exatamente o código 4xx ou 5xx, dependendo do erro.

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

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

Como usar a segurança do token OAuth2

Esta seção explica como conseguir tokens de acesso e tokens de atualização 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 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 Como gerenciar tokens.

API 1: enviar credenciais como parâmetros do corpo

Substitua os nomes da organização e do ambiente no URL. Além disso, substitua os valores de ID e chave secreta do consumidor recebidos de um app do 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 do Auth básico

Envie as credenciais do cliente como um cabeçalho da autenticação básica e o grant_type como um parâmetro de formulário. Esse formulário de comando também é discutido na RFC 6749: o framework de autorização do OAuth 2.0 (link em inglês).

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

A API retorna uma resposta JSON. Não há diferença entre as propriedades token e access_token. Você pode usar qualquer um deles. Observe que expires_in é um valor inteiro especificado em segundos.

{
"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. Receber um token de acesso e atualização com a API /token. Observe que 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 é semelhante a esta. Observe que expires_in valoriza números inteiros e é especificado 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. Basta chamar o endpoint /refresh da mesma API. Por 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 é semelhante a esta:

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

Monitoramento permanente

Como especificar um endpoint de arquivo de configuração

Se você executa várias instâncias do Edge Microgateway, pode gerenciar as configurações de um único local. Para fazer isso, especifique um endpoint HTTP em que o Edge Micro pode fazer o download do arquivo de configuração. É possível especificar esse endpoint ao iniciar o Edge Micro usando a sinalização -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.

Desativando 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 serão desligados imediatamente cada vez que socket.write() for chamado). Consulte também a documentação do Node.js para mais detalhes.

Para ativar 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 completamente desconectado 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 seguintes recursos não funcionam porque exigem conexão com o Apigee Edge:

• OAuth e chave de API
• Cota
• Análise

Por outro lado, plug-ins personalizados e detenção de pico 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 autônomo.

Como configurar e iniciar o gateway

Para executar o Edge Microgateway no modo independente:

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

   Exemplo:

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

2. Cole o seguinte código 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 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 "org" usado no nome do arquivo de configuração.
   • $ENV é o nome "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_autorização". Este plug-in valida um JWT que precisa estar presente no cabeçalho "Autorização" da chamada de API. Na próxima seção, você vai receber um JWT que permite que as chamadas de API passem sem o erro.

Exemplo: como obter 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ê executa uma configuração padrão do Edge Microgateway. Para receber o JWT do endpoint da Apigee, primeiro é necessário fazer a configuração padrão do Edge Microgateway e estar conectado à Internet. O endpoint da Apigee é usado aqui apenas para fins de exemplo e não é obrigatório. Se quiser, é possível usar outro endpoint de token JWT. Se fizer isso, você precisará receber 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. Execute 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á tiver feito essa etapa anteriormente, não será necessário repeti-la.
2. Se você implantou o Edge Microgateway na 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 criado 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. Por exemplo:

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

5. Reinicie o Edge Microgateway como você fez anteriormente, usando os nomes de organização/ambiente usados no nome do arquivo de configuração. Por 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 no Edge Microgateway.
• your_env é um ambiente na organização.
• A opção i especifica a chave do cliente de um app de desenvolvedor que tem um produto que inclui o proxy edgemicro-auth.
• A opção s especifica o secret do cliente 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 possa ser usado para verificar chamadas de API.

Consulte também Gerar um token.

Testar a configuração independente

Para testar a configuração, chame a API com o token adicionado no cabeçalho "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 com reconhecimento de microgateway seja implantado no Apigee Edge. Em vez disso, configure um "proxy local" fornecendo um nome de proxy local, um caminho de base e um URL de destino ao iniciar o microgateway. As chamadas de API para o microgateway são enviadas para o 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 detenção de pico 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 onde o microgateway gerencia o tráfego de e para o serviço complementar. A figura a seguir ilustra essa arquitetura em que o Edge Microgateway funciona como um proxy de arquivo secundário em um cluster do Kubernetes. Cada instância de microgateway se comunica com apenas um endpoint no serviço complementar:

Um benefício desse estilo de arquitetura é que o Edge Microgateway fornece 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 definir seu 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 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 a chave e o 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 e com os seguintes requisitos de configuração obrigatórios. É possível 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 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 atual, se quiser. Para receber ajuda, consulte Como adicionar desenvolvedores usando a IU de gerenciamento de borda.

5. No Apigee Edge, crie um app de desenvolvedor. É necessário adicionar ao app o produto de API que você acabou de criar. Se precisar de ajuda, consulte Como registrar um app na interface 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 para o destino do proxy (o serviço que o proxy 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

Chame o endpoint do proxy para testar a configuração do proxy local. 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"
}

Esta chamada de API inicial produziu um erro porque você não forneceu uma chave de API válida. É possível encontrar a chave no app do desenvolvedor criado anteriormente. Abra o app na interface do Edge, copie a chave do cliente 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

Nesta seção, explicamos como usar o sincronizador, um recurso opcional que melhora a resiliência do Edge Microgteway, permitindo que ele recupere dados de configuração do Apigee Edge e os grave em um banco de dados local do Redis. Com uma instância do 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 sincronia é 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 garante que todas as instâncias do Edge Microgateway usem 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 o proxy de API e as configurações de produtos. 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 serã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 que estejam fora de sincronia com outras instâncias.

O sincronizador do Edge Microgateway fornece um mecanismo alternativo para que as instâncias do Edge Microgateway recuperem dados de configuração necessários para iniciar e processar o tráfego do proxy de API. Os dados de configuração recuperados das chamadas para o Apigee Edge incluem as chamadas jwk_public_keys, jwt_public_key, de inicialização e de produtos de API. O sincronizador possibilita 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 especialmente configurada do Edge Microgateway. A única finalidade dele é pesquisar o Apigee Edge (o tempo é configurável), recuperar dados de configuração e gravá-los em um banco de dados local do Redis. A 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 do Redis, em vez do Apigee Edge. Como todas as instâncias de microgateway extraem os dados de configuração do banco de dados local, elas podem iniciar e processar solicitações de API mesmo no caso de uma interrupção da Internet.

Como configurar uma instância do sincronizador

Adicione a seguinte configuração ao arquivo org-env/config.yaml para a instalação do Edge Microgateway que você quer usar como o 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

Opção	Descrição
redisHost	O host em que a instância do Redis está sendo executada. Padrão: 127.0.0.1
redisPort	A porta da instância do Redis. Padrão: 6379
redisDb	O banco de dados Redis a ser usado. Padrão: 0
redisPassword	A senha do banco de dados.

Por fim, salve o arquivo de configuração e inicie a instância do Edge Microgateway. Ele começará a sondar o Apigee Edge e a armazenar os dados de configuração salvos no banco de dados do 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 receber os dados de configuração do banco de dados do Redis, e não do Apigee Edge.

Adicione a configuração a seguir a cada arquivo org-env/config.yaml extra do nó Edge Microgateway. Observe que a propriedade synchronizerMode é definida como 0. Essa propriedade configura a instância para operar como uma instância normal do Edge Microgateway que processa o tráfego do proxy de API, e a instância receberá os dados de configuração do banco de dados do 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 permitir o uso do sincronizador:

Atributo	Valores	Descrição
edge_config.synchronizerMode	0 ou 1	Se 0 (o padrão), o Edge Microgateway operará no modo padrão. Se 1, inicie a instância do Edge Microgateway para operar como um sincronizador. Nesse modo, a instância extrai dados de configuração do Apigee Edge e os armazena em um banco de dados local do Redis. Esta instância não pode processar solicitações de proxy de API. O único objetivo dela é pesquisar dados de configuração no Apigee Edge e gravá-los no banco de dados local. Em seguida, configure outras instâncias de microgateway para ler o banco de dados.
edge_config.redisBasedConfigCache	"true" ou "false"	Se verdadeiro, a instância do Edge Microgateway busca os dados de configuração no banco de dados do Redis em vez do Apigee Edge. O banco de dados do Redis precisa ser o mesmo em que o sincronizador está configurado para fazer gravações. Se o banco de dados do Redis estiver indisponível ou vazio, o microgateway vai procurar um arquivo cache-config.yaml atual para a configuração. Se for "false" (o padrão), a instância do Edge Microgateway buscará os dados de configuração do Apigee Edge normalmente.
edgemicro.config_change_poll_interval	Intervalo de tempo, em segundos	Especifica o intervalo de pesquisa para o sincronizador extrair dados do Apigee Edge.

Como configurar URLs de exclusão para plug-ins

É possível configurar o microgateway para pular o processamento de plug-ins de URLs especificados. É possível 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 vão processar as 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.

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

Especifique variáveis de ambiente usando tags no arquivo de configuração. As tags das 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. Elas não são armazenadas na configuração original nem nos arquivos em cache.

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

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

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