Conectar serviços públicos e acessar bancos privados pelo cluster

Um caso real

• Redis no Azure Cache: o firewall do cache tinha IPs antigos, e a conexão dava tempo esgotado. A correção foi liberar os IPs de saída atuais do Kubepier na regra de firewall do cache e conectar na porta 6380 com TLS (a porta 6379, sem TLS, vem desligada no Azure Cache).
• MongoDB numa VM: o nome do servidor resolvia para um IP privado (172.16.x.x) e a VM não tinha IP público. Pela rota Direta não há como chegar lá; o caminho é a rota Pelo cluster, de dentro da rede do cliente (ou o desktop pela VPN).
• Redis no Azure Cache Premium: conexao_encerrada pela rota Direta e pela rota Pelo cluster, com firewall, porta e TLS certos. A causa era a senha salva no cadastro, de outro cache. Desde 05/10/2026 esse caso aparece como erro de autenticação (WRONGPASS), não mais como conexão encerrada. Detalhes em Problemas comuns.

• Problemas comuns: Redis com conexão encerrada nas duas rotas

De onde o Kubepier conecta

Seu serviço é público ou privado (private endpoint, IP privado)?

• Público (tem endpoint na internet): use a rota Direta. Libere os IPs de saída do Kubepier no firewall do serviço. Prefira liberar só a faixa do Kubepier em vez de abrir para todos.
• Privado (private endpoint, IP privado, só pela VPN ou on-premises): use a rota Pelo cluster, se algum cluster do cliente alcança o serviço. Nada precisa ser aberto para a internet.
• Se nenhum cluster do cliente alcança o serviço: use o Kubepier Desktop pela sua VPN.
• Para testar a rede antes, de dentro do cluster: Bastion da web (nc, curl, dig) ou Túnel seguro do desktop.

Rota de conexão: Direta ou Pelo cluster

No formulário de cada serviço do cliente (RabbitMQ, Service Bus, MongoDB e Redis), Rota de conexão tem duas opções. O serviço mostra a rota em uso: "direta" ou "via cluster <nome>".

