ansible-playbook

Run tasks in playbook

$ ansible-playbook [playbook]

$ ansible-playbook [playbook] [[-i|--inventory]] [inventory_file]

$ ansible-playbook [playbook] [[-e|--extra-vars]] "[variable1]=[value1] [variable2]=[value2]"

$ ansible-playbook [playbook] [[-e|--extra-vars]] "@[variables.json]"

$ ansible-playbook [playbook] [[-t|--tags]] [tag1,tag2]

$ ansible-playbook [playbook] --start-at [task_name]

$ ansible-playbook [playbook] [[-C|--check]] [[-D|--diff]]

ansible-playbook [options] playbook.yml [playbook2.yml ...]

-i INVENTORY, --inventory=INVENTORY
    Specify the Ansible inventory file or host list to target. This can be a file path, directory, or a comma-separated list of hosts.

-l SUBSET, --limit=SUBSET
    Further limit the selected hosts to a specified group, host pattern, or individual host name within the inventory.

-f FORKS, --forks=FORKS
    Specify the number of parallel processes (forks) to use for execution. The default value is typically 5.

-u REMOTE_USER, --user=REMOTE_USER
    Connect to the remote host as this specified user.

-b, --become
    Run operations with privilege escalation (e.g., using sudo or su) on the remote hosts.

-k, --ask-become-pass
    Ask for the privilege escalation password (e.g., sudo password) before execution.

-K, --ask-pass
    Ask for the connection password (e.g., SSH password) if SSH keys are not used or protected.

--check
    Perform a 'dry run' of the playbook. It won't make any actual changes, but will report what would have happened.

--diff
    When changing files or templates, show the differences (diffs) between the original and modified content.

--syntax-check
    Perform a syntax check on the playbook(s) without executing any tasks. Useful for validating playbook structure early.

--list-hosts
    List all hosts that would be targeted by the playbook based on the inventory and limit parameters, without running tasks.

--list-tasks
    List all tasks that would be executed by the playbook, in the order they would run, without actual execution.

--start-at-task=TASK_NAME
    Begin the playbook execution at a specific named task, skipping preceding tasks.

-v, -vv, -vvv, -vvvv, --verbose
    Increase the verbosity level of output. More 'v's provide progressively more detailed information for debugging.

-e EXTRA_VARS, --extra-vars=EXTRA_VARS
    Set additional variables as key=value, @file.yml, or @file.json. These variables override others.

-t TAGS, --tags=TAGS
    Only run plays and tasks that have the specified tags (comma-separated list).

--skip-tags=SKIP_TAGS
    Skip plays and tasks that have the specified tags (comma-separated list).

--flush-cache
    Clear the fact cache before running the playbook. Useful when facts might be stale or need to be re-gathered.

--step
    Engage one-step-at-a-time interactive execution, prompting the user before each task runs.

ansible-playbook is the primary command-line tool for running Ansible playbooks.
Playbooks are declarative YAML files that define a set of tasks to be executed on remote hosts or localhost. They serve as the blueprint for automating complex IT workflows, ranging from simple configuration changes to multi-tier application deployments and continuous delivery pipelines.

The command parses the specified playbook(s), connects to the hosts defined in the inventory, and executes tasks sequentially. It leverages SSH for communication (by default) and aims to ensure idempotency, meaning tasks can be run multiple times without causing unintended side effects. It's the core component of Ansible's powerful automation capabilities, enabling users to define, manage, and scale their infrastructure and applications as code.

While Ansible strives for idempotency, custom scripts or external commands called within playbooks might not always be inherently idempotent, potentially leading to unintended state changes if not carefully designed.
Ansible requires Python on both the control node (where ansible-playbook is executed) and the managed nodes (for running modules).
Reliable SSH connectivity between the control node and managed nodes is fundamental for ansible-playbook to function correctly.
Effective use of ansible-playbook necessitates a good understanding of YAML syntax for writing playbooks and Ansible's execution model.

An Ansible playbook is a YAML file typically structured with one or more 'plays'. Each play defines a group of hosts (from the inventory) to target and a list of 'tasks' to execute on those hosts. Playbooks can also include sections for variables (vars), handlers (for executing tasks when notified), roles (reusable collections of content), and more, allowing for modular and highly reusable automation code.

A core principle of Ansible and ansible-playbook is idempotency. This means that executing a playbook multiple times should result in the same system state as executing it once, assuming no external factors interfere. Ansible modules are designed to check the current state of a system before making changes, only acting if the desired state is not met, thus ensuring consistency, preventing unnecessary modifications, and simplifying repeated deployments.

When ansible-playbook runs:
1. It parses the specified playbook(s) and the associated inventory.
2. For each play, it identifies the target hosts based on the 'hosts' directive and any applied limits.
3. It then typically gathers 'facts' (system information) about the remote hosts.
4. Tasks are executed sequentially on the target hosts. For each task, Ansible determines if a change is needed (due to idempotency) and executes the relevant module.
5. If a task signals that a change occurred, 'handlers' (special tasks that run only when notified) can be triggered at the end of the play or specific plays.

Ansible was created by Michael DeHaan and first released in 2012, aiming to be a simpler, agentless automation engine compared to existing configuration management tools. Red Hat acquired Ansible in 2015. From its inception, ansible-playbook has been central to Ansible's design, providing a declarative, human-readable way to define IT automation workflows using YAML. Its popularity surged due to its agentless architecture (relying on SSH), ease of use, and strong focus on idempotency, which has made it a de-facto standard for infrastructure as code and orchestration.

ansible(1), ansible-galaxy(1), ansible-vault(1), ansible-console(1)