Ansible playbooks for iTop

name:: Ansible playbooks for iTop
description:: Set of Ansible playbooks to interact with iTop
version:: 1.0.0
release:: 2023-11-07
itop-version-min:: 2.7
code:: combodo-ansible-playbooks
state:: Stable

This extension is dedicated to Ansible, the application that automates the management of remote systems and controls their desired state. It provides a set of Ansible playbooks that will enable communication between Ansible and iTop applications. Together with the Data model for Ansible extension, it allows Ansible playbooks, tasks or modules to directly fetch in iTop CMDB related information like inventory files or list of hosts to work on. It allows as well the creation and the modification of CIs in iTop.

Features

As everyone knows, Ansible relies on inventories to execute its services. These inventories, files or lists of hosts maintained by an Ansible administrator, can be considered as CMDB information. The CMDB being one of iTop's core features, it may be worth to promote iTop as the central CMDB of its environment by allowing Ansible to retrieve its inventories from iTop and enabling the creation or update, within iTop, of the CIs that Ansible manages, directly from Ansible scripts. This is precisely what the Ansible playbooks for iTop extension is for. It is a toolbox that contains different playbooks to interact with iTop:

The playbooks with a * in the dependency column do require iTop to be configured with the Data model for Ansible extension that provides the WEB services that these playbooks rely on .

Name of the Playbook	Description	Comments	Dependency
itop.list_operations.yml	Get the list of all REST/JSON operations that can be sent to iTop	To be used for test purposes
itop.ansible.get_webservice_version.yml	Get the version of the Ansible web services		*
itop.ansible.get_inventory.yml	Builds and save an inventory file based on the information stored in iTop CMDB		*
itop.ansible.get_hosts_by_oql.yml	Builds an inventory list based on an OQL		*
itop.core.write.yml	Writes a CI in iTop i.e. checks if a CI exists, creates it if not and updates it otherwise
itop.create.virtualmachine.yml	Creates a virtual machine in iTop with predefined attributes	Example to implement itop.core.write.yml playbook
itop.create.logicalinterface.yml	Creates a logical interface in iTop with predefined attributes	Example to implement itop.core.write.yml playbook

Together with these playbooks, the extension provides:

A configuration file that hosts the parameters required by the playbooks,
Ansible security files (itopvault.yml and itoppwd.txt) to secure the access to iTop credentials, should that be needed.

Revision History

Version	Release Date	Comments
1.0.0	2023-09-24	First version

Limitations

None.

Requirements

Usage of the playbooks requires you to comply with a few points:

Ansible must be installed on your server.
Playbooks have been developped with Ansible version 2.9.27, dated September 2021. Therefore, your version cannot be older.
Your Ansible server must be able to reach your iTop servers through HTTPS protocol.

Installation

Do not install this extension in your webserver directories (like apache) otherwise your configuration files (with URLs, credentials) may be accessible from outside.

Simply extend the contents of the zip archive into a folder on the machine where Ansible is installed and from which you want to run the playbooks. You'll get a set of files and directories organized as described in the next chapter:

Structure of the package

The package contains the following directories and files:

data/: directory where is stored the output of the different scripts,
playbooks/: directory where all Ansible playbooks reside,
playbooks/host_vars/: directory that contains the main configuration file,
playbooks/host_vars/localhost.yml: main configuration file,
module.combodo-ansible-playbooks.php: hosts the revision of the extension,
README.md: short description of the extension

Configuration

The Ansible playbooks for iTop do need different set of parameters to run. These are centralized in the file playbooks/host_vars/localhost.yml.

Parameter	Description	Example	Applies to…
General parameters to connect to iTop
itop_root	URL to reach iTop web services	http://10.128.0.14/dev/3.x/current	All playbooks
itop_ws_version	Version of the web services to use	1.3	All playbooks
itop_ws_auth_user	User login	admin	All playbooks
itop_ws_auth_pwd	User password	admin	All playbooks
Inventories related parameters
itop_ws_ansible_uuid	UUID in iTop of the Ansible application to work with	DEMO_UUID	itop.ansible.get_inventory.yml itop.ansible.get_hosts_by_oql.yml
itop_ws_ansible_inventory	Name of the inventory to consider	DMZ-1	itop.ansible.get_inventory.yml itop.ansible.get_hosts_by_oql.yml
itop_ws_ansible_inventory_format	Format of the inventory file	INI / YML	itop.ansible.get_inventory.yml
local_inventory_path	Directory where to store the inventory file on the Ansible controller	../data/	itop.ansible.get_inventory.yml
local_inventory_name	Name of the inventory file	inventory	itop.ansible.get_inventory.yml
backup_inventory	Defines if a backup of the previous inventory file should be made	True / False	itop.ansible.get_inventory.yml
itop_ws_ansible_oql_for_hosts	OQL that defines the list of CIs to retrieve	SELECT VirtualMachine	itop.ansible.get_hosts_by_oql.yml
itop_ws_ansible_attribute	Attribute to consider to build the list	name	itop.ansible.get_hosts_by_oql.yml
hosts_in_file	Save the list in a file	True / False	itop.ansible.get_hosts_by_oql.yml

