Copilot Instructions for Madagascar Thunderbolts & Backups

Big Picture Architecture

• The codebase manages high-MTU Thunderbolt networking and automated backups for a Proxmox cluster (baobab, ebony, tapia).
• Networking: Early boot systemd/udev units create and maintain a thunderbridge (MTU 65520), hotplug Thunderbolt NICs, and ensure persistent bridge membership.
• Backups: Autonomous agent scripts (in backups/) discover VMs, run scheduled backups, and log lifecycle events.
• All node, network, and backup config is centralized in cluster/madagascar.json.

Critical Developer Workflows

• Network Deploy:
  • Run deploy/attempt1/deploy_tb.sh from its directory to push configs and services to all nodes.
  • Validate with scripts/check_thunderbridge.sh (checks bridge ports, MTU, and cluster connectivity).
• Backup Deploy:
  • Use backups/scripts/deploy_to_nodes.sh to install backup agents on all nodes.
  • Backup agent lifecycle is managed by systemd timers (backup_agent.timer).
• Issue Tracking:
  • All issues documented in issues/ using TEMPLATE.md.
  • Every fix/change must be referenced in CHANGELOG.md.

Project-Specific Conventions

• Network config:
  • Node-specific overlays in deploy/attempt1/<node>/etc/network/interfaces.d/10-thunderbolt.
  • Shared systemd/udev units in deploy/attempt1/common/.
  • Always use post-up hooks for bridge membership and MTU persistence.
• SSH Automation:
  • Scripts use -o LogLevel=ERROR to suppress known hosts warnings.
  • Management and Thunderbolt IPs are set in deploy scripts; update helpers for new nodes.
• Versioning:
  • New network designs go in new attemptN folders for reproducibility.
• Backups:
  • All backup config and manifests reference madagascar.json for node/IP discovery.
  • Backup agent logs lifecycle events and changes in madagascar-changelog.json (if present).

Integration Points & Data Flows

• Network:
  • Systemd/udev units interact via device events; enlist services attach NICs to bridge.
  • Deploy script pushes all config and reloads services atomically.
• Backups:
  • Agent scripts SSH into nodes, discover VMs, and run backups using Proxmox CLI.
  • Results and metadata are logged for auditability.

Key Files & Directories

• deploy/attempt1/deploy_tb.sh: Main network deploy script
• deploy/attempt1/common/: Shared systemd/udev units
• deploy/attempt1/<node>/etc/network/interfaces.d/10-thunderbolt: Node overlays
• scripts/check_thunderbridge.sh: Cluster network health check
• cluster/madagascar.json: Canonical node/network/backup config
• backups/: Backup agent, deployment, and documentation
• issues/: Issue tracker
• CHANGELOG.md: Change log

Example Patterns

• To add a node: copy an existing node directory, update IPs, extend deploy script helpers.
• To troubleshoot: check systemd unit status, bridge membership, and kernel logs.
• To automate: use provided scripts, keep configs in sync with madagascar.json, and document all changes.

For questions or unclear conventions, review README.md and issue templates, or ask for clarification in the issue tracker.