AWS Global Accelerator

(1)

AWS Global Accelerator

API Reference

API Version 2018-08-08

(2)

AWS Global Accelerator: API Reference

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

Welcome

This is the AWS Global Accelerator API Reference. This guide is for developers who need detailed information about AWS Global Accelerator API actions, data types, and errors. For more information about Global Accelerator features, see the AWS Global Accelerator Developer Guide.

AWS Global Accelerator is a service in which you create accelerators to improve the performance of your applications for local and global users. Depending on the type of accelerator you choose, you can gain additional beneﬁts.

• By using a standard accelerator, you can improve availability of your internet applications that are used by a global audience. With a standard accelerator, Global Accelerator directs traﬃc to optimal endpoints over the AWS global network.

• For other scenarios, you might choose a custom routing accelerator. With a custom routing accelerator, you can use application logic to directly map one or more users to a speciﬁc endpoint among many endpoints.

Important

Global Accelerator is a global service that supports endpoints in multiple AWS Regions but you must specify the US West (Oregon) Region to create or update accelerators.

By default, Global Accelerator provides you with two static IP addresses that you associate with your accelerator. With a standard accelerator, instead of using the IP addresses that Global Accelerator provides, you can configure these entry points to be IPv4 addresses from your own IP address ranges that you bring to Global Accelerator. The static IP addresses are anycast from the AWS edge network. For a standard accelerator, they distribute incoming application traffic across multiple endpoint resources in multiple AWS Regions , which increases the availability of your applications. Endpoints for standard accelerators can be Network Load Balancers, Application Load Balancers, Amazon EC2 instances, or Elastic IP addresses that are located in one AWS Region or multiple AWS Regions. For custom routing accelerators, you map traffic that arrives to the static IP addresses to specific Amazon EC2 servers in endpoints that are virtual private cloud (VPC) subnets.

Important

The static IP addresses remain assigned to your accelerator for as long as it exists, even if you disable the accelerator and it no longer accepts or routes traﬃc. However, when you delete an accelerator, you lose the static IP addresses that are assigned to it, so you can no longer route traﬃc by using them. You can use IAM policies like tag-based permissions with Global Accelerator to limit the users who have permissions to delete an accelerator. For more information, see Tag-based policies.

For standard accelerators, Global Accelerator uses the AWS global network to route traffic to the optimal regional endpoint based on health, client location, and policies that you configure. The service reacts instantly to changes in health or configuration to ensure that internet traffic from clients is always directed to healthy endpoints.

AWS Global Accelerator includes the following components:

Static IP addresses

Global Accelerator provides you with a set of two static IP addresses that are anycast from the AWS edge network. If you bring your own IP address range to AWS (BYOIP) to use with a standard accelerator, you can instead assign IP addresses from your own pool to use with your accelerator. For more information, see Bring your own IP addresses (BYOIP) in AWS Global Accelerator.

API Version 2018-08-08 1

(12)

The IP addresses serve as single ﬁxed entry points for your clients. If you already have Elastic Load Balancing load balancers, Amazon EC2 instances, or Elastic IP address resources set up for your applications, you can easily add those to a standard accelerator in Global Accelerator. This allows Global Accelerator to use static IP addresses to access the resources.

The static IP addresses remain assigned to your accelerator for as long as it exists, even if you disable the accelerator and it no longer accepts or routes traﬃc. However, when you delete an accelerator, you lose the static IP addresses that are assigned to it, so you can no longer route traﬃc by using them. You can use IAM policies like tag-based permissions with Global Accelerator to delete an accelerator. For more information, see Tag-based policies.

Accelerator

An accelerator directs traﬃc to endpoints over the AWS global network to improve the performance of your internet applications. Each accelerator includes one or more listeners.

There are two types of accelerators:

• A standard accelerator directs traﬃc to the optimal AWS endpoint based on several factors, including the user’s location, the health of the endpoint, and the endpoint weights that you conﬁgure. This improves the availability and performance of your applications. Endpoints can be Network Load Balancers, Application Load Balancers, Amazon EC2 instances, or Elastic IP addresses.

• A custom routing accelerator directs traffic to one of possibly thousands of Amazon EC2 instances running in a single or multiple virtual private clouds (VPCs). With custom routing, listener ports are mapped to statically associate port ranges with VPC subnets, which allows Global Accelerator to determine an EC2 instance IP address at the time of connection. By default, all port mapping destinations in a VPC subnet can't receive traffic. You can choose to configure all destinations in the subnet to receive traffic, or to specify individual port mappings that can receive traffic.

For more information, see Types of accelerators.

