From 4e5cf7747d743743ec56db1f74c168e8872c0941 Mon Sep 17 00:00:00 2001 From: shraddha bang Date: Mon, 1 Dec 2025 09:41:15 -0800 Subject: [PATCH] [feat aga] Add documentation for AGA controller --- .go-version | 2 +- docs/deploy/configurations.md | 3 +- .../guide/globalaccelerator/aga-controller.md | 296 +++++++++++++++++ docs/guide/globalaccelerator/examples.md | 310 ++++++++++++++++++ docs/guide/globalaccelerator/installation.md | 88 +++++ docs/install/aga_controller_iam_policy.md | 155 +++++++++ go.mod | 2 +- helm/aws-load-balancer-controller/values.yaml | 2 +- main.go | 4 +- mkdocs.yml | 5 + pkg/aga/utils.go | 8 +- pkg/aga/utils_test.go | 20 +- pkg/config/feature_gates.go | 4 +- 13 files changed, 877 insertions(+), 22 deletions(-) create mode 100644 docs/guide/globalaccelerator/aga-controller.md create mode 100644 docs/guide/globalaccelerator/examples.md create mode 100644 docs/guide/globalaccelerator/installation.md create mode 100644 docs/install/aga_controller_iam_policy.md diff --git a/.go-version b/.go-version index eb716f77a..d6c68ad2d 100644 --- a/.go-version +++ b/.go-version @@ -1 +1 @@ -1.24.9 +1.24.11 diff --git a/docs/deploy/configurations.md b/docs/deploy/configurations.md index bd6476cfb..092595ce5 100644 --- a/docs/deploy/configurations.md +++ b/docs/deploy/configurations.md @@ -190,5 +190,6 @@ There are a set of key=value pairs that describe AWS load balancer controller fe | 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` | | LBCapacityReservation | string | true | Enable or disable the capacity reservation feature on ALB and NLB | | 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` | +| GlobalAcceleratorController | string | false | Enable the Global Accelerator controller for managing AWS Global Accelerator resources through Kubernetes CRDs | | EnhancedDefaultBehavior | string | false | Enable this feature to allow the controller to remove Provisioned Capacity or mTLS settings by removing the corresponding annotation. | -| EnableDefaultTagsLowPriority | string | false | If enabled, tags supplied via `--default-tags` will be overridden by tags specified in other manners, like via annotations. | \ No newline at end of file +| EnableDefaultTagsLowPriority | string | false | If enabled, tags supplied via `--default-tags` will be overridden by tags specified in other manners, like via annotations. | diff --git a/docs/guide/globalaccelerator/aga-controller.md b/docs/guide/globalaccelerator/aga-controller.md new file mode 100644 index 000000000..d4be258b7 --- /dev/null +++ b/docs/guide/globalaccelerator/aga-controller.md @@ -0,0 +1,296 @@ +# AWS Global Accelerator Controller + +## Introduction + +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). + +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. + +## Architecture + +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: + +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, or directly manages ELBs specified by their ARNs (endpointID) +3. Maintains and updates the status of the AWS Global Accelerator resources in the CRD +4. Handles cleanup and resource deletion when objects are removed + +## Key Features + +### Monolithic CRD Design + +The controller uses a single `GlobalAccelerator` resource to manage the entire AWS Global Accelerator hierarchy, including: + +- The accelerator itself +- Listeners with protocol and port range configurations +- Endpoint groups with region and traffic dial settings +- Endpoints from different Kubernetes resource types (Service, Ingress, and Gateway API resources managed by AWS Load Balancer Controller or ELBs referenced by their ARNs) + +This design simplifies management by keeping all configuration in one place while still allowing granular control over each component. + +### Full Lifecycle Management (CRUD) + +The controller manages the complete lifecycle of AWS Global Accelerator resources: + +- **Create**: Provisions new AWS Global Accelerator resources from CRD specifications +- **Read**: Updates CRD status with current state and ARNs from AWS +- **Update**: Modifies existing accelerator configurations when the CRD is updated +- **Delete**: Cleans up AWS resources when the CRD is deleted + +### Automatic Endpoint Discovery + +The AWS Global Accelerator Controller provides comprehensive auto-discovery capabilities that simplify Global Accelerator configuration in Kubernetes: + +#### Resource Discovery +The controller automatically discovers load balancers from multiple Kubernetes resource types in the local cluster: + +- **Service resources**: Discovers Network Load Balancers (NLBs) from Service type LoadBalancer +- **Ingress resources**: Discovers Application Load Balancers (ALBs) from Ingress resources +- **Gateway API resources**: Discovers ALBs and NLBs from Gateway API resources + +#### Automatic Configuration +For simple use cases, the controller can automatically configure listener protocol and port ranges based on the discovered endpoints or the ELB ARN: + +```yaml +kind: GlobalAccelerator +metadata: + name: autodiscovery-accelerator + namespace: test-ns +spec: + name: "autodiscovery-test-accelerator" + listeners: + - # Protocol and portRanges will be auto-discovered from the endpoint + endpointGroups: + - endpoints: + - type: Ingress + name: web-ingress + weight: 200 +``` + +### Manual Endpoint Registration + +For multi-region configurations or when referencing load balancers, you can manually specify endpoint ARNs instead of using auto-discovery: + +```yaml +spec: + listeners: + - protocol: TCP + portRanges: + - fromPort: 443 + toPort: 443 + endpointGroups: + - endpoints: + - type: EndpointID + endpointID: arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/app/my-load-balancer/1234567890123456 +``` + +> **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: +> +> ```yaml +> listeners: +> - protocol: TCP # Must explicitly specify protocol +> portRanges: # Must explicitly specify port ranges +> - fromPort: 443 +> toPort: 443 +> endpointGroups: +> - region: us-west-2 # Explicitly set a different region +> endpoints: +> - type: EndpointID +> endpointID: arn:aws:elasticloadbalancing:us-west-2:123456789012:loadbalancer/app/my-load-balancer/1234567890123456 +> ``` + +### BYOIP (Bring Your Own IP) Support + +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. + +#### Prerequisites + +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. + +#### Controller Limitations + +The AWS Global Accelerator Controller has the following limitations when working with BYOIP addresses: + +1. **Creation-Only Feature**: BYOIP addresses can only be specified during the initial creation of an accelerator. + +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. + +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. + +#### Configuration Example + +For BYOIP usage, specify the addresses in the `ipAddresses` field of your GlobalAccelerator resource: + +```yaml +spec: + ipAddressType: IPV4 + ipAddresses: + - "198.51.100.10" # Your own IP from BYOIP pool +``` + +### Status Reporting + +The controller updates the CRD status with important information from the AWS Global Accelerator: + +- The Accelerator's ARN for reference in other systems +- The default DNS name for the accelerator +- The dual-stack DNS name when available for IPv6 support +- IP address sets for both IPv4 and dual-stack configurations +- The current state of the accelerator (deployed, in progress, etc.) +- Conditions reflecting the health and status of the reconciliation process + +#### Accelerator Status States + +The `status.status` field in the GlobalAccelerator CRD reflects the current state of the accelerator in AWS. This field can have the following values: + +- **DEPLOYED**: The accelerator is fully deployed and operational +- **IN_PROGRESS**: The accelerator is being created or updated +- **FAILED**: The accelerator creation or update has failed + +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. + +If the status shows FAILED, check the controller logs and the `status.conditions` field for more detailed error information. + +## Intelligent Listener Management + +The AWS Global Accelerator Controller intelligently manages listeners to minimize service disruption during reconciliation. The controller: + +1. Preserves existing listeners when possible to maintain stable ARNs and associated resources +2. Manages conflicts carefully to ensure smooth transitions during updates +3. Optimizes the operation order to minimize downtime and maintain traffic flow + +This approach ensures reliable service while making necessary changes to your Global Accelerator configuration. + +## Port Overrides + +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. + +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. + +```yaml +endpointGroups: + - trafficDialPercentage: 100 + portOverrides: + - listenerPort: 443 # The port your Global Accelerator listener is using + endpointPort: 80 # The port your endpoint is listening on +``` + +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. + +> **Note**: The AWS Global Accelerator Controller handles all port override constraints automatically, ensuring your configuration is valid. + +## Sample CRDs + +### Basic Global Accelerator with Single TCP Port + +```yaml +apiVersion: aga.k8s.aws/v1beta1 +kind: GlobalAccelerator +metadata: + name: simple-accelerator + namespace: default +spec: + name: "simple-accelerator" + ipAddressType: IPV4 + tags: + Environment: "production" + listeners: + - protocol: TCP + portRanges: + - fromPort: 80 + toPort: 80 + clientAffinity: NONE +``` + +### Multiple Port Ranges with Source IP Affinity + +```yaml +apiVersion: aga.k8s.aws/v1beta1 +kind: GlobalAccelerator +metadata: + name: multi-port-accelerator + namespace: default +spec: + ipAddressType: IPV4 + listeners: + - protocol: TCP + portRanges: + - fromPort: 80 + toPort: 80 + - fromPort: 443 + toPort: 443 + clientAffinity: SOURCE_IP +``` + +### Complex Configuration with Multiple Listeners and Endpoints + +```yaml +apiVersion: aga.k8s.aws/v1beta1 +kind: GlobalAccelerator +metadata: + name: complex-accelerator + namespace: default +spec: + ipAddressType: IPV4 + tags: + Environment: "test" + Team: "platform" + listeners: + - protocol: TCP + portRanges: + - fromPort: 80 + toPort: 80 + - fromPort: 443 + toPort: 443 + clientAffinity: SOURCE_IP + endpointGroups: + - trafficDialPercentage: 100 + portOverrides: + - listenerPort: 80 + endpointPort: 8081 + endpoints: + - type: Service + name: service-nlb-1 + weight: 128 + clientIPPreservationEnabled: true + - type: Ingress + name: test-ingress + weight: 240 + - protocol: UDP + portRanges: + - fromPort: 53 + toPort: 53 + clientAffinity: NONE +``` + +## Troubleshooting + +Common issues and their solutions: + +### Status Shows Failure + +Check the controller logs for detailed error messages: + +```bash +kubectl logs -n kube-system -l app.kubernetes.io/name=aws-load-balancer-controller +``` + +### Endpoint Discovery Not Working + +Ensure your Service/Ingress/Gateway resources: + +1. Are properly configured with correct annotations +2. Have been successfully provisioned with actual AWS load balancers +3. Are in the same namespace as specified in the endpoint + +## Current Limitations and Future Enhancements + +### Cross-Namespace Reference Limitations + +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. + +## References + +- [AWS Global Accelerator Developer Guide](https://docs.aws.amazon.com/global-accelerator/latest/dg/what-is-global-accelerator.html) +- [GlobalAccelerator CRD Reference](spec.md) +- [AWS Load Balancer Controller Installation](../../deploy/installation.md) diff --git a/docs/guide/globalaccelerator/examples.md b/docs/guide/globalaccelerator/examples.md new file mode 100644 index 000000000..7d651e940 --- /dev/null +++ b/docs/guide/globalaccelerator/examples.md @@ -0,0 +1,310 @@ +# AWS Global Accelerator Controller Examples + +This document provides practical examples for using the AWS Global Accelerator Controller feature of the AWS Load Balancer Controller in various scenarios. + +## Basic Examples + +### Single Ingress Acceleration + +This example creates a Global Accelerator that accelerates traffic to a single ingress resource. It's the simplest configuration and ideal for getting started. + +```yaml +apiVersion: aga.k8s.aws/v1beta1 +kind: GlobalAccelerator +metadata: + name: web-app-accelerator + namespace: web-app +spec: + name: "web-app-accelerator" + ipAddressType: IPV4 + tags: + Environment: "production" + Application: "web-app" + listeners: + - protocol: TCP + portRanges: + - fromPort: 80 + toPort: 80 + - fromPort: 443 + toPort: 443 + clientAffinity: NONE + endpointGroups: + - endpoints: + - type: Ingress + name: web-app-ingress + namespace: web-app +``` + +### Network Load Balancer Service Acceleration + +This example accelerates traffic to a Network Load Balancer provisioned by a Kubernetes Service of type LoadBalancer. + +```yaml +apiVersion: aga.k8s.aws/v1beta1 +kind: GlobalAccelerator +metadata: + name: api-service-accelerator + namespace: api +spec: + name: "api-service-accelerator" + ipAddressType: IPV4 + listeners: + - protocol: TCP + portRanges: + - fromPort: 443 + toPort: 443 + clientAffinity: SOURCE_IP + endpointGroups: + - endpoints: + - type: Service + name: api-service + weight: 128 + clientIPPreservationEnabled: true +``` + +### Gateway API Acceleration + +This example accelerates traffic to a Gateway API resource (requires Gateway API CRDs installed in your cluster). + +```yaml +apiVersion: aga.k8s.aws/v1beta1 +kind: GlobalAccelerator +metadata: + name: gateway-accelerator + namespace: gateway-ns +spec: + name: "gateway-accelerator" + ipAddressType: IPV4 + listeners: + - protocol: TCP + portRanges: + - fromPort: 80 + toPort: 80 + - fromPort: 443 + toPort: 443 + endpointGroups: + - endpoints: + - type: Gateway + name: my-gateway + weight: 128 +``` + +### Auto-Discovery Configuration + +This minimal configuration uses the auto-discovery feature to determine protocol and port ranges from the ingress resource. + +```yaml +apiVersion: aga.k8s.aws/v1beta1 +kind: GlobalAccelerator +metadata: + name: autodiscovery-accelerator + namespace: default +spec: + name: "autodiscovery-accelerator" + listeners: + - endpointGroups: + - endpoints: + - type: Ingress + name: web-ingress + namespace: default + weight: 200 +``` + +## Advanced Examples + +### Multiple Listeners with Different Protocols + +This example creates a Global Accelerator with both TCP and UDP listeners for different services. + +```yaml +apiVersion: aga.k8s.aws/v1beta1 +kind: GlobalAccelerator +metadata: + name: multi-protocol-accelerator + namespace: default +spec: + name: "multi-protocol-accelerator" + ipAddressType: IPV4 + listeners: + - protocol: TCP + portRanges: + - fromPort: 80 + toPort: 80 + - fromPort: 443 + toPort: 443 + clientAffinity: SOURCE_IP + endpointGroups: + - endpoints: + - type: Ingress + name: web-ingress + - protocol: UDP + portRanges: + - fromPort: 53 + toPort: 53 + clientAffinity: NONE + endpointGroups: + - endpoints: + - type: Service + name: dns-service +``` + +### Traffic Distribution with Multiple Endpoints + +This example distributes traffic between multiple endpoints with different weights. + +```yaml +apiVersion: aga.k8s.aws/v1beta1 +kind: GlobalAccelerator +metadata: + name: traffic-distribution-accelerator + namespace: default +spec: + name: "traffic-distribution-accelerator" + ipAddressType: IPV4 + listeners: + - protocol: TCP + portRanges: + - fromPort: 80 + toPort: 80 + endpointGroups: + - endpoints: + - type: Service + name: service-1 + weight: 200 # Higher weight - receives more traffic + - type: Service + name: service-2 + weight: 100 # Lower weight - receives less traffic +``` + +### Port Override Example + +This example demonstrates port overrides to map external ports to different internal ports. + +```yaml +apiVersion: aga.k8s.aws/v1beta1 +kind: GlobalAccelerator +metadata: + name: port-override-accelerator + namespace: default +spec: + name: "port-override-accelerator" + ipAddressType: IPV4 + listeners: + - protocol: TCP + portRanges: + - fromPort: 80 + toPort: 80 + - fromPort: 443 + toPort: 443 + endpointGroups: + - portOverrides: + - listenerPort: 80 + endpointPort: 8080 # Redirects traffic from port 80 to port 8080 + - listenerPort: 443 + endpointPort: 8443 # Redirects traffic from port 443 to port 8443 + endpoints: + - type: Service + name: backend-service +``` + +### Cross-Region Manual Endpoint + +This example uses manual endpoint registration with ARNs for cross-region configurations. + +```yaml +apiVersion: aga.k8s.aws/v1beta1 +kind: GlobalAccelerator +metadata: + name: cross-region-accelerator + namespace: default +spec: + name: "cross-region-accelerator" + ipAddressType: IPV4 + listeners: + - protocol: TCP + portRanges: + - fromPort: 443 + toPort: 443 + endpointGroups: + # Local region endpoint group + - endpoints: + - type: Service + name: local-service + # Remote region endpoint group + - region: us-west-2 # Specific AWS region + trafficDialPercentage: 50 # Split traffic 50% + endpoints: + - type: EndpointID + endpointID: arn:aws:elasticloadbalancing:us-west-2:123456789012:loadbalancer/app/remote-lb/1234567890123456 + weight: 128 +``` + +### BYOIP (Bring Your Own IP) Configuration + +This example demonstrates using your own IP addresses with Global Accelerator. + +```yaml +apiVersion: aga.k8s.aws/v1beta1 +kind: GlobalAccelerator +metadata: + name: byoip-accelerator + namespace: default +spec: + name: "byoip-accelerator" + ipAddressType: IPV4 + ipAddresses: + - "198.51.100.10" # Your own IP from BYOIP pool + listeners: + - protocol: TCP + portRanges: + - fromPort: 443 + toPort: 443 + endpointGroups: + - endpoints: + - type: Ingress + name: secure-ingress +``` + +### Dual-Stack (IPv4 and IPv6) Configuration + +This example sets up a dual-stack Global Accelerator that supports both IPv4 and IPv6. + +```yaml +apiVersion: aga.k8s.aws/v1beta1 +kind: GlobalAccelerator +metadata: + name: dual-stack-accelerator + namespace: default +spec: + name: "dual-stack-accelerator" + ipAddressType: DUAL_STACK # Support both IPv4 and IPv6 + listeners: + - protocol: TCP + portRanges: + - fromPort: 80 + toPort: 80 + - fromPort: 443 + toPort: 443 + endpointGroups: + - endpoints: + - type: Service + name: dual-stack-service +``` + +## Important Limitations and Best Practices + +### Cross-Namespace References + +In the initial release, the AWS Global Accelerator Controller has a limitation regarding cross-namespace references: + +1. **Same-Namespace Default**: By default, the controller expects endpoints to be in the same namespace as the GlobalAccelerator resource. + +2. **Security Considerations**: Cross-namespace references without proper security controls can present security risks. + +### BYOIP Considerations + +When using Bring Your Own IP (BYOIP) with Global Accelerator: + +1. **Creation-Only**: IP addresses can only be set during initial creation and cannot be changed afterward. + +2. **New Accelerator Required**: If you need to change IP addresses, you must create a new GlobalAccelerator resource. diff --git a/docs/guide/globalaccelerator/installation.md b/docs/guide/globalaccelerator/installation.md new file mode 100644 index 000000000..13b9216ed --- /dev/null +++ b/docs/guide/globalaccelerator/installation.md @@ -0,0 +1,88 @@ +# Installation and Prerequisites for AWS Global Accelerator Controller + +This guide covers the prerequisites and installation steps required to use the AWS Global Accelerator Controller feature in the AWS Load Balancer Controller. + +## Prerequisites + +> **Important**: AWS Global Accelerator is only available in the commercial AWS partition. It is not available in other partitions such as the AWS GovCloud (aws-us-gov) or AWS China (aws-cn) partitions. + +### Configure IAM + +**Additional IAM Permissions for Global Accelerator**: + +In addition to the standard AWS Load Balancer Controller permissions that you already have configured, you'll need to add specific permissions for the Global Accelerator controller feature. We recommend creating a dedicated policy named `AWSGlobalAcceleratorControllerIAMPolicy` that includes these additional permissions. + +- [Complete IAM Policy for Global Accelerator Controller](../../install/aga_controller_iam_policy.md) + +This additional policy includes permissions for: + +- Creating and managing Global Accelerator resources (accelerators, listeners, endpoint groups, endpoints) +- Tagging resources for proper identification and management +- Creating service-linked roles required by Global Accelerator +- Reading load balancer information for endpoint discovery + +You can attach this policy using the same method you've used for the AWS Load Balancer Controller permissions - either through IAM Roles for Service Accounts (IRSA) or by attaching it to your worker node IAM roles, depending on your cluster setup. + +### Kubernetes Cluster Requirements + +1. **Kubernetes Version**: The AWS Global Accelerator Controller requires Kubernetes version 1.19 or later. + +2. **AWS Load Balancer Controller**: The Global Accelerator feature is integrated into the AWS Load Balancer Controller version 2.17.0 or later. + +3. **IAM Permissions**: The IAM role used by the AWS Load Balancer Controller must include the Global Accelerator permissions listed above. + +## Installation + +The AWS Global Accelerator Controller is built into the AWS Load Balancer Controller and requires minimal additional configuration. Follow these steps to install and enable the feature: + +- **Follow the standard AWS Load Balancer Controller installation steps** from the [official installation guide](../../deploy/installation.md). + +- **Install the GlobalAccelerator Custom Resource Definition (CRD)**: + + ```bash + kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/main/config/crd/aga/bases/aga.k8s.aws_globalaccelerators.yaml + ``` + + Verify the CRD is installed: + + ```bash + kubectl get crd | grep globalaccelerators.aga.k8s.aws + ``` + +- **Enable the required feature gates** by adding the following flags to your controller deployment: + + ``` + --feature-gates=GlobalAcceleratorController=true,EnableRGTAPI=true + ``` + + When using Helm, these can be enabled with the following parameters: + + ``` + --set controllerConfig.featureGates.GlobalAcceleratorController=true --set controllerConfig.featureGates.EnableRGTAPI=true + ``` + +> **Note**: Both feature gates are required for the AWS Global Accelerator Controller to function properly: + +> - `GlobalAcceleratorController`: Enables the core Global Accelerator controller functionality +> - `EnableRGTAPI`: Enables the Resource Group Tagging API integration needed for tagging + +## Configuration Options + +The AWS Global Accelerator Controller supports the following configuration options that can be set as command-line flags for the AWS Load Balancer Controller: + +| Flag | Type | Default | Description | +| --- | --- |------|----------------------------------------------------------------------------------| +| `--feature-gates=GlobalAcceleratorController` | boolean | false | Enable the Global Accelerator controller feature | +| `--feature-gates=EnableRGTAPI` | boolean | false | Enable the Resource Group Tagging API integration for tagging | +| `--global-accelerator-max-concurrent-reconciles` | integer | 1 | Maximum number of concurrent reconciles for Global Accelerator resources | +| `--global-accelerator-max-exponential-backoff-delay` | duration | 16m40s | Maximum delay for exponential backoff for Global Accelerator resource reconciles | + +## AWS Global Accelerator Service Quotas + +For the most up-to-date quotas, refer to the [AWS Global Accelerator quotas documentation](https://docs.aws.amazon.com/global-accelerator/latest/dg/limits-global-accelerator.html). + +## Next Steps + +1. [AWS Global Accelerator Controller Guide](aga-controller.md) +2. [GlobalAccelerator CRD Reference](spec.md) +3. [Examples](examples.md) diff --git a/docs/install/aga_controller_iam_policy.md b/docs/install/aga_controller_iam_policy.md new file mode 100644 index 000000000..fddfb5489 --- /dev/null +++ b/docs/install/aga_controller_iam_policy.md @@ -0,0 +1,155 @@ +# IAM Policy for AWS Global Accelerator Controller + +This document outlines the required IAM permissions for the AWS Global Accelerator Controller feature of the AWS Load Balancer Controller. + +## IAM Policy + +Create an IAM policy with the following permissions to allow the controller to manage AWS Global Accelerator resources: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "iam:CreateServiceLinkedRole" + ], + "Resource": "*", + "Condition": { + "StringEquals": { + "iam:AWSServiceName": [ + "globalaccelerator.amazonaws.com" + ] + } + } + }, + { + "Effect": "Allow", + "Action": [ + "globalaccelerator:DescribeAccelerator", + "globalaccelerator:DescribeEndpointGroup", + "globalaccelerator:DescribeListener", + "globalaccelerator:ListAccelerators", + "globalaccelerator:ListEndpointGroups", + "globalaccelerator:ListListeners", + "globalaccelerator:ListTagsForResource", + "ec2:DescribeRegions" + ], + "Resource": "*" + }, + { + "Effect": "Allow", + "Action": [ + "globalaccelerator:CreateAccelerator" + ], + "Resource": "*", + "Condition": { + "Null": { + "aws:RequestTag/elbv2.k8s.aws/cluster": "false" + }, + "StringEquals": { + "aws:RequestTag/aga.k8s.aws/resource": "GlobalAccelerator" + } + } + }, + { + "Effect": "Allow", + "Action": [ + "globalaccelerator:UpdateAccelerator", + "globalaccelerator:DeleteAccelerator", + "globalaccelerator:CreateListener", + "globalaccelerator:UpdateListener", + "globalaccelerator:DeleteListener", + "globalaccelerator:CreateEndpointGroup", + "globalaccelerator:UpdateEndpointGroup", + "globalaccelerator:DeleteEndpointGroup", + "globalaccelerator:AddEndpoints", + "globalaccelerator:RemoveEndpoints" + ], + "Resource": [ + "arn:aws:globalaccelerator::*:accelerator/*", + "arn:aws:globalaccelerator::*:accelerator/*/listener/*", + "arn:aws:globalaccelerator::*:accelerator/*/listener/*/endpoint-group/*" + ], + "Condition": { + "Null": { + "aws:ResourceTag/elbv2.k8s.aws/cluster": "false" + }, + "StringEquals": { + "aws:ResourceTag/aga.k8s.aws/resource": "GlobalAccelerator" + } + } + }, + { + "Effect": "Allow", + "Action": [ + "globalaccelerator:TagResource", + "globalaccelerator:UntagResource" + ], + "Resource": "arn:aws:globalaccelerator::*:accelerator/*", + "Condition": { + "Null": { + "aws:RequestTag/elbv2.k8s.aws/cluster": "true", + "aws:ResourceTag/elbv2.k8s.aws/cluster": "false" + }, + "StringEquals": { + "aws:ResourceTag/aga.k8s.aws/resource": "GlobalAccelerator" + } + } + }, + { + "Effect": "Allow", + "Action": [ + "globalaccelerator:TagResource" + ], + "Resource": "arn:aws:globalaccelerator::*:accelerator/*", + "Condition": { + "Null": { + "aws:RequestTag/elbv2.k8s.aws/cluster": "false" + }, + "StringEquals": { + "aws:RequestTag/aga.k8s.aws/resource": "GlobalAccelerator" + } + } + } + ] +} +``` + +## Permission Requirements Explanation + +This policy provides fine-grained access to AWS Global Accelerator resources: + +### Service-Linked Role Creation + +Allows the controller to create service-linked roles required by Global Accelerator: +- `iam:CreateServiceLinkedRole` for `globalaccelerator.amazonaws.com` + +### Read Permissions + +Allows listing and describing Global Accelerator resources: +- `globalaccelerator:Describe*` and `globalaccelerator:List*` operations +- `ec2:DescribeRegions` for cross-region endpoint configuration + +### Resource Creation and Management + +Allows creation, updating, and deletion of Global Accelerator resources with appropriate tagging: +- Resource creation limited by required tags +- Resource modification limited to resources with appropriate tags +- Endpoint management tied to tagged resources + +### Tag Management + +Allows the controller to manage tags on Global Accelerator resources: +- Tagging operations constrained by tag conditions to prevent modification of resources not owned by the controller + +## AWS Load Balancer Controller Integration + +When configuring the AWS Load Balancer Controller to use this policy: + +1. Create the IAM policy in your AWS account +2. Attach the policy to the IAM role used by the controller +3. Ensure the controller's service account is configured to use the role via IRSA (IAM Roles for Service Accounts) + +For more details on setting up IAM roles for the controller, see the [main installation documentation](../deploy/installation.md). diff --git a/go.mod b/go.mod index 7ea5607cd..d4b0bb9b8 100644 --- a/go.mod +++ b/go.mod @@ -1,6 +1,6 @@ module sigs.k8s.io/aws-load-balancer-controller -go 1.24.9 +go 1.24.11 require ( github.com/aws/aws-sdk-go-v2 v1.40.0 diff --git a/helm/aws-load-balancer-controller/values.yaml b/helm/aws-load-balancer-controller/values.yaml index 794d0e9b6..4014b723a 100644 --- a/helm/aws-load-balancer-controller/values.yaml +++ b/helm/aws-load-balancer-controller/values.yaml @@ -391,7 +391,7 @@ controllerConfig: # NLBHealthCheckAdvancedConfig: true # ALBSingleSubnet: false # LBCapacityReservation: true - # AGAController: false + # GlobalAcceleratorController: false # EnhancedDefaultBehavior: false # EnableDefaultTagsLowPriority: false # ALBTargetControlAgent: false diff --git a/main.go b/main.go index ce0ec948a..ca7f7ffaa 100644 --- a/main.go +++ b/main.go @@ -241,7 +241,7 @@ func main() { } // Setup GlobalAccelerator controller only if enabled - if aga.IsAGAControllerEnabled(controllerCFG.FeatureGates, cloud.Region()) { + if aga.IsGlobalAcceleratorControllerEnabled(controllerCFG.FeatureGates, cloud.Region()) { agaReconciler := agacontroller.NewGlobalAcceleratorReconciler(mgr.GetClient(), mgr.GetEventRecorderFor("globalAccelerator"), finalizerManager, controllerCFG, cloud, ctrl.Log.WithName("controllers").WithName("globalAccelerator"), lbcMetricsCollector, reconcileCounters) if err := agaReconciler.SetupWithManager(ctx, mgr, clientSet); err != nil { @@ -442,7 +442,7 @@ func main() { networkingwebhook.NewIngressValidator(mgr.GetClient(), controllerCFG.IngressConfig, ctrl.Log, lbcMetricsCollector).SetupWithManager(mgr) // Setup GlobalAccelerator validator only if enabled - if aga.IsAGAControllerEnabled(controllerCFG.FeatureGates, cloud.Region()) { + if aga.IsGlobalAcceleratorControllerEnabled(controllerCFG.FeatureGates, cloud.Region()) { agawebhook.NewGlobalAcceleratorValidator(ctrl.Log, lbcMetricsCollector).SetupWithManager(mgr) } //+kubebuilder:scaffold:builder diff --git a/mkdocs.yml b/mkdocs.yml index d01912ac4..4adeab11f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -40,6 +40,11 @@ nav: - ListenerRuleConfiguration: guide/gateway/listenerruleconfig.md - Gateway Chaining: guide/gateway/gateway_chaining.md - Specification: guide/gateway/spec.md + - AWS Global Accelerator (New): + - Overview: guide/globalaccelerator/aga-controller.md + - Installation: guide/globalaccelerator/installation.md + - Examples: guide/globalaccelerator/examples.md + - Specification: guide/globalaccelerator/spec.md - Tasks: - Cognito Authentication: guide/tasks/cognito_authentication.md - SSL Redirect: guide/tasks/ssl_redirect.md diff --git a/pkg/aga/utils.go b/pkg/aga/utils.go index f4e96ee37..a18323a14 100644 --- a/pkg/aga/utils.go +++ b/pkg/aga/utils.go @@ -17,11 +17,11 @@ func IsPortInRanges(port int32, portRanges []agamodel.PortRange) bool { return false } -// IsAGAControllerEnabled checks if the AGA controller is both enabled via feature gate +// IsGlobalAcceleratorControllerEnabled checks if the Global Accelerator controller is both enabled via feature gate // and if the region is in a partition that supports Global Accelerator -func IsAGAControllerEnabled(featureGates config.FeatureGates, region string) bool { - // First check if AGA controller is enabled via feature gate - if !featureGates.Enabled(config.AGAController) { +func IsGlobalAcceleratorControllerEnabled(featureGates config.FeatureGates, region string) bool { + // First check if Global Accelerator controller is enabled via feature gate + if !featureGates.Enabled(config.GlobalAcceleratorController) { return false } diff --git a/pkg/aga/utils_test.go b/pkg/aga/utils_test.go index e029259c4..e444808c6 100644 --- a/pkg/aga/utils_test.go +++ b/pkg/aga/utils_test.go @@ -8,7 +8,7 @@ import ( agamodel "sigs.k8s.io/aws-load-balancer-controller/pkg/model/aga" ) -func TestIsAGAControllerEnabled(t *testing.T) { +func TestIsGlobalAcceleratorControllerEnabled(t *testing.T) { tests := []struct { name string featureGates config.FeatureGates @@ -19,7 +19,7 @@ func TestIsAGAControllerEnabled(t *testing.T) { name: "Feature gate disabled", featureGates: func() config.FeatureGates { fg := config.NewFeatureGates() - fg.Disable(config.AGAController) + fg.Disable(config.GlobalAcceleratorController) return fg }(), region: "us-west-2", @@ -29,7 +29,7 @@ func TestIsAGAControllerEnabled(t *testing.T) { name: "Feature gate enabled, standard region", featureGates: func() config.FeatureGates { fg := config.NewFeatureGates() - fg.Enable(config.AGAController) + fg.Enable(config.GlobalAcceleratorController) return fg }(), region: "us-west-2", @@ -39,7 +39,7 @@ func TestIsAGAControllerEnabled(t *testing.T) { name: "Feature gate enabled, China region", featureGates: func() config.FeatureGates { fg := config.NewFeatureGates() - fg.Enable(config.AGAController) + fg.Enable(config.GlobalAcceleratorController) return fg }(), region: "cn-north-1", @@ -49,7 +49,7 @@ func TestIsAGAControllerEnabled(t *testing.T) { name: "Feature gate enabled, GovCloud region", featureGates: func() config.FeatureGates { fg := config.NewFeatureGates() - fg.Enable(config.AGAController) + fg.Enable(config.GlobalAcceleratorController) return fg }(), region: "us-gov-west-1", @@ -59,7 +59,7 @@ func TestIsAGAControllerEnabled(t *testing.T) { name: "Feature gate enabled, ISO region", featureGates: func() config.FeatureGates { fg := config.NewFeatureGates() - fg.Enable(config.AGAController) + fg.Enable(config.GlobalAcceleratorController) return fg }(), region: "us-iso-east-1", @@ -69,7 +69,7 @@ func TestIsAGAControllerEnabled(t *testing.T) { name: "Feature gate enabled, ISO-E region", featureGates: func() config.FeatureGates { fg := config.NewFeatureGates() - fg.Enable(config.AGAController) + fg.Enable(config.GlobalAcceleratorController) return fg }(), region: "eu-isoe-west-1", @@ -79,7 +79,7 @@ func TestIsAGAControllerEnabled(t *testing.T) { name: "Feature gate enabled, upper case region", featureGates: func() config.FeatureGates { fg := config.NewFeatureGates() - fg.Enable(config.AGAController) + fg.Enable(config.GlobalAcceleratorController) return fg }(), region: "US-WEST-2", @@ -89,8 +89,8 @@ func TestIsAGAControllerEnabled(t *testing.T) { for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { - if got := IsAGAControllerEnabled(tt.featureGates, tt.region); got != tt.want { - t.Errorf("IsAGAControllerEnabled() = %v, want %v", got, tt.want) + if got := IsGlobalAcceleratorControllerEnabled(tt.featureGates, tt.region); got != tt.want { + t.Errorf("IsGlobalAcceleratorControllerEnabled() = %v, want %v", got, tt.want) } }) } diff --git a/pkg/config/feature_gates.go b/pkg/config/feature_gates.go index e9ee7d09f..3cbef65d1 100644 --- a/pkg/config/feature_gates.go +++ b/pkg/config/feature_gates.go @@ -27,7 +27,7 @@ const ( SubnetDiscoveryByReachability Feature = "SubnetDiscoveryByReachability" NLBGatewayAPI Feature = "NLBGatewayAPI" ALBGatewayAPI Feature = "ALBGatewayAPI" - AGAController Feature = "AGAController" + GlobalAcceleratorController Feature = "GlobalAcceleratorController" EnhancedDefaultBehavior Feature = "EnhancedDefaultBehavior" EnableDefaultTagsLowPriority Feature = "EnableDefaultTagsLowPriority" ALBTargetControlAgent Feature = "ALBTargetControlAgent" @@ -73,7 +73,7 @@ func NewFeatureGates() FeatureGates { LBCapacityReservation: true, NLBGatewayAPI: false, ALBGatewayAPI: false, - AGAController: false, + GlobalAcceleratorController: false, EnableTCPUDPListenerType: false, EnhancedDefaultBehavior: false, EnableDefaultTagsLowPriority: false,