ecsta

ecsta

ecsta is an "ECS Task Assistant" tool.

Product status

Production ready.

Install

Homebrew

$ brew install fujiwara/tap/ecsta

Binary releases

Usage

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

Configuration

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"
}

List tasks

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 |

Filtering tasks by family and service

The --family and --service flags are accepted by list, describe, exec, portforward, cp, stop, trace, and logs.

The AWS ListTasks API does not allow family and serviceName to be specified at the same time. When both flags are passed to ecsta, tasks are listed by family and then post-filtered as follows:

• Tasks belonging to the specified service are kept.
• Tasks not associated with any service (typically launched via RunTask, e.g. ecspresso run) of the same family are kept.
• Tasks belonging to other services that share the family are excluded.

This is useful when several ECS services share a single task definition family: passing both --family and --service returns only the tasks that belong to the specified service plus its standalone runs.

Describe task

Usage: ecsta describe

Describe tasks

Flags:
      --id=STRING          task ID
      --family=FAMILY      task definition family name
      --service=SERVICE    ECS service name

Exec task

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

Portforward task

--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:80

ecsta 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:8080

Stop task

Usage: 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

Trace task

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

Logs

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.

copy files

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 name

Example:

$ 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.

How to work ecsta cp

ecsta cp works as below.

1. ecsta starts 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 -l command.
   • The server is terminated when the file transfer is completed.
2. ecsta starts a port forwarding to the temporary server.
3. ecsta connects to the temporary server via the port forwarding.
4. ecsta sends or receives a file via the connection.

Requirements:

• The task must have the ECS Exec feature enabled.
• The task must have sh, base64, and chmod commands.

Limitations:

• Multiple files and directories are not supported.

--task-format-query(-q) option

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' exec

A task selector output will be as below.

045a0639-1dc5-4d17-8101-2dd3fd339e91    prod    EC2
8f431e68-a57d-41db-ae8d-5eb700a134dc    dev     FARGATE

The query [(.tags[]|select(.key=="Env")|.value), .launchType] | @tsv means, "Show tags value of "Env" key, and LaunchType for tasks as TSV format.".

LICENSE

MIT