theforeman.foreman.foreman (4.0.0) — inventory

Install collection

Install with ansible-galaxy collection install theforeman.foreman:==4.0.0

Add to requirements.yml

  collections:
    - name: theforeman.foreman
      version: 4.0.0

Description

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 C(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

• requests >= 1.1

Inputs

    
url:
    description:
    - URL of the Foreman server.
    env:
    - name: FOREMAN_SERVER
    - name: FOREMAN_SERVER_URL
    - name: FOREMAN_URL
    required: true

user:
    description:
    - Username accessing the Foreman server.
    env:
    - name: FOREMAN_USER
    - name: FOREMAN_USERNAME
    required: true

cache:
    default: false
    description:
    - Toggle to enable/disable the caching of the inventory's source data, requires a
      cache plugin setup to work.
    env:
    - name: ANSIBLE_INVENTORY_CACHE
    ini:
    - key: cache
      section: inventory
    type: bool

groups:
    default: {}
    description: Add hosts to group based on Jinja2 conditionals.
    type: dict

plugin:
    choices:
    - theforeman.foreman.foreman
    description: token that ensures this is a source file for the C(foreman) plugin.
    required: true

report:
    description:
    - 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.
    type: dict

strict:
    default: false
    description:
    - If V(yes) make invalid entries a fatal error, otherwise skip and continue.
    - Since it is possible to use facts in the expressions they might not always be available
      and we ignore those errors by default.
    type: bool

compose:
    default: {}
    description: Create vars from jinja2 expressions.
    type: dict

foreman:
    description:
    - Foreman server related configuration, deprecated.
    - You can pass I(use_reports_api) in this dict to enable the Reports API.
    - Only for backward compatibility.

password:
    description:
    - Password of the user accessing the Foreman server.
    env:
    - name: FOREMAN_PASSWORD
    required: true

hostnames:
    default:
    - name
    description:
    - 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.
    elements: str
    type: list

want_ipv4:
    default: true
    description:
    - Toggle, if true the inventory will fetch ipv4 address of the host.
    - Only applies to inventories using the Reports API - attribute is ignored otherwise.
    type: boolean

want_ipv6:
    default: true
    description:
    - Toggle, if true the inventory will fetch ipv6 address of the host.
    - Only applies to inventories using the Reports API - attribute is ignored otherwise.
    type: boolean

batch_size:
    default: 250
    description: Number of hosts per batch that will be retrieved from the Foreman API
      per individual call
    type: int

want_facts:
    default: false
    description: Toggle, if True the plugin will retrieve host facts from the server
    type: boolean

max_timeout:
    default: 600
    description: Timeout before falling back to old host API when using report_data endpoint
      while polling.
    type: int

vars_prefix:
    default: foreman_
    description: prefix to apply to host variables, does not include facts nor params

want_params:
    default: false
    description: Toggle, if true the inventory will retrieve 'all_parameters' information
      as host vars
    type: boolean

want_subnet:
    default: true
    description:
    - Toggle, if true the inventory will fetch subnet.
    - Only applies to inventories using the Reports API - attribute is ignored otherwise.
    type: boolean

cache_plugin:
    default: memory
    description:
    - Cache plugin to use for the inventory's source data.
    env:
    - name: ANSIBLE_CACHE_PLUGIN
    - name: ANSIBLE_INVENTORY_CACHE_PLUGIN
    ini:
    - key: fact_caching
      section: defaults
    - key: cache_plugin
      section: inventory
    type: str

cache_prefix:
    default: ansible_inventory_
    description:
    - Prefix to use for cache plugin files/tables
    env:
    - name: ANSIBLE_CACHE_PLUGIN_PREFIX
    - name: ANSIBLE_INVENTORY_CACHE_PLUGIN_PREFIX
    ini:
    - key: fact_caching_prefix
      section: defaults
    - key: cache_prefix
      section: inventory

group_prefix:
    default: foreman_
    description: prefix to apply to foreman groups

host_filters:
    description: This can be used to restrict the list of returned host
    type: string

keyed_groups:
    default: []
    description: Add hosts to group based on the values of a variable.
    elements: dict
    suboptions:
      default_value:
        description:
        - The default value when the host variable's value is an empty string.
        - This option is mutually exclusive with O(keyed_groups[].trailing_separator).
        type: str
        version_added: '2.12'
        version_added_collection: ansible.builtin
      key:
        description:
        - The key from input dictionary used to generate groups
        type: str
      parent_group:
        description: parent group for keyed group
        type: str
      prefix:
        default: ''
        description: A keyed group name will start with this prefix
        type: str
      separator:
        default: _
        description: separator used to build the keyed group name
        type: str
      trailing_separator:
        default: true
        description:
        - Set this option to V(False) to omit the O(keyed_groups[].separator) after the
          host variable when the value is an empty string.
        - This option is mutually exclusive with O(keyed_groups[].default_value).
        type: bool
        version_added: '2.12'
        version_added_collection: ansible.builtin
    type: list

cache_timeout:
    default: 3600
    description:
    - Cache duration in seconds
    env:
    - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT
    - name: ANSIBLE_INVENTORY_CACHE_TIMEOUT
    ini:
    - key: fact_caching_timeout
      section: defaults
    - key: cache_timeout
      section: inventory
    type: int

poll_interval:
    default: 10
    description: The polling interval between 2 calls to the report_data endpoint while
      polling.
    type: int

want_location:
    default: true
    description:
    - 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.
    type: boolean

use_extra_vars:
    default: false
    description: Merge extra vars into the available variables for composition (highest
      precedence).
    env:
    - name: ANSIBLE_INVENTORY_USE_EXTRA_VARS
    ini:
    - key: use_extra_vars
      section: inventory_plugins
    type: bool
    version_added: '2.11'
    version_added_collection: ansible.builtin

validate_certs:
    default: true
    description:
    - Whether or not to verify the TLS certificates of the Foreman server.
    env:
    - name: FOREMAN_VALIDATE_CERTS
    type: boolean

want_subnet_v6:
    default: true
    description:
    - Toggle, if true the inventory will fetch ipv6 subnet.
    - Only applies to inventories using the Reports API - attribute is ignored otherwise.
    type: boolean

legacy_hostvars:
    default: false
    description:
    - 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`
    type: boolean

use_reports_api:
    default: true
    description: Use Reports API.
    type: boolean

want_host_group:
    default: true
    description:
    - 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.
    type: boolean

cache_connection:
    description:
    - Cache connection data or path, read cache plugin documentation for specifics.
    env:
    - name: ANSIBLE_CACHE_PLUGIN_CONNECTION
    - name: ANSIBLE_INVENTORY_CACHE_CONNECTION
    ini:
    - key: fact_caching_connection
      section: defaults
    - key: cache_connection
      section: inventory
    type: str

leading_separator:
    default: true
    description:
    - 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.
    type: boolean
    version_added: '2.11'
    version_added_collection: ansible.builtin

want_organization:
    default: true
    description:
    - 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.
    type: boolean

want_smart_proxies:
    default: true
    description:
    - 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.
    type: boolean

want_hostcollections:
    default: false
    description: Toggle, if true the plugin will create Ansible groups for host collections
    type: boolean

want_content_facet_attributes:
    default: true
    description:
    - 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.
    type: boolean