nathan/homelab
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Releases Wiki Activity
homelab/ansible/archive/documentation/contracts/Handover-AnsibleEngineer.md

2.7 KiB
Raw Blame History

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.