DNS name

Global Accelerator assigns each accelerator a default Domain Name System (DNS) name, similar to a1234567890abcdef.awsglobalaccelerator.com, that points to the static IP addresses that Global Accelerator assigns to you or that you choose from your own IP address range. Depending on the use case, you can use your accelerator's static IP addresses or DNS name to route traﬃc to your accelerator, or set up DNS records to route traﬃc using your own custom domain name.

Network zone

A network zone services the static IP addresses for your accelerator from a unique IP subnet.

Similar to an AWS Availability Zone, a network zone is an isolated unit with its own set of physical infrastructure. When you conﬁgure an accelerator, by default, Global Accelerator allocates two IPv4 addresses for it. If one IP address from a network zone becomes unavailable due to IP address blocking by certain client networks, or network disruptions, then client applications can retry on the healthy static IP address from the other isolated network zone.

Listener

A listener processes inbound connections from clients to Global Accelerator, based on the port (or port range) and protocol (or protocols) that you configure. A listener can be configured for TCP, UDP, or both TCP and UDP protocols. Each listener has one or more endpoint groups associated with it, and traffic is forwarded to endpoints in one of the groups. You associate endpoint groups with listeners by specifying the Regions that you want to distribute traffic to. With a standard accelerator, traffic is distributed to optimal endpoints within the endpoint groups associated with a listener.

Endpoint group

Each endpoint group is associated with a specific AWS Region. Endpoint groups include one or more endpoints in the Region. With a standard accelerator, you can increase or reduce the percentage of traffic that would be otherwise directed to an endpoint group by adjusting a setting called a traffic

(13)

dial. The traﬃc dial lets you easily do performance testing or blue/green deployment testing, for example, for new releases across diﬀerent AWS Regions .

Endpoint

An endpoint is a resource that Global Accelerator directs traﬃc to.

Endpoints for standard accelerators can be Network Load Balancers, Application Load Balancers, Amazon EC2 instances, or Elastic IP addresses. An Application Load Balancer endpoint can be internet-facing or internal. Traﬃc for standard accelerators is routed to endpoints based on the health of the endpoint along with conﬁguration options that you choose, such as endpoint weights.

For each endpoint, you can conﬁgure weights, which are numbers that you can use to specify the proportion of traﬃc to route to each one. This can be useful, for example, to do performance testing within a Region.

Endpoints for custom routing accelerators are virtual private cloud (VPC) subnets with one or many EC2 instances.

This document was last published on March 6, 2022.

(14)

Actions

The following actions are supported:

• AddCustomRoutingEndpoints (p. 6)

• AdvertiseByoipCidr (p. 9)

• AllowCustomRoutingTraﬃc (p. 12)

• CreateAccelerator (p. 15)

• CreateCustomRoutingAccelerator (p. 19)

• CreateCustomRoutingEndpointGroup (p. 23)

• CreateCustomRoutingListener (p. 27)

• CreateEndpointGroup (p. 30)

• CreateListener (p. 36)

• DeleteAccelerator (p. 40)

• DeleteCustomRoutingAccelerator (p. 42)

• DeleteCustomRoutingEndpointGroup (p. 44)

• DeleteCustomRoutingListener (p. 46)

• DeleteEndpointGroup (p. 48)

• DeleteListener (p. 50)

• DenyCustomRoutingTraﬃc (p. 52)

• DeprovisionByoipCidr (p. 55)

• DescribeAccelerator (p. 58)

• DescribeAcceleratorAttributes (p. 61)

• DescribeCustomRoutingAccelerator (p. 63)

• DescribeCustomRoutingAcceleratorAttributes (p. 66)

• DescribeCustomRoutingEndpointGroup (p. 68)

• DescribeCustomRoutingListener (p. 71)

• DescribeEndpointGroup (p. 73)

• DescribeListener (p. 76)

• ListAccelerators (p. 79)

• ListByoipCidrs (p. 82)

• ListCustomRoutingAccelerators (p. 86)

• ListCustomRoutingEndpointGroups (p. 90)

• ListCustomRoutingListeners (p. 93)

• ListCustomRoutingPortMappings (p. 96)

• ListCustomRoutingPortMappingsByDestination (p. 99)

• ListEndpointGroups (p. 103)

• ListListeners (p. 107)

• ListTagsForResource (p. 110)

• ProvisionByoipCidr (p. 113)

• RemoveCustomRoutingEndpoints (p. 116)

• TagResource (p. 118)

• UntagResource (p. 120)

• UpdateAccelerator (p. 122)

(15)

• UpdateAcceleratorAttributes (p. 125)

