tegwick
644d5391bd
Handle becomes secret:railiance-platform/backup. IAM application is resource-control; policy and API key are Scoped backup access.
146 lines
4.8 KiB
Markdown
146 lines
4.8 KiB
Markdown
# Operational reference convention v0.1
|
|
|
|
Status: baseline
|
|
Effective: 2026-08-14
|
|
Owners: `resource-control` (join keys), `reef-*` (operational facts)
|
|
|
|
`resource-control` manages resources from **procurement, consumption, usage,
|
|
and cost**. It does not operate them. A `reef-*` repo is the operational
|
|
substrate. Non-secret operating attributes and credential *handles* are
|
|
therefore **references**, never copies of the operating record and never
|
|
secret values.
|
|
|
|
This is the join convention. Schema adoption is `RESOURCE-WP-0006`.
|
|
`reef-storage` materialization is `RMASTER-WP-0022`.
|
|
|
|
---
|
|
|
|
## Authority
|
|
|
|
| Fact | Authoritative home |
|
|
| --- | --- |
|
|
| Why the resource exists, what was decided, who pays, who may consume, what it cost | `resource-control` |
|
|
| How the substrate is named, reached, bound, and run | the `reef-*` repo |
|
|
| Secret material (access keys, tokens, payment instruments) | approved OpenBao / credential-broker lane (`railiance-platform` today) |
|
|
| Booked invoices and recognized payments | `fin-hub` |
|
|
| Workload use of a reviewed destination | the consuming `rapp-*` |
|
|
|
|
Do not duplicate a reef attribute into the inventory record “for convenience.”
|
|
Cite it. If the reef path moves, update the reference, not a shadow copy.
|
|
|
|
---
|
|
|
|
## Reference forms
|
|
|
|
### Reef attribute
|
|
|
|
A non-secret operating fact owned by a reef:
|
|
|
|
```text
|
|
reef:<reef_id>/<repo-relative-path>#<json_or_yaml_key>
|
|
```
|
|
|
|
- `reef_id` equals the reef repo slug (`reef-railiance`, `reef-storage`).
|
|
- Path is from the reef repo root, POSIX, no `..`.
|
|
- Fragment is a dotted key into that file (`endpoint`, `bucket.prefix`).
|
|
- The file is committed, non-secret, and the reef is authoritative for it.
|
|
|
|
Examples (illustrative until `reef-storage` exists):
|
|
|
|
```text
|
|
reef:storage/substrate/object-stores/platform-audit-storage.yaml#endpoint
|
|
reef:storage/substrate/object-stores/platform-audit-storage.yaml#bucket
|
|
reef:storage/substrate/object-stores/platform-audit-storage.yaml#region
|
|
reef:railiance/declarations/reef.yaml#current_members
|
|
```
|
|
|
|
Inventory stores the reference, not the endpoint string.
|
|
|
|
### Credential handle
|
|
|
|
A pointer to custody, never a value:
|
|
|
|
```text
|
|
secret:<custody_repo>/<secret_id>
|
|
```
|
|
|
|
Example already named by the backup split:
|
|
|
|
```text
|
|
secret:railiance-platform/backup
|
|
```
|
|
|
|
The handle may also record `broker` (`openbao`) and `rotation` as non-secret
|
|
metadata. The secret body stays in the broker.
|
|
|
|
### Structured form
|
|
|
|
When a record needs more than a string:
|
|
|
|
```json
|
|
{
|
|
"kind": "reef_attribute",
|
|
"reef_id": "reef-storage",
|
|
"repo": "reef-storage",
|
|
"path": "substrate/object-stores/platform-audit-storage.yaml",
|
|
"key": "endpoint",
|
|
"ref": "reef:storage/substrate/object-stores/platform-audit-storage.yaml#endpoint"
|
|
}
|
|
```
|
|
|
|
```json
|
|
{
|
|
"kind": "credential_handle",
|
|
"custody_repo": "railiance-platform",
|
|
"secret_id": "backup",
|
|
"broker": "openbao",
|
|
"ref": "secret:railiance-platform/backup"
|
|
}
|
|
```
|
|
|
|
Both `ref` and the parsed fields must agree when both are present.
|
|
|
|
---
|
|
|
|
## What a resource-control resource then holds
|
|
|
|
Five facets, all first-class in the forthcoming inventory v0.3:
|
|
|
|
1. **Description** — purpose and class; why this resource exists.
|
|
2. **Decision** — chosen option, approver, date, rejected alternatives
|
|
(or an explicit “not decided” gap). Required before status `ordered`.
|
|
3. **Operational attribute refs** — `reef:…` pointers. Empty only with an
|
|
explicit gap (reef not created yet).
|
|
4. **Credential handles** — `secret:…` pointers. Empty is allowed when no
|
|
credential exists yet; values are never stored here.
|
|
5. **Consumers** — `potential` (intended / declared) vs `actual` (observed
|
|
using the resource). A name in `workload_ids` alone is not enough.
|
|
|
|
---
|
|
|
|
## Reef views
|
|
|
|
`data/reefs/<reef_id>.json` is the **resource-control view** of a reef: which
|
|
inventory records implement its procured capacity, which entities pay, which
|
|
consumers are potential vs actual. It is not a second `reef.yaml` and must
|
|
not restate member IPs, kubeconfig paths, or endpoints.
|
|
|
|
`reef-railiance` is compute (Host Europe `railiance01`, k3s, platform
|
|
services). It does **not** grow an S3 object store. Backup object storage is
|
|
a different substrate boundary: `reef-storage`.
|
|
|
|
---
|
|
|
|
## Backup / S3 split (the proving case)
|
|
|
|
| Concern | Owner |
|
|
| --- | --- |
|
|
| Demand, comparison, purchase approval, cost, settlement | `resource-control` (`RESOURCE-WP-0002`) |
|
|
| Operate the Scaleway (or successor) object store: endpoint, bucket, region, lifecycle as committed facts | `reef-storage` (`RMASTER-WP-0022`) |
|
|
| Credential custody and delivery | `railiance-platform` OpenBao |
|
|
| Barman, schedule, retention, restore | `rapp-postgres` after a reviewed destination |
|
|
| Consume the destination | `rapp-postgres` (actual once WAL flows) |
|
|
|
|
Until `reef-storage` exists, the proposed backup record may cite a gap
|
|
instead of a `reef:` URL. That gap is expected; inventing an endpoint here
|
|
is not.
|