bogdan Analizeaza timpi reboot si documente

f16725e 3 months ago History

Madagascar cluster context files

Purpose

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.

Files

- `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.

- `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).
- `history/` - historical snapshots that are useful for reference but are not the current source of truth.

Contract (madagascar.json)

- schemaVersion: string
- lastUpdated: ISO 8601 timestamp in UTC
- source: project name that last updated the file
- clusters: map of cluster objects. Cluster object fields:
  - name: cluster name
  - hosts: map of role->hostname or role->fqdn
  - network: optional map with keys `interfacesFile` and `interfacesD` (relative paths)
  - services: optional map of service name -> { enabled: bool, systemdUnit: path }
  - notes: optional string

Changelog entry contract (madagascar-changelog.json)

- entries: array of objects, each with:
  - id: unique id string (recommend prefix: project-YYYYMMDD-HHMM)
  - timestamp: ISO 8601 UTC
  - project: project name making the change
  - author: author name or automation id
  - summary: short summary
  - details: longer description
  - affectedResources: array of strings (paths or logical names)
  - type: one of info|change|breaking|deprecated

How to update

Manual append example (bash + jq):

```bash
# create new entry JSON
entry=$(jq -n --arg id "entry-$(date -u +%Y%m%d%H%M%S)" \
  --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --arg project "mysvc" \
  --arg author "$USER" \
  --arg summary "Updated network config" \
  --arg details "Added new interface route needed by Madagascar" \
  '{id: $id, timestamp: $ts, project: $project, author: $author, summary: $summary, details: $details, affectedResources:["network/interfaces"], type: "change"}')

# append atomically
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
```

Automation guidance

- Prefer creating unique `id` values (project prefix + timestamp + random suffix).
- When automation updates `cluster-context/madagascar.json`, also add a changelog entry.
- Keep `cluster-context/madagascar.json` small — only cache what's necessary.

Notes

- 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.