How to Use Ansible Dynamic Inventory with the AWS Ec2 Plugin to Automatically Target Cloud Instances by Tag on Ubuntu Server

ByAkensai

How to Use Ansible Dynamic Inventory with the AWS Ec2 Plugin to Automatically Target Cloud Instances by Tag on Ubuntu Server is one of the most practical skills you can add to your DevOps toolkit. If you manage fleets of EC2 instances that scale up and down, maintaining a static inventory file quickly becomes a nightmare. Dynamic inventory solves this by querying AWS in real time. You’ll always target the right machines. In this tutorial, you’ll configure the AWS EC2 dynamic inventory plugin on Ubuntu Server, tag your instances in AWS, and run Ansible playbooks that automatically discover and group those instances by tag. No more editing hosts files by hand. No more missed servers.

Prerequisites and Requirements for Using Ansible Dynamic Inventory with AWS EC2

Before you start, make sure you have the following in place. This setup assumes you have basic familiarity with the Linux command line and AWS.

You will need:

  • Ubuntu Server 20.04 or 22.04 (local or remote control node)
  • Python 3.8 or later installed
  • Ansible 2.12 or later
  • An active AWS account with EC2 instances already running
  • AWS CLI configured with a valid access key and secret key
  • The boto3 and botocore Python libraries
  • EC2 instances tagged with at least one key-value pair (for example, Environment: production)
  • SSH access to your EC2 instances from your Ubuntu control node

Estimated time: 30–45 minutes.

You don’t need to be an AWS expert. You do need to understand basic IAM permissions. Your AWS user or role must have at least ec2:DescribeInstances and ec2:DescribeTags permissions. Without those, the plugin can’t query your instances.

Step-by-Step Guide to Configuring the AWS EC2 Dynamic Inventory Plugin

Related tutorial: How to Manage ZFS Datasets, Snapshots, and Replication on Ubuntu Server

Follow these steps carefully on your Ubuntu Server control node.

Step 1: Update your system and install dependencies.

Start with a clean, updated system. Run the following commands:

sudo apt update && sudo apt upgrade -y
sudo apt install python3-pip python3-venv -y
pip3 install boto3 botocore

These libraries let Ansible talk to the AWS API. Without them, the EC2 plugin won’t work.

Step 2: Install Ansible and the Amazon collection.

Install Ansible via pip for the latest version. Then install the official Amazon collection:

pip3 install ansible
ansible-galaxy collection install amazon.aws

The amazon.aws collection includes the EC2 inventory plugin. Check the official Ansible EC2 inventory plugin documentation for a full list of supported options.

Step 3: Configure your AWS credentials.

The plugin needs AWS credentials to authenticate. The easiest method uses the AWS credentials file:

mkdir -p ~/.aws
nano ~/.aws/credentials

Add your credentials in this format:

[default]
aws_access_key_id = YOUR_ACCESS_KEY
aws_secret_access_key = YOUR_SECRET_KEY

Save and close the file. You can also set these as environment variables if you prefer. Use export AWS_ACCESS_KEY_ID=YOUR_KEY and export AWS_SECRET_ACCESS_KEY=YOUR_SECRET.

Step 4: Create your dynamic inventory file.

This is the core configuration step. Create a directory for your Ansible project and add an inventory file:

mkdir ~/ansible-aws && cd ~/ansible-aws
nano aws_ec2.yml

Paste this configuration into the file:

plugin: amazon.aws.aws_ec2
regions:
  - us-east-1
filters:
  tag:Environment:
    - production
keyed_groups:
  - key: tags.Environment
    prefix: env
  - key: tags.Role
    prefix: role
hostnames:
  - dns-name
  - ip-address
compose:
  ansible_host: public_ip_address

The filters block tells the plugin to return only instances tagged with Environment: production. The keyed_groups block creates Ansible groups automatically based on tag values. Change the region and tag values to match your setup.

Step 5: Test your dynamic inventory.

Run this command to verify the plugin is working:

ansible-inventory -i aws_ec2.yml --list

You should see JSON output listing your EC2 instances grouped by tag. If you see your instances, the plugin is working correctly. Run this to see a cleaner tree view:

ansible-inventory -i aws_ec2.yml --graph

This shows your groups and hosts in a readable format.

Step 6: Create an Ansible configuration file.

Create an ansible.cfg file in your project directory. This sets the default inventory so you don’t need to specify it every time:

nano ansible.cfg

Add the following:

[defaults]
inventory = aws_ec2.yml
remote_user = ubuntu
private_key_file = ~/.ssh/your-key.pem
host_key_checking = False

Replace your-key.pem with the path to your actual EC2 key pair file. Set remote_user to match your AMI’s default user. For Ubuntu AMIs, it’s ubuntu. For Amazon Linux, it’s ec2-user.

Step 7: Run a playbook targeting instances by tag.

Create a simple playbook to test targeting by tag group:

nano site.yml

Add this 

---
- name: Ping all production servers
  hosts: env_production
  gather_facts: false
  tasks:
    - name: Ping test
      ansible.builtin.ping:

The hosts: env_production line targets the group the plugin created from your Environment: production tag. Run the playbook:

ansible-playbook site.yml

You should see successful ping responses from all matching instances. That confirms your dynamic inventory is working end to end.

Troubleshooting Common Issues with AWS EC2 Dynamic Inventory

Even with careful setup, you’ll sometimes hit snags. Here are the most common problems and how to fix them.

Error: “boto3 module not found”
This means Python can’t find the boto3 library. Run pip3 install boto3 botocore again. Make sure you’re using the same Python version Ansible uses. Check with ansible --version to see the Python path.

Error: “Unable to locate credentials”
Your AWS credentials aren’t configured correctly. Double-check your ~/.aws/credentials file. Make sure there are no extra spaces around the equals signs. You can also run aws sts get-caller-identity to verify your credentials work.

No hosts returned in inventory
This usually means your filter doesn’t match any running instances. Check that your EC2 instances are in the running state. Verify the tag key and value match exactly, including capitalization. AWS tags are case-sensitive.

SSH connection refused
Check your security group rules. Your EC2 instances must allow inbound SSH (port 22) from your control node’s IP address. Also confirm the key pair file path in ansible.cfg is correct and the file has proper permissions: chmod 400 ~/.ssh/your-key.pem.

Plugin not recognized
If Ansible doesn’t recognize the amazon.aws.aws_ec2 plugin, the collection isn’t installed. Run ansible-galaxy collection install amazon.aws again. Refer to the AWS CLI configuration guide to verify your credential setup is correct.

Conclusion

You now know exactly how to use Ansible dynamic inventory with the AWS EC2 plugin to automatically target cloud instances by tag on Ubuntu Server. You’ve installed the required dependencies, configured the EC2 inventory plugin, filtered instances by tag, and run a real playbook against dynamically discovered hosts. This approach scales with your infrastructure. When you launch new EC2 instances with the right tags, Ansible picks them up automatically. No manual inventory updates needed. From here, you can explore more advanced features like using multiple tag filters, combining groups in playbooks, or integrating this setup into a CI/CD pipeline. Dynamic inventory is a foundational skill for any serious infrastructure automation workflow.

Similar Posts