Knowledge Vault

Hardware capacity documentation

2 min read

Hardware capacity documentation

Capacity documentation must reflect actual deployed infrastructure, not theoretical or initial estimates.

Context

Infrastructure documentation often includes capacity requirements (CPU, RAM, disk) for planning and provisioning. These numbers can become stale as infrastructure evolves, leading to under-provisioned systems or misleading expectations.

Problem

# README.md - WRONG: Outdated capacity documentation
 
## Requirements
 
- CPU: 7 cores
- RAM: 14 GB
 
# Reality after adding Library repos:
 
# - 7 runners × 2 cores = 14 cores needed
 
# - 7 runners × 4 GB = 28 GB RAM needed
 
# - Documentation is 50% of actual requirements!

The original documentation assumed 3 runners at 2 cores and 4 GB each. When 4 more runners were added for Library repos, the documentation wasn’t updated, leaving it dramatically understated.

Solution

  1. Document capacity calculation, not just totals:
## Capacity Requirements
 
### Per-Runner Resources
 
- CPU: 2 cores
- RAM: 4 GB
- Disk: 20 GB
 
### Current Deployment (7 runners)
 
- Total CPU: 7 × 2 = **14 cores**
- Total RAM: 7 × 4 = **28 GB**
- Total Disk: 7 × 20 = **140 GB**
 
Last verified: 2026-01-27
  1. Add automated capacity checks:
#!/bin/bash
# verify-capacity-docs.sh
 
RUNNER_COUNT=$(docker ps --format '{{.Names}}' | grep -c runner)
EXPECTED_CPU=$((RUNNER_COUNT * 2))
EXPECTED_RAM=$((RUNNER_COUNT * 4))
 
echo "Current deployment: $RUNNER_COUNT runners"
echo "Required CPU: $EXPECTED_CPU cores"
echo "Required RAM: $EXPECTED_RAM GB"
 
# Compare against documented values
DOCUMENTED_CPU=$(grep -oP 'CPU: \K\d+' README.md)
if [ "$EXPECTED_CPU" != "$DOCUMENTED_CPU" ]; then
  echo "WARNING: Documented CPU ($DOCUMENTED_CPU) != actual ($EXPECTED_CPU)"
fi
  1. Include verification timestamp:
## Capacity Requirements
 
> **Last verified**: 2026-01-27 via `scripts/verify-capacity-docs.sh`

Reusability

  • Score: 4/5
  • Used in: aloysiusproductions-ops-core runner documentation

Trade-offs

  • Pro: Documentation stays accurate over time
  • Pro: Formula shows reasoning, making updates easier
  • Pro: Prevents under-provisioning surprises
  • Con: Requires discipline to update on each change
  • Con: Automated checks add maintenance overhead

Source

Discovered during workflow audit on 2026-01-23. Commit 5132a1a corrected capacity documentation from “7 CPU, 14 GB” to “14 CPU, 28 GB” (later refined to “13 CPU, 26 GB” based on actual config).

Graph View

Backlinks