The itop.core.write.yml playbook needs additionnal parameters which are related to the CI that needs to be created or updated. See below Core write chapter.

For security reasons, authentication parameters may be encrypted in an Ansible vault. For that purpose:

Remove the itop_ws_auth_user and itop_ws_auth_pwd parameters from the playbooks/host_vars/localhost.yml configuration file
Store them then in the playbooks/itopvault.yml file with the appropriate Ansible commands
Optionally store the password that protects the itopvault.yml file into the playbooks/itoppwd.txt file or any other similar file if you want to use it in a non interactive mode
Uncomment the lines that refer to the vault usage in the different playbooks

Add the –vault_id option to the playbook command lines

Interactive mode:

ansible-playbook myplaybook.yml --vault-id=@prompt

Non interactive mode:

ansible-playbook myplaybook.yml --vault-id=/path/to/file/itoppwd.txt

You may refer to Ansible documentation for more details.

Overwriting parameters

Should you wish to overwrite some parameters without changing the configuration file, you may do so through the command line, using the –extra-vars (or -e) argument.

Key/Value format

$ ansible-playbook <my-combodo-ansible-playbook> --extra-vars "parameter1-to-overwrite=new-value1 parameter2-to-overwrite=new-value2"
or
$ ansible-playbook <my-combodo-ansible-playbook> -e "parameter1-to-overwrite=new-value1 parameter2-to-overwrite=new-value2"

JSON string format

$ ansible-playbook <my-combodo-ansible-playbook> -extra-vars '{"parameter1-to-overwrite":"new-value1","parameter2-to-overwrite":"new-value2"}'
or
$ ansible-playbook <my-combodo-ansible-playbook> -e '{"parameter1-to-overwrite":"new-value1","parameter2-to-overwrite":"new-value2"}'

Please, refer to the related Ansible documentation for further details on the subject.

Usage

This chapter lists the different playbooks provided by the extension and explains how they should be used. For each of them, you'll find:

their name,
a description,
wether or not they need the Data model for Ansible extension to be installed on the remote iTop,
the required input parameters,
the output parameters that will be returned,
an example of usage
what main error codes may be encountered.

The playbooks do need to run on the Ansible controller. They are executed against a single host, the localhost for which a set of specific parameters have been defined (see above).

List operations

Playbook name: itop.list_operations.yml

Description: Get the list of all REST/JSON operations that can be sent to iTop

Require Data model for Ansible: No

Input parameters:

itop_root = Root URL of the iTop application
itop_ws_version = Version of iTop REST/JSON API
itop_ws_auth_user = User login
itop_ws_auth_pwd = User password

These parameters are, by default, defined in the ./host_vars/localhost.yml file provided by the extension but can be overwritten in the Ansible command line. See Overwriting parameters section.

Output parameters: None, the result is displayed in the standard output

You will get the list of all the web services known by your iTop Server. The Ansible dedicated web services will appear in this list only if the Data model for Ansible extension has been installed on iTop.

Usage:

$ ansible-playbook itop.list_operations.yml 
 
PLAY [Get from iTop the list of all possible web services] **************************************************************************************************************************************************
 
TASK [Call operation list_operation] ************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Save the Json data] ***********************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Get error code, message and answer] *******************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Display error, if any] ********************************************************************************************************************************************************************************
skipping: [localhost]
 
