From 07d990953e2a80bbfffdf6d305ebbe4b4d76818a Mon Sep 17 00:00:00 2001 From: Doug Date: Thu, 7 Feb 2019 09:41:59 -0800 Subject: [PATCH] chore (docs): Updated ECS readme to use branded AWS/Amazon service names (#1703) * Updated ECS readme to use branded AWS/Amazon serive names * Update README.md * Update README.md If we make the top-level heading an H1, we have to promote the sub-headings (done). --- packages/@aws-cdk/aws-ecs/README.md | 114 ++++++++++++++++------------ 1 file changed, 64 insertions(+), 50 deletions(-) diff --git a/packages/@aws-cdk/aws-ecs/README.md b/packages/@aws-cdk/aws-ecs/README.md index 47177d90029ae..b913f8756c623 100644 --- a/packages/@aws-cdk/aws-ecs/README.md +++ b/packages/@aws-cdk/aws-ecs/README.md @@ -1,7 +1,18 @@ -## AWS Elastic Container Service (ECS) Construct Library +# Amazon ECS -This package contains constructs for working with **AWS Elastic Container -Service** (ECS). The simplest example of using this library looks like this: +This package contains constructs for working with **Amazon Elastic Container +Service** (Amazon ECS). + +Amazon ECS is a highly scalable, fast, container management service +that makes it easy to run, stop, +and manage Docker containers on a cluster of Amazon EC2 instances. + +For further information on Amazon ECS, +see the [Amazon ECS documentation](https://docs.aws.amazon.com/ecs) + +The following example creates an Amazon ECS cluster, +adds capacity to it, +and instantiates the Amazon ECS Service with an automatic load balancer. ```ts // Create an ECS cluster @@ -15,7 +26,7 @@ cluster.addDefaultAutoScalingGroupCapacity({ instanceCount: 3, }); -// Instantiate ECS Service with an automatic load balancer +// Instantiate Amazon ECS Service with an automatic load balancer const ecsService = new ecs.LoadBalancedEc2Service(this, 'Service', { cluster, memoryLimitMiB: 512, @@ -23,38 +34,38 @@ const ecsService = new ecs.LoadBalancedEc2Service(this, 'Service', { }); ``` -### Fargate vs ECS +## AWS Fargate vs Amazon ECS -There are two sets of constructs in this library; one to run tasks on ECS and -one to run Tasks on Fargate. +There are two sets of constructs in this library; one to run tasks on Amazon ECS and +one to run tasks on AWS Fargate. -- Use the `Ec2TaskDefinition` and `Ec2Service` constructs to run tasks on EC2 instances running in your account. +- Use the `Ec2TaskDefinition` and `Ec2Service` constructs to run tasks on Amazon EC2 instances running in your account. - Use the `FargateTaskDefinition` and `FargateService` constructs to run tasks on instances that are managed for you by AWS. Here are the main differences: -- **EC2**: instances are under your control. Complete control of task to host +- **Amazon EC2**: instances are under your control. Complete control of task to host allocation. Required to specify at least a memory reseration or limit for every container. Can use Host, Bridge and AwsVpc networking modes. Can attach Classic Load Balancer. Can share volumes between container and host. -- **Fargate**: tasks run on AWS-managed instances, AWS manages task to host +- **AWS Fargate**: tasks run on AWS-managed instances, AWS manages task to host allocation for you. Requires specification of memory and cpu sizes at the taskdefinition level. Only supports AwsVpc networking modes and Application/Network Load Balancers. Only the AWS log driver is supported. Many host features are not supported such as adding kernel capabilities and mounting host devices/volumes inside the container. -For more information on EC2 vs Fargate and networking see the AWS Documentation: +For more information on Amazon EC2 vs AWS Fargate and networking see the AWS Documentation: [AWS Fargate](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html) and [Task Networking](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-networking.html). -### Clusters +## Clusters A `Cluster` defines the infrastructure to run your tasks on. You can run many tasks on a single cluster. -To create a cluster that can run Fargate tasks, go: +The following code creates a cluster that can run AWS Fargate tasks: ```ts const cluster = new ecs.Cluster(this, 'Cluster', { @@ -62,15 +73,15 @@ const cluster = new ecs.Cluster(this, 'Cluster', { }); ``` -If you wish to use tasks with EC2 launch-type, you also have to add capacity to -your cluster in order for tasks to be scheduled on your instances. Typically, -you will add an AutoScalingGroup with instances running the latest -ECS-optimized AMI to the cluster. There is a method to build and add such an +To use tasks with Amazon EC2 launch-type, you have to add capacity to +the cluster in order for tasks to be scheduled on your instances. Typically, +you add an AutoScalingGroup with instances running the latest +Amazon ECS-optimized AMI to the cluster. There is a method to build and add such an AutoScalingGroup automatically, or you can supply a customized AutoScalingGroup that you construct yourself. It's possible to add multiple AutoScalingGroups -with various instance types if you want to. +with various instance types. -Creating an ECS cluster and adding capacity to it looks like this: +The following example creates an Amazon ECS cluster and adds capacity to it: ```ts const cluster = new ecs.Cluster(this, 'Cluster', { @@ -83,12 +94,12 @@ cluster.addDefaultAutoScalingGroupCapacity({ instanceCount: 3, }); -// Or add customized capacity. Be sure to start the ECS-optimized AMI. +// Or add customized capacity. Be sure to start the Amazon ECS-optimized AMI. const autoScalingGroup = new autoscaling.AutoScalingGroup(this, 'ASG', { vpc, instanceType: new ec2.InstanceType('t2.xlarge'), machineImage: new EcsOptimizedAmi(), - // Or use ECS-Optimized Amazon Linux 2 AMI + // Or use Amazon ECS-Optimized Amazon Linux 2 AMI // machineImage: new EcsOptimizedAmi({ generation: ec2.AmazonLinuxGeneration.AmazonLinux2 }), desiredCapacity: 3, // ... other options here ... @@ -97,15 +108,16 @@ const autoScalingGroup = new autoscaling.AutoScalingGroup(this, 'ASG', { cluster.addAutoScalingGroupCapacity(autoScalingGroup); ``` -### Task definitions -A Task Definition describes what a single copy of a **Task** should look like. +## Task definitions + +A task Definition describes what a single copy of a **task** should look like. A task definition has one or more containers; typically, it has one main container (the *default container* is the first one that's added -to the task definition, and it will be marked *essential*) and optionally +to the task definition, and it is marked *essential*) and optionally some supporting containers which are used to support the main container, doings things like upload logs or metrics to monitoring services. -To run a task or service with EC2 launch type, use the `Ec2TaskDefinition`. For Fargate tasks/services, use the +To run a task or service with Amazon EC2 launch type, use the `Ec2TaskDefinition`. For AWS Fargate tasks/services, use the `FargateTaskDefinition`. These classes provide a simplified API that only contain properties relevant for that specific launch type. @@ -117,7 +129,7 @@ const fargateTaskDefinition = new ecs.FargateTaskDefinition(this, 'TaskDef', { cpu: '256' }); ``` -To add containers to a Task Definition, call `addContainer()`: +To add containers to a task definition, call `addContainer()`: ```ts const container = fargateTaskDefinition.addContainer("WebContainer", { @@ -150,11 +162,12 @@ container.addPortMappings({ }) ``` -If you wish to use a TaskDefinition that can be used with either EC2 or -Fargate launch types, there is also the `TaskDefinition` construct. +To use a TaskDefinition that can be used with either Amazon EC2 or +AWS Fargate launch types, use the `TaskDefinition` construct. -When creating a Task Definition you have to specify what kind of -tasks you intend to run: EC2, Fargate, or both: +When creating a task definition you have to specify what kind of +tasks you intend to run: Amazon EC2, AWS Fargate, or both. +The following example uses both: ```ts const taskDefinition = new ecs.TaskDefinition(this, 'TaskDef', { @@ -165,7 +178,7 @@ const taskDefinition = new ecs.TaskDefinition(this, 'TaskDef', { }); ``` -#### Images +### Images Images supply the software that runs inside the container. Images can be obtained from either DockerHub or from ECR repositories, or built directly from a local Dockerfile. @@ -177,11 +190,12 @@ obtained from either DockerHub or from ECR repositories, or built directly from * `ecs.ContainerImage.fromAsset(this, 'Image', { directory: './image' })`: build and upload an image directly from a `Dockerfile` in your source directory. -### Service +## Service A `Service` instantiates a `TaskDefinition` on a `Cluster` a given number of -times, optionally associating them with a load balancer. Tasks that fail will -automatically be restarted. +times, optionally associating them with a load balancer. +If a task fails, +Amazon ECS automatically restarts the task. ```ts const taskDefinition; @@ -193,7 +207,7 @@ const service = new ecs.FargateService(this, 'Service', { }); ``` -#### Include a load balancer +### Include a load balancer `Services` are load balancing targets and can be directly attached to load balancers: @@ -216,9 +230,9 @@ There are two higher-level constructs available which include a load balancer fo * `LoadBalancedFargateService` * `LoadBalancedEc2Service` -### Task AutoScaling +## Task Auto-Scaling -You can configure the task count of a service to match demand. Task AutoScaling is +You can configure the task count of a service to match demand. Task auto-scaling is configured by calling `autoScaleTaskCount()`: ```ts @@ -233,18 +247,18 @@ scaling.scaleOnRequestCount('RequestScaling', { }) ``` -Task AutoScaling is powered by *Application AutoScaling*. Refer to that for -more information. +Task auto-scaling is powered by *Application Auto-Scaling*. +See that section for details. -### Instance AutoScaling +## Instance Auto-Scaling -If you're running on Fargate, AWS will manage the physical machines that your -containers are running on for you. If you're running an ECS cluster however, -your EC2 instances might fill up as your number of Tasks goes up. +If you're running on AWS Fargate, AWS manages the physical machines that your +containers are running on for you. If you're running an Amazon ECS cluster however, +your Amazon EC2 instances might fill up as your number of Tasks goes up. -To avoid placement errors, you will want to configure AutoScaling for your -EC2 instance group so that your instance count scales with demand. To keep -your EC2 instances halfway loaded, scaling up to a maximum of 30 instances +To avoid placement errors, configure auto-scaling for your +Amazon EC2 instance group so that your instance count scales with demand. To keep +your Amazon EC2 instances halfway loaded, scaling up to a maximum of 30 instances if required: ```ts @@ -268,16 +282,16 @@ autoScalingGroup.scaleOnCpuUtilization('KeepCpuHalfwayLoaded', { See the `@aws-cdk/aws-autoscaling` library for more autoscaling options you can configure on your instances. -### Integration with CloudWatch Events +## Integration with CloudWatch Events -To start an ECS task on an EC2-backed Cluster, instantiate an +To start an Amazon ECS task on an Amazon EC2-backed Cluster, instantiate an `Ec2TaskEventRuleTarget` instead of an `Ec2Service`: [example of CloudWatch Events integration](test/ec2/integ.event-task.lit.ts) -> Note: it is currently not possible to start Fargate tasks in this way. +> Note: it is currently not possible to start AWS Fargate tasks in this way. -### Roadmap +## Roadmap - [ ] Service Discovery Integration - [ ] Private registry authentication