• UpdateCustomRoutingAccelerator (p. 128)

• UpdateCustomRoutingAcceleratorAttributes (p. 131)

• UpdateCustomRoutingListener (p. 134)

• UpdateEndpointGroup (p. 137)

• UpdateListener (p. 142)

• WithdrawByoipCidr (p. 146)

(16)

AddCustomRoutingEndpoints

Associate a virtual private cloud (VPC) subnet endpoint with your custom routing accelerator.

The listener port range must be large enough to support the number of IP addresses that can be speciﬁed in your subnet. The number of ports required is: subnet size times the number of ports per destination EC2 instances. For example, a subnet deﬁned as /24 requires a listener port range of at least 255 ports.

Note: You must have enough remaining listener ports available to map to the subnet ports, or the call will fail with a LimitExceededException.

By default, all destinations in a subnet in a custom routing accelerator cannot receive traffic. To enable all destinations to receive traffic, or to specify individual port mappings that can receive traffic, see the AllowCustomRoutingTraffic operation.

Request Syntax

{ "EndpointConfigurations": [ {

"EndpointId": "string"

} ],

"EndpointGroupArn": "string"

}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters (p. 184).

The request accepts the following data in JSON format.

EndpointConﬁgurations (p. 6)

The list of endpoint objects to add to a custom routing accelerator.

Type: Array of CustomRoutingEndpointConﬁguration (p. 162) objects Array Members: Minimum number of 1 item. Maximum number of 20 items.

Required: Yes EndpointGroupArn (p. 6)

The Amazon Resource Name (ARN) of the endpoint group for the custom routing endpoint.

Type: String

Length Constraints: Maximum length of 255.

Required: Yes

Response Syntax

{

(17)

"EndpointDescriptions": [ {

} ],

"EndpointGroupArn": "string"

}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

EndpointDescriptions (p. 6)

The endpoint objects added to the custom routing accelerator.

Type: Array of CustomRoutingEndpointDescription (p. 163) objects EndpointGroupArn (p. 6)

The Amazon Resource Name (ARN) of the endpoint group for the custom routing endpoint.

Type: String

Errors

For information about the errors that are common to all actions, see Common Errors (p. 186).

AccessDeniedException

You don't have access permission.

HTTP Status Code: 400 ConﬂictException

You can't use both of those options.

HTTP Status Code: 400 EndpointAlreadyExistsException

The endpoint that you speciﬁed doesn't exist.

HTTP Status Code: 400

EndpointGroupNotFoundException

The endpoint group that you speciﬁed doesn't exist.

HTTP Status Code: 400 InternalServiceErrorException

There was an internal error for AWS Global Accelerator.

(18)

AdvertiseByoipCidr

Advertises an IPv4 address range that is provisioned for use with your AWS resources through bring your own IP addresses (BYOIP). It can take a few minutes before traﬃc to the speciﬁed addresses starts routing to AWS because of propagation delays.

To stop advertising the BYOIP address range, use WithdrawByoipCidr.

For more information, see Bring Your Own IP Addresses (BYOIP) in the AWS Global Accelerator Developer Guide.

Request Syntax

{ "Cidr": "string"

}

Request Parameters

Cidr (p. 9)

The address range, in CIDR notation. This must be the exact range that you provisioned. You can't advertise only a portion of the provisioned range.

Type: String

Required: Yes

Response Syntax

{ "ByoipCidr": { "Cidr": "string", "Events": [ {

"Message": "string", "Timestamp": number }

],

"State": "string"

}}

Response Elements

(20)

Errors

ByoipCidr (p. 9)

Information about the address range.

Type: ByoipCidr (p. 153) object

Errors

HTTP Status Code: 400 ByoipCidrNotFoundException

The CIDR that you speciﬁed was not found or is incorrect.

HTTP Status Code: 400 IncorrectCidrStateException

The CIDR that you speciﬁed is not valid for this action. For example, the state of the CIDR might be incorrect for this action.

HTTP Status Code: 400 InvalidArgumentException

Examples

Advertise address range

The following is an example of advertising an address range, and the response.

aws globalaccelerator advertise-byoip-cidr --cidr "198.51.100.0/24"

{

"ByoipCidr": {

"Cidr": "198.51.100.0/24", "State": "PENDING_ADVERTISING"

} }

(21)

AllowCustomRoutingTraﬃc

Specify the Amazon EC2 instance (destination) IP addresses and ports for a VPC subnet endpoint that can receive traffic for a custom routing accelerator. You can allow traffic to all destinations in the subnet endpoint, or allow traffic to a specified list of destination IP addresses and ports in the subnet. Note that you cannot specify IP addresses or ports outside of the range that you configured for the endpoint group.

