Living Document Notice
Published 2026-09-12. The evolving architecture, revisions, and connected notes for this dispatch live in the Stax Digital Garden.

The Anatomy of a Node Manifest (CPU, storage, PCIe, and network interface YAML schema)

The Anatomy of a Node Manifest (CPU, storage, PCIe, and network interface YAML schema): Emerald green P31 hierarchical node bus lines with warm golden-amber P20 PCIe interface slot diamonds and network bus traces

Summary

Effective node provisioning requires strict hardware definitions before workloads are scheduled. When system capabilities are ambiguously defined, schedulers place memory-intensive or I/O-bound tasks on underpowered hardware. The Quartermaster node manifest formalizes compute, storage, PCIe, and network properties into an explicit, deterministic schema.

Structural Principles of Node Manifests

Hardware provisioning fails when configuration models blur the boundary between physical assets and logical software assignments. A physical network card exists independently of the IP address currently assigned to it. An NVMe drive possesses immutable endurance ratings regardless of which filesystem occupies its partitions.

Quartermaster enforces strict separation by organizing node manifests into dedicated top-level sections: compute, memory, storage, pcie_topology, and networking. Every attribute represents physical properties verifiable through Linux kernel interfaces such as /sys, /proc, and standard PCIe configuration spaces.

By keeping properties typed and deterministic, Quartermaster allows deployment tools to validate target nodes before executing package installs or filesystem writes.

Complete Node Manifest Specification

The definitive YAML specification for a Quartermaster node manifest defines all hardware boundaries required by orchestrators and edge supervisors.

version: "1.0"
node_metadata:
  identifier: "edge-lon-02"
  datacenter: "lon-facility-3"
  rack: "rack-b-04"
  chassis_unit: 14
compute:
  architecture: "x86_64"
  socket_count: 1
  physical_cores: 8
  threads_per_core: 2
  flags:
    - "aes"
    - "vmx"
  l3_cache_kb: 11264
memory:
  installed_bytes: 34359738368
  ecc_enabled: true
  form_factor: "DDR4-RDIMM"
  memory_nodes: 1
storage:
  block_devices:
    - path: "/dev/nvme0n1"
      type: "nvme"
      transport: "pcie"
      sector_size_bytes: 512
      size_bytes: 1000204886016
      wear_rating_tbw: 600
    - path: "/dev/sda"
      type: "sata-ssd"
      transport: "sata"
      sector_size_bytes: 512
      size_bytes: 500107862016
      wear_rating_tbw: 300
pcie_topology:
  slots:
    - address: "0000:00:1c.0"
      lane_width: 4
      max_link_speed: "8.0 GT/s"
      device_class: "Mass storage controller"
    - address: "0000:03:00.0"
      lane_width: 8
      max_link_speed: "8.0 GT/s"
      device_class: "Ethernet controller"
networking:
  ports:
    - logical_name: "eth0"
      pci_bus_address: "0000:03:00.0"
      mac_address: "00:25:90:ed:44:a2"
      link_speed_gbps: 10
      supported_mtu: 9000
      interface_type: "sfp+"
    - logical_name: "eth1"
      pci_bus_address: "0000:03:00.1"
      mac_address: "00:25:90:ed:44:a3"
      link_speed_gbps: 10
      supported_mtu: 9000
      interface_type: "sfp+"

Attribute Validation Rules

Every node manifest passes through strict validation before acceptance into the cluster inventory. The parser rejects unknown keys and enforces type constraints.

Manifest Path	Data Type	Physical Verification Source	Validation Constraint
`compute.physical_cores`	integer	`/sys/devices/system/cpu/cpu*/topology/core_id`	Positive integer matching unique core IDs
`compute.flags`	list[str]	`/proc/cpuinfo` feature flags	Standard Linux kernel CPU capability strings
`memory.installed_bytes`	integer	`/proc/meminfo` or `dmidecode -t memory`	Exact byte count, multiple of 1073741824
`storage.block_devices[].wear_rating_tbw`	integer	Manufacturer engineering datasheet	Value greater than zero for SSD block devices
`pcie_topology.slots[].address`	string	`lspci -D` bus domain notation	Regex: `^[0-9a-f]{4}:[0-9a-f]{2}:[0-9a-f]{2}\.[0-7]$`
`networking.ports[].mac_address`	string	`/sys/class/net/<iface>/address`	Regex: `^([0-9a-f]{2}:){5}[0-9a-f]{2}$`

PCIe Topology and Interrupt Routing

A major source of performance degradation in low-power servers is unaligned interrupt handling across CPU cores. When a 10GbE network interface or NVMe storage controller routes interrupts to CPU cores located across a memory bus or on a separate NUMA socket, memory latency increases noticeably.

The Quartermaster manifest documents physical bus addresses to establish strict CPU core pinning and interrupt request (IRQ) balance rules.

Bus Address	Device Class	Subsystem ID	IRQ Affinity Mask	Assigned NUMA Domain
`0000:00:1c.0`	Root Port	`0x0821`	`0x0000000f`	Node 0 (Cores 0-3)
`0000:03:00.0`	10GbE SFP+	`0x1528`	`0x000000f0`	Node 0 (Cores 4-7)
`0000:04:00.0`	NVMe Controller	`0xa808`	`0x0000ff00`	Node 0 (Cores 8-15)

Strict Manifest Validation Execution

Validation executes locally or in CI pipelines using the Quartermaster schema validator. The tool parses YAML, resolves references, and compares declared values against operating system interfaces.

# Validate manifest structure against the formal schema specification
quartermaster-cli manifest lint   --schema /etc/quartermaster/schemas/v1/node.json   --file /etc/quartermaster/nodes/edge-lon-02.yaml   --strict
 
# Execute live node hardware verification against kernel sysfs
quartermaster-cli manifest verify   --file /etc/quartermaster/nodes/edge-lon-02.yaml   --sysfs-root /sys   --proc-root /proc

Directus Target: quartermaster
Garden Source Reference: MOC - Fleet Operations
Garden Source Reference: MOC - Bosun PKM Tools
Garden Source Reference: [QTM-1003 - The Anatomy of a Node Manifest (CPU, storage, PCIe, and network interface YAML schema)](QTM-1003 - The Anatomy of a Node Manifest (CPU, storage, PCIe, and network interface YAML schema))

Stax Digital Garden

Explorer

QTM-1003 - The Anatomy of a Node Manifest (CPU, storage, PCIe, and network interface YAML schema)