ecs-cli up
Creates the Amazon ECS cluster (if it does not already exist) and the AWS resources required to set up the cluster.
This command creates a new AWS CloudFormation stack called
amazon-ecs-cli-setup-
. You can
view the progress of the stack creation in the AWS Management Console. cluster_name
Some features described might only be available with the latest version of the Amazon ECS CLI. For more information about obtaining the latest version, see Installing the Amazon ECS CLI.
Syntax
ecs-cli up [--capability-iam |
--instance-role
] [--keypair
instance-profile-name
keypair_name
] [--size
] [n
--azs
]
[--security-group
availability_zone_1,availability_zone_2
security_group_id
[,security_group_id
[,...]]]
[--cidr
] [ip_range
--port
] [port_number
--subnets
] [subnet_1,subnet_2
--vpc
] [--extra-user-data
vpc_id
string
] [--instance-type
instance_type
] [--image-id
ami_id
] [--launch-type
launch_type
] [--no-associate-public-ip-address]
[--force] [--tags key1=value1,key2=value2
] [--cluster
cluster_name
] [--region
region
] [--empty] [--verbose] [--help]
Options
Name |
Description |
---|---|
|
Acknowledges that this command may create IAM resources. This parameter is only supported with tasks that use the EC2 launch type. This parameter is required if you do not specify and instance
profile name with Required: No |
|
Specifies the name of an existing Amazon EC2 key pair to enable SSH access to the EC2 instances in your cluster. This parameter is only supported with tasks that use the EC2 launch type. For more information about creating a key pair, see Setting Up with Amazon EC2 in the Amazon EC2 User Guide for Linux Instances. Type: String Required: No |
|
Specifies the number of instances to launch and register to the cluster. This parameter is only supported with tasks that use the EC2 launch type. Type: Integer Default: 1 Required: No |
|
Specifies a comma-separated list of two VPC Availability Zones in
which to create subnets (these zones must have the
Leaving this option blank can result in a failure to launch container instances when the randomly chosen zone is unavailable. Type: String Required: No |
|
Specifies a comma-separated list of existing security groups to associate with your container instances. If you do not specify a security group here, then a new one is created. For more information, see Security Groups in the Amazon EC2 User Guide for Linux Instances. Required: No |
|
Specifies a CIDR/IP range for the security group to use for container instances in your cluster. This parameter is ignored if an existing security group is
specified with the Type: CIDR/IP range Default: Required: No |
|
Specifies a port to open on the security group to use for container instances in your cluster. This parameter is ignored if an existing security group is
specified with the Type: Integer Default: Required: No |
|
Specifies a comma-separated list of existing VPC subnet IDs in which to launch your container instances. Type: String Required: This option is required if you specify a VPC with the
|
|
Specifies the ID of an existing VPC in which to launch your
container instances. If you specify a VPC ID, you must specify a
list of existing subnets in that VPC with the Type: String Required: No |
|
Specifies additional user data for your container instance. Files can be shell scripts or cloud-init directives. They are packaged into a MIME multipart archive along with user data provided by the Amazon ECS CLI that directs instances to join your cluster. For more information, see Specifying User Data. Type: String Required: No |
|
Specifies the Amazon EC2 instance type for your container instances. If
you specify an A1 instance type, for example This parameter is supported only with tasks that use the EC2 launch type. For more information on EC2 instance types, see Amazon EC2
Instances Type: String Default: Required: No |
|
Specifies the Amazon EC2 AMI ID to use for your container instances. If you don't specify an AMI ID, the Amazon ECS CLI automatically retrieves the latest stable Amazon ECS-optimized Amazon Linux 2 AMI by querying the Systems Manager Parameter Store API during the cluster resource creation process. This requires the user account that you're using to have the required Systems Manager permissions. For more information, see Retrieving Amazon ECS-Optimized AMI metadata. If you specify an A1 instance type for the
This parameter is supported only with tasks that use the EC2 launch type. Type: String Default: The latest stable Amazon ECS–optimized AMI for the specified Region. Required: No |
|
Do not assign public IP addresses to new instances in this VPC. Unless this option is specified, new instances in this VPC receive an automatically assigned public IP address. This parameter is only supported with tasks that use the EC2 launch type. Required: No |
|
Forces the recreation of any existing resources that match your current configuration. This option is useful for cleaning up stale resources from previous failed attempts. 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 |
|
Specifies a custom IAM role name for instances in your cluster. A new instance profile will be created and attached to this role. This parameter is only supported with tasks that use the EC2 launch type. This parameter is required if you do not specify the
Required: No |
|
Specifies the launch type to use. Available options are
This overrides the default launch type stored in your cluster configuration. Type: String Required: No |
|
Turn on debug logging. This provides a more verbose command output to aid in diagnosing issues. 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 |
|
Specifies that an ECS cluster is created with no resources. If other flags are also specified that would create resources, they are ignored and a warning is displayed. Required: No |
|
Shows the help text for the specified command. Required: No |
Specifying User Data
When launching tasks that use the EC2 launch type, the ECS CLI always creates container instances that include the following user data:
#!/bin/bash
echo ECS_CLUSTER={ clusterName } >> /etc/ecs/ecs.config
This user data directs the container instance to join your ECS cluster. You can
optionally include additional user data using the --extra-user-data
flag.
The flag can be specified multiple times. For example, extra user data can be shell
scripts or cloud-init directives. For more information, see Running Commands on Your Linux Instance at
Launch in the Amazon EC2 User Guide for Linux Instances.
The Amazon ECS CLI takes the user data and packs it into a MIME multipart archive, which
can be used by cloud-init on the container instance. The Amazon ECS CLI allows existing MIME
multipart archives to be passed in with --extra-user-data
. The Amazon ECS CLI
unpacks the existing archive, and then repack it into the final archive (preserving all
header and content type information). The following is an example:
ecs-cli up \ --capability-iam \ --extra-user-data
my-shellscript
\ --extra-user-datamy-cloud-boot-hook
\ --extra-user-datamy-mime-multipart-archive
\ --launch-type EC2
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.
If you specify resource tags when using the ecs-cli up command, the Amazon ECS cluster as well as the following resources created by the AWS CloudFormation stack can be tagged:
-
Container instances
Note In order for your container instances to allow tags, you need to opt in to the new Amazon ECS resource ARN formats. For more information, see Amazon Resource Names (ARNs) and IDs.
-
VPC
-
Subnets
-
Internet gateway
-
Route tables
-
Security group
-
Autoscaling group
For the autoscaling group, the ECS CLI adds a Name
tag whose value is
the ECS Instance - <CloudFormation stack name>
, which is propagated
to your container instances. You can override this behavior by specifying your own
Name
tag.
Examples
Creating a Cluster for Tasks Using the EC2 Launch Type
This example brings up a cluster of four c4.large
container instances
and configures them to use the EC2 key pair called id_rsa
.
ecs-cli up --keypair
id_rsa
--capability-iam --size4
--instance-typec4.large
--launch-typeEC2
Output:
INFO[0001] Using recommended Amazon Linux AMI with ECS Agent 1.17.3 and Docker version 17.12.1-ce INFO[0000] Created cluster cluster=ecs-cli-ec2-demo INFO[0000] Waiting for your cluster resources to be created INFO[0001] Cloudformation stack status stackStatus=CREATE_IN_PROGRESS INFO[0061] Cloudformation stack status stackStatus=CREATE_IN_PROGRESS INFO[0121] Cloudformation stack status stackStatus=CREATE_IN_PROGRESS INFO[0181] Cloudformation stack status stackStatus=CREATE_IN_PROGRESS Cluster creation succeeded. VPC created: vpc-abcd1234 Security Group created: sg-abcd1234 Subnets created: subnet-abcd1234 Subnets created: subnet-dcba4321
Creating a Cluster with Container Instances That Use the Amazon ECS-optimized Amazon Linux 2 (arm64) AMI
This example brings up a cluster of one a1.medium
container instances
which will use the Amazon ECS-optimized Amazon Linux 2 (arm64) AMI.
ecs-cli up --capability-iam --instance-type
a1.medium
--launch-typeEC2
--regionus-east-2
Output:
WARN[0000] You will not be able to SSH into your EC2 instances without a key pair. INFO[0000] Using Arm ecs-optimized AMI because instance type was a1.medium INFO[0001] Using recommended Amazon Linux 2 AMI with ECS Agent 1.25.3 and Docker version 18.06.1-ce INFO[0000] Created cluster cluster=ecs-cli-ec2-demo INFO[0000] Waiting for your cluster resources to be created INFO[0001] Cloudformation stack status stackStatus=CREATE_IN_PROGRESS INFO[0061] Cloudformation stack status stackStatus=CREATE_IN_PROGRESS INFO[0121] Cloudformation stack status stackStatus=CREATE_IN_PROGRESS INFO[0181] Cloudformation stack status stackStatus=CREATE_IN_PROGRESS Cluster creation succeeded. VPC created: vpc-abcd1234 Security Group created: sg-abcd1234 Subnets created: subnet-abcd1234 Subnets created: subnet-dcba4321
Creating a Cluster for Tasks Using the Fargate Launch Type
This example brings up a cluster for your Fargate tasks and creates a new VPC with two subnets.
ecs-cli up --launch-type
FARGATE
Output:
INFO[0001] Created cluster cluster=ecs-cli-fargate-demo region=us-west-2 INFO[0003] Waiting for your cluster resources to be created... INFO[0003] Cloudformation stack status stackStatus="CREATE_IN_PROGRESS" INFO[0066] Waiting for your cluster resources to be created... INFO[0066] Cloudformation stack status stackStatus="CREATE_IN_PROGRESS" VPC created: vpc-abcd1234 Subnets created: subnet-abcd1234 Subnets created: subnet-dcba4321 Cluster creation succeeded.
Creating an Empty Cluster
This example brings up an empty cluster named ecs-cli-empty-demo
with
no resources.
ecs-cli up --empty --cluster
ecs-cli-empty-demo
Output:
INFO[0000] Created cluster cluster=ecs-cli-empty-demo region=us-east-1 Cluster creation succeeded.