Configuring the Amazon ECS CLI
The Amazon ECS CLI requires some basic configuration information before you can use
it,
such as your AWS credentials, the AWS Region in which to create your cluster, and
the name of the Amazon ECS cluster to use. Configuration information is stored in
the
~/.ecs
directory on macOS and Linux systems and in
C:\Users\
on Windows systems.
<username>
\AppData\local\ecs
To configure the Amazon ECS CLI
-
Set up a CLI profile with the following command, substituting
with your desired profile name,profile_name
and$AWS_ACCESS_KEY_ID
environment variables with your AWS credentials.$AWS_SECRET_ACCESS_KEY
ecs-cli configure profile --profile-name
profile_name
--access-key$AWS_ACCESS_KEY_ID
--secret-key$AWS_SECRET_ACCESS_KEY
-
Complete the configuration with the following command, substituting
with the task launch type you want to use by default,launch_type
with your desired AWS region,region_name
with the name of an existing Amazon ECS cluster or a new cluster to use, andcluster_name
for the name you'd like to give this configuration.configuration_name
ecs-cli configure --cluster
--config-namecluster_name
--default-launch-typelaunch_type
--regionregion_name
configuration_name
After you have installed and configured the CLI, you can try the Tutorial: Creating a cluster with a Fargate task using the Amazon ECS CLI. For more information, see the Amazon ECS Command Line Reference in the Amazon Elastic Container Service Developer Guide.
Profiles
The Amazon ECS CLI supports the configuring of multiple sets of AWS credentials as
named profiles using the ecs-cli
configure profile command. A default profile can be set by using the
ecs-cli configure profile default command. These profiles can
then be referenced when you run Amazon ECS CLI commands that require credentials using
the --ecs-profile
flag otherwise the default profile is used.
For more information, see the Amazon ECS Command Line Reference in the Amazon Elastic Container Service Developer Guide.
Cluster Configurations
A cluster configuration is a set of fields that describes an Amazon ECS cluster
including the name of the cluster and the region. A default cluster configuration
can be set by using the ecs-cli configure default command. The
Amazon ECS CLI supports the configuring of multiple named cluster configurations using
the --config-name
option.
For more information, see the Amazon ECS Command Line Reference in the Amazon Elastic Container Service Developer Guide.
Order of Precedence
There are multiple methods for passing both the credentials and the region in an Amazon ECS CLI command. The following is the order of precedence for each of these.
The order of precedence for credentials is:
-
Amazon ECS CLI profile flags:
-
ECS profile (
--ecs-profile
) -
AWS profile (
--aws-profile
)
-
-
Environment variables:
-
ECS_PROFILE
-
AWS_PROFILE
-
AWS_ACCESS_KEY_ID
,AWS_SECRET_ACCESS_KEY
, andAWS_SESSION_TOKEN
-
-
ECS config‐attempts to fetch credentials from the default ECS profile.
-
Default AWS profile—Attempts to use credentials (
aws_access_key_id
,aws_secret_access_key
) orassume_role
(role_arn
,source_profile
) from the AWS profile name.-
AWS_DEFAULT_PROFILE
environment variable (defaults todefault
).
-
-
EC2 instance role
The order of precedence for Region is:
-
Amazon ECS CLI flags:
-
Region flag (
--region
) -
Cluster config flag (
--cluster-config
)
-
-
ECS config‐attempts to fetch the Region from the default ECS profile.
-
Environment variables—Attempts to fetch the region from the following environment variables:
-
AWS_REGION
-
AWS_DEFAULT_REGION
-
-
AWS profile‐attempts to use the region from the AWS profile name:
-
AWS_PROFILE
environment variable -
AWS_DEFAULT_PROFILE
environment variable (defaults todefault
)
-