Nebula certificate reload did not change the IP: here is why

You issue a new host certificate with a different overlay address, copy it over the old file, send the reload, and the host keeps answering on the address it had before. The reflex is to assume the reload failed or that the wrong file was read. Usually neither happened: the running process deliberately kept the identity it already had, because the replacement changed something a reload cannot apply.

Nebula's PKI reload support is documented with that boundary, and it is easy to miss when the same documentation shows reload working for other changes.

What a reload actually re-reads

A host certificate is not just a credential in the way an SSH key is. It carries the overlay address, the host name, the group memberships and a validity window, and all of those are bound together by the CA's signature. The daemon uses that signed content to decide how it presents itself and which rules apply to it.

Reloading lets the process pick up a renewed credential without dropping its tunnels, which is valuable for routine rotation: same address, same name, same groups, later expiry. The constraint is that the identity has to stay the same. Change the overlay address and the reload path cannot apply it, because the address is part of what the running instance already committed to.

So the behaviour you saw is the documented limit doing its job, not a silent failure. The file on disk is new; the identity in memory is old; the process has no supported way to reconcile that difference without a restart.

Address, name and groups are one identity

It helps to think of the certificate as a single record rather than a set of fields you can edit independently. Moving the address is not like changing a preference, because the address appears in other hosts' peer configurations, in service bindings, and in policies written against the identity.

Groups deserve their own line because they cause a quieter version of the same confusion. A host that keeps its address but moves groups can reach different services after a restart, and a test that only pings the old address will look completely healthy while access decisions have changed underneath it. Check one ruled service, not only reachability. That is the difference between confirming the tunnel and confirming the policy.

Compare the loaded certificate with the replacement

Before assuming the daemon ignored the file, read both. Print the certificate you intend to load and confirm the fields you think you changed, then confirm that the running configuration points at that path rather than at a copy somewhere else.

nebula-cert print -path /etc/nebula/host.crt
systemctl status nebula
ps -o args= -p $(pgrep -f 'nebula -config' | head -1)

The process arguments matter more than people expect. A unit that passes -config /etc/nebula/config.yml is reading that file's pki.cert entry, and a certificate installed in a staging directory affects nothing. Check the path in the running command line, not the path in the documentation you followed. If the two differ, you have found the problem without touching the certificate at all.

If the new certificate has a different address and the process kept the old one, you now have an explanation rather than a mystery. Restart it if that is acceptable, and treat the address change as a planned network change rather than an accidental one.

An address change is a network change

Plan it the way you would plan moving a machine. Other hosts may have pinned the old address in their configuration, services may bind to it explicitly, and firewall rules may be written against it. Changing the certificate moves the host, and moving the host invalidates assumptions elsewhere.

Keep a second management path available while you do it, because the overlay connection may be the one you are interrupting. Doing this over the tunnel you are about to break is the classic way to turn a five-minute change into a site visit.

Whether a restart is acceptable depends on what the host is doing, and that is a scheduling question rather than a technical one. What is not optional is acknowledging the restart requirement instead of sending the reload a fifth time.

Retire the old credential separately

Installing a replacement on a single machine leaves every peer still trusting the credential it already knows about. If the reason for the change was a compromise, the old identity has to be retired through the trust or blocklist procedure so peers actually reject it.

That is a distinct step with its own verification: confirm from another host that the old identity no longer works, rather than assuming the new file did the job. The Nebula PKI configuration documentation covers the reloadable settings and the address limitation described here, and it is worth reading in full before you rotate anything production-facing.