Namespace Amazon.CDK.AWS.GlobalAccelerator

AWS::GlobalAccelerator Construct Library

---

AWS CDK v1 has reached End-of-Support on 2023-06-01.
This package is no longer being updated, and users should migrate to AWS CDK v2.

For more information on how to migrate, see the Migrating to AWS CDK v2 guide.

Introduction

AWS Global Accelerator (AGA) is a service that improves the availability and performance of your applications with local or global users.

It intercepts your user's network connection at an edge location close to them, and routes it to one of potentially multiple, redundant backends across the more reliable and less congested AWS global network.

AGA can be used to route traffic to Application Load Balancers, Network Load Balancers, EC2 Instances and Elastic IP Addresses.

For more information, see the AWS Global Accelerator Developer Guide.

Example

Here's an example that sets up a Global Accelerator for two Application Load Balancers in two different AWS Regions:

// Create an Accelerator
var accelerator = new Accelerator(this, "Accelerator");

// Create a Listener
var listener = accelerator.AddListener("Listener", new ListenerOptions {
    PortRanges = new [] { new PortRange { FromPort = 80 }, new PortRange { FromPort = 443 } }
});

// Import the Load Balancers
var nlb1 = NetworkLoadBalancer.FromNetworkLoadBalancerAttributes(this, "NLB1", new NetworkLoadBalancerAttributes {
    LoadBalancerArn = "arn:aws:elasticloadbalancing:us-west-2:111111111111:loadbalancer/app/my-load-balancer1/e16bef66805b"
});
var nlb2 = NetworkLoadBalancer.FromNetworkLoadBalancerAttributes(this, "NLB2", new NetworkLoadBalancerAttributes {
    LoadBalancerArn = "arn:aws:elasticloadbalancing:ap-south-1:111111111111:loadbalancer/app/my-load-balancer2/5513dc2ea8a1"
});

// Add one EndpointGroup for each Region we are targeting
listener.AddEndpointGroup("Group1", new EndpointGroupOptions {
    Endpoints = new [] { new NetworkLoadBalancerEndpoint(nlb1) }
});
listener.AddEndpointGroup("Group2", new EndpointGroupOptions {
    // Imported load balancers automatically calculate their Region from the ARN.
    // If you are load balancing to other resources, you must also pass a `region`
    // parameter here.
    Endpoints = new [] { new NetworkLoadBalancerEndpoint(nlb2) }
});

Concepts

The Accelerator construct defines a Global Accelerator resource.

An Accelerator includes one or more Listeners that accepts inbound connections on one or more ports.

Each Listener has one or more Endpoint Groups, representing multiple geographically distributed copies of your application. There is one Endpoint Group per Region, and user traffic is routed to the closest Region by default.

An Endpoint Group consists of one or more Endpoints, which is where the user traffic coming in on the Listener is ultimately sent. The Endpoint port used is the same as the traffic came in on at the Listener, unless overridden.

Types of Endpoints

There are 4 types of Endpoints, and they can be found in the @aws-cdk/aws-globalaccelerator-endpoints package:

Application Load Balancers

ApplicationLoadBalancer alb;
Listener listener;


listener.AddEndpointGroup("Group", new EndpointGroupOptions {
    Endpoints = new [] {
        new ApplicationLoadBalancerEndpoint(alb, new ApplicationLoadBalancerEndpointOptions {
            Weight = 128,
            PreserveClientIp = true
        }) }
});

Network Load Balancers

NetworkLoadBalancer nlb;
Listener listener;


listener.AddEndpointGroup("Group", new EndpointGroupOptions {
    Endpoints = new [] {
        new NetworkLoadBalancerEndpoint(nlb, new NetworkLoadBalancerEndpointProps {
            Weight = 128
        }) }
});

EC2 Instances

Listener listener;
Instance instance;


listener.AddEndpointGroup("Group", new EndpointGroupOptions {
    Endpoints = new [] {
        new InstanceEndpoint(instance, new InstanceEndpointProps {
            Weight = 128,
            PreserveClientIp = true
        }) }
});

Elastic IP Addresses

Listener listener;
CfnEIP eip;


listener.AddEndpointGroup("Group", new EndpointGroupOptions {
    Endpoints = new [] {
        new CfnEipEndpoint(eip, new CfnEipEndpointProps {
            Weight = 128
        }) }
});

Client IP Address Preservation and Security Groups

