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] [--target-groups "targetGroupArn=arn:elasticloadbalancing:region:aws_account_id:
targetgroup/target_group_name_1,containerName=container_name,containerPort=container_port"]
[--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 (p. 567).
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 (p. 568).
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.
Deprecated, use target-groups.
Required: No
Amazon ECS command line reference
Name Description
--target-groups Specifies one or more target groups to be registered with the service. Specify the Amazon Resource Name (ARN) of the target group, the container name and the container port for each group to register. A single --target-groups flag specifies only one target group. Add additional --target-groups flags to add additional target groups.
You use a target group to configure where aload balancer direct traffic to, for example Amazon EC2 instances. When you create a load balancer, you create one or more listeners and configure listener rules to direct the traffic to one target group.
Type: Strings
For more information see Registering multiple target groups with a service (p. 621).
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.
Deprecated, use target-groups.
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.
Deprecated, use target-groups.
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.
Deprecated, use target-groups.
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
Amazon ECS command line reference
Name Description
--create-log-groups Creates the CloudWatch log groups specified in your Compose files.
Required: No
--force-deployment Forces a new deployment of the service.
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.
Amazon ECS command line reference
Name Description
--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
Amazon ECS command line reference
Name Description
--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 (p. 563).
• 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.
The service scheduler evaluates the task placement constraints for running tasks and will stop tasks that do not meet the placement constraints. 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 (p. 562).
NoteFargate tasks do not support the DAEMON scheduling strategy.
For more information, see Service scheduler concepts (p. 561).
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 (p. 131).
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 (p. 638).
Required: No
Amazon ECS command line reference
Name Description
--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 (p. 606). 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.
NoteYou 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 (p. 611).
• 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
Amazon ECS command line reference
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 (p. 71).
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 Tagging your Amazon ECS resources (p. 636).
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 (p. 638).
Examples Example 1
This example brings up an Amazon ECS service with the project name 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-service=ecscompose-service-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
Amazon ECS command line reference
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