After you make changes, you can verify that the updates are complete by checking the status of your accelerator: the status changes from IN_PROGRESS to DEPLOYED.

Request Syntax

{ "AllowAllTrafficToEndpoint": boolean, "DestinationAddresses": [ "string" ], "DestinationPorts": [ number ], "EndpointGroupArn": "string", "EndpointId": "string"

}

Request Parameters

AllowAllTraﬃcToEndpoint (p. 12)

Indicates whether all destination IP addresses and ports for a speciﬁed VPC subnet endpoint can receive traﬃc from a custom routing accelerator. The value is TRUE or FALSE.

When set to TRUE, all destinations in the custom routing VPC subnet can receive traﬃc. Note that you cannot specify destination IP addresses and ports when the value is set to TRUE.

When set to FALSE (or not specified), you must specify a list of destination IP addresses that are allowed to receive traffic. A list of ports is optional. If you don't specify a list of ports, the ports that can accept traffic is the same as the ports configured for the endpoint group.

The default value is FALSE.

Type: Boolean Required: No

DestinationAddresses (p. 12)

A list of specific Amazon EC2 instance IP addresses (destination addresses) in a subnet that you want to allow to receive traffic. The IP addresses must be a subset of the IP addresses that you specified for the endpoint group.

DestinationAddresses is required if AllowAllTrafficToEndpoint is FALSE or is not speciﬁed.

Type: Array of strings

(23)

Array Members: Maximum number of 100 items.

Required: No DestinationPorts (p. 12)

A list of speciﬁc Amazon EC2 instance ports (destination ports) that you want to allow to receive traﬃc.

Type: Array of integers

Array Members: Maximum number of 100 items.

Valid Range: Minimum value of 1. Maximum value of 65535.

Required: No

EndpointGroupArn (p. 12)

The Amazon Resource Name (ARN) of the endpoint group.

Type: String

Required: Yes EndpointId (p. 12)

An ID for the endpoint. For custom routing accelerators, this is the virtual private cloud (VPC) subnet ID.

Type: String

Required: Yes

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

InternalServiceErrorException

(24)

Examples

Allow destination EC2 instances to receive traﬃc

The following is an example for specifying all EC2 instances in a subnet endpoint to receive traﬃc for a custom routing accelerator.

aws --region us-west-2 globalaccelerator allow-custom-routing-traffic --endpoint-group-arn arn:aws:globalaccelerator::012345678901:accelerator/1234abcd-abcd-1234-

abcd-1234abcdefgh/listener/0123vxyz/endpoint-group/ab88888example --endpoint-id subnet-abcd123example --allow-all

CreateAccelerator

Create an accelerator. An accelerator includes one or more listeners that process inbound connections and direct traﬃc to one or more endpoint groups, each of which includes endpoints, such as Network Load Balancers.

Important

Request Syntax

{

"Enabled": boolean,

"IdempotencyToken": "string", "IpAddresses": [ "string" ], "IpAddressType": "string", "Name": "string",

"Tags": [ {

"Key": "string", "Value": "string"

} ]}

Request Parameters

Enabled (p. 15)

Indicates whether an accelerator is enabled. The value is true or false. The default value is true.

If the value is set to true, an accelerator cannot be deleted. If set to false, the accelerator can be deleted.

IdempotencyToken (p. 15)

A unique, case-sensitive identiﬁer that you provide to ensure the idempotency—that is, the uniqueness—of an accelerator.

Type: String

Required: Yes IpAddresses (p. 15)

Optionally, if you've added your own IP address pool to Global Accelerator (BYOIP), you can choose an IP address from your own pool to use for the accelerator's static IP address when you create an accelerator.

(26)

Response Syntax

After you bring an address range to AWS, it appears in your account as an address pool. When you create an accelerator, you can assign one IP address from your range to it. Global Accelerator assigns you a second static IP address from an Amazon IP address range. If you bring two IP address ranges to AWS, you can assign one IP address from each range to your accelerator. This restriction is because Global Accelerator assigns each address range to a diﬀerent network zone, for high availability.

You can specify one or two addresses, separated by a space. Do not include the /32 suﬃx.

Note that you can't update IP addresses for an existing accelerator. To change them, you must create a new accelerator with the new addresses.

For more information, see Bring your own IP addresses (BYOIP) in the AWS Global Accelerator Developer Guide.

Array Members: Minimum number of 0 items. Maximum number of 2 items.

Required: No IpAddressType (p. 15)

