"Fossies" - the Fresh Open Source Software Archive 
Source code changes of the file "docs/docsite/rst/dev_guide/developing_inventory.rst" between
ansible-2.14.0.tar.gz and ansible-2.14.1rc1.tar.gz
About: Ansible is an IT Configuration Management, Deployment & Orchestration tool. Release candidate.
| developing_inventory.rst (ansible-2.14.0) | : | developing_inventory.rst (ansible-2.14.1rc1) | ||
|---|---|---|---|---|
| skipping to change at line 188 | skipping to change at line 188 | |||
| for colo in mydata: | for colo in mydata: | |||
| for server in mydata[colo]['servers']: | for server in mydata[colo]['servers']: | |||
| self.inventory.add_host(server['name']) | self.inventory.add_host(server['name']) | |||
| self.inventory.set_variable(server['name'], 'ansible_host', server['external_ip']) | self.inventory.set_variable(server['name'], 'ansible_host', server['external_ip']) | |||
| The specifics will vary depending on API and structure returned. Remember that i f you get an inventory source error or any other issue, you should ``raise Ansib leParserError`` to let Ansible know that the source was invalid or the process f ailed. | The specifics will vary depending on API and structure returned. Remember that i f you get an inventory source error or any other issue, you should ``raise Ansib leParserError`` to let Ansible know that the source was invalid or the process f ailed. | |||
| For examples on how to implement an inventory plugin, see the source code here: | For examples on how to implement an inventory plugin, see the source code here: | |||
| `lib/ansible/plugins/inventory <https://github.com/ansible/ansible/tree/devel/li b/ansible/plugins/inventory>`_. | `lib/ansible/plugins/inventory <https://github.com/ansible/ansible/tree/devel/li b/ansible/plugins/inventory>`_. | |||
| .. _inventory_object: | ||||
| inventory object | ||||
| ^^^^^^^^^^^^^^^^ | ||||
| The ``inventory`` object passed to ``parse`` has helpful methods for populating | ||||
| inventory. | ||||
| ``add_group`` adds a group to inventory if it doesn't already exist. It takes th | ||||
| e group name as the only positional argument. | ||||
| ``add_child`` adds a group or host that exists in inventory to a parent group in | ||||
| inventory. It takes two positional arguments, the name of the parent group and | ||||
| the name of the child group or host. | ||||
| ``add_host`` adds a host to inventory if it doesn't already exist, optionally to | ||||
| a specific group. It takes the host name as the first argument and accepts two | ||||
| optional keyword arguments, ``group`` and ``port``. ``group`` is the name of a g | ||||
| roup in inventory, and ``port`` is an integer. | ||||
| ``set_variable`` adds a variable to a group or host in inventory. It takes three | ||||
| positional arguments: the name of the group or host, the name of the variable, | ||||
| and the value of the variable. | ||||
| To create groups and variables using Jinja2 expressions, see the section on impl | ||||
| ementing ``constructed`` features below. | ||||
| To see other inventory object methods, see the source code here: | ||||
| `lib/ansible/inventory/data.py <https://github.com/ansible/ansible/tree/devel/li | ||||
| b/ansible/inventory/data.py>`_. | ||||
| .. _inventory_plugin_caching: | .. _inventory_plugin_caching: | |||
| inventory cache | inventory cache | |||
| ^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^ | |||
| To cache the inventory, extend the inventory plugin documentation with the inven tory_cache documentation fragment and use the Cacheable base class. | To cache the inventory, extend the inventory plugin documentation with the inven tory_cache documentation fragment and use the Cacheable base class. | |||
| .. code-block:: yaml | .. code-block:: yaml | |||
| extends_documentation_fragment: | extends_documentation_fragment: | |||
| skipping to change at line 285 | skipping to change at line 305 | |||
| extends_documentation_fragment: | extends_documentation_fragment: | |||
| - constructed | - constructed | |||
| .. code-block:: python | .. code-block:: python | |||
| class InventoryModule(BaseInventoryPlugin, Constructable): | class InventoryModule(BaseInventoryPlugin, Constructable): | |||
| NAME = 'ns.coll.myplugin' | NAME = 'ns.coll.myplugin' | |||
| The three main options from the ``constructed`` documentation fragment are ``com | There are three main options in the ``constructed`` documentation fragment: | |||
| pose``, ``keyed_groups``, and ``groups``. See the ``constructed`` inventory plug | ||||
| in for examples on using these. ``compose`` is a dictionary of variable names an | ``compose`` creates variables using Jinja2 expressions. This is implemented by c | |||
| d Jinja2 expressions. Once a host is added to inventory and any initial variable | alling the ``_set_composite_vars`` method. | |||
| s have been set, call the method ``_set_composite_vars`` to add composed host va | ``keyed_groups`` creates groups of hosts based on variable values. This is imple | |||
| riables. If this is done before adding ``keyed_groups`` and ``groups``, the grou | mented by calling the ``_add_host_to_keyed_groups`` method. | |||
| p generation will be able to use the composed variables. | ``groups`` creates groups based on Jinja2 conditionals. This is implemented by c | |||
| alling the ``_add_host_to_composed_groups`` method. | ||||
| Each method should be called for every host added to inventory. Three positional | ||||
| arguments are required: the constructed option, a dictionary of variables, and | ||||
| a host name. Calling the method ``_set_composite_vars`` first will allow ``keyed | ||||
| _groups`` and ``groups`` to use the composed variables. | ||||
| By default, undefined variables are ignored. This is permitted by default for `` | ||||
| compose`` so you can make the variable definitions depend on variables that will | ||||
| be populated later in a play from other sources. For groups, it allows using va | ||||
| riables that are not always present without having to use the ``default`` filter | ||||
| . To support configuring undefined variables to be an error, pass the constructe | ||||
| d option ``strict`` to each of the methods as a keyword argument. | ||||
| ``keyed_groups`` and ``groups`` use any variables already associated with the ho | ||||
| st (for example, from an earlier inventory source). ``_add_host_to_keyed_groups` | ||||
| ` and ``add_host_to_composed_groups`` can turn this off by passing the keyword a | ||||
| rgument ``fetch_hostvars``. | ||||
| Here is an example using all three methods: | ||||
| .. code-block:: python | .. code-block:: python | |||
| def add_host(self, hostname, host_vars): | def add_host(self, hostname, host_vars): | |||
| self.inventory.add_host(hostname, group='all') | self.inventory.add_host(hostname, group='all') | |||
| for var_name, var_value in host_vars.items(): | for var_name, var_value in host_vars.items(): | |||
| self.inventory.set_variable(hostname, var_name, var_value) | self.inventory.set_variable(hostname, var_name, var_value) | |||
| # Determines if composed variables or groups using nonexistent variables is an error | ||||
| strict = self.get_option('strict') | strict = self.get_option('strict') | |||
| # Add variables created by the user's Jinja2 expressions to the host | # Add variables created by the user's Jinja2 expressions to the host | |||
| self._set_composite_vars(self.get_option('compose'), host_vars, hostname, strict=True) | self._set_composite_vars(self.get_option('compose'), host_vars, hostname, strict=True) | |||
| # The following two methods combine the provided variables dictionary wit | # Create user-defined groups using variables and Jinja2 conditionals | |||
| h the latest host variables | ||||
| # Using these methods after _set_composite_vars() allows groups to be cre | ||||
| ated with the composed variables | ||||
| self._add_host_to_composed_groups(self.get_option('groups'), host_vars, h ostname, strict=strict) | self._add_host_to_composed_groups(self.get_option('groups'), host_vars, h ostname, strict=strict) | |||
| self._add_host_to_keyed_groups(self.get_option('keyed_groups'), host_vars , hostname, strict=strict) | self._add_host_to_keyed_groups(self.get_option('keyed_groups'), host_vars , hostname, strict=strict) | |||
| By default, group names created with ``_add_host_to_composed_groups()`` and ``_a dd_host_to_keyed_groups()`` are valid Python identifiers. Invalid characters are replaced with an underscore ``_``. A plugin can change the sanitization used fo r the constructed features by setting ``self._sanitize_group_name`` to a new fun ction. The core engine also does sanitization, so if the custom function is less strict it should be used in conjunction with the configuration setting ``TRANSF ORM_INVALID_GROUP_CHARS``. | By default, group names created with ``_add_host_to_composed_groups()`` and ``_a dd_host_to_keyed_groups()`` are valid Python identifiers. Invalid characters are replaced with an underscore ``_``. A plugin can change the sanitization used fo r the constructed features by setting ``self._sanitize_group_name`` to a new fun ction. The core engine also does sanitization, so if the custom function is less strict it should be used in conjunction with the configuration setting ``TRANSF ORM_INVALID_GROUP_CHARS``. | |||
| .. code-block:: python | .. code-block:: python | |||
| from ansible.inventory.group import to_safe_group_name | from ansible.inventory.group import to_safe_group_name | |||
| class InventoryModule(BaseInventoryPlugin, Constructable): | class InventoryModule(BaseInventoryPlugin, Constructable): | |||
| End of changes. 4 change blocks. | ||||
| 12 lines changed or deleted | 59 lines changed or added | |||