ArgoCD Configuration
These pages often point at shared systems. Confirm the cluster, namespace, and ownership boundary before running mutating commands.
This page explains how the dev cluster keeps itself in sync with Git.
ArgoCD is the deployment robot. You change the deployment repo, and ArgoCD makes the cluster match it.
It watches crawbl-argocd-apps, renders the manifests for each component, and applies them to the cluster.
Every change is a commit with an author and a diff, with no kubectl apply from laptops.
App-of-Apps Pattern
One top-level ArgoCD application, crawbl-apps, points to the root/ directory.
That directory contains one ArgoCD Application object per component. If the phrase Application CR is unfamiliar, it simply means "the Kubernetes object that tells ArgoCD how to deploy one component."
ArgoCD reads those child applications and manages each one independently.
If the phrase "app-of-apps" is unfamiliar, the practical meaning is simple: one parent ArgoCD object points at many child applications so the whole cluster can be managed from one entry point.
Each application in root/ references components/<name>/chart with values from components/<name>/envs/dev.yaml. ArgoCD clones the repo, renders the chart, and applies it.
platform-resources is a special component with no chart. It holds shared raw manifests such as namespaces, ArgoCD ingress routing, and bootstrap RBAC.
Apps Repo Structure
crawbl-argocd-apps/
├── root/ # One Application YAML per component
│ ├── cert-manager.yaml # Wave 1
│ ├── envoy-gateway.yaml # Wave 1
│ ├── platform-resources.yaml # Wave 0
│ ├── external-secrets.yaml # Wave 2
│ ├── metacontroller.yaml # Wave 3
│ ├── postgresql.yaml # Wave 5
│ ├── redis.yaml # Wave 5
│ ├── external-dns.yaml # Wave 5
│ ├── orchestrator.yaml # Wave 6
│ ├── docs.yaml # Wave 6
│ └── pgweb.yaml # Wave 6
└── components/ # One directory per component
└── <name>/
├── chart/ # Vendored Helm chart
├── envs/dev.yaml # Per-environment values
└── resources/ # Raw K8s manifests (if needed)
Why Deployment Order Matters
Some components depend on earlier components already being available.
To handle that, ArgoCD uses sync waves.
Lower waves deploy first. ArgoCD waits for all resources in a wave to be healthy before starting the next. If a wave fails, subsequent waves do not deploy.
| Wave | Applications | Why |
|---|---|---|
| 0 | platform-resources | Shared namespaces and bootstrap manifests must exist first. |
| 1 | cert-manager, envoy-gateway | Core platform addons. |
| 2 | external-secrets | Secret sync controller after the base platform is ready. |
| 3 | metacontroller | Installs Metacontroller plus the UserSwarm CRD, webhook, and reaper resources. |
| 5 | postgresql, redis, external-dns | Shared data services and DNS automation. |
| 6 | orchestrator, docs, pgweb | User-facing workloads that depend on the layers above. |
Vendored Charts
Helm charts are vendored directly into components/<name>/chart/ rather than pulled at deploy time.
In plain language, we keep an exact local copy of the chart in the repo instead of asking ArgoCD to fetch it live during deploys.
This avoids external registry failures during sync and prevents OOM kills from downloading large charts.
| Chart | Version |
|---|---|
| cert-manager | v1.20.0 |
| envoy-gateway | v1.7.0 |
| external-secrets | 0.9.x |
| postgresql (Bitnami) | 18.5.14 |
| redis (Bitnami) | 25.3.9 |
| external-dns | 1.16.1 |
| ArgoCD (Pulumi-managed) | 7.8.13 |
Sync and Health Status
| Sync Status | Meaning |
|---|---|
| Synced | Cluster matches Git |
| OutOfSync | Git has unapplied changes (auto-syncs within 3 min) |
| Health Status | Meaning |
|---|---|
| Healthy | All resources running and ready |
| Progressing | Creating or updating resources |
| Degraded | Something is wrong — check pod logs |
Adding a New Application
If you are adding a new app, follow this flow:
Vendor the chart
Pull the chart into components/<name>/chart/ so the repo owns the exact deploy input.
helm pull <repo>/<chart> --version <v> --untar -d components/<name>/chart/
Create values
Add environment-specific overrides in components/<name>/envs/dev.yaml.
Create the Application
Add root/<name>.yaml and set the sync wave based on the app's dependencies.
Commit and push
ArgoCD auto-syncs within 3 minutes, so the repo commit is the deploy trigger.
To pick the right wave, list the new app's dependencies, find the highest wave among them, and use the next wave.
Dashboard Access
If you only need to check status, the web dashboard is usually the simplest option.
kubectl port-forward svc/argocd-server -n argocd 8080:443
# Open https://localhost:8080
# Username: admin
# Password:
kubectl -n argocd get secret argocd-initial-admin-secret \
-o jsonpath="{.data.password}" | base64 -d
🔗 Terms On This Page
If a term below is unfamiliar, open its glossary entry. For the full list, go to Internal Glossary.
- ArgoCD: The GitOps deployment system that keeps the cluster aligned with what is committed in Git.
- GitOps: An operations model where Git is the source of truth for live cluster state.
- Application Resource: The Kubernetes object ArgoCD uses to describe how one deployable component should be synced.
- Helm Chart: A packaged set of Kubernetes templates and values used to deploy an application.
- Sync Wave: The deployment order number ArgoCD uses to make dependent apps start in sequence.