aws-cdk-lib.aws_globalaccelerator

AWS::GlobalAccelerator Construct Library

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
const accelerator = new globalaccelerator.Accelerator(this, 'Accelerator');

// Create a Listener
const listener = accelerator.addListener('Listener', {
  portRanges: [
    { fromPort: 80 },
    { fromPort: 443 },
  ],
});

// Import the Load Balancers
const nlb1 = elbv2.NetworkLoadBalancer.fromNetworkLoadBalancerAttributes(this, 'NLB1', {
  loadBalancerArn: 'arn:aws:elasticloadbalancing:us-west-2:111111111111:loadbalancer/app/my-load-balancer1/e16bef66805b',
});
const nlb2 = elbv2.NetworkLoadBalancer.fromNetworkLoadBalancerAttributes(this, 'NLB2', {
  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', {
  endpoints: [new ga_endpoints.NetworkLoadBalancerEndpoint(nlb1)],
});
listener.addEndpointGroup('Group2', {
  // 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 ga_endpoints.NetworkLoadBalancerEndpoint(nlb2)],
});

# Create an Accelerator
accelerator = globalaccelerator.Accelerator(self, "Accelerator")

# Create a Listener
listener = accelerator.add_listener("Listener",
    port_ranges=[globalaccelerator.PortRange(from_port=80), globalaccelerator.PortRange(from_port=443)
    ]
)

# Import the Load Balancers
nlb1 = elbv2.NetworkLoadBalancer.from_network_load_balancer_attributes(self, "NLB1",
    load_balancer_arn="arn:aws:elasticloadbalancing:us-west-2:111111111111:loadbalancer/app/my-load-balancer1/e16bef66805b"
)
nlb2 = elbv2.NetworkLoadBalancer.from_network_load_balancer_attributes(self, "NLB2",
    load_balancer_arn="arn:aws:elasticloadbalancing:ap-south-1:111111111111:loadbalancer/app/my-load-balancer2/5513dc2ea8a1"
)

# Add one EndpointGroup for each Region we are targeting
listener.add_endpoint_group("Group1",
    endpoints=[ga_endpoints.NetworkLoadBalancerEndpoint(nlb1)]
)
listener.add_endpoint_group("Group2",
    # 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=[ga_endpoints.NetworkLoadBalancerEndpoint(nlb2)]
)

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

// Create a Listener
Listener listener = accelerator.addListener("Listener", ListenerOptions.builder()
        .portRanges(List.of(PortRange.builder().fromPort(80).build(), PortRange.builder().fromPort(443).build()))
        .build());

// Import the Load Balancers
INetworkLoadBalancer nlb1 = NetworkLoadBalancer.fromNetworkLoadBalancerAttributes(this, "NLB1", NetworkLoadBalancerAttributes.builder()
        .loadBalancerArn("arn:aws:elasticloadbalancing:us-west-2:111111111111:loadbalancer/app/my-load-balancer1/e16bef66805b")
        .build());
INetworkLoadBalancer nlb2 = NetworkLoadBalancer.fromNetworkLoadBalancerAttributes(this, "NLB2", NetworkLoadBalancerAttributes.builder()
        .loadBalancerArn("arn:aws:elasticloadbalancing:ap-south-1:111111111111:loadbalancer/app/my-load-balancer2/5513dc2ea8a1")
        .build());

// Add one EndpointGroup for each Region we are targeting
listener.addEndpointGroup("Group1", EndpointGroupOptions.builder()
        .endpoints(List.of(new NetworkLoadBalancerEndpoint(nlb1)))
        .build());
listener.addEndpointGroup("Group2", EndpointGroupOptions.builder()
        // 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(List.of(new NetworkLoadBalancerEndpoint(nlb2)))
        .build());

// 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) }
});

// Create an Accelerator
accelerator := globalaccelerator.NewAccelerator(this, jsii.String("Accelerator"))

// Create a Listener
listener := accelerator.AddListener(jsii.String("Listener"), &ListenerOptions{
	PortRanges: []PortRange{
		&PortRange{
			FromPort: jsii.Number(80),
		},
		&PortRange{
			FromPort: jsii.Number(443),
		},
	},
})

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

