My former employer quietly open sourced a handy utility for mocking out the metadata service on AWS’ EC2 hosts a few weeks ago. As I’ve mentioned previously, there are a few projects in this space, but none quite as simple as this one to get going.

ectou-metadata includes an implementation of the IAM security credential API that, to applications, feels exactly like running on an EC2 instance launched with an IAM Role. This means no more injecting credentials into containers needing AWS API access. It also helps increase dev prod parity.

Here’s how I’m using it out under Mac OSX with a stock docker-machine virtualbox VM.

First, build the docker container image. I’ve contributed a Dockerfile.

Next, plumb the well-known address in the docker-machine VM:

docker-machine ssh <machine-label> sudo ip addr add dev eth0

Finally, launch a container bound to that IP. This works with --net if using docker networking.

docker run \
  --env=MOCK_METADATA_ROLE_ARN=arn:aws:iam::ACCOUNT:role/ROLE \
  --publish= \
  --volume=$HOME/.aws/mock-metadata-credentials:/home/ec2-user/.aws/credentials:ro \

If everything is wired up correctly you’ll see 200s logged by the ectou-metadata service when making API calls, like: - - [01/Feb/2016 18:54:29] "GET /latest/meta-data/iam/security-credentials/ HTTP/1.1" 200 9 - - [01/Feb/2016 18:54:29] "GET /latest/meta-data/iam/security-credentials/role-name HTTP/1.1" 200 641

Other containers running on this VM that have network access will be able to use these credentials.

I’d love to figure out how to run multiple instances of this within a single VM so different containers automatically have access to different roles but for now I’ve settled on one instance per VM/set of containers. If there’s anyone out there, please get in touch with thoughts.

There are some other goodies baked in that look useful. Big thanks to Monetate for opening up this code!