AWS Documentation » Amazon ECS » Developer Guide » Using the Amazon ECS Command Line Interface » Amazon ECS Command Line Reference » ecs-cli compose service » ecs-cli compose service up

ecs-cli compose service up

Creates an Amazon ECS service from your compose file (if it does not already exist) and runs one instance of that task on your cluster (a combination of the create and start commands). This command updates the desired count of the service to 1.

Syntax

ecs-cli compose service up [--deployment-max-percent n] [--deployment-min-healthy-percent n] [--load-balancer-name value|--target-group-arn value] [--container-name value] [--container-port value] [--role value] [--health-check-grace-period integer] [--timeout value] [--launch-type launch_type] [--create-log-groups] [--force-deployment] [--enable-service-discovery] [--vpc value] [--private-dns-namespace value] [--private-dns-namespace-id value] [--public-dns-namespace value] [--public-dns-namespace-id value] [--sd-container-name value] [--sd-container-port value] [--dns-ttl value] [--dns-type value] [--healthcheck-custom-config-failure-threshold value] [--update-service-discovery] [--help]

Options

Name	Description
--deployment-max-percent	Specifies the upper limit (as a percentage of the service's desiredCount) of the number of running tasks that can be running in a service during a deployment. For more information, see maximumPercent. Default value: 200 Required: No
--deployment-min-healthy-percent	Specifies the lower limit (as a percentage of the service's desiredCount) of the number of running tasks that must remain running and healthy in a service during a deployment. For more information, see minimumHealthyPercent. Default value: 100 Required: No
--target-group-arn	Specifies the full Amazon Resource Name (ARN) of a previously configured Elastic Load Balancing target group to associate with your service. Required: No
--container-name	Specifies the container name (as it appears in a container definition). This parameter is required if a load balancer or target group is specified. Required: No, unless a load balancer or target group is specified.
--container-port	Specifies the port on the container to associate with the load balancer. This port must correspond to a containerPort in the service's task definition. This parameter is required if a load balancer or target group is specified. Required: No, unless a load balancer or target group is specified.
--load-balancer-name	Specifies the name of a previously configured Elastic Load Balancing load balancer to associate with your service. Required: No
--role	Specifies the name or full Amazon Resource Name (ARN) of the IAM role that allows Amazon ECS to make calls to your load balancer or target group on your behalf. This parameter is required if you are using a load balancer or target group with your service. If you specify the role parameter, you must also specify a load balancer name or target group ARN, along with a container name and container port. Required: No, unless a load balancer or target group is specified.
--health-check-grace-period	Specifies the period of time, in seconds, that the Amazon ECS service scheduler should ignore unhealthy Elastic Load Balancing target health checks after a task has first started. Required: No
--create-log-groups	Creates the CloudWatch log groups specified in your compose files. Required: No
--enable-service-discovery	Specifies whether to enable service discovery for this service. Required: No
--vpc	Specifies the VPC that will be attached to the private DNS namespace for service discovery. This parameter is required if --private-dns-namespace is specified. Required: No
--private-dns-namespace	Specifies the name of the private DNS namespace to use with service discovery. The ECS CLI automatically creates the namespace if it does not exist. For example, if the namespace is corp, then a service named foo is reachable via DNS at foo.corp. If this parameter is used, you must also specify a VPC using the --vpc parameter. Required: No
--private-dns-namespace-id	Specifies the ID of an existing private DNS namespace to use with service discovery. If this parameter is used, you cannot specify either --private-dns-namespace or --vpc. Required: No
--public-dns-namespace	Specifies the name of the public DNS namespace to use with service discovery. For example, if the namespace is corp, then a service named foo is reachable via DNS at foo.corp. Required: No
--public-dns-namespace-id	Specifies the ID of an existing public DNS namespace to use with service discovery. If this parameter is used, you cannot specify a --public-dns-namespace. Required: No
--sd-container-name	Specifies the name of the container, which is referred to as a service in your Docker compose file. For more information, see Service configuration reference. This parameter is required if you are using SRV records. Required: No, unless SRV DNS records are being used.
--sd-container-port	Specifies the port on the container that will be used for service discovery. This parameter is required if you are using SRV records. Required: No, unless SRV DNS records are being used.
--dns-ttl	Specifies the amount of time, in seconds, that you want DNS resolvers to cache the settings for the DNS records used for service discovery. Default value: 60 Required: No
--dns-type	Specifies the type of DNS record used for service discovery. Accepted values are A or SRV. If your task uses either the bridge or host network modes, then SRV records are required. If your task uses the awsvpc network mode then A records are the default. Required: No
--healthcheck-custom-config-failure-threshold	Specifies the number of 30-second intervals that you want the service discovery service to wait after receiving an UpdateInstanceCustomHealthStatus request before it changes the health status. Default value: 1 Required: No
--update-service-discovery	If specified, this allows the service discovery service settings for --dns-ttl and --healthcheck-custom-config-failure-threshold to be updated. Required: No
--region, -r region	Specifies the AWS Region to use. Defaults to the cluster configured using the configure command. Type: String Required: No
--cluster-config cluster_config_name	Specifies the name of the Amazon ECS cluster configuration to use. Defaults to the cluster configuration set as the default. Type: String Required: No
--ecs-profile ecs_profile	Specifies the name of the Amazon ECS profile configuration to use. Defaults to the profile configured using the configure profile command. Type: String Required: No
--aws-profile aws_profile	Specifies the AWS profile to use. Enables you to use the AWS credentials from an existing named profile in ~/.aws/credentials. Type: String Required: No
--cluster, -c cluster_name	Specifies the Amazon ECS cluster name to use. Defaults to the cluster configured using the configure command. Type: String Required: No
--help, -h	Shows the help text for the specified command. Required: No

Using a Load Balancer

You can optionally run your service behind a load balancer. The load balancer distributes traffic across the tasks that are associated with the service. For more information, see Service Load Balancing. After you create a service, the load balancer name or target group ARN, container name, and container port specified in the service definition are immutable.

Note

You must create your load balancer resources before you can configure a service to use them. Your load balancer resources should reside in the same VPC as your container instances and they should be configured to use the same subnets. You must also add a security group rule to your container instance security group that allows inbound traffic from your load balancer. For more information, see Creating a Load Balancer.

• To configure your service to use an existing Elastic Load Balancing Classic Load Balancer, you must specify the load balancer name, the container name (as it appears in a container definition), and the container port to access from the load balancer. When a task from this service is placed on a container instance, the container instance is registered with the load balancer specified here.

• To configure your service to use an existing Elastic Load Balancing Application Load Balancer, you must specify the load balancer target group ARN, the container name (as it appears in a container definition), and the container port to access from the load balancer. When a task from this service is placed on a container instance, the container instance and port combination is registered as a target in the target group specified here.

The --health-check-grace-period option specifies the period of time, in seconds, that the Amazon ECS service scheduler should ignore unhealthy Elastic Load Balancing target health checks after a task has first started. This is only valid if your service is configured to use a load balancer. If your tasks take a while to start and respond to ELB health checks, you can specify a health check grace period of up to 1,800 seconds during which the ECS service scheduler ignores the Elastic Load Balancing health check status. This grace period can prevent the Amazon ECS service scheduler from marking tasks as unhealthy and stopping them before they have time to come up.

Using Service Discovery

Your Amazon ECS service can optionally be configured to use Amazon ECS Service Discovery. Service discovery uses Amazon Route 53 auto naming API actions to manage DNS entries for your service's tasks, making them discoverable within your VPC. For more information, see Tutorial: Creating an Amazon ECS Service That Uses Service Discovery Using the Amazon ECS CLI.

Examples

Example 1

This example brings up an Amazon ECS service with the project name hello-world from the hello-world.yml compose file.

ecs-cli compose --project-name hello-world --file hello-world.yml service up

Output:

INFO[0000] Using ECS task definition                     TaskDefinition="ecscompose-hello-world:7"
INFO[0000] Created an ECS service                        service=ecscompose-service-hello-world taskDefinition="ecscompose-hello-world:7"
INFO[0000] Updated ECS service successfully              desiredCount=1 serviceName=ecscompose-service-hello-world
INFO[0015] (service ecscompose-service-hello-world) has started 1 tasks: (task 682dc22f-8bfa-4c28-b6f8-3a916bd8f86a).  timestamp=2017-08-18 21:16:00 +0000 UTC
INFO[0060] Service status                                desiredCount=1 runningCount=1 serviceName=ecscompose-service-hello-world
INFO[0060] ECS Service has reached a stable state        desiredCount=1 runningCount=1 serviceName=ecscompose-service-hello-world

Example 2

This example creates a service from the nginx-compose.yml compose file and configures it to use an existing Application Load Balancer.

ecs-cli compose -f nginx-compose.yml service up --target-group-arn arn:aws:elasticloadbalancing:us-east-1:aws_account_id:targetgroup/ecs-cli-alb/9856106fcc5d4be8 --container-name nginx --container-port 80 --role ecsServiceRole

Example 3

This example creates a service from the nginx-compose.yml compose file and configures it to use an existing Application Load Balancer with a health check grace period of 25 seconds.

ecs-cli compose -f nginx-compose.yml service up --target-group-arn arn:aws:elasticloadbalancing:us-east-1:aws_account_id:targetgroup/ecs-cli-alb/9856106fcc5d4be8 --container-name nginx --container-port 80 --role ecsServiceRole --health-check-grace-period 25