DOCSEARCHbyAlgolia
Submit Docs

Argo Rollouts Documentation

repository·master·Indexed 25 days ago

https://github.com/argoproj/argo-rollouts

A Kubernetes controller providing advanced progressive delivery capabilities, including Blue-Green and Canary deployments. It features fine-grained traffic shifting via ingress or service mesh, automated rollbacks and promotions based on metric-driven analysis (Prometheus, Datadog, New Relic), and manual judgement. The project includes a set of CRDs and a kubectl plugin for managing rollouts, experiments, and analysis.

Tokens
87.4K
Snippets
202
Records
368
Agent score
86%

What's inside Argo Rollouts

  1. Overview of Argo Rollouts features

    master

    Argo Rollouts is a Kubernetes controller and set of CRDs that provides advanced deployment capabilities beyond standard Kubernetes RollingUpdate strategies.

    Key features include:

    • Blue-Green update strategy: Switch traffic between two identical environments.
    • Canary update strategy: Gradually shift traffic to a new version.
    • Fine-grained traffic shifting: Weighted traffic control via ingress or service mesh.
    • Automated rollbacks and promotions: Based on metric analysis.
    • Manual judgement: Pause rollouts for human intervention.
    • Metric-driven analysis: Customizable queries to verify business KPIs using providers like Prometheus, Datadog, or New Relic.

  2. Understand Argo Rollouts scope and limitations

    master

    Argo Rollouts is a self-contained solution that does not require Argo CD to function. However, keep the following constraints in mind:

    • Single Cluster/Deployment: It currently works with a single Kubernetes deployment/application within a single cluster.
    • Controller Deployment: If you use multiple clusters with Rollout workloads, the controller must be deployed on every cluster.
    • Deployment Duration: It is recommended for brief deployments (15-20 minutes up to a maximum of 1-2 hours). It is not designed for running new versions for days or weeks before promotion.
    • Version Model: It assumes a model of one stable/previous version and one preview/next version. It is not designed to manage a wave of multiple simultaneous versions (e.g., 1.1, 1.2, and 1.3 all running at once).

  3. Understand the Argo Rollouts Architecture

    master

    Argo Rollouts manages progressive delivery by introducing a custom Rollout resource that replaces or augments standard Kubernetes Deployment resources. The architecture consists of several key components:

    • Argo Rollouts Controller: The central controller that monitors Rollout resources and manages the cluster state to match the rollout definition. It does not interact with standard Kubernetes Deployment resources.
    • Rollout Resource: A custom Kubernetes resource used to define deployment strategies (like Canary or Blue/Green), stages, and thresholds. To use Argo Rollouts, you must migrate your existing Deployment resources to Rollout resources.
    • ReplicaSets: The controller automatically manages standard Kubernetes ReplicaSet resources for both old and new versions, adding metadata to track different versions. You should not manually modify these.
    • Ingress/Service: Argo Rollouts uses standard Kubernetes Service resources to route traffic. It supports advanced traffic shaping (splitting traffic by percentage) via integrations with service meshes and ingress controllers.
    • Analysis (AnalysisTemplate & AnalysisRun): Provides automated decision-making based on metrics. AnalysisTemplate defines the metric queries, while AnalysisRun represents the actual execution of an analysis for a specific rollout. You can also use Kubernetes Jobs or Webhooks for analysis.
    • CLI and UI: Optional tools for viewing and managing rollouts via the kubectl plugin or a web-based dashboard.

  4. Use Step Plugins for Canary Rollouts

    master
    Step plugins allow you to execute custom code built outside of the Argo Rollouts codebase during a canary rollout. This enables users to perform specialized actions (such as calling external APIs or proprietary tools) without waiting for a new Argo Rollouts release cycle. By using plugins, community experts can maintain specific rollout steps independently, and users can integrate proprietary logic directly into their rollout workflows.

  5. Understand the Rollout resource

    master

    A Rollout is a Kubernetes workload resource designed to replace the standard Kubernetes Deployment object when advanced deployment or progressive delivery capabilities are required.

    Key features provided by a Rollout that a standard Deployment lacks include:

    • Blue-Green deployments: Running two versions simultaneously and switching traffic.
    • Canary deployments: Gradually exposing new versions to a subset of users.
    • Traffic Routing Integration: Integration with ingress controllers and service meshes for advanced routing.
    • Metric-driven Analysis: Integration with metric providers for automated analysis during deployments.
    • Automated Lifecycle: Automated promotion or rollback based on successful or failed metrics.

  6. Understand RolloutPlugin traffic shaping and scaling

    master

    The RolloutPlugin focuses on progressive delivery through native resource capabilities rather than external traffic management.

    • Weight-only approach: The CRD uses setWeight steps to control progression. For resources like StatefulSet, this translates to manipulating the partition field (the percentage of pods updated) rather than shifting network traffic percentages.
    • Decoupled Scaling: The setCanaryScale field is not implemented in the RolloutPlugin CRD to avoid coupling pod counts with traffic routing. Progression is driven by setWeight steps.

  7. Extend Argo Rollouts with Resource Plugins

    master

    Argo Rollouts is moving towards a plugin-based architecture to support advanced deployment strategies (canary and blue/green) for Kubernetes resource types beyond standard Deployments.

    This architecture allows you to perform progressive delivery on workloads like StatefulSets and DaemonSets by using a dedicated RolloutPlugin Controller that manages a new Custom Resource Definition (CRD). This approach decouples resource-specific logic from the core Rollouts controller, providing a framework for the community to implement support for various resource types.

  8. Use the Ping-Pong feature for zero-downtime updates

    master

    The Ping-Pong feature (available since v1.2) is a strategy to achieve zero-downtime updates when using the AWS LoadBalancer controller in IP mode.

    Standard Blue-Green updates modify Service selector labels, which can prevent the AWS LoadBalancer controller from injecting necessary pod readiness gates. The Ping-Pong feature avoids this by swapping roles between two services (e.g., ping and pong). Instead of changing selectors, the Rollout directs 100% of traffic to the new service and then swaps which service is considered 'stable'.

    Status tracking: The current stable service is tracked in the Rollout status object via status.canary.currentPingPong.

  9. Understand the new Pause mechanism (v0.6+)

    master

    Starting in version v0.6, the pause functionality was reworked to allow both controller-managed and user-managed pauses.

    • Controller Pauses: The controller now adds a pause condition to .status.pauseCondition (including a start time and reason) instead of setting .spec.paused.
    • User Pauses: Users can now manually set the .spec.paused field. The controller will respect this manual setting.

    Migration: The v0.6 controller includes a migration function to convert pre-v0.6 rollouts (which used .spec.paused) to the new .status.pauseCondition format. Note that this migration function is intended to be temporary and will be removed in a future release.

  10. Configure custom NGINX ingress classes for Argo Rollouts

    master

    By default, the Argo Rollouts controller only operates on Ingresses where kubernetes.io/ingress.class or spec.ingressClassName is set to nginx.

    To change this behavior, use the --nginx-ingress-classes flag when starting the Argo Rollouts controller:

    • To support multiple specific classes: Use the flag multiple times (e.g., --nginx-ingress-classes class1 --nginx-ingress-classes class2).
    • To operate on any Ingress (ignoring class annotations): Use the flag with an empty string: --nginx-ingress-classes ''.

  11. Enable AWS TargetGroup verification for zero-downtime updates

    master

    To prevent downtime caused by delays in AWS TargetGroup updates (e.g., due to rate limiting or controller downtime), you can enable TargetGroup verification. This causes the Rollout controller to verify that changes made to the Ingress are actually reflected in the underlying AWS TargetGroup before proceeding with the rollout.

    Features:

    • TargetGroup IP Verification: (Available since v1.1) Verifies that Pod IPs of the active service are correctly registered in the TargetGroup. This is highly recommended when using the AWS LoadBalancer controller in IP mode.
    • TargetGroup Weight Verification: (Available since v1.0) Verifies that the traffic weights in the TargetGroup match the weights specified in the Ingress annotations.

    Setup:

    1. Add the --aws-verify-target-group flag to the argo-rollouts controller deployment arguments.
    2. Mandatory: You must also provide the --aws-region flag.
    3. Ensure the controller has the necessary IAM permissions for the Elastic Load Balancing API.
    apiVersion: apps/v1
kind: Deployment
metadata:
  name: argo-rollouts
spec:
  template:
    spec:
      containers:
        - name: argo-rollouts
          args: [--aws-verify-target-group, --aws-region, <your-region>]

  12. Install the Argo Rollouts Controller (Standard)

    master

    The standard installation method creates a new namespace named argo-rollouts and installs the controller.

    Important Notes:

    • If using a custom namespace, you must update the serviceaccount namespace in the ClusterRoleBinding within install.yaml.
    • For Kubernetes v1.14 or lower, you must apply the CRD manifests using the --validate=false flag because of new CRD fields introduced in v1.15.
    • On GKE, you may need to grant your account cluster-admin privileges to create cluster roles.
    kubectl create namespace argo-rollouts
kubectl apply -n argo-rollouts -f https://github.com/argoproj/argo-rollouts/releases/latest/download/install.yaml