Rota pelo cluster: como acessar o banco privado

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: kubepier-relay
  namespace: <namespace>
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["create", "get", "list", "delete"]
  - apiGroups: [""]
    resources: ["pods/exec", "pods/portforward"]
    verbs: ["create", "get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: kubepier-relay
  namespace: <namespace>
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: kubepier-relay
subjects:
  - kind: User
    name: <usuario-ou-objectId-da-credencial>
    apiGroup: rbac.authorization.k8s.io

• No cadastro do serviço, em Rota de conexão, escolha Pelo cluster, escolha um cluster do cliente e o namespace, e clique em Salvar rota. Só o admin muda a rota; o membro vê a dica para pedir a um admin.
• Aplique no namespace o Role abaixo (o mesmo que o app mostra em Rede e segurança, no item da rota pelo cluster), ligado à identidade da credencial do cluster.
• No primeiro uso, a tela mostra "Preparando conexão pelo cluster…" enquanto o relay sobe (até 120 segundos).
• Quando a conexão direta falha com IP privado ou tempo esgotado, a tela sugere "Conectar pelo cluster".

Rota pelo cluster: como funciona e limites

MongoDB: replica sets e mongodb+srv:// funcionam; os registros SRV e TXT são resolvidos dentro do cluster. Service Bus: pela rota, usa AMQP sobre WebSocket na porta 443. A rota também vale no plano Free, para as telas de leitura.

Rota pelo cluster: auditoria

• Criação e remoção do relay (relay_criar, relay_remover) e cada mudança de rota (rota_alterada) vão para a auditoria da organização.
• Nunca o tráfego nem as credenciais.

Como saber se o endereço é privado

Resolva o nome do serviço. Se o IP estiver em 10.0.0.0/8, 172.16.0.0/12 ou 192.168.0.0/16, ele é privado e a web não chega lá.

# O nome resolve para IP público ou privado?
dig +short mongo.cliente.com.br
nslookup mongo.cliente.com.br

# A porta responde? (do Bastion, de dentro do cluster)
nc -vz mongo.cliente.com.br 27017

# TLS: qual certificado o servidor apresenta?
openssl s_client -connect meu-cache.redis.cache.windows.net:6380 -servername meu-cache.redis.cache.windows.net </dev/null

Azure Cache for Redis

az redis firewall-rules create --resource-group <resource-group> --name <cache> \
  --rule-name kubepier --start-ip 20.206.66.128 --end-ip 20.206.66.129

• Libere os IPs de saída em Firewall do cache (no portal) ou pelo comando abaixo. Remova regras antigas que não servem mais.
• Conecte na porta 6380 com TLS: use rediss://, ou marque TLS no cadastro. A porta 6379 sem TLS vem desligada.
• A senha é uma das chaves de acesso do cache.
• Cache só com private endpoint (acesso público desligado): a web não alcança. Use a rota Pelo cluster, ou o desktop pela VPN.

Azure Cosmos DB for MongoDB (RU e vCore)

• No portal, em Networking: deixe o acesso público em redes selecionadas e acrescente os IPs de saída do Kubepier (no vCore, em regras de firewall).
• Com acesso público desligado e só private endpoint, use a rota Pelo cluster, ou o desktop pela VPN.

MongoDB Atlas

atlas accessLists create 20.206.66.128/31 --type cidrBlock --comment "Kubepier"

• Em Network Access → IP Access List, acrescente a faixa do Kubepier, ou pelo Atlas CLI:

Cluster com private endpoint ou peering, sem acesso público: use a rota Pelo cluster, ou o desktop pela VPN.

Azure Service Bus

• No portal: o namespace → Networking → Selected networks, e acrescente os IPs de saída no firewall.
• Nem todo tier aceita regras de IP: confira na documentação da Azure o do seu namespace.
• Namespace só com private endpoint: use a rota Pelo cluster, ou o desktop pela VPN.

RabbitMQ

• CloudAMQP e outros gerenciados: acrescente os IPs na lista de IPs permitidos do provedor, no painel.
• Numa VM: libere no NSG (Azure) ou no security group (AWS) a porta da API de gerenciamento (15672, ou a que você publica) para a faixa do Kubepier.

AWS

aws ec2 authorize-security-group-ingress --group-id <sg-id> \
  --protocol tcp --port 5432 --cidr 20.206.66.128/31

• ElastiCache: não tem endpoint público; a web não alcança. Use a rota Pelo cluster com um cluster na mesma VPC, ou o desktop pela VPN.
• RDS: só com Publicly accessible ligado e o security group liberando a porta para a faixa do Kubepier:

MSK: hoje a web não conecta no Kafka; o painel Dependências do desktop só lê as variáveis do pod e os ConfigMaps que elas referenciam.

Google Cloud

# Substitui a lista inteira: inclua as redes que já estão lá
gcloud sql instances patch <instancia> --authorized-networks=20.206.66.128/31,<redes-ja-liberadas>

• Memorystore (Redis): só IP privado; use a rota Pelo cluster com um cluster na mesma VPC, ou o desktop pela VPN.
• Cloud SQL: em Authorized networks, acrescente a faixa do Kubepier:

Serviços próprios em VMs

Libere a porta do serviço só para a faixa do Kubepier no NSG ou no security group. Exemplo no Azure, para um MongoDB na 27017:

az network nsg rule create --resource-group <resource-group> --nsg-name <nsg> \
  --name kubepier --priority 300 --direction Inbound --access Allow --protocol Tcp \
  --source-address-prefixes 20.206.66.128/31 --destination-port-ranges 27017

On-premises

• Com IP público e NAT: libere a faixa do Kubepier no firewall de borda para a porta do serviço, com TLS.
• Sem exposição para a internet: use a rota Pelo cluster com um cluster que tenha rota até lá, ou o desktop pela VPN.

Mensagem de erro → o que fazer

Na rota Direta, a web mostra a mensagem do próprio serviço (por exemplo, connect ETIMEDOUT ou getaddrinfo ENOTFOUND) dentro de "erro no serviço", e as falhas de credencial como "sem permissão no serviço". No cartão de status do Redis aparece a mensagem do servidor, como WRONGPASS invalid username-password pair. Na rota Pelo cluster, os erros de rede têm os códigos da tabela abaixo; os de credencial são os mesmos da rota Direta.

Erros da rota pelo cluster

Quando a rota pelo cluster falha, a API responde 502 com o erro rota_cluster e um destes códigos:

Formatos de conexão aceitos

• Redis: redis://usuario:senha@host:porta/banco, rediss:// para TLS, ou os campos host, porta, usuário, senha, TLS e banco.
• Redis no formato que o portal da Azure mostra (host:6380,password=...,ssl=True,abortConnect=False, com user= e defaultDatabase= opcionais). Nesse formato não há como escapar vírgula, então uma senha com vírgula é recusada. Prefira colar a connection string inteira, copiada em Chaves de acesso do cache certo: host, porta, senha e TLS vêm juntos e a chave de dev não vai parar no cadastro de prd.
• Redis: TLS ligado sem porta usa 6380 (sem TLS, 6379); a caixa TLS vale também com connection string; TLS na 6379 de um *.redis.cache.windows.net, ou redis:// na 6380 sem TLS, são recusados com a explicação.
• MongoDB: a connection string (mongodb:// ou mongodb+srv://) e, em campo separado, o nome do banco. Se você chega a um replica set por um único nó (um IP ou um túnel), acrescente directConnection=true: sem isso, o driver tenta os outros membros pelos nomes internos e falha.
• RabbitMQ: URL da API de gerenciamento (https://host:15672 ou a do provedor), usuário e senha.
• Service Bus: a connection string do namespace (Endpoint=sb://...;SharedAccessKeyName=...;SharedAccessKey=...).

Boas práticas de segurança

• Libere só a faixa do Kubepier (a /31 da lista acima), nunca 0.0.0.0/0.
• Nunca exponha um banco na internet sem TLS.
• Ao trocar de IPs, remova as regras antigas.
• Use credenciais com o mínimo de permissão; a lista de IPs soma uma camada de rede às credenciais, não as substitui.