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.

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.

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).

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.

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.

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.

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.

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.

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.

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.

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

Cross-Namespace References with GlobalAccelerator¶

This example demonstrates how to configure a GlobalAccelerator to reference multiple endpoint types (Ingress, Service, Gateway) from different namespaces using ReferenceGrant resources

Step 1: Create the ReferenceGrant Resources¶

# ReferenceGrant in ingress-ns
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-aga-to-ingress
  namespace: ingress-ns
spec:
  from:
  - group: aga.k8s.aws
    kind: GlobalAccelerator
    namespace: accelerator-ns
  to:
  - group: networking.k8s.io
    kind: Ingress
---
# ReferenceGrant in service-ns
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-aga-to-service
  namespace: service-ns
spec:
  from:
  - group: aga.k8s.aws
    kind: GlobalAccelerator
    namespace: accelerator-ns
  to:
  - group: ""
    kind: Service
---
# ReferenceGrant in gateway-ns
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-aga-to-gateway
  namespace: gateway-ns
spec:
  from:
  - group: aga.k8s.aws
    kind: GlobalAccelerator
    namespace: accelerator-ns
  to:
  - group: gateway.networking.k8s.io
    kind: Gateway

Step 2: Create the GlobalAccelerator Resource with Cross-Namespace References¶

apiVersion: aga.k8s.aws/v1beta1
kind: GlobalAccelerator
metadata:
name: cross-namespace-example
namespace: accelerator-ns
spec:
acceleratorName: cross-namespace-accelerator
ipAddressType: IPV4
listeners:
- protocol: TCP
  portRanges:
    - fromPort: 80
      toPort: 80
      clientAffinity: NONE
      endpointGroups:
    - trafficDialPercentage: 100
      endpoints:
      # Ingress endpoint in ingress-ns
        - type: INGRESS
          name: example-ingress
          namespace: ingress-ns
          weight: 100
      # Service endpoint in service-ns
        - type: SERVICE
          name: example-service
          namespace: service-ns
          weight: 100
      # Gateway endpoint in gateway-ns
        - type: GATEWAY
          name: example-gateway
          namespace: gateway-ns
          weight: 100

Important Limitations and Best Practices¶

BYOIP Considerations¶

When using Bring Your Own IP (BYOIP) with Global Accelerator:

Creation-Only: IP addresses can only be set during initial creation and cannot be changed afterward.
New Accelerator Required: If you need to change IP addresses, you must create a new GlobalAccelerator resource.