home-ops AGENTS.md

Home Ops

GitOps Talos Kubernetes homelab (single-node, local-only). Changes via PR only. Tech: Talos • K8s • Argo CD • Istio Gateway API • External Secrets (Bitwarden) • VictoriaMetrics/VictoriaLogs/VLAgent/Grafana • Helm • Ansible • Terraform

Build & Test

• Format: task fmt
• Format check: task fmt:check
• Dependencies: task deps creates .venv and installs Ansible Python dependencies
• Lint: task lint (offline validation: formatting, shellcheck, yamllint, GitHub Actions workflow lint, Ansible syntax/lint/contracts, metadata policy, raw manifest policy/schema/deprecation checks, batched rendered policy/schema/deprecation checks, tofu validate)
• Focused checks: task lint:static, task lint:workflows, task lint:ansible, task lint:kubernetes, task lint:terraform
• Policy layers:
  • policy/metadata/ validates app metadata structure and required sync waves
  • policy/kubernetes/ validates manifest and rendered-workload guardrails
• Policy semantics are regression-tested in policy/metadata/*_test.rego and policy/kubernetes/*_test.rego
• CI gate: GitHub Quality Gate job, backed by the same focused local task lint:* targets aggregated by task lint
• Pre-commit gate: task precommit (task fmt + task lint)
• Sync ArgoCD app: task argo:sync [app=<name>] (GitOps: changes must be committed and pushed to repo first)

Developer Loop

1. Make a small change
2. If behavior changes, write or update the failing policy or contract check first
3. Use task lint while iterating when changing script behavior or Helm/app compatibility
4. Run task fmt
5. Run task lint before commit or PR update

Project Layout

apps/<category>/<app>/{app.yaml,values.yaml,manifests/}
argocd/appsets/          # Auto-discovers apps/*/*/app.yaml
ansible/                 # Local orchestration, inventory, roles, role defaults, and Talos bootstrap inputs
terraform/               # Cloudflare/Tailscale infra

App Categories:

• platform-system: cert-manager, external-dns, external-secrets, gateway-api, istio, istio-base, prometheus-blackbox-exporter, reloader, tailscale-router, victoria-logs-collector, victoria-logs-single, victoria-metrics-k8s-stack
• kube-system: coredns, k8s-gateway, k8tz, multus, nfs-provisioner
• home-automation: homeassistant, scrypted
• media: bazarr, flaresolverr, plex, plextraktsync, prowlarr, qbittorrent, radarr, recyclarr, sonarr, unpackerr
• selfhosted: atuin, changedetection, echo, karakeep, paperless, renovate-operator, restic