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 |
---|---|
|
Specifies the upper limit (as a percentage of the service's
Default value: Required: No |
|
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: Required: No |
|
Specifies the full Amazon Resource Name (ARN) of a previously configured Elastic Load Balancing target group to associate with your service. Deprecated, use Required: No |
|
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 Type: Strings For more information see Registering multiple target groups with a service. Required: No |
|
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 Required: No, unless a load balancer or target group is specified. |
|
Specifies the port on the container to associate with the load
balancer. This port must correspond to a Deprecated, use Required: No, unless a load balancer or target group is specified. |
|
Specifies the name of a previously configured Elastic Load Balancing load balancer to associate with your service. Deprecated, use Required: No |
|
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. |
|
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 |
|
Creates the CloudWatch log groups specified in your Compose files. Required: No |
|
Forces a new deployment of the service. Required: No |
|
Specifies whether to enable service discovery for this service. Required: No |
|
Specifies the VPC that will be attached to the private DNS
namespace for service discovery. This parameter is required if
Required: No |
|
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
Required: No |
|
Specifies the ID of an existing private DNS namespace to use
with service discovery. If you use this parameter, you can't
specify either Required: No |
|
Specifies the name of the public DNS namespace to use with
service discovery. For example, if the namespace is
Required: No |
|
Specifies the ID of an existing public DNS namespace to use
with service discovery. If you use this parameter, you can't
specify a Required: No |
|
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 Required: No, unless SRV DNS records are being used. |
|
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. |
|
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: Required: No |
|
Specifies the type of DNS record used for service discovery. Accepted values are
Required: No |
|
Specifies the number of 30-second intervals that you want the
service discovery service to wait after receiving an
Default value: Required: No |
|
If specified, this enables the service discovery service
settings for Required: No |
|
Specifies the scheduling strategy to use for the service. There are two service scheduler strategies available:
For more information, see Service scheduler concepts. Type: String Valid values: Default value: Required: No |
|
Specifies the metadata to apply to your AWS resources. Each
tag consists of a key and an optional value. Tags use the
following format:
Type: Key value pairs Required: No |
|
Disable the Amazon ECS managed tags. For more information, see Tagging your resources for billing. Required: No |
|
Specifies the AWS Region to use. Defaults to the cluster configured using the configure command. Type: String Required: No |
|
Specifies the name of the Amazon ECS cluster configuration to use. Defaults to the cluster configuration set as the default. Type: String Required: No |
|
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 |
|
Specifies the AWS profile to use. Enables you to use the AWS credentials from an existing
named profile in Type: String Required: No |
|
Specifies the Amazon ECS cluster name to use. Defaults to the cluster configured using the configure command. Type: String Required: No |
|
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.
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
--filehello-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-namenginx
--container-port80
--roleecsServiceRole
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-namenginx
--container-port80
--roleecsServiceRole
--health-check-grace-period25