When using the preserveClientIp feature, AGA creates Elastic Network Interfaces (ENIs) in your AWS account, that are associated with a Security Group AGA creates for you. You can use the security group created by AGA as a source group in other security groups (such as those for EC2 instances or Elastic Load Balancers), if you want to restrict incoming traffic to the AGA security group rules.

AGA creates a specific security group called GlobalAccelerator for each VPC it has an ENI in (this behavior can not be changed). CloudFormation doesn't support referencing the security group created by AGA, but this construct library comes with a custom resource that enables you to reference the AGA security group.

Call endpointGroup.connectionsPeer() to obtain a reference to the Security Group which you can use in connection rules. You must pass a reference to the VPC in whose context the security group will be looked up. Example:

Listener listener;

// Non-open ALB
ApplicationLoadBalancer alb;

// Remember that there is only one AGA security group per VPC.
Vpc vpc;


var endpointGroup = listener.AddEndpointGroup("Group", new EndpointGroupOptions {
    Endpoints = new [] {
        new ApplicationLoadBalancerEndpoint(alb, new ApplicationLoadBalancerEndpointOptions {
            PreserveClientIp = true
        }) }
});
var agaSg = endpointGroup.ConnectionsPeer("GlobalAcceleratorSG", vpc);

// Allow connections from the AGA to the ALB
alb.Connections.AllowFrom(agaSg, Port.Tcp(443));

Classes

Accelerator	The Accelerator construct.
AcceleratorAttributes	Attributes required to import an existing accelerator to the stack.
AcceleratorProps	Construct properties of the Accelerator.
CfnAccelerator	A CloudFormation `AWS::GlobalAccelerator::Accelerator`.
CfnAcceleratorProps	Properties for defining a `CfnAccelerator`.
CfnEndpointGroup	A CloudFormation `AWS::GlobalAccelerator::EndpointGroup`.
CfnEndpointGroup.EndpointConfigurationProperty	A complex type for endpoints.
CfnEndpointGroup.PortOverrideProperty	Override specific listener ports used to route traffic to endpoints that are part of an endpoint group.
CfnEndpointGroupProps	Properties for defining a `CfnEndpointGroup`.
CfnListener	A CloudFormation `AWS::GlobalAccelerator::Listener`.
CfnListener.PortRangeProperty	A complex type for a range of ports for a listener.
CfnListenerProps	Properties for defining a `CfnListener`.
ClientAffinity	Client affinity gives you control over whether to always route each client to the same specific endpoint.
ConnectionProtocol	The protocol for the connections from clients to the accelerator.
EndpointGroup	EndpointGroup construct.
EndpointGroupOptions	Basic options for creating a new EndpointGroup.
EndpointGroupProps	Property of the EndpointGroup.
HealthCheckProtocol	The protocol for the connections from clients to the accelerator.
Listener	The construct for the Listener.
ListenerOptions	Construct options for Listener.
ListenerProps	Construct properties for Listener.
PortOverride	Override specific listener ports used to route traffic to endpoints that are part of an endpoint group.
PortRange	The list of port ranges for the connections from clients to the accelerator.
RawEndpoint	Untyped endpoint implementation.
RawEndpointProps	Properties for RawEndpoint.

Interfaces

CfnEndpointGroup.IEndpointConfigurationProperty	A complex type for endpoints.
CfnEndpointGroup.IPortOverrideProperty	Override specific listener ports used to route traffic to endpoints that are part of an endpoint group.
CfnListener.IPortRangeProperty	A complex type for a range of ports for a listener.
IAccelerator	The interface of the Accelerator.
IAcceleratorAttributes	Attributes required to import an existing accelerator to the stack.
IAcceleratorProps	Construct properties of the Accelerator.
ICfnAcceleratorProps	Properties for defining a `CfnAccelerator`.
ICfnEndpointGroupProps	Properties for defining a `CfnEndpointGroup`.
ICfnListenerProps	Properties for defining a `CfnListener`.
IEndpoint	An endpoint for the endpoint group.
IEndpointGroup	The interface of the EndpointGroup.
IEndpointGroupOptions	Basic options for creating a new EndpointGroup.
IEndpointGroupProps	Property of the EndpointGroup.
IListener	Interface of the Listener.
IListenerOptions	Construct options for Listener.
IListenerProps	Construct properties for Listener.
IPortOverride	Override specific listener ports used to route traffic to endpoints that are part of an endpoint group.
IPortRange	The list of port ranges for the connections from clients to the accelerator.
IRawEndpointProps	Properties for RawEndpoint.