########## User Guide ##########

note:

**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 <https://www.redhat.com/en/blog/making-open-source-more-inclusive-eradicating-problematic-language>`_.

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.

Getting started

• I'd like an overview of how Ansible works. Where can I find:
• a quick video overview
• a text introduction
• I'm ready to learn about Ansible. What basic_concepts do I need to learn?
• I want to use Ansible without writing a playbook. How do I use ad hoc commands?

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
• Running tasks only when certain conditions apply with conditionals and evaluating conditions with tests
• 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 want to take advantage of the power of re-usable Ansible artifacts. How do I create re-usable files and roles?
• 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?

Executing playbooks

Once your playbook is ready to run, you may need to use these topics:

• Executing "dry run" playbooks with check mode and diff
• Running playbooks while troubleshooting with start and step
• Correcting tasks during execution with the Ansible debugger
• Controlling how my playbook executes with strategies and more
• Running tasks, plays, and playbooks asynchronously

Advanced features and reference

• Using advanced syntax
• Manipulating complex data
• Using plugins
• Using playbook keywords
• Using command-line tools
• Rejecting specific modules
• Module maintenance

Traditional Table of Contents

If you prefer to read the entire User Guide, here's a list of the pages in order: