ecsta

package module
v0.6.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 3, 2024 License: MIT Imports: 41 Imported by: 3

README

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

Documentation

Index

Constants

View Source 
const SessionManagerPluginBinary = "session-manager-plugin"

Variables

View Source 
var ErrAborted = errors.New("Aborted")
View Source 
var Version string

Functions

func MarshalJSONForAPI added in v0.0.4 

func MarshalJSONForAPI(v interface{}, query *gojq.Query) ([]byte, error)

func RunCLI added in v0.0.6 

func RunCLI(ctx context.Context, args []string) error

func UnmarshalJSONForStruct added in v0.0.4 

func UnmarshalJSONForStruct(src []byte, v interface{}) error

Types

type CLI added in v0.0.6 

type CLI struct {
	Cluster         string `help:"ECS cluster name" short:"c" env:"ECS_CLUSTER"`
	Region          string `help:"AWS region" short:"r" env:"AWS_REGION"`
	Output          string `help:"output format (table, tsv, json)" short:"o" default:"table" enum:"table,tsv,json" env:"ECSTA_OUTPUT"`
	TaskFormatQuery string `help:"A jq query to format task in selector" short:"q" env:"ECSTA_TASK_FORMAT_QUERY"`
	Debug           bool   `help:"enable debug output" env:"ECSTA_DEBUG"`

	Configure   *ConfigureOption   `cmd:"" help:"Create a configuration file of ecsta"`
	Describe    *DescribeOption    `cmd:"" help:"Describe tasks"`
	Exec        *ExecOption        `cmd:"" help:"Execute a command on a task"`
	List        *ListOption        `cmd:"" help:"List tasks"`
	Logs        *LogsOption        `cmd:"" help:"Show log messages of a task"`
	Portforward *PortforwardOption `cmd:"" help:"Forward a port of a task"`
	Stop        *StopOption        `cmd:"" help:"Stop a task"`
	Trace       *TraceOption       `cmd:"" help:"Trace a task"`
	CP          *CpOption          `cmd:"" help:"Copy files from/to a task"`
	Version     struct{}           `cmd:"" help:"Show version"`
}

type Config 

type Config struct {
	FilterCommand   string `help:"command to run to filter messages" json:"filter_command"`
	Output          string `help:"output format (table, tsv or json)" enum:"table,tsv,json" default:"table" json:"output"`
	TaskFormatQuery string `help:"A jq query to format task in selector" json:"task_format_query"`
}

func (*Config) ConfigElements added in v0.3.2 

func (c *Config) ConfigElements() []ConfigElement

func (*Config) Get 

func (c *Config) Get(name string) string

func (*Config) Names added in v0.3.2 

func (c *Config) Names() []string

func (*Config) OverrideCLI added in v0.0.3 

func (c *Config) OverrideCLI(cli *CLI)

func (*Config) Set 

func (c *Config) Set(name, value string)

func (*Config) String 

func (c *Config) String() string

type ConfigElement 

type ConfigElement struct {
	Name        string `json:"name"`
	Description string `json:"help"`
	Default     string `json:"default"`
}

type ConfigureOption added in v0.0.3 

type ConfigureOption struct {
	Show bool `help:"show current configuration" short:"s"`
}

type CpOption added in v0.6.0 

type CpOption struct {
	Src      string `arg:"" help:"Source"`
	Dest     string `arg:"" help:"Destination"`
	Port     int    `help:"port number for file transfer" default:"12345"`
	Progress bool   `help:"show progress bar" negatable:"" default:"true"`

	ID        string  `help:"task ID"`
	Container string  `help:"container name"`
	Family    *string `help:"task definition family name"`
	Service   *string `help:"ECS service name"`
}

func (*CpOption) DestTarget added in v0.6.0 

func (cp *CpOption) DestTarget() (string, string)

func (*CpOption) SrcTarget added in v0.6.0 

func (cp *CpOption) SrcTarget() (string, string)

type DescribeOption added in v0.0.3 

type DescribeOption struct {
	ID      string  `help:"task ID"`
	Family  *string `help:"task definition family name"`
	Service *string `help:"ECS service name"`
}

type Ecsta 

type Ecsta struct {
	Config *Config
	// contains filtered or unexported fields
}

func New 

func New(ctx context.Context, region, cluster string) (*Ecsta, error)

