keidarcy/e1s

E1S - Easily Manage AWS ECS Resources in Terminal(~k9s for ECS) 🐱

E1S - Easily Manage AWS ECS Resources in Terminal 🐱

e1s is a terminal application to easily browse and manage AWS ECS resources, supports both Fargate and EC2 ECS launch types. Inspired by k9s.

A quick video demo

AWS credentials and configuration

e1s uses the default aws-cli configuration. It does not store or send your access and secret key anywhere. The access and secret key are used only to securely connect to AWS API via AWS SDK. Both profile and region are overridable via the AWS_PROFILE, AWS_REGION prepend environment variable or --profile, --region option.

Installation

e1s is available on Linux, macOS and Windows platforms.

• Binaries for Linux, Windows and Mac are available in the release page.
• Homebrew for maxOS or Linux

brew install keidarcy/tap/e1s
# brew upgrade
# brew upgrade keidarcy/tap/e1s

• Docker image

# docker image
docker pull ghcr.io/keidarcy/e1s:latest

• AWS CloudShell(Good for quick tryout)

curl -sL https://raw.githubusercontent.com/keidarcy/e1s-install/master/cloudshell-install.sh | bash

• go install command

go install github.com/keidarcy/e1s/cmd/e1s@latest

Usage

Make sure you have the AWS CLI installed and properly configured with the necessary permissions to access your ECS resources, and session manager plugin installed if you want to use the interactive exec or port forwarding features.

• Usage of e1s:

$ e1s -h
e1s is a terminal application to easily browse and manage AWS ECS resources 🐱.
Check https://github.com/keidarcy/e1s for more details.

Usage:
  e1s [flags]

Flags:
      --cluster string       specify the default cluster
  -c, --config-file string   config file (default "$HOME/.config/e1s/config.yml")
  -d, --debug                sets debug mode
  -h, --help                 help for e1s
  -j, --json                 log output json format
  -l, --log-file string      specify the log file path (default "${TMPDIR}e1s.log")
      --profile string       specify the AWS profile
      --read-only            sets read only mode
  -r, --refresh int          specify the default refresh rate as an integer, sets -1 to stop auto refresh (sec) (default 30)
      --region string        specify the AWS region
  -s, --shell string         specify interactive ecs exec shell (default "/bin/sh")
      --theme string         specify color theme
  -v, --version              version for e1s

• Examples

# use all default config
$ e1s
# use custom-profile profile, us-east-2 region
$ AWS_PROFILE=custom-profile AWS_REGION=us-east-2 e1s
# use custom-profile profile, us-east-2 region
$ e1s --profile custom-profile --region us-east-2
# use command line to set read only, debug, stop auto refresh with a custom log path json output and dracula theme
$ e1s --readonly --debug --refresh -1 --log-file /tmp/e1s.log --json --theme dracula
# docker run with specified profile and region
$ docker run -it --rm -v $HOME/.aws:/root/.aws ghcr.io/keidarcy/e1s:latest e1s --profile YOUR_PROFILE --region YOUR_REGION

Config file(sample)

Default config file path is $HOME/.config/e1s/config.yml, it's possible specify the config file that viper supports with --config-file option.

Theme and colors

Theme and colors can be specified by options or config file. Full themes list can be found here. If you prefer to use your own color theme, you can specify the colors in the config file.

examples

• command e1s --theme dracula
• screenshot

• config file

colors:
  BgColor: "#272822"
  FgColor: "#f8f8f2"
  BorderColor: "#a1efe4"
  Black: "#272822"
  Red: "#f92672"
  Green: "#a6e22e"
  Yellow: "#f4bf75"
  Blue: "#66d9ef"
  Magenta: "#ae81ff"
  Cyan: "#a1efe4"
  Gray: "#808080"

• screenshot

• config file

colors:
  BgColor: black
  FgColor: cadeblue
  BorderColor: dodgerblue
  Black: black
  Red: orangered
  Green: palegreen
  Yellow: greenyellow
  Blue: darkslateblue
  Magenta: mediumpurple
  Cyan: lightskyblue
  Gray: lightslategray

• screenshot

Key bindings

Press ? to check overall key bindings, top right corner to check current resource specific hot keys.

help

Development

go run cmd/e1s/main.go --debug --log-file /tmp/e1s.log

tail -f /tmp/e1s.log

Features

Full features list

features

• Specify config file
• Specify the default cluster
• Read only mode
• Auto refresh
• Describe clusters
• Describe services
• Describe tasks(running, stopped)
• Describe containers
• Describe task definitions
• Describe service autoscaling
• Show cloudwatch logs(only support awslogs logDriver)
  • Realtime log streaming(only support one log group)
• Show Metrics
  • CPUUtilization
  • MemoryUtilization
• Show autoscaling target and policy
• Open selected resource in browser(support new UI(v2))
• Interactively exec towards containers(like ssh)
• Edit service
  • Desired count
  • Force new deployment
  • Task definition family
  • Task definition revision
