Backends

O backend é para onde a sua API encaminha a requisição. O produto aceita endereços públicos e um conjunto pequeno de destinos internos explicitamente autorizados pela operação.

Campos

Campo	Padrão	Regra
name	—	1 a 80 caracteres; único dentro da API
url	—	http:// ou https://, com host, porta opcional e caminho base; de onde saem scheme, host, port e base_path
tls_verify	true	só faz sentido com https; false exige liberação da operação
ca_bundle_pem	vazio	CA própria do seu serviço (PEM); exige https
timeouts.connect_ms	5000	1 a 600000 ms
timeouts.send_ms	60000	1 a 600000 ms
timeouts.read_ms	60000	1 a 600000 ms
retries	0	0 a 3
targets[]	o próprio host da URL	até 16 itens {host, port, weight} — balanceamento entre destinos
kind	EXTERNAL	EXTERNAL ou INTERNAL_ALLOWED (este só quando o par host:porta está na lista da operação)
health_check	ausente	verificação de saúde ativa e passiva

Política de destino

O produto recusa:

• IP literal em qualquer forma — IPv6, IPv4 pontuado, formas curtas e inteiras (127.1, 2130706433), octal com zero à esquerda (0177.0.0.1) e hexadecimal (0x7f.0.0.1). Toda forma que um resolvedor aceita é recusada.
• Nome que resolva (todos os registros) para: loopback, link-local, metadata de nuvem (169.254.169.254), faixas privadas (RFC 1918), CGNAT (100.64.0.0/10), 0.0.0.0/8, multicast, ULA e IPv4 embutido em IPv6.
• Faixas internas da plataforma, além do que a operação acrescentar.
• Nome de um rótulo só (que só resolve pelos domínios de busca internos) e sufixos de topologia interna como .svc, .cluster.local, .internal, .local e localhost.
• Misturar destino interno e externo na mesma definição (URL de um lado, targets de outro): 400 backend_not_allowed com reason = mixed_destinations.

O motivo é direto: o gateway é um ponto onde qualquer cliente pode cadastrar um destino. Sem essa barreira, ele seria um caminho para alcançar o banco de outro cliente, o serviço de metadata da nuvem e a rede interna. A validação acontece na criação, na alteração e de novo na publicação (a resolução pode ter mudado).

Existe ainda uma barreira de rede independente: o tráfego de saída do gateway para a Internet só sai nas portas 80 e 443, e nunca para faixas privadas. Um nome que "mude de IP" depois da validação morre ali.

Limitação declarada: a validação não substitui a rede. Se você precisa de backend em rede privada, isso não é possível hoje.

Vários destinos

Com targets, o gateway distribui as requisições entre os destinos (round-robin ponderado por weight, de 0 a 1000):

• cada destino passa pela mesma política de destino;
• targets ausente numa alteração mantém os destinos atuais — exceto quando os destinos são apenas o alvo implícito da url e a url muda: aí o alvo implícito acompanha a URL nova;
• targets: [] volta ao alvo implícito (o host da URL).

Retentativas

retries só vale para métodos seguros (GET e HEAD). Para rotas com POST, PATCH, DELETE e outros, o produto gera um destino sem retentativa: repetir um POST pode duplicar a operação no seu backend. É uma decisão de produto, não uma limitação acidental.

TLS e CA própria

• Com https e tls_verify: true, o certificado do seu serviço é verificado contra as CAs do sistema.
• Se o seu serviço usa CA interna, cole-a em ca_bundle_pem. Um bundle que não é PEM válido resulta em erro de configuração.
• ca_bundle_pem com backend http é recusado na publicação (ca_bundle_requires_https).
• tls_verify: false é recusado na publicação enquanto a operação não liberar (insecure_tls_not_allowed).

Timeout por rota

Uma rota pode sobrescrever o tempo de envio e leitura do backend (timeout_override_ms, de 1000 a 300000). O tempo de conexão continua sendo o do backend. Isso serve para rotas específicas que legitimamente demoram (relatórios), sem afrouxar a API inteira.

Verificação de saúde

Opcional. Quando configurada, o gateway passa a verificar cada alvo e a tirar do balanceamento os que falham — e o estado aparece no status da API.

Campo	Padrão	Faixa	Significado
http_path	—	até 256 caracteres, começando com /	caminho pedido em cada alvo (não soma o base_path); obrigatório ao ligar
interval_seconds	10	1..300	intervalo entre verificações, por alvo e por réplica
timeout_seconds	3	1..60	prazo de cada verificação
healthy_threshold	2	1..10	sucessos seguidos para o alvo voltar
unhealthy_threshold	3	1..10	falhas seguidas (HTTP 404/429/5xx, TCP ou timeout) para tirar o alvo
passive	true	—	também conta o tráfego real (500/502/503/504, falha de conexão, timeout) com os mesmos limiares

• Ativa: GET http_path a cada interval_seconds; bom = 2xx/3xx; ruim = 404, 429 e 5xx.
• Passiva: só o que é erro do backend conta (5xx e falha de conexão). Um 4xx do cliente jamais derruba o alvo. O retorno a saudável fica com a verificação ativa.
• Em https, a verificação usa o mesmo tls_verify do backend.
• Remover: PATCH com {"health_check": {"enabled": false}}. PATCH com campos faz merge sobre a verificação atual.

O que surpreende: o verificador só começa a observar os alvos depois da primeira requisição que passa por aquele upstream em cada réplica. Por isso o status mostra unknown (no_observation) enquanto não há tráfego, e warming_up logo depois — "saudável" só passa a ser observação depois do aquecimento (intervalo × limiar de falhas + timeout).

Exemplo

curl -sS -X POST "$BASE/v1/apis/$API_ID/backends" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: backend-erp-01' \
  -d '{
        "name": "erp-producao",
        "url": "https://api.suaempresa.com/v2",
        "tls_verify": true,
        "timeouts": {"connect_ms": 3000, "send_ms": 30000, "read_ms": 30000},
        "retries": 2,
        "health_check": {"http_path": "/healthz", "interval_seconds": 10, "timeout_seconds": 3,
                         "healthy_threshold": 2, "unhealthy_threshold": 3, "passive": true},
        "targets": [
          {"host": "api1.suaempresa.com", "port": 443, "weight": 1},
          {"host": "api2.suaempresa.com", "port": 443, "weight": 1}
        ]
      }'

Erros comuns

Resposta	Causa provável	Ação
400 backend_not_allowed (literal_ip, private_address, internal_suffix, single_label_host)	destino interno ou IP literal	use nome público que resolva só para IP público
400 backend_not_allowed (dns_timeout)	o DNS não respondeu dentro do prazo	verifique a zona e repita
400 backend_not_allowed (mixed_destinations)	URL externa com targets internos, ou o inverso	mantenha um único tipo por backend
429 too_many_requests (backend_validation_busy)	validações de destino simultâneas demais na organização	aguarde e repita
422 publish_validation_failed (insecure_tls_not_allowed)	tls_verify: false sem liberação	mantenha true ou peça liberação
409 ao excluir	backend em uso por rota	remova ou aponte a rota antes

Próximos passos

• Rotas: como o caminho público chega ao backend.
• Publicação: a revalidação do destino antes de aplicar.
• Uso e métricas: como ler a saúde do backend no status.