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):

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