AWS CDK Global Accelerator

Common errors

• ModuleNotFoundError: No module named 'aws_cdk.aws_globalaccelerator'

  cause The `aws-cdk-aws-globalaccelerator` Python package has not been installed in your environment, or your Python interpreter path is incorrect.
  fix Run `pip install aws-cdk-aws-globalaccelerator aws-cdk.core` in your project's virtual environment. Ensure the correct Python interpreter is selected in your IDE.

• jsii.errors.JSIIError: The specified Endpoint Group region us-west-2 does not match the listener's region for accelerator ...

  cause Global Accelerator is a global service, but its endpoint groups are regional. This error indicates that the `endpoint_group_region` specified for an `EndpointGroup` is invalid or refers to a region that doesn't host the actual endpoints for that listener.
  fix Verify that the `endpoint_group_region` property in your `ga.EndpointGroup` construct matches the AWS region where your target resources (e.g., ALBs, EC2 instances) are deployed. Remember that the stack's region (defined in `cdk.Environment`) is separate from the endpoint group region.

• TypeError: Expected type 'PortRange', got '<int>'

  cause You attempted to provide an integer directly to the `port_ranges` property of a `ga.Listener`, but it expects a list of `ga.PortRange` objects.
  fix Wrap your port numbers within `ga.PortRange` objects. For example, change `port_ranges=[80]` to `port_ranges=[ga.PortRange(from_port=80, to_port=80)]`.

Warnings

• breaking This library is for AWS CDK v1 (version 1.x.x). AWS CDK v2 has significant breaking changes, including module names (e.g., `aws_cdk.aws_globalaccelerator` vs `aws_cdk.aws_globalaccelerator` in v2 but with different class properties/methods) and construct patterns. Do not mix v1 and v2 libraries.
  Fix: Ensure all CDK libraries in your project are either v1.x.x or v2.x.x. If migrating to v2, consult the official CDK v2 upgrade guide for `aws-globalaccelerator` changes.
• gotcha Global Accelerator endpoint groups require a specified `endpoint_group_region`. While Global Accelerator itself is a global service, its endpoint groups must be associated with a specific AWS region where your application endpoints (e.g., ALBs, EC2 instances) reside.
  Fix: Always specify the `endpoint_group_region` property when creating an `EndpointGroup`. Ensure this region matches the region where the actual endpoints are deployed.
• gotcha Global Accelerator listeners require a list of `PortRange` objects, not just integers or tuples. Forgetting to wrap port numbers in `ga.PortRange()` is a common mistake.
  Fix: When defining `port_ranges` for a `Listener`, always use `[ga.PortRange(from_port=X, to_port=Y)]`.

Install

• pip install aws-cdk-aws-globalaccelerator aws-cdk.core Install library and core CDK
• npm install -g aws-cdk Install AWS CDK CLI (recommended)

Imports

• Accelerator
  wrong:

  from aws_cdk.aws_globalaccelerator import Accelerator

  correct:

  from aws_cdk import aws_globalaccelerator as ga

  While direct import works, aliasing to 'ga' is the community standard for brevity and consistency in CDK v1.
• PortRange

  from aws_cdk import aws_globalaccelerator as ga

• ApplicationLoadBalancerEndpoint
  wrong:

  from aws_cdk.aws_globalaccelerator import ApplicationLoadBalancerEndpoint

  correct:

  from aws_cdk import aws_globalaccelerator_endpoints as ga_endpoints

  Endpoint-specific constructs are often in `aws_globalaccelerator_endpoints` for clarity, not directly in `aws_globalaccelerator`.

Quickstart

This quickstart demonstrates how to create a basic Global Accelerator with a listener and an empty endpoint group. It's runnable and will synthesize a CloudFormation template. To make it functional, you would typically add actual application endpoints (like Application Load Balancers or EC2 instances) to the `endpoint_group`.

import os
from aws_cdk import (
    core as cdk,
    aws_globalaccelerator as ga
)

class GlobalAcceleratorStack(cdk.Stack):
    def __init__(self, scope: cdk.Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Create a Global Accelerator
        accelerator = ga.Accelerator(self, "MyGlobalAccelerator",
            accelerator_name="MyWebAppAccelerator"
        )

        # Add a Listener for HTTP traffic on port 80
        # GA listeners are always TCP or UDP. HTTP/S is handled by the endpoints.
        listener = ga.Listener(self, "HttpListener",
            accelerator=accelerator,
            port_ranges=[ga.PortRange(from_port=80, to_port=80)],
            protocol=ga.ConnectionProtocol.TCP
        )

        # Add an Endpoint Group for a specific region
        # This group is initially empty; you would add actual endpoints to it.
        endpoint_group = ga.EndpointGroup(self, "UsEast1EndpointGroup",
            listener=listener,
            endpoint_group_region="us-east-1" # The region where your application endpoints reside
        )

        # To add actual endpoints (e.g., an Application Load Balancer):
        # from aws_cdk import aws_globalaccelerator_endpoints as ga_endpoints
        # from aws_cdk import aws_elasticloadbalancingv2 as elbv2
        # alb = elbv2.ApplicationLoadBalancer.from_lookup(...)
        # endpoint_group.add_endpoint(ga_endpoints.ApplicationLoadBalancerEndpoint(alb))

app = cdk.App()
GlobalAcceleratorStack(app, "GlobalAcceleratorQuickstartStack",
    env=cdk.Environment(
        account=os.environ.get("CDK_DEFAULT_ACCOUNT"),
        region=os.environ.get("CDK_DEFAULT_REGION", "us-east-1") # GA itself is global, but stack needs a region for deployment
    )
)
app.synth()