Skip to content

Commit 56ccddd

Browse files
xtineskimxtineskim
committed
Cilium Gateway API and Flagger integration
Signed-off-by: Christine Kim <xtineskim@gmail.com>
1 parent 1d61a63 commit 56ccddd

File tree

1 file changed

+346
-0
lines changed

1 file changed

+346
-0
lines changed

‎content/en/flagger/tutorials/cilium-progressive-delivery.md‎

Lines changed: 346 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,346 @@
1+
---
2+
weight: 1
3+
title: Cilium Gateway API Canary Deployments
4+
---
5+
6+
This guide shows you how to use Cilium's implementation of the [Gateway API](https://gateway-api.sigs.k8s.io/) and Flagger to automate canary deployments and A/B testing.
7+
8+
![Flagger Canary Stages](/img/diagrams/flagger-canary-steps.png)
9+
10+
## Prerequisites
11+
12+
Flagger requires a Kubernetes cluster **v1.19** or newer and any mesh/ingress that implements the `v1beta1` version of Gateway API.
13+
14+
Ensure that you have the Kubernetes Gateway API CRDs installed:
15+
```bash
16+
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v0.7.0/config/crd/standard/gateway.networking.k8s.io_gatewayclasses.yaml
17+
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v0.7.0/config/crd/standard/gateway.networking.k8s.io_gateways.yaml
18+
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v0.7.0/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml
19+
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v0.7.0/config/crd/standard/gateway.networking.k8s.io_referencegrants.yaml
20+
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v0.7.0/config/crd/experimental/gateway.networking.k8s.io_tlsroutes.yaml
21+
```
22+
23+
Install Cilium with Gateway API enabled:
24+
```bash
25+
# To install with Helm
26+
helm install cilium cilium/cilium \
27+
--namespace kube-system \
28+
--set gatewayAPI.enabled=true \
29+
--set kubeProxyReplacement=true
30+
```
31+
This will also create a `GatewayClass` on your behalf. Try running `kubectl get gatewayclass -A` to verify it is there.
32+
33+
Install Flagger in the `flagger-system` namespace:
34+
35+
```bash
36+
kubectl apply -k github.com/fluxcd/flagger//kustomize/gatewayapi
37+
```
38+
## Creating the Gateway
39+
Create a `cilium` namespace:
40+
```bash
41+
kubectl create ns cilium
42+
```
43+
Create a `Gateway` that configures load balancing, traffic ACL, etc:
44+
```yaml
45+
kind: Gateway
46+
apiVersion: gateway.networking.k8s.io/v1beta1
47+
metadata:
48+
name: cilium
49+
namespace: cilium
50+
spec:
51+
gatewayClassName: cilium
52+
listeners:
53+
- name: http
54+
protocol: HTTP
55+
port: 80
56+
allowedRoutes:
57+
namespaces:
58+
from: All
59+
```
60+
61+
----
62+
## Bootstrap
63+
64+
Flagger takes a Kubernetes deployment and optionally a horizontal pod autoscaler \(HPA\), then creates a series of objects \(Kubernetes deployments, ClusterIP services, Istio destination rules and virtual services\). These objects expose the application inside the mesh and drive the canary analysis and promotion.
65+
66+
Create a test namespace with Istio sidecar injection enabled:
67+
68+
```bash
69+
kubectl create ns test
70+
```
71+
72+
Create a deployment and a horizontal pod autoscaler:
73+
74+
```bash
75+
kubectl apply -k https://github.com/fluxcd/flagger//kustomize/podinfo?ref=main
76+
```
77+
78+
Deploy the load testing service to generate traffic during the canary analysis:
79+
80+
```bash
81+
kubectl apply -k https://github.com/fluxcd/flagger//kustomize/tester?ref=main
82+
```
83+
84+
Create metric templates targeting the Prometheus server in the `flagger-system` namespace. This example will use the default metrics that Flagger provides. You can [change it to your ingress/mesh provider](/flagger/faq#metrics) accordingly.
85+
86+
```yaml
87+
apiVersion: flagger.app/v1beta1
88+
kind: MetricTemplate
89+
metadata:
90+
name: latency
91+
namespace: flagger-system
92+
spec:
93+
provider:
94+
type: prometheus
95+
address: http://flagger-prometheus:9090
96+
query: |
97+
histogram_quantile(0.99,
98+
sum(
99+
rate(
100+
envoy_cluster_upstream_rq_time_bucket{
101+
envoy_cluster_name=~"{{ namespace }}_{{ target }}-canary_[0-9a-zA-Z-]+",
102+
}[{{ interval }}]
103+
)
104+
) by (le)
105+
)/1000
106+
---
107+
apiVersion: flagger.app/v1beta1
108+
kind: MetricTemplate
109+
metadata:
110+
name: error-rate
111+
namespace: flagger-system
112+
spec:
113+
provider:
114+
type: prometheus
115+
address: http://flagger-prometheus:9090
116+
query: |
117+
100 - sum(
118+
rate(
119+
http_requests_total{
120+
namespace="{{ namespace }}",
121+
status!~"5.*"
122+
}[{{ interval }}]
123+
)
124+
)
125+
/
126+
sum(
127+
rate(
128+
http_requests_total{
129+
namespace="{{ namespace }}",
130+
}[{{ interval }}]
131+
)
132+
)
133+
* 100
134+
```
135+
136+
Save the above resource as metric-templates.yaml and then apply it:
137+
138+
```bash
139+
kubectl apply -f metric-templates.yaml
140+
```
141+
142+
Create a canary custom resource \(replace "loaclproject.contour.io" with your own domain\):
143+
```yaml
144+
apiVersion: flagger.app/v1beta1
145+
kind: Canary
146+
metadata:
147+
name: podinfo
148+
namespace: test
149+
spec:
150+
# deployment reference
151+
targetRef:
152+
apiVersion: apps/v1
153+
kind: Deployment
154+
name: podinfo
155+
# the maximum time in seconds for the canary deployment
156+
# to make progress before it is rollback (default 600s)
157+
progressDeadlineSeconds: 60
158+
# HPA reference (optional)
159+
autoscalerRef:
160+
apiVersion: autoscaling/v2
161+
kind: HorizontalPodAutoscaler
162+
name: podinfo
163+
service:
164+
# service port number
165+
port: 9898
166+
# container port number or name (optional)
167+
targetPort: 9898
168+
# Gateway API HTTPRoute host names
169+
# Reference to the Gateway that the generated HTTPRoute would attach to.
170+
gatewayRefs:
171+
- name: cilium
172+
namespace: cilium
173+
analysis:
174+
# schedule interval (default 60s)
175+
interval: 1m
176+
# max number of failed metric checks before rollback
177+
threshold: 5
178+
# max traffic percentage routed to canary
179+
# percentage (0-100)
180+
maxWeight: 50
181+
# canary increment step
182+
# percentage (0-100)
183+
stepWeight: 10
184+
metrics:
185+
- name: request-success-rate
186+
interval: 1m
187+
# minimum req success rate (non 5xx responses)
188+
# percentage (0-100)
189+
thresholdRange:
190+
min: 99
191+
- name: error-rate
192+
# max error rate (5xx responses)
193+
# percentage (0-100)
194+
templateRef:
195+
name: error-rate
196+
namespace: flagger-system
197+
thresholdRange:
198+
max: 1
199+
interval: 1m
200+
- name: latency
201+
templateRef:
202+
name: latency
203+
namespace: flagger-system
204+
# seconds
205+
thresholdRange:
206+
max: 0.5
207+
interval: 30s
208+
```
209+
210+
```bash
211+
# applied
212+
deployment.apps/podinfo
213+
horizontalpodautoscaler.autoscaling/podinfo
214+
canary.flagger.app/podinfo
215+
216+
# generated
217+
deployment.apps/podinfo-primary
218+
horizontalpodautoscaler.autoscaling/podinfo-primary
219+
service/podinfo
220+
service/podinfo-canary
221+
service/podinfo-primary
222+
destinationrule.networking.istio.io/podinfo-canary
223+
destinationrule.networking.istio.io/podinfo-primary
224+
virtualservice.networking.istio.io/podinfo
225+
```
226+
227+
## Automated canary promotion
228+
229+
Trigger a canary deployment by updating the container image:
230+
231+
```bash
232+
kubectl -n test set image deployment/podinfo \
233+
podinfod=ghcr.io/stefanprodan/podinfo:6.0.1
234+
```
235+
236+
Flagger detects that the deployment revision changed and starts a new rollout:
237+
238+
```text
239+
kubectl -n test describe canary/podinfo
240+
241+
Status:
242+
Canary Weight: 0
243+
Failed Checks: 0
244+
Phase: Succeeded
245+
Events:
246+
Type Reason Age From Message
247+
---- ------ ---- ---- -------
248+
Normal Synced 3m flagger New revision detected podinfo.test
249+
Normal Synced 3m flagger Scaling up podinfo.test
250+
Warning Synced 3m flagger Waiting for podinfo.test rollout to finish: 0 of 1 updated replicas are available
251+
Normal Synced 3m flagger Advance podinfo.test canary weight 5
252+
Normal Synced 3m flagger Advance podinfo.test canary weight 10
253+
Normal Synced 3m flagger Advance podinfo.test canary weight 15
254+
Normal Synced 2m flagger Advance podinfo.test canary weight 20
255+
Normal Synced 2m flagger Advance podinfo.test canary weight 25
256+
Normal Synced 1m flagger Advance podinfo.test canary weight 30
257+
Normal Synced 1m flagger Advance podinfo.test canary weight 35
258+
Normal Synced 55s flagger Advance podinfo.test canary weight 40
259+
Normal Synced 45s flagger Advance podinfo.test canary weight 45
260+
Normal Synced 35s flagger Advance podinfo.test canary weight 50
261+
Normal Synced 25s flagger Copying podinfo.test template spec to podinfo-primary.test
262+
Warning Synced 15s flagger Waiting for podinfo-primary.test rollout to finish: 1 of 2 updated replicas are available
263+
Normal Synced 5s flagger Promotion completed! Scaling down podinfo.test
264+
```
265+
266+
**Note** that if you apply new changes to the deployment during the canary analysis, Flagger will restart the analysis.
267+
268+
A canary deployment is triggered by changes in any of the following objects:
269+
270+
* Deployment PodSpec \(container image, command, ports, env, resources, etc\)
271+
* ConfigMaps mounted as volumes or mapped to environment variables
272+
* Secrets mounted as volumes or mapped to environment variables
273+
274+
You can monitor how Flagger progressively changes the weights of the HTTPRoute object that is attahed to the Gateway with:
275+
276+
```bash
277+
watch kubectl get httproute -n test podinfo -o=jsonpath='{.spec.rules}'
278+
```
279+
280+
You can monitor all canaries with:
281+
282+
```bash
283+
watch kubectl get canaries --all-namespaces
284+
285+
NAMESPACE NAME STATUS WEIGHT LASTTRANSITIONTIME
286+
test podinfo Progressing 15 2022-01-16T14:05:07Z
287+
prod frontend Succeeded 0 2022-01-15T16:15:07Z
288+
prod backend Failed 0 2022-01-14T17:05:07Z
289+
```
290+
291+
292+
## Automated rollback
293+
294+
During the canary analysis you can generate HTTP 500 errors and high latency to test if Flagger pauses the rollout.
295+
296+
Trigger another canary deployment:
297+
298+
```bash
299+
kubectl -n test set image deployment/podinfo \
300+
podinfod=ghcr.io/stefanprodan/podinfo:6.0.2
301+
```
302+
303+
Exec into the load tester pod with:
304+
305+
```bash
306+
kubectl -n test exec -it flagger-loadtester-xx-xx sh
307+
```
308+
309+
Generate HTTP 500 errors:
310+
311+
```bash
312+
watch curl http://podinfo-canary:9898/status/500
313+
```
314+
315+
Generate latency:
316+
317+
```bash
318+
watch curl http://podinfo-canary:9898/delay/1
319+
```
320+
321+
When the number of failed checks reaches the canary analysis threshold, the traffic is routed back to the primary, the canary is scaled to zero and the rollout is marked as failed.
322+
323+
```text
324+
kubectl -n test describe canary/podinfo
325+
326+
Status:
327+
Canary Weight: 0
328+
Failed Checks: 10
329+
Phase: Failed
330+
Events:
331+
Type Reason Age From Message
332+
---- ------ ---- ---- -------
333+
Normal Synced 3m flagger Starting canary deployment for podinfo.test
334+
Normal Synced 3m flagger Advance podinfo.test canary weight 5
335+
Normal Synced 3m flagger Advance podinfo.test canary weight 10
336+
Normal Synced 3m flagger Advance podinfo.test canary weight 15
337+
Normal Synced 3m flagger Halt podinfo.test advancement success rate 69.17% < 99%
338+
Normal Synced 2m flagger Halt podinfo.test advancement success rate 61.39% < 99%
339+
Normal Synced 2m flagger Halt podinfo.test advancement success rate 55.06% < 99%
340+
Normal Synced 2m flagger Halt podinfo.test advancement success rate 47.00% < 99%
341+
Normal Synced 2m flagger (combined from similar events): Halt podinfo.test advancement success rate 38.08% < 99%
342+
Warning Synced 1m flagger Rolling back podinfo.test failed checks threshold reached 10
343+
Warning Synced 1m flagger Canary failed! Scaling down podinfo.test
344+
```
345+
346+
The above procedures can be extended with [custom metrics](../usage/metrics.md) checks, [webhooks](../usage/webhooks.md), [manual promotion](../usage/webhooks.md#manual-gating) approval and [Slack or MS Teams](../usage/alerting.md) notifications.

0 commit comments

Comments
 (0)