How Argo Rollouts adds progressive delivery to Argo CD
A platform team that already syncs Deployments through Argo CD can add canary and blue-green releases without writing release scripts by installing Argo Rollouts, a Kubernetes controller with its own custom resource definitions. Argo Rollouts does not sit beside Argo CD as a separate release tool. You replace the Deployment in each workload with a Rollout resource that carries the same pod template plus a strategy block describing how traffic moves to the new version and when promotion or rollback happens. The Rollout manifest lives in Git like any other manifest, Argo CD syncs it to the cluster, and the Argo Rollouts controller then creates and scales the ReplicaSets that the strategy calls for. Argo CD continues to own desired state, and the controller owns the step-by-step progression within that state.
Two integration points do the actual work. The first is traffic shifting. Argo Rollouts can move traffic through NGINX, AWS ALB, Apache APISIX, Istio, Linkerd and SMI, so the router you already run determines how weights are applied. The second is metric analysis, where an AnalysisTemplate queries a provider such as Prometheus, Datadog or New Relic and the controller promotes or aborts a release based on the result. Confirm which router and provider your clusters already expose, since each one needs its own configuration, and confirm that the Argo CD version you run reports Rollout health correctly before relying on it. The health status is what lets Argo CD show a paused or degraded canary instead of a green application.
Plan the ownership boundary before the first sync. Decide which team writes the AnalysisTemplate and which team can change the strategy steps, because a permissive analysis or a missing abort condition turns the rollout into an unattended change. Also decide whether existing Deployment objects are converted in place or migrated workload by workload, and check that no other controller, such as a Horizontal Pod Autoscaler configured against the old Deployment, still targets the removed resource. The rest of this page covers those decisions and the build sequence for each router.
What you need in place before the first Rollout
A Rollout only behaves as designed when the platform under it is ready. The cards below cover the Argo CD and cluster baseline, the traffic router, the metrics source and the Git path that together let Argo CD and Argo Rollouts shift traffic, analyze results and report health.
A working Argo CD installation
Argo CD must already reconcile applications in the cluster where the Rollouts will run, so that Rollout manifests in Git are synced and their status appears in the Argo CD UI. Confirm which Argo CD minor version you run and check that it is still in the supported patch window described in the release process. Decide early whether Argo CD manages the Argo Rollouts controller itself or whether your platform team installs it separately.
A Kubernetes cluster you control
Progressive delivery adds controllers, ingress or mesh configuration and metric queries to the cluster, so the target must be one your team can change and roll back. Confirm with the Argo Rollouts documentation which controller release matches your Kubernetes and Argo CD versions, because this page does not pin one. Check that the cluster policy allows the Rollouts CRDs and the controller's service account to read Services, Ingresses and traffic-router objects.
A traffic router for shifting weight
Canary weights are applied by the traffic layer, so you must choose one of NGINX, AWS ALB, Apache APISIX, Istio, Linkerd or SMI before writing a Rollout. Each option has its own ingress or mesh objects, its own weight semantics and its own version constraints. Confirm that the router is installed, reachable from the stable and canary Services, and that the controller can read and write the objects it needs.
A metrics provider for analysis
Automatic promotion and rollback depend on a query that returns a result the controller can judge. Prometheus is the common choice, but Datadog and New Relic are also supported providers. Confirm that the provider already holds the request, error and latency series for the service, that queries return within the analysis interval, and that the platform team owns the alert and dashboard path that will show a failed analysis.
Git access for Rollout manifests
Rollout, AnalysisTemplate and traffic-router manifests should live in the same Git path as the rest of the application, so that a change to a canary step is reviewed like any other change. Confirm that the repository is registered with Argo CD, that its credentials are scoped to the application project, and that the team agrees who approves changes to analysis thresholds. Keep these manifests out of any path that Argo CD prunes unintentionally.
Ownership and rollback rights
Someone must be able to pause, promote, abort or roll back a Rollout at 2 a.m. without waiting for a Git change to merge. Name the people or group allowed to run these actions through the Argo Rollouts command line or UI, and confirm that the Argo CD project role grants them only the verbs they need. Agree in writing which team owns the analysis result when it fails.
Choosing the traffic router for canary weights
With NGINX, Argo Rollouts manages a stable Ingress and a canary Ingress for the same host, then changes the share of traffic sent to the canary as the rollout advances. The controller edits the canary Ingress settings that the NGINX ingress controller reads, so the request path stays the same and only the split moves. This is the most direct option when NGINX already fronts the application.
- Existing ingress controller: The team must already run an NGINX ingress controller in the cluster, with the stable Ingress serving production traffic.
- Managed canary Ingress: Argo Rollouts creates and updates the canary Ingress, so teams should not hand-edit it in Git alongside the rollout.
- Annotation support: Confirm which canary annotations your controller version reads for weighted routing and whether the Argo Rollouts NGINX section covers that version.
- Header and cookie rules: Confirm whether your controller version supports header-based or cookie-based routing to the canary before you rely on it for targeted testing.
Check the Argo Rollouts traffic routing documentation and your ingress controller's canary documentation together, since each project defines part of the behavior.
With AWS ALB, the AWS Load Balancer Controller turns an Ingress into an Application Load Balancer, and Argo Rollouts adjusts the weights between two target groups behind that load balancer. The split happens at the load balancer, so application pods do not need a mesh sidecar. Every weight change is an update to an AWS resource, which affects rollout timing and the cost you pay directly to AWS.
- AWS footprint: The team must run on AWS, with the AWS Load Balancer Controller installed and IAM permissions to manage load balancers and target groups.
- Two target groups: Stable and canary Services each map to a target group, and the controller changes the forward weights between them.
- Annotation keys: The controller reads ALB annotations on the Ingress, so confirm the exact keys and the controller version your Argo Rollouts release expects.
- Health checks and quotas: Confirm target group health check settings and the ALB limits and pricing for your Region, since the load balancer is a billed resource in your own account.
Confirm the controller version, IAM policy and ALB behavior in the AWS Load Balancer Controller documentation alongside the Argo Rollouts ALB section before you commit.
With Apache APISIX, Argo Rollouts changes the weights on a route in the gateway, so APISIX becomes the traffic split point. This suits teams that already run APISIX as their API gateway. The deployment mode and the versions decide how the controller reaches the gateway, so confirm both during design. The APISIX deployment modes documentation describes the options in detail.
- Traditional mode: The data and control planes run together with etcd. Client traffic uses port 9080 and the Admin API uses port 9180. Controlling weights through an API means the Admin API must be reachable from the controller, so restrict access to port 9180.
- Standalone mode: Configuration comes from a YAML or JSON file that APISIX checks every second. Route weights would need to be produced as files, so confirm with the project whether this fits your Argo Rollouts workflow.
- Version pairing: APISIX 3.19.0 was released September 28, 2026, and APISIX Ingress Controller 2.2.0 on August 18, 2026. Match your gateway and ingress controller versions to the Argo Rollouts APISIX support you plan to use. The downloads page does not mark either release as long-term support, so plan your own upgrade path.
- Plugins on the route: Authentication and other plugins on the canary route apply to canary traffic too, so review them before the split.
Check the Argo Rollouts APISIX section and the deployment modes documentation together, then test a route weight change on a non-production gateway first.
With Istio, Argo Rollouts updates the weights on a VirtualService that routes between stable and canary Services, so the split happens in the mesh's proxies. The team must already operate Istio, which brings its own control plane, certificates and proxy lifecycle. Argo Rollouts also supports Linkerd and SMI, which follow the same weighted-routing idea through their own resources.
- Mesh prerequisite: Istio must be installed and the application workloads must be part of the mesh, and the team must own the Istio upgrade cadence.
- Existing VirtualService: The VirtualService must already exist and reference stable and canary destinations, which the controller then weights.
- Linkerd and SMI: Both are listed among the traffic routers Argo Rollouts supports. Confirm the resource types, mesh versions and features each one requires in its own documentation.
- Operating overhead: Confirm the cost of running sidecars or gateways, the mTLS configuration and the observability you already have before adopting a mesh for canary routing alone.
Check the Argo Rollouts traffic routing reference for your mesh and version, then confirm the VirtualService fields in the Istio documentation.
How to configure a canary Rollout in sequence
This sequence takes one existing Deployment managed by Argo CD and turns it into a canary Rollout with traffic routing and metric analysis, so each release is shifted, measured and promoted or rolled back from Git. Each step ends with a check you can run before moving on.
Install the Argo Rollouts controller
A platform engineer installs the Argo Rollouts controller and its CRDs into the target cluster, usually through the project's manifests or a Helm chart that your team has reviewed and pinned to a version. Confirm the controller version and the chosen install method with the Argo Rollouts documentation before you start. The step is complete when the controller pod is running in its namespace and the Rollout, AnalysisTemplate and Experiment resource types are available to kubectl. You can list them with
kubectl get crdto confirm.Convert the Deployment into a Rollout
In the Git repository that Argo CD watches, replace the Deployment manifest with a Rollout that keeps the same pod template, labels and selector, and add a canary strategy with ordered steps such as a small initial weight, a pause and a larger weight. Keep the change in its own commit so the diff is easy to review. Argo CD syncs the change, and the controller takes over the ReplicaSets. The check is
kubectl argo rollouts get rollout <name>showing the Rollout as Healthy at the first step, with the stable and canary ReplicaSets listed.Define the traffic routing block
Add a trafficRouting section to the canary strategy that names your router, such as NGINX, AWS ALB, Apache APISIX or Istio, and points to the stable and canary Services the controller should manage. The router-specific fields differ, so confirm them against the documentation for your ingress controller or mesh version. Your team owns the ingress or mesh objects that the router reads. The check is that the controller reports the expected canary weight on the router, and the traffic split matches that weight in your gateway metrics or the router's own status.
Add an AnalysisTemplate for the metrics provider
Create an AnalysisTemplate that runs a query against your metrics provider, for example a PromQL query against Prometheus for error rate or latency on the canary pods, and sets a success condition and failure limit. Use labels that separate canary from stable traffic so the query reads only the new version. Reference the template from the canary steps so the controller runs it during the rollout. The check is an AnalysisRun that completes with a Successful result when the metric is healthy, and a Failed result that triggers a rollback when it is not.
Commit the change and let Argo CD sync
Commit the Rollout, the routing configuration and the AnalysisTemplate to the same Git path, then let Argo CD detect the change and sync the application. Confirm that Argo CD shows the Application as Synced and that the Rollout health reflects the controller's state, since Argo CD reads Rollout health through the Argo Rollouts health check. Do not edit the live Rollout by hand, because the next sync would revert it. The check is the Application status in Argo CD matching the Rollout status reported by the controller.
Promote or roll back and verify the result
Run a new image version through Git, watch the canary steps advance, and confirm that the AnalysisRun passes before the rollout moves to full traffic. Then test a deliberately failing version in a non-production cluster to confirm that the analysis fails and the controller aborts and rolls back to the stable ReplicaSet. Record both results and the Argo CD sync history as evidence for your change process. The step is complete when both the promotion path and the rollback path have been observed.
How metric analysis decides promotion or rollback
The quality of a canary decision is only as good as the metrics the analysis run queries. An analysis run is the check Argo Rollouts performs during a canary step to decide whether the new version advances or aborts. If the query measures the wrong thing, or measures the right thing in a way that hides failures, the rollout will promote a bad release or roll back a good one. Before you wire any metric into an AnalysisTemplate, confirm that the series exist for the new and stable ReplicaSets, that labels distinguish the two, and that the query returns a value over the window you plan to use. Argo Rollouts documents Prometheus, Datadog, New Relic and other providers as sources, so the first decision is which system already holds the signals your service level depends on.
Prometheus pulls metrics over HTTP from targets it discovers or is configured to scrape, and analysis queries are written in PromQL. Prometheus documents that it values reliability over precision and is not a suitable choice where every event must be counted exactly, such as per-request billing. For rollout decisions this means a small gap in scrapes or a rate computed over a short window can shift a canary's error ratio enough to change the outcome. Plan the scrape interval and the analysis window together, and test the query against recent traffic before trusting it. Also decide where the data lives. Prometheus local storage is not clustered or replicated and should be operated like any single-node database, so a failed or rebuilt Prometheus can leave a rollout without history. If you need long-term retention or a replicated store, confirm the remote write setup and how the analysis query reaches the data during an outage.
Alertmanager serves a different purpose and should not be mistaken for the rollout gate. It groups, silences and routes alerts from Prometheus to people, and it can run as a cluster for high availability. Analysis runs decide promotion or rollback automatically, while Alertmanager notifies on-call engineers about conditions they should look at. Keep both: use analysis for the immediate release decision and alerts for the operational signal that follows. Confirm with your monitoring owners which metrics both paths depend on, since a metric that disappears will break promotion silently unless an alert also covers the missing data.
Which Rollout fields map to routers and metrics
This table maps the Rollout strategy fields for canary and blue-green releases to the Kubernetes objects, external systems and owning teams they touch. Use it to decide who sets each value and what to confirm against the Argo Rollouts documentation for your installed version. The main takeaway is that traffic weights, pause durations and analysis thresholds depend on decisions from three groups, so agree ownership before the first production Rollout.
| Field or object | Kubernetes object and external system | Owned by |
|---|---|---|
| Canary steps and setWeight | Rollout spec; the traffic router (NGINX, ALB, Istio or APISIX) receives the weight | Service team, agreed with platform team |
| Canary pause duration | Rollout spec steps; no external system, but Argo CD health waits on it | Service team |
| Blue-green activeService and previewService | Rollout spec; two Kubernetes Services selected by the Rollout | Platform team sets the pattern, service team names Services |
| Blue-green autoPromotionEnabled | Rollout spec; controls whether promotion waits for a manual step | Service team with release owner approval |
| Traffic router settings (ingress, mesh or gateway reference) | Rollout spec referencing Ingress, VirtualService or APISIX route; the router applies weights | Platform team |
| AnalysisTemplate metric queries | AnalysisTemplate CRD; queries the metrics provider such as Prometheus | Service team writes queries, security reviews data sources |
| AnalysisTemplate success and failure conditions | AnalysisTemplate CRD; decides automatic rollback | Service team with SRE sign-off |
| Metric provider credentials and endpoints | Kubernetes Secret or provider config; reaches the metrics system | Security team |
Security controls for progressive delivery
A canary or blue-green release is only as trustworthy as the manifests, permissions and credentials behind it. The controls below cover who can change a rollout, what a service team can reach, and how analysis and traffic routing are protected.
Git review for rollout manifests
Rollout and AnalysisTemplate resources decide how much traffic reaches a new version and what counts as healthy. Treat changes to them like changes to production code: require review by someone outside the owning team for any edit to step weights, pause settings or analysis thresholds. Argo CD authenticates API requests only with JWTs, so the Git review gate is the control that decides who can alter a release. Check that branch protection covers the repositories holding rollout definitions.
Project boundaries for traffic changes
Argo CD projects limit which repositories, destination clusters and namespaces an application may use. Scope each service team's project so it cannot create or edit routing resources that belong to another service, such as a shared ingress or a mesh virtual service. Without this boundary, a team with sync rights can redirect traffic meant for someone else. Confirm that project roles grant sync access only for the team's own applications.
Least-privilege analysis credentials
Analysis runs query metrics providers such as Prometheus, Datadog or New Relic to decide whether a rollout proceeds. Give each analysis job a read-only credential limited to the metrics its template needs, and store it as a Kubernetes Secret in the namespace that runs the analysis. Do not reuse cluster-admin or write-capable tokens for this purpose. Argo CD redacts cluster, Git and OAuth2 credentials from API responses and logs, but analysis credentials stored in your own manifests need the same care.
Protecting the traffic router
NGINX, ALB, APISIX or Istio control the split between stable and canary traffic, so their admin interfaces are part of the release path. Restrict admin APIs and configuration endpoints to the controllers that need them, and limit who can edit gateway resources directly. For APISIX, the Admin API listens on port 9180 in traditional mode, so keep it off client-facing networks. Review whether the rollout controller's service account can change routing objects it does not own.
TLS between Argo CD components
Argo CD uses TLS for traffic between its own components, and the rollout controller depends on that path to read and update cluster state. Keep the default TLS configuration in place and do not disable it to simplify a test environment. Also keep the repo-server in mind: it runs Helm and Kustomize on repository content, so a rollout manifest sourced from an untrusted repository is a risk even when the rollout logic is sound. Confirm that only approved repositories feed the rollout applications.
Common failures in canary weights and analysis
This table lists the failures teams most often hit when canary weights or analysis runs misbehave, with the likely cause and first fix for each. Read it as a triage list: match the symptom you see, check the likely cause, then confirm the fix against the Argo Rollouts and Argo CD documentation for your installed versions.
| Symptom | Likely cause | Fix |
|---|---|---|
| Analysis run never completes | The metrics query returns no data, often because the label selectors do not match the canary pods or the metric provider has no samples yet | Run the query by hand against the same provider, confirm the labels Argo Rollouts injects for canary and stable pods, and adjust the query or the analysis interval |
| Traffic weights do not change | The traffic router configuration in the cluster differs from what Rollout declares, or the ingress or mesh object is managed by another tool | Check the Rollout status and the router object (NGINX, ALB, Istio or APISIX) for drift, remove competing manual edits, and confirm the router integration in the Argo Rollouts documentation |
| Application shows Progressing or Degraded during a paused step | A paused Rollout waiting for manual promotion or a timed pause is reported as not yet healthy by Argo CD's health check | Confirm the Rollout health assessment in the Argo CD version you run, promote or abort the Rollout intentionally, and review the Argo Rollouts health documentation for expected states |
| Rollback does not restore the stable ReplicaSet | The stable revision was never recorded correctly, or Git still declares the new image so Argo CD reapplies it after an abort | Revert the image or spec in Git to the known-good revision, then confirm how the abort and stable pointer behave in the Argo Rollouts version you run |
| Sync fails because a Deployment and Rollout target the same workload | A leftover Deployment selects the same pods as the Rollout, or both resources are tracked by the same Argo CD application | Remove the Deployment from Git and the cluster, keep only the Rollout, and check resource tracking settings in the Argo CD documentation for your version |
| Canary pods receive no traffic despite healthy status | The stable and canary Services point to the wrong selectors, or the traffic router is not configured for the chosen strategy | Compare the Service selectors with the pod template labels, then verify the traffic routing setup for your router against the Argo Rollouts documentation |
| Analysis passes but the release regresses | Analysis templates check too few signals, such as only error rate, or the sample window is too short to show slow degradation | Add latency and saturation checks, lengthen the analysis window where traffic allows, and confirm the metric semantics with your monitoring team |
| Manual promotion ignored after a sync | Argo CD resyncs the Rollout from Git and overwrites the status or pause fields the team changed in the cluster | Drive promotion through the Rollout tooling or Git-driven changes rather than direct edits, and confirm sync and ignore-difference behavior for your Argo CD version |
What progressive delivery costs and what it asks from your team
What drives the cost of a progressive delivery setup with Argo Rollouts?
The cost depends mainly on how many services move to canary or blue-green releases, which traffic router and metric source they already use, and how much analysis logic has to be written. Cost comes from four places: design (choosing strategies per service and deciding what counts as a healthy release), configuration (Rollout resources, traffic routing and AnalysisTemplates), testing (proving that a bad release is caught and rolled back), and run support after go-live. Argo CD and Argo Rollouts themselves are open source under the Apache License 2.0, so the spend is on people, infrastructure and the time to build and maintain the setup. Ask any quote to list these four items separately, with the services in scope named.
Can our in-house platform team build progressive delivery without outside help?
Yes, many teams do, provided someone owns the Kubernetes, Argo CD and traffic routing skills at the same time. The harder parts are not the Rollout manifest itself but the traffic split, the metric queries that decide promotion, and the rollback path when analysis fails. Check whether your team already runs your ingress or service mesh in production, has a metrics backend that answers queries quickly, and can practice rollbacks outside business hours. If any of these is missing, an outside partner can cover that gap, and your team keeps the work it needs to run the setup afterwards.
How long does a progressive delivery implementation take?
Duration depends on the number of services, how many traffic routers and metric providers are involved, and how much existing deployment work must be converted. A single service on a router you already operate is much smaller than a fleet of services across two gateways and two monitoring stacks. Ask the partner to break the timeline into design, a pilot service, rollout to the remaining services, and a rollback test, and to name what has to be ready before each phase starts, such as cluster access, metric data and change approval.
What depends on our traffic router and metrics setup?
Traffic shifting and automatic rollback both depend on what is already in place. Argo Rollouts can shift traffic through NGINX, AWS ALB, Apache APISIX, Istio, Linkerd and SMI, and can drive promotion or rollback from metrics in providers such as Prometheus, Datadog and New Relic. Each router needs its own configuration, and each metric provider needs queries that return reliable data for the release window. Confirm which router handles production traffic for each service, which metric source reports error rate and latency, and whether those signals are trusted enough to stop a release automatically. Gaps here are often the largest source of extra work.
What does the work ask from our application and platform teams?
Application teams must define what a healthy release looks like for their service, including the error and latency thresholds, the warm-up period and the endpoints that represent real traffic. Platform teams provide the cluster, the ingress or mesh, Argo CD access, the metrics backend, and an approval path for production changes. Both teams should expect to review the first few releases together. Ask for a written list of who supplies each input and by which date, so the work does not stall waiting for access or metric definitions.
Does progressive delivery need ongoing tuning after go-live?
Yes, most setups need some ongoing tuning. Thresholds that fit one release period can produce false rollbacks after traffic patterns change, new services add metrics that need analysis, and Argo CD and Argo Rollouts releases bring version updates that must be tested on the same routing paths. These activities recur, so they belong in the run cost. Ask whether the quote includes a support period after go-live, what a tuning request costs under a retainer, and who on your side approves changes to analysis thresholds.
What should we request in a written scope before hiring a partner?
Request a scope that names each service in progressive delivery, the traffic router and metric provider for each, the strategy chosen (canary or blue-green), and the rollback criteria. Ask for the deliverables in writing: Rollout and AnalysisTemplate resources in Git, a documented promotion and rollback runbook, test evidence showing an automatic rollback, and handover of access and knowledge. Also ask which items are one-time and which recur, what is excluded, and how changes after signing are priced. Fixed-scope engagements agree these points before work starts, which makes comparing quotes far more reliable.
How DeployOpen scopes and delivers progressive delivery
DeployOpen plans, implements, tests and documents Argo Rollouts inside your Argo CD installation and the clusters you control. Each engagement starts from a written, fixed scope that names the workloads, traffic providers, metric sources and rollback rules before any build begins.
How we scope
- Inventory which services get canary or blue-green releases and which stay on plain Deployments
- Confirm the traffic provider for each cluster, such as NGINX, ALB, Istio or APISIX, before writing any Rollout
- Agree the metrics, thresholds and rollback conditions that analysis will use, with owners named
- Record scope, deliverables and timelines in writing, with ongoing support available as a retainer
How we build
- Write Rollout resources and analysis templates in Git so Argo CD manages them like other manifests
- Configure traffic shifting and verify weights against the chosen ingress or mesh in a non-production cluster
- Set Argo CD health handling for Rollouts so paused or degraded releases show accurately in the UI
- Test automatic rollback with deliberately failing revisions and document the observed behavior
How we hand over
- Deliver a runbook covering promotion, abort, manual pause and rollback steps for each team
- Document the metric queries, thresholds and the reasoning behind each analysis gate
- Walk platform and application teams through the release flow using your own services as examples
- Confirm access, RBAC scope and who may approve promotions before the handover closes
How we support
- Review Argo Rollouts and Argo CD version changes against the release notes before upgrades are scheduled
- Retest analysis templates when metric providers, labels or dashboards change
- Available as a retainer for patching, upgrades, tuning and periodic release drills
- Confirm support boundaries and response expectations in the written agreement
