DevOps GitOps and Packaging
Agent Workflow (MANDATORY)
Before ANY chart, overlay, Application or Flux object, spawn in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - find existing
Chart.yaml,kustomization.yaml, Argo CD or Flux manifests and the repo layout - fuse-ai-pilot:research-expert - verify fields and flags for the installed tool version at helm.sh, kubectl.docs.kubernetes.io, argo-cd.readthedocs.io, fluxcd.io
- mcp__context7__query-docs -
/websites/helm_sh,/helm/helm,/kubernetes-sigs/kustomize,/websites/argo-cd_readthedocs_io_en_stable,/websites/fluxcd_io_flux
Then read the target read-only (helm version, helm list -A, argocd version, flux check, kubectl get crd | grep -E 'argoproj|fluxcd'). After changes, run fuse-ai-pilot:sniper.
Versions (checked 2026-11-10)
Helm 4.3.1 (https://helm.sh/docs/overview/), Kustomize 5.8.3 (https://github.com/kubernetes-sigs/kustomize/releases), Argo CD 3.6.1 (https://github.com/argoproj/argo-cd/releases/tag/v3.6.1), Flux 2.10.0 (https://github.com/fluxcd/flux2/releases/tag/v2.10.0). API versions used here: argoproj.io/v1alpha1, source.toolkit.fluxcd.io/v1, kustomize.toolkit.fluxcd.io/v1, helm.toolkit.fluxcd.io/v2, image.toolkit.fluxcd.io/v1, kustomize.config.k8s.io/v1beta1. Read the installed version first (helm version, argocd version, flux version); the CRDs on the cluster win over this file.
Overview
| Area | Decision in one line |
|---|---|
| Packaging | Helm for third-party or parameterised apps; Kustomize for your own plain manifests; both only with a stated reason (helm-vs-kustomize.md) |
| Helm 4 | Server-side apply default for new releases, --atomic renamed --rollback-on-failure, --force renamed --force-replace, post-renderers are plugins (helm-4-changes.md) |
| Controller | Argo CD when a UI, multi-cluster and per-app RBAC matter; Flux when everything should be CRDs reconciled in-cluster; one controller per cluster, never both on the same objects |
| Delivery | Git is the source of truth; change Git, not the cluster; pin charts and images by version or digest |
| Pruning | Off by default or confirm; a prune is a delete (see Critical Rules) |
| Promotion | One artifact, environment-specific config only; promote by PR, not by rebuilding (repo-layout-promotion.md) |
Critical Rules
- Version first - read the tool versions and the CRDs on the cluster before writing a field; an apiVersion not in the cluster is not usable
- Render, then diff, then apply -
helm template/kustomize build, thenhelm diff upgradeorkubectl diff,argocd app diff,flux diff kustomization; never sync blind - Destructive verbs are proposed, not run -
helm uninstall,helm rollback, Argo CD sync with prune,argocd app delete --cascade,flux delete,flux suspend,kustomize build | kubectl delete -f -: exact ACTION / EFFECT / PROOF, then WAIT-FOR-GO (helm-release-ops.md) - Never hand-edit a GitOps-owned object - the controller reverts it; the fix is a commit
- No secret value in Git or in output - names and keys only, values via devops-secrets (SOPS, External Secrets);
helm template/--dry-runprint Secrets, so use--hide-secret - Pin everything - chart version,
targetRevisionas tag or SHA, image tag plus digest; noHEAD,latestor floating range in production - Never invent a field or flag - cite the official page; unknown = "not verified"
Architecture
gitops/
├── charts/<app>/ # Helm chart (Chart.yaml, values.yaml, values.schema.json, templates/)
├── apps/<app>/base/ # Kustomize base
├── apps/<app>/overlays/{staging,prod}/
├── clusters/{staging,prod}/ # per-cluster entry: Flux Kustomizations or Argo CD Applications
└── infrastructure/ # controllers and shared config, reconciled before apps
Reference Guide
Concepts
| Topic | Reference | When to Consult |
|---|---|---|
| Helm 4 changes | helm-4-changes.md | Moving from Helm 3, CI flags, SSA, plugins |
| Chart authoring | helm-chart-authoring.md | Structure, values, schema, dependencies, hooks, tests |
| Release operations | helm-release-ops.md | OCI push/pull, diff, upgrade, rollback, uninstall |
| Kustomize | kustomize.md | Bases, overlays, patches, generators, components |
| Helm vs Kustomize | helm-vs-kustomize.md | Choosing, combining, helmCharts limits |
| Argo CD | argocd-applications.md | Application, AppProject, sync policy, waves, hooks, deletion |
| ApplicationSet | argocd-applicationset-appofapps.md | Many apps or clusters, app-of-apps |
| Flux | flux.md | Sources, Kustomization, HelmRelease, suspend/delete |
| Flux image automation | flux-image-automation.md | Tag scanning and commits back to Git |
| Layout and promotion | repo-layout-promotion.md | Environments, promotion, drift, rollback, secrets pointer |
Templates
| Template | When to Use |
|---|---|
| chart/ | Minimal chart with values.schema.json (Helm templates are not parseable YAML) |
| kustomize/ | Base + prod overlay + component |
| argocd/appproject.yaml | Project limiting repos, destinations, resource kinds |
| argocd/application.yaml | Application with manual-prune safe sync policy |
| argocd/applicationset.yaml | One app per environment directory |
| flux/gitrepository.yaml | Git source |
| flux/kustomization.yaml | Reconcile a path with ordering and health checks |
| flux/helmrelease.yaml | OCI chart, remediation, drift detection |
| flux/image-automation.yaml | ImageRepository, ImagePolicy, ImageUpdateAutomation |
| gitops-repo-layout.md | Repository tree and promotion flow |
Quick Reference
CTX=prod-eu; NS=shop # always explicit
helm template web ./charts/web -f values-prod.yaml --hide-secret >/dev/null # render only
helm --kube-context "$CTX" -n "$NS" diff upgrade web ./charts/web -f values-prod.yaml # helm-diff plugin
helm --kube-context "$CTX" -n "$NS" upgrade web ./charts/web -f values-prod.yaml --dry-run=server --hide-secret
kustomize build apps/web/overlays/prod | kubectl --context "$CTX" diff -f - # exit 1 = differences
argocd app diff web --refresh # exit 1 = differences
flux diff kustomization web --path ./apps/web/overlays/prod # exit 1 = differences
flux reconcile kustomization web --with-source # after the user's go
Best Practices
DO
- Add
values.schema.jsonto every chart you own so bad values fail at render time - Keep one Application or Kustomization per deployable unit, with
dependsOnor sync waves for ordering - Give Argo CD
AppProjector Flux service accounts the narrowest repos, namespaces and kinds - Record the rollback target (chart version, Git SHA, Helm revision) in the change proposal
DON'T
- Enable automated prune or
selfHealon a production Application without the owner's go - Run
helm upgrade --reuse-valuesacross chart versions (stale values hide new defaults) - Let Argo CD and Flux, or Helm CLI and a controller, manage the same release
- Template secrets into values files committed in clear text
