---
id: RCLUSTER-WP-0014
type: workplan
title: "Publish cluster capacity, utilization, and allocation evidence"
domain: financials
repo: railiance-cluster
status: finished
owner: codex
topic_slug: railiance
created: "2026-08-11"
updated: "2026-08-22"
related:
  - RAIL-BS-WP-0007
  - RESOURCE-WP-0003
  - ADR-0006
  - ADR-0008
state_hub_workstream_id: "73ff6641-eaf6-5546-8f0e-b5aa1aa7f35b"
---

# RCLUSTER-WP-0014 — cluster resource evidence

## Goal

Publish reproducible non-secret evidence for
`resource:railiance:reef-railiance:k3s`: capacity, requested and observed
utilization, persistent-storage exposure, failure domains, and allocation
drivers. Origin: `RESOURCE-WP-0003-T04` delegated evidence gap.

This is ADR-0006 reef evidence (capacity headroom, failure-domain
assumptions). It does not promote a binding to `production-approved`.
It does not publish a public metrics listener (ADR-0008). Collect
in-cluster or via the operator tunnel.

Current reality: one Ready node (`railiance01`), local storage, Traefik.
Do not invent a three-domain map or report Longhorn as live capacity.
`RAIL-BS-WP-0007` is the HA *target*.

S2 publishes facts. `reef-railiance` cites them. `resource-control` /
fin-hub allocate. No booked EUR in this repo.

## T01 — Produce periodic cluster capacity observations

```task
id: RCLUSTER-WP-0014-T01
status: done
priority: high
state_hub_task_id: "abc4980e-4103-5d63-9e05-5a198dc7988b"
```

Collect node count, allocatable CPU/memory/storage/pods, workload requests and
limits, observed usage when metrics are available, and PVC requested capacity.
Aggregate by namespace/workload without exposing Secret data or pod
environment. Preserve observation time, cluster identity, units, unavailable
metrics, and source commands.

Done when repeated observations use a stable machine-readable interface and
resource-control can distinguish headroom, reservations, and actual usage.

**Outcome (2026-08-22):** `make cluster-observe REMOTE=railiance01` now emits
versioned, timestamped JSON with node allocatable/observed resources,
namespace/workload requests and limits, PVC/PV/storage-class state, stable
units, source commands, and explicit gaps without reading Secrets or pod
environments.

## T02 — Publish the failure-domain and storage contract

```task
id: RCLUSTER-WP-0014-T02
status: done
priority: high
state_hub_task_id: "9e0dc15e-a853-512e-be44-71525ce0bc47"
```

Expose the current node-to-host/provider failure-domain map and the actual
storage-class/PVC durability contract. Link the target ThreePhoenix work in
`RAIL-BS-WP-0007` without reporting target nodes or distributed storage as
current capacity.

Done when consumers can calculate correlated-failure risk and recognize which
state remains local to `railiance01`.

**Outcome (2026-08-22):** the evidence contract reports one Ready node,
`local-path` storage, `threephoenix_ready: false`, and the missing independent
region/zone labels. Target HA and Longhorn capacity are not represented as
current facts.

## T03 — Define technical allocation-driver evidence

```task
id: RCLUSTER-WP-0014-T03
status: done
priority: medium
state_hub_task_id: "8a052726-e6f2-5852-aada-a14e67bca695"
```

Evaluate namespace/workload CPU-request hours, memory-request hours, PVC
GB-month, and observed usage as allocation drivers. Publish numerator,
denominator, residual/unallocated capacity, method version, and uncertainty;
do not convert the result into booked spend.

Done when resource-control can create an explainable allocation and fin-hub can
reconcile it to referenced financial facts.

**Outcome (2026-08-22):** `cluster-raw-drivers-v1` publishes CPU requests,
memory requests, PVC bytes, observed usage, totals, residual capacity, and
uncertainty, while leaving formula selection and booked cost to
`resource-control`.

## Acceptance

- [x] Capacity evidence separates allocatable, requested, limited, and observed.
- [x] Current single-host/local-storage risk is machine-readable.
- [x] Allocation drivers reconcile to explicit totals and residuals.

## Completion evidence

- `python3 -m unittest discover -s tests -p 'test_*.py' -v`: 2 tests passed.
- Live read-only capture:
  `docs/evidence/resource-reef-railiance-k3s/observations/20260822T100349Z.json`.
- Observed totals: 1 node, 53 workloads, 25 claims; 4,000m allocatable CPU,
  3,830m requested CPU, 16,770,076,672 allocatable memory bytes, and
  137,438,953,472 requested PVC bytes.