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, você aprende a 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, é preciso 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 alterações 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 é preciso saber sobre 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 prefixos npm. Consulte Onde o Edge Microgateway está instalado se não for possível 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 os nomes da organização e do ambiente do Apigee Edge. É possível usar esse arquivo para fazer alterações na configuração e recarregá-los sem inatividade. 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 configure.
    • $SECRET é a chave retornada anteriormente pelo comando configure.

    Por exemplo:

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

Se o Edge Microgateway for interrompido:

  1. Reinicie o Edge Microgateway:
    edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET

    Em que:

    • $ORG é o nome da sua organização 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 configure.
    • $SECRET é a chave retornada anteriormente pelo comando configure.

    Exemplo:

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

Confira um exemplo de arquivo de configuração. Veja mais detalhes 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 o ambiente e a organização do Edge, além da chave e do secret necessários para iniciar o Edge Microgateway, podem ser armazenados nessas 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 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 aos vídeos a seguir para saber como configurar o TLS no Apigee Edge Microgateway:

Vídeo Descrição
Configurar o TLS unidirecional no sentido norte Saiba como configurar o TLS no Apigee Edge Microgateway. Este vídeo fornece uma visão geral do TLS e a importância dele, apresenta o TLS no Edge Microgateway e demonstra como configurar o TLS de sentido norte.
Configurar o TLS bidirecional no 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 do 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 direções para o sul.

É possível configurar o servidor do Microgateway para usar o 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 de sua preferência.
  2. Adicione o atributo edgemicro:ssl ao arquivo de configuração do Edge Microgateway. Para uma lista completa de opções, consulte a tabela abaixo. Por exemplo:
    edgemicro:
      ssl:
       key: <absolute path to the SSL key file>
       cert: <absolute path to the SSL cert file>
       passphrase: admin123 #option added in v2.2.2
       rejectUnauthorized: true #option added in v2.2.2
       requestCert: true
  3. Reinicie o Edge Microgateway. Siga as etapas descritas em Como fazer alterações na configuração, dependendo do arquivo de configuração editado: o arquivo padrão ou o de ambiente 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

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 String que descreve as criptografias a serem usadas, separadas por um ":".
rejectUnauthorized Se verdadeiro, o certificado do servidor será verificado de acordo com a lista de CAs fornecidas. Se a verificação falhar, um erro será retornado.
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 SNI (Indicação de nome do servidor) TLS.
requestCert verdadeiro para SSL bidirecional; falso para SSL unidirecional

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

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

Este exemplo mostra 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 somente 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

Veja um exemplo de TLS:

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

No caso em que você quer aplicar configurações de TLS/SSL a vários destinos específicos, é necessário definir o primeiro host na configuração como "vazio", o que ativa as solicitações universais, e depois 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

Esta é uma lista com 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 String que descreve as criptografias a serem usadas, separadas por um ":".
rejectUnauthorized Se verdadeiro, o certificado do servidor será verificado de acordo com a lista de CAs fornecidas. Se a verificação falhar, um erro será retornado.
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 SNI (Indicação de nome do servidor) TLS.

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 a um JSON Web Token (JWT), configurar a expiração do token e gerar tokens de atualização. Para saber mais, 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 registros

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 de 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 diferente para o arquivo de registros.

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 em vez de para um arquivo de registros. Defina a flag to_console como verdadeira da seguinte maneira:

edgemicro:
  logging:
    to_console: true

Com esta 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 registros.

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

