Skip to content

Architecture

alpstack is a small, affordable, self-hosted Kubernetes platform running openDesk in production. It's split across four Git repositories — each a layer that builds on the one below.

The four repos

Layer Repo Role
1 · OS talos-cluster Talos OS machine configs — bootstraps a hardened, encrypted cluster from scratch
2 · Platform platform-argocd Networking, storage, certificates, monitoring, secrets management
3 · Addons addons-argocd Add-ons layered on top (e.g. NetBird remote access, Vaultwarden)
4 · openDesk opendesk-argocd openDesk itself + its production-grade backing services

Three ArgoCD instances

The three GitOps repos are each reconciled by their own ArgoCD instance, using the app-of-apps pattern. Separation means a problem in one layer's ArgoCD can't cascade into another.

Instance (namespace) Watches namePrefix App names
platform-argocd platform-argocd repo platform platform-<app>
addons-argocd addons-argocd repo addons addons-<app>
opendesk-argocd opendesk-argocd repo opendesk opendesk-<app>

All three track revision main and deploy in-cluster (https://kubernetes.default.svc).

Repo layout (identical in all three GitOps repos)

applications/<app>/                                 # one Helm chart per application
clusters/<cluster>/applications/templates/<app>.yaml  # the ArgoCD Application CRs
clusters/<cluster>/values/<app>.yaml                # per-app cluster overrides
values/global.yaml                                  # sourceRepo, revision, namePrefix
bootstrap/                                          # one-time bootstrap resources

A root app-of-apps Application renders everything under clusters/<cluster>/applications/, and values/global.yaml is included by every Application — so changing it affects the whole layer.

Conventions

  • Chart defaults live in applications/<app>/values.yaml; cluster overrides in clusters/<cluster>/values/<app>.yaml.
  • Secrets are never committed — everything is encrypted with Sealed Secrets first. ArgoCD repository credentials go in a git-ignored values-local.yaml.
  • Networking is Cilium (also the kube-proxy replacement and host firewall).

See also: Operations · Sealed Secrets · Renovate · Storage.