{"id":9518,"library":"aws-cdk-aws-globalaccelerator","title":"AWS CDK Global Accelerator","description":"The AWS Cloud Development Kit (CDK) Construct Library for AWS Global Accelerator. This library allows developers to define and provision Global Accelerator resources using familiar programming languages. It is part of the AWS CDK v1 ecosystem, with version 1.204.0 being released as part of the broader CDK v1 maintenance cycle. AWS CDK has a regular release cadence, often weekly for minor updates and bug fixes.","status":"active","version":"1.204.0","language":"en","source_language":"en","source_url":"https://github.com/aws/aws-cdk.git","tags":["aws","cdk","cloud","globalaccelerator","networking"],"install":[{"cmd":"pip install aws-cdk-aws-globalaccelerator aws-cdk.core","lang":"bash","label":"Install library and core CDK"},{"cmd":"npm install -g aws-cdk","lang":"bash","label":"Install AWS CDK CLI (recommended)"}],"dependencies":[{"reason":"This package is a CDK construct library and depends on aws-cdk.core for foundational CDK constructs and functionalities. This version specifically requires `aws-cdk.core (>=1.204.0,<2.0.0)`.","package":"aws-cdk.core","optional":false}],"imports":[{"note":"While direct import works, aliasing to 'ga' is the community standard for brevity and consistency in CDK v1.","wrong":"from aws_cdk.aws_globalaccelerator import Accelerator","symbol":"Accelerator","correct":"from aws_cdk import aws_globalaccelerator as ga"},{"symbol":"PortRange","correct":"from aws_cdk import aws_globalaccelerator as ga"},{"note":"Endpoint-specific constructs are often in `aws_globalaccelerator_endpoints` for clarity, not directly in `aws_globalaccelerator`.","wrong":"from aws_cdk.aws_globalaccelerator import ApplicationLoadBalancerEndpoint","symbol":"ApplicationLoadBalancerEndpoint","correct":"from aws_cdk import aws_globalaccelerator_endpoints as ga_endpoints"}],"quickstart":{"code":"import os\nfrom aws_cdk import (\n    core as cdk,\n    aws_globalaccelerator as ga\n)\n\nclass GlobalAcceleratorStack(cdk.Stack):\n    def __init__(self, scope: cdk.Construct, construct_id: str, **kwargs) -> None:\n        super().__init__(scope, construct_id, **kwargs)\n\n        # Create a Global Accelerator\n        accelerator = ga.Accelerator(self, \"MyGlobalAccelerator\",\n            accelerator_name=\"MyWebAppAccelerator\"\n        )\n\n        # Add a Listener for HTTP traffic on port 80\n        # GA listeners are always TCP or UDP. HTTP/S is handled by the endpoints.\n        listener = ga.Listener(self, \"HttpListener\",\n            accelerator=accelerator,\n            port_ranges=[ga.PortRange(from_port=80, to_port=80)],\n            protocol=ga.ConnectionProtocol.TCP\n        )\n\n        # Add an Endpoint Group for a specific region\n        # This group is initially empty; you would add actual endpoints to it.\n        endpoint_group = ga.EndpointGroup(self, \"UsEast1EndpointGroup\",\n            listener=listener,\n            endpoint_group_region=\"us-east-1\" # The region where your application endpoints reside\n        )\n\n        # To add actual endpoints (e.g., an Application Load Balancer):\n        # from aws_cdk import aws_globalaccelerator_endpoints as ga_endpoints\n        # from aws_cdk import aws_elasticloadbalancingv2 as elbv2\n        # alb = elbv2.ApplicationLoadBalancer.from_lookup(...)\n        # endpoint_group.add_endpoint(ga_endpoints.ApplicationLoadBalancerEndpoint(alb))\n\napp = cdk.App()\nGlobalAcceleratorStack(app, \"GlobalAcceleratorQuickstartStack\",\n    env=cdk.Environment(\n        account=os.environ.get(\"CDK_DEFAULT_ACCOUNT\"),\n        region=os.environ.get(\"CDK_DEFAULT_REGION\", \"us-east-1\") # GA itself is global, but stack needs a region for deployment\n    )\n)\napp.synth()","lang":"python","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"CDK v1.x.x when attempting to use v2 constructs/patterns"},{"fix":"Always specify the `endpoint_group_region` property when creating an `EndpointGroup`. Ensure this region matches the region where the actual endpoints are deployed.","message":"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.","severity":"gotcha","affected_versions":"All versions of `aws-cdk-aws-globalaccelerator`"},{"fix":"When defining `port_ranges` for a `Listener`, always use `[ga.PortRange(from_port=X, to_port=Y)]`.","message":"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.","severity":"gotcha","affected_versions":"All versions of `aws-cdk-aws-globalaccelerator`"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","cause":"The `aws-cdk-aws-globalaccelerator` Python package has not been installed in your environment, or your Python interpreter path is incorrect.","error":"ModuleNotFoundError: No module named 'aws_cdk.aws_globalaccelerator'"},{"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.","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.","error":"jsii.errors.JSIIError: The specified Endpoint Group region us-west-2 does not match the listener's region for accelerator ..."},{"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)]`.","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.","error":"TypeError: Expected type 'PortRange', got '<int>'"}]}