Menu
Amazon EC2 Container Service
Developer Guide (API Version 2014-11-13)

Creating a Service

When you create an Amazon ECS service, you specify the basic parameters that define what makes up your service and how it should behave. These parameters create a service definition.

You can optionally configure additional features, such as an Elastic Load Balancing load balancer to distribute traffic across the containers in your service, For more information, see Service Load Balancing. You must verify that your container instances can receive traffic from your load balancers. You can allow traffic to all ports on your container instances from your load balancer's security group to ensure that traffic can reach any containers that use dynamically assigned ports.

Configuring Basic Service Parameters

All services require some basic configuration parameters that define the service, such as the task definition to use, which cluster the service should run on, how many tasks should be placed for the service, and so on; this is called the service definition. For more information about the parameters defined in a service definition, see Service Definition Parameters.

This procedure covers creating a service with the basic service definition parameters that are required. After you have configured these parameters, you can create your service or move on to the procedures for optional service definition configuration, such as configuring your service to use a load balancer.

To configure the basic service definition parameters

  1. Open the Amazon ECS console at https://console.aws.amazon.com/ecs/.

  2. On the navigation bar, select the region that your cluster is in.

  3. In the navigation pane, choose Task Definitions and select the task definition from which to create your service.

  4. On the Task Definition name page, select the revision of the task definition from which to create your service.

  5. Review the task definition, and choose Create Service.

  6. On the Create Service page, for Cluster, select the cluster in which to create your service. For Service name, type a unique name for your service. For Number of tasks, type the number of tasks to launch and maintain on your cluster. If your task definition uses static host port mappings on your container instances, then you need at least one container instance with the specified port available in your cluster for each task in your service. This restriction does not apply if your task definition uses dynamic host port mappings. For more information, see portMappings.

  7. (Optional) You can specify deployment parameters that control how many tasks run during the deployment and the ordering of stopping and starting tasks.

    • Minimum healthy percent: Specify a lower limit on the number of your service's tasks that must remain in the RUNNING state during a deployment, as a percentage of the service's desired number of tasks (rounded up to the nearest integer). For example, if your service has a desired number of four tasks and a minimum healthy percent of 50%, the scheduler may stop two existing tasks to free up cluster capacity before starting two new tasks. Tasks for services that do not use a load balancer are considered healthy if they are in the RUNNING state; tasks for services that do use a load balancer are considered healthy if they are in the RUNNING state and the container instance it is hosted on is reported as healthy by the load balancer. The default value for minimum healthy percent is 50% in the console, and 100% with the AWS CLI or SDKs.

    • Maximum percent: Specify an upper limit on the number of your service's tasks that are allowed in the RUNNING or PENDING state during a deployment, as a percentage of the service's desired number of tasks (rounded down to the nearest integer). For example, if your service has a desired number of four tasks and a maximum percent value of 200%, the scheduler may start four new tasks before stopping the four older tasks (provided that the cluster resources required to do this are available). The default value for maximum percent is 200%.

  8. (Optional) For Task Placement, you can specify how tasks are placed using task placement strategies and constraints. Choose from the following options:

    • AZ Balanced Spread - distribute tasks across Availability Zones and across container instances in the Availability Zone.

    • AZ Balanced BinPack - distribute tasks across Availability Zones and across container instances with the least available memory.

    • BinPack - distribute tasks based on the least available amount of CPU or memory.

    • One Task Per Host - place, at most, one task from the service on each container instance.

    • Custom - define your own task placement strategy. See Amazon ECS Task Placement for examples.

    For more information, see Amazon ECS Task Placement.

(Optional) Configuring Your Service to Use a Load Balancer

If you have an available Elastic Load Balancing load balancer configured, you can attach it to your service with the following procedures, or you can configure a new load balancer. For more information see Creating a Load Balancer.

Note

You must create your Elastic Load Balancing load balancer resources prior to following these procedures.

First, you must choose the load balancer type to use with your service. Then you can configure your service to work with the load balancer.