Você especifica o nível de registro a ser usado na configuração do edgemicro. Para conferir uma lista completa dos níveis de registro e as descrições deles, consulte Atributosedgemicro.

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 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 os seguintes:

  • 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, em que os arquivos de registros 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 diminuir as permissões rígidas de arquivos de registros

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 ou usuários externos leiam o arquivo de registro. 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 de arquivo 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

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

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

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 salvos e o JSON Web Token (JWT). 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 registro "api" contém informações detalhadas sobre o fluxo de solicitações e respostas pelo Edge Microgateway. Os arquivos de registro "api" são nomeados da seguinte forma:

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

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

  • Solicitação recebida do cliente
  • Solicitação enviada ao 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 registros mais compactos. Veja quatro entradas de exemplo que representam cada um dos quatro eventos. No arquivo de registro, eles têm essa 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 analisá-los um por 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 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 os intervalos de registro.
  • req: identifica o evento. Nesse caso, 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 número do host e da porta em que o Edge Microgateway está detectando.
  • r: o host remoto e a porta em que a solicitação do cliente foi originada.
  • i: o ID da solicitação. As quatro entradas de evento vão compartilhar esse ID. Cada solicitação recebe um ID exclusivo. A correlação de registros por ID da solicitação pode fornecer insights valiosos sobre a latência do destino.
  • d: 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, sendo sete milissegundos obtidos pelo destino e quatro 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 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 os intervalos de registro.
  • treq: identifica o evento. Nesse caso, direcione a solicitação.
  • m: o verbo HTTP usado na solicitação de destino.
  • u: a parte do URL após o caminho de base.
  • h: número do host e da porta do destino de back-end.
  • i: o ID da entrada de registro. 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 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 alterar os intervalos de registro.
  • tres: identifica o evento. Nesse caso, segmentação de resposta.
  • s: o status da resposta HTTP.
  • d: a duração em milissegundos. O tempo que o destino levou para a chamada de API.
  • i: o ID da entrada de registro. As quatro entradas de evento vão compartilhar esse ID.

4. Exemplo de resposta de saída para o 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 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 os intervalos de registro.
  • res: identifica o evento. Nesse caso, resposta ao cliente.
  • s: o status da resposta HTTP.
  • d: a duração em milissegundos. É o tempo total que a chamada de API leva, incluindo o tempo gasto pela API de destino e o próprio Edge Microgateway.
  • i: o ID da entrada de registro. As quatro entradas de evento vão compartilhar esse ID.

Programação do arquivo de registros

Os arquivos de registros são rotacionados no intervalo especificado pelo atributo de configuração rotate_interval. As entradas continuarão 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 ocorrem os erros, consulte a Referência de erros do Edge Microgateway.

Referência de configuração do Edge Microgateway

Local do arquivo de configuração

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

Atributos Edge_config

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

  • bootstrap: (padrão: nenhum) um URL que aponta para um serviço específico do Edge Microgateway em execução na 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 os detalhes em Como instalar e configurar o Edge Microgateway.
  • 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 os detalhes em Como instalar e configurar o Edge Microgateway.
  • quotaUri: defina essa propriedade de configuração se você quiser gerenciar cotas pelo proxy edgemicro-auth que é 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 Edgemicro

