Updated April 6, 2023
Definition
Ansible XML module, which is a part of the General ansible collection module and it supports the various parameters (described in the syntax section) to read the content of the XML file, add or remove the child elements or values, print the specific child attributes or the nodes, change the attribute values, etc. by providing the correct xpath syntax.
Syntax;
For the non-windows target, ansible uses the module syntax community.general.xml, and for the windows target, ansible uses the win_xml module.
Parameters supported by the community.general.xml module.
Parameters:
- add_children:
To add the additional child nodes in the XML file. This parameter requires XPath to be set. To add the child elements, we must provide a string, and each item may be a string like <ansible/> to add an empty element or the hash with the key name and the value.
- attribute:
- The attribute to select when using the parameter value.
- This is a string and not pretended with @.
- backup:
- choices: no (default) / yes
Create the backup file, including the timestamp of the backup. This module doesn’t take the backup automatically; we need to set the backup parameter to yes.
- content: attribute/text
- choices: attribute / text
To search for the given XPath and get or read the content.
- count:
- choices: no (default) / yes
Search for the given XPath and provide the count of any matches.
- input_type:
- choices: xml / yaml (default)
Type of the input for the add_children and set_children.
- insertafter:
- choices: no (default) / yes
It adds the additional child element(s) after the last element given in the Xpath.
- Insertbefore:
- choices: no (default) / yes
It adds the additional child element(s) before the first element given in the Xpath.
- pretty_print:
- choices: no (default) / yes
Pretty print xml output.
- print_match:
- choice: no (default) / yes
Search for the given Xpath and print any output that matches.
- path:
- aliases: dest / file
Path of the XML file as an input. If the XML string is not specified, then the path is required.
- set_children:
To set the child element of the selected element from the given xpath.
- state:
- choices: absent/present
alias: ensure
Set or remove an xpath selection (node(s), attributes(s)).
- value:
Desired state of the selected attribute.
- xmlstring:
A string containing xml on which to operate. This parameter is necessary if the path is not provided.
- xpath:
A valid xpath expression to describe the item(s) to manipulate, and it operates on the document root (/) by default.
How XML works in Ansible?
To deal with the XML files, we need the ansible XML module, and it doesn’t come with the ansible default installation, but we need to install it. It is available as a part of the Ansible community.
To install the XML module, we can use the below command. This will install the XML for both the Unix and the Windows operating systems.
ansible-galaxy collection install community.general
For the Windows operating system, you can use the win_xml module, and for the non-windows target, you can use the community.general.xml module
When you work with the XML file, you need to provide the xPath to deal with the XML attributes and the values. You can learn more about the xPath notations from the websites below.
https://www.w3schools.com/xml/xpath_intro.asp
https://developer.mozilla.org/en-US/docs/Web/XPath
There are also many other websites you can refer to. For this example, we will use the sample XML file from Microsoft.
https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ms762271(v=vs.85)
Playbook example:
Examples
Let us discuss examples of Ansible XML.
Example #1: Ansible XML module to count the number of attribute nodes
In this playbook, we will count the total number of author nodes.
---
- name: Ansible playbook to count the XML nodes.
hosts: localhost
tasks:
- name: Count the books nodes.
xml:
path: /tmp/books.xml
xpath: /catalog/book/author
count: yes
register: hits
- ansible.builtin.debug:
var: hits.count
Output:
There are a total of 12 “author” nodes.
Example #2: Remove the specific node with the attribute value
This playbook will remove all the nodes with the book id attribute bk101.
- name: task to remove the book id
xml:
path: /tmp/books.xml
xpath: /catalog/book[@id='bk101']
state: absent
Output:
Example #3: Playbook to remove attributes
This playbook will remove all the matching attributes. In this case, it will remove the ID attribute.
- name: task to remove the all the id attributes.
xml:
path: /tmp/books.xml
xpath: /catalog/book/@id
state: absent
Output:
Once you check the XML output, all the ids will be removed.
Example #4: Adding the new element with the value
This playbook will add the new element “Newbook” with the value “fiction”.
- name: task to add the element to the xml.
xml:
path: /tmp/books.xml
xpath: /catalog/book[@id='bk101']/newbook
value: 'Fiction'
Output:
Example #5: Playbook to change the attribute value
This playbook will modify the content of the genre attribute from Computer to ComputerTech.
- name: task to add the element to the xml.
xml:
path: /tmp/books.xml
xpath: /catalog/book[@id='bk101']/genre
value: 'ComputerTech'
Output:
XML file output:
Example #6: Ansible playbook to add multiple child elements
This playbook will add the multiple child elements to the specified attributes of the book node.
- name: task to add multiple child elements
xml:
path: /tmp/books.xml
xpath: /catalog/book[@id='bk101']
add_children:
- shop: modern
- owner: jack
- tag: '1001'
Output:
XML file output:
If you need to insert before the specific element, then use the insertbefore parameter. For example,
- name: task to add multiple child elements
xml:
path: /tmp/books.xml
xpath: /catalog/book[@id='bk101']/genre[text() = "Computer"]
insertbefore: yes
add_children:
- shop: modern
- owner: jack
- tag: '1001'
XML Output:
And for the insert after some attribute, you need to specify insertafter parameter.
- name: task to add multiple child elements
xml:
path: /tmp/books.xml
xpath: /catalog/book[@id='bk101']/genre
insertafter: yes
add_children:
- shop: modern
- owner: jack
- tag: '1001'
Conclusion
XML file is used by the various websites, software, configurations, etc. and ansible uses the various parameters to read the content, copy the XML file, manipulate the XML file as per the requirement which helps when you configure any website or software using XML then you can use the builtin plugin to work with the XML file.
Recommended Articles
This is a guide to Ansible XML. Here we discuss the Definition, syntax, parameters, How XML works in Ansible? with Examples with code implementation. You may also have a look at the following articles to learn more –
