Diff: how-to/enroll-ppn-node.es
From 1c02ec1 to 1c02ec1
+0 / −0 lines
| Before | After |
|---|---|
| --- | --- |
| schema: foundry-doc-v1 | schema: foundry-doc-v1 |
| title: "How to enroll a PPN node" | title: "How to enroll a PPN node" |
| slug: enroll-ppn-node | slug: enroll-ppn-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: enroll-ppn-node.es.md | paired_with: enroll-ppn-node.es.md |
| --- | --- |
| A PPN (PointSav Private Network) node is a physical or virtual machine that joins the platform's compute fleet. Enrolling a node means registering it with the fleet controller, starting the heartbeat agent, and verifying the node appears in the fleet's active inventory. This guide covers the enrollment sequence for a single node. | A PPN (PointSav Private Network) node is a physical or virtual machine that joins the platform's compute fleet. Enrolling a node means registering it with the fleet controller, starting the heartbeat agent, and verifying the node appears in the fleet's active inventory. This guide covers the enrollment sequence for a single node. |
| For the fleet architecture, see [[ppn-small-business-compute]]. For the service that manages fleet state, see [[service-vm-fleet]]. | For the fleet architecture, see [[ppn-small-business-compute]]. For the service that manages fleet state, see [[service-vm-fleet]]. |
| ## Prerequisites | ## Prerequisites |
| - A machine with network access to the fleet controller endpoint | - A machine with network access to the fleet controller endpoint |
| - The `service-vm-host` binary deployed on the node (the per-node heartbeat agent) | - The `service-vm-host` binary deployed on the node (the per-node heartbeat agent) |
| - The fleet controller address and tenant ID provided by the platform administrator | - The fleet controller address and tenant ID provided by the platform administrator |
| - A terminal session on the node being enrolled | - A terminal session on the node being enrolled |
| ## Step 1: Verify the fleet controller is reachable | ## Step 1: Verify the fleet controller is reachable |
| From the node, confirm the fleet controller responds before starting the heartbeat agent: | From the node, confirm the fleet controller responds before starting the heartbeat agent: |
| ``` | ``` |
| curl -s http://<fleet-controller-host>:9203/health | curl -s http://<fleet-controller-host>:9203/health |
| ``` | ``` |
| A successful response returns `{"status":"ok"}`. If the controller is unreachable, verify network routing and firewall rules before proceeding. Enrollment requires a live connection to the controller. | A successful response returns `{"status":"ok"}`. If the controller is unreachable, verify network routing and firewall rules before proceeding. Enrollment requires a live connection to the controller. |
| ## Step 2: Configure the heartbeat agent | ## Step 2: Configure the heartbeat agent |
| The `service-vm-host` heartbeat agent reads its configuration from environment variables or a local config file. Set the minimum required values: | The `service-vm-host` heartbeat agent reads its configuration from environment variables or a local config file. Set the minimum required values: |
| ``` | ``` |
| 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=<unique-node-name> | NODE_ID=<unique-node-name> |
| ``` | ``` |
| `NODE_ID` must be unique within the tenant's namespace. Use a descriptive name that identifies the machine's role and location (e.g., `compute-west-01`). Once set, this identifier appears in the fleet inventory and in the WORM audit ledger. | `NODE_ID` must be unique within the tenant's namespace. Use a descriptive name that identifies the machine's role and location (e.g., `compute-west-01`). Once set, this identifier appears in the fleet inventory and in the WORM audit ledger. |
| ## Step 3: Start the heartbeat agent | ## Step 3: Start the heartbeat agent |
| Start `service-vm-host` as a systemd service or directly from the command line: | Start `service-vm-host` as a systemd service or directly from the command line: |
| ``` | ``` |
| 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 sends an initial heartbeat immediately and then on its configured interval (default: 30 seconds). The first successful heartbeat registers the node with the fleet controller. | The agent sends an initial heartbeat immediately and then on its configured interval (default: 30 seconds). The first successful heartbeat registers the node with the fleet controller. |
| ## Step 4: Verify enrollment in the fleet inventory | ## Step 4: Verify enrollment in the fleet inventory |
| From a session with access to the fleet controller API, query the fleet for the new node: | From a session with access to the fleet controller API, query the fleet for the new node: |
| ``` | ``` |
| 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 includes an array of enrolled nodes. Find the entry for the `NODE_ID` you set in step 2. The entry shows `status`, `last_heartbeat`, and resource capacity fields populated from the first heartbeat. | The response includes an array of enrolled nodes. Find the entry for the `NODE_ID` you set in step 2. The entry shows `status`, `last_heartbeat`, and resource capacity fields populated from the first heartbeat. |
| If the node does not appear within 60 seconds of starting the agent, check the agent logs for connection errors. The most common causes are a wrong controller URL or a firewall blocking outbound connections on port 9203. | If the node does not appear within 60 seconds of starting the agent, check the agent logs for connection errors. The most common causes are a wrong controller URL or a firewall blocking outbound connections on port 9203. |
| ## Step 5: Confirm the ledger entry | ## Step 5: Confirm the ledger entry |
| Every heartbeat writes a WORM ledger entry. From the fleet controller or from `service-fs`, confirm a ledger record exists for the new node: | Every heartbeat writes a WORM ledger entry. From the fleet controller or from `service-fs`, confirm a ledger record exists for the new node: |
| ``` | ``` |
| service-fs read --filter node-id=<NODE_ID> --limit 5 | service-fs read --filter node-id=<NODE_ID> --limit 5 |
| ``` | ``` |
| A successful enrollment produces at least one `NODE_HEARTBEAT` entry. The ledger entry is the permanent enrollment record — it cannot be deleted or altered. | A successful enrollment produces at least one `NODE_HEARTBEAT` entry. The ledger entry is the permanent enrollment record — it cannot be deleted or altered. |
| ## Key takeaways | ## Key takeaways |
| - Enrollment happens on first heartbeat; no separate registration step is needed | - Enrollment happens on first heartbeat; no separate registration step is needed |
| - `NODE_ID` must be unique per tenant namespace; the fleet controller rejects duplicates | - `NODE_ID` must be unique per tenant namespace; the fleet controller rejects duplicates |
| - A WORM ledger entry is created for every heartbeat — enrollment is permanently recorded | - A WORM ledger entry is created for every heartbeat — enrollment is permanently recorded |
| - If the node does not appear after 60 seconds, check the agent logs before assuming a network problem | - If the node does not appear after 60 seconds, check the agent logs before assuming a network problem |
| ## See also | ## See also |
| - [[ppn-small-business-compute]] — the PPN fleet architecture and tenant model | - [[ppn-small-business-compute]] — the PPN fleet architecture and tenant model |
| - [[service-vm-fleet]] — the fleet controller service that manages enrolled nodes | - [[service-vm-fleet]] — the fleet controller service that manages enrolled nodes |
| - [[add-a-fleet-node]] — how to add a node to a running multi-node fleet (operational follow-on) | - [[add-a-fleet-node]] — how to add a node to a running multi-node fleet (operational follow-on) |
| - [[verify-worm-ledger]] — verifying the ledger entries created during enrollment | - [[verify-worm-ledger]] — verifying the ledger entries created during enrollment |
| - [[pair-a-new-device]] — the pairing protocol that governs device-level access tiers | - [[pair-a-new-device]] — the pairing protocol that governs device-level access tiers |