Adapter requests and responses for the Ansible adapter

This topic describes the input and output XML elements, and sample XML requests and responses for the operations supported by the Ansible adapter. 

When you use a context item as an input for an adapter request, you must enclose the adapter request in the <request-data> elements. However, when you create a static request, <request-data> is not required and the adapter request starts with the <ansible-request> element.

Ansible Command operation

The command line interface is used to run a single command on the managed nodes. The host on which Ansible is installed is known as the Control node. Managed nodes are the networks, or devices to be managed by Ansible. 

The following table describes the input XML elements for the adapter request.

Input element

Description

Required

<ansible-request>

Contains the elements required to run the adapter request.

Yes

<operation-name>

Specifies the name of the operation.

Valid value: ansible-command

Yes

<inventory-file-path>

Specifies the inventory file in which managed nodes (remote hosts) are defined.

If not specified, then the default /etc/ansible/hosts file is considered for this command.

No

<inventory-group>

Specifies the group name of the managed nodes defined in inventory file.

No

<command-module>

Specifies the name of the Ansible command module to run the command.

Default module is command.

No

<target>

Contains the connection details of the Ansible control node required for the adapter request.

Conditional;required if not specified in the adapter configuration.

<host>

Specifies the host name where the Ansible control node is installed.

No

<user-name>

Specifies the username required to log on to the Ansible control node.

No

<password>

Specifies the password.


No

<private-key-file>

Specifies the the path and file name of the local SSH key file.

The key file must be on the peer which runs the adapter request. This element is used if the <password> element is not provided. If both are provided, the adapter ignores the <password> element and considers <private-key-file> during the adapter request.

No

<command>

Specifies the Ansible command, inside a <commands> element, to be run on the managed nodes.

Currently, the adapter only supports one command and does not take any input if the command execution prompts for any further input from user.

Sample <command>
<commands>
 <command  timeout-secs="500" >hostname</command>
</commands>

No

<cli-options>

Contains the <option> elements used to specify Ansible command options.

No

<option>

Specifies the Ansible command CLI options. You can specify more than one <option> element in the <cli-options> element.

No

The following figure shows a sample XML request with target details provided in the request. 

<ansible-request>
     <operation-name>ansible-command</operation-name>
     <target>
         <host>hostname</host>
         <user-name>root</user-name>
         <password>password</password>
         <timeout-secs>70</timeout-secs>
         <allow-unknown-hosts>true</allow-unknown-hosts>
         <character-set>UTF-8</character-set>
     </target>
     <inventory-file-path>/etc/ansible/host_inventory1</inventory-file-path>
     <inventory-group>linuxusers</inventory-group>
     <cli-options>
     <!-- This will add the command arguments switch with value except inventory  -->
         <option></option>
         <option></option>
         <option></option>
         <option></option>
         <option></option>
     </cli-options>
     <command-module>command</command-module>
     <commands>
       <command  timeout-secs="500" >hostname</command>
     </commands>
 </ansible-request>

The following figure shows the adapter response for the request. 

<ansible-response>
 <metadata>
   <status>success</status>
 </metadata>
 <targets-output>
   <target-output host="hostname">
     <metadata>
       <os-id>Linux</os-id>
       <os-version>4.1.12-112.14.13.el7uek.x86_64</os-version>
       <status>success</status>
     </metadata>
     <commands-output>
       <command-output>
         <metadata>
           <command>ansible  linuxusers  -i /etc/ansible/host_inventory1  -m command  -a "hostname"</command>
           <line-count>4</line-count>
           <execution-milliseconds>1934</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1">hostname | CHANGED | rc=0 &gt;&gt;</line>
           <line index="2">hostname</line>
           <line index="3">hostname | CHANGED | rc=0 &gt;&gt;</line>
           <line index="4">hostname</line>
         </output>
       </command-output>
     </commands-output>
   </target-output>
 </targets-output>
</ansible-response>

The following figure shows a sample adapter request where the target is specified in the adapter configuration. 

<ansible-request>
   <operation-name>ansible-command</operation-name>
   <inventory-file-path>/etc/ansible/custom_inventory1</inventory-file-path>
   <inventory-group></inventory-group>
   <cli-options>
       <!-- This will add the command arguments switch with value except inventory  -->
       <option></option>
       <option></option>
       <option></option>
       <option></option>
       <option></option>
   </cli-options>
   <command-module>raw</command-module>
   <commands>
       <command  timeout-secs="500" >ifconfig</command>
   </commands>