// Add one EndpointGroup for each Region we are targeting
listener.AddEndpointGroup(jsii.String("Group1"), &EndpointGroupOptions{
	Endpoints: []IEndpoint{
		ga_endpoints.NewNetworkLoadBalancerEndpoint(nlb1),
	},
})
listener.AddEndpointGroup(jsii.String("Group2"), &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: []IEndpoint{
		ga_endpoints.NewNetworkLoadBalancerEndpoint(nlb2),
	},
})

Create an Accelerator with IP addresses and IP address type

const accelerator = new globalaccelerator.Accelerator(this, 'Accelerator', {
  ipAddresses: [
    '1.1.1.1',
    '2.2.2.2',
  ],
  ipAddressType: globalaccelerator.IpAddressType.IPV4,
});

accelerator = globalaccelerator.Accelerator(self, "Accelerator",
    ip_addresses=["1.1.1.1", "2.2.2.2"
    ],
    ip_address_type=globalaccelerator.IpAddressType.IPV4
)

Accelerator accelerator = Accelerator.Builder.create(this, "Accelerator")
        .ipAddresses(List.of("1.1.1.1", "2.2.2.2"))
        .ipAddressType(IpAddressType.IPV4)
        .build();

var accelerator = new Accelerator(this, "Accelerator", new AcceleratorProps {
    IpAddresses = new [] { "1.1.1.1", "2.2.2.2" },
    IpAddressType = IpAddressType.IPV4
});

accelerator := globalaccelerator.NewAccelerator(this, jsii.String("Accelerator"), &AcceleratorProps{
	IpAddresses: []*string{
		jsii.String("1.1.1.1"),
		jsii.String("2.2.2.2"),
	},
	IpAddressType: globalaccelerator.IpAddressType_IPV4,
})

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-lib/aws-globalaccelerator-endpoints package:

• Application Load Balancers
• Network Load Balancers
• EC2 Instances
• Elastic IP Addresses

Application Load Balancers

declare const alb: elbv2.ApplicationLoadBalancer;
declare const listener: globalaccelerator.Listener;

listener.addEndpointGroup('Group', {
  endpoints: [
    new ga_endpoints.ApplicationLoadBalancerEndpoint(alb, {
      weight: 128,
      preserveClientIp: true,
    }),
  ],
});

# alb: elbv2.ApplicationLoadBalancer
# listener: globalaccelerator.Listener


listener.add_endpoint_group("Group",
    endpoints=[
        ga_endpoints.ApplicationLoadBalancerEndpoint(alb,
            weight=128,
            preserve_client_ip=True
        )
    ]
)

ApplicationLoadBalancer alb;
Listener listener;


listener.addEndpointGroup("Group", EndpointGroupOptions.builder()
        .endpoints(List.of(
            ApplicationLoadBalancerEndpoint.Builder.create(alb)
                    .weight(128)
                    .preserveClientIp(true)
                    .build()))
        .build());

ApplicationLoadBalancer alb;
Listener listener;


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

var alb ApplicationLoadBalancer
var listener Listener


listener.AddEndpointGroup(jsii.String("Group"), &EndpointGroupOptions{
	Endpoints: []IEndpoint{
		ga_endpoints.NewApplicationLoadBalancerEndpoint(alb, &ApplicationLoadBalancerEndpointOptions{
			Weight: jsii.Number(128),
			PreserveClientIp: jsii.Boolean(true),
		}),
	},
})

Network Load Balancers

declare const nlb: elbv2.NetworkLoadBalancer;
declare const listener: globalaccelerator.Listener;

listener.addEndpointGroup('Group', {
  endpoints: [
    new ga_endpoints.NetworkLoadBalancerEndpoint(nlb, {
      weight: 128,
      preserveClientIp: true,
    }),
  ],
});

# nlb: elbv2.NetworkLoadBalancer
# listener: globalaccelerator.Listener


listener.add_endpoint_group("Group",
    endpoints=[
        ga_endpoints.NetworkLoadBalancerEndpoint(nlb,
            weight=128,
            preserve_client_ip=True
        )
    ]
)

NetworkLoadBalancer nlb;
Listener listener;


listener.addEndpointGroup("Group", EndpointGroupOptions.builder()
        .endpoints(List.of(
            NetworkLoadBalancerEndpoint.Builder.create(nlb)
                    .weight(128)
                    .preserveClientIp(true)
                    .build()))
        .build());