The value for the address type must be IPv4.

Type: String Valid Values: IPV4 Required: No Name (p. 15)

The name of the accelerator. The name can have a maximum of 64 characters, must contain only alphanumeric characters, periods (.), or hyphens (-), and must not begin or end with a hyphen or period.

Type: String

Required: Yes Tags (p. 15)

Create tags for an accelerator.

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

Type: Array of Tag (p. 183) objects Required: No

Response Syntax

{

"Accelerator": {

"AcceleratorArn": "string",

(27)

"CreatedTime": number, "DnsName": "string", "Enabled": boolean, "IpAddressType": "string", "IpSets": [

{

"IpAddresses": [ "string" ], "IpFamily": "string"

} ],

"LastModifiedTime": number, "Name": "string",

"Status": "string"

} }

Response Elements

Accelerator (p. 16)

The accelerator that is created by specifying a listener and the supported IP address types.

Type: Accelerator (p. 150) object

Errors

InternalServiceErrorException

Examples

Create an accelerator

The following is an example of creating an accelerator with two tags, and the response (which does not include the tag information).

aws globalaccelerator create-accelerator

(28)

CreateCustomRoutingAccelerator

Create a custom routing accelerator. A custom routing accelerator directs traﬃc to one of possibly thousands of Amazon EC2 instance destinations running in a single or multiple virtual private clouds (VPC) subnet endpoints.

Be aware that, by default, all destination EC2 instances in a VPC subnet endpoint cannot receive traﬃc.

To enable all destinations to receive traffic, or to specify individual port mappings that can receive traffic, see the AllowCustomRoutingTraffic operation.

Important

Request Syntax

{

"Enabled": boolean,

"IdempotencyToken": "string", "IpAddresses": [ "string" ], "IpAddressType": "string", "Name": "string",

"Tags": [ {

"Key": "string", "Value": "string"

} ]}

Request Parameters

Enabled (p. 19)

Indicates whether an accelerator is enabled. The value is true or false. The default value is true.

If the value is set to true, an accelerator cannot be deleted. If set to false, the accelerator can be deleted.

A unique, case-sensitive identiﬁer that you provide to ensure the idempotency—that is, the uniqueness—of the request.

Type: String

Required: Yes

(30)

Request Parameters

IpAddresses (p. 19)

Optionally, if you've added your own IP address pool to Global Accelerator (BYOIP), you can choose an IP address from your own pool to use for the accelerator's static IP address when you create an accelerator.

After you bring an address range to AWS, it appears in your account as an address pool. When you create an accelerator, you can assign one IP address from your range to it. Global Accelerator assigns you a second static IP address from an Amazon IP address range. If you bring two IP address ranges to AWS, you can assign one IP address from each range to your accelerator. This restriction is because Global Accelerator assigns each address range to a diﬀerent network zone, for high availability.

You can specify one or two addresses, separated by a space. Do not include the /32 suﬃx.

Note that you can't update IP addresses for an existing accelerator. To change them, you must create a new accelerator with the new addresses.

For more information, see Bring your own IP addresses (BYOIP) in the AWS Global Accelerator Developer Guide.

Required: No IpAddressType (p. 19)

The value for the address type must be IPv4.

Type: String Valid Values: IPV4 Required: No Name (p. 19)

The name of a custom routing accelerator. The name can have a maximum of 64 characters, must contain only alphanumeric characters or hyphens (-), and must not begin or end with a hyphen.

Type: String

Required: Yes Tags (p. 19)

Create tags for an accelerator.

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

Type: Array of Tag (p. 183) objects Required: No

(31)

Response Syntax

{

"Accelerator": {

"AcceleratorArn": "string", "CreatedTime": number, "DnsName": "string", "Enabled": boolean, "IpAddressType": "string", "IpSets": [

{

"IpAddresses": [ "string" ], "IpFamily": "string"

} ],

"LastModifiedTime": number, "Name": "string",

"Status": "string"

}}

Response Elements

Accelerator (p. 21)

The accelerator that is created.

Type: CustomRoutingAccelerator (p. 157) object

Errors

(32)

Examples

Create a custom routing accelerator

The following is an example of creating a custom routing accelerator with two tags, and the response (which does not include the tag information).

aws globalaccelerator create-custom-routing-accelerator --name ExampleCustomRoutingAccelerator

--tags Key="Name",Value="Example Name" Key="Project",Value="Example Project"

--region us-west-2

--ip-addresses 192.0.2.250 198.51.100.52

