Madagascar
/
cluster-context
/
README.md
Newer
■
■
■
■
■
■
■
■
■
■
Older
64 lines
|
2.999kb
| 1 |
Madagascar cluster context files |
|
| 2 | ||
| 3 |
Purpose |
|
| 4 | ||
| 5 |
These files provide a shared cluster-context cache and changelog for Madagascar. Other projects can read or append to these files to share knowledge about cluster layout, network configuration, and changes that may affect deployments. |
|
| 6 | ||
| 7 |
Files |
|
| 8 | ||
| 9 |
- `madagascar.json` - primary cache. Contains a schemaVersion, lastUpdated, source, and a `clusters` map keyed by cluster name. Each cluster can include hosts, network file paths, services and notes. |
|
| 10 | ||
| 11 |
- `madagascar-changelog.json` - append-only changelog. Contains an `entries` array. Each entry should include: `id`, `timestamp` (ISO 8601 UTC), `project`, `author`, `summary`, `details`, `affectedResources` (array), and `type` (info|change|breaking|deprecated). |
|
| 12 |
- `history/` - historical snapshots that are useful for reference but are not the current source of truth. |
|
| 13 | ||
| 14 |
Contract (madagascar.json) |
|
| 15 | ||
| 16 |
- schemaVersion: string |
|
| 17 |
- lastUpdated: ISO 8601 timestamp in UTC |
|
| 18 |
- source: project name that last updated the file |
|
| 19 |
- clusters: map of cluster objects. Cluster object fields: |
|
| 20 |
- name: cluster name |
|
| 21 |
- hosts: map of role->hostname or role->fqdn |
|
| 22 |
- network: optional map with keys `interfacesFile` and `interfacesD` (relative paths) |
|
| 23 |
- services: optional map of service name -> { enabled: bool, systemdUnit: path }
|
|
| 24 |
- notes: optional string |
|
| 25 | ||
| 26 |
Changelog entry contract (madagascar-changelog.json) |
|
| 27 | ||
| 28 |
- entries: array of objects, each with: |
|
| 29 |
- id: unique id string (recommend prefix: project-YYYYMMDD-HHMM) |
|
| 30 |
- timestamp: ISO 8601 UTC |
|
| 31 |
- project: project name making the change |
|
| 32 |
- author: author name or automation id |
|
| 33 |
- summary: short summary |
|
| 34 |
- details: longer description |
|
| 35 |
- affectedResources: array of strings (paths or logical names) |
|
| 36 |
- type: one of info|change|breaking|deprecated |
|
| 37 | ||
| 38 |
How to update |
|
| 39 | ||
| 40 |
Manual append example (bash + jq): |
|
| 41 | ||
| 42 |
```bash |
|
| 43 |
# create new entry JSON |
|
| 44 |
entry=$(jq -n --arg id "entry-$(date -u +%Y%m%d%H%M%S)" \ |
|
| 45 |
--arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ |
|
| 46 |
--arg project "mysvc" \ |
|
| 47 |
--arg author "$USER" \ |
|
| 48 |
--arg summary "Updated network config" \ |
|
| 49 |
--arg details "Added new interface route needed by Madagascar" \ |
|
| 50 |
'{id: $id, timestamp: $ts, project: $project, author: $author, summary: $summary, details: $details, affectedResources:["network/interfaces"], type: "change"}')
|
|
| 51 | ||
| 52 |
# append atomically |
|
| 53 |
jq --argjson e "$entry" '.entries += [$e]' cluster-context/madagascar-changelog.json > cluster-context/madagascar-changelog.json.tmp && mv cluster-context/madagascar-changelog.json.tmp cluster-context/madagascar-changelog.json |
|
| 54 |
``` |
|
| 55 | ||
| 56 |
Automation guidance |
|
| 57 | ||
| 58 |
- Prefer creating unique `id` values (project prefix + timestamp + random suffix). |
|
| 59 |
- When automation updates `cluster-context/madagascar.json`, also add a changelog entry. |
|
| 60 |
- Keep `cluster-context/madagascar.json` small — only cache what's necessary. |
|
| 61 | ||
| 62 |
Notes |
|
| 63 | ||
| 64 |
- These files are meant to be shared between related projects. Treat `cluster-context/madagascar-changelog.json` as append-only; prefer appending rather than rewriting history. |