aim-web2.1.0rc9

2026-09-22 19:23:17 +02:00
parent d095887d2e
commit 3dfc80b782
438 changed files with 31613 additions and 1510 deletions
@@ -0,0 +1,69 @@
+# 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.