{ "Accelerator": {

"AcceleratorArn": "arn:aws:globalaccelerator::012345678901:accelerator/1234abcd- abcd-1234-abcd-1234abcdefgh",

"IpAddressType": "IPV4",

"Name": "ExampleCustomRoutingAccelerator", "Enabled": true,

"Status": "IN_PROGRESS", "IpSets": [

{

"IpAddresses": [ "192.0.2.250", "198.51.100.52"

],

"IpFamily": "IPv4"

} ],

"DnsName":"a1234567890abcdef.awsglobalaccelerator.com", "CreatedTime": 1542394847.0,

"LastModifiedTime": 1542394847.0 }

}

CreateCustomRoutingEndpointGroup

Create an endpoint group for the speciﬁed listener for a custom routing accelerator. An endpoint group is a collection of endpoints in one AWS Region.

Request Syntax

{ "DestinationConfigurations": [ {

"FromPort": number,

"Protocols": [ "string" ], "ToPort": number

} ],

"EndpointGroupRegion": "string", "IdempotencyToken": "string", "ListenerArn": "string"

}

Request Parameters

DestinationConﬁgurations (p. 23)

Sets the port range and protocol for all endpoints (virtual private cloud subnets) in a custom routing endpoint group to accept client traﬃc on.

Type: Array of CustomRoutingDestinationConﬁguration (p. 160) objects Array Members: Minimum number of 1 item. Maximum number of 100 items.

Required: Yes

EndpointGroupRegion (p. 23)

The AWS Region where the endpoint group is located. A listener can have only one endpoint group in a speciﬁc Region.

Type: String

Required: Yes

Type: String

Required: Yes

(34)

Response Syntax

ListenerArn (p. 23)

The Amazon Resource Name (ARN) of the listener for a custom routing endpoint.

Type: String

Required: Yes

Response Syntax

{

"EndpointGroup": {

"DestinationDescriptions": [ {

"FromPort": number, "Protocols": [ "string" ], "ToPort": number

} ],

"EndpointGroupArn": "string", "EndpointGroupRegion": "string"

}}

Response Elements

EndpointGroup (p. 24)

The information about the endpoint group created for a custom routing accelerator.

Type: CustomRoutingEndpointGroup (p. 164) object

Errors

AcceleratorNotFoundException

The accelerator that you speciﬁed doesn't exist.

HTTP Status Code: 400 AccessDeniedException

(35)

EndpointGroupAlreadyExistsException

The endpoint group that you speciﬁed already exists.

HTTP Status Code: 400 InvalidPortRangeException

The port numbers that you speciﬁed are not valid numbers or are not unique for this accelerator.

HTTP Status Code: 400 ListenerNotFoundException

The listener that you speciﬁed doesn't exist.

Examples

Create an endpoint group for a custom routing accelerator

The following is an example of creating an endpoint group for a custom routing accelerator, and the response.

aws globalaccelerator create-custom-routing-endpoint-group

--listener-arn arn:aws:globalaccelerator::012345678901:accelerator/1234abcd- abcd-1234-abcd-1234abcdefgh/listener/0123vxyz

--endpoint-group-region us-east-1

--endpoint-configurations EndpointId=i-1234567890abcdef0,Weight=128 --region us-west-2

{ "EndpointGroup": {

"EndpointId": "i-1234567890abcdef0"

"EndpointGroupArn": "arn:aws:globalaccelerator::012345678901:accelerator/1234abcd- abcd-1234-abcd-1234abcdefgh/listener/0123vxyz/endpoint-group/098765zyxwvu",

"EndpointGroupRegion": "us-east-1"

} }

(36)

CreateCustomRoutingListener

Create a listener to process inbound connections from clients to a custom routing accelerator.

Connections arrive to assigned static IP addresses on the port range that you specify.

Request Syntax

{ "AcceleratorArn": "string", "IdempotencyToken": "string", "PortRanges": [

{

"FromPort": number, "ToPort": number }

]}

Request Parameters

AcceleratorArn (p. 27)

The Amazon Resource Name (ARN) of the accelerator for a custom routing listener.

Type: String

Required: Yes

Type: String

Required: Yes PortRanges (p. 27)

The port range to support for connections from clients to your accelerator.

Separately, you set port ranges for endpoints. For more information, see About endpoints for custom routing accelerators.

Type: Array of PortRange (p. 181) objects

Array Members: Minimum number of 1 item. Maximum number of 10 items.

Required: Yes

(38)

Response Syntax

