152 lines
4.2 KiB
Markdown
152 lines
4.2 KiB
Markdown
# Environment constraints
|
||
|
||
**Date:** 2026-01-10
|
||
**Status:** Living document
|
||
**Author:** Chester + FrankGPT
|
||
|
||
## Purpose
|
||
|
||
This document defines the hardware, software, and network constraints of the homelab environment. All playbooks and roles must respect these constraints.
|
||
|
||
---
|
||
|
||
## Network topology
|
||
|
||
> [!IMPORTANT]
|
||
> Current operational state is still a flat network on `10.0.0.0/24`.
|
||
> VLAN segmentation and target zone allocations in this document are migration targets,
|
||
> not fully applied runtime state.
|
||
|
||
| Parameter | Value |
|
||
| :--- | :--- |
|
||
| Subnet | `10.0.0.0/24` |
|
||
| Gateway | `10.0.0.2` |
|
||
| Primary DNS | `10.0.0.2` |
|
||
| Secondary DNS | `8.8.8.8` |
|
||
| Domain | `local` (optional) |
|
||
|
||
### IP allocation scheme
|
||
|
||
| Range | Purpose |
|
||
| :--- | :--- |
|
||
| `10.0.0.1` | Reserved |
|
||
| `10.0.0.2` | Gateway / Primary DNS |
|
||
| `10.0.0.3 - 10.0.0.199` | DHCP / General devices |
|
||
| `10.0.0.200 - 10.0.0.209` | Proxmox hosts (physical) |
|
||
| `10.0.0.210 - 10.0.0.219` | Swarm managers (VMs) |
|
||
| `10.0.0.220 - 10.0.0.229` | Swarm workers (VMs) / legacy AI nodes during migration |
|
||
| `10.0.0.230 - 10.0.0.239` | AI workstations |
|
||
| `10.0.0.240 - 10.0.0.248` | Reserved / Future |
|
||
| `10.0.0.249 - 10.0.0.250` | NAS devices |
|
||
| `10.0.0.251 - 10.0.0.254` | Docker hosts / Misc |
|
||
|
||
---
|
||
|
||
## Host categories
|
||
|
||
### Proxmox cluster (physical)
|
||
|
||
| Hostname | IP | Hardware | Notes |
|
||
| :--- | :---: | :--- | :--- |
|
||
| `pve01` | `10.0.0.201` | Lenovo SFF, 16 GB RAM, 512 GB NVMe | First node, 2× NICs |
|
||
| `pve02` | `10.0.0.202` | (future) | |
|
||
| `pve03` | `10.0.0.203` | (future) | |
|
||
| `pve04` | `10.0.0.204` | (future) | |
|
||
| `pve05` | `10.0.0.205` | (future) | |
|
||
|
||
**Constraints:**
|
||
- Proxmox VE 8.x or 9.x
|
||
- `ansible_user=root` for provisioning
|
||
- Python 3 available at `/usr/bin/python3`
|
||
|
||
### Swarm nodes (VMs on Proxmox)
|
||
|
||
| Role | Hostname pattern | IP range | Specs |
|
||
| :--- | :--- | :--- | :--- |
|
||
| Manager | `swarm-manager-X` | `.211 - .215` | 4 GB RAM, 2 vCPU, 32 GB disk |
|
||
| Worker | `swarm-worker-X` | `.221 - .225` | 4 GB RAM, 2 vCPU, 32 GB disk |
|
||
|
||
**Constraints:**
|
||
- Ubuntu 24.04 LTS (Noble)
|
||
- Docker CE installed via official repo
|
||
- `ansible_user=chester`
|
||
|
||
### AI workstations (physical)
|
||
|
||
| Hostname | IP | Hardware | Notes |
|
||
| :--- | :---: | :--- | :--- |
|
||
| `ai-lenovo` | `10.0.0.220` | Laptop, 12 GB GPU | Ubuntu Server |
|
||
|
||
**Constraints:**
|
||
- Ubuntu Server (not Desktop)
|
||
- GPU drivers managed separately
|
||
- `ansible_user=chester`
|
||
|
||
### Storage / NAS (appliances)
|
||
|
||
| Hostname | IP | Product | Notes |
|
||
| :--- | :---: | :--- | :--- |
|
||
| `synology` | `10.0.0.249` | Synology NAS | Proprietary Linux, limited shell |
|
||
| `terramaster` | `10.0.0.250` | TerraMaster NAS | Proprietary Linux, limited shell |
|
||
|
||
**Constraints:**
|
||
- **Caution required** — proprietary OS, not standard Ubuntu
|
||
- Use `ansible_scp_if_ssh=True` for Synology
|
||
- Avoid destructive commands; test in check mode first
|
||
- Limited Python support; prefer `raw` module when needed
|
||
|
||
### Controller (watchtower)
|
||
|
||
| Hostname | IP | Hardware | Notes |
|
||
| :--- | :---: | :--- | :--- |
|
||
| `localhost` | N/A | Raspberry Pi 5 | Ansible controller |
|
||
|
||
**Constraints:**
|
||
- `ansible_connection=local`
|
||
- Runs all playbooks from this host
|
||
- ARM64 architecture (consider when building containers)
|
||
|
||
---
|
||
|
||
## Software standards
|
||
|
||
| Component | Version | Notes |
|
||
| :--- | :--- | :--- |
|
||
| Ansible | 2.15+ | Core automation |
|
||
| Python | 3.10+ | Required on all managed hosts |
|
||
| Docker CE | Latest stable | Swarm mode |
|
||
| Proxmox VE | 8.x or 9.x | Hypervisor |
|
||
| Ubuntu | 24.04 LTS | Guest OS for VMs |
|
||
|
||
---
|
||
|
||
## Firewall / ports
|
||
|
||
| Port | Protocol | Purpose | Required on |
|
||
| :---: | :---: | :--- | :--- |
|
||
| 22 | TCP | SSH | All hosts |
|
||
| 8006 | TCP | Proxmox GUI | Proxmox hosts |
|
||
| 2377 | TCP | Swarm cluster mgmt | Swarm nodes |
|
||
| 7946 | TCP/UDP | Swarm node comm | Swarm nodes |
|
||
| 4789 | UDP | Swarm overlay network | Swarm nodes |
|
||
|
||
---
|
||
|
||
## Documentation mandate
|
||
|
||
> [!IMPORTANT]
|
||
> **FrankGPT core principle:** Documentation is not optional.
|
||
>
|
||
> - Every decision must be recorded in `documentation/standards/`
|
||
> - Every playbook must have a header comment explaining usage
|
||
> - Every variable must be documented in defaults or group_vars
|
||
> - When in doubt, write it down
|
||
|
||
---
|
||
|
||
## Change log
|
||
|
||
| Date | Change | Author |
|
||
| :--- | :--- | :--- |
|
||
| 2026-01-10 | Initial creation | Chester + FrankGPT |
|