Networking & the mesh

Every node runs a brig-proxy sidecar. Together they form a workload-identity mesh: each replica gets a SPIFFE identity, all proxy-to-proxy traffic is mTLS, and routing decisions (which replica, on which node) happen at the proxy. You get service discovery, edge TLS, sticky sessions, and network policy without running your own ingress or service registry.

Service discovery

Replicas reach each other by workload name — no DNS records, no IPs, no ports to publish. A request to another workload’s name is resolved by the local proxy to a live replica:

• If a replica of the target runs on the same node, the proxy routes there directly.
• Otherwise it forwards over mTLS to a peer proxy on a node that has one.

Discovery is environment-scoped. A staging caller only ever reaches staging replicas; a production workload of the same name is invisible to it.

Inspect what the mesh sees:

brig mesh endpoints api      # live placements for "api": node, replica, identity
brig mesh check              # probe every node's proxy from the cp, report unreachable peers

Public exposure & TLS

Set public = true (the default) and Brig hands the workload a managed URL on *.brig.run with automatic TLS — the wildcard certificate is issued and renewed centrally, and the edge terminates TLS before routing to the nearest healthy replica.

name   = "api"
image  = "ghcr.io/me/api:v13"
public = true            # <name>-<slug>.brig.run, TLS included

Set public = false to keep a workload mesh-internal and bring your own ingress (Cloudflare Tunnel, nginx, Traefik). To attach your own domain with automatic certs, see Custom domains.

Ports control what’s reachable and under which hostname at the edge:

ports = ["80:api.example.com", "9000"]   # 80 routed for api.example.com; 9000 mesh-only

Network policy

Two workload fields gate who may call whom. Both take lists of workload names; empty means unrestricted.

name       = "orders"
allow_from = ["web", "api"]    # only these workloads may call "orders"
allow_to   = ["payments"]      # "orders" may call only "payments"

Field	Direction	Enforced where
allow_from	ingress — who may call this workload	At the receiving replica’s proxy, using the caller’s mTLS-attested identity.
allow_to	egress — who this workload may call	At the caller’s proxy. The target’s allow_from is the authoritative gate.

The caller’s identity is taken from its mesh client certificate, so a plaintext or unauthenticated caller is treated as anonymous and fails any non-empty allow_from list (fail-closed). Pair allow_from with placement.same_node_only for sidecars that should never accept cross-node traffic at all.

Note

allow_from is only enforced for callers that present a mesh identity. Make sure your workloads dial peers through the local proxy (the default for mesh-aware clients) rather than hitting container IPs directly.

Sticky routing

By default the proxy round-robins across replicas. To pin a logical session to one replica, name a header to hash on:

[routing]
sticky_by_header = "X-User-Id"

When the header is present, the proxy uses rendezvous hashing on its value to pick a stable replica; requests without the header fall back to round-robin. The header name must be a valid HTTP token.

Diagnostics

brig mesh exposes the primitives the proxy uses, handy for debugging identity and reachability:

brig mesh check                  # cp probes every node's proxy; non-zero exit if any fail
brig mesh endpoints <workload>   # live placements + SPIFFE ids for a workload
brig mesh routes                 # dump a local brig-proxy's routing table (loopback)
brig mesh ping <host:port>       # dial a target with the local workload identity (mTLS)
brig mesh server                 # run a tiny mTLS echo server that prints the caller's identity

brig mesh ping and brig mesh server read identity material from --identity-dir (default /var/run/brig/identity: tls.crt, tls.key, ca.crt) and are mostly useful from inside a node when verifying that mTLS and SPIFFE validation behave as expected.