ecs-cli compose service up - Amazon Elastic Container Service
SyntaxOptionsUsing a Load BalancerUsing Service DiscoveryTagging ResourcesExamples

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] [--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.

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.

Deprecated, use target-groups.

Required: No

--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 --targetgroups flag specifies only one target group. Add additional --target-groups flags to add additional target groups.

Type: Strings

For more information see Registering multiple target groups with a 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.

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

--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.

--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. 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.

    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 Tagging Your Amazon ECS Resources.

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