# AIM Inventory Model

## Source of truth

The authoritative inventory is:

``` text
/etc/ansible/inventories/<customer>/hosts.yml
```

AIM does not use `.hosts.tsv` as a secondary database and does not
reverse-sync TSV data into YAML.

AIM uses round-trip YAML handling so valid manually maintained
structures/comments can be preserved where possible.

## Platform groups

Default top-level platform groups:

``` text
linux
windows
sophosxgs
pfsense
```

Platform remains top-level because it determines connection semantics
such as SSH, WinRM or HTTPAPI.

Hosts may have multiple memberships and optional one-level functional
subgroups.

## Linux

Linux group variables normally include the SSH connection and service
account. The customer SSH key directory is:

``` text
group_vars/linux/.ssh/
```

not:

``` text
group_vars/linux/files/.ssh/
```

`ansible_ssh_pass` may remain configured as a legacy
remote-login-password fallback. A private-key passphrase is a separate
secret.

## Windows

Domain-joined Windows hosts normally inherit the group-level service
identity/password.

A local-account host can override credentials in:

``` text
host_vars/<fqdn>/main.yml
```

Shared local example:

``` yaml
ansible_user: svc_bf-ansible
ansible_password: "{{ vault_windows_local_ansible_password }}"
```

Host-specific example:

``` yaml
ansible_user: svc_bf-ansible
ansible_password: "{{ vault_ansible_password_server01_example_lan }}"
```

## Host vars

Every newly managed host has:

``` text
host_vars/<fqdn>/main.yml
```

Existing host-vars content is not blindly overwritten.

## Customer defaults

AIM customer defaults live in:

``` text
/etc/ansible/inventories/<customer>/.aim.yml
```

Example:

``` yaml
domain_suffix: bfmiglabor.lan
network_address: 10.20.30.0
netmask: 255.255.255.0
ad_dns_domain: intra.company.de
ad_netbios_domain: COMPANY
```

The AD DNS domain is used for service-account UPNs. NetBIOS remains
metadata/legacy naming information.

## Safe writes

Inventory mutations use the conceptual sequence:

``` text
candidate temp file
→ local YAML validation
→ compare
→ session backup
→ atomic replace
```

AIM also protects against stale/concurrent writes and uses an inventory
lock.