Diff: how-to/add-a-fleet-node.es
From 1c02ec1 to 1c02ec1
+0 / −0 lines
| Before | After |
|---|---|
| --- | --- |
| schema: foundry-doc-v1 | schema: foundry-doc-v1 |
| title: "How to add a node to a running fleet" | title: "How to add a node to a running fleet" |
| slug: add-a-fleet-node | slug: add-a-fleet-node |
| category: how-to | category: how-to |
| content_type: how-to | content_type: how-to |
| type: how-to | type: how-to |
| status: active | status: active |
| last_edited: 2026-06-14 | last_edited: 2026-06-14 |
| editor: pointsav-engineering | editor: pointsav-engineering |
| paired_with: add-a-fleet-node.es.md | paired_with: add-a-fleet-node.es.md |
| --- | --- |
| A running fleet has one or more PPN nodes already enrolled and actively sending heartbeats. Adding a node to a running fleet means enrolling a new machine without interrupting the existing nodes' operation. This guide covers the steps specific to adding to an active fleet, as opposed to enrolling the very first node. | A running fleet has one or more PPN nodes already enrolled and actively sending heartbeats. Adding a node to a running fleet means enrolling a new machine without interrupting the existing nodes' operation. This guide covers the steps specific to adding to an active fleet, as opposed to enrolling the very first node. |
| For the initial node enrollment procedure, see [[enroll-ppn-node]]. For the fleet controller service, see [[service-vm-fleet]]. | For the initial node enrollment procedure, see [[enroll-ppn-node]]. For the fleet controller service, see [[service-vm-fleet]]. |
| ## Prerequisites | ## Prerequisites |
| - At least one node already enrolled and the fleet controller running (see [[enroll-ppn-node]]) | - At least one node already enrolled and the fleet controller running (see [[enroll-ppn-node]]) |
| - A second machine prepared with `service-vm-host` installed | - A second machine prepared with `service-vm-host` installed |
| - A new unique `NODE_ID` that does not conflict with any existing node in the tenant namespace | - A new unique `NODE_ID` that does not conflict with any existing node in the tenant namespace |
| ## Step 1: Verify the fleet controller's current state | ## Step 1: Verify the fleet controller's current state |
| Before adding a node, confirm the existing fleet is healthy: | Before adding a node, confirm the existing fleet is healthy: |
| ``` | ``` |
| curl -s "http://<fleet-controller-host>:9203/v1/vms?tenant_id=<your-tenant-id>" | curl -s "http://<fleet-controller-host>:9203/v1/vms?tenant_id=<your-tenant-id>" |
| ``` | ``` |
| All existing nodes should show a recent `last_heartbeat` timestamp (within the last 60 seconds under default settings). A node showing a stale heartbeat has a connectivity problem — resolve it before adding a new node to avoid confusing the advisory placement algorithm. | All existing nodes should show a recent `last_heartbeat` timestamp (within the last 60 seconds under default settings). A node showing a stale heartbeat has a connectivity problem — resolve it before adding a new node to avoid confusing the advisory placement algorithm. |
| ## Step 2: Choose a node ID that does not conflict | ## Step 2: Choose a node ID that does not conflict |
| The fleet controller rejects duplicate `NODE_ID` values within a tenant namespace. List the current IDs: | The fleet controller rejects duplicate `NODE_ID` values within a tenant namespace. List the current IDs: |
| ``` | ``` |
| curl -s "http://<fleet-controller-host>:9203/v1/vms?tenant_id=<your-tenant-id>" \ | curl -s "http://<fleet-controller-host>:9203/v1/vms?tenant_id=<your-tenant-id>" \ |
| | jq '.[].node_id' | | jq '.[].node_id' |
| ``` | ``` |
| Pick an ID for the new node that follows the naming pattern of existing nodes (e.g., if existing nodes are `compute-west-01` and `compute-west-02`, name the new one `compute-west-03`). | Pick an ID for the new node that follows the naming pattern of existing nodes (e.g., if existing nodes are `compute-west-01` and `compute-west-02`, name the new one `compute-west-03`). |
| ## Step 3: Configure and start the heartbeat agent on the new machine | ## Step 3: Configure and start the heartbeat agent on the new machine |
| On the new machine, set the configuration and start `service-vm-host`: | On the new machine, set the configuration and start `service-vm-host`: |
| ``` | ``` |
| FLEET_CONTROLLER_URL=http://<fleet-controller-host>:9203 | FLEET_CONTROLLER_URL=http://<fleet-controller-host>:9203 |
| TENANT_ID=<your-tenant-id> | TENANT_ID=<your-tenant-id> |
| NODE_ID=<new-unique-id> | NODE_ID=<new-unique-id> |
| service-vm-host --controller $FLEET_CONTROLLER_URL --tenant $TENANT_ID --node-id $NODE_ID | service-vm-host --controller $FLEET_CONTROLLER_URL --tenant $TENANT_ID --node-id $NODE_ID |
| ``` | ``` |
| The agent registers on its first heartbeat. The fleet controller updates its advisory placement data automatically — no restart of the controller or other nodes is required. | The agent registers on its first heartbeat. The fleet controller updates its advisory placement data automatically — no restart of the controller or other nodes is required. |
| ## Step 4: Verify the new node appears in the fleet | ## Step 4: Verify the new node appears in the fleet |
| Query the fleet again and confirm the new node appears alongside the existing ones: | Query the fleet again and confirm the new node appears alongside the existing ones: |
| ``` | ``` |
| curl -s "http://<fleet-controller-host>:9203/v1/vms?tenant_id=<your-tenant-id>" | curl -s "http://<fleet-controller-host>:9203/v1/vms?tenant_id=<your-tenant-id>" |
| ``` | ``` |
| The response should now include the new node with a `last_heartbeat` from within the last 60 seconds. | The response should now include the new node with a `last_heartbeat` from within the last 60 seconds. |
| ## Step 5: Confirm load distribution | ## Step 5: Confirm load distribution |
| The fleet controller's advisory placement algorithm balances new tenant VM placements across healthy nodes. After adding a node, submit a new VM placement request and verify the controller considers the new node as a candidate: | The fleet controller's advisory placement algorithm balances new tenant VM placements across healthy nodes. After adding a node, submit a new VM placement request and verify the controller considers the new node as a candidate: |
| ``` | ``` |
| curl -s "http://<fleet-controller-host>:9203/v1/placement?tenant_id=<your-tenant-id>" | curl -s "http://<fleet-controller-host>:9203/v1/placement?tenant_id=<your-tenant-id>" |
| ``` | ``` |
| The response suggests a target node based on current capacity. If the new node does not appear as a candidate, check that its reported capacity fields are populated (memory, CPU) in the heartbeat data. | The response suggests a target node based on current capacity. If the new node does not appear as a candidate, check that its reported capacity fields are populated (memory, CPU) in the heartbeat data. |
| ## Key takeaways | ## Key takeaways |
| - The fleet controller accepts new nodes without requiring existing nodes to restart | - The fleet controller accepts new nodes without requiring existing nodes to restart |
| - Duplicate `NODE_ID` values within a tenant namespace are rejected — verify current IDs before choosing one | - Duplicate `NODE_ID` values within a tenant namespace are rejected — verify current IDs before choosing one |
| - Advisory placement updates automatically when a new node's first heartbeat arrives | - Advisory placement updates automatically when a new node's first heartbeat arrives |
| - A stale heartbeat from existing nodes should be resolved before adding new nodes to avoid placement skew | - A stale heartbeat from existing nodes should be resolved before adding new nodes to avoid placement skew |
| ## See also | ## See also |
| - [[enroll-ppn-node]] — enrolling the first node in a fleet from scratch | - [[enroll-ppn-node]] — enrolling the first node in a fleet from scratch |
| - [[service-vm-fleet]] — the fleet controller service that manages node inventory and advisory placement | - [[service-vm-fleet]] — the fleet controller service that manages node inventory and advisory placement |
| - [[configure-tenant-namespace]] — the namespace that contains the fleet's nodes | - [[configure-tenant-namespace]] — the namespace that contains the fleet's nodes |
| - [[ppn-small-business-compute]] — the fleet architecture and the role of each node tier | - [[ppn-small-business-compute]] — the fleet architecture and the role of each node tier |
| - [[verify-worm-ledger]] — confirming that node enrollment events are permanently recorded | - [[verify-worm-ledger]] — confirming that node enrollment events are permanently recorded |