fleets
A fast, high-compatibility replacement for ansible-inventory, written in Rust. It supports
the most common static, directory, script, and constructed inventory workflows while making
documented choices where exact Ansible behavior is undesirable.
Fleets targets Linux and macOS controllers. It is an independent project and is not affiliated with or endorsed by Red Hat or the Ansible project. Ansible is a trademark of Red Hat, Inc.
Install
OpenTelemetry support is optional because it adds a substantial dependency tree:
To build from a checkout, run cargo build --release; the binary is written to
target/release/fleets.
Usage
Flags mirror ansible-inventory: --list, --host, -i/--inventory (repeatable),
-l/--limit, -y/--yaml, --toml, --export. Fleets also provides
--strict-compatibility to retain ansible's exact group-reference shape. (--graph is not
yet implemented.)
By default, list output prunes groups that have no visible hosts, relevant descendants, or
exported variables. This also removes dangling names from children. Set
FLEETS_STRICT_COMPATIBILITY=true or pass --strict-compatibility to preserve ansible's
shallow pruning instead.
fleets honors ANSIBLE_INVENTORY (default source when no -i is given) and
ANSIBLE_INVENTORY_ENABLED (which source kinds are enabled); most other ANSIBLE_*
variables are fixed to their ansible defaults. See docs/environment.md
for the full matrix of which are honored, fixed, or only pinned in the test harness.
Supported inventory sources
| Source | Notes |
|---|---|
| YAML / JSON | .yaml/.yml/.json (JSON rides the YAML schema, as in ansible) |
| TOML | ansible's toml plugin schema (children as a list of names) |
| INI | [group], [group:children], [group:vars], inline key=value, host:port, host ranges, ast.literal_eval value coercion |
| Directory | merges all non-ignored files (alphabetical, recursive) plus adjacent group_vars/ and host_vars/ |
| Dynamic script | executable run with --list; honors _meta.hostvars, falls back to --host <name> |
| Constructed | plugin: ansible.builtin.constructed — compose + keyed_groups + groups over a documented expression subset (runs as an incremental post-processing pass; see below) |
Variable precedence follows ansible faithfully: all → group_vars/all → other groups
(ordered by (depth, ansible_group_priority, name)) → group_vars/<g> files → host vars →
host_vars/<h> files. Host-range expansion, group-name sanitization, and Python-literal
value coercion all match ansible-core.
Testing
Strict compatibility is verified against ansible-core 2.18.9 by a differential test harness
(tests/differential.rs) that runs both fleets --strict-compatibility and the real
ansible-inventory on every fixture and compares output semantically (order-independent)
across --list/--host, all three formats, --export, and a matrix of --limit patterns.
# Required-oracle mode used in CI:
FLEETS_REQUIRE_ANSIBLE=1
Without ansible-inventory on PATH, ordinary local test runs skip the differential suite.
Required-oracle mode fails instead. Known cases that ansible itself cannot serialize are
explicitly allowlisted and reported separately rather than counted as passing comparisons.
Known intentional divergences
- Graph-aware group pruning by default: fleets removes child references to groups that
contribute no visible hosts, relevant descendants, or exported variables; ansible can
leave those names dangling. Use
--strict-compatibilityto restore ansible's shape. - Same-name host and group under
--export: ansible merges the host's vars into the group and empties_meta; fleets keeps them distinct. (Quarantined in the harness.) - Malformed INI: ansible soft-fails the whole source to an empty inventory; fleets is
more lenient on some malformed input (e.g.
[g:vars]for an undeclared group). - Constructed expression subset: fleets implements
compose,keyed_groups, andgroupsover a documented expression grammar (arithmetic,~, slicing, and a curated filter set incl.regex_replace), and errors loudly on syntax outside it (e.g.map/selectattr, dict literals) instead of silently producing wrong groups/vars.regex_replacebackreference translation is best-effort, so exotic Python-repatterns may diverge. Seedocs/anomalies.md§28–32 for the supported grammar and the verified compose ordering, snapshot-isolation, and type-coercion semantics.
Tracing
When built with --features telemetry, fleets can export OpenTelemetry spans for inventory
processing to an OTLP/HTTP collector such as Jaeger. Export remains off at runtime unless
enabled via ~/.config/fleets/config.toml:
[]
= true
= "http://localhost:4318"
= "fleets"
You get a load_inventory root span with one child span per source (named by kind:
parse_yaml/parse_toml/parse_ini/parse_script/parse_directory), directory sub-sources
nested under their directory, and a constructed span for the constructed-plugin synthesis
pass. See docs/tracing.md for details.
Benchmark
On one Apple Silicon development machine, the checked 5000-host benchmark measured 29.8 ms for fleets and 1.55 s for ansible-core 2.18.9 (51.9× median speedup). Results vary by machine; the script validates equivalent successful output before recording timings.
Security
Treat inventory sources as trusted input. Executable inventory sources are run directly and
inherit the fleets process environment; fleets does not sandbox them. See
SECURITY.md for reporting vulnerabilities.
Rust API
Fleets is CLI-first. The small API re-exported from the crate root is experimental during the
0.1.x series and may change in 0.2.0.
License
Licensed under the MIT License.