Skip to content

Commit fa43ed5

Browse files
zac-nixonzac-nixon
committed
add alb chaining documentation
1 parent 99676e0 commit fa43ed5

File tree

4 files changed

+285
-6
lines changed

4 files changed

+285
-6
lines changed

‎docs/guide/gateway/gateway.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -47,9 +47,13 @@ You can disable the worker node security group rule management using the [LoadBa
4747

4848
## Certificate Discovery for secure listeners
4949

50-
Both L4 and L7 Gateway implementations support static certificate configuration and certificate discovery using Listener hostname.
51-
The caveat is that configuration of TLS certificates can not be done via the `certificateRefs` field of a Gateway Listener,
52-
as the controller only supports certificate references via an ARN. In the future, we may support syncing Kubernetes secrets into ACM.
50+
Both L4 and L7 Gateway implementations support static certificate configuration and certificate discovery
51+
using the hostname field on the Gateway listener and attached routes.
52+
See the Gateway API [documentation](https://gateway-api.sigs.k8s.io/reference/spec/#httproutespec)
53+
for more information on how specifying hostnames at listener and route level work with each other.
54+
An important caveat to consider is
55+
that configuration of TLS certificates cannot be done via the `certificateRefs` field of a Gateway Listener.
56+
In the future, we may support syncing Kubernetes secrets into ACM.
5357

5458

5559
### Worker node security groups selection
@@ -127,7 +131,7 @@ spec:
127131

128132
When `my-http-service` or the configured service port can't be found,
129133
the target group will not be materialized on any ALBs that the route attaches to.
130-
An [500 Fixed Response](https://docs.aws.amazon.com/elasticloadbalancing/latest/APIReference/API_FixedResponseActionConfig.html)
134+
A [500 Fixed Response](https://docs.aws.amazon.com/elasticloadbalancing/latest/APIReference/API_FixedResponseActionConfig.html)
131135
will be added to any Listener Rules that would have referenced the invalid backend.
132136

133137
## Specify out-of-band Target Groups

‎docs/guide/gateway/gateway_chaining.md‎

Lines changed: 274 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
1+
## Gateway Chaining
2+
3+
### Introduction
4+
5+
Gateway chaining involves forwarding traffic from one gateway listener directly to another gateway listener.
6+
Specifically, the LBC allows you to configure an NLB gateway listener and point it to an ALB gateway listener.
7+
Under the hood, this is implemented by using [ALB target of NLB](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/application-load-balancer-target.html).
8+
9+
10+
Using a chaining setup provides multiple benefits:
11+
12+
- You can use the HTTP request-based routing features of the Application Load Balancer in combination with features that the Network Load Balancer supports.
13+
- Use of endpoint services (AWS PrivateLink)
14+
- Static IP for Application Load Balancer.
15+
- Serve TCP and HTTP traffic from a single endpoint.
16+
17+
### Set up
18+
19+
This guide will walk you through setting up a chained Gateway.
20+
21+
22+
#### ALB Setup
23+
24+
In the YAML below, we set up an ALB Gateway with an HTTP listener on port 80 and an HTTPS listener on port 443. These listeners forward traffic to
25+
an arbitrary backend service. It's important to note that the ALB Gateway is configured as an internal load balancer. Clients
26+
that wish to connect to the ALB Gateway must do so via the NLB Gateway we will set up next. While it's possible
27+
to use an internet-facing ALB Gateway where clients could communicate directly, in a chained
28+
setup the NLB Gateway always uses private IP addresses to communicate with the ALB Gateway.
29+
30+
```yaml
31+
# alb-gatewayclass.yaml
32+
apiVersion: gateway.networking.k8s.io/v1beta1
33+
kind: GatewayClass
34+
metadata:
35+
name: aws-alb-gateway-class
36+
spec:
37+
controllerName: gateway.k8s.aws/alb
38+
---
39+
# my-alb-gateway.yaml
40+
apiVersion: gateway.networking.k8s.io/v1beta1
41+
kind: Gateway
42+
metadata:
43+
name: my-alb-gateway
44+
namespace: example-ns
45+
spec:
46+
gatewayClassName: aws-alb-gateway-class
47+
infrastructure:
48+
parametersRef:
49+
kind: LoadBalancerConfiguration
50+
name: alb-lb-config
51+
group: gateway.k8s.aws
52+
listeners:
53+
- name: http
54+
protocol: HTTP
55+
port: 80
56+
allowedRoutes:
57+
namespaces:
58+
from: Same
59+
- name: https
60+
protocol: HTTPS
61+
port: 443
62+
allowedRoutes:
63+
namespaces:
64+
from: Same
65+
---
66+
# lbconfig.yaml
67+
apiVersion: gateway.k8s.aws/v1beta1
68+
kind: LoadBalancerConfiguration
69+
metadata:
70+
name: alb-lb-config
71+
namespace: example-ns
72+
spec:
73+
listenerConfigurations:
74+
- protocolPort: HTTPS:443
75+
defaultCertificate: <my cert arn>
76+
---
77+
# httproute.yaml
78+
apiVersion: gateway.networking.k8s.io/v1beta1
79+
kind: HTTPRoute
80+
metadata:
81+
name: my-http-app-route
82+
namespace: example-ns
83+
spec:
84+
parentRefs:
85+
- group: gateway.networking.k8s.io
86+
kind: Gateway
87+
name: my-alb-gateway
88+
sectionName: http
89+
- group: gateway.networking.k8s.io
90+
kind: Gateway
91+
name: my-alb-gateway
92+
sectionName: https
93+
rules:
94+
- backendRefs:
95+
- name: echoserver
96+
port: 80
97+
```
98+
99+
#### NLB Setup
100+
101+
In the YAML below, we set up an NLB Gateway with TCP listeners on ports 80 and 443. These listeners forward traffic to
102+
the ALB Gateway configured above. The NLB Gateway is configured as internet-facing to allow external clients
103+
to connect. The NLB will route traffic to the internal ALB using private IP addresses.
104+
105+
```yaml
106+
# nlb-gatewayclass.yaml
107+
apiVersion: gateway.networking.k8s.io/v1beta1
108+
kind: GatewayClass
109+
metadata:
110+
name: aws-nlb-gateway-class
111+
spec:
112+
controllerName: gateway.k8s.aws/nlb
113+
---
114+
# my-nlb-gateway.yaml
115+
apiVersion: gateway.networking.k8s.io/v1beta1
116+
kind: Gateway
117+
metadata:
118+
name: my-tcp-gateway
119+
namespace: example-ns
120+
spec:
121+
gatewayClassName: aws-nlb-gateway-class
122+
infrastructure:
123+
parametersRef:
124+
group: gateway.k8s.aws
125+
kind: LoadBalancerConfiguration
126+
name: nlb-lb-config
127+
listeners:
128+
- name: unsecure
129+
protocol: TCP
130+
port: 80
131+
allowedRoutes:
132+
namespaces:
133+
from: Same
134+
- name: secure
135+
protocol: TCP
136+
port: 443
137+
allowedRoutes:
138+
namespaces:
139+
from: Same
140+
---
141+
# lbconfig.yaml
142+
apiVersion: gateway.k8s.aws/v1beta1
143+
kind: LoadBalancerConfiguration
144+
metadata:
145+
name: nlb-lb-config
146+
namespace: example-ns
147+
spec:
148+
scheme: internet-facing
149+
---
150+
# my-unsecure-tcproute.yaml
151+
apiVersion: gateway.networking.k8s.io/v1alpha2
152+
kind: TCPRoute
153+
metadata:
154+
name: my-unsecure-app-route
155+
namespace: example-ns
156+
spec:
157+
parentRefs:
158+
- group: gateway.networking.k8s.io
159+
kind: Gateway
160+
name: my-tcp-gateway
161+
sectionName: unsecure
162+
rules:
163+
- backendRefs:
164+
- name: my-alb-gateway
165+
kind: Gateway
166+
port: 80
167+
---
168+
# my-secure-tcproute.yaml
169+
apiVersion: gateway.networking.k8s.io/v1alpha2
170+
kind: TCPRoute
171+
metadata:
172+
name: my-secure-app-route
173+
namespace: example-ns
174+
spec:
175+
parentRefs:
176+
- group: gateway.networking.k8s.io
177+
kind: Gateway
178+
name: my-tcp-gateway
179+
sectionName: secure
180+
rules:
181+
- backendRefs:
182+
- name: my-alb-gateway
183+
kind: Gateway
184+
port: 443
185+
---
186+
# tg-configuration.yaml
187+
apiVersion: gateway.k8s.aws/v1beta1
188+
kind: TargetGroupConfiguration
189+
metadata:
190+
name: example-tg-config
191+
namespace: example-ns
192+
spec:
193+
targetReference:
194+
name: my-alb-gateway
195+
kind: Gateway
196+
routeConfigurations:
197+
- routeIdentifier:
198+
kind: TCPRoute
199+
namespace: example-ns
200+
name: my-unsecure-app-route
201+
targetGroupProps:
202+
healthCheckConfig:
203+
healthCheckProtocol: HTTP
204+
- routeIdentifier:
205+
kind: TCPRoute
206+
namespace: example-ns
207+
name: my-secure-app-route
208+
targetGroupProps:
209+
healthCheckConfig:
210+
healthCheckProtocol: HTTPS
211+
```
212+
213+
#### Customizing the ALB Gateway target settings
214+
215+
Customizing the ALB Gateway, in the context as a target, works exactly the same way as customizing a Target Group
216+
based on a Kubernetes Service. The only caveat is that target groups of type ALB do not support attribute customization,
217+
this is an AWS limitation and not one imposed within the controller. For more information about customization, see the
218+
[TargetGroupConfiguration CRD documentation](./targetgroupconfig.md).
219+
220+
In the example presented above, we have customized the target group that points to the ALB listener port on 443. In our example,
221+
this is required when forwarding traffic from the NLB to the ALB on listener port 443 as the ALB listener is expecting HTTPS traffic; even
222+
for health check traffic.
223+
224+
```yaml
225+
apiVersion: gateway.k8s.aws/v1beta1
226+
kind: TargetGroupConfiguration
227+
metadata:
228+
name: example-tg-config
229+
namespace: example-ns
230+
spec:
231+
targetReference:
232+
name: my-alb-gateway
233+
kind: Gateway
234+
routeConfigurations:
235+
- routeIdentifier:
236+
kind: TCPRoute
237+
namespace: example-ns
238+
name: my-unsecure-app-route
239+
targetGroupProps:
240+
healthCheckConfig:
241+
healthCheckProtocol: HTTP
242+
- routeIdentifier:
243+
kind: TCPRoute
244+
namespace: example-ns
245+
name: my-secure-app-route
246+
targetGroupProps:
247+
healthCheckConfig:
248+
healthCheckProtocol: HTTPS
249+
```
250+
251+
#### Cross namespace access
252+
253+
Chained Gateways support [Reference Grants](https://gateway-api.sigs.k8s.io/api-types/referencegrant/) to support chaining
254+
Gateways in different namespaces. The Reference Grant must exist within the namespace of the ALB Gateway. The same semantics used
255+
for routes and reference grants apply to Gateway-based reference grants.
256+
257+
```yaml
258+
apiVersion: gateway.networking.k8s.io/v1beta1
259+
kind: ReferenceGrant
260+
metadata:
261+
name: example-reference-grant
262+
namespace: alb-gw-ns
263+
spec:
264+
from:
265+
- group: gateway.networking.k8s.io
266+
kind: TCPRoute
267+
namespace: nlb-gw-ns
268+
to:
269+
- group: gateway.networking.k8s.io
270+
kind: Gateway
271+
```
272+
273+
In this example, we are establishing a reference grant that allows TCPRoutes from the `nlb-gw-ns` namespace
274+
to attach any ALB Gateway in the `alb-gw-ns` namespace.

‎docs/guide/gateway/l4gateway.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ spec:
4747
controllerName: gateway.k8s.aws/nlb
4848
---
4949
# my-nlb-gateway.yaml
50-
apiVersion: gateway.networking.k8s.io/v1beta1
50+
apiVersion: gateway.networking.k8s.io/v1alpha2
5151
kind: Gateway
5252
metadata:
5353
name: my-tcp-gateway
@@ -63,7 +63,7 @@ spec:
6363
from: Same
6464
---
6565
# my-tcproute.yaml
66-
apiVersion: gateway.networking.k8s.io/v1beta1
66+
apiVersion: gateway.networking.k8s.io/v1alpha2
6767
kind: TCPRoute
6868
metadata:
6969
name: my-tcp-app-route

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ nav:
3838
- LoadBalancerConfiguration: guide/gateway/loadbalancerconfig.md
3939
- TargetGroupConfiguration: guide/gateway/targetgroupconfig.md
4040
- ListenerRuleConfiguration: guide/gateway/listenerruleconfig.md
41+
- Gateway Chaining: guide/gateway/gateway_chaining.md
4142
- Specification: guide/gateway/spec.md
4243
- Tasks:
4344
- Cognito Authentication: guide/tasks/cognito_authentication.md

0 commit comments

Comments
 (0)