Skip to main content

kubectl-style command line client for AWS ECS.

Project description

kubectl-style command line tool for AWS EC2 Container Service (ECS) travis-ci


pip install ecsctl


A convenient command line tool to view ECS cluster status and do troubleshooting.

This tool is trying to provide similar functionality of kubectl for kubernetes.

Of course, ECS and kubernetes are so different. Many features on kubernetes are not possible here in ECS.

Some AWS official projects to check out:



List nodes:

% ecsctl get clusters
default  ACTIVE            3          0                 2

Get cluster details:

% ecsctl describe cluster mycluster

Create/delete cluster:

% ecsctl create cluster mycluster

Container Instances (nodes)

List nodes:

% ecsctl get nodes --cluster mycluster
INSTANCE ID                           EC2 INSTANCE ID      STATUS      RUNNING COUNT
00000000-1111-2222-3333-444444444444  i-abcdef123456abcde  ACTIVE                  1

Get node detail:

% ecsctl describe node 00000000-1111-2222-3333-444444444444

Drain/undrain node:

% ecsctl drain 00000000-1111-2222-3333-444444444444


List services:

% ecsctl get services

List services in certain order:

% ecsctl get services --sort-by "createdAt"

Delete a service:

% ecsctl delete service badservice

Delete a service (even if it has desiredCount > 0):

% ecsctl delete service badservice --force

Run container quick start

% ecsctl run mycontainer --image busybox

% ecsctl get services
mycontainer-svc  mycontainer:1              1          0  ACTIVE    10 seconds ago

Run docker exec on containers (Requires customizing docker daemon to listen on internal addresses)

% ecsctl get tasks
TASK ID                               STATUS    TASK DEFINITION    AGE
42f052c4-80e9-411d-bea2-407b0b4a4b0b  PENDING   mycontainer:1      2 minutes ago

% ecsctl exec 42f052c4-80e9-411d-bea2-407b0b4a4b0b date
Fri May 26 00:13:24 PDT 2017

% ecsctl exec -it 42f052c4-80e9-411d-bea2-407b0b4a4b0b /bin/bash
root@container:/# (interactive)

Configure docker daemon to allow ecsctl exec

  1. Let docker daemon listen on TCP ports (required)

Add options like -H tcp:// or environment variable DOCKER_HOST=tcp:// to configure docker daemon. See dockerd documentation for more information.

  1. Security enhancement: dropping traffic from ECS containers to docker daemon.

    iptables --insert INPUT 1 \
             --in-interface docker+ \
             --protocol tcp \
             --destination-port MYDOCKERPORT \
             --jump DROP


Set default cluster name (equivalent to --cluster option)

% ecsctl config set cluster mycluster

Set default docker daemon port

% ecsctl config set docker_port 2375

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for ecsctl, version 20200907
Filename, size File type Python version Upload date Hashes
Filename, size ecsctl-20200907-py2-none-any.whl (10.5 kB) File type Wheel Python version py2 Upload date Hashes View
Filename, size ecsctl-20200907.tar.gz (9.8 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page