Getting started

Getting started

Overview

Yaani is a python script used as an Ansible dynamic inventory script. It takes a YAML configuration file in input and dynamically generate a Ansible inventory. It is dumped in JSON format on the standard output. The configuration file is mandatory.

Here is a quick summary of how Yaani works in a few words.

First, it loads its configuration file and start processing its sections in the following order: 1 - Data Sources 2 - Data Sets 3 - Render 4 - Transform (This section is optional)

It first registers data sources, then uses them to extract chunks of data. According to the configuration, Yaani may, in addition, cross-check data against different pieces of information before cherry-picking and rendering specific pieces of data in order to constitute the Ansible inventory. After rendering process, Yaani may optionaly run user custom python code on the inventory.

The execution ends up with Yaani dumping the generated inventory in JSON format on the standard output.

The script may be used multiple ways:

• Along with Ansible
• On a standalone basis
• By importing it in a custom script

The first scenario is the most likely to occur. Yaani script is passed to Ansible in the cli command and its execution is delegated to Ansible. The second scenario is a direct call to Yaani in the cli. The last scenario consists in importing Yaani from another python script.

Those 3 cases are explained in more details in the following sections.

Using Yaani along with Ansible

When using Yaani with Ansible, you have to make sure :

• You set the YAANI_CONFIG_FILE environment variable to point to your configuration file if it is not named netbox.yml and placed in the current directory.
• Yaani has execution rights granted.

At the time you run your playbook, use the -i option to pass yaani.py to Ansible.

ansible[-playbook] -i yaani.py ...

In this case, the inventory script execution is handled by Ansible.

Using Yaani on a standalone basis

When using Yaani on a standalone basis, just execute it as you would execute any python script. It is required that you don't forget to use the --list option to triggers inventory generation. Yaani returns an empty inventory otherwise. If your configuration file is not netbox.yml in the current directory, you may use the YAANI_CONFIG_FILE environment variable or the -c (--config-file) option to specify its location.

This is the standard command:

./yaani.py --list -c config.yml

The resulting inventory is directly dumped in JSON on the standard output. If you need to filter data from it, it is a good idea to use it along with JQ.

./yaani.py --list -c config.yml | jq 'whatever filter you want'

Please note that the --host option does nothing. As a '_meta' key is always returned by the script in the inventory, Ansible does not need to call Yaani with the --host option to discover host variables.

usage: yaani.py [-h] [-c CONFIG_FILE] [--list] [--host HOST]

optional arguments:
  -h, --help            show this help message and exit
  -c CONFIG_FILE, --config-file CONFIG_FILE
                        Path for script's configuration file. If None is
                        specified, default value is YAANI_CONFIG_FILE
                        environment variable or netbox.yml in the current dir.
  --list                Print the entire inventory with hostvars respecting
                        the Ansible dynamic inventory syntax.
  --host HOST           Return an empty inventory.

Importing Yaani in script

It is possible to import Yaani's entry point and to call it from a custom script. For example, take a look at this script.

from yaani import cli
import sys

cli(sys.argv)

Considering that yaani.py is located at the same place as this script, you can import the 'cli' method with the import statement above. The 'cli' method is the main entry point of Yaani, no other method should be used.

Pass on the arguments you want in the same format sys.argv does. For example: ["yaani.py", "--list", "-c", "netbox.yml"]

N. B.: Please note that the first element of the list argument is stripped off the list.

Output structure

The output generated by Yaani is designed to feed Ansible. However, as it can be used without Ansible, it is useful to know the structure of the output.

The output has the following structure:

{
  "_meta": {
    "hostvars": {
      "<host name 1>": {
        /// host vars for host 1
      },
      /// ...
    }
  },
  "<group X>": {
    "hosts": [
      "<host name 1>",
      "<host name 2>",
      "<host name 3>",
    ],
    "vars": {
      /// Ansible group vars
    },
    "children": [
      "<group name 1>",
      "<group name 2>",
    ]
  }
}

The output is a dictionary with two types of key: - '_meta': holds hostvars for every hosts in the nested key "hostvars". This key is always returned. - group keys: all other keys represent a group. A group may contain the following keys: - 'hosts': Mandatory. It a list of host names that belong to the group. - 'vars': Optional. It is the group vars loaded for this group. - 'children': Optional. It is the list of group whose parent is this group.

The whole output is JSON formated.

N. B.: As the '_meta' key is always returned, Ansible does not try to use the option '--host' on the script.

If the '--list' option is not activated when using Yaani, an empty dict is returned:

{
  "_meta": {
    "hostvars": {}
  }
}

For more information, please visit https://docs.ansible.com/ansible/latest/dev_guide/developing_inventory.html#developing-inventory-scripts.

Environment variables

Yaani uses 2 environment variables:

• YAANI_CONFIG_FILE: This variable is used to indicate to Yaani where is the configuration file you want to use. If not set, the default behaviour is to try to open netbox.yml in the current folder.
• YAANI_MODULES_PATH: This variable indicates Yaani the base folder of your custom modules when using the transform feature. The default value for this path is the folder 'modules' in the current directory.