{

"Listener": {

"ListenerArn": "string", "PortRanges": [

{

] }}

Response Elements

Listener (p. 28)

The listener that you've created for a custom routing accelerator.

Type: CustomRoutingListener (p. 165) object

Errors

HTTP Status Code: 400 InvalidPortRangeException

The port numbers that you speciﬁed are not valid numbers or are not unique for this accelerator.

(39)

Examples

Create a listener for a custom routing accelerator

The following is an example of creating a listener for a custom routing accelerator, and the response.

aws --region us-west-2 globalaccelerator create-custom-routing-listener

--accelerator-arn arn:aws:globalaccelerator::012345678901:accelerator/1234abcd- abcd-1234-abcd-1234abcdefgh

--port-ranges FromPort=80,ToPort=80 FromPort=81,ToPort=81

{ "Listener": { "PortRange": [ "FromPort": 5000 "ToPort": 10000, ],

"ListenerArn": "arn:aws:globalaccelerator::012345678901:accelerator/1234abcd- abcd-1234-abcd-1234abcdefgh/listener/0123vxyz"

} }

CreateEndpointGroup

Create an endpoint group for the speciﬁed listener. An endpoint group is a collection of endpoints in one AWS Region. A resource must be valid and active when you add it as an endpoint.

Request Syntax

{

"EndpointConfigurations": [ {

"ClientIPPreservationEnabled": boolean, "EndpointId": "string",

"Weight": number }

],

"EndpointGroupRegion": "string", "HealthCheckIntervalSeconds": number, "HealthCheckPath": "string",

"HealthCheckPort": number, "HealthCheckProtocol": "string", "IdempotencyToken": "string", "ListenerArn": "string", "PortOverrides": [ {

"EndpointPort": number, "ListenerPort": number }

],

"ThresholdCount": number, "TrafficDialPercentage": number }

Request Parameters

EndpointConﬁgurations (p. 30) The list of endpoint objects.

Type: Array of EndpointConﬁguration (p. 168) objects

Required: No

EndpointGroupRegion (p. 30)

The AWS Region where the endpoint group is located. A listener can have only one endpoint group in a speciﬁc Region.

Type: String

Required: Yes

(41)

HealthCheckIntervalSeconds (p. 30)

The time—10 seconds or 30 seconds—between each health check for an endpoint. The default value is 30.

Type: Integer

Required: No HealthCheckPath (p. 30)

If the protocol is HTTP/S, then this speciﬁes the path that is the destination for health check targets.

The default value is slash (/).

Type: String

Pattern: ^/[-a-zA-Z0-9@:%_\\+.~#?&/=]*$

Required: No HealthCheckPort (p. 30)

The port that AWS Global Accelerator uses to check the health of endpoints that are part of this endpoint group. The default port is the listener port that this endpoint group is associated with. If listener port is a list of ports, Global Accelerator uses the ﬁrst port in the list.

Type: Integer

Required: No

HealthCheckProtocol (p. 30)

The protocol that AWS Global Accelerator uses to check the health of endpoints that are part of this endpoint group. The default value is TCP.

Type: String

Valid Values: TCP | HTTP | HTTPS Required: No

Type: String

Required: Yes ListenerArn (p. 30)

The Amazon Resource Name (ARN) of the listener.

Type: String

(42)

Response Syntax

Required: Yes PortOverrides (p. 30)

Override specific listener ports used to route traffic to endpoints that are part of this endpoint group. For example, you can create a port override in which the listener receives user traffic on ports 80 and 443, but your accelerator routes that traffic to ports 1080 and 1443, respectively, on the endpoints.

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

Type: Array of PortOverride (p. 180) objects

Required: No ThresholdCount (p. 30)

The number of consecutive health checks required to set the state of a healthy endpoint to unhealthy, or to set an unhealthy endpoint to healthy. The default value is 3.

Type: Integer

Required: No

TraﬃcDialPercentage (p. 30)

The percentage of traﬃc to send to an AWS Region. Additional traﬃc is distributed to other endpoint groups for this listener.

Use this action to increase (dial up) or decrease (dial down) traﬃc to a speciﬁc Region. The

percentage is applied to the traﬃc that would otherwise have been routed to the Region based on optimal routing.

The default value is 100.

Type: Float

Required: No

Response Syntax

"ClientIPPreservationEnabled": boolean, "EndpointId": "string",

"HealthReason": "string", "HealthState": "string", "Weight": number

} ],

"EndpointGroupArn": "string", "EndpointGroupRegion": "string", "HealthCheckIntervalSeconds": number, "HealthCheckPath": "string",

(43)

"HealthCheckPort": number, "HealthCheckProtocol": "string", "PortOverrides": [

{

"EndpointPort": number, "ListenerPort": number }

],

