Skip to content

Dynamic Inventory

Ansible's dynamic inventory system allows you to programmatically generate host and group inventories at runtime, eliminating the need for manually maintained static files. This approach is particularly powerful when integrating with cloud platforms, APIs, or databases that provide structured host metadata. Dynamic inventory scripts leverage external data sources to populate inventory details, enabling automation that adapts to infrastructure changes in real time.

How Dynamic Inventory Works

Dynamic inventory scripts are executable files (e.g., Python, Bash, or JSON) that Ansible runs to fetch host information. These scripts output data in a format Ansible understands, typically JSON, with keys like hosts, groups, and vars. When you run an Ansible command, it executes the script, reads the output, and uses it to determine which hosts to target.

For example, a dynamic inventory script might query a cloud provider's API to list all running virtual machines, then group them by region or tags. This data is then used to execute playbooks against the correct hosts without manual intervention.

Integrating with Cloud Providers

Ansible provides built-in dynamic inventory scripts for major cloud platforms, which interact with their APIs to fetch host details. These scripts are typically located in the inventory directory of your Ansible installation.

Example: AWS EC2 Inventory

The ec2.py script uses AWS's EC2 API (via Boto3) to list instances. It filters hosts based on tags, regions, or instance states. To use it:

ansible all -i ec2.py --list
This command lists all hosts managed by the script, grouped by tags or regions. The script requires AWS credentials (via environment variables or IAM roles) and can be customized with parameters like --regions or --tags.

Example: Azure Inventory

The azure_rm.py script connects to Azure's REST API to retrieve virtual machines. It supports filtering by resource groups or tags. Example usage:

ansible all -i azure_rm.py --list
Authentication is handled via Azure CLI credentials or managed identities, depending on the environment.

Custom Dynamic Inventory Scripts

For non-cloud systems or proprietary APIs, you can write custom scripts. The script must output JSON with the following structure:

{
  "hosts": {"host1": {}, "host2": {}},
  "groups": {
    "group1": ["host1", "host2"],
    "group2": ["host3"]
  },
  "vars": {"key": "value"}
}
A simple Bash script to list hosts from a database might look like:
#!/bin/bash
# Fetch hosts from a database
HOSTS=$(curl -s http://db-api/host-list)
echo "{ \"hosts\": $HOSTS }"
This script would then be used with Ansible via:
ansible all -i custom_script.sh --list

Best Practices and Considerations

  • Security: Store API credentials in environment variables or use Ansible Vault to protect sensitive data.
  • Performance: Dynamic inventories can be slower than static ones, as they fetch data on each run. Cache results if possible.
  • Scalability: Avoid overloading APIs with frequent requests; use pagination or rate-limiting where necessary.
  • Testing: Validate script outputs with tools like jq or Ansible's --check mode to ensure correctness.

Key takeaways

  • Dynamic inventory scripts fetch host data at runtime, enabling integration with cloud APIs and databases.
  • Ansible provides built-in scripts for AWS, Azure, and GCP, simplifying cloud infrastructure management.
  • Custom scripts can adapt to any data source, offering flexibility beyond standard providers.
  • Secure credential handling and performance optimization are critical for reliable automation.
  • Always validate script outputs to ensure Ansible can correctly interpret the inventory data.