TASK [Display operations] ***********************************************************************************************************************************************************************************
ok: [localhost] => {
    "operations": [
        {
            "description": "Provide the version currently in use for the iTop WEB services dedicated to Ansible", 
            "extension": "Combodo\\iTop\\Ansible\\Hook\\AnsibleServices", 
            "verb": "ansible/get_webservices_version"
        }, 
        {
            "description": "Get the inventory of an Ansible application", 
            "extension": "Combodo\\iTop\\Ansible\\Hook\\AnsibleServices", 
            "verb": "ansible/get_inventory"
        }, 
        {
            "description": "Get a list of hosts for an the Ansible application", 
            "extension": "Combodo\\iTop\\Ansible\\Hook\\AnsibleServices", 
            "verb": "ansible/get_hosts_by_oql"
        }, 
        {
            "description": "Create an object", 
            "extension": "CoreServices", 
            "verb": "core/create"
        }, 
        {
            "description": "Update an object", 
            "extension": "CoreServices", 
            "verb": "core/update"
        }, 
        {
            "description": "Apply a stimulus to change the state of an object", 
            "extension": "CoreServices", 
            "verb": "core/apply_stimulus"
        }, 
        {
            "description": "Search for objects", 
            "extension": "CoreServices", 
            "verb": "core/get"
        }, 
        {
            "description": "Delete objects", 
            "extension": "CoreServices", 
            "verb": "core/delete"
        }, 
        {
            "description": "Get related objects through the specified relation", 
            "extension": "CoreServices", 
            "verb": "core/get_related"
        }, 
        {
            "description": "Check user credentials", 
            "extension": "CoreServices", 
            "verb": "core/check_credentials"
        }
    ]
}
 
PLAY RECAP **************************************************************************************************************************************************************************************************
localhost                  : ok=4    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0   
 
$

Error codes

Name	Value	Meaning
changed	0	No change is expected since the playbook will just retrieve the list of iTop's web services
failed	0	Other values may indicate that: * iTop is not reachable * the user is not allowed to read iTop's web services

Get Ansible web service version

Playbook name: itop.ansible.get_webservice_version.yml

Description: Get the version of the Ansible web services available in iTop

Require Data model for Ansible: Yes

Input parameters:

itop_root = Root URL of the iTop application
itop_ws_version = Version of iTop REST/JSON API
itop_ws_auth_user = User login
itop_ws_auth_pwd = User password

These parameters are, by default, defined in the ./host_vars/localhost.yml file provided by the extension but can be overwritten in the Ansible command line. See Overwriting parameters section.

Output parameters: None, the result is displayed in the standard output

Usage:

$ ansible-playbook itop.ansible.get_webservice_version.yml 
 
PLAY [Get from iTop the version of the web services dedicated to Ansible] ***********************************************************************************************************************************
 
TASK [Call operation ansible/get_webservices_version] *******************************************************************************************************************************************************
ok: [localhost]
 
TASK [Save the Json data] ***********************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Get error code, message and answer] *******************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Display error, if any] ********************************************************************************************************************************************************************************
skipping: [localhost]
 
TASK [Display message] **************************************************************************************************************************************************************************************
ok: [localhost] => {
    "msg": "Running version of the iTop WEB services dedicated to Ansible is: 1.0"
}
 
PLAY RECAP **************************************************************************************************************************************************************************************************
localhost                  : ok=4    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0   
 
$

Error codes

Name	Value	Meaning
changed	0	No change is expected since the playbook will just retrieve the list of iTop's web services
failed	0	Other values may indicate that: * iTop is not reachable * the user is not allowed to read iTop's web services

Get inventory

Playbook name: itop.ansible.get_inventory.yml

Description: Build and save an inventory file based on the information stored in iTop CMDB

Require Data model for Ansible: Yes

Input parameters:

itop_root = Root URL of the iTop application
itop_ws_version = Version of iTop REST/JSON API
itop_ws_auth_user = User login
itop_ws_auth_pwd = User password
itop_ws_ansible_uuid = UUID of the Ansible application to consider in iTop
itop_ws_ansible_inventory = Name of the inventory in iTop
itop_ws_ansible_inventory_format = Format of the inventory output file (INI or YAML)
local_inventory_path = Path of the output file
local_inventory_name = Name of the output file
backup_inventory = Boolean to define if a backup of the current inventory file should be done or not

These parameters are, by default, defined in the ./host_vars/localhost.yml file provided by the extension but can be overwritten in the Ansible command line. See Overwriting parameters section.

The inventory file will only contain the list of classes that can be attached to an Inventory group. This list is defined through the Data model for Ansible extension.
A warning message is added to the log/error.log file when a CI is rejected from the inventory output for such reason.

