Skip to content

Network Peering

Network Peering connects two teams that you own so that resources in either team's namespace can reach each other over the cluster network — without going through the public internet.

A common use case is connecting a staging team to a production team for read-only data sync, or connecting a shared services team (e.g. a central observability stack) to one or more application teams.

How it works

Each team has its own Kubernetes namespace and is isolated by default — pods in one team cannot reach pods in another. A peering establishes bidirectional Cilium network policies between the two namespaces:

  • After peering, every pod in team A can reach every pod in team B and vice versa
  • Internal DNS works across the peering (resolve services by their short names from either side)
  • Traffic stays inside the cluster — it does not touch the public internet
  • The firewalls attached to individual instances still apply on top — peering opens the cluster path; per-instance rules decide what listens

Requirements

  • You must own both teams (the same user account must be the team owner on each side)
  • Each team must already have a tenant namespace provisioned (the default for any team that has created at least one resource)
  • A given pair of teams can only be peered once

Create a peering

  1. Switch into the team you want to peer from (top-right team switcher)
  2. Open Networking from the main menu, then the Peering tab
  3. Click Peer with a team
  4. Pick the peer team from the list. Only teams you own that aren't already peered with this one are listed
  5. Click Peer teams

The peering shows Waiting, then Connecting, then Active. Deployment usually takes 10 to 30 seconds while the policies are committed and synced into the cluster, and the page updates by itself.

Use the peering

Once active, resources in either team can reach the other side using the peer's internal DNS names. The fully-qualified form is:

Text
<service-name>.<peer-team-namespace>.svc.cluster.local

The service name is the address the peer team's Internal endpoints tab lists for the resource, without its port. It is not always the resource's own name: a PostgreSQL database named db-orders answers at db-orders-rw.

For example, from a VPS in team app-prod, to reach that database in team data-shared (namespace datashared42):

Bash
psql -h db-orders-rw.datashared42.svc.cluster.local -U appuser -d orders

You can find the exact namespace name on the peer team's Networking page, where it heads the page. The Peering tab also lists each peer team's namespace under its name.

Remove a peering

  1. Open Networking in either of the peered teams, then the Peering tab
  2. Find the peer team in the list
  3. Click Remove, then Remove peering to confirm

Only the person who created a peering can remove it. Both directions are torn down together. The status briefly shows Removing while the policies are cleaned up, and the peering leaves the list once they are gone.

Limitations and notes

  • Peering is all-or-nothing at the namespace level: every pod in one team can reach every pod in the other. There is no per-service or per-port granularity in the peering itself — use per-instance firewall rules to restrict what each service exposes.
  • Peering does not cross teams owned by different users. There is no cross-account peering today.
  • Peering does not create new IP addresses or NICs. Your resources continue to use their existing internal cluster IPs.
  • A peering does not count against any resource quota and is not billed separately.
  • Tearing down a peering immediately drops in-flight connections that depended on it.

Troubleshooting

The peer team I want isn't in the list

The list only shows teams owned by your account that aren't already peered with the current team. Check that the team is owned by the same user (not just one you're a member of), and that no peering already exists between the two.

Peering is stuck on Waiting or Connecting

Deployment normally completes within 30 seconds. If it hasn't moved after a few minutes, contact support — there may be a sync issue with the underlying GitOps reconciliation.

I can resolve the peer's hostname but the connection times out

The peering opens cluster-level connectivity, but the target instance may still have a firewall blocking the source. On the target instance's Firewall tab, add an inbound rule with the source set to the calling instance (you can pick instances across peered teams — they appear in the instance picker once peering is active). See Firewalls — east-west traffic for the worked example.