# AWS::GlobalAccelerator Construct Library
<!--BEGIN STABILITY BANNER-->---
---
<!--END STABILITY BANNER-->
## 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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/AWS_GlobalAccelerator.html).
## Example
Here's an example that sets up a Global Accelerator for two Application Load
Balancers in two different AWS Regions:
```python
# 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)]
)
```
## 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
* Network Load Balancers
* EC2 Instances
* Elastic IP Addresses
### Application Load Balancers
```python
# alb: elbv2.ApplicationLoadBalancer
# listener: globalaccelerator.Listener
listener.add_endpoint_group("Group",
endpoints=[
ga_endpoints.ApplicationLoadBalancerEndpoint(alb,
weight=128,
preserve_client_ip=True
)
]
)
```
### Network Load Balancers
```python
# nlb: elbv2.NetworkLoadBalancer
# listener: globalaccelerator.Listener
listener.add_endpoint_group("Group",
endpoints=[
ga_endpoints.NetworkLoadBalancerEndpoint(nlb,
weight=128
)
]
)
```
### EC2 Instances
```python
# listener: globalaccelerator.Listener
# instance: ec2.Instance
listener.add_endpoint_group("Group",
endpoints=[
ga_endpoints.InstanceEndpoint(instance,
weight=128,
preserve_client_ip=True
)
]
)
```
### Elastic IP Addresses
```python
# listener: globalaccelerator.Listener
# eip: ec2.CfnEIP
listener.add_endpoint_group("Group",
endpoints=[
ga_endpoints.CfnEipEndpoint(eip,
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:
```python
# 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))
```
Raw data
{
"_id": null,
"home_page": "https://github.com/aws/aws-cdk",
"name": "aws-cdk.aws-globalaccelerator",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Amazon Web Services",
"author_email": "",
"download_url": "",
"platform": null,
"description": "# AWS::GlobalAccelerator Construct Library\n\n<!--BEGIN STABILITY BANNER-->---\n\n\n\n\n\n\n---\n<!--END STABILITY BANNER-->\n\n## Introduction\n\nAWS Global Accelerator (AGA) is a service that improves the availability and\nperformance of your applications with local or global users.\n\nIt intercepts your user's network connection at an edge location close to\nthem, and routes it to one of potentially multiple, redundant backends across\nthe more reliable and less congested AWS global network.\n\nAGA can be used to route traffic to Application Load Balancers, Network Load\nBalancers, EC2 Instances and Elastic IP Addresses.\n\nFor more information, see the [AWS Global\nAccelerator Developer Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/AWS_GlobalAccelerator.html).\n\n## Example\n\nHere's an example that sets up a Global Accelerator for two Application Load\nBalancers in two different AWS Regions:\n\n```python\n# Create an Accelerator\naccelerator = globalaccelerator.Accelerator(self, \"Accelerator\")\n\n# Create a Listener\nlistener = accelerator.add_listener(\"Listener\",\n port_ranges=[globalaccelerator.PortRange(from_port=80), globalaccelerator.PortRange(from_port=443)\n ]\n)\n\n# Import the Load Balancers\nnlb1 = elbv2.NetworkLoadBalancer.from_network_load_balancer_attributes(self, \"NLB1\",\n load_balancer_arn=\"arn:aws:elasticloadbalancing:us-west-2:111111111111:loadbalancer/app/my-load-balancer1/e16bef66805b\"\n)\nnlb2 = elbv2.NetworkLoadBalancer.from_network_load_balancer_attributes(self, \"NLB2\",\n load_balancer_arn=\"arn:aws:elasticloadbalancing:ap-south-1:111111111111:loadbalancer/app/my-load-balancer2/5513dc2ea8a1\"\n)\n\n# Add one EndpointGroup for each Region we are targeting\nlistener.add_endpoint_group(\"Group1\",\n endpoints=[ga_endpoints.NetworkLoadBalancerEndpoint(nlb1)]\n)\nlistener.add_endpoint_group(\"Group2\",\n # Imported load balancers automatically calculate their Region from the ARN.\n # If you are load balancing to other resources, you must also pass a `region`\n # parameter here.\n endpoints=[ga_endpoints.NetworkLoadBalancerEndpoint(nlb2)]\n)\n```\n\n## Concepts\n\nThe **Accelerator** construct defines a Global Accelerator resource.\n\nAn Accelerator includes one or more **Listeners** that accepts inbound\nconnections on one or more ports.\n\nEach Listener has one or more **Endpoint Groups**, representing multiple\ngeographically distributed copies of your application. There is one Endpoint\nGroup per Region, and user traffic is routed to the closest Region by default.\n\nAn Endpoint Group consists of one or more **Endpoints**, which is where the\nuser traffic coming in on the Listener is ultimately sent. The Endpoint port\nused is the same as the traffic came in on at the Listener, unless overridden.\n\n## Types of Endpoints\n\nThere are 4 types of Endpoints, and they can be found in the\n`@aws-cdk/aws-globalaccelerator-endpoints` package:\n\n* Application Load Balancers\n* Network Load Balancers\n* EC2 Instances\n* Elastic IP Addresses\n\n### Application Load Balancers\n\n```python\n# alb: elbv2.ApplicationLoadBalancer\n# listener: globalaccelerator.Listener\n\n\nlistener.add_endpoint_group(\"Group\",\n endpoints=[\n ga_endpoints.ApplicationLoadBalancerEndpoint(alb,\n weight=128,\n preserve_client_ip=True\n )\n ]\n)\n```\n\n### Network Load Balancers\n\n```python\n# nlb: elbv2.NetworkLoadBalancer\n# listener: globalaccelerator.Listener\n\n\nlistener.add_endpoint_group(\"Group\",\n endpoints=[\n ga_endpoints.NetworkLoadBalancerEndpoint(nlb,\n weight=128\n )\n ]\n)\n```\n\n### EC2 Instances\n\n```python\n# listener: globalaccelerator.Listener\n# instance: ec2.Instance\n\n\nlistener.add_endpoint_group(\"Group\",\n endpoints=[\n ga_endpoints.InstanceEndpoint(instance,\n weight=128,\n preserve_client_ip=True\n )\n ]\n)\n```\n\n### Elastic IP Addresses\n\n```python\n# listener: globalaccelerator.Listener\n# eip: ec2.CfnEIP\n\n\nlistener.add_endpoint_group(\"Group\",\n endpoints=[\n ga_endpoints.CfnEipEndpoint(eip,\n weight=128\n )\n ]\n)\n```\n\n## Client IP Address Preservation and Security Groups\n\nWhen using the `preserveClientIp` feature, AGA creates\n**Elastic Network Interfaces** (ENIs) in your AWS account, that are\nassociated with a Security Group AGA creates for you. You can use the\nsecurity group created by AGA as a source group in other security groups\n(such as those for EC2 instances or Elastic Load Balancers), if you want to\nrestrict incoming traffic to the AGA security group rules.\n\nAGA creates a specific security group called `GlobalAccelerator` for each VPC\nit has an ENI in (this behavior can not be changed). CloudFormation doesn't\nsupport referencing the security group created by AGA, but this construct\nlibrary comes with a custom resource that enables you to reference the AGA\nsecurity group.\n\nCall `endpointGroup.connectionsPeer()` to obtain a reference to the Security Group\nwhich you can use in connection rules. You must pass a reference to the VPC in whose\ncontext the security group will be looked up. Example:\n\n```python\n# listener: globalaccelerator.Listener\n\n# Non-open ALB\n# alb: elbv2.ApplicationLoadBalancer\n\n# Remember that there is only one AGA security group per VPC.\n# vpc: ec2.Vpc\n\n\nendpoint_group = listener.add_endpoint_group(\"Group\",\n endpoints=[\n ga_endpoints.ApplicationLoadBalancerEndpoint(alb,\n preserve_client_ip=True\n )\n ]\n)\naga_sg = endpoint_group.connections_peer(\"GlobalAcceleratorSG\", vpc)\n\n# Allow connections from the AGA to the ALB\nalb.connections.allow_from(aga_sg, ec2.Port.tcp(443))\n```\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "The CDK Construct Library for AWS::GlobalAccelerator",
"version": "1.189.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bbcfabd494293e6760cae400ccc81b55e19929ddfdc0776e982a297b5ad85382",
"md5": "29479b354e69b936ef5f3459dead98bd",
"sha256": "31739bae837b07e48d714a56097e901b3b3d746b9a53948411a72fece77be8d9"
},
"downloads": -1,
"filename": "aws_cdk.aws_globalaccelerator-1.189.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "29479b354e69b936ef5f3459dead98bd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.7",
"size": 123309,
"upload_time": "2023-01-19T03:39:53",
"upload_time_iso_8601": "2023-01-19T03:39:53.625577Z",
"url": "https://files.pythonhosted.org/packages/bb/cf/abd494293e6760cae400ccc81b55e19929ddfdc0776e982a297b5ad85382/aws_cdk.aws_globalaccelerator-1.189.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-19 03:39:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "aws",
"github_project": "aws-cdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aws-cdk.aws-globalaccelerator"
}
JSON
