feat: Support for deploying LB to multiple regions using region property on LoadBalancerConfiguration

[aleksanderaleksic]

Description

Motivation: Support deploying edge ALBs in AWS regions closer to end users, enabling TLS termination at the edge to reduce latency. For example, a cluster running in us-east-1 can now deploy an ALB in ap-northeast-1 via the Gateway API, terminating TLS in Tokyo rather than routing encrypted traffic back to the US.

What this PR does

Adds multi-region support to the AWS Load Balancer Controller's Gateway API implementation. A new optional region field on LoadBalancerConfiguration allows users to specify an AWS region for the ALB/NLB, and the controller handles all cross-region resource management automatically.

Key changes:

1. LoadBalancerConfiguration API (apis/gateway/v1beta1/loadbalancerconfig_types.go)

   • Added Region and VpcID fields to LoadBalancerConfigurationSpec, allowing users to target a specific AWS region and VPC for the load balancer.

2. ReconcileContext / Cloud Provider (pkg/gateway/cloud_provider.go)

   • New ReconcileContext encapsulates region-specific AWS clients (ELBV2, EC2, ACM) and resolvers (subnets, VPC info, security groups, cert discovery, tagging manager, TG ARN mapper).
   • ReconcileContext is always passed to Build() — for the default region it wraps the existing clients/resolvers; for non-default regions all fields are region-scoped.
   • IsCrossRegion() bool on the context lets downstream code branch on cross-region without comparing VPC IDs or regions directly.
   • GetReconcileContext auto-discovers the VPC in the target region (via vpcId, vpcSelector, or first subnet) and caches the result.

3. Gateway Controller (controllers/gateway/gateway_controller.go)

   • Always obtains a ReconcileContext from CloudProvider and passes it through to the model builder and stack deployer.
   • Uses reconcileContext.IsCrossRegion() to select the region-scoped stack deployer and backend SG provider.

4. Model Builder (pkg/gateway/model/base_model_builder.go)

   • Build() takes a required ReconcileContextInterface parameter (no variadic/optional). All effective clients and resolvers come from the RC unconditionally.
   • ReconcileContextInterface exposes IsCrossRegion() — used to disable backend SG allocation and clear the backend SG token on TargetGroupBinding resources for cross-region gateways (cross-region SG references are not supported by AWS).

5. Region-aware AWS clients (pkg/aws/region.go)

   • NewCloudForRegion, NewEC2ClientForRegion, NewELBV2ForRegion — factory functions for creating region-scoped AWS service clients without EC2 metadata.
   • regionStubCloud — minimal Cloud implementation for ELBV2-only operations (webhooks, ARN validation).

6. TGB Webhooks (webhooks/elbv2/targetgroup_helper.go, targetgroupbinding_mutator.go, targetgroupbinding_validator.go)

   • ELBV2ClientProvider type and resolveELBV2ForTGB helper extract the region from a target group ARN and return the correct regional ELBV2 client.
   • Mutator and validator use the regional client for DescribeTargetGroups calls, preventing ValidationError when validating cross-region TG ARNs.

7. TGB Reconciler (pkg/targetgroupbinding/targets_manager.go, resource_manager.go)

   • cachedTargetsManager.resolveELBV2() dynamically selects the correct ELBV2 client based on target group ARN region for RegisterTargets, DeregisterTargets, and DescribeTargetHealth.
   • generateOverrideAzFn now handles cross-region VPCs (not just cross-account) — when the TGB's VPC differs from the controller's VPC and DescribeVpcs returns InvalidVpcID.NotFound, target AZs are overridden to "all".

8. Security Group Synthesizer (pkg/deploy/ec2/security_group_synthesizer.go)

   • Handles cross-region SG cleanup gracefully.

9. Documentation (docs/guide/gateway/loadbalancerconfig.md, docs/guide/gateway/spec.md)

   • Documents the new region and vpcID fields with usage examples.

10. Tests

    • webhooks/elbv2/targetgroup_helper_test.go — regionFromTGARN and resolveELBV2ForTGB (18 cases)
    • pkg/targetgroupbinding/targets_manager_resolve_test.go — cachedTargetsManager.resolveELBV2 (7 cases)
    • pkg/aws/region_test.go — regionStubCloud interface compliance and getters (12 cases)
    • pkg/gateway/cloud_provider_test.go — ReconcileContext getters, IsCrossRegion(), GetReconcileContext default path, resolveVPCForRegion, resolveVPCFromSelector, resolveVPCFromFirstSubnet (21 cases)
    • Updated pkg/targetgroupbinding/resource_manager_test.go — cross-region VPC override AZ test case
    • Updated pkg/gateway/model/model_build_target_group_binding_network_test.go — nil backend SG token (cross-region) case

Example usage

apiVersion: gateway.k8s.aws/v1beta1
kind: LoadBalancerConfiguration
metadata:
  name: edge-tokyo
spec:
  region: ap-northeast-1
  scheme: internet-facing
  # vpcID is auto-discovered from the target region

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

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

[linux-foundation-easycla]

• ❌ - login: @aleksanderaleksic / name: Aleksander Aleksic . The commit (2708e16) is not authorized under a signed CLA. Please click here to be authorized. For further assistance with EasyCLA, please submit a support request ticket.

[k8s-ci-robot]

Welcome @aleksanderaleksic!

It looks like this is your first PR to kubernetes-sigs/aws-load-balancer-controller 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/aws-load-balancer-controller has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

[k8s-ci-robot]

Hi @aleksanderaleksic. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: aleksanderaleksic
Once this PR has been reviewed and has the lgtm label, please assign oliviassss for approval. For more information see the Code Review Process.

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

Details

Needs approval from an approver in each of these files:

• OWNERS

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

[zac-nixon]

Hi. I wish you would have reached out to discuss this, prior to writing all this code :(. We are unlikely to accept this contribution as AWS offers CDN capabilities already (like CloudFront). What is your use-case?

[aleksanderaleksic]

Hi @zac-nixon.
Sorry for creating this PR without much context.

To be honest I did not realize that we could use Cloudfront to get similar results so thanks for enlightening me about that.

We have our workloads based in us-east-1 and we have some customers in ASIA and want to make sure the TLS handshake does not have to go to us-east-1 every time, so we want to terminate TLS in ap-northeast-1.
Cloudfront would solve that for us but we also have some requirements around Anycast Static IPs, and while Cloudfront supports that we dont want to pay $3k per month for that feature. So instead we have a global accelerator for this.

Also we dont want to deploy a EKS cluster in ASIA as of now, so we accept the latency between the edge ALBs and the instances in us-east-1. In fact our benchmarks shows that we have cut the overall request latency by 50% and that the TLS handshake is now 68x faster than before, so for us this is a huge win.

I hope this gives you a better understanding of why we want to de able to manage ALBs from a different region.

Given that the aws-load-balancer-controller does not support multiple deployments in a single cluster and its bound to a single region, we where not able to achieve the same results as with the suggested approach in any other way.

[k8s-ci-robot]

PR needs rebase.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.