Output parameters:

file.date-time = Backup of the previous inventory file, if requested
file = Inventory file

Usage:

$ ansible-playbook itop.ansible.get_inventory.yml 
 
PLAY [Get from iTop the Ansible inventory] ******************************************************************************************************************************************************************
 
TASK [Gathering Facts] **************************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Call operation ansible/get_inventory] *****************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Save the Json data] ***********************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Get error code and message] ***************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Display error, if any] ********************************************************************************************************************************************************************************
skipping: [localhost]
 
TASK [Check that the current inventory file exits] **********************************************************************************************************************************************************
ok: [localhost]
 
TASK [Backup current inventory if it exists] ****************************************************************************************************************************************************************
changed: [localhost]
 
TASK [Get text_file] ****************************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Save result in file] **********************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Set returned variables] *******************************************************************************************************************************************************************************
ok: [localhost]
 
PLAY RECAP **************************************************************************************************************************************************************************************************
localhost                  : ok=9    changed=1    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0   
 
$

Error codes

Name	Value	Meaning
changed	0	The inventory file has not changed and no backup has been performed
	> 0	The inventory file has changed and/or a backup has been performed
failed	0	Other values may indicate that: * iTop is not reachable * the user is not allowed to read iTop's web services * iTop is missing some parameters * iTop failed to generate the inventory

Get hosts by OQL

Playbook name: itop.ansible.get_hosts_by_oql.yml

Description: Build an inventory list based on an OQL.The list can be restricted to the hosts contained within an inventory

Require Data model for Ansible: Yes

Input parameters:

itop_root = Root URL of the iTop application
itop_ws_version = Version of iTop REST/JSON API
itop_ws_auth_user = User login
itop_ws_auth_pwd = User password
itop_ws_ansible_uuid = UUID of the Ansible application to consider in iTop
itop_ws_ansible_inventory = Name of the inventory in iTop
itop_ws_ansible_oql_for_hosts = OQL that defines the list of hosts to consider
itop_ws_ansible_attribute = Attribute of the hosts to be used in the output
hosts_in_file = Boolean to define if the output should be stored in file or not
local_inventory_path = Path to the output file, if any
local_inventory_name = Name of the output file, if any

These parameters are, by default, defined in the ./host_vars/localhost.yml file provided by the extension but can be overwritten in the Ansible command line. See Overwriting parameters section.

The itop_ws_ansible_oql_for_hosts OQL must return a set of CIs that belong to the FunctionalCI class tree.

Note related to the itop_ws_ansible_inventory parameter

If it is left empty, the result will contain all the hosts in iTop defined by the itop_ws_ansible_oql_for_hosts, limited to the list of classes that can be attached to an Inventory group (see the green note below).
If it contains the name of an inventory, the list will be the intersection between the OQL result and the list of hosts contained within the inventory, limited to the list of classes that can be attached to an Inventory group (see the green note below).
It cannot be left undefined, it means that this parameter can not be removed from the ./host_vars/localhost.yml file.

The list of classes that can be attached to an Inventory group is defined through the Data model for Ansible extension.

Output parameters:

file.date-time = Backup of the previous inventory file, if requested
itop_hosts = List of hosts as a string

Usage:

$ ansible-playbook itop.ansible.get_hosts_by_oql.yml 
 
PLAY [Get from iTop a list of hosts defined by an OQL] ******************************************************************************************************************************************************
 
TASK [Gathering Facts] **************************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Call operation ansible/get_hosts_by_oql] **************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Save the Json data] ***********************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Get error code and message] ***************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Display error, if any] ********************************************************************************************************************************************************************************
skipping: [localhost]
 
TASK [Get list of hosts] ************************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Save result in file] **********************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Save list in parameter] *******************************************************************************************************************************************************************************
ok: [localhost]
 
PLAY RECAP **************************************************************************************************************************************************************************************************
localhost                  : ok=7    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0   
 
$

Error codes

Name	Value	Meaning
changed	0	No backup of result has been performed
	> 0	A backup of result has been performed
failed	0	Other values may indicate that: * iTop is not reachable * the user is not allowed to read iTop's web services * iTop is missing some parameters * The OQL is wrong * iTop failed to generate the list of hosts

Core write

Playbook name: itop.core.write.yml

