admin_rb
70 lines
2.2 KiB
Markdown
70 lines
2.2 KiB
Markdown
# AIM inventory hierarchy discovery
|
|
|
|
**AIM 3.3.0rc8 / service API 1.0.** `inventory_hierarchy_v1` is a read-only,
|
|
additive discovery capability. It exists so interfaces can present AIM's actual
|
|
inventory group/subgroup structure without duplicating Ansible-inventory parsing.
|
|
|
|
## Public operation
|
|
|
|
Python:
|
|
|
|
```python
|
|
result = AimService().inventory_hierarchy('CUSTOMER')
|
|
```
|
|
|
|
Machine interface:
|
|
|
|
```bash
|
|
printf '%s\n' '{"api_version":"1.0","operation":"inventory_hierarchy","customer":"CUSTOMER"}' | aimctl request
|
|
```
|
|
|
|
Query `capabilities.inventory_hierarchy` before relying on this operation.
|
|
|
|
The result has this shape:
|
|
|
|
```json
|
|
{
|
|
"api_version": "1.0",
|
|
"schema": "inventory_hierarchy_v1",
|
|
"customer": "CUSTOMER",
|
|
"hosts": ["direct-customer-host.example"],
|
|
"groups": [
|
|
{
|
|
"name": "windows",
|
|
"path": ["windows"],
|
|
"hosts": ["win01.example"],
|
|
"children": [
|
|
{
|
|
"name": "servers",
|
|
"path": ["windows", "servers"],
|
|
"hosts": ["win02.example"],
|
|
"children": []
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
`hosts` on each node means **direct membership in that node**, not recursively
|
|
expanded membership. A client can render descendants without guessing whether a
|
|
host came from the parent or a subgroup. Group nesting is preserved to a bounded
|
|
64 levels / 10,000 group nodes; malformed mappings, aliases/cycles or larger
|
|
structures fail as invalid source rather than being silently flattened.
|
|
|
|
## Safety and execution boundary
|
|
|
|
Only customer/group names, group paths and inventory host names are returned.
|
|
Variables, addresses, credentials, Vault values, connection settings and group
|
|
vars are not part of this tree. `list_hosts` remains the flat host/address/platform
|
|
metadata operation.
|
|
|
|
The hierarchy is presentation/discovery metadata only. It does **not** add group
|
|
patterns to `RunRequest`, change `--limit`, authorize targets, or skip preparation
|
|
and review. Execution still accepts explicit host names and Core revalidates them
|
|
against current inventory/catalog compatibility.
|
|
|
|
Interfaces should not persist a competing hierarchy or derive execution authority
|
|
from a previously fetched tree. Fetch current hierarchy when presenting inventory,
|
|
then prepare the final explicit host request through Core.
|