• Stop task
• Register new task definition
• Start port forwarding session
• Start remote host port forwarding session
• Transfer files to and from your local machine and a remote host like aws s3 cp
• Customize theme
• Customize colors

Interactively exec towards containers(ECS Exec)

Use aws-ecs-exec-checker to check for the pre-requisites to use ECS exec.

interactive exec demo

Use ctrl + d to exit interactive-exec session.

Troubleshooting

The execute command failed because execute command... - check service execute command, task role policy

Session Manager plugin not found - document.

Update service

update service demo

• Force new deployment
• Desired tasks
• Task definition family
• Task definition revision

Register task definition

Register task definition

Start port forwarding session

With a specified task and container, to start port forwarding session you need to specify a port and a local port. The local port is the port on your local machine that you want to use to access the container port.

Port forwarding session

Start remote host port forwarding session

With a specified task and container, to start a remote host port forwarding session you need to specify a port, a host and a local port. The local port is the port on your local machine that you want to use to access the remote host port though container.

Remote host port forwarding session

File transfer

Implemented by a S3 bucket. Since file transfer though a S3 bucket and aws-cli in container, you need a S3 bucket and add permissions S3 bucket permission to the task role and e1s role, and also need a aws-cli installed container.

File transfer

Feature requests & bug reports

If you have any feature requests or bug reports, please submit them through GitHub Issues.

Publish new version

• Bump version
• make tag

Thanks

• tview
• k9s
• ecsview

License

MIT

e1s's Issues

credential_process doesn't work for authentication

I've been getting bit on credential_process multiple places on products using the aws go sdk v2 (terraform,pulumi and now e1s 😄 etc) due to this bug I think you just might need to bump the sdk to the fixed version

 ~ ❯ e1s
sh: /Users/ryan.odonnell/go/bin/redacted: No such file or directory
e1s failed to start, please check your aws cli credential or permission.
operation error ECS: ListClusters, get identity: get credentials: failed to refresh cached credentials, process provider error: error in credential_process: exit status 127

View service/task logs

Just discovered this tool and it looks awesome!

I'd like to view the logs of a service/task, just like in k9s 😄

Maybe some like Cloudwatch Logs Live Tail can be used for this?

AWS CLI ref: https://awscli.amazonaws.com/v2/documentation/api/latest/reference/logs/tail.html

Themes/customization support

Hi,

Can you please consider an option to allow colours customization? I use Catppuccin Mocha theme for my terminal and when I run e1s it uses much lighter background. It would be great to have an option to customize colours so they'd match terminal theme or maybe as a quick workaround just have a transparent e1s background?

e1s displays a maximum of 100 services associated with a cluster

👋 Hi - thanks for your work on es1! Here's a lil' bug users may want to be aware of:

In addition to issue #116 , which prevents the rendering of services when the service count is divisible by 10 (including when there are >= 100 services on a cluster), I believe there's another problem hiding in the details: in current implementation, es1 will not display more than 100 services, as it only fetches first 100 services associated with a cluster.

Use a logger with level

Seems to be a limit of 10 services

Hi, when I browse a ecs cluster with more than 10 services, it seems to be able to view only 10? Or maybe I'm just doing it wrong? (TM)

Lacking details when using ECS over EC2 ?

Hi there

Gave a quick shot at e1s. It look likes what I've been looking for, except that I've few details. Maybe because we're running tasks over an EC2 ASG ? Skimming through the README I saw a focus on Fargate, might explain why and are grayed out ?

Thanks !

AWS Credentials chain not working

The tool fails to initialize when ~/.aws/config file is empty and ~/.aws/credentials file only contains profiles that work with other tooling, the example of one profile being:

...
[ProfileName_Prod_ReadOnly]
aws_access_key_id = <REDACTED>
aws_secret_access_key = <REDACTED>
aws_session_token = <REDACTED>
aws_security_token = <REDACTED>
token_expiration = 2024-01-31T02:14:57Z

...

Alongside this profile, the following env vars are initialized in same shell where e1s run is attempted:

export AWS_PROFILE=ProfileName_Prod_ReadOnly
export AWS_DEFAULT_PROFILE=ProfileName_Prod_ReadOnly

The attempt to run e1s fails with following error message:

e1s -readonly

e1s failed to start, please check your aws cli credential or permission.
operation error ECS: ListClusters, exceeded maximum number of attempts, 3, https response error StatusCode: 0, RequestID: , request send failed, Post "https://ecs..amazonaws.com/": Bad Request

Rendering issues after reload

Thank you for a such helpful tool! Since I started to use it, I've picked up few issues that happen after Ctrl-r is hit:

• List selection is being reset to position 0. Let's say I have 10 services and I've highlighted 4th, I'd like selection to stay on it after list is refreshed
• It seems like list is not being re-drawn until navigation keys are pressed. (press Ctrl-r, pop-up is shown that resources were reloaded but list stays exactly the same, then you press Up or Down and list is re-drawn)
• Service event view (w) being closed after Ctrl-r is pressed few times (you go back to the Services view). There is no exact number of times you need to refresh view for this to happen - sometimes it happens on a second Ctrl-r, sometimes on third...

