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.
- 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
- 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
- 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 initedgemicro 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 stopedgemicro 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):
- 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:
- 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:
- Gere ou consiga um certificado SSL e uma chave usando o utilitário openssl ou o método que preferir.
- 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
- 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 comostats
. Os registros de estatísticas são informados em um intervalo regular definido com a configuraçãostats_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 comostats
. Os registros de estatísticas são informados em um intervalo regular definido com a configuraçãostats_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 comostats
. Os registros de estatísticas são informados em um intervalo regular definido com a configuraçãostats_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 comostats
. Os registros de estatísticas são informados em um intervalo regular definido com a configuraçãostats_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.
-
level: (padrão: erro)
- 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 comedgemicro.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
ouDENY
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 comtargetResponse 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 comtargetResponse aborted
e o código de resposta 502. Além disso, o erroTargetResponseAborted
é registrado com a mensagemTarget 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:
- Na interface do Edge, selecione o proxy edgemicro_auth na organização/ambiente em que você configurou o Edge Microgateway.
- No toque de desenvolvimento, abra a política Java callout no editor.
- 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. - 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
comofalse
. O padrão é "true". - (Somente nuvem privada) Se você estiver no Edge para nuvem privada, defina a propriedade
org.noncps
comotrue
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 comoedgemicro_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çãoproxyPath
. - 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 comoedgemicro_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:
- Defina as variáveis de ambiente
HTTP_PROXY
,HTTPS_PROXY
eNO_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
- 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:
- 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 valorproxy.url
para o proxy HTTP. Se for verdadeiro eproxy.url
não estiver definido, use os proxies especificados nas variáveis de ambienteHTTP_PROXY
eHTTPS_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
- 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:
- 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.
- 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. - 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. - 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'
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.
- Abra o arquivo de configuração do Edge Micro:
~/.edgemicro/org-env-config.yaml
- 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.
- Reinicie o Edge Microgateway no modo de depuração. Para fazer isso, adicione
DEBUG=*
ao início do comandostart
: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
- Inicie o depurador e configure-o para detectar o número da porta do processo de depuração.
- 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 propriedadestoken
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.
- 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" }
- 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:
- Crie um arquivo de configuração com o nome a seguir:
$HOME/.edgemicro/$ORG
-
$ENV-config.yamlExemplo:
vi $HOME/.edgemicro/foo-bar-config.yaml
- 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
- Exporte a seguinte variável de ambiente com o valor "1":
export EDGEMICRO_LOCAL=1
- 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 /
- Testar a configuração.
curl http://localhost:8000/echo { "error" : "missing_authorization" }
Como o plug-in
extauth
está no arquivofoo-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
:
- 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. - Se você implantou o Edge Microgateway na Apigee Cloud, precisa estar conectado à Internet para receber um JWT desse endpoint.
-
Parar o Edge Microgateway:
edgemicro stop
- No arquivo de configuração criado anteriormente (
$HOME/.edgemicro
/org-env-config.yaml
), aponte o atributoextauth:publickey_url
para o endpointedgemicro-auth/jwkPublicKeys
na organização/ambiente do Apigee Edge. Por exemplo:extauth: publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'
-
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 /
-
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 proxyedgemicro-auth
. - A opção
s
especifica o secret do cliente de um app de desenvolvedor que tem um produto que inclui o proxyedgemicro-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:
- 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. - 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.
- 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.
- Você precisa adicionar o proxy edgemicro-auth ao produto. Esse proxy
foi implantado automaticamente quando você executou
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.
- 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.
- 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
- 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>