Pular para o conteúdo principal

Entradas internas do Gateway

Uma entrada interna é uma entrada do Gateway da organização que só existe dentro de uma rede. Ela tem um nome na rede — api.zero.internal — e leva cada caminho a um serviço: /v1 para um, /v2 para outro. São as mesmas rotas por caminho do Gateway público, sem endereço na internet.

Use uma entrada interna quando vários serviços precisam aparecer como uma API só para os outros projetos da rede, ou quando quem chama não deve depender de qual serviço atende cada caminho.

Antes de começar​

  • A entrada é criada por quem administra a organização, em Conectividade, e a organização precisa ter um Gateway.
  • Cada Gateway tem uma entrada interna por rede, e há um limite de entradas por organização.
  • Os serviços de destino precisam estar em ambientes da mesma rede.

Passo a passo​

1. Criar a entrada​

Em Conectividade, Entradas internas, clique em Nova entrada interna: escolha a rede e o Nome na rede. A entrada nasce sem caminhos e sem ninguém que possa chamá-la — até lá, ela responde "não encontrado" a tudo.

2. Ligar caminhos a serviços​

Em Rotas, crie uma rota escolhendo a entrada interna como endereço. Como nas rotas públicas:

  • o caminho é prefixo (/v1 vale para tudo abaixo dele) ou exato;
  • Remover o prefixo da rota faz o serviço receber /pedidos quando a chamada foi para /v1/pedidos; sem isso, ele recebe o caminho inteiro.

O caminho segue as mesmas regras da rota pública: começa com /, tem até 256 caracteres, não tem .., // nem *, e um prefixo diferente de / não termina em barra.

3. Dizer quem pode chamar​

Em Quem pode chamar esta entrada, use Autorizar projeto e escolha o Projeto que passa a chamar. Ele precisa ter um ambiente na mesma rede. A permissão vale para a entrada inteira — todos os caminhos dela — e passa pelos mesmos estados de uma permissão de serviço.

Quem pode chamar a entrada não ganha por isso acesso direto aos serviços atrás dela: chega só pelos caminhos que as rotas abrem. E uma permissão direta num serviço não passa pela entrada. São portas diferentes, e cada uma se revoga pela própria.

Pela CLI​

zero entries create api --network pagamentos
zero entries add-route api --service <serviço-de-pedidos> --path /v1 --strip-prefix
zero entries add-route api --service <serviço-de-cobrança> --path /v2
zero entries grant api --from <projeto-checkout> --wait

E quem foi autorizado chama:

curl http://api.zero.internal/v1/pedidos

O que a entrada faz com cada chamada​

SituaçãoResposta
Caminho sem rota404
Caminho que tenta sair da rota, como /v1/../admin404 — nada escapa da rota
Cabeçalhos acima de 60 KiB431
O serviço não começa a responder em 15 segundos504
Mais de 1024 chamadas simultâneas para o mesmo serviço503
Pedido de troca para HTTP/2 em texto aberto (h2c)403

WebSocket e respostas em fluxo funcionam, sem prazo total: os 15 segundos valem até o serviço começar a responder. Uma conexão longa sem tráfego por 5 minutos é encerrada.

O serviço recebe X-Forwarded-For com o endereço de quem chamou, e X-Forwarded-Host e X-Forwarded-Proto. Cabeçalhos de encaminhamento e de identidade enviados por quem chama — Forwarded, X-Real-IP, os X-Forwarded-* — são descartados antes de chegar ao serviço: ele não recebe uma origem forjada.

Revogar, remover um caminho, excluir a entrada​

  • Revogar uma permissão da entrada bloqueia as chamadas novas e fecha as conexões longas de todos que chamam a entrada, não só as do projeto revogado. Quem continua autorizado reconecta.
  • Remover um caminho faz quem o chama receber 404, e as conexões abertas por ele são encerradas quando a plataforma aplicar.
  • Excluir a entrada remove os caminhos, revoga as permissões e libera o nome na rede.

Limites​

  • Só HTTP, sem TLS, e só dentro da rede.
  • Sem política de rota: chave de API, JWT, limite de tráfego e CORS são do Gateway público. Quem tem permissão na entrada chama qualquer caminho que as rotas abrem.
  • Conexões longas podem ser encerradas quando a plataforma é atualizada. Quem chama deve saber reconectar.

Erros comuns​

SintomaCausaO que fazer
"Este gateway já tem uma entrada interna nesta rede"Cada Gateway tem uma entrada por redeAcrescente caminhos à entrada que já existe
"A organização chegou ao limite de entradas internas"O limite da organização foi atingidoRemova uma entrada que não é mais usada
"Esse nome já está em uso"Um serviço ou outra entrada da rede usa o nomeEscolha outro nome
"Este projeto já pode chamar a entrada interna"A permissão já existeNão é preciso criar outra
"Não é possível criar entradas internas agora"A capacidade não está disponível nesta instalaçãoA ação é de quem administra a plataforma
404 em todos os caminhosA entrada ainda não tem rotaCrie uma rota em Rotas, escolhendo a entrada como endereço
A conexão não completaO projeto que chama não tem permissão na entradaPeça para autorizarem o projeto em Quem pode chamar esta entrada

Próximos passos​