P.S.: also +1 for the auto refresh mode (maybe at least while service is being updated)

Option for ssh shell

Add options to reload and/or auto-refresh

In k9s the UI gets automatically refreshed and you can force a reload with <ctrl>+r. In e1s this is not the case and forcing a reload is also not supported. I'd like at least to have the ability to force a reload, with a further enhancement being the auto refresh.

Support better command line input

Support session manager port forward

exec inside container does not seem to work

I am able to get to EC2 from console session manager, do docker ps and docker exec. But from e1s it fails when doing shift+e:

Execute: "/bin/sh"

The Session Manager plugin was installed successfully. Use the AWS CLI to start a session.


An error occurred (InvalidParameterException) when calling the ExecuteCommand operation: The execute command failed because execute command was not enabled when the task was run or the execute command agent isn’t running. Wait and try again or run a new task with execute command enabled and try again.

Done...

Logs from wrong container are displayed

Hello,

Thanks for the great tool!

I think I might have found a bug where logs from the wrong container are being displayed. See screenshot below of logs from task e1fd60503c464114964fd0bb89622f0e showing the container printing its own task ID as e9a5d8f337084920bf203b2087711fa3 which it fetched from the metadata endpoint.

I've verified by checking the CloudWatch logs that each task does indeed correctly print its own task ID, so it's not an issue with the ECS metadata endpoint or with CloudWatch. So I figure it must be e1s showing the logs from the wrong task.

Cheers!

Update service with task definition selection

Docker image i/o timeout on api.github.com inside a private environment

Hello,

I have an issue running E1S in a docker. The docker host is a private EC2.

The following commands:

# docker image
docker pull ghcr.io/keidarcy/e1s:latest
# docker run with specified profile and region
docker run -it --rm -v /home/myuser/.aws:/root/.aws ghcr.io/keidarcy/e1s:latest e1s --profile myprofile --region eu-west-3

Generate the follwing error:

2024/06/11 14:12:15 Get "https://api.github.com/repos/keidarcy/e1s/releases/latest": dial tcp: lookup api.github.com on xxx.xxx.xxx.xxx:53: read udp 172.17.0.2:35787->xxx.xxx.xxx.xxx:53: i/o timeout

Why does the docker image is accessing github ?

Enhance task definition support

• Check all task definition family

• Check each family task definition revisions

• Register a new task definition

Regression in 1.0.34

Hi,

there is regression related to the theming introduced in v1.0.34. I have BgColor set to #1e1e2e in my config but background is being reset to #282828. Before that version it was picked up correctly.
My full config is:

colors:
  BgColor: "#1e1e2e" 
  FgColor: "#cdd6f4"
  BorderColor: "#585b70"
  Black: "#45475a"
  Red: "#f38ba8"
  Green: "#a6e3a1"
  Yellow: "#f9e2af"
  Blue: "#89b4fa"
  Magenta: "#f5c2e7"
  Cyan: "#94e2d5"
  Gray: "#9399b2"

Show e1s show feedback in footer

Add errors, update msg, remove modal feedback

List of clusters limited to 100

1. List of ecs clusters visible in the UI is limited to 100. In scenarios where more than 100 clusters are there in the account , cluster is not shown in the UI.

Additional points that can be addressed:

1. Search functionality in UI similar to k9s
2. An argument for the cluster name while using e1s command to open a specific cluster like one we have for k9s.

Unable to update task definition on services with CODE_DEPLOY deployment controller

This is a really great tool, thank you for working on this 🙇🏻

I only have this one issue with it where I couldn't update desired tasks on services with CODE_DEPLOY as deployment controller, I haven't look that much deeper into this but changing it from console works, so I'm guessing maybe they use AWS CodeDeploy API behind the scene to upgrade instead of normal ECS Service update, I'm wondering if e1s could do the same?

showing logs are broken after SSH into container

it seems like when you try to show logs after exiting SSH connection the logs are not being displayed from Cloud Watch anymore instead shows the logs of SSH connection.

go run main.go --debug --log-file-path /tmp/e1s.log

e1s fails to render a cluster's "services" view when the number of services is divisible by 10

Currently, e1s silently fails to render a cluster's "services" view when the number of services fetched via the AWS API is divisible by 10. While no error is surfaced in the e1s UI, the /tmp/debug-e1s.log reveals the following clue:

2024/01/30 06:54:31 e1s - aws failed to describe services, err: operation error ECS: DescribeServices, https response error StatusCode: 400, RequestID: REDACTED, InvalidParameterException: Services cannot be empty
2024/01/30 06:54:31 e1s - show services page failed, error: operation error ECS: DescribeServices, https response error StatusCode: 400, RequestID: REDACTED InvalidParameterException: Services cannot be empty

Option to change default sorting

Hi,

It would be great if you can allow changing default sorting (Column, Direction) per each view. Ideally, custom sorting should be saved in a state file so next time I open e1s everything's sorted how I left it.