Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Amazon ECS Service Discovery Tool

Build Status Coverage Status

Designed as a Cluster Orchestration helper, more info below.


This is one of my first Golang projects I have completed start-to-finish, the codebase could use some splitting up/separation into more modular pieces, but it performs the task required for now so not really too concerned. I spent less than a day in total on it. I am sure there are lots of improvements that can be made, but being it runs and exits in under 300ms (most of that AWS API latencies), I am happy :)


So let's say you want to orchestrate a cluster of containers running on top of Amazon ECS, for example a service like Consul. You need to obtain the IP addresses of all other potential members/nodes to be able to attempt to join one. This utility provides you the other node addresses to use.

This could easily be achieved with awscli + bash + jq, but it is a handful of API calls, and sifting through results so I opted to do it all in a single binary instead.


Designed to be run on EC2 within an Amazon ECS cluster, inside a Docker container (and with the default networking topology). This utility will attempt to access the ECS agent on in addition to the AWS APIs. Access to the local Docker daemon socket is not required. In future ideally this would support handling Docker networks, with a custom IP to hit, for now it just hits the default bridge network docker0 IP.

Service/Task Ports

There is an expectation you will know the service port already, and all tasks under a given service will have that port open. This utility only deals with retrieving the correct IP addresses, ports are not covered at all.


I have 2 ECS container instances in a single cluster, with 2 services running. One of the services is named "nginx", and has a desired count of 2 (one on each of the ECS container instances for now). The result will be a CSV of VPC/private IPs, excluding the current instance (you normally don't want to attempt to join yourself if orchestrating a cluster):

root@cddb6164b344:/# ./ecs-discoverer -s nginx

Use ./ecs-discoverer --help for a full help listing.


go build

Single binary, copy/put into the Docker container of your choice. Or download a binary release if it suffices for you.

IAM Policy

Make sure your ECS container instances have a policy containing the below (feel free to lock down the Resource by account/region):

    "Version": "2012-10-17",
    "Statement": [
            "Effect": "Allow",
            "Action": [
            "Resource": [


Released under MIT License.


Single binary (Golang) for discovery of VPC IPs of Amazon ECS container instances running a task for a given service.







No packages published