NetBird Part 5 - The Sharp Edges and When to Walk Away

The Part the Series Owes You

The first four parts of this series built NetBird up. Part 1 made the
case for a WireGuard mesh with a control plane. Part 2 self-hosted that
control plane. Part 3 locked it down with deny-by-default access
policies. Part 4 bridged the devices that cannot run the agent with
routing peers. Each part ended with a limits section, because that is
how I write, but the arc was upward: here is a good tool, here is how
to run it well.

A four-part series that stops there is an advertisement, not an
assessment. Every tool I run in production has a set of sharp edges I
learned the hard way, and the honest service to a reader is to name
them before they find them at 2 a.m. during an outage. So this is the
part that bites back. Where NetBird's abstractions leak, what breaks
and how, and the cases where the correct move is not to deploy it at
all. If the first four parts were the argument for, this is the
argument against, written by the same person, which is the only kind
of argument against worth trusting.

The Control Plane Is a Single Point of Failure

The defining property of NetBird, the thing that separates it from raw
WireGuard, is the control plane: management and signal, plus the relay
and an identity provider. That control plane is what makes the mesh
self-configuring. It is also a thing that can go down, and when it does
the failure mode is specific and worth understanding exactly, because
the marketing blurs it and the reality is more nuanced than either
"nothing breaks" or "everything breaks."

Here is what actually happens when management and signal are
unreachable. Existing, already-established peer connections keep
working. This is the one genuinely reassuring fact, and it follows
directly from WireGuard's design: once two peers have exchanged keys
and found each other, the tunnel is a direct kernel-level thing between
them that does not consult the control plane on every packet. A dead
management server does not tear down live tunnels.

Everything else stops. No new peer can join the network. No peer that
reconnects, after a laptop sleeps or a server reboots, can re-establish,
because the signal exchange that pairs it with the others runs through
the control plane. Policy changes you make do not propagate. Peers
whose authentication expires cannot re-authenticate and drop off the
network for good until the control plane returns. So the honest summary
is: a control-plane outage does not break the network you have, but it
freezes it, and any disruption to any peer during the outage becomes a
peer that is simply gone until you recover. On a network where laptops
sleep and servers reboot, "frozen" degrades to "shrinking" within
hours.

If you self-hosted, per Part 2, that uptime is now your problem. The
NetBird control plane is critical infrastructure in the specific sense
that its availability is a ceiling on your network's ability to heal
itself. It deserves the same treatment as any other critical service:
monitored, backed up, with a tested recovery path. This is not a flaw,
it is the cost of the feature, but it is a cost that the "just run these
containers" quickstart does not put on the invoice.

The Mesh Is Not Always a Mesh

NetBird sells a peer-to-peer mesh: every node talks directly to every
other node, no traffic through a central box. When it works, it is
exactly that, and it is excellent. The word "when" is doing real labor
in that sentence.

Direct connections depend on NAT traversal. Two peers behind separate
home routers, mobile networks, or corporate firewalls cannot just open
a socket to each other. NetBird uses the standard ICE machinery, STUN
to discover each peer's public-facing address and punch a hole, to
establish the direct path. STUN works for most NAT types. It does not
work for all of them. Symmetric NAT, which allocates a different
external port per destination, defeats hole-punching. Carrier-grade NAT
on mobile and some residential ISPs stacks NAT on NAT and does the
same. A sufficiently paranoid corporate firewall that blocks outbound
UDP kills it outright.

When direct fails, NetBird does not fail the connection. It falls back
to the relay, a TURN server that both peers can reach, and forwards the
encrypted traffic through it. The tunnel stays up and stays encrypted,
the relay sees only ciphertext, and from the user's point of view it
just works. But for that pair of peers, the mesh has quietly become
hub-and-spoke. Their traffic now takes an extra hop through your relay,
inherits the relay's latency and its bandwidth ceiling, and depends on
the relay staying up. If you self-host one relay and a chunk of your
fleet is behind CGNAT, that single relay is carrying real traffic and
is now a bottleneck and a dependency you may not have planned for.

The lesson is to look, not assume. netbird status --detail tells you,
per peer, whether the connection is direct or relayed. Run it across
your fleet before you believe you have a mesh. A deployment that is 90%
relayed is a perfectly functional VPN, but it is not the architecture
you thought you deployed, and you should size and site your relays for
the traffic they are actually carrying rather than the traffic you
hoped they would not.

