Infrastructure¶
The Git source for every platform component synced by Argo CD.
Directory layout¶
| Directory | Purpose |
|---|---|
argocd/ |
Argo CD itself (root-app, projects, applications, AppProject, etc.) |
network/ |
CNI (Cilium), Service Mesh (Istio), Gateway API, CoreDNS, Cloudflare Tunnel, NetworkPolicy |
apps/ |
App components under platform management (e.g. apps/app-kensan = the new kensan's namespace/PVC/syncthing, etc.) |
observability/ |
Prometheus, Grafana, Loki, Tempo, OTel Collector |
auth/ |
Keycloak (OIDC IdP), oauth2-proxy (Gateway ext_authz), Vault OIDC auth |
secrets/ |
Vault + Vault Config Operator + Vault Database/Transit engines, External Secrets, Sealed Secrets, cert-manager, Reloader |
storage/ |
Longhorn |
policy/ |
Kyverno (policy engine + the ClusterPolicy / PolicyException set) |
backstage/ |
Deploy definitions for Backstage (developer portal) — Pattern B. Source lives at the repo top-level backstage/ (ADR-018 / ADR-020) |
kube-system/ |
Label / PSA / shared-resource management for the kube-system namespace |
Component layout rules¶
Each component directory's file layout branches into two shapes depending on whether a values.yaml is present. The deciding question: does the Argo CD app render a Helm chart?
Pattern A: Helm-chart-based (values.yaml + resources/)¶
Components where an Argo CD multi-source app combines an upstream Helm chart + values.yaml + additional raw YAML.
<component>/
├── values.yaml # Helm values
└── resources/ # Raw YAML outside the chart (namespace, ServiceMonitor, HTTPRoute, SealedSecret, etc.)
└── *.yaml
Examples: secrets/vault/, network/cilium/, observability/grafana/, observability/prometheus/, secrets/cert-manager/, secrets/external-secrets/, secrets/vault-config-operator/, observability/otel-collector/, observability/loki/, observability/tempo/
resources/ exists to separate out the YAML that Helm doesn't render. It only makes sense alongside a values.yaml, so don't create it for components that have none.
Pattern B: raw YAML only (flat)¶
Components with no Helm chart, where the Argo CD app reads raw manifests directly.
Examples: network/network-policy/, network/cloudflare-tunnel/, network/gateway-api/, secrets/sealed-secrets/, and the Gateway / PeerAuthentication / namespace, etc. directly under network/istio/
Place .yaml files directly at the top level. No resources/ indirection.
Exceptional structures¶
istio/: a multi-component directory bundling several charts (base/,cni/,istiod/). Each subchart follows Pattern A with its own<subchart>/values.yaml. Raw YAML that belongs to Istio as a whole but sits outside any chart (Gateway, PeerAuthentication, theistio-systemnamespace, etc.) is placed flat directly underistio/(Pattern B).network-policy/: a special component that aggregates NetworkPolicy / CiliumClusterwideNetworkPolicy across namespaces. To keep PE-exclusive resources in one place, these are split out from each namespace-owning app and consolidated into thenetwork-policyapp.observability/: has noapp.yaml. The ApplicationSet atargocd/applications/observability/applicationset.yamluses a git generator to pick up eachobservability/*/config.json(which holds the chartVersion etc.) and generates one Application per component. Eachconfig.jsonis the source of truth for that component's chart version.secrets/vault-database-engine/,secrets/vault-transit-engine/: a three-part structure of a homegrown chart (chart/) + raw YAML shared across all instances (shared/) + per-instance values (platform-values/). Configured as a pair —argocd/applications/secrets/<engine>/app-shared.yaml(syncsshared/) andapplicationset-instances.yaml(an ApplicationSet that generates one instance per file underplatform-values/) — with no singleapp.yaml.
Namespace lifecycle management¶
Most components carry resources/namespace.yaml (Pattern A) or a flat namespace.yaml (Pattern B) inside their own Application and self-contain namespace creation + labeling via CreateNamespace=true (e.g. secrets/cert-manager/, secrets/external-secrets/, secrets/reloader/, backstage/, network/cloudflare-tunnel/).
A dedicated ns-lifecycle app under kubernetes/argocd/applications/namespaces/ only exists when one of these three patterns applies (ADR-020):
| Pattern | Reason | Example |
|---|---|---|
| No owning component | No component in this repo corresponds to the namespace (e.g. one created by kubeadm outside GitOps, adopted here purely to attach labels) | kube-system |
| Multiple components share the namespace | No single owning Application can be designated (policy/kyverno + policy/kyverno-policies share policy/namespace.yaml; the 6 observability/* components share observability/namespace.yaml) |
kyverno, monitoring |
| Deliberate lifecycle isolation | There is a single owner, but the app is deliberately split off for protection (e.g. sealed-secrets — no finalizer + Prune=false to protect the sealing key) |
sealed-secrets |
Cases that are "single-owner but split off" without matching one of the above are consolidation candidates (reloader was consolidated in 2026-07, per ADR-020).
Argo CD Application placement¶
Each component's Argo CD Application CR lives at argocd/applications/<category>/<component>/app.yaml. platform-root (the App-of-Apps) recurses argocd/applications/ to discover and manage every child app.
Related documents¶
.claude/rules/helm-multisource.md: details of Pattern A (the 3-file structure for Argo CD multi-source).claude/rules/gitops-workflow.md: GitOps operating rulesdocs/: ADRs, architecture diagrams