Changing the IPv6 Addresses of Nodes
Why an IPv6 change forces a node redeployment, and the safe sequence for retiring the old node and bringing the replacement online.
A node's IPv6 address is a read-only field in the registry. There is no in-place update path. Changing it requires removing the node from the registry and redeploying the machine as a new node under a new IPv6 address.
[!WARNING] This procedure takes the node out of service. Do not run it on several nodes in the same subnet at the same time. Confirm with the Node Provider Matrix channel before starting, and check that enough healthy nodes remain in every subnet you are touching.
When you need this
The most common trigger is a hardware change — replacing a motherboard, NIC, or HSM — because the IPv6 address derives from machine hardware. Network-side changes (a new IPv6 prefix from the data center, for instance) also force this path.
If only the IPv4 address or domain name changes, use Updating a Node's IPv4 Address and Domain Name instead. That procedure does not require redeployment.
Procedure
Step 1 — Coordinate
Announce the planned change in the Node Provider Matrix channel. Confirm that every subnet hosting one of the affected nodes will still have enough healthy nodes after you remove yours.
Step 2 — Disconnect the nodes
Disconnect the affected nodes from the internet so they cannot re-register automatically once the registry record is gone.
Step 3 — Remove subnet-assigned nodes
For nodes currently assigned to a subnet, use the DRE tool to submit the NNS proposals that remove them from their subnets. Wait for the proposals to adopt and execute before continuing.
Step 4 — Remove the node records
Once the nodes are unassigned, follow Removing a Node From the Registry for each one. This frees the slot in the operator record's allowance.
Step 5 — Redeploy
Redeploy the machines as new nodes. Update the installation USB config file with the new IPv6 prefix, then run the standard deployment per the Gen-2 Node Deployment Guide (or the Gen-1 guide for Gen-1 hardware). The nodes come back under fresh node IDs.
[!NOTE] Reward configuration does not need to change if the total node count under your operator record is unchanged.
Related
- Node Provider Maintenance Guide — the parent runbook.
- Removing a Node From the Registry — the sub-step used here.
- Node Provider Networking Guide — the underlying networking spec.
- Moving a Node Between Data Centers — another procedure that uses node removal.