Making Open Source More Inclusive
Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. We ask that you open an issue or pull request if you come upon a term that we have missed. For more details, see our CTO Chris Wright’s message.
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
- Rejecting modules
- Sample Ansible setup
- Working With Modules
- Working with plugins
- Playbook Keywords
- Ansible and BSD
- Windows Guides
- Using collections