To choose a load balancer type

  1. If you have not done so already, follow the basic service creation procedures in Configuring Basic Service Parameters.

  2. On the Create Service page, choose Configure ELB.

  3. Choose the load balancer type to use with your service:

    Application Load Balancer

    Allows containers to use dynamic host port mapping, which enables you to place multiple tasks using the same port on a single container instance. Multiple services can use the same listener port on a single load balancer with rule-based routing and paths.

    Network Load Balancer

    Allows containers to use dynamic host port mapping, which enables you to place multiple tasks using the same port on a single container instance. Multiple services can use the same listener port on a single load balancer with rule-based routing.

    Classic Load Balancer

    Requires static host port mappings (only one task allowed per container instance); rule-based routing and paths are not supported.

    We recommend that you use Application Load Balancers for your Amazon ECS services so that you can take advantage of the advanced features available to them.

  4. For Select IAM role for service, choose Create new role to create a new role for your service, or select an existing IAM role to use for your service (by default, this is ecsServiceRole).

    Important

    If you choose to use an existing ecsServiceRole IAM role, you must verify that the role has the proper permissions to use Application Load Balancers and Classic Load Balancers, as shown in Amazon ECS Service Scheduler IAM Role.

  5. For ELB Name, choose the name of the load balancer to use with your service. Only load balancers that correspond to the load balancer type you selected earlier are visible here.

  6. The next step depends on the load balancer type for your service. If you've chosen an Application Load Balancer, follow the steps in To configure an Application Load Balancer. If you've chosen an Network Load Balancer, follow the steps in To configure an Network Load Balancer. If you've chosen a Classic Load Balancer, follow the steps in To configure a Classic Load Balancer.

To configure an Application Load Balancer

  1. For Select a Container, choose the container and port combination from your task definition that your load balancer should distribute traffic to, and choose Add to ELB.

  2. For Listener port, choose the listener port and protocol of the listener that you created in Creating an Application Load Balancer (if applicable), or choose create new to create a new listener and then enter a port number and choose a port protocol in Listener protocol.

  3. For Target group name, choose the target group that you created in Creating an Application Load Balancer (if applicable), or choose create new to create a new target group.

  4. (Optional) If you chose to create a new target group, complete the following fields as follows:

    • For Target group name, enter a name for your target group.

    • For Target group protocol, enter the protocol to use for routing traffic to your tasks.

    • For Path pattern, if your listener does not have any existing rules, the default path pattern (/) is used. If your listener already has a default rule, then you must enter a path pattern that matches traffic that you want to have sent to your service's target group. For example, if your service is a web application called web-app, and you want traffic that matches http://my-elb-url/web-app to route to your service, then you would enter /web-app* as your path pattern. For more information, see ListenerRules in the User Guide for Application Load Balancers.

    • For Health check path, enter the path to which the load balancer should send health check pings.

  5. When you are finished configuring your Application Load Balancer, choose Save to save your configuration and proceed to Review and Create Your Service.

To configure an Network Load Balancer

  1. For Select a Container, choose the container and port combination from your task definition that your load balancer should distribute traffic to, and choose Add to ELB.

  2. For Listener port, choose the listener port and protocol of the listener that you created in Creating an Application Load Balancer (if applicable), or choose create new to create a new listener and then enter a port number and choose a port protocol in Listener protocol.

  3. For Target group name, choose the target group that you created in Creating an Application Load Balancer (if applicable), or choose create new to create a new target group.

  4. (Optional) If you chose to create a new target group, complete the following fields as follows:

    • For Target group name, enter a name for your target group.

    • For Target group protocol, enter the protocol to use for routing traffic to your tasks.

    • For Path pattern, if your listener does not have any existing rules, the default path pattern (/) is used. If your listener already has a default rule, then you must enter a path pattern that matches traffic that you want to have sent to your service's target group. For example, if your service is a web application called web-app, and you want traffic that matches http://my-elb-url/web-app to route to your service, then you would enter /web-app* as your path pattern. For more information, see ListenerRules in the User Guide for Application Load Balancers.

    • For Health check path, enter the path to which the load balancer should send health check pings.

  5. When you are finished configuring your Network Load Balancer, choose Save to save your configuration and proceed to Review and Create Your Service.

To configure a Classic Load Balancer

  1. The Health check port, Health check protocol, and Health check path fields are all pre-populated with the values you configured in Creating a Classic Load Balancer (if applicable). You can update these settings in the Amazon EC2 console.

  2. For Container for ELB health check, choose the container to send health checks.

  3. When you are finished configuring your Classic Load Balancer, choose Save to save your configuration and proceed to Review and Create Your Service.

(Optional) Configuring Your Service to Use Service Auto Scaling

Your Amazon ECS service can optionally be configured to use Auto Scaling to adjust its desired count up or down in response to CloudWatch alarms. For more information see Service Auto Scaling.

