194 lines
6.6 KiB
Markdown
194 lines
6.6 KiB
Markdown
reconstructed
|
|
=============
|
|
|
|
`reconstructed` is an Ansible inventory plugin which can be used to generate
|
|
group hierarchies and place hosts within them based solely on host facts.
|
|
This allows functionality similar to what the [ansible.builtin.add_host](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/add_host_module.html)
|
|
module can provide, but it is available during inventory construction rather
|
|
than playbook execution.
|
|
|
|
Installation from Ansible Galaxy
|
|
--------------------------------
|
|
|
|
You can install the latest version from Ansible Galaxy repository.
|
|
|
|
```bash
|
|
ansible-galaxy collection install -U tseeker.reconstructed
|
|
```
|
|
|
|
If you are using a *requirements.yml* file to download collections and roles,
|
|
you can use these lines:
|
|
|
|
```yaml
|
|
collections:
|
|
- tseeker.reconstructed
|
|
```
|
|
|
|
Usage
|
|
-----
|
|
|
|
A `reconstructed` script can be added to the inventory by creating a YAML
|
|
file in the inventory, with the following structure:
|
|
|
|
```yaml
|
|
---
|
|
plugin: tseeker.reconstructed.reconstructed
|
|
instructions:
|
|
- action: ...
|
|
- action: ...
|
|
# ...
|
|
```
|
|
|
|
Script actions are somewhat similar to playbook tasks. Once a script has been
|
|
added, it will be executed once for each host in the input inventory.
|
|
|
|
Each action record in a script must include an `action` field, which describes
|
|
the action to perform. In addition, it may include fields which contain the
|
|
action's details, as well as fields which implement various controls that
|
|
apply to an action (loops, local variables, etc).
|
|
|
|
The script can manipulate and use host facts. In addition, local variables
|
|
which do not pollute the inventory are used automatically for e.g. loops, and
|
|
can be defined manually.
|
|
|
|
### Actions
|
|
|
|
The following actions may be used in a `reconstructed` script.
|
|
|
|
#### add_child
|
|
|
|
This action adds an existing group to the set of another existing group's
|
|
children.
|
|
|
|
It supports the following fields.
|
|
|
|
* `group` must contain the name of the parent group, or a Jinja template
|
|
that evaluates to that name. The group must exist.
|
|
* `child` must contain the name of the child group, or a Jinja template
|
|
that evaluates to that name. The group must exist.
|
|
|
|
#### add_host
|
|
|
|
The `add_host` action can be used to add the inventory host currently being
|
|
processed to a group.
|
|
|
|
The following field is supported.
|
|
|
|
* `group` must contain the name of the group to add the host to. It may
|
|
be a Jinja template. The group in question must exist.
|
|
|
|
#### block
|
|
|
|
The `block` action can be used to group multiple actions and to support error
|
|
recovery, behaving in many ways like the playbooks' `block`. The following
|
|
fields may be used.
|
|
|
|
* `block` contains the block's main list of instructions.
|
|
* `rescue` contains a list of instructions that will be executed if an
|
|
error occurs while executing the main list. The `reconstructed_error`
|
|
local variable will contain the message of the error that caused the
|
|
`rescue` list to be executed. This field may be omitted.
|
|
* `always` contains a list of instructions that will be executed after
|
|
both other lists, independently of any error. This field may be omitted.
|
|
|
|
#### create_group
|
|
|
|
The `create_group` action creates an inventory group. In addition, it may
|
|
specify the new group's parent and add the current host to the group.
|
|
|
|
If the group already exists, no error will be raised. The group will be added
|
|
to the specified parent and the host will be added to the group if requested.
|
|
|
|
The following fields are supported.
|
|
|
|
* `group` contains the name of the group. It must be present and may contain
|
|
a Jinja template.
|
|
* `parent` may contain the name of an additional group to which the new
|
|
group will be added as a child. The group in question must exist. This
|
|
field is optional and may contain a Jinja template.
|
|
* If the `add_host` field is present, it may contain a boolean which will
|
|
determine whether the current inventory host must be added to the group.
|
|
|
|
#### fail
|
|
|
|
This action causes the script to fail immediately. The following field may be
|
|
used:
|
|
|
|
* `msg` may contain a message (or a Jinja template resulting in a message)
|
|
to write to the output. By default the message will be `fail requested`
|
|
followed by the name of the current host.
|
|
|
|
#### rename_host
|
|
|
|
This action changes the name of the current host. It can only be executed once
|
|
for each host. The actual renaming will occur after the script has completed
|
|
its execution. It requires the following field:
|
|
|
|
* `name`: the new name of the host.
|
|
|
|
#### set_fact
|
|
|
|
This action sets an Ansible fact associated to the current host. The following
|
|
fields must be set:
|
|
|
|
* `name` is the name of the fact to set, or a Jinja template returning the
|
|
name. It must represent a valid fact name.
|
|
* `value` is the fact's new value, or a template computing it.
|
|
|
|
#### set_var
|
|
|
|
This action sets a local variable. Local variables are only kept for the
|
|
duration of the script's execution for a given host. A local variable will
|
|
hide a fact by the same name.
|
|
|
|
The following fields are required:
|
|
|
|
* `name` is the name of the fact to set, or a Jinja template returning the
|
|
name. It must result in a valid fact name.
|
|
* `value` is the variable's new value, or a template computing it.
|
|
|
|
#### stop
|
|
|
|
The `stop` action interrupts the execution of the script for the current host.
|
|
It requires no additional information.
|
|
|
|
### Control fields
|
|
|
|
The following additional fields may be added to any action record to alter its
|
|
behaviour.
|
|
|
|
#### run_once
|
|
|
|
If this field is set to a ``true``, it will cause the action to be executed
|
|
only once.
|
|
|
|
#### loop and loop_var
|
|
|
|
The `loop` field may contain a list or a Jinja template that evaluates to a
|
|
list. The action record will be repeated for each item in the list, with a
|
|
local variable set to the value of the item.
|
|
|
|
By default the variable that contains the item is called `item`. However it
|
|
is possible to add a `loop_var` field containing a valid variable name to
|
|
change it. This variable will be restored to its previous state once the loop
|
|
is finished.
|
|
|
|
#### vars
|
|
|
|
The `vars` field may contain a table of local variables to set for the duration
|
|
of the action. The table's keys are variable names, and its values will be
|
|
evaluated using Jinja. During a loop, variables will be evaluated evaluated
|
|
once for each loop iteration. Once the action is finished, the local variables
|
|
defined using `vars` will disappear.
|
|
|
|
#### when
|
|
|
|
The `when` field may be used to check a condition and prevent the execution
|
|
of the action it is bound to if the condition isn't satisfied. The condition
|
|
is evaluated once for each iteration of a loop. All local variables defined
|
|
using `vars` are available for use in the condition.
|
|
|
|
## To do
|
|
|
|
* `create_group.add_host` should allow Jinja templates
|
|
* Add a `debug` action
|