k-kbot / ecsk

CLI tool that you can interactively call Amazon ECS APIs (run-task, execute-command, stop-task), copy files between ECS and local, and view logs.

English / 日本語

ecsk

ECS + Task = ecsk 😆

ecsk is a CLI tool that you can interactively call Amazon ECS APIs (run-task, execute-command, stop-task), copy files between ECS and local, and view logs.

Since esck specializes in operating containers (tasks),

• Management of ECS services and task definitions -> CDK, Terraform, etc
• Debugging -> ecsk 😁

The above use is assumed.

Install

MacOS

brew install yukiarrr/tap/ecsk

Linux

wget https://github.com/yukiarrr/ecsk/releases/download/v0.9.0/ecsk_Linux_x86_64.tar.gz
tar zxvf ecsk_Linux_x86_64.tar.gz
chmod +x ./ecsk
sudo mv ./ecsk /usr/local/bin/ecsk

Windows

Download from Releases.

Usage

Here are some frequently used commands.
For detailed flags, run ecsk [command] --help to check them.

ecsk run

ecsk run

If you don't specify any flags, after entering task information interactively, the log will continue to flow until the task is started and stopped as in docker run.

ecsk run -e -i --rm -c [container_name] -- /bin/sh

After the task is started, execute the command specified by execute-command.
By specifying --rm, the task will be automatically stopped at the end of the session, so you can operate it like a bastion host.

ecsk run -d

After entering the task information interactively, the command will be stopped without waiting for the task to start or stop.

ecsk exec

ecsk exec -i -- /bin/sh

After selecting the task and container interactively, and execute the command.

ecsk cp

ecsk cp ./ [container_name]:/etc/nginx/

After selecting the task interactively, copy the files from local to remote.
Internally, using an S3 Bucket to transfer the files, so you need to add permissions for the corresponding Bucket to the task role.

If you want to select the container interactively, use ecsk cp ./ :/etc/nginx/.

ecsk cp [container_name]:/var/log/nginx/access.log ./

Transfer files from remote to local.

ecsk logs

ecsk logs

After selecting the task interactively, view logs.
Multiple tasks can be specified.

ecsk uses knqyf263/utern to view logs.

ecsk stop

ecsk stop

After selecting the task interactively, stop.

ecsk describe

ecsk describe

After selecting the tasks interactively, view detailed information.
You can also use it to check a task list.

Prerequisites

When using ecsk exec

Since ecsk is executing execute-command internally, there are some prerequisites.
Here are the prerequisites with reference to the official documentation.

Install Session Manager plugin

Please refer to the following.

https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html

Permissions required for ECS Exec

The ECS Exec feature requires a task IAM role to grant containers the permissions needed for communication between the managed SSM agent (execute-command agent) and the SSM service.

{
   "Version": "2012-10-17",
   "Statement": [
       {
       "Effect": "Allow",
       "Action": [
            "ssmmessages:CreateControlChannel",
            "ssmmessages:CreateDataChannel",
            "ssmmessages:OpenControlChannel",
            "ssmmessages:OpenDataChannel"
       ],
      "Resource": "*"
      }
   ]
}

Enabling ECS Exec

You need to enable ECS Exec in order to execute-command on a task of a service that has already been created.
Add the --enable-execute-command flag for AWS CLI, or EnableExecuteCommand for CFn.

Note that you should use the -e or --enable-execute-command flag for tasks started with ecsk run.

Supplement

As these are more prerequisites, ecsk will run aws-containers/amazon-ecs-exec-checker on errors.

When using ecsk cp

Since ecsk uses S3 Bucket for file transfer, you need to add permissions for the corresponding bucket to the task role.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetObject",
                "s3:PutObject",
                "s3:PutObjectAcl"
            ],
            "Resource": [
                "arn:aws:s3:::[bucket_name]",
                "arn:aws:s3:::[bucket_name]/ecsk_*"
            ]
        }
    ]
}