</ansible-request>

The following figure shows the adapter response. 

<ansible-response>
 <metadata>
   <status>success</status>
 </metadata>
 <targets-output>
   <target-output host="hostname">
     <metadata>
       <os-id>Linux</os-id>
       <os-version>3.10.0-957.27.2.el7.x86_64</os-version>
       <status>success</status>
     </metadata>
     <commands-output>
       <command-output>
         <metadata>
           <command>ansible  all  -i /etc/ansible/custom_inventory1  -m raw  -a "ifconfig"</command>
           <line-count>59</line-count>
           <execution-milliseconds>1172</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1">hostname | CHANGED | rc=0 &gt;&gt;</line>
           <line index="2">ens192: flags=4163&lt;UP,BROADCAST,RUNNING,MULTICAST&gt;  mtu 1500&#xD;</line>
           <line index="3">        inet 10.135.55.47  netmask 255.255.224.0  broadcast 10.135.63.255&#xD;</line>
           <line index="4">        inet6 fe80::250:56ff:fe8f:f9cf  prefixlen 64  scopeid 0x20&lt;link&gt;&#xD;</line>
           <line index="5">        ether 00:50:56:8f:f9:cf  txqueuelen 1000  (Ethernet)&#xD;</line>
           <line index="6">        RX packets 198522918  bytes 17231064021 (16.0 GiB)&#xD;</line>
           <line index="7">        RX errors 1  dropped 0  overruns 0  frame 0&#xD;</line>
           <line index="8">        TX packets 89811  bytes 7152966 (6.8 MiB)&#xD;</line>
           <line index="9">        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0&#xD;</line>
           <line index="10">&#xD;</line>
           <line index="11">ens224: flags=4163&lt;UP,BROADCAST,RUNNING,MULTICAST&gt;  mtu 1500&#xD;</line>
           <line index="12">        inet 10.135.23.118  netmask 255.255.224.0  broadcast 10.135.31.255&#xD;</line>
           <line index="13">        inet6 fe80::250:56ff:fe8f:e388  prefixlen 64  scopeid 0x20&lt;link&gt;&#xD;</line>
           <line index="14">        ether 00:50:56:8f:e3:88  txqueuelen 1000  (Ethernet)&#xD;</line>
           <line index="15">        RX packets 981859504  bytes 63401500208 (59.0 GiB)&#xD;</line>
           <line index="16">        RX errors 1  dropped 0  overruns 0  frame 0&#xD;</line>
           <line index="17">        TX packets 859927  bytes 37146021 (35.4 MiB)&#xD;</line>
           <line index="18">        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0&#xD;</line>
           <line index="19">&#xD;</line>
           <line index="20">lo: flags=73&lt;UP,LOOPBACK,RUNNING&gt;  mtu 65536&#xD;</line>
           <line index="21">        inet 127.0.0.1  netmask 255.0.0.0&#xD;</line>
           <line index="22">        inet6 ::1  prefixlen 128  scopeid 0x10&lt;host&gt;&#xD;</line>
           <line index="23">        loop  txqueuelen 1000  (Local Loopback)&#xD;</line>
           <line index="24">        RX packets 280736  bytes 99815602 (95.1 MiB)&#xD;</line>
           <line index="25">        RX errors 0  dropped 0  overruns 0  frame 0&#xD;</line>
           <line index="26">        TX packets 280736  bytes 99815602 (95.1 MiB)&#xD;</line>
           <line index="27">        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0&#xD;</line>
           <line index="28">&#xD;</line>
           <line index="29">Shared connection to hostname closed.&#xD;</line>
           <line index="30"></line>
           <line index="31">hostname | CHANGED | rc=0 &gt;&gt;</line>
           <line index="32">ens160: flags=4163&lt;UP,BROADCAST,RUNNING,MULTICAST&gt;  mtu 1500&#xD;</line>
           <line index="33">        inet 10.135.39.4  netmask 255.255.224.0  broadcast 10.135.63.255&#xD;</line>
           <line index="34">        inet6 fe80::250:56ff:fe8f:a69  prefixlen 64  scopeid 0x20&lt;link&gt;&#xD;</line>
           <line index="35">        ether 00:50:56:8f:0a:69  txqueuelen 1000  (Ethernet)&#xD;</line>
           <line index="36">        RX packets 35143267  bytes 3155001683 (2.9 GiB)&#xD;</line>
           <line index="37">        RX errors 0  dropped 6  overruns 0  frame 0&#xD;</line>
           <line index="38">        TX packets 7730  bytes 1704900 (1.6 MiB)&#xD;</line>
           <line index="39">        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0&#xD;</line>
           <line index="40">&#xD;</line>
           <line index="41">ens192: flags=4163&lt;UP,BROADCAST,RUNNING,MULTICAST&gt;  mtu 1500&#xD;</line>
           <line index="42">        inet 10.135.7.139  netmask 255.255.224.0  broadcast 10.135.31.255&#xD;</line>
           <line index="43">        inet6 fe80::250:56ff:fe8f:5979  prefixlen 64  scopeid 0x20&lt;link&gt;&#xD;</line>
           <line index="44">        ether 00:50:56:8f:59:79  txqueuelen 1000  (Ethernet)&#xD;</line>
           <line index="45">        RX packets 150631007  bytes 9863768018 (9.1 GiB)&#xD;</line>
           <line index="46">        RX errors 0  dropped 6  overruns 0  frame 0&#xD;</line>
           <line index="47">        TX packets 119565  bytes 5210250 (4.9 MiB)&#xD;</line>
           <line index="48">        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0&#xD;</line>
           <line index="49">&#xD;</line>
           <line index="50">lo: flags=73&lt;UP,LOOPBACK,RUNNING&gt;  mtu 65536&#xD;</line>
           <line index="51">        inet 127.0.0.1  netmask 255.0.0.0&#xD;</line>
           <line index="52">        inet6 ::1  prefixlen 128  scopeid 0x10&lt;host&gt;&#xD;</line>
           <line index="53">        loop  txqueuelen 0  (Local Loopback)&#xD;</line>
           <line index="54">        RX packets 37782  bytes 13447524 (12.8 MiB)&#xD;</line>
           <line index="55">        RX errors 0  dropped 0  overruns 0  frame 0&#xD;</line>
           <line index="56">        TX packets 37782  bytes 13447524 (12.8 MiB)&#xD;</line>
           <line index="57">        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0&#xD;</line>
           <line index="58">&#xD;</line>
           <line index="59">Shared connection to hostname closed.&#xD;</line>
         </output>
       </command-output>
     </commands-output>
   </target-output>
 </targets-output>
