eigenstate-ipa

Inventory Plugin

Purpose

eigenstate.ipa.idm reads IdM data and turns it into Ansible inventory.

This reference covers:

what the plugin reads from IdM
how IdM objects are converted into Ansible groups and curated idm_* host vars
how password auth and Kerberos auth differ operationally
how hostvars_enabled and hostvars_include control metadata export
when filters remove hosts from inventory versus only pruning groups

The principal does not need to be a global IdM administrator. It does need the read and auth rights required for the specific IdM objects you want to expose.

Inventory Model
Authentication Model
Current Supported Options
How Groups Are Built
Host Variable Enrichment
Filtering Behavior
Minimal Examples
When To Read The Scenario Guide

Inventory Model

flowchart LR
    idm["IdM / FreeIPA"]
    hosts["Hosts"]
    hostgroups["Hostgroups"]
    netgroups["Netgroups"]
    hbac["HBAC rules"]
    plugin["eigenstate.ipa.idm"]
    inv["Ansible inventory"]

    idm --> hosts
    idm --> hostgroups
    idm --> netgroups
    idm --> hbac
    hosts --> plugin
    hostgroups --> plugin
    netgroups --> plugin
    hbac --> plugin
    plugin --> inv

The inventory plugin reads the IdM JSON-RPC API and consumes four object classes:

hosts
hostgroups
netgroups
hbacrules

The plugin exports a curated set of IdM host attributes as host variables with an idm_ prefix. Group names created from IdM objects are sanitized into Ansible-safe names.

Authentication Model

The plugin supports two auth modes:

password auth:
- uses session/login_password
- requires ipaadmin_password
Kerberos auth:
- uses session/login_kerberos
- requires an existing ticket or kerberos_keytab

[!IMPORTANT] Kerberos mode is the right default for Automation Controller / AAP execution environments. The plugin can obtain a private credential cache from kerberos_keytab so it does not depend on an interactive kinit.

TLS behavior:

verify: /path/to/ca.crt enables explicit certificate verification
omitting verify first tries /etc/ipa/ca.crt
if no local IdM CA path is available, the plugin warns and then disables TLS verification

That means production use should normally provide the IdM CA path explicitly, even though the plugin now has a safer local default when the host is already enrolled with IdM.

Current Supported Options

Option	Meaning
`server`	IdM server FQDN
`ipaadmin_principal`	Principal used for password auth or Kerberos auth
`ipaadmin_password`	Password mode credential
`use_kerberos`	Enables Kerberos/GSSAPI auth
`kerberos_keytab`	Non-interactive Kerberos auth for EE/AAP use; the plugin warns if the file is more permissive than `0600`
`verify`	CA bundle path for TLS verification
`sources`	Which IdM object types to include
`hostgroup_filter`	Restrict generated hostgroup-derived groups
`netgroup_filter`	Restrict generated netgroup-derived groups
`hbacrule_filter`	Restrict generated HBAC-derived groups
`include_disabled_hbacrules`	Include disabled HBAC rules when true
`hostgroup_prefix`	Prefix for hostgroup-derived Ansible groups
`netgroup_prefix`	Prefix for netgroup-derived Ansible groups
`hbacrule_prefix`	Prefix for HBAC-derived Ansible groups
`host_filter_from_groups`	Removes hosts that do not land in any selected generated group
`hostvars_enabled`	Enables curated `idm_*` host variable export
`hostvars_include`	Allowlist of exported `idm_*` host variable names

The plugin also supports standard constructed-inventory features such as:

compose
keyed_groups
groups
inventory caching

How Groups Are Built

Hosts

When sources includes hosts, every enrolled IdM host is added to inventory. The plugin then applies the curated hostvar export policy described below.

Hostgroups

IdM hostgroups become Ansible groups with hostgroup_prefix, defaulting to idm_hostgroup_.

Nested IdM hostgroups are resolved recursively before membership is assigned. That means an Ansible group for a parent hostgroup contains the flattened set of all nested member hosts.

Netgroups

IdM netgroups become Ansible groups with netgroup_prefix, defaulting to idm_netgroup_.

The plugin resolves both:

direct host membership
hostgroup membership referenced by the netgroup