NetworkLoadBalancer nlb;
Listener listener;


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

var nlb NetworkLoadBalancer
var listener Listener


listener.AddEndpointGroup(jsii.String("Group"), &EndpointGroupOptions{
	Endpoints: []IEndpoint{
		ga_endpoints.NewNetworkLoadBalancerEndpoint(nlb, &NetworkLoadBalancerEndpointProps{
			Weight: jsii.Number(128),
			PreserveClientIp: jsii.Boolean(true),
		}),
	},
})

EC2 Instances

declare const listener: globalaccelerator.Listener;
declare const instance: ec2.Instance;

listener.addEndpointGroup('Group', {
  endpoints: [
    new ga_endpoints.InstanceEndpoint(instance, {
      weight: 128,
      preserveClientIp: true,
    }),
  ],
});

# listener: globalaccelerator.Listener
# instance: ec2.Instance


listener.add_endpoint_group("Group",
    endpoints=[
        ga_endpoints.InstanceEndpoint(instance,
            weight=128,
            preserve_client_ip=True
        )
    ]
)

Listener listener;
Instance instance;


listener.addEndpointGroup("Group", EndpointGroupOptions.builder()
        .endpoints(List.of(
            InstanceEndpoint.Builder.create(instance)
                    .weight(128)
                    .preserveClientIp(true)
                    .build()))
        .build());

Listener listener;
Instance instance;


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

var listener Listener
var instance Instance


listener.AddEndpointGroup(jsii.String("Group"), &EndpointGroupOptions{
	Endpoints: []IEndpoint{
		ga_endpoints.NewInstanceEndpoint(instance, &InstanceEndpointProps{
			Weight: jsii.Number(128),
			PreserveClientIp: jsii.Boolean(true),
		}),
	},
})

Elastic IP Addresses

declare const listener: globalaccelerator.Listener;
declare const eip: ec2.CfnEIP;

listener.addEndpointGroup('Group', {
  endpoints: [
    new ga_endpoints.CfnEipEndpoint(eip, {
      weight: 128,
    }),
  ],
});

# listener: globalaccelerator.Listener
# eip: ec2.CfnEIP


listener.add_endpoint_group("Group",
    endpoints=[
        ga_endpoints.CfnEipEndpoint(eip,
            weight=128
        )
    ]
)

Listener listener;
CfnEIP eip;


listener.addEndpointGroup("Group", EndpointGroupOptions.builder()
        .endpoints(List.of(
            CfnEipEndpoint.Builder.create(eip)
                    .weight(128)
                    .build()))
        .build());

Listener listener;
CfnEIP eip;


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

var listener Listener
var eip CfnEIP


