Personal homelab infrastructure-as-code. Provisions Proxmox VMs, configures hosts, and runs services across Docker and Kubernetes with unified ingress and TLS.

1. Install tooling – Terraform ≥ 1.6, Ansible ≥ 2.14, Docker CLI, kubectl, and Azure CLI. Use Scripts/install_tf.sh on new Ubuntu control hosts to bootstrap Terraform quickly.
2. Configure secrets – Populate Terraform/terraform.tfvars with the variables in Terraform/variables.tf, authenticate to Azure for the remote state backend defined in Terraform/backend.tf, and store host/app secrets inside the .env files that live next to every compose project. Ansible inventory is encrypted via Vault (Ansible/inventory.ini).
3. Provision VMs – cd Terraform && terraform init && terraform plan -var-file=terraform.tfvars && terraform apply. State is stored in GJ-HomeLab-RG/gjterraformstatesa/tfstate so multiple operators stay coordinated.
4. Configure hosts + apps – cd Ansible && ansible-playbook -i inventory.ini pve-1-docker-apps.yml --vault-id @prompt (repeat for pve-2-docker-apps.yml, pve-plex.yml, etc.). Plays install Docker when missing, copy the Docker/<app> folder, and run docker compose up -d with optional restart/pull_latest flags.
5. Kubernetes + ingress – Terraform provisions the RKE2 nodes; manifests for Traefik and MetalLB live in K8s/ingress/*. Apply them with the kubeconfigs under K8s/kubeconfigs/.

🔁 Day-two operations: rerun Terraform for VM lifecycle changes and rerun the relevant Ansible playbook whenever compose projects change. Tasks copy only when files differ and restart stacks asynchronously to minimize downtime.

• 🖥️ Platform: Proxmox (pve-1, pve-2) hosting VMs for Docker workloads, DNS, Plex, NAS, and a Kubernetes cluster (RKE2).
• 🧱 Provisioning: Terraform modules define VMs, networking, storage, GPU/USB passthrough, and startup order per node.
• 🔧 Configuration: Ansible installs Docker and deploys per-host app stacks; baseline metrics via cAdvisor on all app nodes.
• 🌐 Networking & Ingress: Traefik v3 reverse proxy terminates TLS and routes to services. Let’s Encrypt DNS-01 via Azure DNS; domains under docker-1.example.com and docker-2.example.com.
• 💾 Storage: App data on host under /Apps/*; media via CIFS mounts from NAS to containers (e.g., //nas/Medias). Plex uses host networking and NVIDIA GPU.
• 📊 Observability: Prometheus + Grafana; exporters via cAdvisor and Traefik metrics. Healthchecks for external monitoring.
• 🚀 CI/CD: GitHub workflows for Terraform and Ansible deployments and updates.
• 🔐 Secrets: Environment-driven (.env) for cloud DNS, CIFS credentials, VPN, and OAuth/OpenAI integrations.

1. VM lifecycle (Terraform) – Each VM defined in pve-1.tf / pve-2.tf consumes the shared module in modules/proxmox_vm. Defaults include CPU topology, boot disks, and cloud-init (auto SSH key, DHCP). Override specifics such as GPU/USB passthrough, datastore target, or static IPs per node file.
2. Host bootstrap (Ansible) – Inventory groups match VM names. Plays compute the docker_apps_by_host map, ensure Docker is present (via Tasks/install_docker.yml), copy the matching compose directory, and start docker compose up asynchronously (Tasks/docker.yml). cAdvisor is auto-added to every host list for baseline metrics.
3. Services (Docker) – Every application folder contains its docker-compose.yml, .env, and any extra configs (e.g., Docker/dns-update/update_dns.sh, Docker/homeassistant/README-zigbee-usb.md). Because the folder is copied wholesale, treat it as the source of truth.
4. Kubernetes ingress – K8s/ingress/traefik houses the cluster-facing Traefik deployment plus values for the LANs, while K8s/ingress/metallb defines the L2 pools feeding RKE services. Choose Kubernetes Traefik vs Docker Traefik depending on workload placement.

The Docker/ tree mirrors production services. Highlights:

• Edge & networking – traefik/, dns-update/, adguardhome/, upsnap/.
• Observability – monitoring/ (Prometheus/Grafana stack), cadvisor/, healthchecks/.
• Media & automation – plex/, plexapps/, homeassistant/, satisfactory/.
• Dashboards & tools – homepage-1/, homepage-2/, code-server/, open-webui/, gitea/, pdf/, portainer/.
• Misc utilities – joke-de-jean/, teamspeak/, scrutiny/, etc.

Add a new service by creating Docker/<service> with its compose stack, referencing it inside the right Ansible playbook, and rerunning the play.

• Terraform – Supply the variables in variables.tf via terraform.tfvars or environment variables. Azure Storage backend (see backend.tf) provides locking/encryption; run az login before terraform init.
• Ansible Vault – Hostnames, IPs, and credentials in inventory.ini remain encrypted. Use ansible-vault view inventory.ini or --vault-id when running playbooks.
• Compose secrets – .env files sit beside each docker-compose.yml and are copied during playbook runs. Keep them outside version control and rotate as needed.

Terraform:

cd Terraform
terraform init
terraform plan -var-file=terraform.tfvars
terraform apply -var-file=terraform.tfvars

Update Docker stacks on pve-1:

cd Ansible
ansible-playbook -i inventory.ini pve-1-docker-apps.yml --vault-id @prompt

Kubernetes ingress refresh:

kubectl apply -k K8s/ingress/traefik
kubectl apply -k K8s/ingress/metallb

Use the restart / pull_latest toggles inside each playbook entry for targeted restarts without touching other services.

• Nodes provisioned via Terraform modules (master on pve-1; workers across pve-1/pve-2).
• Ingress: Traefik manifests under K8s/ingress/traefik.
• L2 Load Balancing: MetalLB configuration under K8s/ingress/metallb.
• Workloads can be fronted either by Kubernetes Traefik or the Docker Traefik, depending on routing strategy.

• Core zones: docker-1.example.com, docker-2.example.com (and app subdomains).
• TLS: Certificates via ACME DNS-01 (Azure DNS), persisted under /Apps/Traefik/letsencrypt.

Client ──TLS──► Traefik ──► Docker services (or K8s ingress) ──► App containers

Media apps ──CIFS──► NAS-1 share (//nas/Medias)

Exporters (cAdvisor/Traefik) ──► Prometheus ──► Grafana