theforeman.foreman.foreman inventory – Foreman inventory source
Note
This inventory plugin is part of the theforeman.foreman collection (version 4.2.0).
You might already have this collection installed if you are using the ansible
package.
It is not included in ansible-core
.
To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install theforeman.foreman
.
You need further requirements to be able to use this inventory plugin,
see Requirements for details.
To use it in a playbook, specify: theforeman.foreman.foreman
.
Synopsis
Get inventory hosts from Foreman.
Can use the Reports API (default) or the Hosts API to fetch information about the hosts.
The Reports API is faster with many hosts.
The Reports API requires the
foreman_ansible
plugin to be installed on the Foreman server.Some options only work when using the Reports API.
Uses a YAML configuration file that ends with ``foreman.(yml|yaml)``.
Requirements
The below requirements are needed on the local controller node that executes this inventory.
requests >= 1.1
Parameters
Parameter |
Comments |
---|---|
Number of hosts per batch that will be retrieved from the Foreman API per individual call Default: |
|
Toggle to enable/disable the caching of the inventory’s source data, requires a cache plugin setup to work. Choices:
Configuration:
|
|
Cache connection data or path, read cache plugin documentation for specifics. Configuration:
|
|
Cache plugin to use for the inventory’s source data. Default: Configuration:
|
|
Prefix to use for cache plugin files/tables Default: Configuration:
|
|
Cache duration in seconds Default: Configuration:
|
|
Create vars from jinja2 expressions. Default: |
|
Foreman server related configuration, deprecated. You can pass use_reports_api in this dict to enable the Reports API. Only for backward compatibility. |
|
prefix to apply to foreman groups Default: |
|
Add hosts to group based on Jinja2 conditionals. Default: |
|
This can be used to restrict the list of returned host |
|
A list of templates in order of precedence to compose inventory_hostname. If the template results in an empty string or None value it is ignored. Default: |
|
Add hosts to group based on the values of a variable. Default: |
|
The default value when the host variable’s value is an empty string. This option is mutually exclusive with |
|
The key from input dictionary used to generate groups |
|
parent group for keyed group |
|
A keyed group name will start with this prefix Default: |
|
separator used to build the keyed group name Default: |
|
Set this option to This option is mutually exclusive with Choices:
|
|
Use in conjunction with keyed_groups. By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore. This is because the default prefix is “” and the default separator is “_”. Set this option to False to omit the leading underscore (or other separator) if no prefix is given. If the group name is derived from a mapping the separator is still used to concatenate the items. To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead. Choices:
|
|
Toggle, if true the plugin will build legacy hostvars present in the foreman script Places hostvars in a dictionary with keys `foreman`, `foreman_facts`, and `foreman_params` Choices:
|
|
Timeout before falling back to old host API when using report_data endpoint while polling. Default: |
|
Password of the user accessing the Foreman server. Configuration:
|
|
token that ensures this is a source file for the Choices:
|
|
The polling interval between 2 calls to the report_data endpoint while polling. Default: |
|
Report API specific configuration, deprecated. You can pass the Report API specific params as part of this dict, instead of the main configuration. Only for backward compatibility. |
|
If Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default. Choices:
|
|
URL of the Foreman server. Configuration:
|
|
Merge extra vars into the available variables for composition (highest precedence). Choices:
Configuration:
|
|
Use Reports API. Choices:
|
|
Username accessing the Foreman server. Configuration:
|
|
Whether or not to verify the TLS certificates of the Foreman server. Choices:
Configuration:
|
|
prefix to apply to host variables, does not include facts nor params Default: |
|
Toggle, if true the inventory will fetch content view details that the host is tied to. Only applies to inventories using the Reports API - attribute is ignored otherwise. Choices:
|
|
Toggle, if True the plugin will retrieve host facts from the server Choices:
|
|
Toggle, if true the inventory will fetch host_groups and create groupings for the same. Only applies to inventories using the Reports API - attribute is ignored otherwise. Choices:
|
|
Toggle, if true the plugin will create Ansible groups for host collections Choices:
|
|
Toggle, if true the inventory will fetch ipv4 address of the host. Only applies to inventories using the Reports API - attribute is ignored otherwise. Choices:
|
|
Toggle, if true the inventory will fetch ipv6 address of the host. Only applies to inventories using the Reports API - attribute is ignored otherwise. Choices:
|
|
Toggle, if true the inventory will fetch location the host belongs to and create groupings for the same. Only applies to inventories using the Reports API - attribute is ignored otherwise. Choices:
|
|
Toggle, if true the inventory will fetch organization the host belongs to and create groupings for the same. Only applies to inventories using the Reports API - attribute is ignored otherwise. Choices:
|
|
Toggle, if true the inventory will retrieve ‘all_parameters’ information as host vars Choices:
|
|
Toggle, if true the inventory will fetch smart proxy that the host is registered to. Only applies to inventories using the Reports API - attribute is ignored otherwise. Choices:
|
|
Toggle, if true the inventory will fetch subnet. Only applies to inventories using the Reports API - attribute is ignored otherwise. Choices:
|
|
Toggle, if true the inventory will fetch ipv6 subnet. Only applies to inventories using the Reports API - attribute is ignored otherwise. Choices:
|
Examples
# my.foreman.yml
plugin: theforeman.foreman.foreman
url: https://foreman.example.com
user: ansibleinventory
password: changeme
host_filters: 'organization="Web Engineering"'
# shortname.foreman.yml
plugin: theforeman.foreman.foreman
url: https://foreman.example.com
user: ansibleinventory
password: changeme
hostnames:
- name.split('.')[0]
Hint
Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.