Rollout Specification¶
The following describes all the available fields of a rollout:
apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
name: example-rollout-canary
spec:
# Number of desired pods.
# Defaults to 1.
replicas: 5
analysis:
# limits the number of successful analysis runs and experiments to be stored in a history
# Defaults to 5.
successfulRunHistoryLimit: 10
# limits the number of unsuccessful analysis runs and experiments to be stored in a history.
# Stages for unsuccessful: "Error", "Failed", "Inconclusive"
# Defaults to 5.
unsuccessfulRunHistoryLimit: 10
# Label selector for pods. Existing ReplicaSets whose pods are selected by
# this will be the ones affected by this rollout. It must match the pod
# template's labels.
selector:
matchLabels:
app: guestbook
# WorkloadRef holds a references to a workload that provides Pod template
# (e.g. Deployment). If used, then do not use Rollout template property.
workloadRef:
apiVersion: apps/v1
kind: Deployment
name: rollout-ref-deployment
# Template describes the pods that will be created. Same as deployment.
# If used, then do not use Rollout workloadRef property.
template:
spec:
containers:
- name: guestbook
image: argoproj/rollouts-demo:blue
# Minimum number of seconds for which a newly created pod should be ready
# without any of its container crashing, for it to be considered available.
# Defaults to 0 (pod will be considered available as soon as it is ready)
minReadySeconds: 30
# The number of old ReplicaSets to retain.
# Defaults to 10
revisionHistoryLimit: 3
# Pause allows a user to manually pause a rollout at any time. A rollout
# will not advance through its steps while it is manually paused, but HPA
# auto-scaling will still occur. Typically not explicitly set the manifest,
# but controlled via tools (e.g. kubectl argo rollouts pause). If true at
# initial creation of Rollout, replicas are not scaled up automatically
# from zero unless manually promoted.
paused: true
# The maximum time in seconds in which a rollout must make progress during
# an update, before it is considered to be failed. Argo Rollouts will
# continue to process failed rollouts and a condition with a
# ProgressDeadlineExceeded reason will be surfaced in the rollout status.
# Note that progress will not be estimated during the time a rollout is
# paused.
# Defaults to 600s
progressDeadlineSeconds: 600
# Whether to abort the update when ProgressDeadlineSeconds is exceeded.
# Optional and default is false.
progressDeadlineAbort: false
# UTC timestamp in which a Rollout should sequentially restart all of
# its pods. Used by the `kubectl argo rollouts restart ROLLOUT` command.
# The controller will ensure all pods have a creationTimestamp greater
# than or equal to this value.
restartAt: "2020-03-30T21:19:35Z"
# The rollback window provides a way to fast track deployments to
# previously deployed versions.
# Optional, and by default is not set.
rollbackWindow:
revisions: 3
strategy:
# Blue-green update strategy
blueGreen:
# Reference to service that the rollout modifies as the active service.
# Required.
activeService: active-service
# Pre-promotion analysis run which performs analysis before the service
# cutover. +optional
prePromotionAnalysis:
templates:
- templateName: success-rate
args:
- name: service-name
value: guestbook-svc.default.svc.cluster.local
# Post-promotion analysis run which performs analysis after the service
# cutover. +optional
postPromotionAnalysis:
templates:
- templateName: success-rate
args:
- name: service-name
value: guestbook-svc.default.svc.cluster.local
# Name of the service that the rollout modifies as the preview service.
# +optional
previewService: preview-service
# The number of replicas to run under the preview service before the
# switchover. Once the rollout is resumed the new ReplicaSet will be fully
# scaled up before the switch occurs +optional
previewReplicaCount: 1
# Indicates if the rollout should automatically promote the new ReplicaSet
# to the active service or enter a paused state. If not specified, the
# default value is true. +optional
autoPromotionEnabled: false
# Automatically promotes the current ReplicaSet to active after the
# specified pause delay in seconds after the ReplicaSet becomes ready.
# If omitted, the Rollout enters and remains in a paused state until
# manually resumed by resetting spec.Paused to false. +optional
autoPromotionSeconds: 30
# Adds a delay before scaling down the previous ReplicaSet. If omitted,
# the Rollout waits 30 seconds before scaling down the previous ReplicaSet.
# A minimum of 30 seconds is recommended to ensure IP table propagation
# across the nodes in a cluster.
scaleDownDelaySeconds: 30
# Limits the number of old RS that can run at once before getting scaled
# down. Defaults to nil
scaleDownDelayRevisionLimit: 2
# Add a delay in second before scaling down the preview replicaset
# if update is aborted. 0 means not to scale down. Default is 30 second
abortScaleDownDelaySeconds: 30
# Anti Affinity configuration between desired and previous ReplicaSet.
# Only one must be specified
antiAffinity:
requiredDuringSchedulingIgnoredDuringExecution: {}
preferredDuringSchedulingIgnoredDuringExecution:
weight: 1 # Between 1 - 100
# Canary update strategy
canary:
# Reference to a service which the controller will update to select
# canary pods. Required for traffic routing.
canaryService: canary-service
# Reference to a service which the controller will update to select
# stable pods. Required for traffic routing.
stableService: stable-service
# Metadata which will be attached to the canary pods. This metadata will
# only exist during an update, since there are no canary pods in a fully
# promoted rollout.
canaryMetadata:
annotations:
role: canary
labels:
role: canary
# metadata which will be attached to the stable pods
stableMetadata:
annotations:
role: stable
labels:
role: stable
# The maximum number of pods that can be unavailable during the update.
# Value can be an absolute number (ex: 5) or a percentage of total pods
# at the start of update (ex: 10%). Absolute number is calculated from
# percentage by rounding down. This can not be 0 if MaxSurge is 0. By
# default, a fixed value of 1 is used. Example: when this is set to 30%,
# the old RC can be scaled down by 30% immediately when the rolling
# update starts. Once new pods are ready, old RC can be scaled down
# further, followed by scaling up the new RC, ensuring that at least 70%
# of original number of pods are available at all times during the
# update. +optional
maxUnavailable: 1
# The maximum number of pods that can be scheduled above the original
# number of pods. Value can be an absolute number (ex: 5) or a
# percentage of total pods at the start of the update (ex: 10%). This
# can not be 0 if MaxUnavailable is 0. Absolute number is calculated
# from percentage by rounding up. By default, a value of 1 is used.
# Example: when this is set to 30%, the new RC can be scaled up by 30%
# immediately when the rolling update starts. Once old pods have been
# killed, new RC can be scaled up further, ensuring that total number
# of pods running at any time during the update is at most 130% of
# original pods. +optional
maxSurge: "20%"
# Adds a delay before scaling down the previous ReplicaSet when the
# canary strategy is used with traffic routing (default 30 seconds).
# A delay in scaling down the previous ReplicaSet is needed after
# switching the stable service selector to point to the new ReplicaSet,
# in order to give time for traffic providers to re-target the new pods.
# This value is ignored with basic, replica-weighted canary without
# traffic routing.
scaleDownDelaySeconds: 30
# The minimum number of pods that will be requested for each ReplicaSet
# when using traffic routed canary. This is to ensure high availability
# of each ReplicaSet. Defaults to 1. +optional
minPodsPerReplicaSet: 2
# Limits the number of old RS that can run at one time before getting
# scaled down. Defaults to nil
scaleDownDelayRevisionLimit: 2
# Background analysis to run during a rollout update. Skipped upon
# initial deploy of a rollout. +optional
analysis:
templates:
- templateName: success-rate
args:
- name: service-name
value: guestbook-svc.default.svc.cluster.local
# valueFrom.podTemplateHashValue is a convenience to supply the
# rollouts-pod-template-hash value of either the Stable ReplicaSet
# or the Latest ReplicaSet
- name: stable-hash
valueFrom:
podTemplateHashValue: Stable
- name: latest-hash
valueFrom:
podTemplateHashValue: Latest
# valueFrom.fieldRef allows metadata about the rollout to be
# supplied as arguments to analysis.
- name: region
valueFrom:
fieldRef:
fieldPath: metadata.labels['region']
# Steps define sequence of steps to take during an update of the
# canary. Skipped upon initial deploy of a rollout. +optional
steps:
# Sets the ratio of canary ReplicaSet to 20%
- setWeight: 20
# Pauses the rollout for an hour. Supported units: s, m, h
- pause:
duration: 1h
# Pauses indefinitely until manually resumed
- pause: {}
# set canary scale to a explicit count without changing traffic weight
# (supported only with trafficRouting)
- setCanaryScale:
replicas: 3
# set canary scale to a percentage of spec.replicas without changing traffic weight
# (supported only with trafficRouting)
- setCanaryScale:
weight: 25
# set canary scale to match the canary traffic weight (default behavior)
- setCanaryScale:
matchTrafficWeight: true
# Sets header based route with specified header values
# Setting header based route will send all 100 traffic to the canary for the requests
# O with a specified header, in this case request header "version":"2"
# (supported only with trafficRouting, for Istio only at the moment)
- setHeaderRoute:
# Name of the route that will be created by argo rollouts this must also be configured
# in spec.strategy.canary.trafficRouting.managedRoutes
name: "header-route-1"
# The matching rules for the header route, if this is missing it acts as a removal of the route.
match:
# headerName The name of the header to apply the match rules to.
- headerName: "version"
# headerValue must contain exactly one field of exact, regex, or prefix. Not all traffic routers support
# all types
headerValue:
# Exact will only match if the header value is exactly the same
exact: "2"
# Will match the rule if the regular expression matches
regex: "2.0.(.*)"
# prefix will be a prefix match of the header value
prefix: "2.0"
# Sets up a mirror/shadow based route with the specified match rules
# The traffic will be mirrored at the configured percentage to the canary service
# during the rollout
# (supported only with trafficRouting, for Istio only at the moment)
- setMirrorRoute:
# Name of the route that will be created by argo rollouts this must also be configured
# in spec.strategy.canary.trafficRouting.managedRoutes
name: "header-route-1"
# The percentage of the matched traffic to mirror to the canary
percentage: 100
# The matching rules for the header route, if this is missing it acts as a removal of the route.
# All conditions inside a single match block have AND semantics, while the list of match blocks have OR semantics.
# Each type within a match (method, path, headers) must have one and only one match type (exact, regex, prefix)
# Not all match types (exact, regex, prefix) will be supported by all traffic routers.
match:
- method: # What HTTP method to match
exact: "GET"
regex: "P.*"
prefix: "POST"
path: # What HTTP url paths to match.
exact: "/test"
regex: "/test/.*"
prefix: "/"
headers:
agent-1b: # What HTTP header name to use in the match.
exact: "firefox"
regex: "firefox2(.*)"
prefix: "firefox"
# an inline analysis step
- analysis:
templates:
- templateName: success-rate
# an inline experiment step
- experiment:
duration: 1h
templates:
- name: baseline
specRef: stable
- name: canary
specRef: canary
# optional, set the weight of traffic routed to this version
weight: 10
analyses:
- name : mann-whitney
templateName: mann-whitney
# Anti-affinity configuration between desired and previous ReplicaSet.
# Only one must be specified.
antiAffinity:
requiredDuringSchedulingIgnoredDuringExecution: {}
preferredDuringSchedulingIgnoredDuringExecution:
weight: 1 # Between 1 - 100
# Traffic routing specifies the ingress controller or service mesh
# configuration to achieve advanced traffic splitting. If omitted,
# will achieve traffic split via a weighted replica counts between
# the canary and stable ReplicaSet.
trafficRouting:
# This is a list of routes that Argo Rollouts has the rights to manage it is currently only required for
# setMirrorRoute and setHeaderRoute. The order of managedRoutes array also sets the precedence of the route
# in the traffic router. Argo Rollouts will place these routes in the order specified above any routes already
# defined in the used traffic router if something exists. The names here must match the names from the
# setHeaderRoute and setMirrorRoute steps.
managedRoutes:
- name: set-header
- name: mirror-route
# Istio traffic routing configuration
istio:
# Either virtualService or virtualServices can be configured.
virtualService:
name: rollout-vsvc # required
routes:
- primary # optional if there is a single route in VirtualService, required otherwise
virtualServices:
# One or more virtualServices can be configured
- name: rollouts-vsvc1 # required
routes:
- primary # optional if there is a single route in VirtualService, required otherwise
- name: rollouts-vsvc2 # required
routes:
- secondary # optional if there is a single route in VirtualService, required otherwise
# NGINX Ingress Controller routing configuration
nginx:
stableIngress: primary-ingress # required
annotationPrefix: customingress.nginx.ingress.kubernetes.io # optional
additionalIngressAnnotations: # optional
canary-by-header: X-Canary
canary-by-header-value: iwantsit
# ALB Ingress Controller routing configuration
alb:
ingress: ingress # required
servicePort: 443 # required
annotationPrefix: custom.alb.ingress.kubernetes.io # optional
# Service Mesh Interface routing configuration
smi:
rootService: root-svc # optional
trafficSplitName: rollout-example-traffic-split # optional
# Add a delay in second before scaling down the canary pods when update
# is aborted for canary strategy with traffic routing (not applicable for basic canary).
# 0 means canary pods are not scaled down. Default is 30 seconds.
abortScaleDownDelaySeconds: 30
status:
pauseConditions:
- reason: StepPause
startTime: 2019-10-00T1234
- reason: BlueGreenPause
startTime: 2019-10-00T1234
- reason: AnalysisRunInconclusive
startTime: 2019-10-00T1234
Examples¶
You can find examples of Rollouts at: