Updated May 17, 2023
Introduction to Ansible Register
Ansible register is a way to capture the output from task execution and store it in a variable. This is an important feature, as this output is different for each remote host, and the basis on that, we can use conditions loops to do some other tasks. Also, each register value is valid throughout the playbook execution. So, we can use set_fact to manipulate the data and provide input to other tasks accordingly. In this article, we will learn and see examples of using registers in different scenarios. We will also see how only a piece of information in the registered variable can be used.
Ansible Register
For any task output, which we register in a variable, it is stored in a pre-defined format in JSON. We will get different outputs for different tasks, which are stored as defined in Ansible documentation. When we see the output, we will see the values as per Ansible documentation, and some fields are shown in each output like changed.
Below is an output from a task where we tried to copy a file from the control node to the remote node. We registered it and displayed the registered variable below:
How does Ansible Register work?
You will store the output of your task in these variables on the Ansible Control Server. In simple words, when you want to run a command on a remote computer, store the output in a variable, and use a piece of information from the output later in your plays. This kind of usage is possible by registered variables. This functionality is similar to the system Facts, which the setup module discovers and fetches. In this case, you save the output of any command you run in JSON format and then utilize that information like facts.
For another reference for a playbook with content like the below:
- hosts: host-one tasks: name: check HTTP status command: service httpd status register: output_var
- name: display the output of the above execution debug: var: output_var
We are checking the status of the httpd service on a remote server named host-one. You will see that; In the following output, we obtained comprehensive details about the command executed on the remote host. Similarly, when we run any other module and store its output in a variable, we can access similarly detailed information. We will notice all details about the task execution, and related information will be seen in JSON fields.
You will see most of the fields in the output; we will try to explore some of those.
- changed – this will be true or false based on the state of remote hosts. If the state changes, then it will contain true, else it will contain
- cmd – This is a command which ran on the remote host
- delta – the time taken to execute the command
- end – end date and time when the task completed
- failed – if a task failed or not, it has true or false values
- RC – return code
- start – start date and time of a task
- stderr – the standard error message in a single line
- stderr_lines – the standard error message in separate lines
- stdout – the output in a single line
- stdout_lines – the output in separate lines
Examples to Implement Ansible Register
Using examples, we will learn about the ansible register, which you might have to use in day-to-day operations. We will take some examples, but before going there, we first understand our lab used for testing.
Here we have an Ansible control server named ansible-controller and two remote hosts named host-one and host-two. We will create playbooks, run Ansible commands on the ansible-controller node, and manage the information from remote hosts for executed tasks.
Example #1
In the example below, we try to find the .txt files on remote nodes, capture the output in a variable, and then display that variable find_output. For this, first, see the contents of the playbook like
Code:
- hosts: all tasks:
name: find all txt files in /tmp shell: "find /tmp -name *.txt" register: find_output
debug:
var: find_output
After executing it, we will see the below output; in this output, under stdout_lines, we will know the name of files that are found.
Output:
ansible-playbook register_variable_task_find.yaml
Example #2
If you want to see the files only, then update the playbook and make the debug task like the below:
Code:
- debug:
var: find_output.stdout_lines
Output:
ansible-playbook register_variable_task_find.yaml
Example #3
In this example, we check the remote host’s free memory and uptime. We create a playbook like the one below. Here we used stdout_lines to display only the output of
Code:
---
hosts: host-two tasks:
name: To check the uptime of remote host command: uptime
register: uptime_var
name: To check free memory on remote host shell: free -m
register: free_var
debug:
var: "{{ item }}" loop:
stdout_lines
stdout_lines
Output:
ansible-playbook register_multiple_variable.yaml
Example #4
In the below example, we use a condition by when and check whether a file exists or nor on remote hosts. If the file does not exist, then create it. Else, skip creation. We check the file’s existence simply by ls and checking the return code. In Linux, is any command is successful, then the return code is zero, else it is non-zero. We create a sample playbook like the one below:
Code:
---
hosts: all tasks:
name: check whether /tmp/test1.txt exists or not command: ls /tmp/test1.txt
register: check_rc_var ignore_errors: yes
debug:
var: check_rc_var.rc
name: create file /tmp/test1.txt when it doesn't exists already file:
path: /tmp/test1.txt state: touch
when: check_rc_var.rc != 0
When deploying this playbook, we will see the output below. You can see that the playbook displayed an error message and returned a non-zero code on the remote host where the file does not exist. On the remote host where the file exists, the task state changed as the “ls” command ran successfully. In this case, the return code will be zero. Based on this information, we can conclude that the file was created on host two and skipped on host one.
Output:
ansible-playbook register_condition.yaml
Conclusion
In Ansible, using a register is very helpful, especially in the production environment. The feasibility of capturing output differently for different remote nodes is very useful. Also, as the output is stored in JSON, reading and parsing it is easy for other tools as input. So learn it and use it wisely.
Recommended Articles
This is a guide to Ansible Register. Here we discuss an introduction to Ansible Register and how it works with respective examples. You can also go through our other related articles to learn more –
