Reach a cluster over the mesh

This walks you all the way from an empty cluster to curling a pod on it from your laptop over the mesh — no public load balancer, no kubectl port-forward, no inbound firewall hole. The machines on your network reach the cluster’s pods and services directly, gated by the network’s policy.

Runs on vs. attached to. A cluster runs on a network — the private network its own nodes live on — and can separately be attached to other networks. This guide is about attaching: bridging a cluster onto a network through a connector, so machines there reach its pods. For the network a cluster runs on, see Core concepts → Networking.

The pieces:

• a Control Plane with at least one node (where your pods run),
• a Mesh network (the private network your laptop and the cluster share),
• an attachment — a managed connector the platform runs inside the cluster that advertises the cluster’s pod and service ranges onto the network.

You’ll need: the lbr CLI, kubectl, Console access, and the Mesh product enabled for your organization. One Linux host to attach as a node — a QEMU VM on your laptop is perfect for trying this out.

1. A cluster with a node

Create a Control Plane and attach a node so there’s somewhere to run pods:

lbr cp cluster create test

Then attach a worker. Any Linux box works; for a self-contained trial, follow Join a node from a local QEMU VM — it boots a throwaway VM and joins it in a few minutes. Confirm the node is Ready:

lbr cp node list test      # or: kubectl get nodes

2. A mesh network

In the Console, open Mesh → Networks and create a network — call it corp. (Prefer code? The longbridge_mesh_network Terraform resource does the same.) A network is a private, Tailscale-compatible tailnet the platform runs the coordination plane for; you’ll join machines to it in a moment.

3. Attach the cluster

On the network’s Clusters tab, choose Attach cluster and pick test. Leave the defaults — the attachment advertises the cluster’s pod and service ranges (10.244.0.0/16 and 10.96.0.0/16) onto the network, so machines on corp can reach anything running in the cluster.

Everything on the network can reach the cluster until you say otherwise — a fresh network is allow-all. Scope access with tags on the network’s Policy tab before you put anything sensitive behind it. See Policy.

Behind the scenes the platform deploys a small connector into the cluster (namespace longbridge-mesh), joins it to corp, and approves exactly the routes the attachment advertises. Nothing you have to run.

4. Check it’s connected

The attachment goes Ready once the connector is up and its routes are approved. On the Clusters tab it shows Ready; the network’s Machines tab lists the connector as lb-test-<network>, online. That’s the signal the path is live.

5. A test workload

Run something to reach. From your workstation, against the cluster:

kubectl run web --image nginx --port 80
kubectl expose pod web --port 80 --name web
kubectl get pod web -o wide    # note its pod IP, e.g. 10.244.0.92
kubectl get svc web            # note the ClusterIP, e.g. 10.96.31.2

6. Join your machine to the mesh

Now put your own machine on corp. On the network’s Machines tab, Add machine prints a one-command join. Run it — and add --accept-routes so your machine picks up the cluster ranges the connector advertises:

tailscale up --login-server https://corp.eu-hel.mesh.lngbrdg.com \
  --auth-key <key> --accept-routes

Your machine gets a mesh IP (100.64.0.x) and installs routes for the cluster’s pod and service ranges via the connector.

7. Reach the cluster

Curl the pod or the service by IP, straight from your machine:

curl http://10.244.0.92/     # the pod
curl http://10.96.31.2/      # the ClusterIP
# <title>Welcome to nginx!</title>

That request left your laptop, crossed the mesh to the connector, and the connector forwarded it into the cluster — no public endpoint anywhere. The pod sees the request coming from the connector (source-NAT), so return traffic finds its way back with nothing to configure on the cluster side.

Reach services by name

Pod IPs come and go — you want a stable name. Turn on cluster DNS for the attachment (the DNS toggle on the network’s Clusters tab, or dns_enabled = true on the Terraform attachment). The platform runs a small resolver in the cluster and teaches the network to route the cluster’s DNS to it.

Make sure your machine is using the network’s DNS — join (or re-run) with --accept-dns:

tailscale up --login-server https://corp.eu-hel.mesh.lngbrdg.com \
  --auth-key <key> --accept-routes --accept-dns

Now reach the service by name, from your laptop:

curl http://web.default.svc.test.cluster.internal/    # <cluster>.cluster.internal
# <title>Welcome to nginx!</title>

The name is ‹service›.‹namespace›.svc.‹cluster›.cluster.internal — the cluster name is baked in, so it stays unambiguous even when several clusters are on the same network. While test is the only DNS-providing cluster on corp, the plain in-cluster name works too, as a convenience:

curl http://web.default.svc.cluster.local/            # same pod

Attach a second cluster with DNS on and cluster.local retires (it can only mean one cluster) — the per-cluster …cluster.internal names keep working for both.

Clean up

Detach on the network’s Clusters tab (or delete the longbridge_mesh_network attachment). Remove the workload and the node when you’re done:

kubectl delete pod web && kubectl delete svc web
lbr cp node rm test <node>

Detaching removes the connector and drops the routes; the cluster keeps running untouched.