Run Your First Ansible Playbook on a Test Host

This guide walks you through creating and running your first Ansible playbook against a test host. You’ll learn how to define a simple task, execute it, and verify the result—giving you a solid foundation for automating your own infrastructure.

What You’ll Need

A Linux machine (or WSL on Windows) where Ansible is installed. If you don’t have it yet, install it with sudo apt install ansible (Debian/Ubuntu) or sudo yum install ansible (RHEL/CentOS).
A test host—this can be another Linux machine, a VM, a container, or even localhost. The host must have SSH enabled and Python available (Ansible needs Python on the target).
SSH access to the test host. Ideally, set up key-based authentication so you don’t have to type a password each time.
Basic familiarity with the command line and YAML syntax.

Step-by-Step

Create a working directory. Open a terminal and run mkdir ansible-test && cd ansible-test. This keeps your playbook and inventory tidy.
Create an inventory file. An inventory lists your hosts. Create a file named hosts and add your test host’s IP or hostname. For example, 192.168.1.100 or testhost.example.com. If you want to test on your local machine, you can use localhost and run Ansible with --connection=local later.
Write your first playbook. Create a file named playbook.yml and open it in a text editor. Start with a simple task that pings the host (a connectivity check) and creates a test file. Here’s a minimal playbook:
```
---
- name: My first play
  hosts: all
  tasks:
    - name: Ping the host
      ping:

    - name: Create a test file
      file:
        path: /tmp/ansible_test.txt
        state: touch
    
```
Check the playbook syntax. Run ansible-playbook -i hosts playbook.yml --syntax-check. This catches YAML errors before you run anything.
Run the playbook. Execute ansible-playbook -i hosts playbook.yml. Ansible will connect via SSH, run the tasks, and show you the results. If you set up SSH keys, it should run without prompting for a password. If not, you’ll need to add --ask-pass to be prompted for the SSH password.
Verify the result. After the run, check the output. You should see ok for the ping task and changed for the file creation. To confirm the file exists, SSH into the test host and run ls -l /tmp/ansible_test.txt.

Common Mistakes

Forgetting the inventory file. Ansible needs to know where to connect. Always specify -i hosts or set ANSIBLE_INVENTORY.
SSH host key verification. If the test host is new, Ansible may prompt to confirm the host key. To avoid this in a test environment, you can add --ssh-common-args='-o StrictHostKeyChecking=no' to your command, but be aware this is insecure for production.
YAML indentation errors. YAML is strict about spaces. Use spaces, not tabs, and be consistent. The tasks list must be indented under the play.
Wrong Python path. If the target host has Python in a non-standard location, Ansible may fail. You can specify the interpreter in the inventory or playbook with ansible_python_interpreter.

Tips

Start with --check to do a dry run: ansible-playbook -i hosts playbook.yml --check. This shows what would change without actually making changes.
Use -v (verbose) to see more details, or -vvv for debugging SSH issues.
Keep your playbooks idempotent—running them multiple times should not cause errors or repeated changes. The example above is idempotent because touch only creates the file if it doesn’t exist.
Organize your inventory with groups. For example, put your host under [test] and then target that group in the playbook with hosts: test.

Troubleshooting

Playbook fails with “Failed to connect to the host via ssh”
Check that the host is reachable (ping), SSH is running, and you have the correct credentials. Try connecting manually with ssh user@host to see the exact error.

Permission denied (publickey)
Your SSH key isn’t authorized on the target. Use ssh-copy-id user@host to copy your public key, or use --ask-pass to use a password.

YAML syntax error
Run ansible-playbook --syntax-check to get the exact line. Common issues are missing spaces after colons or inconsistent indentation.

Module not found or unsupported
Ensure the target host has Python and that the module you’re using is available in your Ansible version. For example, the ping module is built-in, but others might require collections.

“Timeout (12s) waiting for privilege escalation prompt”
If you need sudo, add become: yes to your playbook or task. Make sure your user has sudo privileges on the target.

Playbook runs but nothing changes
Check if the task is already in the desired state. Use --check and -v to see what Ansible thinks the state is.

Frequently Asked Questions

Do I need a separate test host, or can I use localhost?

You can use localhost by setting hosts: localhost in your playbook and running with --connection=local. This is great for testing playbooks that don’t require remote access.

What’s the difference between `ansible` and `ansible-playbook`?

ansible runs a single ad-hoc command, while ansible-playbook runs a playbook file with multiple tasks. For anything beyond a quick check, use playbooks.

Can I run a playbook on multiple hosts at once?

Yes, just list multiple hosts in your inventory file. Ansible will run the tasks on all of them in parallel (by default, 5 at a time). You can control this with the forks parameter.

How do I pass variables to a playbook?

You can define variables in the playbook, in separate files, or pass them on the command line with --extra-vars "var1=value1 var2=value2".

Is it safe to run Ansible on production after testing?

Yes, but always test thoroughly first. Use --check mode, review the changes, and consider using a version control system for your playbooks.

What if I don’t have root access on the test host?

You can still run tasks that don’t require elevated privileges. For tasks that need sudo, add become: yes and ensure your user is in the sudoers file.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →