AR
ArgoCD Configuration Conventions
Application manifest structure, naming, and project organization
Details
Language / Topic
Argo CDCategory
Style Guide
Rules
balanced
- Define every Application as a declarative YAML CRD in Git — never create applications imperatively via the UI or CLI in production
- Use ArgoCD Projects to group related applications and enforce RBAC, source repo restrictions, and destination cluster/namespace boundaries
- Follow consistent naming: `<team>-<app>-<env>` for Application names, matching the target namespace and Helm release name
- Store Application manifests separately from the Kubernetes manifests they deploy — keep a dedicated `argocd/` directory in your GitOps repo
- Add standard labels to all Application CRDs: `app.kubernetes.io/part-of`, `argocd.argoproj.io/instance`, and team/environment labels for filtering
- Define every Application as a declarative YAML CRD committed to Git — never create apps imperatively via the ArgoCD UI or CLI for production workloads
- Use ArgoCD Projects to group related applications and enforce RBAC boundaries, restricting which Git repos, clusters, and namespaces each project can access
- Follow consistent naming conventions: `<team>-<app>-<env>` for Application names (e.g., `payments-api-prod`), aligning with the target namespace
- Store Application CRDs in a dedicated `argocd/` or `apps/` directory, separate from the Kubernetes manifests they reference — clear separation of concerns
- Apply standard labels on all Applications: `app.kubernetes.io/part-of`, `argocd.argoproj.io/instance`, and custom labels for team, environment, and tier
- Pin `spec.source.targetRevision` to a specific branch, tag, or commit SHA — avoid `HEAD` in production to prevent unreviewed changes from deploying automatically
- Use `spec.destination.namespace` explicitly on every Application — never rely on the default namespace to prevent accidental cross-namespace deployments
- Set `spec.project` on every Application to a non-default project — the `default` project has no restrictions and bypasses all RBAC guardrails
- Use Finalizers (`resources-finalizer.argocd.argoproj.io`) on Applications to automatically clean up deployed resources when the Application CRD is deleted
- Organize repos with a clear directory structure: one directory per environment or cluster, with Kustomize overlays or Helm value files per environment
- Keep Application CRD manifests as static as possible — avoid templating Application specs with Helm; use ApplicationSets for dynamic generation instead