Ansible - How To Work With Debug Module & Register Directive With Examples

This article has two sections where in the first section you will learn about the debug module and how to print information to the terminal. In the second section, you will learn how to capture the command output in a variable using the register directive.

Ansible Default Output

Before going through the debug module usage let’s run a playbook to understand the default output. I am using the following playbook which has one task. The task will use the shell module to run the echo command.

---
- hosts: localhost
  gather_facts: false

 tasks:

   - name: Sample printing tasks
     ansible.builtin.shell: echo "Howdy Ansible learners"

The requirement is to print the echo command output to the terminal. But If you look at the below output, all it printed was the play, task, and status.

$ ansible-playbook playbook.yml 

PLAY [localhost] ********************************************************************************************************************

TASK [Sample printing tasks] ********************************************************************************************************
changed: [localhost]

PLAY RECAP **************************************************************************************************************************
localhost                  : ok=1    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Ansible Debug Module Documentation

The debug module does not have a lot of options so it is quite easy to use. The debug module comes by default with ansible installation.

You can run the following command to check the module availability.

$ ansible-doc -l | grep -i ansible.builtin.debug
ansible.builtin.debug            Print statem...

You can run the following command to access the documentation.

$ ansible-doc debug

Ansible Debug Module

The debug module is similar to the print statement in any programming language. It is used to print variables and expressions to stdout(terminal). The debug module supports three parameters.

msg parameter
var parameter
verbosity parameter

Ansible Debug Module – Msg Parameter

The msg parameter can print variables, strings, list, and dictionary values to stdout. The following playbook contains three tasks.

The first task will print the string to stdout.
The second task will use the variable message and print the string to stdout. You should use jinja2 double curly braces to expand the variable. When the variable comes as the first word you should enclose the entire string with quotes.
Same as the second task but the string is not enclosed with quotes as the variable is not as the first word.

---
- hosts: localhost
  gather_facts: false

  vars:
    message: "Ansible"

  tasks:

   - name: String output
     ansible.builtin.debug:
       msg: "Howdy Ansible learners"

   - name: Print variable with quotes
     ansible.builtin.debug:
       msg: "{{ message }} is fun to learn"
  
   - name: Print variable without quotes
     ansible.builtin.debug:
       msg: latest {{ message }} version

playbook output.

PLAY [localhost] ********************************************************************************************************************

TASK [String output] ****************************************************************************************************************
ok: [localhost] => {
    "msg": "Howdy Ansible learners"
}

TASK [Print variable with quotes] ***************************************************************************************************
ok: [localhost] => {
    "msg": "Ansible is fun to learn"
}

TASK [Print variable without quotes] ************************************************************************************************
ok: [localhost] => {
    "msg": "latest Ansible version"
}

The msg parameter also supports a list and dictionary. I have two tasks defined below. The first and second task prints the same message but syntactically the former is YAML list representation and the latter is python list representation.

 tasks:

   - name: YAML List represntation
     ansible.builtin.debug:
       msg:
         - List value 1
         - List value 2
         - List value 3

   - name: Python List representation
     ansible.builtin.debug:
       msg: ["List value 1", "List value 2", "List value 3"]

In the below output, you can see both task prints the same output.

TASK [YAML List represntation] ******************************************************************************************************
ok: [localhost] => {
    "msg": [
        "List value 1",
        "List value 2",
        "List value 3"
    ]
}

TASK [Python List representation] ***************************************************************************************************
ok: [localhost] => {
    "msg": [
        "List value 1",
        "List value 2",
        "List value 3"
    ]
}

Similar to the list you can create a dictionary either with yaml representation or python representation. In the below code, the first task is yaml representation and the second task is python representation.

   - name: YAML dict representation
     ansible.builtin.debug:
       msg:
         key1: value1
         key2: value2

   - name: Python dict representation
     ansible.builtin.debug:
       msg:
         { key1: value1, key2: value2 }

The below output shows that both tasks return the same dictionary values as the output.

TASK [YAML dict representation] *****************************************************************************************************
ok: [localhost] => {
    "msg": {
        "key1": "value1",
        "key2": "value2"
    }
}

