Connect public services and reach private databases through the cluster

A real case

• Redis on Azure Cache: the cache firewall had old IPs, and the connection timed out. The fix was to allow Kubepier’s current egress IPs in the cache firewall rule and connect on port 6380 with TLS (port 6379, without TLS, is off on Azure Cache).
• MongoDB on a VM: the server name resolved to a private IP (172.16.x.x) and the VM had no public IP. The Direct route cannot reach it; the way in is the Through the cluster route, from inside the client network (or the desktop over the VPN).
• Redis on Azure Cache Premium: conexao_encerrada on both the Direct and the Through the cluster route, with the right firewall, port and TLS. The cause was the password saved on the client, from another cache. Since 2026-10-05 this case shows as an authentication error (WRONGPASS), no longer as a closed connection. Details in Troubleshooting.

• Troubleshooting: Redis closed connection on both routes

Where Kubepier connects from

Is your service public or private (private endpoint, private IP)?

• Public (has an internet endpoint): use the Direct route. Allow Kubepier’s egress IPs on the service firewall. Prefer allowing only Kubepier’s range over opening it to everyone.
• Private (private endpoint, private IP, VPN-only or on-premises): use the Through the cluster route, if one of the client’s clusters reaches the service. Nothing has to be opened to the internet.
• If no client cluster reaches the service: use Kubepier Desktop over your VPN.
• To test the network first, from inside the cluster: the web Bastion (nc, curl, dig) or the desktop Secure tunnel.

Connection route: Direct or Through the cluster

In the form of each client service (RabbitMQ, Service Bus, MongoDB and Redis), Connection route has two options. The service shows the route in use: "direct" or "via cluster <name>".

Route through the cluster: reaching the private database

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: <user-or-objectId-of-the-credential>
    apiGroup: rbac.authorization.k8s.io

• In the service form, under Connection route, pick Through the cluster, pick one of the client’s clusters and the namespace, and click Save route. Only admins change the route; members see a hint to ask an admin.
• Apply the Role below in the namespace (the same one the app shows under Network and security, in the cluster-route item), bound to the cluster credential identity.
• On first use, the screen shows "Preparing connection through the cluster…" while the relay starts (up to 120 seconds).
• When the direct connection fails with a private IP or a timeout, the screen suggests "Connect through the cluster".

Route through the cluster: how it works and limits

MongoDB: replica sets and mongodb+srv:// work; the SRV and TXT records are resolved inside the cluster. Service Bus: through the route, it uses AMQP over WebSocket on port 443. The route also works on the Free plan, for the read-only views.

Route through the cluster: audit

• Relay creation and removal (relay_criar, relay_remover) and every route change (rota_alterada) go to the organization audit log.
• Never the traffic or the credentials.

How to tell whether the address is private

Resolve the service name. If the IP is in 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16, it is private and the web cannot reach it.

# Does the name resolve to a public or a private IP?
dig +short mongo.cliente.com.br
nslookup mongo.cliente.com.br

# Does the port answer? (from the Bastion, inside the cluster)
nc -vz mongo.cliente.com.br 27017

# TLS: which certificate does the server present?
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

• Allow the egress IPs under the cache Firewall (in the portal) or with the command below. Remove old rules you no longer need.
• Connect on port 6380 with TLS: use rediss://, or tick TLS in the form. Port 6379 without TLS is off.
• The password is one of the cache access keys.
• A cache with a private endpoint only (public access off): the web cannot reach it. Use the Through the cluster route, or the desktop over the VPN.

Azure Cosmos DB for MongoDB (RU and vCore)

• In the portal, under Networking: keep public access on selected networks and add Kubepier’s egress IPs (on vCore, as firewall rules).
• With public access off and a private endpoint only, use the Through the cluster route, or the desktop over the VPN.

MongoDB Atlas

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

• Under Network Access → IP Access List, add Kubepier’s range, or with the Atlas CLI:

A cluster with a private endpoint or peering and no public access: use the Through the cluster route, or the desktop over the VPN.

Azure Service Bus

• In the portal: the namespace → Networking → Selected networks, then add the egress IPs to the firewall.
• Not every tier supports IP rules: check the Azure documentation for your namespace tier.
• A namespace with a private endpoint only: use the Through the cluster route, or the desktop over the VPN.

RabbitMQ

• CloudAMQP and other managed services: add the IPs to the provider’s allowed IP list, in its dashboard.
• On a VM: allow the management API port (15672, or the one you publish) to Kubepier’s range in the NSG (Azure) or security group (AWS).

AWS

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

• ElastiCache: no public endpoint; the web cannot reach it. Use the Through the cluster route with a cluster in the same VPC, or the desktop over the VPN.
• RDS: only with Publicly accessible on and the security group allowing the port to Kubepier’s range:

MSK: the web does not connect to Kafka today; the desktop Dependencies panel only reads pod variables and the ConfigMaps they reference.

Google Cloud

# Replaces the whole list: include the networks already there
gcloud sql instances patch <instance> --authorized-networks=20.206.66.128/31,<already-allowed-networks>

• Memorystore (Redis): private IP only; use the Through the cluster route with a cluster in the same VPC, or the desktop over the VPN.
• Cloud SQL: under Authorized networks, add Kubepier’s range:

Self-hosted services on VMs

Allow the service port only to Kubepier’s range in the NSG or security group. Example on Azure, for MongoDB on 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

• With a public IP and NAT: allow Kubepier’s range on the edge firewall to the service port, with TLS.
• Not exposed to the internet: use the Through the cluster route with a cluster that has a route there, or the desktop over the VPN.

Error message → what to do

On the Direct route, the web shows the service’s own message (for example connect ETIMEDOUT or getaddrinfo ENOTFOUND) under "service error", and credential failures as "no permission on the service". The Redis status card shows the server message, such as WRONGPASS invalid username-password pair. On the Through the cluster route, network errors carry the codes in the table below; credential errors are the same as on the Direct route.

Route-through-the-cluster errors

When the route through the cluster fails, the API answers 502 with the rota_cluster error and one of these codes:

Accepted connection formats

• Redis: redis://user:password@host:port/db, rediss:// for TLS, or the host, port, user, password, TLS and database fields.
• Redis in the format the Azure portal shows (host:6380,password=...,ssl=True,abortConnect=False, with optional user= and defaultDatabase=). That format has no way to escape a comma, so a password containing one is refused. Prefer pasting the whole connection string, copied from Access keys of the right cache: host, port, password and TLS come together and a dev key does not end up on the prd client.
• Redis: TLS on without a port uses 6380 (6379 without TLS); the TLS box also applies to connection strings; TLS on port 6379 of a *.redis.cache.windows.net, or redis:// on 6380 without TLS, is refused with an explanation.
• MongoDB: the connection string (mongodb:// or mongodb+srv://) and, in a separate field, the database name. If you reach a replica set through a single node (one IP or a tunnel), add directConnection=true: otherwise the driver tries the other members by their internal names and fails.
• RabbitMQ: management API URL (https://host:15672 or the provider’s), user and password.
• Service Bus: the namespace connection string (Endpoint=sb://...;SharedAccessKeyName=...;SharedAccessKey=...).

Security practices

• Allow only Kubepier’s range (the /31 in the list above), never 0.0.0.0/0.
• Never expose a database to the internet without TLS.
• When IPs change, remove the old rules.
• Use least-privilege credentials; the IP allowlist adds a network layer on top of credentials, it does not replace them.