Documentation rewrite
This commit is contained in:
parent
3f38940a9c
commit
74e0f92595
1 changed files with 172 additions and 47 deletions
219
README.md
219
README.md
|
|
@ -1,61 +1,186 @@
|
||||||
reconstructed
|
reconstructed
|
||||||
=============
|
=============
|
||||||
|
|
||||||
An Ansible plugin that can generate structured inventories programmatically.
|
`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.
|
||||||
|
|
||||||
This is a work in progress. I will make this README more useful later, provided
|
Installation from Ansible Galaxy
|
||||||
I just don't forget about this whole thing.
|
--------------------------------
|
||||||
|
|
||||||
A `reconstructed` inventory executes a list of instructions that is read
|
You can install the latest version from Ansible Galaxy repository.
|
||||||
from the `instructions` YAML field. Each instruction is a table with some
|
|
||||||
minimal control flow (`when`, `loop` and `run_once` keywords that work mostly
|
|
||||||
like their playbook cousins), an `action` field that contains the name of the
|
|
||||||
instruction to execute, and whatever fields are needed for the instruction.
|
|
||||||
|
|
||||||
The following actions are supported:
|
```bash
|
||||||
|
ansible-galaxy collection install -U tseeker.reconstructed
|
||||||
|
```
|
||||||
|
|
||||||
* `create_group` creates a group. The name of the group must be
|
If you are using a *requirements.yml* file to download collections and roles,
|
||||||
provided using the `group` field, which must be a valid name or a
|
you can use these lines:
|
||||||
Jinja template that evaluates to a valid name. In addition, a
|
|
||||||
`parent` field containting the name of a single, existing parent
|
|
||||||
group (or a Jinja template generating the name) may be provided.
|
|
||||||
Finally, the `add_host` field may be set to a truthy value if the
|
|
||||||
current host must be added to the new group.
|
|
||||||
|
|
||||||
* `add_child` adds a child group to another group. The name of the
|
```yaml
|
||||||
group being added must be provided in the `child` entry, while
|
collections:
|
||||||
the name of the parent must be provided in the `group` entry. Both
|
- tseeker.reconstructed
|
||||||
groups must exist. In addition, the names may be specified using
|
```
|
||||||
Jinja templates.
|
|
||||||
|
|
||||||
* `add_host` adds the current inventory host to a group. The name
|
Usage
|
||||||
of the group must be provided in the `group` entry. The group
|
-----
|
||||||
must exist.
|
|
||||||
|
|
||||||
* `fail` causes the computations for the current host to stop with
|
A `reconstructed` script can be added to the inventory by creating a YAML
|
||||||
an error. The error message may be specified in the `message`
|
file in the inventory, with the following structure:
|
||||||
entry; if present, it will be evaluated using Jinja.
|
|
||||||
|
|
||||||
* `set_fact` and `set_var` create a fact and a local variable,
|
```yaml
|
||||||
respectively. Local variables will only be kept during the execution
|
---
|
||||||
of the script for the current host, while facts will be added to the
|
plugin: tseeker.reconstructed.reconstructed
|
||||||
host's data. The `name` entry specifies the name of the fact or
|
instructions:
|
||||||
variable while the `value` entry specifies its value. Both may be
|
- action: ...
|
||||||
Jinja templates.
|
- action: ...
|
||||||
|
# ...
|
||||||
|
```
|
||||||
|
|
||||||
* `stop` stops processing the list of instructions for the current
|
Script actions are somewhat similar to playbook tasks. Once a script has been
|
||||||
host.
|
added, it will be executed once for each host in the input inventory.
|
||||||
|
|
||||||
In addition, the `block` can be used to repeat multiple instructions or make
|
Each action record in a script must include an `action` field, which describes
|
||||||
them obey a single conditional. The instruction must include a `block` field,
|
the action to perform. In addition, it may include fields which contain the
|
||||||
containing the list of instructions which are part of the block. It may have
|
action's details, as well as fields which implement various controls that
|
||||||
a `rescue` field, containing a list of instructions which will be executed on
|
apply to an action (loops, local variables, etc).
|
||||||
error, and `always`, which may contain a list of instructions to execute in
|
|
||||||
all cases.
|
|
||||||
|
|
||||||
If the `vars` field is defined on an instruction, it must contain a table of
|
The script can manipulate and use host facts. In addition, local variables
|
||||||
local variables to define. Their values are computed after the loop variable
|
which do not pollute the inventory are used automatically for e.g. loops, and
|
||||||
is evaluated, but before the condition is. If these variables already existed,
|
can be defined manually.
|
||||||
their state will be saved and they will be restored after the instruction is
|
|
||||||
done executing. This is different from the core Ansible behaviour, which does
|
### Actions
|
||||||
not evaluate the `vars` unless they are used.
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
#### 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
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue