ecsta is an "ECS Task Assistant" tool.
Production ready.
$ brew install fujiwara/tap/ecsta
Usage: ecsta <command>
Flags:
-h, --help Show context-sensitive help.
-c, --cluster=STRING ECS cluster name ($ECS_CLUSTER)
-r, --region=STRING AWS region ($AWS_REGION)
-o, --output="table" output format (table, tsv, json) ($ECSTA_OUTPUT)
-q, --task-format-query=STRING A jq query to format task in selector
($ECSTA_TASK_FORMAT_QUERY)
Commands:
configure
Create a configuration file of ecsta
describe
Describe tasks
exec
Execute a command on a task
list
List tasks
logs
Show log messages of a task
portforward --local-port=INT --remote-port=INT
Forward a port of a task
stop
Stop a task
trace
Trace a task
version
Show version
ecsta is a zero configuration command. But you can use a configuration file (~/.config/ecsta/config.json) to set default options.
Run an interactive setting as below.
$ ecsta configure$ ecsta configure --show
2022/08/08 15:36:54 configuration file: /home/fujiwara/.config/ecsta/config.json
{
"filter_command": "peco",
"output": "tsv"
}Usage: ecsta list
List tasks
Flags:
-f, --family=FAMILY Task definition family
-s, --service=SERVICE Service name
--output-tags Output tags of tasks
--tags=KEY=VALUE,... Show only tasks that have specified tags
$ ecsta list --cluster foo
| ID | TASKDEFINITION | INSTANCE | LASTSTATUS | DESIREDSTATUS | CREATEDAT | GROUP | TYPE |
+----------------------------------+--------------------+----------+------------+---------------+---------------------------+---------------------+---------+
| 38b0db90fd4c4b5aaff29288b2179b5a | ecspresso-test:499 | | RUNNING | RUNNING | 2022-08-05T09:59:27+09:00 | service:nginx-local | FARGATE |
| 4deeb701c49a4892b7de39a2d0df17e0 | ecspresso-test:499 | | RUNNING | RUNNING | 2022-08-06T00:12:50+09:00 | service:nginx-local | FARGATE |$ ecsta list --cluster foo --output-tags --tags Env=prod
| ID | TASKDEFINITION | INSTANCE | LASTSTATUS | DESIREDSTATUS | CREATEDAT | GROUP | TYPE | TAGS |
+----------------------------------+--------------------+----------+------------+---------------+---------------------------+---------------------+---------+---------------------------+
| 38b0db90fd4c4b5aaff29288b2179b5a | ecspresso-test:499 | | RUNNING | RUNNING | 2022-08-05T09:59:27+09:00 | service:nginx-local | FARGATE | Env=prod,Name=nginx-local |
| 4deeb701c49a4892b7de39a2d0df17e0 | ecspresso-test:499 | | RUNNING | RUNNING | 2022-08-06T00:12:50+09:00 | service:nginx-local | FARGATE | Env=prod,Name=nginx-local |Usage: ecsta describe
Describe tasks
Flags:
--id=STRING task ID
--family=FAMILY task definition family name
--service=SERVICE ECS service name
Usage: ecsta exec
Execute a command on a task
Flags:
--id=STRING task ID
--command="sh" command to execute
--container=STRING container name
--family=FAMILY task definition family name
--service=SERVICE ECS service name
--local-port and --remote-port, or -L is required.
Usage: ecsta portforward
Forward a port of a task
Flags:
--id=STRING task ID
--container=STRING container name
--local-port=INT local port
--remote-port=INT remote port
--remote-host=STRING remote host
-L, --L=STRING short expression of local-port:remote-host:remote-port
--family=FAMILY task definition family name
--service=SERVICE ECS service name
An example of port forwarding. Forward a port 8080 of a task to 80 of example.com.
$ ecsta portforward --local-port 8080 --remote-port 80 --remote-host example.com
$ ecsta portforward -L 8080:example.com:80ecsta connects to the task and starts a port forwarding. You can access the port 8080 of the local machine.
$ curl -H"Host: example.com" http://localhost:8080Usage: ecsta stop
Stop a task
Flags:
--id=STRING task ID
--force stop without confirmation
--family=FAMILY task definition family name
--service=SERVICE ECS service name
Run tracer. No need to install tracer command.
Usage: ecsta trace [flags]
Trace a task
Flags:
--id=STRING task ID
-d, --duration=1m duration to trace
--sns-topic-arn=STRING SNS topic ARN
--family=FAMILY task definition family name
--service=SERVICE ECS service name
-j, --json output JSON lines
Usage: ecsta logs
Show log messages of a task
Flags:
--id=STRING task ID
-s, --start-time=STRING a start time of logs
-d, --duration=1m log timestamps duration
-f, --follow follow logs
--container=STRING container name
--family=FAMILY task definition family name
--service=SERVICE ECS service name
-j, --json output as JSON lines
--start-time accepts flexible time formats (ISO8601, RFC3339, and etc). See also (tkuchiki/parsetime)[https://github.com/tkuchiki/parsetime].
When --start-time and --follow is specified both, --start-time may not work correctly.
Usage: ecsta cp <src> <dest> [flags]
Copy files from/to a task
Arguments:
<src> Source
<dest> Destination
Flags:
--port=12345 port number for file transfer
--[no-]progress show progress bar
--id=STRING task ID
--container=STRING container name
--family=FAMILY task definition family name
--service=SERVICE ECS service nameExample:
$ ecsta cp /path/to/file.txt _:/tmp/file.txt # copy file to a task(_ is the selected task)
$ ecsta cp 75dc060ef49b4ba1b2a33581dc5b876f:/tmp/file.txt /path/to/file.txt # copy file from the task.ecsta cp copies files from/to a task.
ecsta cp works as below.
ecstastarts a temporary TCP server on the task vie ECS Exec.- The server listens on the specified port (default is 12345).
- tncl is used as the server. It is a tiny TCP server that like
nc -lcommand. - The server is terminated when the file transfer is completed.
ecstastarts a port forwarding to the temporary server.ecstaconnects to the temporary server via the port forwarding.ecstasends or receives a file via the connection.
Requirements:
- The task must have the ECS Exec feature enabled.
- The task must have
sh,base64, andchmodcommands.
Limitations:
- Multiple files and directories are not supported.
This option provides a formatter by jq query. The query processes tasks JSON (that output equals to ecsta describe) in task selector outputs.
For example,
$ ecsta -q '[(.tags[]|select(.key=="Env")|.value), .launchType] | @tsv' execA task selector output will be as below.
045a0639-1dc5-4d17-8101-2dd3fd339e91 prod EC2
8f431e68-a57d-41db-ae8d-5eb700a134dc dev FARGATEThe query [(.tags[]|select(.key=="Env")|.value), .launchType] | @tsv means,
"Show tags value of "Env" key, and LaunchType for tasks as TSV format.".