Preflight Check
Automatic infrastructure checks and live validation before marketplace listing
After plans and addons are created, NodeRings must confirm your infrastructure can actually sell them. This happens in two stages:
- Preflight checks: automatic inventory and health gates that run on a schedule
- Live validation: an on-demand end-to-end test that provisions a pilot VM on each plan × node pair
Both must pass before a plan appears in the marketplace. If preflight finds a problem, the plan is hidden from customers until you fix it. Passing preflight alone is not enough. You still need a successful live validation run on every sell-path node.
Open the dashboard at /infrastructure/preflight-check.
For a walkthrough with screenshots, see Get started → Preflight check.
What preflight checks do
Preflight is automatic. NodeRings re-evaluates your plans on a recurring schedule (typically every few minutes). No manual trigger is required.
Each row in the preflight matrix is one plan × node combination in a sell region. The dashboard shows whether that pair is Ready, Blocked, or Pending.
| Outcome | Marketplace visibility |
|---|---|
| All gates green | Plan can list after live validation passes on that node |
| Any gate red | Plan is removed from marketplace search until the blocker is fixed |
| Pending | Checks still running or waiting for fresh data |
When something breaks later (agent offline, IP pool exhausted, node in maintenance), the next preflight cycle catches it and the plan stops appearing in search until the issue is resolved.
What gets checked
Checks run at plan level first, then per candidate node on the sell path (agent → platform → node).
Reading the preflight table
The main matrix matches the dashboard columns. Each plan row shows billing type, then one cell per gate:
| Dashboard column | Preflight gate | What it means |
|---|---|---|
| Addon | addons_created | Required addons exist with billing type matching the plan |
| Agent | agent_online | Sell-path agent connected |
| Platform | platform_online | Hypervisor API reachable (pve_up=1) |
| Node | node_online | Node active, in region, network attached; summary shows N/N passed |
| Physical fit | plan_physical_fit | Node has enough real CPU, RAM, and VM disk storage for one instance of the plan |
| Sell capacity | plan_capacity | Node still has sell headroom after overallocation (sold + plan ≤ limit) |
| IP Avail. | ip_available | Enough assignable IPv4/IPv6 in the guest pool |
| OS | os_template | Required VM templates on the node |
Physical fit and Sell capacity are separate columns. Do not confuse them. A node can pass one and fail the other.
Click a plan row to open the detail sidebar. It shows plan checks, per-node status, and the infrastructure path (for example agent01 → platform1 → proxmox01-lab01-dev). Green Ready with “No blockers; plan is marketplace ready” means all preflight gates passed for that plan.
Physical fit vs sell capacity
These answer different questions. The dashboard shows them as two columns in the preflight matrix.
Physical fit (plan_physical_fit)
Question: Can this node run one VM of this plan size on real hardware?
NodeRings compares the plan’s vCPU, RAM, and disk against the node’s physical CPU cores, installed RAM, and VM disk storage pool (from metrics). No overallocation math: if the plan is bigger than the hardware, Physical fit fails even when nothing is sold yet.
Example: a 16 vCPU / 64 GB RAM / 500 GB disk plan needs a node with ≥ 16 physical cores, ≥ 64 GB RAM, and ≥ 500 GB on its configured VM disk storage. An 8-core / 32 GB node fails Physical fit for that plan regardless of overallocation settings.
Sell capacity (plan_capacity)
Question: With what you have already sold on this node, is there still room to sell one more instance under your overallocation limits?
NodeRings checks: sold + plan size ≤ physical × overallocation% for CPU and memory. This is about inventory headroom, not whether a single instance could ever fit on bare metal.
Example: an 8-core node at 200% CPU overallocation can sell up to 16 vCPU in total across all VMs. If you already sold 16 vCPU, Sell capacity fails for another 8 vCPU plan, even though Physical fit might still pass for an 8 vCPU plan on that hardware.
Side by side
| Physical fit | Sell capacity | |
|---|---|---|
| Dashboard column | Physical fit | Sell capacity |
| Asks | Can one instance fit on real hardware? | Is there sell headroom after what’s already sold? |
| Uses overallocation | No | Yes |
| Includes disk | Yes (VM storage pool) | No (CPU + RAM only) |
| Typical fix | Bigger node, smaller plan, or more VM disk storage | Free capacity, raise overallocation, or sell fewer VMs on the node |
Both must be green for the plan × node row to pass preflight.
Plan-level checks (detail)
| Check | What it verifies |
|---|---|
| addons_created | Required addons exist with billing type matching the plan |
| plan_regions | Plan sell regions have at least one platform/node |
| cloud_init_template | Org cloud-init templates in use on a VM template (compile + valid YAML) |
Per-node checks (detail)
| Check | Dashboard column | What it verifies |
|---|---|---|
| agent_online | Agent | Node agent connected and reporting |
| platform_online | Platform | Hypervisor API reachable (pve_up=1) |
| node_online | Node | Node active, not in maintenance, in plan region, network attached |
| plan_physical_fit | Physical fit | Real CPU, RAM, and VM disk storage ≥ one plan instance |
| plan_capacity | Sell capacity | Sell headroom after overallocation (not the same as physical fit) |
| os_template | OS | Required VM templates and marketplace OS images on the node |
| ip_available | IP Avail. | Guest network has enough assignable IPv4 and IPv6 (see IPAM minimums) |
Live validation
Preflight proves inventory and connectivity exist. Live validation proves NodeRings can actually provision and operate a VM end to end on a specific node.
Live validation is required for marketplace listing and is not automatic. After preflight is green, you must click Start validation for each plan × node you want to sell. Until at least one sell-region node passes both preflight and live validation, the plan stays unpublished.
You run live validation manually, once per plan × node pair you want to sell on. Click Start validation, choose the plan and node, and optionally enable Include hardware benchmarks.
Choose plan and node
Only marketplace-eligible nodes appear. The plan badge shows how many nodes are already validated (for example 0/1 validated).
Wait for the pilot VM run
NodeRings provisions a short-lived VM, runs checks, then tears it down. Status progresses through phases such as Running (provision) until complete.
Confirm Validated: Yes
A plan appears on the marketplace only when at least one node in a sell region has passed both preflight and live validation.
Live validation checks
| Check | What it verifies |
|---|---|
| marketplace_eligible_node | Node passed preflight infrastructure gates |
| vm_created | Operator clones a template and creates the VM |
| ips_assigned | Static IPv4 and IPv6 assigned from IPAM |
| ssh_key_injected | Benchmark SSH key injected (when benchmarking enabled) |
| ping_ipv4 / ping_ipv6 | Guest addresses reachable from the platform |
| ssh_login | SSH accepts connections after cloud-init (when benchmarking enabled) |
| power_stop_start | VM survives a stop/start cycle |
| metrics | Pilot VM visible in monitoring |
| benchmark_script | Optional CPU, memory, disk, and network benchmark (see below) |
| check_cleanup | Pilot VM removed after the run |
Expand a completed run to see each gate and assigned IPs.
Hardware benchmarks
When you enable Include hardware benchmarks, live validation SSHes into the pilot VM and runs noderings-benchmark: CPU, memory, disk I/O, and network throughput.
NodeRings stores these scores with the validation run. They help marketplace search rank plans by measured performance, not just list price.
Repository: github.com/noderings/noderings-benchmark
curl -fsSL -o nr-liveval.sh \
https://raw.githubusercontent.com/noderings/noderings-benchmark/main/nr-liveval.sh
chmod +x nr-liveval.sh
sudo ./nr-liveval.shYou can run the same script on any Linux guest to reproduce what live validation exercises during the benchmark step.
Marketplace listing checklist
| Step | Automatic? | Required for search? |
|---|---|---|
| Preflight checks pass | Yes; recurring | Yes |
| Live validation passes (per plan × node) | No; you start each run | Yes |
| Hardware benchmarks (optional) | Part of live validation when enabled | No, but recommended for search ranking |
Using the dashboard
Open preflight check
Go to /infrastructure/preflight-check. Review the summary counts: Plans, Ready, Blocked, Pending.
Fix red gates
Click a failing row or gate. The dashboard links to the fix location (agent, node, IPAM, addons, etc.). After each change, wait for the next preflight cycle or refresh until the row is green.
Run live validation
Scroll to Live validation, click Start validation, pick plan and node, and run. Repeat for every plan × node pair you sell.
Related
- Get started → Preflight check: screenshots and onboarding walkthrough
- Plans & Addons: create and price plans before validation
- Troubleshooting → Preflight: quick fixes for red gates