Running an Ansible Playbook on a Single Host

1. Overview

Ansible uses inventory files to keep track of the hosts in an infrastructure. An inventory file consists of the hosts and groups in the infrastructure. It may also specify how to reach the hosts for running commands and playbooks.

Sometimes, we may not want to run a playbook on all hosts in the inventory. For example, we may want to test our playbook on a single host.

In this tutorial, we’ll discuss how to run an Ansible playbook on a single host without updating the inventory file. The version of Ansible we use in the examples is 2.12.0.

2. Example Playbook

We’ll use the following playbook, example_playbook.yml:

$ cat example_playbook.yml
- hosts: all
  name: Example Ansible Playbook
  tasks:
    - name: Print message
      debug:
        msg: Hello Baeldung

This playbook has a task that prints the greeting message, Hello Baeldung. We print the greeting using the msg parameter of Ansible’s built-in debug module.

We’ll also use the following inventory file, inventory:

$ cat inventory
host1
host2
host3

There are three hosts in inventory, namely host1, host2, and host3.

2.1. Testing the Playbook

Let’s run the playbook using the ansible-playbook command:

$ ansible-playbook -i inventory example_playbook.yml

PLAY [Example Ansible Playbook] ************************************************

TASK [Gathering Facts] *********************************************************
ok: [host1]
ok: [host2]
ok: [host3]

TASK [Print message] ***********************************************************
ok: [host1] => {
    "msg": "Hello Baeldung "
}
ok: [host2] => {
    "msg": "Hello Baeldung "
}
ok: [host3] => {
    "msg": "Hello Baeldung"
}

PLAY RECAP *********************************************************************
host1                      : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0 
host2                      : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   
host3                      : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

The -i option of ansible-playbook specifies the inventory file, which is inventory in our example. As is apparent from the output, the playbook ran on all the hosts in the inventory file since the hosts field in the playbook was set to all, i.e., hosts: all.

We aim to run the playbook on a single host without updating the inventory file.

3. Using a Modified Playbook

We can run the playbook on a specific host in the inventory by updating the playbook accordingly.

3.1. Using the hosts Field

One way to run the playbook on a single host is to update the hosts field in the playbook. For example, we can run example_playbook.yml on only host2 by updating the hosts field as follows:

- hosts: host2

Let’s run example_playbook.yml after this update:

$ ansible-playbook -i inventory example_playbook.yml

PLAY [Example Ansible Playbook] ************************************************

TASK [Gathering Facts] *********************************************************
ok: [host2]

TASK [Print message] ***********************************************************
ok: [host2] => {
    "msg": "Hello Baeldung"
}

PLAY RECAP *********************************************************************
host2                      : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0 

Now, the playbook ran only on host2 as expected.

3.2. Using a Conditional Task

Another alternative is to run a task conditionally using the when conditional.  For example, we can convert the Print message task to a conditional task by adding the when: inventory_hostname == “host2” condition:

$ cat example_playbook.yml
- hosts: all   
  name: Example Ansible Playbook
  tasks:
    - name: Print message
      debug:
        msg: Hello Baeldung
      when: inventory_hostname == "host2"

inventory_hostname is a special Ansible variable corresponding to the current host being iterated over in a run. Therefore, ansible-playbook runs the task only for host2 in our case:

$ ansible-playbook -i inventory example_playbook.yml

PLAY [Example Ansible Playbook] ************************************************

TASK [Gathering Facts] *********************************************************
ok: [host1]
ok: [host2]
ok: [host3]

TASK [Print message] ***********************************************************
skipping: [host1]
ok: [host2] => {
    "msg": "Hello Baeldung"
}
skipping: [host3]

PLAY RECAP *********************************************************************
host1                      : ok=1    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0 
host2                      : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   
host3                      : ok=1    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0

Ansible skips host1 and host3 as expected and runs the task only on host2. However, this method also requires updating the playbook each time we want to run it on a different host.

4. Using Variables

It’s possible to pass the host to the playbook as a parameter. We need to parameterize the hosts field in example_playbook.yml:

- hosts: '{{ target }}'

The target host is a variable now. The name of the variable is target. We can provide the value of target from the command line using the -e option of ansible-playbook:

$ ansible-playbook -i inventory example_playbook.yml -e "target=host2"

PLAY [Example Ansible Playbook] ************************************************

TASK [Gathering Facts] *********************************************************
ok: [host2]

TASK [Print message] ***********************************************************
ok: [host2] => {
    "msg": "Hello Baeldung"
}

PLAY RECAP *********************************************************************
host2                      : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

We set the target variable in example_playbook.yml to host2 using the target=host2 key-value pair. As is apparent from the output of the Print message task, the playbook was run only on host2 as expected.

It’s possible to run the playbook on all hosts in the inventory by setting target to all in the command line, i.e., -e “target=all”.

5. Using a Host List

Normally, we use the -i option of ansible-playbook to specify an inventory file. However, we can also specify a host list using the -i option. The list needs to be comma-separated.

Let’s run example_playbook.yml only on host2 using a host list:

$ ansible-playbook -i host2, example_playbook.yml

PLAY [Example Ansible Playbook] ************************************************

TASK [Gathering Facts] *********************************************************
ok: [host2]

TASK [Print message] ***********************************************************
ok: [host2] => {
    "msg": "Hello Baeldung"
}

PLAY RECAP *********************************************************************
host2                      : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

We used the -i host2, option to run the playbook on host2. The comma after host2 is critical for specifying that this is a host list. Otherwise, ansible-playbook interprets host2 as an inventory file if we pass it without a comma, i.e., -i host2. However, if we want to run the playbook on host2 and host3, we can specify the option as -i host2,host3.

As the output shows, we ran the playbook on only host2 by using the -i host2, option.

6. Using the –limit Option

We can also use the –limit option of ansible-playbook to run a playbook on a single host. The –limit option limits the hosts we target on a particular run:

$ ansible-playbook -i inventory --limit host2 example_playbook.yml

PLAY [Example Ansible Playbook] ************************************************

TASK [Gathering Facts] *********************************************************
ok: [host2]

TASK [Print message] ***********************************************************
ok: [host2] => {
    "msg": "Hello Baeldung"
}

PLAY RECAP *********************************************************************
host2                      : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

The playbook ran only on host2 because of the –limit host2 part of the command.

7. Conclusion

In this article, we discussed how to run an Ansible playbook on a single host without updating the inventory file. First, we saw that we could either update the hosts field or use the when conditional to limit the Ansible playbook to a specific target. However, we may not prefer this method as it requires modifying the playbook.

Then, we learned to pass a host to ansible-playbook using variables. This method also requires modifying the playbook, but we don’t need to change it each time we run it on a different host.

We saw that the -i option of ansible-playbook also accepts host lists. Therefore, we could pass a host list, consisting of a single host, to ansible-playbook.

Finally, we discussed the –limit option of ansible-playbook and learned that it can run the playbook only on the host specified using this option.