[feat aga] Add documentation for AGA controller #4478

shraddhabang · 2025-12-01T17:46:57Z

This PR adds documentation for the AWS Global Accelerator (AGA) Controller feature.

Add installation guide with CRD installation steps and feature flag requirements
Document IAM permissions required for the Global Accelerator controller
Clarify cross-region support limitations and auto-discovery capabilities
Add configuration options and feature flag details
Document AWS partition availability (standard partition only)

Checklist

Added tests that cover your change (if possible)
Added/modified documentation as required (such as the README.md, or the docs directory)
Manually tested
Made sure the title of the PR is a good description that can go into the release notes

BONUS POINTS checklist: complete for good vibes and maybe prizes?! 🤯

Backfilled missing tests for code in same general area 🎉
Refactored something and made the world a better place 🌟

wweiwei-li · 2025-12-01T23:06:28Z

docs/guide/globalaccelerator/aga-controller.md

+The AGA 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:
+
+1. Translates the desired state defined in the CRD into corresponding AWS Global Accelerator API calls
+2. Automatically discovers resources like Elastic Load Balancers (ELBs) referenced by Kubernetes Services, Ingresses, and Gateway APIs


do we want to also mention we support manual specification (direct ARN as endpointID)

Yes. Good point I can update it.

Yes. Good catch.

wweiwei-li · 2025-12-01T23:06:43Z

docs/guide/globalaccelerator/aga-controller.md

+- **Update**: Modifies existing accelerator configurations when the CRD is updated
+- **Delete**: Cleans up AWS resources when the CRD is deleted
+
+### Extended Endpoint Discovery


Nit: I am thinking Extended Endpoint Discovery and Auto-Discovery for One-Click Accelerators consolidate to one auto discovery. They're the same auto-discovery feature just focusing on different aspects (endpoint versus listener and port). Maybe it is partial used based on their crd config. but looks to me it is same thing. What do you think.

Agree; "Automatic Endpoint Discovery" sounds great as a combined heading.

All right. let me rewrite this to capture this better.

wweiwei-li · 2025-12-01T23:14:00Z

docs/guide/globalaccelerator/aga-controller.md

+
+### BYOIP (Bring Your Own IP) Support
+
+The AWS Global Accelerator Controller supports Bring Your Own IP (BYOIP) functionality with some important constraints:


thinking if we want to add some prerequisites. For example, link to how they provision IP address range with Global Accelerator - https://docs.aws.amazon.com/global-accelerator/latest/dg/using-byoip.html.

Also, if we want to clarify No Updates Allowed is controller limitation.

Agreed. Good point.

wweiwei-li · 2025-12-01T23:26:51Z

docs/guide/globalaccelerator/installation.md

+
+3. **IAM Permissions**: The IAM role used by the AWS Load Balancer Controller must include the Global Accelerator permissions listed above.
+
+## Installation


do we want to also mention RBAC config needed for controller to have permissions to manage AGA resources

Required RBACs will be updated automatically when they upgrade to latest version. That we dont have conditional. So we dont need to specify that.

emdelaney · 2025-12-02T00:41:06Z

docs/guide/globalaccelerator/aga-controller.md

+- The accelerator itself
+- Listeners with protocol and port range configurations
+- Endpoint groups with region and traffic dial settings
+- Endpoints from different Kubernetes resource types


I'd highlight AWS Load Balancer Controller Ingress, Service, and Gateway resources specifically here as supported endpoint types

emdelaney · 2025-12-02T00:41:54Z

docs/guide/globalaccelerator/aga-controller.md

+- **Update**: Modifies existing accelerator configurations when the CRD is updated
+- **Delete**: Cleans up AWS resources when the CRD is deleted
+
+### Extended Endpoint Discovery


Agree; "Automatic Endpoint Discovery" sounds great as a combined heading.

emdelaney · 2025-12-02T00:43:38Z

docs/guide/globalaccelerator/aga-controller.md

+
+### Manual Endpoint Registration
+
+For more advanced use cases, you can manually specify endpoint ARNs instead of using auto-discovery:


Let's be specific and say that to use multiple regions, you can specify endpoint ARNs, instead of 'advanced use cases'.

emdelaney · 2025-12-02T00:48:33Z

docs/guide/globalaccelerator/aga-controller.md

+The controller updates the CRD status with important information from the AWS Global Accelerator:
+
+- The Accelerator's ARN for reference in other systems
+- The assigned DNS name for client access


The DNS name is a courtesy; because AWS Global Accelerator operates at layer 3/4 (TCP/UDP), you don't need to use it. So I'd call this "The default DNS name for the accelerator."

Also, do we want to provide the dual stack DNS name, if available, in another field? https://docs.aws.amazon.com/global-accelerator/latest/api/API_Accelerator.html#globalaccelerator-Type-Accelerator-DualStackDnsName

emdelaney · 2025-12-02T00:50:46Z

docs/guide/globalaccelerator/aga-controller.md

+
+This approach ensures reliable service while making necessary changes to your Global Accelerator configuration.
+
+## Port Override Constraints and Solutions


Not sure this is super relevant / useful to users of the system; we might want to highlight when to use port overrides (when you plan to support both direct access to the endpoint, and also access over AGA): https://docs.aws.amazon.com/global-accelerator/latest/dg/about-endpoint-groups-port-override.html

Makes sense. Let me update this.

emdelaney · 2025-12-02T00:54:55Z

docs/guide/globalaccelerator/aga-controller.md