Every Peer Needs the Agent

NetBird is an agent-based overlay. Each participating node runs the
NetBird client daemon, which manages the WireGuard interface and talks
to the control plane. For servers, laptops, and VMs this is a
non-issue, you install a package. For a large fleet it is a fleet of
daemons to deploy, keep updated, and monitor, which is ordinary
endpoint management but is work.

The real wall is the device that cannot run the agent at all. The
network printer, the NAS with a locked-down firmware, the IP camera,
the managed cloud resource with no host to install on. That is exactly
the gap Part 4 filled with routing peers, and it is worth being clear
that routing peers are a workaround, not a feature you would choose if
the device could run the agent. A routing peer reintroduces the
hub-and-spoke shape on purpose, concentrates that subnet's traffic
through one node, and carries the ACL interaction I flagged in Part 3
and the Networks model in Part 4. It is the right tool for unavoidable
cases. It is not free, and a design that leans heavily on routing peers
is a design that is fighting the agent-based model rather than using it.

Self-Hosting Is Real Weight

Part 2 walked through standing up management, signal, relay, the
embedded identity provider, a database, and TLS. That is five or six
stateful services, and once they are up you own all of them. Upgrades
that must stay compatible across components. Certificate renewal.
Database backups that you have actually tested restoring, because the
control plane's state is what your whole network's configuration lives
in. The identity provider is its own stateful service with its own
upgrade and backup story, and if it is down, authentication is down and
you are back in the frozen-network state from two sections ago.

This is the tradeoff nobody escapes: self-hosting buys you control and
data sovereignty, the whole reason Part 2 exists, and it charges you
operational ownership of a non-trivial distributed system. The managed
NetBird cloud makes all of that someone else's job, which is a real and
honest option, and in exchange you hand a third party the control plane
and identity layer of your private network, which for some threat
models is precisely the thing you were trying to avoid. There is no
free choice here. There is a choice between running critical infra
yourself and trusting someone else to, and you should make it on
purpose rather than defaulting into the self-hosted path because a blog
series, this one included, made it look like a weekend project.

When Not to Use NetBird

The strongest thing I can say for a tool is where it is the wrong one.

Use plain WireGuard, no control plane, when your topology is small and
static. A handful of servers with stable public addresses, or a classic
hub with a few spokes, does not need self-configuration. Hand-managing
a dozen WireGuard peers is a text file and a habit, and it has zero
moving parts beyond the kernel module. The entire value of NetBird is
automating away a configuration problem you do not have at that scale,
and you would be adding a control plane, a relay, and an IdP to avoid
editing a config you edit twice a year. I covered raw WireGuard
thinking in earlier posts for a reason: it is still the right answer for
the simple case.

Reach for a more established overlay, Tailscale or self-hosted
Headscale, when relay maturity and sheer deployment mileage matter more
to you than NetBird's model. They solve the same problem with a larger
relay footprint and a longer track record. NetBird's edge is the
self-hostable control plane and the clean policy model this series
covered; if those are not what you are optimizing for, the more-trodden
path has fewer surprises.

Use nothing at all when the overlay would be solving a problem your
platform already solved. If every workload lives in one cloud VPC, the
cloud's native networking already gives you private, authenticated
connectivity, and layering a mesh on top is complexity with no payoff.
NetBird earns its place when you are stitching together things that are
genuinely scattered, across clouds, sites, and the random devices in a
homelab, which is exactly the shape this series was written around.
Inside a single network boundary, it is overhead.

Closing the Series

NetBird is a tool I run and recommend, and everything in the first four
parts stands. It is also, like everything, a set of tradeoffs: a
control plane that is a single point of failure for healing, a mesh
that degrades to relayed hub-and-spoke exactly when NAT is hostile, an
agent requirement that routing peers paper over at a cost, and a
self-hosting story that is real infrastructure and not a weekend. None
of that makes it a bad choice. It makes it a choice, which is the only
kind worth making deliberately.

If you reached this part, you have the whole picture: how to deploy it,
how to run it, how to lock it down, how to extend it, and now where it
bites and when to walk away. That is the series I would have wanted
before I started, and it is the one I would trust, because it argues
both sides in the same voice. Use NetBird where it fits the scattered,
multi-site, mixed-device problem it was built for. Use something
simpler, or nothing, where it does not. The tool is good. Knowing when
not to use it is better.