To configure basic Service Auto Scaling parameters

  1. If you have not done so already, follow the basic service creation procedures in Configuring Basic Service Parameters.

  2. On the Create Service page, choose Configure Service Auto Scaling.

  3. On the Service Auto Scaling page, select Configure Service Auto Scaling to adjust your service’s desired count.

  4. For Minimum number of tasks, enter the lower limit of the number of tasks for Service Auto Scaling to use. Your service's desired count will not be automatically adjusted below this amount.

  5. For Desired number of tasks, this field is pre-populated with the value you entered earlier. You can change your service's desired count at this time, but this value must be between the minimum and maximum number of tasks specified on this page.

  6. For Maximum number of tasks, enter the upper limit of the number of tasks for Service Auto Scaling to use. Your service's desired count will not be automatically adjusted above this amount.

  7. For IAM role for Service Auto Scaling, choose an IAM role to authorize the Application Auto Scaling service to adjust your service's desired count on your behalf. If you have not previously created such a role, choose Create new role and the role will be created for you. For future reference, the role that is created for you is called ecsAutoscaleRole. For more information, see Amazon ECS Service Auto Scaling IAM Role.

To configure scaling policies for your service

These steps will help you create scaling policies and CloudWatch alarms that can be used to trigger scaling activities for your service. You can create a Scale out alarm to increase the desired count of your service, and a Scale in alarm to decrease the desired count of your service.

  1. For Policy name, enter a descriptive name for your policy, or use the default policy name that is already entered.

  2. For Execute policy when, select the CloudWatch alarm that you want to use to scale your service up or down.

    You can use an existing CloudWatch alarm that you have previously created, or you can choose to create a new alarm. The Create new alarm workflow allows you to create CloudWatch alarms that are based on the CPUUtilization and MemoryUtilization of the service that you are creating. To use other metrics, you can create your alarm in the CloudWatch console and then return to this wizard to choose that alarm.

  3. (Optional) If you've chosen to create a new alarm, complete the following steps.

    1. For Alarm name, enter a descriptive name for your alarm. For example, if your alarm should trigger when your service CPU utilization exceeds 75%, you could call the alarm service_name-cpu-gt-75.

    2. For ECS service metric, choose the service metric to use for your alarm. For more information about these service utilization metrics, see Service Utilization.

    3. For Alarm threshold, enter the following information to configure your alarm:

      • Choose the CloudWatch statistic for your alarm (the default value of Average works in many cases). For more information, see Statistics in the Amazon CloudWatch User Guide.

      • Choose the comparison operator for your alarm and enter the value that the comparison operator checks against (for example, > and 75).

      • Enter the number of consecutive periods before the alarm is triggered and the period length. For example, a 2 consecutive periods of 5 minutes would take 10 minutes before the alarm triggered. Because your Amazon ECS tasks can scale up and down quickly, you should consider using a low number of consecutive periods and a short period duration to react to alarms as soon as possible.

    4. Choose Save to save your alarm.

  4. For Scaling action, enter the following information to configure how your service responds to the alarm:

    • Choose whether to add to, subtract from, or set a specific desired count for your service.

    • If you chose to add or subtract tasks, enter the number of tasks (or percent of existing tasks) to add or subtract when the scaling action is triggered. If you chose to set the desired count, enter the desired count that your service should be set to when the scaling action is triggered.

    • (Optional) If you chose to add or subtract tasks, choose whether the previous value is used as an integer or a percent value of the existing desired count.

    • Enter the lower boundary of your step scaling adjustment. By default, for your first scaling action, this value is the metric amount where your alarm is triggered. For example, the following scaling action adds 100% of the existing desired count when the CPU utilization is greater than 75%.

      
                                    Scaling activity example
  5. (Optional) You can repeat Step 4 to configure multiple scaling actions for a single alarm (for example, to add 1 task if CPU utilization is between 75-85%, and to add 2 tasks if CPU utilization is greater than 85%).

  6. (Optional) If you chose to add or subtract a percentage of the existing desired count, enter a minimum increment value for Add tasks in increments of N task(s).

  7. For Cooldown period, enter the number of seconds between scaling actions.

  8. Repeat Step 1 through Step 7 for the Scale in policy and choose Save to save your Service Auto Scaling configuration.

Review and Create Your Service

After you have configured your basic service definition parameters and optionally configured your service to use a load balancer, you can review your configuration and then choose Create Service to finish creating your service.

Note

After you create a service, the target group ARN or load balancer name, container name, and container port specified in the service definition are immutable. You cannot add, remove, or change the load balancer configuration of an existing service. If you update the task definition for the service, the container name and container port that were specified when the service was created must remain in the task definition.