+
+## References
+
+- [AWS Global Accelerator Documentation](https://docs.aws.amazon.com/global-accelerator/latest/dg/what-is-global-accelerator.html)


Let's call this the AWS Global Accelerator Developer Guide

emdelaney · 2025-12-02T00:59:04Z

docs/guide/globalaccelerator/installation.md

+
+## Prerequisites
+
+> **Important**: AWS Global Accelerator is only available in the standard AWS partition. It is not available in specialized AWS partitions such as AWS GovCloud (US) or AWS China regions.


...is only available in the commercial aws partition. It is not available in other partitions such as the AWS GovCoud (aws-us-gov) or AWS China (aws-cn) partitions.

(ref: https://docs.aws.amazon.com/whitepapers/latest/aws-fault-isolation-boundaries/partitions.html )

emdelaney · 2025-12-02T01:02:09Z

docs/guide/globalaccelerator/installation.md

+
+## AWS Global Accelerator Service Quotas
+
+Be aware of the following AWS Global Accelerator service quotas:


What limits do you want to highlight? (Maybe 10 ALBs or NLBs per endpoint group, and 20 accelerators per account?)

Yes. Just the overall limits so directed them to the service quota page.

Got it, we can probably remove this sentence then, and just leave the line with the link to the maintained service quotas documentation?

emdelaney · 2025-12-02T01:04:35Z

docs/install/aga_controller_iam_policy.md

+
+This document outlines the required IAM permissions for the AWS Global Accelerator Controller feature of the AWS Load Balancer Controller.
+
+## IAM Policy


Might be worth highlighting that this is a scoped-down (RBAC) version of the GlobalAcceleratorFullAccess policy: https://docs.aws.amazon.com/aws-managed-policy/latest/reference/GlobalAcceleratorFullAccess.html

Scoped down version GlobalAcceleratorFullAccess will get full access to all the resources. While our IAM policy is tag based.

emdelaney · 2025-12-02T01:05:07Z

docs/install/aga_controller_iam_policy.md

+
+This policy provides fine-grained access to AWS Global Accelerator resources:
+
+### Service-Linked Role Creation


Some customers are sensitive about IAM create permissions; it's also fine to pre-create the role outside of k8s automation as well. Not sure if we want to highlight that here or not. (not is simpler.)

We have given the same policy for our ELB service as well. So the customers are aware of this. These are anyway recommended policies. If the customer wants, they can always remove this from their policies. This is pretty common practice to use our controller.

shraddhabang · 2025-12-02T16:35:14Z

/retest

emdelaney · 2025-12-02T18:05:19Z

docs/guide/globalaccelerator/installation.md

+
+## AWS Global Accelerator Service Quotas
+
+Be aware of the following AWS Global Accelerator service quotas:


Got it, we can probably remove this sentence then, and just leave the line with the link to the maintained service quotas documentation?

k8s-ci-robot · 2025-12-02T18:07:14Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: emdelaney, shraddhabang, wweiwei-li

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [shraddhabang,wweiwei-li]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

k8s-ci-robot requested review from oliviassss and shuqz December 1, 2025 17:47

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. approved Indicates a PR has been approved by an approver from all required OWNERS files. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Dec 1, 2025

wweiwei-li reviewed Dec 1, 2025

View reviewed changes

emdelaney suggested changes Dec 2, 2025

View reviewed changes

shraddhabang force-pushed the agadocs branch from 7bf045f to 26d64ba Compare December 2, 2025 13:12

wweiwei-li approved these changes Dec 2, 2025

View reviewed changes

emdelaney approved these changes Dec 2, 2025

View reviewed changes

shraddhabang force-pushed the agadocs branch 2 times, most recently from 6c88a98 to f3a8a2c Compare December 3, 2025 11:41

[feat aga] Add documentation for AGA controller

4e5cf77

shraddhabang force-pushed the agadocs branch from f3a8a2c to 4e5cf77 Compare December 3, 2025 11:43

shraddhabang merged commit c3a7895 into kubernetes-sigs:main Dec 3, 2025
8 of 9 checks passed


		### BYOIP (Bring Your Own IP) Support

		The AWS Global Accelerator Controller supports Bring Your Own IP (BYOIP) functionality with some important constraints:


		3. IAM Permissions: The IAM role used by the AWS Load Balancer Controller must include the Global Accelerator permissions listed above.

		## Installation


		### Manual Endpoint Registration

		For more advanced use cases, you can manually specify endpoint ARNs instead of using auto-discovery:


		This approach ensures reliable service while making necessary changes to your Global Accelerator configuration.

		## Port Override Constraints and Solutions


		## References

		- [AWS Global Accelerator Documentation](https://docs.aws.amazon.com/global-accelerator/latest/dg/what-is-global-accelerator.html)


		## Prerequisites

		> Important: AWS Global Accelerator is only available in the standard AWS partition. It is not available in specialized AWS partitions such as AWS GovCloud (US) or AWS China regions.


		## AWS Global Accelerator Service Quotas

		Be aware of the following AWS Global Accelerator service quotas:


		This document outlines the required IAM permissions for the AWS Global Accelerator Controller feature of the AWS Load Balancer Controller.

		## IAM Policy


		This policy provides fine-grained access to AWS Global Accelerator resources:

		### Service-Linked Role Creation

[feat aga] Add documentation for AGA controller #4478

[feat aga] Add documentation for AGA controller #4478

Conversation

shraddhabang commented Dec 1, 2025

Checklist

BONUS POINTS checklist: complete for good vibes and maybe prizes?! 🤯

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shraddhabang commented Dec 2, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

k8s-ci-robot commented Dec 2, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants