julianobarbosa/progressive-delivery

Progressive Delivery

Two complementary tools for moving versions safely through Kubernetes environments:

• Argo Rollouts — replaces Deployment with a Rollout CRD that supports canary, blue-green, and metric-gated automated analysis. Handles traffic shaping at the cluster/service-mesh layer.
• Kargo — extends GitOps with promotion logic. Tracks Freight (versioned bundles of artifacts) and promotes it through Stages (dev → staging → prod) via Warehouses (sources) and verification steps.

ArgoCD continues to do what it does (sync desired state → cluster). Rollouts decides traffic split during a single deploy. Kargo decides when the next stage gets the new version.

Scope routing

| If you need to… | Read | |---|---| | Canary / blue-green / metric-gated deploy of a single workload | References/argo-rollouts.md + References/argo-rollouts/ | | Promote a version across dev → stg → prod with manual or automated gates | References/kargo.md + References/kargo/ | | Both (Rollouts as the deploy strategy inside a Kargo-managed promotion) | Read both; Kargo invokes ArgoCD which deploys a Rollout |

Mental model

Kargo:    Freight v1.2.3 -> [dev stage] -> verify -> [stg stage] -> verify -> [prod stage]
                                                                              |
                                                                              v
ArgoCD:                                                                   syncs Rollout manifest
                                                                              |
                                                                              v
Rollouts:                                                          canary @ 10% -> analysis -> 50% -> 100%

When NOT to use

• Simple Deployment rollouts that don't need traffic shaping or analysis gates — vanilla Kubernetes Deployments are fine.
• Manual promotion via PRs editing target revision — that's the core argocd skill, not this one.
• Feature flags and runtime percentage rollouts inside the app — that's an application concern (LaunchDarkly, Unleash, etc.), not a deployment one.

Gotchas

• Rollouts replaces Deployment; it is not an addition. Migrating an existing app means changing the resource kind. Plan for one revision of downtime if not handled with kubectl-argo-rollouts conversion.
• AnalysisTemplate metrics queries are scoped to the Rollouts controller's permissions. If your Prometheus is in another namespace, the controller needs RBAC or a service-account token.
• Kargo Freight is immutable. Once produced, you don't edit it — you produce new Freight. Trying to "patch" a Stage's current Freight is an anti-pattern.
• Kargo + ArgoCD integration requires Kargo's controller to have permission to update ArgoCD Application CRs. Default install doesn't grant this — read the Helm values for argocd.permissions.
• Verification steps run between stages, not within them. A failing verification doesn't roll back the prior stage — it just blocks promotion forward. If you need rollback, that's a separate Rollouts-level analysis.