</ansible-response>

The following figure shows the sample adapter request with the cli-options element. 

<ansible-request>
   <operation-name>ansible-command</operation-name>
   <target>
     <host>hostname</host>
     <user-name>root</user-name>
     <password>****MASKED****</password>
     <timeout-secs>70</timeout-secs>
     <allow-unknown-hosts>true</allow-unknown-hosts>
     <character-set>UTF-8</character-set>
   </target>
   <inventory-file-path>/etc/ansible/host_inventory1</inventory-file-path>
   <inventory-group>linuxusers</inventory-group>
   <cli-options>
     <!-- This will add the command arguments switch with value except inventory  -->
     <option>-b --become-user=ansibleUser1</option>
     <option />
   </cli-options>
   <command-module>command</command-module>
   <commands>
     <command timeout-secs="500">whoami</command>
   </commands>
</ansible-request>

The following figure shows the adapter response.

<ansible-response>
 <metadata>
   <status>success</status>
 </metadata>
 <targets-output>
   <target-output host="hostname">
     <metadata>
       <os-id>Linux</os-id>
       <os-version>4.1.12-112.14.13.el7uek.x86_64</os-version>
       <status>success</status>
     </metadata>
     <commands-output>
       <command-output>
         <metadata>
           <command>ansible  linuxusers  -i /etc/ansible/host_inventory1  -m command  -b --become-user=ansibleUser1  -a "whoami"</command>
           <line-count>4</line-count>
           <execution-milliseconds>1936</execution-milliseconds>
           <exit-code>2</exit-code>
           <status>error</status>
           <error>Exit code indicates error</error>
         </metadata>
         <output>
           <line index="1">hostname | FAILED | rc=-1 &gt;&gt;</line>
           <line index="2">Failed to change ownership of the temporary files Ansible needs to create despite connecting as a privileged user. Unprivileged become user would be unable to read the file.</line>
           <line index="3">hostname | CHANGED | rc=0 &gt;&gt;</line>
           <line index="4">ansibleUser1</line>
         </output>
       </command-output>
     </commands-output>
   </target-output>
 </targets-output>
</ansible-response>


Ansible Playbook operation

This operation executes the ansible playbook, which contains the list of defined tasks to be executed on managed nodes.

The following table describes the input XML elements for the adapter request.

