OpenStack-Ansible Inventory¶

OpenStack-Ansible uses an included script to generate the inventory of hosts and containers within the environment. This script is called by Ansible through its dynamic inventory functionality.

Generating the Inventory¶

The script that creates the inventory is located at playbooks/inventory/dynamic_inventory.py.

Execution¶

When running an Ansible command (such as ansible, ansible-playbook or openstack-ansible) Ansible will execute the dynamic_inventory.py script and use its output as inventory.

The command can also be run manually as follows:

# from the playbooks directory
inventory/dynamic_inventory.py --config /etc/openstack_deploy/

This invocation is useful when testing changes to the dynamic inventory script.

Inputs¶

The dynamic_inventory.py takes the --config argument for the directory holding configuration from which to create the inventory. If not specified, the default is /etc/openstack_deploy/.

In addition to this argument, the base environment skeleton is provided in the playbooks/inventory/env.d directory of the OpenStack-Ansible codebase.

Should an env.d directory be found in the directory specified by --config, it’s contents will be added to the base environment, overriding any previous contents in the event of conflicts.

Note

In all versions prior to Mitaka, this argument was --file.

The following file must be present in the configuration directory:

openstack_user_config.yml

Additionally, the configuration or environment could be spread between two additional sub-directories:

conf.d

env.d (for environment customization)

The dynamic inventory script does the following:

Generates the names of each container that runs a service
Creates container and IP address mappings
Assigns containers to physical hosts

As an example, consider the following excerpt from openstack_user_config.yml:

identity_hosts:
  infra01:
    ip: 10.0.0.10
  infra02:
    ip: 10.0.0.11
  infra03:
    ip: 10.0.0.12

The identity_hosts dictionary defines an Ansible inventory group named identity_hosts containing the three infra hosts. The configuration file playbooks/inventory/env.d/keystone.yml defines additional Ansible inventory groups for the containers that are deployed onto the three hosts named with the prefix infra.

Note that any services marked with is_metal: true will run on the allocated physical host and not in a container. For an example of is_metal: true being used refer to playbooks/inventory/env.d/cinder.yml in the container_skel section.

Outputs¶

Once executed, the script will output an openstack_inventory.json file into the directory specified with the --config argument. This is used as the source of truth for repeated runs.

Note

The openstack_inventory.json file is the source of truth for the environment. Deleting this in a production environment means that the UUID portion of container names will be regenerated, which then results in new containers being created. Containers generated under the previous version will no longer be recognized by Ansible, even if reachable via SSH.

The same JSON structure is printed to stdout, which is consumed by Ansible as the inventory for the playbooks.

Changing the Base Environment Directory¶

The --environment/-e argument will take the path to a directory containing an env.d directory. This defaults to playbooks/inventory/ in the OpenStack-Ansible codebase.

Contents of this directory are populated into the environment before the env.d found in the directory specified by --config.

Checking Inventory Configuration for Errors¶

Using the --check flag when running dynamic_inventory.py will run the inventory build process and look for known errors, but not write any files to disk.

This check does not do YAML syntax validation, though it will fail if there are unparseable errors.

Writing Debug Logs¶

The --debug/-d parameter allows writing of a detailed log file for debugging the inventory script’s behavior. The output is written to inventory.log in the current working directory.

The inventory.log file is appended to, not overwritten.

Like --check, this flag is not invoked when running from ansible.

Inspecting and Managing the Inventory¶

The file scripts/inventory-manage.py is used to produce human readable output based on the /etc/openstack_deploy/openstack_inventory.json file.

The same script can be used to safely remove hosts from the inventory.

Viewing the Inventory¶

The /etc/openstack_deploy/openstack_inventory.json file is read by default. An alternative file can be specified with --file.

A list of all hosts can be seen with the --list-host/-l argument

To see a listing of hosts and containers by their group, use --list-groups/-g.

To see all of the containers, use --list-containers/-G.

Removing a Host¶

A host can be removed with the --remove-item/-r parameter.

Use the host’s name as an argument.

Exporting Host Information¶

Information on a per-host basis can be obtained with the --export/-e parameter.

This JSON output has two top-level keys: hosts and all.

hosts contains a map of a host’s name to its variable and group data.

all contains global network information such as the load balancer IPs and provider network metadata.

The lxc_hosts Group¶

When a container name is created by the dynamic inventory script, the host on which the container resides is added to the lxc_hosts inventory group.

Using this name for a group in the configuration will result in a runtime error.

Dynamic Inventory API documentation¶

dynamic_inventory.append_if(array, item)¶

Append an item to an array if its not already in it.

Parameters:	array – `list` List object to append to item – `object` Object to append to the list
Returns array:	returns the amended list.

dynamic_inventory.args(arg_list)¶: Setup argument Parsing.

dynamic_inventory.container_skel_load(container_skel, inventory, config)¶

Build out all containers as defined in the environment file.

Parameters:	container_skel – `dict` container skeleton for all known containers inventory – `dict` Living dictionary of inventory config – `dict` User defined information

dynamic_inventory.find_config_path(user_config_path=None)¶

Return the path to the user configuration files.

If no directory is found the system will exit.

The lookup will be done in the following directories:

user_config_path

/etc/openstack_deploy/

Parameters:	user_config_path – `str` Location to look in FIRST for a file

dynamic_inventory.get_ip_address(name, ip_q)¶: Return an IP address from our IP Address queue.

dynamic_inventory.load_environment(config_path, environment)¶

Create an environment dictionary from config files

Parameters:	config_path – `str` path where the environment files are kept environment – `dict` dictionary to populate with environment data

dynamic_inventory.load_user_configuration(config_path)¶

Create a user configuration dictionary from config files

Parameters:	config_path – `str` path where the configuration files are kept

dynamic_inventory.main(config=None, check=False, debug=False, environment=None, **kwargs)¶

Run the main application.

Parameters:	config – `str` Directory from which to pull configs and overrides check – `bool` Flag to enable check mode debug – `bool` Flag to enable debug logging kwargs – `dict` Dictionary of arbitrary arguments; mostly for catching Ansible’s required –list parameter without name shadowing the list built-in. environment – `str` Directory containing the base env.d

dynamic_inventory.network_entry(is_metal, interface, bridge=None, net_type=None, net_mtu=None)¶: Return a network entry for a container.

dynamic_inventory.populate_lxc_hosts(inventory)¶

Insert nodes hosting LXC containers into the lxc_hosts group

The inventory dictionary passed in to this function will be mutated.

Parameters:	inventory – The dictionary containing the Ansible inventory

dynamic_inventory.skel_load(skeleton, inventory)¶

Build out data as provided from the defined skel dictionary.

Parameters:	skeleton – `dict` Dictionary defining group and component memberships for the inventory. inventory – `dict` Living dictionary of inventory

dynamic_inventory.skel_setup(environment, inventory)¶

Build out the main inventory skeleton as needed.

Parameters:	environment – `dict` Known environment information inventory – `dict` Living dictionary of inventory

dynamic_inventory.user_defined_setup(config, inventory)¶

Apply user defined entries from config into inventory.

Parameters:	config – `dict` User defined information inventory – `dict` Living dictionary of inventory