README
¶
ECS Query CLI
The ecsq CLI tool provides a set of simple commands to query ECS for information. It presents the
data in compact, tabular format in most cases, with links to the AWS console where useful.
What's so special about this compared to the aws-cli?
Well, if the tabular output and short, consistent commands doesn't interest you, not much. This tool is about saving a few steps in my workflow.
The aws-cli tool is great for fetching the information, but it produces giant blobs of JSON and
can sometimes take a few invocations to get what I want. ecsq can be seen as a script that does a
few things on top of aws-cli. The major improvements, other than how information is presented, are
eval "$(ecsq container-env <cluster> <service> --format=export)"sources the production environment variables into your shell- direct links to the AWS console for services and tasks
Installation
ecsq is distributed via Go. Make sure you have Go installed, and run
go get -u github.com/button/ecsq
Upgrading
ecsq does not yet follow semantic versioning. Upgrading uses the same command as installing
go get -u github.com/button/ecsq
Configuration and credentials
ecsq uses the ~/.aws/credentials and ~/.aws/config for credentials and configuration, respectively.
You can also use the standard AWS CLI environment variables for overriding them. The common environment variables are
AWS_ACCESS_KEY_IDAWS_ACCESS_SECRET_KEYAWS_DEFAULT_REGION
More parameters can be found in Configuring the AWS CLI.
Overview
The ecsq tool can query AWS ECS by cluster, service, or task. The --help option shows the
commands.
> ecsq
usage: ecsq [<flags>] <command> [<args> ...]
A friendly ECS CLI
Flags:
--help Show context-sensitive help (also try --help-long and --help-man).
--profile=PROFILE AWS profile to use. Overrides the ~/.aws/config and AWS_DEFAULT_PROFILE
Commands:
help [<command>...]
Show help.
clusters
List existing clusters
services [<flags>] <cluster>
List services within the cluster
service [<flags>] <cluster> <service>
Show details of a service
tasks <cluster> <service>
List tasks belonging to a service
task <cluster> <task or service>
Describe the given task. If a service name is provided instead, describes an arbitrary task for that service.
container-env [<flags>] <cluster> <service>
List environment variables for the task's container
List clusters
ecsq clusters lists the ECS clusters in our AWS account.
> ecsq clusters
+------------------------+---------------------+-----------------+---------------+---------------+
| CLUSTER NAME | CONTAINER INSTANCES | ACTIVE SERVICES | RUNNING TASKS | PENDING TASKS |
+------------------------+---------------------+-----------------+---------------+---------------+
| default | 0 | 0 | 0 | 0 |
| ecs-prod | 3 | 3 | 3 | 0 |
| ecs-staging | 3 | 6 | 6 | 0 |
+------------------------+---------------------+-----------------+---------------+---------------+
List services
ecsq services lists the services within a cluster. For large clusters. this command can take a
while. Results can be filtered using the --filter flag.
> ecsq services ecs-prod
Found 3 services
+--------------+--------+---------+--------+----------+
| SERVICE NAME | STATUS | DESIRED | RUNNING | PENDING |
+--------------+--------+---------+--------+----------+
| applepicker | ACTIVE | 6 | 6 | 0 |
| helloworld | ACTIVE | 89 | 89 | 0 |
| my-blog | ACTIVE | 5 | 5 | 0 |
+--------------+--------+---------+--------+----------+
Describe service
ecsq service shows the details of a service, and provides useful links to the dashboard.
> ecsq service ecs-prod applepicker
Service
+----------------------+------------------------------------------------------------------------------------------------------------------+
| Name | applepicker |
| Status | ACTIVE |
| Service ARN | arn:aws:ecs:us-west-2:4817267453:service/applepicker |
| Task Definition | arn:aws:ecs:us-west-2:4817267453:task-definition/task-applepicker-ecs-prod:38 |
| Desired Count | 1 |
| Running Count | 1 |
| Pending Count | 0 |
| Service Link | https://us-west-2.console.aws.amazon.com/ecs/home?region=us-west-2#/clusters/ecs-prod/services/applepicker/tasks |
| Task Definition Link | https://us-west-2.console.aws.amazon.com/ecs/home?region=us-west-2#/taskDefinitions/task-applepicker-ecs-prod/ |
| LB Container Name | ngfe |
| LB Container Port | 8000 |
+----------------------+------------------------------------------------------------------------------------------------------------------+
Containers
+-------------+-----+--------+---------+
| NAME | CPU | MEMORY | COMMAND |
+-------------+-----+--------+---------+
| applepicker | 0 | 256 | |
| ngfe | 0 | 256 | |
+-------------+-----+--------+---------+
List service events
ecsq service --events lists events for that service in addition to the service details.
> ecsq service ecs-prod applepicker
...
2017-08-11T18:08:05Z: (service applepicker) has reached a steady state.
2017-08-15T12:12:08Z: (service applepicker) has reached a steady state.
2017-08-15T18:12:21Z: (service applepicker) has reached a steady state.
2017-08-15T19:00:53Z: (service applepicker) has stopped 2 running tasks: (task 02262781-54d0-4d1a-b76f-77693b0547f1) (task 56dce574-c297-41ef-8ec8-7b00477c5bfa).
2017-08-15T19:01:04Z: (service applepicker) has reached a steady state.
List tasks
ecsq tasks lists the tasks belonging to the service, by ARN. It's not useful by itself, but the
ARNs can be given to the ecsq task command to get task details:
> ecsq tasks ecs-prod applepicker
Running Tasks:
arn:aws:ecs:us-west-2:4817267453:task/bfbf861b-7f10-4dfb-b344-32169dc3e55c
Stopped Tasks:
Use the "task" command to get details of a task. For example:
ecsq task ecs-prod arn:aws:ecs:us-west-2:4817267453:task/bfbf861b-7f10-4dfb-b344-32169dc3e55c
Describe task
ecsq task shows the details of a given task, by ARN or task ID, and provides useful links to the
dashboard. If a service name is provided instead of an ARN/ID, then it will look up an arbitrary
task for the service and provide its details
> ecsq task ecs-prod applepicker
> ecsq task ecs-prod arn:aws:ecs:us-west-2:192431242:task/bfbf861b-7f10-4dfb-b344-32169dc3e55c
Details:
+-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
| Task ID | bfbf861b-7f10-4dfb-b344-32169dc3e55c |
| Task ARN | arn:aws:ecs:us-west-2:192431242:task/bfbf861b-7f10-4dfb-b344-32169dc3e55c |
| Task Definition | task-applepicker-ecs-prod |
| Container Instance | 44019f70-aa88-48e3-babf-4614e10afe08 |
| EC2 Instance | i-072932614cc14ccf9 |
| Task Link | https://us-west-2.console.aws.amazon.com/ecs/home?region=us-west-2#/clusters/ecs-prod/tasks/bfbf861b-7f10-4dfb-b344-32169dc3e55c |
| Task Definition Link | https://us-west-2.console.aws.amazon.com/ecs/home?region=us-west-2#/taskDefinitions/task-applepicker-ecs-prod/ |
| Container Instance Link | https://us-west-2.console.aws.amazon.com/ecs/home?region=us-west-2#/clusters/ecs-prod/containerInstances/44019f70-aa88-48e3-babf-4614e10afe08 |
| EC2 Instance Link | https://us-west-2.console.aws.amazon.com/ec2/v2/home?region=us-west-2#Instances:instanceId=i-072932614cc14ccf9 |
+-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
Containers:
+-------------+--------------------------+--------------------+
| applepicker | Status | RUNNING |
| | Network - Container Port | 3000 |
| | Network - External Link | 10.10.121.212:3030 |
| ngfe | Status | RUNNING |
| | Network - Container Port | 8000 |
| | Network - External Link | 10.10.121.212:8080 |
| | Network - Container Port | 8001 |
| | Network - External Link | 10.10.121.212:8081 |
+-------------+--------------------------+--------------------+
Show (and source) container environment variables
ecsq container-env fetches and dumps environment variables for a service's container definition. It
can often be useful to run a container locally with the same configuration as on ECS.
The command supports 3 formats, set with the --format flag
tablethis is the default format, it renders the environment variales as a tableshellrenders the environment variables to prefix the command with inbashorzsh, or pass into theenvfunctionexportrenders the environment variables asexportstatements tobashorzshdockerrenders the environment variables as-eflags to thedockercommand
Running the command as eval "$(ecsq container-env <my_cluster> <my_service>) --format=export" will
automatically populate your environment with container's ECS environment variables. If you want to omit
specific variables here, you can provide a comma-separated list of names via the --drop flag. This list is
case-insensitive, e.g. --drop node_env,port is the same as --drop NODE_ENV,PORT. The
ECSQ_DROP_ENV_VARS environment variable can also be used in place of --drop to drop the same
vars across invocations.
> ecsq container-env ecs-prod applepicker --container applepicker
+-------------------+---------+
| NAME | VALUE |
+-------------------+---------+
| NODE_ENV | prod |
| PORT | 3000 |
| ORCHARD_API_KEY | xxxxxxx |
| ORCHARD_API_TOKEN | xxxxxxx |
+------------------+----------+
> ecsq container-env ecs-prod applepicker --format=shell --container applepicker
NODE_ENV="prod" PORT="3000" ORCHARD_API_KEY="xxxxxxxx" ORCHARD_API_TOKEN="xxxxxxxx"
> ecsq container-env ecs-prod applepicker --format=docker --container applepicker
-eNODE_ENV="prod" -ePORT="3000" -eORCHARD_API_KEY="xxxxxxxx" -eORCHARD_API_TOKEN="xxxxxxxx"
> ecsq container-env ecs-prod applepicker --format=export --container applepicker
export NODE_ENV="prod"
export PORT="3000"
export ORCHARD_API_KEY="xxxxxxx"
export ORCHARD_API_TOKEN="xxxxxxx"
Environment Variables
ECSQ_SERVICE_NAME_EXPANSION can be used to specify a Golang template string to expand the provided
service name to. This is kind of an obscure option, to allow writing shorter service names if your
service names follow a predefined format. For example, if your services names follow the format
service-{{.Name}}-{{.Cluster}}, then the service applepicker on cluster ecs-prod will be
expanded to service-applepicker-ecs-prod when querying ECS.
ECSQ_DROP_ENV_VARS can be used to set a default value for container-env command's --drop flag,
to always omit these vars.
Documentation
¶
There is no documentation for this package.
Source Files