"ThresholdCount": number, "TrafficDialPercentage": number }

}

Response Elements

EndpointGroup (p. 32)

The information about the endpoint group that was created.

Type: EndpointGroup (p. 172) object

Errors

HTTP Status Code: 400 AccessDeniedException

EndpointGroupAlreadyExistsException

The endpoint group that you speciﬁed already exists.

(44)

Examples

HTTP Status Code: 400 ListenerNotFoundException

The listener that you speciﬁed doesn't exist.

Examples

Create an endpoint group

The following is an example of creating an endpoint group, and the response.

aws globalaccelerator create-endpoint-group

--listener-arn arn:aws:globalaccelerator::012345678901:accelerator/1234abcd- abcd-1234-abcd-1234abcdefgh/listener/0123vxyz

--endpoint-group-region us-east-1

--port-overrides ListenerPort=443,EndpointPort=1443

--endpoint-configurations EndpointId=i-1234567890abcdef0,Weight=128 --region us-west-2

"TrafficDialPercentage": 100.0, "EndpointDescriptions": [

{

"Weight": 128,

"EndpointId": "i-1234567890abcdef0"

} ],

"PortOverrides": [ {

"EndpointPort": 1443, "ListenerPort": 443 }

],

"EndpointGroupArn": "arn:aws:globalaccelerator::012345678901:accelerator/1234abcd- abcd-1234-abcd-1234abcdefgh/listener/0123vxyz/endpoint-group/098765zyxwvu",

"EndpointGroupRegion": "us-east-1"

} }

CreateListener

Create a listener to process inbound connections from clients to an accelerator. Connections arrive to assigned static IP addresses on a port, port range, or list of port ranges that you specify.

Request Syntax

{ "AcceleratorArn": "string", "ClientAffinity": "string", "IdempotencyToken": "string", "PortRanges": [

{

],

"Protocol": "string"

}

Request Parameters

AcceleratorArn (p. 36)

The Amazon Resource Name (ARN) of your accelerator.

Type: String

Required: Yes ClientAﬃnity (p. 36)

Client affinity lets you direct all requests from a user to the same endpoint, if you have stateful applications, regardless of the port and protocol of the client request. Client affinity gives you control over whether to always route each client to the same specific endpoint.

AWS Global Accelerator uses a consistent-flow hashing algorithm to choose the optimal endpoint for a connection. If client affinity is NONE, Global Accelerator uses the "five-tuple" (5-tuple) properties

—source IP address, source port, destination IP address, destination port, and protocol—to select the hash value, and then chooses the best endpoint. However, with this setting, if someone uses diﬀerent ports to connect to Global Accelerator, their connections might not be always routed to the same endpoint because the hash value changes.

If you want a given client to always be routed to the same endpoint, set client aﬃnity to SOURCE_IP instead. When you use the SOURCE_IP setting, Global Accelerator uses the "two-tuple" (2-tuple) properties— source (client) IP address and destination IP address—to select the hash value.

The default value is NONE.

Type: String

Valid Values: NONE | SOURCE_IP

(47)

Required: No

Type: String

Required: Yes PortRanges (p. 36)

The list of port ranges to support for connections from clients to your accelerator.

Type: Array of PortRange (p. 181) objects

Array Members: Minimum number of 1 item. Maximum number of 10 items.

Required: Yes Protocol (p. 36)

The protocol for connections from clients to your accelerator.

Type: String

Valid Values: TCP | UDP Required: Yes

Response Syntax

{

"Listener": {

"ClientAffinity": "string", "ListenerArn": "string", "PortRanges": [

{

],

"Protocol": "string"

}}

Response Elements

Listener (p. 37)

The listener that you've created.

Type: Listener (p. 176) object

AWS Global Accelerator

AWS Global Accelerator

API Reference

API Version 2018-08-08

AWS Global Accelerator: API Reference

Table of Contents

Welcome

Actions

AddCustomRoutingEndpoints

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

AdvertiseByoipCidr

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Advertise address range

See Also

AllowCustomRoutingTraﬃc

Request Syntax

Request Parameters

Response Elements

Errors

Examples

Allow destination EC2 instances to receive traﬃc

See Also

CreateAccelerator

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Create an accelerator

See Also

CreateCustomRoutingAccelerator

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Create a custom routing accelerator

See Also

CreateCustomRoutingEndpointGroup

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Create an endpoint group for a custom routing accelerator

See Also

CreateCustomRoutingListener

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Create a listener for a custom routing accelerator

See Also

CreateEndpointGroup

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Create an endpoint group

See Also

CreateListener

Request Syntax

Request Parameters