HBAC Rules

IdM HBAC rules become Ansible groups with hbacrule_prefix, defaulting to idm_hbacrule_.

The plugin resolves:

direct host membership
hostgroup membership referenced by the rule
hostcategory=all as all enrolled hosts

Disabled rules are skipped unless include_disabled_hbacrules: true.

Host Variable Enrichment

The inventory plugin does not dump every raw IPA attribute into hostvars. It exports a curated set of automation-friendly fields under idm_* names.

Default curated variables:

Host var	Meaning
`idm_fqdn`	Enrolled host FQDN
`idm_description`	Host description
`idm_locality`	LDAP locality field
`idm_location`	IdM host location
`idm_platform`	Hardware platform
`idm_os`	Operating system version
`idm_krbcanonicalname`	Canonical Kerberos principal name
`idm_has_keytab`	Whether a host keytab is present
`idm_has_password`	Whether a host password exists
`idm_serverhostname`	Server-side hostname field
`idm_dn`	LDAP distinguished name
`idm_krb_ok_as_delegate`	Kerberos OK-AS-DELEGATE flag
`idm_krb_requires_preauth`	Kerberos preauth requirement
`idm_ssh_public_keys`	SSH public keys
`idm_krbprincipalname`	Principal aliases
`idm_managedby`	Managing hosts
`idm_hostgroups`	Direct IdM hostgroup membership

Control knobs:

hostvars_enabled: true keeps hostvar enrichment on by default
hostvars_enabled: false disables host attribute export from IdM host objects
hostvars_include: narrows host attribute export to a specific allowlist of idm_* names

[!NOTE] hostvars_include accepts the exported idm_* variable names, not the raw LDAP or IPA attribute names. Unknown names fail fast during inventory parsing.

Live bastion validation against idm-01.workshop.lan showed that these settings only control host-level enrichment. Group variables from generated hostgroups or HBAC groups can still merge into the final hostvars view because that merge happens later in normal Ansible inventory processing.

Filtering Behavior

Filters limit which generated groups are created. They do not automatically remove unmatched hosts from inventory unless host_filter_from_groups is set.

Practical difference:

filter without host_filter_from_groups:
- unmatched hosts remain present, usually under ungrouped
filter with host_filter_from_groups: true:
- unmatched hosts are removed from the resulting inventory

[!NOTE] host_filter_from_groups is the setting that turns a broad IdM estate into a tightly scoped execution slice. Without it, filtering affects group creation more than host inclusion.

Minimal Examples

Password auth:

plugin: eigenstate.ipa.idm
server: idm-01.example.com
ipaadmin_password: "{{ lookup('env', 'IPA_ADMIN_PASSWORD') }}"
verify: /etc/ipa/ca.crt
sources:
  - hosts
  - hostgroups

Kerberos with keytab:

plugin: eigenstate.ipa.idm
server: idm-01.example.com
use_kerberos: true
kerberos_keytab: /runner/env/ipa/admin.keytab
ipaadmin_principal: admin
verify: /etc/ipa/ca.crt
sources:
  - hosts
  - hbacrules

Constructed inventory from IdM metadata:

plugin: eigenstate.ipa.idm
server: idm-01.example.com
ipaadmin_password: "{{ lookup('env', 'IPA_ADMIN_PASSWORD') }}"
verify: /etc/ipa/ca.crt
sources:
  - hosts
keyed_groups:
  - key: idm_location
    prefix: dc
    separator: "_"
compose:
  ansible_host: idm_fqdn
groups:
  has_keytab: idm_has_keytab | default(false)

Trim hostvar export to only what the job needs:

plugin: eigenstate.ipa.idm
server: idm-01.example.com
ipaadmin_password: "{{ lookup('env', 'IPA_ADMIN_PASSWORD') }}"
verify: /etc/ipa/ca.crt
sources:
  - hosts
hostvars_include:
  - idm_location
  - idm_os
  - idm_hostgroups

When To Read The Scenario Guide

Use INVENTORY CAPABILITIES when you need to decide which IdM object type should drive a particular automation boundary:

full-estate operations
role-targeted deploys
access-boundary auditing
policy-targeted SSH or hardening work

This site is open source. Improve this page.