Skip to content

Commit c3a7895

Browse files
shraddhabangshraddhabang
authored
[feat aga] Add documentation for AGA controller (#4478)
1 parent df1744c commit c3a7895

File tree

13 files changed

+877
-22
lines changed

13 files changed

+877
-22
lines changed

‎.go-version‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
1.24.9
1+
1.24.11

‎docs/deploy/configurations.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -190,5 +190,6 @@ There are a set of key=value pairs that describe AWS load balancer controller fe
190190
| NLBSecurityGroup | string | true | Enable or disable all NLB security groups actions including frontend sg creation, backend sg creation, and backend sg modifications. This same behavior is able to be applied to an individual service by using the annotation `aws-load-balancer-disable-nlb-sg` |
191191
| LBCapacityReservation | string | true | Enable or disable the capacity reservation feature on ALB and NLB |
192192
| EnableTCPUDPListenerType | string | false | Enable or disable creation of TCP_UDP type listeners. This value can be overriden at the Service level by the annotation `service.beta.kubernetes.io/aws-load-balancer-enable-tcp-udp-listener` |
193+
| GlobalAcceleratorController | string | false | Enable the Global Accelerator controller for managing AWS Global Accelerator resources through Kubernetes CRDs |
193194
| EnhancedDefaultBehavior | string | false | Enable this feature to allow the controller to remove Provisioned Capacity or mTLS settings by removing the corresponding annotation. |
194-
| EnableDefaultTagsLowPriority | string | false | If enabled, tags supplied via `--default-tags` will be overridden by tags specified in other manners, like via annotations. |
195+
| EnableDefaultTagsLowPriority | string | false | If enabled, tags supplied via `--default-tags` will be overridden by tags specified in other manners, like via annotations. |

‎docs/guide/globalaccelerator/aga-controller.md‎

Lines changed: 296 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,296 @@
1+
# AWS Global Accelerator Controller
2+
3+
## Introduction
4+
5+
AWS Global Accelerator is a networking service that improves the performance of users' traffic by up to 60% using the AWS global network. The AWS Load Balancer Controller (LBC) extends its capabilities with a new AWS Global Accelerator Controller that allows users to declaratively manage accelerators, listeners, and endpoint groups using Kubernetes Custom Resource Definitions (CRDs).
6+
7+
This feature bridges a significant operational gap - traditionally, accelerators must be manually created and managed through the AWS console, CLI, or CloudFormation. With the AWS Global Accelerator Controller, accelerators are managed directly by your Kubernetes cluster, eliminating operational overhead and integrating with your existing Kubernetes workflows.
8+
9+
## Architecture
10+
11+
The AWS Global Accelerator Controller operates as a continuous reconciliation loop within the AWS Load Balancer Controller, watching for changes to the `GlobalAccelerator` CRD. When it detects a change, it:
12+
13+
1. Translates the desired state defined in the CRD into corresponding AWS Global Accelerator API calls
14+
2. Automatically discovers resources like Elastic Load Balancers (ELBs) referenced by Kubernetes Services, Ingresses, and Gateway APIs, or directly manages ELBs specified by their ARNs (endpointID)
15+
3. Maintains and updates the status of the AWS Global Accelerator resources in the CRD
16+
4. Handles cleanup and resource deletion when objects are removed
17+
18+
## Key Features
19+
20+
### Monolithic CRD Design
21+
22+
The controller uses a single `GlobalAccelerator` resource to manage the entire AWS Global Accelerator hierarchy, including:
23+
24+
- The accelerator itself
25+
- Listeners with protocol and port range configurations
26+
- Endpoint groups with region and traffic dial settings
27+
- Endpoints from different Kubernetes resource types (Service, Ingress, and Gateway API resources managed by AWS Load Balancer Controller or ELBs referenced by their ARNs)
28+
29+
This design simplifies management by keeping all configuration in one place while still allowing granular control over each component.
30+
31+
### Full Lifecycle Management (CRUD)
32+
33+
The controller manages the complete lifecycle of AWS Global Accelerator resources:
34+
35+
- **Create**: Provisions new AWS Global Accelerator resources from CRD specifications
36+
- **Read**: Updates CRD status with current state and ARNs from AWS
37+
- **Update**: Modifies existing accelerator configurations when the CRD is updated
38+
- **Delete**: Cleans up AWS resources when the CRD is deleted
39+
40+
### Automatic Endpoint Discovery
41+
42+
The AWS Global Accelerator Controller provides comprehensive auto-discovery capabilities that simplify Global Accelerator configuration in Kubernetes:
43+
44+
#### Resource Discovery
45+
The controller automatically discovers load balancers from multiple Kubernetes resource types in the local cluster:
46+
47+
- **Service resources**: Discovers Network Load Balancers (NLBs) from Service type LoadBalancer
48+
- **Ingress resources**: Discovers Application Load Balancers (ALBs) from Ingress resources
49+
- **Gateway API resources**: Discovers ALBs and NLBs from Gateway API resources
50+
51+
#### Automatic Configuration
52+
For simple use cases, the controller can automatically configure listener protocol and port ranges based on the discovered endpoints or the ELB ARN:
53+
54+
```yaml
55+
kind: GlobalAccelerator
56+
metadata:
57+
name: autodiscovery-accelerator
58+
namespace: test-ns
59+
spec:
60+
name: "autodiscovery-test-accelerator"
61+
listeners:
62+
- # Protocol and portRanges will be auto-discovered from the endpoint
63+
endpointGroups:
64+
- endpoints:
65+
- type: Ingress
66+
name: web-ingress
67+
weight: 200
68+
```
69+
70+
### Manual Endpoint Registration
71+
72+
For multi-region configurations or when referencing load balancers, you can manually specify endpoint ARNs instead of using auto-discovery:
73+
74+
```yaml
75+
spec:
76+
listeners:
77+
- protocol: TCP
78+
portRanges:
79+
- fromPort: 443
80+
toPort: 443
81+
endpointGroups:
82+
- endpoints:
83+
- type: EndpointID
84+
endpointID: arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/app/my-load-balancer/1234567890123456
85+
```
86+
87+
> **Note:** While auto-discovery currently only works within the same AWS region as the controller, you can manually specify endpoints in other regions by explicitly setting the region field and providing the endpoint ARN. For cross-region configurations, you must manually specify the protocol and port ranges as well:
88+
>
89+
> ```yaml
90+
> listeners:
91+
> - protocol: TCP # Must explicitly specify protocol
92+
> portRanges: # Must explicitly specify port ranges
93+
> - fromPort: 443
94+
> toPort: 443
95+
> endpointGroups:
96+
> - region: us-west-2 # Explicitly set a different region
97+
> endpoints:
98+
> - type: EndpointID
99+
> endpointID: arn:aws:elasticloadbalancing:us-west-2:123456789012:loadbalancer/app/my-load-balancer/1234567890123456
100+
> ```
101+
102+
### BYOIP (Bring Your Own IP) Support
103+
104+
The AWS Global Accelerator Controller supports Bring Your Own IP (BYOIP) functionality, which allows you to use your own IP address ranges with AWS Global Accelerator.
105+
106+
#### Prerequisites
107+
108+
To use your own IP address range with Global Accelerator, review the requirements, and then follow the steps provided in the [Bring your own IP addresses (BYOIP) in AWS Global Accelerator](https://docs.aws.amazon.com/global-accelerator/latest/dg/using-byoip.html) documentation.
109+
110+
#### Controller Limitations
111+
112+
The AWS Global Accelerator Controller has the following limitations when working with BYOIP addresses:
113+
114+
1. **Creation-Only Feature**: BYOIP addresses can only be specified during the initial creation of an accelerator.
115+
116+
2. **No Updates Allowed**: This is a controller limitation - IP addresses cannot be updated after an accelerator has been created. If you need to change IP addresses, you must create a new accelerator.
117+
118+
3. **Handling Update Attempts**: If users attempt to modify IP addresses on an existing accelerator, the controller will log this as an invalid operation and ignore the IP address changes, preserving the original configuration.
119+
120+
#### Configuration Example
121+
122+
For BYOIP usage, specify the addresses in the `ipAddresses` field of your GlobalAccelerator resource:
123+
124+
```yaml
125+
spec:
126+
ipAddressType: IPV4
127+
ipAddresses:
128+
- "198.51.100.10" # Your own IP from BYOIP pool
129+
```
130+
131+
### Status Reporting
132+
133+
The controller updates the CRD status with important information from the AWS Global Accelerator:
134+
135+
- The Accelerator's ARN for reference in other systems
136+
- The default DNS name for the accelerator
137+
- The dual-stack DNS name when available for IPv6 support
138+
- IP address sets for both IPv4 and dual-stack configurations
139+
- The current state of the accelerator (deployed, in progress, etc.)
140+
- Conditions reflecting the health and status of the reconciliation process
141+
142+
#### Accelerator Status States
143+
144+
The `status.status` field in the GlobalAccelerator CRD reflects the current state of the accelerator in AWS. This field can have the following values:
145+
146+
- **DEPLOYED**: The accelerator is fully deployed and operational
147+
- **IN_PROGRESS**: The accelerator is being created or updated
148+
- **FAILED**: The accelerator creation or update has failed
149+
150+
When an accelerator is first created, it will typically show as IN_PROGRESS and then transition to DEPLOYED once fully provisioned. During updates, it may temporarily show as IN_PROGRESS again.
151+
152+
If the status shows FAILED, check the controller logs and the `status.conditions` field for more detailed error information.
153+
154+
## Intelligent Listener Management
155+
156+
The AWS Global Accelerator Controller intelligently manages listeners to minimize service disruption during reconciliation. The controller:
157+
158+
1. Preserves existing listeners when possible to maintain stable ARNs and associated resources
159+
2. Manages conflicts carefully to ensure smooth transitions during updates
160+
3. Optimizes the operation order to minimize downtime and maintain traffic flow
161+
162+
This approach ensures reliable service while making necessary changes to your Global Accelerator configuration.
163+
164+
## Port Overrides
165+
166+
Port overrides allow you to map traffic from a specific listener port to a different port on your endpoint. This is especially useful when you need to support both direct access to your endpoint and access through AWS Global Accelerator.
167+
168+
For example, your application might be accessible directly on port 80, but you want to route traffic from AWS Global Accelerator's listener port 443 to this endpoint. Port overrides enable this flexibility.
169+
170+
```yaml
171+
endpointGroups:
172+
- trafficDialPercentage: 100
173+
portOverrides:
174+
- listenerPort: 443 # The port your Global Accelerator listener is using
175+
endpointPort: 80 # The port your endpoint is listening on
176+
```
177+
178+
For more information about when and how to use port overrides, see [AWS Global Accelerator Port Overrides](https://docs.aws.amazon.com/global-accelerator/latest/dg/about-endpoint-groups-port-override.html) in the AWS documentation.
179+
180+
> **Note**: The AWS Global Accelerator Controller handles all port override constraints automatically, ensuring your configuration is valid.
181+
182+
## Sample CRDs
183+
184+
### Basic Global Accelerator with Single TCP Port
185+
186+
```yaml
187+
apiVersion: aga.k8s.aws/v1beta1
188+
kind: GlobalAccelerator
189+
metadata:
190+
name: simple-accelerator
191+
namespace: default
192+
spec:
193+
name: "simple-accelerator"
194+
ipAddressType: IPV4
195+
tags:
196+
Environment: "production"
197+
listeners:
198+
- protocol: TCP
199+
portRanges:
200+
- fromPort: 80
201+
toPort: 80
202+
clientAffinity: NONE
203+
```
204+
205+
### Multiple Port Ranges with Source IP Affinity
206+
207+
```yaml
208+
apiVersion: aga.k8s.aws/v1beta1
209+
kind: GlobalAccelerator
210+
metadata:
211+
name: multi-port-accelerator
212+
namespace: default
213+
spec:
214+
ipAddressType: IPV4
215+
listeners:
216+
- protocol: TCP
217+
portRanges:
218+
- fromPort: 80
219+
toPort: 80
220+
- fromPort: 443
221+
toPort: 443
222+
clientAffinity: SOURCE_IP
223+
```
224+
225+
### Complex Configuration with Multiple Listeners and Endpoints
226+
227+
```yaml
228+
apiVersion: aga.k8s.aws/v1beta1
229+
kind: GlobalAccelerator
230+
metadata:
231+
name: complex-accelerator
232+
namespace: default
233+
spec:
234+
ipAddressType: IPV4
235+
tags:
236+
Environment: "test"
237+
Team: "platform"
238+
listeners:
239+
- protocol: TCP
240+
portRanges:
241+
- fromPort: 80
242+
toPort: 80
243+
- fromPort: 443
244+
toPort: 443
245+
clientAffinity: SOURCE_IP
246+
endpointGroups:
247+
- trafficDialPercentage: 100
248+
portOverrides:
249+
- listenerPort: 80
250+
endpointPort: 8081
251+
endpoints:
252+
- type: Service
253+
name: service-nlb-1
254+
weight: 128
255+
clientIPPreservationEnabled: true
256+
- type: Ingress
257+
name: test-ingress
258+
weight: 240
259+
- protocol: UDP
260+
portRanges:
261+
- fromPort: 53
262+
toPort: 53
263+
clientAffinity: NONE
264+
```
265+
266+
## Troubleshooting
267+
268+
Common issues and their solutions:
269+
270+
### Status Shows Failure
271+
272+
Check the controller logs for detailed error messages:
273+
274+
```bash
275+
kubectl logs -n kube-system -l app.kubernetes.io/name=aws-load-balancer-controller
276+
```
277+
278+
### Endpoint Discovery Not Working
279+
280+
Ensure your Service/Ingress/Gateway resources:
281+
282+
1. Are properly configured with correct annotations
283+
2. Have been successfully provisioned with actual AWS load balancers
284+
3. Are in the same namespace as specified in the endpoint
285+
286+
## Current Limitations and Future Enhancements
287+
288+
### Cross-Namespace Reference Limitations
289+
290+
The initial release of the AWS Global Accelerator Controller does not support cross-namespace endpoint references. This means that all endpoint resources (Services, Ingresses, Gateways) must be in the same namespace as the GlobalAccelerator resource that references them.
291+
292+
## References
293+
294+
- [AWS Global Accelerator Developer Guide](https://docs.aws.amazon.com/global-accelerator/latest/dg/what-is-global-accelerator.html)
295+
- [GlobalAccelerator CRD Reference](spec.md)
296+
- [AWS Load Balancer Controller Installation](../../deploy/installation.md)

0 commit comments

Comments
 (0)