Essas 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 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 é impedir ataques de negação de serviço. Normalmente, defina-o como um número maior que max_connections.
  • logging:
    • level (padrão: erro):
      • 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, além de mensagens de informação, aviso e erro.
      • trace: registra informações de rastreamento de 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 onde os arquivos de registros 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, em que os arquivos de registros são alternados.
  • 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 que serão 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, defina seu depurador 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 atualização se algo for alterado. A pesquisa coleta todas as alterações feitas no Edge (alterações em produtos, proxies com reconhecimento de microgateway etc.), bem como alterações feitas no arquivo de configuração local.
  • disable_config_poll_interval: (padrão: false) defina como true para desativar a pesquisa de alteração automática.
  • request_timeout: define um tempo limite para solicitações de destino. O tempo limite é definido em segundos. Se um tempo limite for atingido, 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) (adição da v3.0.6)
  • headers_timeout: este atributo limita o tempo (em milissegundos) que o analisador 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 balanceadores de carga ou proxies descartem a conexão por engano. (Adicionado v3.1.1)

  • noRuleMatchAction: (String) a ação a ser executada (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, não serão feitas chamadas para a análise do Apigee Edge. Se definido como true ou quando esse atributo não for fornecido, o plug-in de análise funcionará normalmente. Consulte os atributos edgemicro para mais detalhes. (Adicionado v3.1.8).

    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 de cabeçalhos

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

  • x-forwarded-for: (padrão: verdadeiro) defina como falso para evitar que x-forwarded-for cabeçalhos sejam transmitidos para o destino. Se houver um cabeçalho "x-forward-for" na solicitação, o valor dele será definido como o valor de client-ip no Edge Analytics.
  • x-forwarded-host: (padrão: verdadeiro) defina como falso para evitar que cabeçalhos x-forwarded-host sejam transmitidos para o destino.
  • x-request-id: (padrão: verdadeiro) 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: verdadeiro) 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 "false" para exigir um cabeçalho de autorização (padrão).
  • allowInvalidAuthorization: (padrão: falso) se definido como verdadeiro, as chamadas de API terão permissão para passar 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).
  • autorização-header (padrão: autorização: portador): o cabeçalho usado para enviar o token de acesso para o Edge Microgateway. É possível alterar o padrão nos casos em que o destino precisa usar o cabeçalho "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 para o Edge Microgateway. Consulte também Como usar uma chave de API.
  • keep-authorized-header: (padrão: falso) se definido como verdadeiro, o cabeçalho de autorização enviado na solicitação é transmitido para o destino (ele é preservado).
  • allowOAuthOnly: se definido como verdadeiro, cada API precisa ter um cabeçalho de autorização com um token de acesso do portador. Permite 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: esse parâmetro ajuda a evitar erros causados por pequenas discrepâncias entre o relógio do sistema e os horários "Não antes" (nbf) ou "Emitido em" (iat) especificados no token de autorização do JWT. Defina esse parâmetro como o número de segundos para permitir essas discrepâncias. (Adicionado 2.5.7)

Atributos específicos do plug-in

Consulte Como usar plug-ins para ver 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 vai 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, esta configuração limita a três proxies que o microgateway processará: 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 transferidos por download e processados pelo Edge Microgateway. 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 no formato de expressão regular e ser codificado para 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 abaixo 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 IU 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 tiverem 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.
  6. 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 push da 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: 10000
  • batchSize (opcional): o tamanho máximo de um lote de registros de análise enviados à Apigee. Padrão: 500
  • flushInterval (opcional): o número de milissegundos entre cada limpeza de um lote de registros de análise enviados à 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 sejam exibidas na análise do Edge. Adicione o seguinte à configuração do microgateway para mascarar o URI e/ou o caminho da solicitação. O URI consiste no nome do host e nas partes do caminho da solicitação.

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

Segregar 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 confundir 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 Analytics: edgemicro_hello-health e edgemicro_mock-health:

Use-os para separar caminhos relativos e absolutos no painel do Analytics como proxies separados:

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

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

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

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

Adicionado na versão 3.1.2.

Para usar um proxy HTTP para 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. 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 para os quais o Edge Microgateway não pode representar.

    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, como mencionado abaixo, usadas na configuração do proxy estiverem ativadas para o TLS. 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 precisam ignorar o proxy HTTP. Se essa propriedade não estiver definida, use a variável de ambiente NO_PROXY para especificar quais URLs de destino devem ser ignorados.
    • enabled: se "true" e proxy.url estiver definido, use o valor proxy.url para o proxy HTTP. Se 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 a 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 com reconhecimento de Microgateway

