# Additional Notes — Ansible NFS Playbook (Iron Legion)

**Date:** 2026-06-04 | **Author:** Artemis (AI Foreman)

---

## Nuance 1: `ansible_ssh_private_key_file` per node

Most fleet nodes use the standard `id_ed25519` key (auto-discovered). Mark44 requires `vscode_ed25519` — the code-server key. Because it's a special case, mark44's inventory block sets:

```yaml
mark44:
  ansible_host: 192.168.5.214
  ansible_user: jarvis
  ansible_ssh_private_key_file: /root/.ssh/vscode_ed25519
```

**Don't change this to `id_ed25519`** — mark44's `authorized_keys` only contains:
1. The Termius key (artemis_key)
2. The vscode_ed25519 key

The artemis_key is NOT auto-discovered by Ansible because the filename is non-standard. Keep the explicit `ansible_ssh_private_key_file` for mark44.

---

## Nuance 2: What the `repogroup` actually is

`repogroup` is a **local alias** for TrueNAS's `apps` group (GID 568). The mapping works like this:

| System | Group Name | GID |
|--------|-----------|-----|
| TrueNAS | `apps` | 568 |
| Client | `repogroup` | 568 |

NFSv4 identity mapping sees the numeric GID only, not the symbolic name. So "jarvis in group 568" on the client maps to "jarvis in group `apps`" on TrueNAS.

**No TrueNAS-side user creation is needed** on clients. We only need the local group with the matching GID.

---

## Nuance 3: NFS mount opts evolution

| Stage | Mount opts | Result |
|-------|-----------|--------|
| Old (broken) | `defaults,_netdev` | Mount failed — TrueNAS rejects unversioned (v3) negotiation |
| Current | `vers=4.2,proto=tcp,_netdev` | Mount succeeds; root can RWX |

The `proto=tcp` is required because UDP negotiation can silently fall back and fail on large packets.

---

## Nuance 4: Why `ansible.posix.mount` instead of `mount` module

The native Ansible `ansible.posix.mount` module handles idempotency correctly:
- If already mounted at the same `src` + `path` + `opts`, reports `ok`
- If opts don't match, reports `changed` and remounts
- If `state: mounted`, ensures `/etc/fstab` entry is added

Manual `shell: mount ...` would create duplicate fstab entries.

---

## Nuance 5: TrueNAS server-side `chmod 775` on `/mnt/Ice/Repo`

This was applied as an emergency fix during debugging. The correct long-term approach would be to add a proper NFS4 ACL entry for `jarvis` (UID 1000) via TrueNAS WebUI or `midclt` API, but the `chmod 775` workaround is sufficient for production.

**Command used (for record):**
```bash
ssh -i ~/.ssh/artemis_key jarvis@192.168.16.254 'sudo chmod 775 /mnt/Ice/Repo'
```

---

## Nuance 6: Host targeting syntax edge cases

Ansible supports two exclusion syntaxes:

1. **Union + subtraction:** `hosts: fleet_nodes:!pve_hosts:!igor` ✅ Working
2. **Direct group list:** `hosts: physical_agents:core_services:infrastructure` ❌ Broken — `nfs_shares` variable is scoped under `fleet_nodes`, not these child groups

The inventory variable `nfs_shares` is defined at `fleet_nodes` level. Exclusion from `fleet_nodes` is the only way to get the variable AND exclude specific children.

---

## Nuance 7: Container vs bare-metal execution

When running Ansible inside the Docker container (`docker exec -it ansible ...`):
- SSH keys mount to `/root/.ssh` inside container
- `ansible.cfg` lives in `/ansible` (container working dir)

When running Ansible on the host (Artemis bare metal):
- SSH keys at `/home/jarvis/.ssh` 
- `ansible.cfg` may be in `/home/jarvis/.ansible-repo` or current dir

The playbooks are identical but paths may differ. Always run from the project root where `ansible.cfg` and inventory files exist.