stable
Install
Tutorials
How it works
​Flagger can be configured to automate the release process for Kubernetes workloads with a custom resource named canary.
Canary resource
The canary custom resource defines the release process of an application running on Kubernetes and is portable across clusters, service meshes and ingress providers.
For a deployment named podinfo, a canary release with progressive traffic shifting can be defined as:
1
apiVersion: flagger.app/v1beta1
2
kind: Canary
3
metadata:
4
name: podinfo
5
spec:
6
targetRef:
7
apiVersion: apps/v1
8
kind: Deployment
9
name: podinfo
10
service:
11
port: 9898
12
analysis:
13
interval: 1m
14
threshold: 10
15
maxWeight: 50
16
stepWeight: 5
17
metrics:
18
- name: request-success-rate
19
thresholdRange:
20
min: 99
21
interval: 1m
22
- name: request-duration
23
thresholdRange:
24
max: 500
25
interval: 1m
26
webhooks:
27
- name: load-test
28
url: http://flagger-loadtester.test/
29
metadata:
30
cmd: "hey -z 1m -q 10 -c 2 http://podinfo-canary.test:9898/"
Copied!
When you deploy a new version of an app, Flagger gradually shifts traffic to the canary, and at the same time, measures the requests success rate as well as the average response duration. You can extend the canary analysis with custom metrics, acceptance and load testing to harden the validation process of your app release process.
If you are running multiple service meshes or ingress controllers in the same cluster, you can override the global provider for a specific canary with
spec.provider.Canary target
A canary resource can target a Kubernetes Deployment or DaemonSet.
Kubernetes Deployment example:
1
spec:
2
progressDeadlineSeconds: 60
3
targetRef:
4
apiVersion: apps/v1
5
kind: Deployment
6
name: podinfo
7
autoscalerRef:
8
apiVersion: autoscaling/v2beta2
9
kind: HorizontalPodAutoscaler
10
name: podinfo
Copied!
Based on the above configuration, Flagger generates the following Kubernetes objects:
deployment/<targetRef.name>-primaryhpa/<autoscalerRef.name>-primary
The primary deployment is considered the stable release of your app, by default all traffic is routed to this version and the target deployment is scaled to zero. Flagger will detect changes to the target deployment (including secrets and configmaps) and will perform a canary analysis before promoting the new version as primary.
Note that the target deployment must have a single label selector in the format
app: <DEPLOYMENT-NAME>:1
apiVersion: apps/v1
2
kind: Deployment
3
metadata:
4
name: podinfo
5
spec:
6
selector:
7
matchLabels:
8
app: podinfo
9
template:
10
metadata:
11
labels:
12
app: podinfo
Copied!
In addition to
app, Flagger supports name and app.kubernetes.io/name selectors. If you use a different convention you can specify your label with the -selector-labels=my-app-label command flag in the Flagger deployment manifest under containers args or by setting --set selectorLabels=my-app-label when installing Flagger with Helm.If the target deployment uses secrets and/or configmaps, Flagger will create a copy of each object using the
-primary suffix and will reference these objects in the primary deployment. If you annotate your ConfigMap or Secret with flagger.app/config-tracking: disabled, Flagger will use the same object for the primary deployment instead of making a primary copy. You can disable the secrets/configmaps tracking globally with the -enable-config-tracking=false command flag in the Flagger deployment manifest under containers args or by setting --set configTracking.enabled=false when installing Flagger with Helm, but disabling config-tracking using the per Secret/ConfigMap annotation may fit your use-case better.The autoscaler reference is optional, when specified, Flagger will pause the traffic increase while the target and primary deployments are scaled up or down. HPA can help reduce the resource usage during the canary analysis. When the autoscaler reference is specified, any changes made to the autoscaler are only made active in the primary autoscaler when a rollout for the deployment starts and completes successfully. Optionally, you can create two HPAs, one for canary and one for the primary to update the HPA without doing a new rollout. As the canary deployment will be scaled to 0, the HPA on the canary will be inactive.
The progress deadline represents the maximum time in seconds for the canary deployment to make progress before it is rolled back, defaults to ten minutes.
Canary service
A canary resource dictates how the target workload is exposed inside the cluster. The canary target should expose a TCP port that will be used by Flagger to create the ClusterIP Services.
1
spec:
2
service:
3
name: podinfo
4
port: 9898
5
portName: http
6
targetPort: 9898
7
portDiscovery: true
Copied!
The container port from the target workload should match the
service.port or service.targetPort. The service.name is optional, defaults to spec.targetRef.name. The service.targetPort can be a container port number or name. The service.portName is optional (defaults to http), if your workload uses gRPC then set the port name to grpc.If port discovery is enabled, Flagger scans the target workload and extracts the containers ports excluding the port specified in the canary service and service mesh sidecar ports. These ports will be used when generating the ClusterIP services.
Based on the canary spec service, Flagger creates the following Kubernetes ClusterIP service:
<service.name>.<namespace>.svc.cluster.localselectorapp=<name>-primary<service.name>-primary.<namespace>.svc.cluster.localselectorapp=<name>-primary<service.name>-canary.<namespace>.svc.cluster.localselectorapp=<name>
This ensures that traffic to
podinfo.test:9898 will be routed to the latest stable release of your app. The podinfo-canary.test:9898 address is available only during the canary analysis and can be used for conformance testing or load testing.You can configure Flagger to set annotations and labels for the generated services with:
1
spec:
2
service:
3
port: 9898
4
apex:
5
annotations:
6
test: "test"
7
labels:
8
test: "test"
9
canary:
10
annotations:
11
test: "test"
12
labels:
13
test: "test"
14
primary:
15
annotations:
16
test: "test"
17
labels:
18
test: "test"
Copied!
Note that the
apex annotations are added to both the generated Kubernetes Service and the generated service mesh/ingress object. This allows using external-dns with Istio VirtualServices and TraefikServices. Beware of configuration conflicts here.Besides port mapping and metadata, the service specification can contain URI match and rewrite rules, timeout and retry polices:
1
spec:
2
service:
3
port: 9898
4
match:
5
- uri:
6
prefix: /
7
rewrite:
8
uri: /
9
retries:
10
attempts: 3
11
perTryTimeout: 1s
12
timeout: 5s
Copied!
When using Istio as the mesh provider, you can also specify HTTP header operations, CORS and traffic policies, Istio gateways and hosts. The Istio routing configuration can be found here.
Canary status
You can use kubectl to get the current status of canary deployments cluster wide:
1
kubectl get canaries --all-namespaces
2
​
3
NAMESPACE NAME STATUS WEIGHT LASTTRANSITIONTIME
4
test podinfo Progressing 15 2019-06-30T14:05:07Z
5
prod frontend Succeeded 0 2019-06-30T16:15:07Z
6
prod backend Failed 0 2019-06-30T17:05:07Z
Copied!
The status condition reflects the last known state of the canary analysis:
1
kubectl -n test get canary/podinfo -oyaml | awk '/status/,0'
Copied!
A successful rollout status:
1
status:
2
canaryWeight: 0
3
failedChecks: 0
4
iterations: 0
5
lastAppliedSpec: "14788816656920327485"
6
lastPromotedSpec: "14788816656920327485"
7
conditions:
8
- lastTransitionTime: "2019-07-10T08:23:18Z"
9
lastUpdateTime: "2019-07-10T08:23:18Z"
10
message: Canary analysis completed successfully, promotion finished.
11
reason: Succeeded
12
status: "True"
13
type: Promoted
Copied!
The
Promoted status condition can have one of the following reasons: Initialized, Waiting, Progressing, WaitingPromotion, Promoting, Finalising, Succeeded or Failed. A failed canary will have the promoted status set to false, the reason to failed and the last applied spec will be different to the last promoted one.Wait for a successful rollout:
1
kubectl wait canary/podinfo --for=condition=promoted
Copied!
CI example:
1
# update the container image
2
kubectl set image deployment/podinfo podinfod=stefanprodan/podinfo:3.0.1
3
​
4
# wait for Flagger to detect the change
5
ok=false
6
until ${ok}; do
7
kubectl get canary/podinfo | grep 'Progressing' && ok=true || ok=false
8
sleep 5
9
done
10
​
11
# wait for the canary analysis to finish
12
kubectl wait canary/podinfo --for=condition=promoted --timeout=5m
13
​
14
# check if the deployment was successful
15
kubectl get canary/podinfo | grep Succeeded
Copied!
Canary finalizers
The default behavior of Flagger on canary deletion is to leave resources that aren't owned by the controller in their current state. This simplifies the deletion action and avoids possible deadlocks during resource finalization. In the event the canary was introduced with existing resource(s) (i.e. service, virtual service, etc.), they would be mutated during the initialization phase and no longer reflect their initial state. If the desired functionality upon deletion is to revert the resources to their initial state, the
revertOnDeletion attribute can be enabled.1
spec:
2
revertOnDeletion: true
Copied!
When a deletion action is submitted to the cluster, Flagger will attempt to revert the following resources:
- Mesh/Ingress traffic routed to the target
The recommended approach to disable canary analysis would be utilization of the
skipAnalysis attribute, which limits the need for resource reconciliation. Utilizing the revertOnDeletion attribute should be enabled when you no longer plan to rely on Flagger for deployment management.Note When this feature is enabled expect a delay in the delete action due to the reconciliation.
Canary analysis
The canary analysis defines:
Spec:
1
analysis:
2
# schedule interval (default 60s)
3
interval:
4
# max number of failed metric checks before rollback
5
threshold:
6
# max traffic percentage routed to canary
7
# percentage (0-100)
8
maxWeight:
9
# canary increment step
10
# percentage (0-100)
11
stepWeight:
12
# promotion increment step
13
# percentage (0-100)
14
stepWeightPromotion:
15
# total number of iterations
16
# used for A/B Testing and Blue/Green
17
iterations:
18
# threshold of primary pods that need to be available to consider it ready
19
# before starting rollout. this is optional and the default is 100
20
# percentage (0-100)
21
primaryReadyThreshold: 100
22
# threshold of canary pods that need to be available to consider it ready
23
# before starting rollout. this is optional and the default is 100
24
# percentage (0-100)
25
canaryReadyThreshold: 100
26
# canary match conditions
27
# used for A/B Testing
28
match:
29
- # HTTP header
30
# key performance indicators
31
metrics:
32
- # metric check
33
# alerting
34
alerts:
35
- # alert provider
36
# external checks
37
webhooks:
38
- # hook
Copied!
The canary analysis runs periodically until it reaches the maximum traffic weight or the number of iterations. On each run, Flagger calls the webhooks, checks the metrics and if the failed checks threshold is reached, stops the analysis and rolls back the canary. If alerting is configured, Flagger will post the analysis result using the alert providers.