Welcome to the Ansible User Guide! This guide covers how to work with Ansible, including using the command line, working with inventory, interacting with data, writing tasks, plays, and playbooks; executing playbooks, and reference materials. This page outlines the most common situations and questions that bring readers to this section. If you prefer a traditional table of contents, you can find one at the bottom of the page.
Writing tasks, plays, and playbooks¶
I’m writing my first playbook. What should I know before I begin?
I have a specific use case for a task or play:
Executing tasks with elevated privileges or as a different user with become
Repeating a task once for each item in a list with loops
Executing tasks on a different machine with delegation
Grouping a set of tasks together with blocks
Running tasks only when something has changed with handlers
Changing the way Ansible handles failures
Setting remote environment values
I need to incorporate one file or playbook inside another. What is the difference between including and importing?
I want to run selected parts of my playbook. How do I add and use tags?
Working with inventory¶
I have a list of servers and devices I want to automate. How do I create inventory to track them?
I use cloud services and constantly have servers and devices starting and stopping. How do I track them using dynamic inventory?
I want to automate specific sub-sets of my inventory. How do I use patterns?
Interacting with data¶
I want to use a single playbook against multiple systems with different attributes. How do I use variables to handle the differences?
I want to retrieve data about my systems. How do I access Ansible facts?
I need to access sensitive data like passwords with Ansible. How can I protect that data with Ansible vault?
I want to change the data I have, so I can use it in a task. How do I use filters to transform my data?
I need to retrieve data from an external datastore. How do I use lookups to access databases and APIs?
I want to ask playbook users to supply data. How do I get user input with prompts?
I use certain modules frequently. How do I streamline my inventory and playbooks by setting default values for module parameters?
Once your playbook is ready to run, you may need to use these topics:
Advanced features and reference¶
Traditional Table of Contents¶
If you prefer to read the entire User Guide, here’s a list of the pages in order:
- Ansible Quickstart Guide
- Ansible concepts
- Getting Started
- Introduction to ad-hoc commands
- Working with playbooks
- Intro to playbooks
- Tips and tricks
- Understanding privilege escalation: become
- Controlling where tasks run: delegation and local actions
- Handlers: running operations on change
- Error handling in playbooks
- Setting the remote environment
- Working with language-specific version managers
- Re-using Ansible artifacts
- Including and importing
- How to build your inventory
- Inventory basics: formats, hosts, and groups
- Adding variables to inventory
- Assigning a variable to one machine: host variables
- Assigning a variable to many machines: group variables
- Organizing host and group variables
- How variables are merged
- Using multiple inventory sources
- Connecting to hosts: behavioral inventory parameters
- Inventory setup examples
- Working with dynamic inventory
- Patterns: targeting hosts and groups
- Connection methods and details
- Working with command line tools
- Using Variables
- Creating valid variable names
- Simple variables
- When to quote variables (a YAML gotcha)
- List variables
- Dictionary variables
- Registering variables
- Referencing nested variables
- Transforming variables with Jinja2 filters
- Where to set variables
- Variable precedence: Where should I put a variable?
- Using advanced variable syntax
- Discovering variables: facts and magic variables
- Encrypting content with Ansible Vault
- Using filters to manipulate data
- Handling undefined variables
- Defining different values for true/false/null (ternary)
- Managing data types
- Formatting data: YAML and JSON
- Combining and selecting data
- Randomizing data
- Managing list variables
- Selecting from sets or lists (set theory)
- Calculating numbers (math)
- Managing network interactions
- Encrypting and checksumming strings and passwords
- Manipulating text
- Manipulating strings
- Managing UUIDs
- Handling dates and times
- Getting Kubernetes resource names
- Interactive input: prompts
- Module defaults
- Validating tasks: check mode and diff mode
- Executing playbooks for troubleshooting
- Debugging tasks
- Controlling playbook execution: strategies and more
- Asynchronous actions and polling
- Advanced Syntax
- Data manipulation
- Blacklisting modules
- Sample Ansible setup
- Working With Modules
- Working With Plugins
- Playbook Keywords
- Ansible and BSD
- Windows Guides
- Using collections