https://github.com/tedsmitt/ecsgo
Provides an interactive prompt to connect to ECS Containers using the ECS ExecuteCommand API.
https://github.com/tedsmitt/ecsgo
aws cli ecs ecs-exec ecs-executecommand-api fargate go port-forward ssm
Last synced: 5 months ago
JSON representation
Provides an interactive prompt to connect to ECS Containers using the ECS ExecuteCommand API.
- Host: GitHub
- URL: https://github.com/tedsmitt/ecsgo
- Owner: tedsmitt
- License: apache-2.0
- Created: 2021-03-17T21:32:58.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2024-12-23T17:20:03.000Z (over 1 year ago)
- Last Synced: 2024-12-23T18:27:25.882Z (over 1 year ago)
- Topics: aws, cli, ecs, ecs-exec, ecs-executecommand-api, fargate, go, port-forward, ssm
- Language: Go
- Homepage:
- Size: 146 KB
- Stars: 82
- Watchers: 4
- Forks: 13
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ecsgo
> [!IMPORTANT]
> PLEASE READ: I recommend using [e1s](https://github.com/keidarcy/e1s) as this does what ecsgo does but with a much better experience and far more capabilities.
Inspired by the incredibly useful [gossm](https://github.com/gjbae1212/gossm), this tool makes use of the [ECS ExecuteCommand API](https://aws.amazon.com/blogs/containers/new-using-amazon-ecs-exec-access-your-containers-fargate-ec2/) to connect to running ECS tasks.
It provides an interactive prompt to select your cluster, task and container (if only one container in the task it will default to this), and opens a connection to it. You can also use it to port-forward to containers within your tasks.
That's it! Nothing fancy.
## Installation
### MacOS/Homebrew
```bash
brew tap tedsmitt/ecsgo
brew install ecsgo
```
### Linux
```bash
wget https://github.com/tedsmitt/ecsgo/releases/latest/download/ecsgo_Linux_x86_64.tar.gz
tar xzf ecsgo_*.tar.gz
```
Move the `ecsgo` binary into your `$PATH`
## Pre-requisites
### session-manager-plugin
This tool makes use of the [session-manager-plugin](https://github.com/aws/session-manager-plugin). For instructions on how to install, please check out [this user guide](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html).
MacOS users can install this via Homebrew if desired
`brew install --cask session-manager-plugin`
### Infrastructure
Use [ecs-exec-checker](https://github.com/aws-containers/amazon-ecs-exec-checker) to check for the pre-requisites to use ECS exec.
## Usage
### CLI Args
By default, the tool will prompt you to interactively select which cluster, service, task and container to connect to. You can change the behaviour using the flags detailed below:
| Long | Short | Description | Default Value |
| -------------------- | ----- | --------------------------------------------------------------------------------------------------------- | -------------------------- |
| `--cluster` | `-n` | Specify the ECS cluster name | N/A |
| `--service` | `-s` | Specify the ECS service name | N/A |
| `--task` | `-t` | Specify the ECS Task ID | N/A |
| `--container` | `-u` | Specify the container name in the ECS Task (if task only has one container this will selected by default) | N/A |
| `--cmd` | `-c` | Specify the command to be run on the container (default will change depending on OS family). | `/bin/sh`,`powershell.exe` |
| `--forward` | `-f` | Port-forward to the container (Remote port will be taken from task/container definitions) | `false` |
| `--local-port` | `-l` | Specify local port to forward (will prompt if not specified) | N/A |
| `--profile` | `-p` | Specify the profile to load the credentials | `default` |
| `--region` | `-r` | Specify the AWS region to run in | N/A |
| `--quiet` | `-q` | Disable output detailing the Cluster/Service/Task information | `false` |
| `--aws-endpoint-url` | `-e` | Specify the AWS endpoint used for all service requests | N/A |
### Environment variables
The above options can also be configured via environment variables. Simply export environment variables in the form `ECSGO_`. For example, if you want to set the `--cluster` value, it would be `ECSGO_CLUSTER`, or for the `--aws-endpoint-url` option it would be `ECSGO_AWS_ENDPOINT_URL`.
The tool supports Standard AWS Environment Variables for AWS Client configuration. If you aren't familiar with working on AWS via the CLI, you can read more about how to configure your environment [here](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html).
## Example
See it in action below
