Migrating a Node Operator Record

A node operator is a principal authorised to manage a set of nodes that belong to a given node provider in a given data center. Over time a provider can end up with several legacy operator records, need to retire the HSM that holds an operator key, or want to rotate that key for security. Node operator migration folds one operator record into another: it repoints every node and moves all of the allowance onto the target record, atomically, in the registry. No NNS proposal is required, and no hardware is restarted or relocated — only the registry records change.

[!NOTE] Migration is a direct registry call, not a governance action. It is authenticated by the node provider that owns the records, and it takes effect immediately once accepted.

When to use this

• HSM retirement or replacement — move the nodes off an operator key held on a device you are decommissioning.
• Consolidating legacy records — collapse several old operator records under a single principal.
• Key rotation — move nodes onto a freshly generated operator key for security.

Before you start

The migration is subject to ownership, locality, and timing rules:

• Only the node provider that owns the records can initiate the migration.
• If the new (target) operator record already exists, it must belong to the same node provider.
• Both records must reside in the same data center (matching dc_id).
• The old operator record must have existed for at least 12 hours. This is a spam-prevention measure, so a record cannot be created and immediately migrated away.

Procedure

Step 1 — Identify the two operator principals

Note the principal of the old node operator record (the one being emptied) and the principal of the new node operator record that will own the nodes afterwards.

Step 2 — Set up authentication

Define an AUTH array with the node provider key that owns the operator records. Use a PEM key file:

AUTH=(
  "--secret-key-pem"
  <path-to-key-pem>
)

or an HSM:

AUTH=(
  "--use-hsm"
  "--slot"
  <hsm-key-slot>
  "--key-id"
  <hsm-key-id>
  "--pin"
  <hsm-pin>
)

Step 3 — Execute the migration

Run migrate-node-operator-directly, passing the old and new operator principals from step 1:

ic-admin --nns-urls https://ic0.app ${AUTH[@]} migrate-node-operator-directly \
  --old-node-operator-id <old-node-operator-principal> \
  --new-node-operator-id <new-node-operator-principal>

What the migration changes

The registry update is atomic. On success:

• Every node record whose node_operator_id matched the old record is repointed to the new operator principal.
• The new operator record is created or updated with the combined node_allowance, rewardable_nodes, and max_rewardable_nodes of both records.
• The old operator record is deleted.

The nodes themselves are untouched — nothing restarts, and no machine moves.

Verification

Confirm on the IC Dashboard↗ that the affected nodes now list the new node operator, that the allowance has carried over, and that the old operator record no longer appears.

Related

• Node Provider Maintenance Guide — the parent runbook.
• Changing the Node Provider or Data-Center Principal — the proposal-based flow for replacing a lost provider principal or operator HSM.
• Node Provider Documentation — the role overview and the node operator concept.
• Removing a Node From the Registry — retiring nodes rather than moving them to another operator.