listener.AddEndpointGroup(jsii.String("Group"), &EndpointGroupOptions{
	Endpoints: []IEndpoint{
		ga_endpoints.NewCfnEipEndpoint(eip, &CfnEipEndpointProps{
			Weight: jsii.Number(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:

declare const listener: globalaccelerator.Listener;

// Non-open ALB
declare const alb: elbv2.ApplicationLoadBalancer;

const endpointGroup = listener.addEndpointGroup('Group', {
  endpoints: [
    new ga_endpoints.ApplicationLoadBalancerEndpoint(alb, {
      preserveClientIp: true,
    }),
  ],
});

// Remember that there is only one AGA security group per VPC.
declare const vpc: ec2.Vpc;
const agaSg = endpointGroup.connectionsPeer('GlobalAcceleratorSG', vpc);

// Allow connections from the AGA to the ALB
alb.connections.allowFrom(agaSg, ec2.Port.tcp(443));

# listener: globalaccelerator.Listener

# Non-open ALB
# alb: elbv2.ApplicationLoadBalancer

# Remember that there is only one AGA security group per VPC.
# vpc: ec2.Vpc


endpoint_group = listener.add_endpoint_group("Group",
    endpoints=[
        ga_endpoints.ApplicationLoadBalancerEndpoint(alb,
            preserve_client_ip=True
        )
    ]
)
aga_sg = endpoint_group.connections_peer("GlobalAcceleratorSG", vpc)

# Allow connections from the AGA to the ALB
alb.connections.allow_from(aga_sg, ec2.Port.tcp(443))

Listener listener;

// Non-open ALB
ApplicationLoadBalancer alb;

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


EndpointGroup endpointGroup = listener.addEndpointGroup("Group", EndpointGroupOptions.builder()
        .endpoints(List.of(
            ApplicationLoadBalancerEndpoint.Builder.create(alb)
                    .preserveClientIp(true)
                    .build()))
        .build());
IPeer agaSg = endpointGroup.connectionsPeer("GlobalAcceleratorSG", vpc);

// Allow connections from the AGA to the ALB
alb.connections.allowFrom(agaSg, Port.tcp(443));

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

var listener Listener

// Non-open ALB
var alb ApplicationLoadBalancer

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


endpointGroup := listener.AddEndpointGroup(jsii.String("Group"), &EndpointGroupOptions{
	Endpoints: []IEndpoint{
		ga_endpoints.NewApplicationLoadBalancerEndpoint(alb, &ApplicationLoadBalancerEndpointOptions{
			PreserveClientIp: jsii.Boolean(true),
		}),
	},
})
agaSg := endpointGroup.ConnectionsPeer(jsii.String("GlobalAcceleratorSG"), vpc)

// Allow connections from the AGA to the ALB
alb.Connections.AllowFrom(agaSg, ec2.Port_Tcp(jsii.Number(443)))

Types

Name	Kind	Summary
Accelerator	Construct (L2)	The Accelerator construct.
EndpointGroup	Construct (L2)	EndpointGroup construct.
Listener	Construct (L2)	The construct for the Listener.
CfnAccelerator	Construct (L1)	The AWS::GlobalAccelerator::Accelerator resource is a Global Accelerator resource type that contains information about how you create an accelerator.
CfnCrossAccountAttachment	Construct (L1)	Create a cross-account attachment in AWS Global Accelerator .
CfnEndpointGroup	Construct (L1)	The AWS::GlobalAccelerator::EndpointGroup resource is a Global Accelerator resource type that contains information about how you create an endpoint group for the specified listener.
CfnListener	Construct (L1)	The AWS::GlobalAccelerator::Listener resource is a Global Accelerator resource type that contains information about how you create a listener to process inbound connections from clients to an accelerator.
AcceleratorAttributes	Struct	Attributes required to import an existing accelerator to the stack.
AcceleratorProps	Struct	Construct properties of the Accelerator.
CfnAcceleratorProps	Struct	Properties for defining a CfnAccelerator.
CfnCrossAccountAttachment.ResourceProperty	Struct	A resource is one of the following: the ARN for an AWS resource that is supported by AWS Global Accelerator to be added as an endpoint, or a CIDR range that specifies a bring your own IP (BYOIP) address pool.
CfnCrossAccountAttachmentProps	Struct	Properties for defining a CfnCrossAccountAttachment.
CfnEndpointGroup.EndpointConfigurationProperty	Struct	A complex type for endpoints.
CfnEndpointGroup.PortOverrideProperty	Struct	Override specific listener ports used to route traffic to endpoints that are part of an endpoint group.
CfnEndpointGroupProps	Struct	Properties for defining a CfnEndpointGroup.
CfnListener.PortRangeProperty	Struct	A complex type for a range of ports for a listener.
CfnListenerProps	Struct	Properties for defining a CfnListener.
ClientAffinity	Enum	Client affinity gives you control over whether to always route each client to the same specific endpoint.
ConnectionProtocol	Enum	The protocol for the connections from clients to the accelerator.
EndpointGroupOptions	Struct	Basic options for creating a new EndpointGroup.
EndpointGroupProps	Struct	Property of the EndpointGroup.
HealthCheckProtocol	Enum	The protocol for the connections from clients to the accelerator.
IAccelerator	Interface	The interface of the Accelerator.
IEndpoint	Interface	An endpoint for the endpoint group.
IEndpointGroup	Interface	The interface of the EndpointGroup.
IListener	Interface	Interface of the Listener.
IpAddressType	Enum	The IP address type that an accelerator supports.
ListenerOptions	Struct	Construct options for Listener.
ListenerProps	Struct	Construct properties for Listener.
PortOverride	Struct	Override specific listener ports used to route traffic to endpoints that are part of an endpoint group.
PortRange	Struct	The list of port ranges for the connections from clients to the accelerator.
RawEndpoint	Class	Untyped endpoint implementation.
RawEndpointProps	Struct	Properties for RawEndpoint.