Skip to content

Commit 2f71d27

Browse files
Lasse4Lasse4
authored
docs: add agentgateway example (#186)
* add agentgatway exapmle Signed-off-by: Lasse4 <lasse@vierow.de> * standardize name Signed-off-by: Lasse4 <lasse@vierow.de> * add explanation Signed-off-by: Lasse4 <lasse@vierow.de> --------- Signed-off-by: Lasse4 <lasse@vierow.de>
1 parent 8f74630 commit 2f71d27

10 files changed

Lines changed: 521 additions & 3 deletions

File tree

‎examples/agentgateway/README.md‎

Lines changed: 380 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,380 @@
1+
# Using agentgateway with Argo Rollouts
2+
3+
This guide will describe how to use agentgateway Kubernetes Gateway as an implementation
4+
for the Gateway API in order to do split traffic with Argo Rollouts.
5+
6+
Versions used in this guide:
7+
- Kubernetes Gateway API: v1.5.0
8+
- agentgateway: v1.0.1
9+
- argo-rollouts: v1.8.4
10+
- rollouts-plugin-trafficrouter-gatewayapi: v0.11.0
11+
12+
Dependency:
13+
- [argo rollouts](https://argo-rollouts.readthedocs.io/en/stable/installation/#kubectl-plugin-installation) kubectl plugin
14+
15+
## Step 1 - Install agentgateway and Argo Rollouts
16+
17+
### 1 - Install agentgateway
18+
This installation creates a `agentgateway` GatewayClass, which you will use later. You can follow the instructions below to install via Helm, or refer to the [installation instructions](https://agentgateway.dev/docs/kubernetes/main/install/) for other methods.
19+
20+
1. Install the custom resources of the Kubernetes Gateway API version 1.5.0.
21+
```shell
22+
kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/standard-install.yaml
23+
```
24+
25+
Example output:
26+
```shell
27+
customresourcedefinition.apiextensions.k8s.io/gatewayclasses.gateway.networking.k8s.io created
28+
customresourcedefinition.apiextensions.k8s.io/gateways.gateway.networking.k8s.io created
29+
customresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s.io created
30+
customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking.k8s.io created
31+
customresourcedefinition.apiextensions.k8s.io/grpcroutes.gateway.networking.k8s.io created
32+
```
33+
34+
2. Deploy the agentgateway CRDs by using Helm. This command creates the agentgateway-system namespace and creates the agentgateway CRDs in the cluster.
35+
```shell
36+
helm upgrade -i --create-namespace \
37+
--namespace agentgateway-system \
38+
--version v1.0.1 agentgateway-crds oci://cr.agentgateway.dev/charts/agentgateway-crds
39+
```
40+
41+
3. Install the agentgateway Helm chart.
42+
```shell
43+
helm upgrade -i -n agentgateway-system agentgateway oci://cr.agentgateway.dev/charts/agentgateway \
44+
--version v1.0.1
45+
```
46+
47+
Example output:
48+
```shell
49+
NAME: agentgateway
50+
LAST DEPLOYED: Thu Feb 13 14:03:51 2025
51+
NAMESPACE: agentgateway-system
52+
STATUS: deployed
53+
REVISION: 1
54+
TEST SUITE: None
55+
```
56+
57+
4. Verify that the control plane is up and running.
58+
```shell
59+
kubectl get pods -n agentgateway-system
60+
```
61+
62+
Example output:
63+
```shell
64+
NAME READY STATUS RESTARTS AGE
65+
agentgateway-78658959cd-cz6jt 1/1 Running 0 12s
66+
```
67+
68+
5. Verify that the agentgateway GatewayClass is created.
69+
```shell
70+
kubectl get gatewayclass agentgateway
71+
```
72+
73+
Example output:
74+
```shell
75+
NAME CONTROLLER ACCEPTED AGE
76+
agentgateway agentgateway.dev/agentgateway True 6m36s
77+
```
78+
79+
### 2 - Install Argo Rollouts
80+
Make sure you also install Argo Rollouts. Follow the [agentgateway Argo Rollouts integration guide](https://agentgateway.dev/docs/kubernetes/main/integrations/argo/#install-argo-rollouts) to install Argo Rollouts.
81+
82+
## Step 2 - Split traffic with Gateway resources
83+
84+
Create a dedicated gateway that splits traffic across your Argo Rollouts resources.
85+
86+
1. Create a Gateway.
87+
```yaml
88+
kubectl apply -f - <<EOF
89+
apiVersion: gateway.networking.k8s.io/v1beta1
90+
kind: Gateway
91+
metadata:
92+
name: argo-rollouts-gateway
93+
namespace: argo-rollouts
94+
spec:
95+
gatewayClassName: agentgateway
96+
listeners:
97+
- protocol: HTTP
98+
name: http
99+
port: 80
100+
EOF
101+
```
102+
103+
2. Create and attach an HTTPRoute to the Gateway.
104+
```yaml
105+
kubectl apply -f - <<EOF
106+
apiVersion: gateway.networking.k8s.io/v1beta1
107+
kind: HTTPRoute
108+
metadata:
109+
name: argo-rollouts-http-route
110+
namespace: argo-rollouts
111+
spec:
112+
parentRefs:
113+
- name: argo-rollouts-gateway
114+
namespace: argo-rollouts
115+
rules:
116+
- matches:
117+
backendRefs:
118+
- name: argo-rollouts-stable-service
119+
port: 80
120+
- name: argo-rollouts-canary-service
121+
port: 80
122+
EOF
123+
```
124+
125+
## Step 3 - Create Services for your application
126+
127+
1. Create a canary service.
128+
```yaml
129+
kubectl apply -f - <<EOF
130+
apiVersion: v1
131+
kind: Service
132+
metadata:
133+
name: argo-rollouts-canary-service
134+
namespace: argo-rollouts
135+
spec:
136+
ports:
137+
- port: 80
138+
targetPort: http
139+
protocol: TCP
140+
name: http
141+
selector:
142+
app: rollouts-demo
143+
EOF
144+
```
145+
146+
2. Create a stable service.
147+
```yaml
148+
kubectl apply -f - <<EOF
149+
apiVersion: v1
150+
kind: Service
151+
metadata:
152+
name: argo-rollouts-stable-service
153+
namespace: argo-rollouts
154+
spec:
155+
ports:
156+
- port: 80
157+
targetPort: http
158+
protocol: TCP
159+
name: http
160+
selector:
161+
app: rollouts-demo
162+
EOF
163+
```
164+
165+
## Step 4 - Grant argo-rollouts permissions
166+
167+
Grant argo-rollouts permissions to view and modify Gateway HTTPRoute resources. The argo-rollouts service account needs the ability to be able to view and modify HTTPRoutes and Configmaps as well as its existing permissions. Edit the `argo-rollouts` cluster role to add the following permissions or use the RBAC example provided in the [agentgateway documentation](https://agentgateway.dev/docs/kubernetes/main/integrations/argo/#create-rbac-rules-for-argo):
168+
169+
1. Create a ClusterRole.
170+
```yaml
171+
kubectl apply -f- <<EOF
172+
apiVersion: rbac.authorization.k8s.io/v1
173+
kind: ClusterRole
174+
metadata:
175+
name: gateway-controller-role
176+
namespace: argo-rollouts
177+
rules:
178+
- apiGroups:
179+
- "gateway.networking.k8s.io"
180+
resources:
181+
- "httproutes"
182+
verbs:
183+
- get
184+
- list
185+
- watch
186+
- update
187+
- patch
188+
- apiGroups:
189+
- ""
190+
resources:
191+
- "configmaps"
192+
verbs:
193+
- get
194+
- list
195+
- watch
196+
- create
197+
- update
198+
- patch
199+
- delete
200+
EOF
201+
```
202+
203+
2. Create a ClusterRoleBinding.
204+
```yaml
205+
kubectl apply -f- <<EOF
206+
apiVersion: rbac.authorization.k8s.io/v1
207+
kind: ClusterRoleBinding
208+
metadata:
209+
name: gateway-admin
210+
roleRef:
211+
apiGroup: rbac.authorization.k8s.io
212+
kind: ClusterRole
213+
name: gateway-controller-role
214+
subjects:
215+
- namespace: argo-rollouts
216+
kind: ServiceAccount
217+
name: argo-rollouts
218+
EOF
219+
```
220+
221+
## Step 5 - Create argo-rollouts resources
222+
223+
1. Create the argo-rollouts resources.
224+
```yaml
225+
kubectl apply -f - <<EOF
226+
apiVersion: argoproj.io/v1alpha1
227+
kind: Rollout
228+
metadata:
229+
name: rollouts-demo
230+
namespace: argo-rollouts
231+
spec:
232+
replicas: 5
233+
strategy:
234+
canary:
235+
canaryService: argo-rollouts-canary-service # our created canary service
236+
stableService: argo-rollouts-stable-service # our created stable service
237+
trafficRouting:
238+
plugins:
239+
argoproj-labs/gatewayAPI:
240+
httpRoute: argo-rollouts-http-route # our created httproute
241+
namespace: argo-rollouts # namespace where this rollout resides
242+
steps:
243+
- setWeight: 30
244+
- pause: {}
245+
- setWeight: 40
246+
- pause: { duration: 10 }
247+
- setWeight: 60
248+
- pause: { duration: 10 }
249+
- setWeight: 80
250+
- pause: { duration: 10 }
251+
revisionHistoryLimit: 2
252+
selector:
253+
matchLabels:
254+
app: rollouts-demo
255+
template:
256+
metadata:
257+
labels:
258+
app: rollouts-demo
259+
spec:
260+
containers:
261+
- name: rollouts-demo
262+
image: argoproj/rollouts-demo:red
263+
ports:
264+
- name: http
265+
containerPort: 8080
266+
protocol: TCP
267+
resources:
268+
requests:
269+
memory: 32Mi
270+
cpu: 5m
271+
EOF
272+
```
273+
274+
## Step 6 - Test Application
275+
276+
1. Port-forward the Gateway service.
277+
```
278+
kubectl port-forward svc/argo-rollouts-gateway 8080:80 -n argo-rollouts
279+
```
280+
281+
2. You can now test the application. An argo application shows up with red dots.
282+
- Via browser:
283+
```shell
284+
http://localhost:8080
285+
```
286+
287+
- Or via terminal:
288+
```shell
289+
curl http://localhost:8080/
290+
curl http://localhost:8080/color
291+
```
292+
293+
## Step 7 - Test the promotion
294+
295+
1. Update the Image of the rollout to blue or a different color.
296+
```shell
297+
kubectl argo rollouts set image rollouts-demo rollouts-demo=argoproj/rollouts-demo:blue -n argo-rollouts
298+
```
299+
300+
Or update the image under containers in rollout.yml to blue or a different color (such as `image: argoproj/rollouts-demo:blue`) and apply the `rollout.yaml` again.
301+
```yaml
302+
kubectl apply -f - <<EOF
303+
apiVersion: argoproj.io/v1alpha1
304+
kind: Rollout
305+
metadata:
306+
name: rollouts-demo
307+
namespace: argo-rollouts
308+
spec:
309+
replicas: 5
310+
strategy:
311+
canary:
312+
canaryService: argo-rollouts-canary-service # our created canary service
313+
stableService: argo-rollouts-stable-service # our created stable service
314+
trafficRouting:
315+
plugins:
316+
argoproj-labs/gatewayAPI:
317+
httpRoute: argo-rollouts-http-route # our created httproute
318+
namespace: argo-rollouts # namespace where this rollout resides
319+
steps:
320+
- setWeight: 30
321+
- pause: {}
322+
- setWeight: 40
323+
- pause: { duration: 10 }
324+
- setWeight: 60
325+
- pause: { duration: 10 }
326+
- setWeight: 80
327+
- pause: { duration: 10 }
328+
revisionHistoryLimit: 2
329+
selector:
330+
matchLabels:
331+
app: rollouts-demo
332+
template:
333+
metadata:
334+
labels:
335+
app: rollouts-demo
336+
spec:
337+
containers:
338+
- name: rollouts-demo
339+
image: argoproj/rollouts-demo:blue # Change the image here.
340+
ports:
341+
- name: http
342+
containerPort: 8080
343+
protocol: TCP
344+
resources:
345+
requests:
346+
memory: 32Mi
347+
cpu: 5m
348+
EOF
349+
```
350+
351+
2. Check the weight difference between the stable and canary service.
352+
```shell
353+
kubectl get httproute argo-rollouts-http-route -o yaml -n argo-rollouts
354+
```
355+
356+
Or use the following command to watch the promotion progress in real time. Make sure you have installed the [argo-rollouts](https://argo-rollouts.readthedocs.io/en/stable/installation/#kubectl-plugin-installation) extension for kubectl.
357+
```shell
358+
kubectl argo rollouts get rollout rollouts-demo -n argo-rollouts --watch
359+
```
360+
361+
3. Promote the rollout. Make sure you have installed the [argo-rollouts](https://argo-rollouts.readthedocs.io/en/stable/installation/#kubectl-plugin-installation) extension for kubectl. Blue and red dots reflect the traffic split in the GUI, run the promotion multiple times until only blue dots remain.
362+
```shell
363+
kubectl argo rollouts promote rollouts-demo -n argo-rollouts
364+
```
365+
366+
4. Check again the weight difference between the stable and canary service.
367+
```shell
368+
kubectl get httproute argo-rollouts-http-route -o yaml -n argo-rollouts
369+
```
370+
371+
5. Verify changes. Now blue dots appear in the web GUI instead of red ones.
372+
- Via browser:
373+
```shell
374+
http://localhost:8080
375+
```
376+
377+
- Or via terminal:
378+
```shell
379+
curl http://localhost:8080/color
380+
```

‎examples/agentgateway/canary.yml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
apiVersion: v1
2+
kind: Service
3+
metadata:
4+
name: argo-rollouts-canary-service
5+
namespace: argo-rollouts
6+
spec:
7+
ports:
8+
- port: 80
9+
targetPort: http
10+
protocol: TCP
11+
name: http
12+
selector:
13+
app: rollouts-demo

0 commit comments

Comments
 (0)