# Homelab Ansible Handover – v2 Architecture

## Purpose

This document summarizes the current homelab architecture and operational contracts. It is intended as a handover for an Ansible engineer to begin developing and maintaining infrastructure automation playbooks.

---

## Architecture Overview

- **Control Plane:** Raspberry Pi 5 (“Watchtower”) – out-of-band management node. Runs Ansible controller, VS Code Tunnel, Tailscale, and Uptime Kuma. No production workloads or reverse proxies.
- **Compute Plane:** 3× Dell OptiPlex Micro 7010 running Proxmox. Each host runs:
  - 1× Swarm Manager VM (control, light infra only)
  - 1× Swarm Worker VM (all app workloads)
- **Networking:** Flat LAN (`10.0.0.0/24`), static IPs for infra, IoT/guest VLANs segregated. Future VLAN segmentation planned.
- **Storage:** TerraMaster (primary data), Synology (backup, cloud sync). Rsync and cloud sync jobs run daily.
- **Access & Identity:** Authentik SSO for operator/admin accounts. Remote access via Omada VPN, Tailscale, VS Code Tunnel. MFA and password vault required.

---

## Playbook Priorities & Expectations

1. **Idempotency:** All playbooks must be safe to run repeatedly and should not cause drift or break contracts.
2. **Contracts:** Reference the v2 contracts in `architecture/v2/contracts/` for allowed/forbidden services, node roles, and operational constraints.
3. **Inventory:** Maintain a clear, up-to-date inventory (hosts, groups, roles) reflecting the contracts.
4. **Separation of Concerns:** 
   - Control plane (Watchtower) is for automation, monitoring, and recovery only.
   - Compute plane (Proxmox VMs) runs all application workloads.
   - Never deploy workloads or Swarm nodes directly on Proxmox hosts or NAS devices.
5. **Access:** Use Authentik SSO for all supported services. Document and automate onboarding/offboarding where possible.
6. **Backups:** Automate and verify backup flows (TerraMaster → Synology → cloud). Never skip scheduled backups.
7. **Security:** Never expose management UIs to the public internet. Enforce MFA and strong password policies.

---

## Immediate Playbook Targets

- Proxmox host and VM provisioning (with static IPs, labels, and roles)
- Docker Swarm cluster setup and node role enforcement
- NAS configuration and backup job automation
- Authentik SSO integration for new services
- Monitoring/alerting setup (Uptime Kuma, notifications)
- Access onboarding/offboarding automation

---

## Reference

- Full contracts: `architecture/v2/contracts/`
- Planning docs: `architecture/v2/plans/`
- README: `architecture/v2/README.md`

---

**Contact the homelab owner for clarifications or to propose contract updates before making architectural changes.**