Input element

Description

Required

<ansible-request>

Contains the elements required to run the adapter request.

Yes

<operation-name>

Specifies the name of the operation.

Valid value: ansible-playbook

Yes

<inventory-file-path>

Specifies the path to the inventory file in which managed nodes (remote hosts) are defined.

If not specified, /etc/ansible/hosts file is considered by default for this command.

No

<playbook>

Specifies the name of the playbook, inside a <commands> element, which contains the tasks to be executed on the managed hosts.

Playbook is a YAML file.

Currently, the adapter only supports one <playbook> element within the commands> element, and does not take any input if the playbook command execution prompts for any further input from user.

Sample <playbook>
<commands>
       <playbook  timeout-secs="70" >/etc/ansible/sampleyml.yml</playbook>
</commands>

Yes

<target>

Contains the connection details of the Ansible control node required for the adapter request.

Conditional;required if not specified in the adapter configuration.

<host>

Specifies the host name where the Ansible control node is installed.

No

<user-name>

Specifies the username required to log on to the Ansible control node.

No

<password>

Specifies the password.

No

<private-key-file>

Specifies the the path and file name of the local SSH key file.

The key file must be on the peer which runs the adapter request. This element is used if the <password> element is not provided. If both are provided, the adapter ignores the <password> element and considers <private-key-file> during the adapter request.

No

<cli-options>

Contains the <option> elements used to specify Ansible command options.

No

<option>

Specifies the Ansible command CLI options.

You can specify more than one <option> element in the <cli-options> element.


No

The following figure shows a sample XML request with a <target> defined in the request. 

<ansible-request>
   <operation-name>ansible-playbook</operation-name>
   <target>
       <host>clm-XXX-YYY</host>
       <user-name>AnsibleUser</user-name>
       <password>*****MASKED******</password>
       <timeout-secs>70</timeout-secs>
       <allow-unknown-hosts>true</allow-unknown-hosts>
       <character-set>UTF-8</character-set>
   </target>
   <inventory-file-path></inventory-file-path>
   <cli-options>
       <!-- This will add the command arguments switch with value except inventory  -->
       <option></option>
       <option></option>
       <option></option>
   </cli-options>
   <commands>
       <playbook  timeout-secs="70" >/etc/ansible/sampleyml.yml</playbook>
   </commands>
</ansible-request>

The following figure shows the adapter response for the request. 

<ansible-response>
 <metadata>
   <status>success</status>
 </metadata>
 <targets-output>
   <target-output host="clm-XXX-YYY">
     <metadata>
       <os-id>Linux</os-id>
       <os-version>4.1.12-112.14.13.el7uek.x86_64</os-version>
       <status>success</status>
     </metadata>
     <commands-output>
       <command-output>
         <metadata>
           <command>ansible-playbook  /etc/ansible/sampleyml.yml  </command>
           <line-count>8</line-count>
           <execution-milliseconds>2668</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1"></line>
           <line index="2">PLAY [rhel8] *******************************************************************</line>
           <line index="3"></line>
           <line index="4">TASK [Gathering Facts] *********************************************************</line>
           <line index="5">ok: [hostname]</line>
           <line index="6"></line>
           <line index="7">PLAY RECAP *********************************************************************</line>
           <line index="8">hostname             : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   </line>
         </output>
       </command-output>
     </commands-output>
   </target-output>
 </targets-output>
</ansible-response>

The following figure shows a sample XML request with <target> defined in the adapter configuration. 

<ansible-request>
   <operation-name>ansible-playbook</operation-name>
   <inventory-file-path></inventory-file-path>
   <cli-options>
       <!-- This will add the command arguments switch with value except inventory  -->
       <option></option>
       <option></option>
       <option></option>
   </cli-options>
   <commands>
       <playbook  timeout-secs="70" >/etc/ansible/sampleyml.yml</playbook>
   </commands>
</ansible-request>

The following figure shows the adapter response for the request.

<ansible-response>
 <metadata>
   <status>success</status>
 </metadata>
 <targets-output>
   <target-output host="clm-XXX-YYY">
     <metadata>
       <os-id>Linux</os-id>
       <os-version>4.1.12-112.14.13.el7uek.x86_64</os-version>
       <status>success</status>
     </metadata>
     <commands-output>
       <command-output>
         <metadata>
           <command>ansible-playbook  /etc/ansible/sampleyml.yml  </command>
           <line-count>8</line-count>
           <execution-milliseconds>2668</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1"></line>
           <line index="2">PLAY [rhel8] *******************************************************************</line>
           <line index="3"></line>
           <line index="4">TASK [Gathering Facts] *********************************************************</line>
           <line index="5">ok: [clm-pun-123XYZ]</line>
           <line index="6"></line>
           <line index="7">PLAY RECAP *********************************************************************</line>
           <line index="8">clm-pun-123XYZ             : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   </line>
         </output>
       </command-output>
     </commands-output>
   </target-output>
 </targets-output>