É possível usar um ou mais caracteres curinga "*" no caminho base de um proxy edgemicro_* (com reconhecimento de Microgateway). Por exemplo, com um caminho base de /team/*/members, os clientes podem chamar https://[host]/team/blue/members e https://[host]/team/green/members sem precisar 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, este comando NÃO é compatível: 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. Com o JWT, é possível assinar um conjunto de declarações, que podem ser verificadas pelo destinatário do JWT de forma 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ê alterna chaves, um novo par de chaves privada/pública é gerado e armazenado na KVM "microgateway" no seu ambiente/organização do Apigee Edge. Além disso, a chave pública antiga é mantida com o valor de 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 (configurado) 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 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 de public_key1 e é usada para oferecer suporte à rotação de chaves. Esse valor é igual ao da chave privada filha.

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

Quando você faz 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 código antigo da chave pública. 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 vão ser verificados usando a nova chave pública. Se a verificação falhar, a chave pública antiga 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 concluir esta 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 concluir esta etapa uma vez.
  3. Adicione a seguinte linha ao arquivo ~/.edgemicro/org-env-config.yaml, em que é preciso especificar a mesma organização e ambiente que você configurou para uso do microgateway:
    jwk_public_keys: 'https://$ORG-$ENV.apigee.net/edgemicro-auth/jwkPublicKeys'
  4. Execute o comando de rotação de chaves para fazer a rotação. Para 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 vai verificar se há uma chave mais antiga no conjunto e testará essa chave. O formato das chaves retornadas é JSON Web Key (JWK). Leia mais sobre esse formato no 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ó era 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 seriam 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 de ambiente de execução intermitentes com o status 403, porque a validação do token passaria em uma instância, mas falharia em outra até que todas as instâncias fossem atualizadas.

A partir da versão 3.1.6, uma nova sinalização no comando rotatekey permite que você especifique um atraso para que a nova chave privada entre em vigor, permitindo tempo para que todas as instâncias de microgateway sejam atualizadas e recebam a nova chave pública. A nova flag é --nbf, que significa "não antes". Essa sinalização 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 definir o atraso como maior que a definição da configuração config_change_poll_internal, que é de 10 minutos por padrão. Veja também Atributos edgemicro.

Como filtrar proxies transferidos por download

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 seu 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 vai fazer o download de proxies como Edgemicro_foo, Edgemicro_fast e Edgemicro_first.
    edge_config:
    …
    proxyPattern: edgemicro_f*

Como especificar produtos sem proxies de API

Na Apigee Edge, é possível criar um produto de API sem 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 observação e assim por diante.

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

Verificando arquivos de registro

Se estiver com problemas, examine os arquivos de registro para saber os detalhes da execução e as informações sobre erros. Para mais detalhes, consulte Como gerenciar arquivos de registros.

Como usar a segurança da chave de API

As chaves de API oferecem um mecanismo simples para autenticar clientes que fazem solicitações para o Edge Microgateway. Consiga uma chave de API copiando o valor da chave do consumidor (também chamado de ID do cliente) de um produto 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 de entrada 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"

Como configurar o nome da chave de API

Por padrão, x-api-key é o nome usado para o cabeçalho da chave de API e o parâmetro de consulta. Você pode alterar esse padrão no arquivo de configuração, conforme explicado em Como fazer alterações na configuração. Por exemplo, para alterar o nome para apiKey:

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

Nesse 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 dois 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 retornará somente códigos de status de erro 4xx se a resposta não for um status 200. Você pode alterar 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 à sua configuração do Edge Microgateway. Exemplo:

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

Como usar a segurança de tokens 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 por meio do microgateway. Os tokens de atualização são usados para conseguir 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 do ID e do secret do consumidor recebidos de um app de desenvolvedor no Apigee Edge pelos parâmetros de corpo client_id e client_secret:

curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \
-d '{"grant_type": "client_credentials", "client_id": "your_client_id", \
"client_secret": "your_client_secret"}' -H "Content-Type: application/json"

API 2: enviar credenciais em um cabeçalho do Basic Auth

Envie as credenciais de 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: framework de autorização OAuth 2.0 (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. É NECESSÁRIO 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. 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 chamando 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 contínuo

Para sempre é uma ferramenta do Node.js que reinicia automaticamente um app do Node.js caso o processo falhe 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 precisa ser reiniciado. Esse arquivo configura um serviço do Forever chamado forever-monitor (em inglês), que gerencia o Forever de maneira programática.

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

O comando edgemicro forever inclui sinalizações que permitem especificar o local do arquivo forever.json (a sinalização -f) e iniciar/interromper o processo de monitoramento "Forever" (a sinalização -a). Exemplo:

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

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

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.

Como desativar o armazenamento em buffer de dados da 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 em buffer os dados antes de enviá-los. Definir nodelay como true desativa esse comportamento (os dados serão imediatamente acionados sempre 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 forma:

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

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 seguinte nome: $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 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 "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 para o 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 "Autorização" da chamada de API. Na próxima seção, você vai receber um JWT que permite que chamadas de API passem sem erros.

Exemplo: como conseguir um token de autorização

O exemplo a seguir mostra como receber um JWT do endpoint JWT do Edge Microgateway na 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 você precisa fazer a configuração padrão do Edge Microgateway e se conectar à Internet. O endpoint da Apigee é usado aqui apenas para fins de exemplo e não é obrigatório. É possível usar outro endpoint de token JWT se quiser. Se fizer isso, você precisará conseguir 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. Caso já tenha feito essa etapa anteriormente, não é 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 que foram 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 para a qual 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 o secret do cliente de um app de desenvolvedor que tem um produto que inclua 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 autônoma

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

Edgemicro como arquivo secundário

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

Se quiser configurar o Edge Microgateway para ser executado no modo de proxy local, siga estas etapas:

  1. Execute edgemicro init para definir o ambiente de configuração local, exatamente como você faria em uma configuração típica do Edge Microgateway. Consulte também Configurar o Edge Microgateway.
  2. Execute edgemicro configure, como você 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, acesse 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. Este 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 desenvolvedor atual, se quiser. Para receber ajuda, consulte Como adicionar desenvolvedores usando a IU 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. 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

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

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

Esta chamada de API inicial gerou um erro porque você não forneceu uma chave de API válida. Encontre a chave no app do desenvolvedor criado anteriormente. Abra o app na IU 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 delas diretamente desse banco de dados.

No momento, o recurso de sincronização é 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 desse serviço 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 de API. Se a conexão de Internet com o Edge for interrompida, as instâncias de microgateway poderão continuar funcionando porque os dados de configuração mais recentes serão armazenados em cache. No entanto, novas instâncias de microgateway não podem ser iniciadas sem uma conexão limpa. Além disso, é possível que uma interrupção da Internet resulte em uma ou mais instâncias de microgateway em execução com informações de configuração fora de sincronia com outras instâncias.

O sincronizador do Edge Microgateway fornece um mecanismo alternativo para instâncias desse serviço para recuperar os 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 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 do Redis em vez do Apigee Edge. Como todas as instâncias de microgateways 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 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
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 pesquisar o Apigee Edge e armazenar os dados de configuração transferidos por download 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.

Inclua a configuração a seguir em cada arquivo org-env/config.yaml extra do nó Edge Microgateway. Observe que a propriedade synchronizerMode está 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 recebe 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 oferecer compatibilidade com o uso do sincronizador:

Atributo Valores Descrição
edge_config.synchronizerMode 0 ou 1

Se 0 (o padrão), o Edge Microgateway opera no modo padrão.

Se for 1, inicia a instância do Edge Microgateway para operar como um sincronizador. Nesse modo, a instância vai extrair dados de configuração do Apigee Edge e armazená-los em um banco de dados local do Redis. Esta instância não pode processar solicitações de proxy de API. O único propósito 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 buscará os dados de configuração do banco de dados do Redis em vez do Apigee Edge. O banco de dados Redis precisa ser o mesmo em que o sincronizador está configurado para fazer gravações. Se o banco de dados Redis não estiver disponível ou se ele estiver vazio, o microgateway vai procurar um arquivo cache-config.yaml atual para a configuração.

Se for falso (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 ignorar o processamento de plug-ins de URLs especificados. É possível configurar esses URLs "excluir" 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 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

Use tags no arquivo de configuração para especificar variáveis de ambiente. As tags da variável de ambiente especificada são substituídas pelos valores reais das variáveis de ambiente. As substituições são armazenadas somente na memória e 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>

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>