tegwick
b1aac08eb2
Seed a non-secret service inventory (environments, hosts, clusters, services, endpoints, access paths, evidence, gaps) with a JSON schema, a renderer, and a generated service-catalog view. Adds the `make ops-inventory-view` target, probe ActivityDefinition, and docs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
95 lines
3.5 KiB
Markdown
95 lines
3.5 KiB
Markdown
# Ops Hub Service Inventory
|
|
|
|
Date: 2026-06-05
|
|
|
|
## Purpose
|
|
|
|
The first ops-hub "now view" should answer one practical question:
|
|
|
|
> What service is running where, who owns it, how is it reached, and what
|
|
> evidence says it is alive?
|
|
|
|
The lowest-effort path is a small read model, not a full new application. The
|
|
read model starts as `ops/service-inventory.yml`, can be surfaced through
|
|
Inter-Hub ops widgets, and can later be ingested by the standalone `ops-hub`
|
|
repo planned in `CUST-WP-0025`.
|
|
|
|
## Operating Model
|
|
|
|
- Git owns the declared inventory.
|
|
- Inter-Hub widgets expose the visible ops entities.
|
|
- Interaction events provide timestamped operational evidence.
|
|
- activity-core runs repeatable probes and writes evidence.
|
|
- State Hub continues to own workstreams, tasks, decisions, and progress. It is
|
|
not the service catalog.
|
|
|
|
## Minimal Record Shape
|
|
|
|
Each service record should include:
|
|
|
|
- `id`: stable lowercase service id, for example `state-hub`.
|
|
- `name`: human-readable name.
|
|
- `lifecycle_state`: `observed`, `planned`, `target`, or `retired`.
|
|
- `health_status`: `unknown`, `observed_ok`, `degraded`, `down`, or `planned`.
|
|
- `environment`: environment id where the service currently belongs.
|
|
- `owner_repos`: repos that own desired state, runtime code, or runbooks.
|
|
- `runtime`: runtime kind and location details, such as `local-process`,
|
|
`k3s`, `systemd`, `external`, or `bridge`.
|
|
- `endpoints`: public, local, cluster, or tunnel endpoints with expected
|
|
non-secret checks.
|
|
- `backing_stores`: databases, PVCs, object stores, or external stores that
|
|
must be backed up with the service.
|
|
- `access_paths`: non-secret descriptions of SSH, Kubernetes, HTTP, or tunnel
|
|
paths.
|
|
- `evidence`: links to docs, progress events, probe results, or workplans.
|
|
- `gaps`: missing evidence or operating controls.
|
|
|
|
The schema lives at `schemas/ops-service-inventory.schema.json`.
|
|
|
|
## First View
|
|
|
|
The initial ops-hub view can be a dense table:
|
|
|
|
| Column | Meaning |
|
|
|---|---|
|
|
| Service | `name` plus `id` |
|
|
| Where | environment, host, cluster, namespace |
|
|
| Owner | owner repo and desired state source |
|
|
| Endpoint | primary endpoint and expected check |
|
|
| Health | latest health status and last evidence timestamp |
|
|
| Data | backing stores and backup gap summary |
|
|
| Access | access path status |
|
|
| Gaps | highest-priority missing operating evidence |
|
|
|
|
This is enough to make scattered operational reality visible without waiting
|
|
for a full incident system, runbook executor, or custom database.
|
|
|
|
The repo-native version is rendered to `docs/ops-hub-service-catalog.md`:
|
|
|
|
```bash
|
|
make ops-inventory-view
|
|
```
|
|
|
|
## Evidence Events
|
|
|
|
Use a small event vocabulary first:
|
|
|
|
- `ops-service-observed`: service/runtime object was observed.
|
|
- `ops-endpoint-verified`: endpoint responded as expected.
|
|
- `ops-access-path-checked`: access path was checked without storing secrets.
|
|
- `ops-backup-verified`: backup and restore evidence exists.
|
|
- `ops-inventory-drift`: observed state differs from declared inventory.
|
|
|
|
Event metadata should reference the stable inventory id and include non-secret
|
|
probe output only.
|
|
|
|
## Promotion Path
|
|
|
|
1. Keep `ops/service-inventory.yml` as the source artifact.
|
|
2. Seed or update Inter-Hub widgets from the inventory ids.
|
|
3. Let activity-core run probes and submit evidence events.
|
|
4. Build the first ops-hub view from inventory plus latest evidence.
|
|
5. When the standalone `ops-hub` repo exists, ingest the same inventory and
|
|
evidence events into the proper Service, AccessPath, Runbook, and Incident
|
|
models from `CUST-WP-0025`.
|