A collection of commands to simplify common tasks built on top of Ansible and the EC2 external inventory plugin
Pull request Compare This branch is 5 commits behind pas256:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
bin Fix ssh using --user and --private-key together Sep 12, 2014
README.md Improving readme documentation Nov 9, 2012



A collection of commands to simplify common tasks built on top of Ansible and the EC2 external inventory plugin.


# Tell me what the heck the 'info' command does
ansible-ec2 help info

# SSH into the EC2 instance with the 'Name' tag 'Web1'
ansible-ec2 ssh --name Web1

# List all instances in the us-east-1a availability zone
ansible-ec2 list --zone us-east-1a

# Give me detailed information about all m1.xlarge instances in the 'database' security group 
ansible-ec2 info --type m1.xlarge --sg database

Setup and Installation

  1. Set up Ansible


  2. Configure the EC2 inventory plugin

    cp ansible/plugins/inventory/ec2.py /etc/ansible/hosts
    cp ansible/plugins/inventory/ec2.ini /etc/ansible/ec2.ini
    cat > ~/.boto <<EOF
    aws_access_key_id = AKIA123
    aws_secret_access_key = SeCrEt123

    Confirm it is working by running

  3. Put ansible-ec2 on your path somewhere, or change your path

    export PATH="${PATH}:/path/to/ansible-ec2/bin"

Now you can run through the examples above or simply list all instance

ansible-ec2 list




  • help Get help about a command

  • list Get a list of instances

  • info Get detailed information about instances

  • ssh Open an interactive SSH connection to a specific instance


By default, ansible-ec2 performs a command against all instances. This might be fine for list, but far from ideal for ssh. This is where filters become powerful, by limiting the set of instances a command runs on.

Multiple filters can be used together to target specific instances. In this example, only m1.large instances using the peter key pair in us-east-1b are listed:

ansible-ec2 list --type m1.large --key peter --zone us-east-1b


EC2 instances can have tags (simple key/value pairs) associated with them. The 'Name' tag is of particular interest as it is the first column in the AWS Web Console. To run only against instances with a specific value for the 'Name' tag, use:

--name NAME

ansible-ec2 list --name MyDB1

Security Group

Run a command only against instances in a specific security group


ansible-ec2 list --sg default

Key Pair

The name of the key pair to filter on

--key KEY_PAIR

ansible-ec2 list --key superadmin

Instance Type

EC2 instances come in a variety of different types, from t1.micro to m1.medium to hi1.4xlarge. This filter enables limiting the instance list to only those using a specific instance type


ansible-ec2 list --type=m1.xlarge

Region and Availability Zone

EC2 is all over the world, so these 2 filters create a subset of instance only in a specific region or availability zone

--region REGION

ansible-ec2 list --region us-east-1
ansible-ec2 list --zone us-east-1a

Instance ID and Raw Group Name

The hosts returned by the EC2 inventory plugin are in one or more groups. One such group is the Instance ID. As the plugin evolves, more groups may be added, so this allows access to all of them without code modification. It also allows filtering on other tag key/value pairs.

ansible-ec2 info i-abcd1234
ansible-ec2 list tag_aws_elasticmapreduce_instance-group-role_CORE
ansible-ec2 list tag_aws_elasticmapreduce_job-flow-id_j-ABCD1234EFGH