Ansible module return values

Return values are the key feature for monitoring and managing task execution. An administrator can determine the status of each action and run other tasks accordingly, either to fix, improve, or follow up on the bigger job. Ansible modules are fitted with a variety of return values. Each module will have the common values and some extra specific ones for the role performed by the module. These extra return values can be used for numerous functionalities. In Ansible, most return values are used as input for playbook conditions and loops. This scripting allows the pipelining of actions and tasks to achieve an automated configuration management. Ansible basically collects all the useful output data about the action performed by the module and arranges it into variables presented as return values.

As for the most common return values, we can identify the following:

• stdout or stdout_lines: This is the variable that contains the standard output of commands executed using an execution module such as raw, command, shell, or win_shell. The stdout_lines have the same value and string as stdout but they have a more organized output—a human-readable text divided into lines.
• stderr or stderr_lines: This has the same output source as stdout, but this is the error message output. If the command executed returns an error message, it will be stored in this variable. The stderr_lines also have the same output string as stderr but are more organized into lines.
• changed: This is the return value that indicates the status of the task or action if the task has made a change to the target host. It will contain a Boolean value of True or False.
• failed: This is another status update return value that indicates whether the task or action has failed or not. It is also a Boolean value that can be either True or False.
• skipped: This is another status return value that indicates whether the task has been skipped. This occurs when a task has been triggered by a playbook condition and the condition was not met. Like the other status return values, it is a Boolean variable.
• rc: This stands for return code. It contains the return code generated by the command that is executed by the command execution modules.
• results: This a value that does not exist in a task unless it has a loop in it. It should contain the list of the normal module result per item used to loop on.
• invocation: This is a value that contains the method detailing how the module was invoked.
• backup_file: This is a value that gets filled when a module has the specific backup=no|yes option. It states the location where the backup file has been created.
• msg: This is a value containing the message that gets generated by the module to the Ansible user.

The common values get collected during the execution of the task using a register, and then are either called for by the playbook condition functions or just printed using a debugger:

---
- name: Restart Linux hosts if reboot is required after updates
  hosts: servers
  gather_facts: false
  tasks:
    - name: check for updates
      become: yes
      become_method: sudo
      apt: update_cache=yes
 
    - name: apply updates
      become: yes
      become_method: sudo
      apt: upgrade=yes 

    - name: check if reboot is required
      become: yes
      become_method: sudo
      shell: "[ -f /var/run/reboot-required ]"
      failed_when: False
      register: reboot_required
      changed_when: reboot_required.rc == 0
      notify: reboot
 
  handlers:
    - name: reboot
      command: shutdown -r now "Ansible triggered reboot after system updated"
      async: 0
      poll: 0
      ignore_errors: true

This playbook will have the following output:

Using the debugger, we can easily specify that we want one or all of the return values to be printed. The playbook task should look as follows:

    - name: apply updates
      become: yes
      become_method: sudo
      apt: upgrade=yes
      register: output

    - name: print system update status return value
      debug:
           var: output.changed

Ansible also collects some extra values to be used for internal Ansible functionalities. These values are ansible_facts, exception, warning, and deprecations. They can be added by some modules to be later removed from the register variables and collected by Ansible.