TASK [Python dict representation] ***************************************************************************************************
ok: [localhost] => {
    "msg": {
        "key1": "value1",
        "key2": "value2"
    }
}

Ansible Debug Module – Var Parameter

The var parameter can be used to print just the variable value. Internally the var parameter uses jinja2 syntax so there is no need to explicitly use double curly braces or surround the variable with quotes.

In the following playbook three tasks are defined.

The first task will print the variable.
The second task will print the list variable.
The third task will print the dictionary variable.

 vars:
   CLOUD_PROVIDER: "Azure"
   APP_PLATFORM: ["Webapps", "AKS", "Cosmos DB"]
   TOOLS: {"biceps": yes,
           "pipeline": yes}

 tasks:
   - name: Print provider
     ansible.builtin.debug:
       var: CLOUD_PROVIDER

   - name: Print platform
     ansible.builtin.debug:
       var: APP_PLATFORM

   - name: Print metadata
     ansible.builtin.debug:
       var: TOOLS

Following is the vars output for all three tasks.

TASK [Print provider] ***************************************************************************************************************
ok: [localhost] => {
    "CLOUD_PROVIDER": "Azure"
}

TASK [Print platform] ***************************************************************************************************************
ok: [localhost] => {
    "APP_PLATFORM": [
        "Webapps",
        "AKS",
        "Cosmos DB"
    ]
}

TASK [Print metadata] ***************************************************************************************************************
ok: [localhost] => {
    "METADATA": {
        "biceps": true,
        "pipeline": true
    }
}

Ansible Debug Module – Verbosity

Verbosity enables some additional logging. There are six levels of verbosity in ansible. When running the ansible command you can use the -v flag to enable the verbosity.

-v       => level 1
-vv      => level 2
-vvv     => level 3
-vvvv    => level 4
-vvvvv   => level 5
-vvvvvv  => level 6

You can set the verbosity level using the debug module for a particular task. All you have to do is set the parameter “verbosity: level”.

   - name: Print provider
     ansible.builtin.debug:
       var: CLOUD_PROVIDER
       verbosity: 4

When you set the verbosity at the task level you have to pass the same level of the -v flag when running the ansible-playbook command otherwise it will skip the output.

You can see from the below output the first task was skipped.

$ anisble-playbook playbook.yml 

PLAY [localhost] ********************************************************************************************************************

TASK [Print provider] ***************************************************************************************************************
skipping: [localhost]

When I run the same task with verbosity the output is printed.

$ ansible-playbook playbook.yml -vvvv

TASK [Print provider] ***************************************************************************************************************
task path: /ansible/dockerlab/playbooks/parallelism/playbook.yml:12
ok: [localhost] => {
    "CLOUD_PROVIDER": "Azure"
}

Ansible Register Directive

The ansible register directive stores the task output in a variable which can later be used in other tasks.

tasks:
  - name: Run the uname command
    ansible.builtin.shell: uname -a

I have the following task in the playbook which uses the shell module to run the “uname -a” command. Neither its output will be printed to the terminal nor stored anywhere.

TASK [Run the uname command] ********************************************************************************************************
changed: [localhost]

I can store the command output using the register directive. The register directive should be given a name which is the variable name. Here the variable name is “uname”.

- name: Run the uname command
  ansible.builtin.shell: uname -a
  register: uname

Using the debug module the uname output can be printed.

- name: Run the uname command
  ansible.builtin.debug:
    var: uname

If you look at the above image the uname variable is printed but the output contains information like return code, failed state, changed status, stdout, and stderr.

The uname variable is a dictionary object. The values can be accessed with keys(uname.key). The second task in the below snippet will print only the stdout(uname.stdout) which stores the uname command output. I have also added a conditional check(uname.failed == false) where the task will only run when the previous task is not failed.

tasks:
  - name: Run the uname command
    ansible.builtin.shell: uname -a
    register: uname

  - name: Run this code only when the rc is zero
    ansible.builtin.debug:
      var: uname.stdout
    when: uname.failed == false

Wrap Up

In this article we have seen how to use debug module to print output to stdout and the register directive to capture any command output.

Devops | Dataops | Automation | Cloud