The when clause is useful when you need to check the output of a variable or a play execution result and act accordingly. We saw a quick example of the when clause in Chapter 7, The Python Automation Framework – Ansible Basics, when we looked at the Ansible 2.5 best practices structure. If you recall, the task only ran when the network operating system of the device was the Cisco IOS. Let's look at another example of its use in chapter8_1.yml:

    ---
    - name: IOS Command Output
      hosts: "iosv-devices"
      gather_facts: false
      connection: local
      vars:
        cli:
          host: "{{ ansible_host }}"
          username: "{{ username }}"
          password: "{{ password }}"
          transport: cli
      tasks:
        - name: show hostname
          ios_command:
            commands:
              - show run | i hostname
                provider: "{{ cli }}"
            register: output
        - name: show output
          when: '"iosv-2" in "{{ output.stdout }}"'
          debug:
            msg: '{{ output }}'

We have seen all the elements in this playbook before in Chapter 7, The Python Automation Framework – Ansible Basics, up to the end of the first task. For the second task in the play, we are using the when clause to check if the output contains the iosv-2 keyword. If true, we will proceed to the task, which is using the debug module to display the output. When the playbook is run, we will see the following output:

    <skip>
    TASK [show output]  
    *************************************************************
    skipping: [ios-r1]
    ok: [ios-r2] => {
        "msg": {
            "changed": false,
           "stdout": [
                "hostname iosv-2"
            ],
            "stdout_lines": [
                [
                    "hostname iosv-2"
                ]
             ],
             "warnings": []
         }
    }
    <skip>

We can see that the iosv-r1 device is skipped from the output because the clause did not pass. We can further expand this example in chapter8_2.yml to only apply certain configuration changes when the condition is met:

    <skip> 
    tasks:
      - name: show hostname
        ios_command:
          commands:
            - show run | i hostname
          provider: "{{ cli }}"
        register: output
      - name: config example
        when: '"iosv-2" in "{{ output.stdout }}"'
        ios_config:
          lines:
            - logging buffered 30000
          provider: "{{ cli }}"

We can see the execution output here:

    TASK [config example]   
    **********************************************************
    skipping: [ios-r1]
    changed: [ios-r2]

    PLAY RECAP  
    ***********************************************************
    ios-r1 : ok=1 changed=0 unreachable=0 failed=0
    ios-r2 : ok=2 changed=1 unreachable=0 failed=0

Again, note in the execution output that ios-r2 was the only change applied while ios-r1 was skipped. In this case, the logging buffer size was only changed on ios-r2. 

The when clause is also very useful in situations when the setup or facts module is used – you can act based on some of the facts that were gathered initially. For example, the following statement will ensure that only the Ubuntu host with major release 16 will be acted upon by placing a conditional statement in the clause:

when: ansible_os_family == "Debian" and ansible_lsb.major_release|int >= 16