56 lines
2.7 KiB
Markdown
56 lines
2.7 KiB
Markdown
# 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.**
|