Deploying Sample Yelb Application with Amazon ECS, AWS CloudFormation, and an Application Load Balancer
This repo was created in conjunction with the AWS Blog Post Migrate Existing Amazon ECS Services to Amazon ECS Service Connect Configured Services.
The Yelb application used in this demo was adapated from Massimo Re Ferrè's original application here.
This reference architecture provides an easy to use YAML template for deploying a sample Yelb application using service discovery to Amazon Elastic Container Service (Amazon ECS) with AWS CloudFormation.
To launch the CloudFormation stack you can use the
provided setup.sh script located in the scripts folder. To
run the script, you will need to have the AWS CLI installed on your system, and
the minimum required AWS CLI version is 2.9.2.
The script accepts 4 optional arguments:
AWS_PROFILE: Name of the AWS CLI profile you wish to use. If you do not provide a valuedefaultwill be used.AWS_DEFAULT_REGION: Default Region where Cloud Formation Resources will be deployed. If you do not provide a valueus-west-2will be used.ENVIRONMENT_NAME: Environment Name for the Amazon ECS cluster. If you do not provide a valueecswill be used.CLUSTER_NAME: Desired Amazon ECS Cluster Name. If you do not provide a valueyelb-clusterwill be used.
To use the setup script with all arguments in the us-east-2 region, you would run the following command:
./scripts/setup.sh my-profile us-east-2 my-ecs-environment my-ecs-clusterThe setup script will take around 5 minutes to complete.
The repository consists of a single cloudformation template that deploys the following:
- An Amazon VPC with public and private subnets.
- A highly available Amazon ECS cluster deployed across two Availability Zones.
- A pair of NAT gateways (one in each zone) to handle outbound traffic.
- Four microservices deployed as Amazon ECS services (yelb-ui, yelb-appserver, yelb-db, yelb-redis).
- An Application Load Balancer (ALB) to the public subnets to handle inbound traffic.
- Internal Load Balancer used to handle internal traffic through a private hosted zone using Route 53.
- Centralized container logging with Amazon CloudWatch Logs.
- Amazon ECS Service Definitions and Task Defintions for
yelb-db,yelb-redis,yelb-appserver, andyelb-ui.
Using CloudFormation to deploy and manage services with Amazon ECS has a number of nice benefits over more traditional methods (AWS CLI, scripting, etc.).
A template can be used repeatedly to create identical copies of the same stack (or to use as a foundation to start a new stack). Templates are simple YAML- or JSON-formatted text files that can be placed under your normal source control mechanisms, stored in private or public locations such as Amazon S3, and exchanged via email. With CloudFormation, you can see exactly which AWS resources make up a stack. You retain full control and have the ability to modify any of the AWS resources created as part of a stack.
Fed up with outdated documentation on your infrastructure or environments? Still keep manual documentation of IP ranges, security group rules, etc.?
With CloudFormation, your template becomes your documentation. Want to see exactly what you have deployed? Just look at your template. If you keep it in source control, then you can also look back at exactly which changes were made and by whom.
CloudFormation not only handles the initial deployment of your infrastructure and environments, but it can also manage the whole lifecycle, including future updates. During updates, you have fine-grained control and visibility over how changes are applied, using functionality such as change sets, rolling update policies and stack policies.
The provided CloudFormation template deploys the following network design:
| Item | CIDR Range | Usable IPs | Description |
|---|---|---|---|
| VPC | 10.0.0.0/16 | 65,534 | The whole range used for the VPC and all subnets |
| Public Subnet | 10.0.0.0/19 | 8,190 | The public subnet in the first Availability Zone |
| Public Subnet | 10.0.32.0/19 | 8,190 | The public subnet in the second Availability Zone |
| Private Subnet | 10.0.64.0/19 | 8,190 | The private subnet in the first Availability Zone |
| Private Subnet | 10.0.96.0/19 | 8,190 | The private subnet in the second Availability Zone |
You can adjust the CIDR ranges used in Mappings: section of the iac/ base-infra-cfn.yaml template. Below is an example:
Mappings:
# Hard values for the subnet masks. These masks define
# the range of internal IP addresses that can be assigned.
# The VPC can have all IP's from 10.0.0.0 to 10.0.255.255
# There are four subnets which cover the ranges:
#
# 10.0.0.0 - 10.0.31.255
# 10.0.32.0 - 10.0.63.255
# 10.0.64.0 - 10.0.95.255
# 10.0.96.0 - 10.0.127.255
#
# If you need more IP addresses (perhaps you have so many
# instances that you run out) then you can customize these
# ranges to add more
SubnetConfig:
VPC:
CIDR: "10.0.0.0/16"
Public1:
CIDR: "10.0.0.0/19"
Public2:
CIDR: "10.0.32.0/19"
Private1:
CIDR: "10.0.64.0/19"
Private2:
CIDR: "10.0.96.0/19"Now that you have your sample application and all required infrastructure deployed, you are ready to generate some traffic using the application endpoint. To do this, use the ./scripts/generate-traffic.sh script by running the following command:
./scripts/generate-traffic.shOnce the script completes, you will see a message similar to the following:
Successfully created/updated stack - hey-loadtest
Running Hey Loadtest with 100 workers and 10,000 requests for 2 minutes...
Please wait...
Hey Loadtest for: http://yelb-serviceconnect-319970139.us-east-2.elb.amazonaws.com/ complete!
View the Amazon EC2 Load Balancer Console here: https://console.aws.amazon.com/ec2/home#LoadBalancers
Be sure to choose the correct region for your deployment.Now you are ready to migrate from service discovery to Amazon ECS Service Connect.
To simplify the commands needed, use the ./scripts/use-service-connect.sh script by running the following command in the shell environment of your choice:
./scripts/use-service-connect.shOnce the script completes, you should see output similar to the following example:
Updating yelb-db...
Updating yelb-redis...
Updating yelb-appserver...
Updating yelb-ui...
Amazon ECS Service Connect migration complete!After the migration is complete, the sample application architecture will look like this:
To avoid future charges, clean up the resources created in this blog post. To make it easier, we created a ./scripts/cleanup.sh script for you to use.
Run the following command:
./scripts/cleanup.shNote: The clean up script will take around 20 minutes to complete.
If you found yourself wishing this set of frequently asked questions had an answer for a particular problem, please submit a pull request. The chances are that others will also benefit from having the answer listed here.
Please create a new GitHub issue for any feature requests, bugs, or documentation improvements.
Where possible, please also submit a pull request for the change.
MIT License
Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.