Homelab

Infrastructure-as-code for a home network, managed through layered automation with no hand-holding.

Built with: AWS CDK, Ansible, Kubernetes, Argo CD, Taskfile, GitHub Actions, Dependabot, Renovate, Cloudflare.

For technical architecture and implementation details, see AGENTS.md.

---

Quick Start

See AGENTS.md for detailed command reference and architecture overview.

Essential setup:

task configure
task check

---

Kubernetes Deployment Strategy

Ansible configures hosts, bootstraps Kubernetes (K3s), and deploys Argo CD. After bootstrap, Argo CD manages all application deployments.

Argo CD

App-of-Apps Pattern

Self-referential Argo CD Applications must live in the default AppProject. Deleting self-referential app-of-apps requires removing the finalizer after dependent resources are cleared.

See AGENTS.md for detailed app dependency, wave ordering, and ApplicationSet configuration.

Operational Notes

Rook/Ceph

Deploy the operator first, then the cluster. Check cluster status:

kubectl -n rook-ceph exec -it deploy/rook-ceph-tools -- bash

Flood/rTorrent

Configure Flood to talk to rTorrent using socket path: /config/.local/share/rtorrent/rtorrent.sock

*Arr Services (Radarr, Sonarr, Whisparr, etc.)

Extract API keys from running containers:

api_key=$(kubectl -n homelab exec -it deploy/whisparr-svc -- cat /config/config.xml | grep -oP '<ApiKey>\K[^<]+' | tr -d '\n')
kubectl -n homelab create secret generic whisparr-secret --from-literal="api_key=${api_key}"

Repeat for other *arr services as needed.

External Access

Cloudflare Tunnel

Applications are exposed via Cloudflare Tunnel. Each application has its own tunnel and credentials secret.

To maintain infrastructure-as-code discipline, do not create resources in the Cloudflare dashboard. Use the setup script:

scripts/setup-tunnel.sh

The script automates tunnel creation, credential management, and Kubernetes secret generation. Note: Cloudflare Application creation (authentication/authorization policy) is manual—not scripted.

See AGENTS.md for detailed setup steps and configuration patterns.

GitHub Actions

Configuration and secrets for CI/CD pipeline:

Variables

Name	Value
ANSIBLE_STDOUT_CALLBACK	gha
AWS_ASSUME_ROLE_ARN	(generated by CDK)
AWS_DEFAULT_REGION	us-west-2
AWS_REGION	us-west-2
BASTION_HOST	(configured)
BASTION_PORT	(configured)
NODE_VERSION	20
PYTHON_VERSION	3.10.13
RUNS_ON	ubuntu-latest
TASK_VERSION	3.31.0

Secrets

Name	Purpose
ANSIBLE_EXTRA_VAR_JSON	Extra Ansible vars (includes op_connect_token, op_vault_id)
OP_SERVICE_ACCOUNT_TOKEN	1Password Service Account token for GitHub Actions

---

Development

See AGENTS.md for detailed development guidance, command reference, and troubleshooting.

Setup:

task configure

Validation:

task check
pre-commit run -a

---

Resources & Thanks

Icons sourced from selfh.st/icons — a curated collection of self-hosted service icons

Thanks to the Kubernetes @Home community, especially:

• Kubernetes @Home Search for deployment ideas
• bjw-s for home-ops and helm-charts
• All contributors to the k8s-at-home community