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.

Source Distribution

ecsctl-20200907.tar.gz (9.8 kB view hashes)

Uploaded source

Built Distribution

ecsctl-20200907-py2-none-any.whl (10.5 kB view hashes)

Uploaded py2

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page