</ansible-response>

The following figure shows a sample XML request with <cli-options> in the request. 

<ansible-request>
   <operation-name>ansible-playbook</operation-name>
   <target>
     <host>clm-pun-zzzz</host>
     <user-name>root</user-name>
     <password>****MASKED****</password>
     <timeout-secs>70</timeout-secs>
     <allow-unknown-hosts>true</allow-unknown-hosts>
     <character-set>UTF-8</character-set>
   </target>
   <inventory-file-path />
   <cli-options>
     <!-- This will add the command arguments switch with value except inventory  -->
     <option>-C</option>
     <option />
     <option />
   </cli-options>
  <commands>
       <playbook  timeout-secs="70" >/etc/ansible/sampleyml.yml</playbook>
  </commands>
 </ansible-request>

The following figure shows the adapter response for the request.

<ansible-response>
 <metadata>
   <status>success</status>
 </metadata>
 <targets-output>
   <target-output host="clm-pun-zzzz">
     <metadata>
       <os-id>Linux</os-id>
       <os-version>4.1.12-112.14.13.el7uek.x86_64</os-version>
       <status>success</status>
     </metadata>
     <commands-output>
       <command-output>
         <metadata>
           <command>ansible-playbook  /etc/ansible/sampleyml.yml  -C </command>
           <line-count>8</line-count>
           <execution-milliseconds>2531</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1"></line>
           <line index="2">PLAY [rhel8] *******************************************************************</line>
           <line index="3"></line>
           <line index="4">TASK [Gathering Facts] *********************************************************</line>
           <line index="5">ok: [clm-ind-12345]</line>
           <line index="6"></line>
           <line index="7">PLAY RECAP *********************************************************************</line>
           <line index="8">hostname          : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   </line>
         </output>
       </command-output>
     </commands-output>
   </target-output>
 </targets-output>
</ansible-response>

The following figure shows a sample XML request with <private-key-authentication> and <inventory-file> path in the adapter request.

<ansible-request>
   <operation-name>ansible-playbook</operation-name>
   <target name="">
       <host>clm-pun-123pqr</host>
       <port>22</port>
       <userName>ansibleuser</userName>
       <private-key-file>C:\temp\ansibleuser_clm-pun-abcd1234.ppk</private-key-file>
       <timeout-secs>60</timeout-secs>
       <allow-unknown-hosts>true</allow-unknown-hosts>
       <character-set>UTF-8</character-set>
   </target>
   <inventory-file-path>/etc/ansible/host_inventory1</inventory-file-path>
   <commands>
       <playbook  timeout-secs="70" >/etc/ansible/sampleyml.yml</playbook>
   </commands>
</ansible-request>

The following figure shows the adapter response for the request.

<ansible-response>
 <metadata>
   <status>success</status>
 </metadata>
 <targets-output>
   <target-output host="clm-pun-123pqr">
     <metadata>
       <os-id>Linux</os-id>
       <os-version>4.1.12-112.14.13.el7uek.x86_64</os-version>
       <status>success</status>
     </metadata>
     <commands-output>
       <command-output>
         <metadata>
           <command>ansible-playbook  /etc/ansible/sampleymlInventoryFile.yml  -i /etc/ansible/host_inventory1  </command>
           <line-count>10</line-count>
           <execution-milliseconds>2438</execution-milliseconds>
           <exit-code>0</exit-code>
           <status>success</status>
         </metadata>
         <output>
           <line index="1"></line>
           <line index="2">PLAY [linuxusers] **************************************************************</line>
           <line index="3"></line>
           <line index="4">TASK [Gathering Facts] *********************************************************</line>
           <line index="5">ok: [hostname]</line>
           <line index="6">ok: [hostname]</line>
           <line index="7"></line>
           <line index="8">PLAY RECAP *********************************************************************</line>
           <line index="9">hostname    : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   </line>
           <line index="10">hostname   : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   </line>
         </output>
       </command-output>
     </commands-output>
   </target-output>
 </targets-output>
</ansible-response>

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*