Nebula advertise_addrs or static_host_map: choose by owner

The static_host_map and advertise_addrs settings both put an address in front of a peer, and they answer different questions. One is a local file listing an overlay address and the underlay endpoint to dial. The other is a host telling its lighthouses which additional endpoints can reach it. Ownership is the real difference: the map is maintained by everyone who needs it, the advertisement by the host itself.

Decide by who owns the information

Every changing peer in every peer's static file is a maintenance job that grows with the square of the fleet. That is the practical reason to reach for the other setting whenever the host itself knows the answer.

The ownership question also predicts what happens when an address changes. With a static map, someone has to remember every peer that holds the old entry. With an advertisement, the host publishes the new endpoint and its lighthouses pass it on, so the change stays local to the machine that moved.

Bootstrap still needs static entries

A client must reach at least one lighthouse before it can ask anyone about other peers. That first hop cannot come from discovery, so it comes from a static entry in the client's configuration. Get that one entry right and the rest of the overlay can be learned.

A map entry pairs a Nebula address with one or more reachable IP or DNS endpoints and ports. Keeping the lighthouses there is normal; keeping every peer there is the pattern that ages badly, because each new peer means editing files on machines you may not control. Keep the list short enough that a person can still verify it by reading it.

Advertise when the host knows the endpoint

A host behind port forwarding is reachable at a public address that is not assigned to any of its own interfaces. It cannot discover that address by looking at itself. advertise_addrs lets it publish the endpoint through its lighthouses so that other peers learn a path that actually works. The setting exists precisely because the host is the only party that knows the mapping was made.

Use the address and port that other peers can genuinely reach. The same reasoning applies to a host with several network paths, where one path is preferable for peers on a particular network. Advertising is a statement about the underlay, not a request for anything. When the mapping changes, update the advertisement at the host and let discovery carry it, instead of editing static files across the fleet.

Advertising is not reachability

Publishing an endpoint does not create the router's forwarding rule, open an upstream firewall, or make a DNS name resolve. Those are separate pieces of work, and a correct advertisement with a missing port forward produces exactly the failure you were trying to fix. Advertising is a claim about reachability, not a mechanism that establishes it.

Check the path from outside before blaming discovery. A peer that learns the endpoint but cannot complete a handshake has a routing or filtering problem on the underlay, and repeating the same address in both settings will not change that.

Keep the overlay address distinct from the endpoint

The node's certificate identifies its Nebula address. The advertised addresses belong to the underlying network, and they are allowed to change without touching the certificate. Issuing a new certificate with a different overlay IP is a different operation, with its own consequences for every trust relationship that pinned the old one. Keep the two changes separate in the runbook, or an endpoint move will be recorded as a re-issue.

When triage stalls, separate the two layers explicitly: does discovery return the expected endpoint, and does a handshake reach it? If discovery is right and packets fail, the problem is below the overlay. If discovery is wrong, the problem is in the map or the advertisement, and the fix belongs there.