func (*Ecsta) Dispatch added in v0.0.6 

func (app *Ecsta) Dispatch(ctx context.Context, command string, cli *CLI) error

func (*Ecsta) Endpoint 

func (app *Ecsta) Endpoint(ctx context.Context) (string, error)

func (*Ecsta) RunConfigure added in v0.0.3 

func (app *Ecsta) RunConfigure(ctx context.Context, cmd *ConfigureOption) error

func (*Ecsta) RunCp added in v0.6.0 

func (app *Ecsta) RunCp(ctx context.Context, opt *CpOption) error

func (*Ecsta) RunDescribe added in v0.0.3 

func (app *Ecsta) RunDescribe(ctx context.Context, opt *DescribeOption) error

func (*Ecsta) RunExec added in v0.0.3 

func (app *Ecsta) RunExec(ctx context.Context, opt *ExecOption) error

func (*Ecsta) RunList added in v0.0.3 

func (app *Ecsta) RunList(ctx context.Context, opt *ListOption) error

func (*Ecsta) RunLogs added in v0.0.4 

func (app *Ecsta) RunLogs(ctx context.Context, opt *LogsOption) error

func (*Ecsta) RunPortforward added in v0.0.3 

func (app *Ecsta) RunPortforward(ctx context.Context, opt *PortforwardOption) error

func (*Ecsta) RunStop added in v0.0.3 

func (app *Ecsta) RunStop(ctx context.Context, opt *StopOption) error

func (*Ecsta) RunTrace added in v0.0.3 

func (app *Ecsta) RunTrace(ctx context.Context, opt *TraceOption) error

func (*Ecsta) SetCluster 

func (app *Ecsta) SetCluster(ctx context.Context) error

type ExecOption added in v0.0.3 

type ExecOption struct {
	ID        string  `help:"task ID"`
	Command   string  `help:"command to execute" default:"sh"`
	Container string  `help:"container name"`
	Family    *string `help:"task definition family name"`
	Service   *string `help:"ECS service name"`
	// contains filtered or unexported fields
}

type ListOption added in v0.0.3 

type ListOption struct {
	Family     *string           `help:"Task definition family" short:"f"`
	Service    *string           `help:"Service name" short:"s"`
	OutputTags bool              `help:"Output tags of tasks"`
	Tags       map[string]string `help:"Show only tasks that have specified tags" mapsep:","`
}

type LogsOption added in v0.0.4 

type LogsOption struct {
	ID        string        `help:"task ID"`
	StartTime string        `help:"a start time of logs" short:"s"`
	Duration  time.Duration `help:"log timestamps duration" short:"d" default:"1m"`
	Follow    bool          `help:"follow logs" short:"f"`
	Container string        `help:"container name"`
	Family    *string       `help:"task definition family name"`
	Service   *string       `help:"ECS service name"`
	JSON      bool          `help:"output as JSON lines" short:"j"`
}

func (*LogsOption) ResolveTimestamps added in v0.2.1 

func (opt *LogsOption) ResolveTimestamps() (time.Time, time.Time, error)

type PortforwardOption added in v0.0.3 

type PortforwardOption struct {
	ID         string  `help:"task ID"`
	Container  string  `help:"container name"`
	LocalPort  int     `help:"local port"`
	RemotePort int     `help:"remote port"`
	RemoteHost string  `help:"remote host"`
	L          string  `name:"L" help:"short expression of local-port:remote-host:remote-port" short:"L"`
	Family     *string `help:"task definition family name"`
	Service    *string `help:"ECS service name"`
	// contains filtered or unexported fields
}

func (*PortforwardOption) ParseL added in v0.4.4 

func (opt *PortforwardOption) ParseL() error

type StopOption added in v0.0.3 

type StopOption struct {
	ID      string  `help:"task ID"`
	Force   bool    `help:"stop without confirmation"`
	Family  *string `help:"task definition family name"`
	Service *string `help:"ECS service name"`
}

type TraceOption added in v0.0.3 

type TraceOption struct {
	ID          string        `help:"task ID"`
	Duration    time.Duration `help:"duration to trace" short:"d" default:"1m"`
	SNSTopicArn string        `help:"SNS topic ARN"`
	Family      *string       `help:"task definition family name"`
	Service     *string       `help:"ECS service name"`
	JSON        bool          `help:"output JSON lines" short:"j"`
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
ecsta

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.