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] [--scheduling-strategy value] [--tags key1=value1,key2=value2] [--disable-ecs-managed-tags] [--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're 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 Amazon ECS CLI automatically creates the namespace if it doesn't exist. For example, if the namespace is corp, a service named foo is reachable via DNS at foo.corp. If you use this parameter, 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 you use this parameter, you can't 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, 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 you use this parameter, you can't 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're 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're 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, SRV records are required. If your task uses the awsvpc network mode, 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 enables the service discovery service settings for --dns-ttl and --healthcheck-custom-config-failure-threshold to be updated. Required: No
--scheduling-strategy value	Specifies the scheduling strategy to use for the service. There are two service scheduler strategies available: REPLICA—The replica scheduling strategy places and maintains the desired number of tasks across your cluster. By default, the service scheduler spreads tasks across Availability Zones. You can use task placement strategies and constraints to customize task placement decisions. For more information, see Replica. DAEMON—The daemon scheduling strategy deploys exactly one task on each active container instance that meets all of the task placement constraints that you specify in your cluster. When using this strategy, there is no need to specify a desired number of tasks, a task placement strategy, or use Service Auto Scaling policies. For more information, see Daemon. Note Fargate tasks do not support the DAEMON scheduling strategy. For more information, see Service Scheduler Concepts. Type: String Valid values: REPLICA | DAEMON Default value: REPLICA Required: No
--tags key1=value1,key2=value2	Specifies the metadata to apply to your AWS resources. Each tag consists of a key and an optional value. Tags use the following format: key1=value1,key2=value2,key3=value3. Amazon ECS managed tags are enabled by default if you have opted in to the new Amazon Resource Name (ARN) and resource identifier (ID) formats unless you specifically disable them using the --disable-ecs-managed-tags flag. For more information, see Tagging Resources. Type: Key value pairs Required: No
--disable-ecs-managed-tags	Disable the Amazon ECS managed tags. For more information, see Tagging Your Resources for Billing. 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, you can't change the load balancer name or target group ARN, container name, and container port specified in the service definition.

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 valid only if your service is configured to use a load balancer. If your tasks take a while to start and respond to Elastic Load Balancing health checks, you can specify a health check grace period of up to 1,800 seconds during which the Amazon 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.

Tagging Resources

The Amazon ECS CLI supports adding metadata in the form of resource tags to your AWS resources. Each tag consists of a key and an optional value. Resource tags can be used for cost allocation, automation, and access control. For more information, see AWS Tagging Strategies.

When using the ecs-cli compose service up command, using the --tags flag allows you to add metadata tags to the task definition and service. The tags will be added to the service and task definition when the resources are created. The tags will be propogated from your task definition to tasks created by the service. Amazon ECS managed tags are enabled by default if you have opted in to the new Amazon Resource Name (ARN) and resource identifier (ID) formats unless you specifically disable them using the --disable-ecs-managed-tags flag. For more information, see Tagging Your Resources for Billing.

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