gitops-calavera

GitOps repository managed with ArgoCD and Kustomize. It follows an App-of-Apps pattern where a root application bootstraps all platform and workload applications across multiple environments (dev, prod).

---

Repository layout

.
├── main.py                       # Utility script entry point
├── mise.toml                     # Mise task configuration
├── pyproject.toml                # Python project dependencies
├── README.md
│
├── apps/                         # ArgoCD server configuration
│   └── argocd/
│       ├── argocd-server-patch.yml   # Patch for the ArgoCD server deployment
│       ├── in-cluster-secret.yml     # In-cluster secret for ArgoCD
│       └── kustomization.yaml
│
├── bootstrap/                    # Root kustomization — entry point for ArgoCD
│   ├── kustomization.yaml
│   ├── appprojects/              # ArgoCD AppProject definitions
│   │   ├── phase-neg20-platform-appproject.yml
│   │   └── phase-neg15-workloads-appproject.yml
│   └── apps/                    # ArgoCD Application & ApplicationSet manifests
│       ├── kustomization.yaml
│       ├── platform/            # Platform-level apps (cluster infrastructure)
│       │   ├── kustomization.yaml
│       │   ├── phase-00-argocd-control-plane.yml
│       │   ├── phase-10-caddy.yml
│       │   ├── phase-15-kyverno-applicationset.yml
│       │   ├── phase-16-policy-reporter.yml
│       │   ├── phase-17-kyverno-policies-applicationset.yml
│       │   ├── phase-20-argocd-ingress.yml
│       │   ├── phase-21-kyverno-ui-ingress.yml
│       │   ├── phase-neg10-bootstrap-root-app.yml
│       │   └── kyverno/
│       │       ├── values/
│       │       │   └── common.yaml                 # Shared Helm values for Kyverno
│       │       ├── overlays/
│       │       │   ├── dev/values.yaml             # Per-environment Kyverno values
│       │       │   └── prod/values.yaml
│       │       └── policies/                       # Kyverno policy definitions
│       │           ├── base/
│       │           │   ├── disallow-latest-tag.yaml
│       │           │   └── kustomization.yaml
│       │           └── overlays/
│       │               ├── dev/kustomization.yaml
│       │               └── prod/kustomization.yaml
│       └── workloads/           # Workload fanout apps
│           ├── kustomization.yaml
│           ├── phase-20-workloads-apps.yml
│           └── applicationsets/
│               └── workloads-apps/
│                   ├── base/
│                   │   ├── kustomization.yaml
│                   │   └── phase-20-env-applicationset.yml   # Cluster-label-based fanout AppSet
│                   └── overlays/
│                       ├── external-prod/kustomization.yaml
│                       └── in-cluster/kustomization.yaml
│
├── environments/                 # Workload sources synced per environment
│   ├── dev/kustomization.yaml
│   └── prod/kustomization.yaml
│
├── scripts/                      # Operational utilities
│   ├── layout-sync-waves.py      # Visualize ArgoCD sync-wave ordering
│   └── missing-sync-waves.py     # Identify manifests without sync-wave annotations
│
└── skills/                       # Repeatable how-to patterns for this repo
    └── argocd/
        ├── README.md
        ├── show-sync-wave-output.md
        ├── static-cross-cluster-appset.md
        ├── add-environment-stage.md
        └── check-missing-sync-wave-annotations.md

Key concepts

Directory	Purpose
bootstrap/	Applied first by ArgoCD; renders AppProjects and all Application/ApplicationSet objects
bootstrap/apps/platform/	Platform capabilities that exist on every cluster (ArgoCD, Kyverno, Caddy, etc.)
bootstrap/apps/workloads/	ApplicationSets that fan out workload apps to clusters by env label
environments/{dev,prod}/	Per-environment kustomizations consumed as targetRevision source by workload AppSets
apps/argocd/	Patches and secrets applied directly to the ArgoCD installation

Phase numbering

Applications are named with a phase-<N>- prefix to communicate dependency order. Lower phase numbers are reconciled first. Negative phase numbers run before ArgoCD's own post-install hook.

---

Skills

The skills/ directory contains self-contained how-to guides for common operational tasks in this repository. Think of them as runbooks you can hand to a human or an AI coding agent.

skills/argocd/

Skill	Description
README.md	Quick-reference checklist: when to use the platform-static pattern vs. the workload-fanout pattern, and project permission reminders
show-sync-wave-output.md	Display ArgoCD sync-wave ordering via layout-sync-waves task (JSON output)
check-missing-sync-wave-annotations.md	Identify manifests without sync-wave annotations to ensure consistent deployment ordering
static-cross-cluster-appset.md	Step-by-step guide for creating a single ApplicationSet that deploys a platform app to all clusters with per-environment overlays
add-environment-stage.md	End-to-end checklist for adding a new environment (e.g. stage) — covers cluster labels, AppSet generators, overlays, and AppProject permissions

---

Development tasks

This repository uses Mise for task automation. Run tasks with mise run <task-name>:

Task	Description
layout-sync-waves	Scan manifests and display sync-wave ordering (JSON output)
missing-sync-waves	Identify manifests missing sync-wave annotations (JSON output)

Example:

mise run layout-sync-waves bootstrap           # Show waves in bootstrap directory
mise run missing-sync-waves apps/              # Check what's missing annotations

Getting started

1. Bootstrap — point ArgoCD at bootstrap/ in this repo. ArgoCD will render the root Kustomization and create all AppProjects and Applications automatically.
2. Register a cluster — label the cluster secret with env: dev or env: prod (see skills/argocd/add-environment-stage.md if you need a new environment value).
3. Add a platform app — follow the pattern in skills/argocd/static-cross-cluster-appset.md and drop the new ApplicationSet under bootstrap/apps/platform/.
4. Add a workload — add it to the relevant environments/{dev,prod}/kustomization.yaml; the existing workload ApplicationSet will pick it up automatically.
5. Validate — always run kustomize build bootstrap and resolve all errors before merging.