Enroll a node

Register a Linux host, validate its capabilities, and admit workloads.

Enrollment registers a Linux host with an organization and establishes the agent identity used for control-plane communication.

PrerequisitesCopy link

The host must run a supported Linux distribution with synchronized time, stable storage, and a resolvable hostname. Compute nodes require hardware virtualization, /dev/kvm, QEMU, and the CPU features required by their pool. Nested virtualization must be available when the host is itself a virtual machine.

Assign the region, zone, pool, management address, and node roles before enrolling. Check control-plane connectivity and mesh connectivity separately. Enrollment does not establish all data paths required for droplet traffic or storage replication.

Generate an enrollment tokenCopy link

1. Open Fleet → Nodes → Enroll node.
2. Select the region, zone, pool, and roles.
3. Set a token expiry and restrict enrollment to the intended host count.
4. Download the signed agent package and the generated enrollment configuration.
5. Install the package using the command shown for the host's distribution.

The token is shown once. It grants enrollment only and cannot be used as a console session or API key. Expired, revoked, or exhausted tokens are rejected without registering another identity.

Register the hostCopy link

On the host being enrolled, open the directory containing the downloaded enrollment.yaml file. The enrollment command consumes its control-plane address, trust information, and token:

sudo infra-agent enroll --config ./enrollment.yaml

Start the enrolled agent and enable it at boot:

sudo systemctl enable --now infra-agent

Run the local capability and connectivity checks:

sudo infra-agent doctor

Store the enrollment file with restrictive permissions and remove its token copy after successful registration. enroll persists the issued node identity in the agent state directory. Re-enrollment is not required after a routine service restart.

Validate admissionCopy link

New nodes begin cordoned. Inspect the enrollment operation and resolve every required check before admitting production workloads.

Confirm the registered node ID and organization before changing admission. Verify KVM and the pool's CPU profile, then check host reserve against actual memory and devices.

Check the management path and mesh path independently. The agent can connect while cross-node guest traffic is broken. For a storage role, verify the intended device identities and replication network before initializing a pool.

Finally, compare region, zone, and rack with physical inventory. A misplaced zone label can make a nominally separated replica set depend on the same power or network segment.

Keep production projects excluded from the node's pool during validation. In Fleet → Nodes, select the node and choose Uncordon, then run a test droplet from an authorized validation project. Confirm its private connectivity, volume writes, and fresh metrics.

If a test fails, select Cordon, inspect the test operation and node journal, and repair the reported condition before repeating the checks. After the tests pass, remove the test resources and permit production projects to use the pool.

Reinstall or replace a hostCopy link

A host identity belongs to one registered node. Do not clone the agent state directory into another machine. Duplicate identities are rejected and can cause the original node to report identity conflicts.

For an operating system reinstall, drain the node and save the required configuration before removing its identity. For replacement hardware, enroll a new node and use node replacement. Reusing a display name does not preserve the original resource ID.

Enrollment errorsCopy link

A trust error requires checking the control-plane hostname, certificate chain, and configured CA. A token error requires a fresh token or a corrected scope. A KVM error leaves the node registered but ineligible for compute admission. Use the agent journal and the enrollment operation ID to correlate the failure.

Control-plane and agent certificates documents renewal, issuer rotation, and identity recovery for nodes that missed renewal while offline.