Description: Write a CI to iTop, i.e. check whether a CI exists, create it if it doesn't and update it if it does

Require Data model for Ansible: No

Input parameters:

itop_root = Root URL of the iTop application
itop_ws_version = Version of iTop REST/JSON API
itop_ws_auth_user = User login
itop_ws_auth_pwd = User password
itop_ws_ansible_uuid = UUID of the Ansible application to consider in iTop
obj_class* = Class of CI to be written
key* = Set of attributes to be used for the reconciliation of the CI
fields* = Set of attributes to be used for update or creation
output_fields* = List of attributes to get from iTop once creation or update is done

These parameters are, by default, defined in the ./host_vars/localhost.yml file provided by the extension but can be overwritten in the Ansible command line. See Overwriting parameters section.

You may refer to iTop's wiki about REST/JSON services for more details on the standard parameters that have been identified by a * in the list.

Output parameters:

code = Error code sent by iTop's API
obj_key = Key of the created or updated CI

Usage: In order to help users with the handling of the “core write” playbook, the extension provides 2 examples implemented in 2 playbooks:

itop.create.virtualmachine.yml will create a virtual machine in iTop
itop.create.logicalinterface.yml will create a logical interface in iTop, attached to the virtual machine created by the itop.create.virtualmachine.yml script

For their purpose, the 2 playbooks contain predefined attributes. It is up to the Ansible administrator or developer to provide the attributes that are relevant to them.

The itop.core.write.yml playbook should NOT be modified but invoked from other playbooks developed and owned by the customer.

$ ansible-playbook itop.create.virtualmachine.yml 
 
PLAY [Create a Virtual Machine in iTop] *********************************************************************************************************************************************************************
 
TASK [Gathering Facts] **************************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Set variables for the creation] ***********************************************************************************************************************************************************************
ok: [localhost]
 
PLAY [Write a CI in iTop - update if exists and create if not] **********************************************************************************************************************************************
 
TASK [Gathering Facts] **************************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Call operation core/get] ******************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Save the Json data] ***********************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Get error code and message] ***************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Display error, if any] ********************************************************************************************************************************************************************************
skipping: [localhost]
 
TASK [Get obj_key] ******************************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Get fields] *******************************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Call operation core/create] ***************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Save the Json data] ***********************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Get error code and message] ***************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Display error, if any] ********************************************************************************************************************************************************************************
skipping: [localhost]
 
TASK [Register operation] ***********************************************************************************************************************************************************************************
changed: [localhost]
 
TASK [Call operation core/update] ***************************************************************************************************************************************************************************
skipping: [localhost]
 
TASK [Save the Json data] ***********************************************************************************************************************************************************************************
skipping: [localhost]
 
TASK [Get error code and message] ***************************************************************************************************************************************************************************
skipping: [localhost]
 
TASK [Display error, if any] ********************************************************************************************************************************************************************************
skipping: [localhost]
 
TASK [Get fields] *******************************************************************************************************************************************************************************************
skipping: [localhost]
 
TASK [Register operation] ***********************************************************************************************************************************************************************************
skipping: [localhost]
 
TASK [Get obj_key] ******************************************************************************************************************************************************************************************
ok: [localhost]
 
TASK [Display obj_key] **************************************************************************************************************************************************************************************
ok: [localhost] => {
    "msg": "Object of class VirtualMachine with key ['344'] has been created"
}
 
TASK [Set returned variables] *******************************************************************************************************************************************************************************
ok: [localhost]
 
PLAY RECAP **************************************************************************************************************************************************************************************************
localhost                  : ok=15   changed=1    unreachable=0    failed=0    skipped=8    rescued=0    ignored=0 
 
$

Error codes

Name	Value	Meaning
changed	0	The CI already exists with the given parameters
	> 0	The CI has been created or has been updated with at least a modified attribute
failed	0	Other values may indicate that: * iTop is not reachable * the user is not allowed to read iTop's web services * iTop is missing some parameters * iTop has failed to generate the inventory

The playbook will automatically detect whether or not a modification has been made to the CI by comparing the values of the CI attributes provided by the output_fields parameter.

Sidebar

Ansible playbooks for iTop

Features

Revision History

Limitations

Requirements

Installation

Structure of the package

Configuration

Overwriting parameters

Key/Value format

JSON string format

Usage

List operations

Get Ansible web service version

Get inventory

Get hosts by OQL

Core write

Table of Contents