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 make use of set_fact to manipulate the data and provide input to other tasks accordingly. In this article we will learn and see examples of using register 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. For different tasks we will get different output and it is stored in the way it is defined in ansible documentation. When we see the output we will see the values as per ansible documentation and some fields which will be 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 like below:
How does Ansible Register work?
These are the variables in which the output of your task will be stored on the Ansible Control Server. In simple words, when you want to run a command on a remote computer and then 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. It is somehow like the system Facts which are discovered and fetched by setup module. Here whatever command you run its output will be saved in JSON format and then you use that information the same as you used facts.
For another reference for a playbook with content like 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
In which we are checking the status of httpd service on a remote server named host-one. You will see that; in the below output we got every small detail about the command executed on the remote host. Similarly when we run any other module and register its output in a variable. We will notice all details about the task execution and related information will be seen in JSON fields.
4.5 (4,919 ratings)
View Course
you will see most of the fields in output, we try to explore some of those.
- changed – this will be true or false based on the state of remote hosts if the state changed 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
Now by using examples, we will try to 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 purposes.
Here we have an Ansible control server named ansible-controller and two remotes hosts named host- one and host-two. We will create playbooks and run Ansible commands on the ansible-controller node and manage the information from remote hosts for executed tasks
Example #1
In the below example, we try to find the .txt files on remote nodes and capture the output in a variable, then will 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 below output, in this output under stdout_lines we will see 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 below:
Code:
- debug:
var: find_output.stdout_lines
Output:
ansible-playbook register_variable_task_find.yaml
Example #3
In this example, we are checking the free memory and uptime on the remote host. We create a playbook like 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 check the return code. In Linux, is any command is successful, then return code is zero, else it is non-zero. We create a sample playbook like 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 as below. Here you can see, on the remote host where the file does not exist, playbook showed an error message and return code will be non-zero and on the remote host where the file exists, it showed task state as changed as ls command ran successfully, also in this case return code will be zero. So, on this basis, the file was created on host- two and skipped on host-one.
Output:
ansible-playbook register_condition.yaml
Conclusion
In Ansible, using register is very helpful especially in the production environment. The feasibility to capture output differently for different remote nodes is very useful. Also, as the output is stored in JSON, reading and parsing it 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, how does it work with respective examples. You can also go through our other related articles to learn more –
