Merge pull request 'fix(ipa): harden script and update module docs' (#82) from worktree-ipa-client-module into main

Reviewed-on: #82

modules/ipa/client.nix

@@ -6,35 +6,39 @@
 #
 # Usage (in a host.nix imports list):
 #   (import ../../modules/ipa/client.nix {
-#     keytabSopsFile = ../../secrets/nix-cache.keytab;
-#     caCertFile     = ../../certs/ipa-ca.crt;
+#     keytabSopsFile = ../../secrets/<hostname>.keytab;
+#     caCertFile     = ../../certs/ipa-ca.crt;  # already committed — do not re-fetch
 #   })
 #
+# The host.nix networking block must also set:
+#   networking.domain   = vars.homeDomain;         # needed for Kerberos FQDN
+#   networking.nameservers = [ vars.domainControllerIp ];  # IPA DNS
+#
 # One-time operator setup per host (do this BEFORE deploying):
 #
-#   1. Fetch the IPA CA certificate (public — safe to commit):
-#        curl -o certs/ipa-ca.crt http://<ipa-server>/ipa/config/ca.crt
-#      Replace the placeholder at certs/ipa-ca.crt and commit it.
+#   0. Generate SSH host keys and the host's age key for sops:
+#        scripts/secrets/sync-host-keys.sh <flake-target>
+#      This must run before step 1 so the host age key is in .sops.yaml
+#      and the keytab can be encrypted for the host to read at boot.
 #
-#   2. On the FreeIPA server, add the host and generate a keytab:
-#        ipa host-add <fqdn> --ip-address=<ip>
-#        ipa-getkeytab -s <ipa-server> -p host/<fqdn> -k /tmp/<host>.keytab
+#   1. Add the IPA host account and produce the sops-encrypted keytab:
+#        scripts/ipa/create-nixos-ipa-host-account.sh [--ip <addr>] <hostname>
+#      The script handles ipa host-add, ipa-getkeytab, .sops.yaml patching,
+#      and sops encryption in one step. See the script header for details.
 #
-#   3. sops-encrypt the keytab as a binary secret from your admin machine
-#      (must run from repo root; sops matches creation rules against the file
-#      path, so copy to secrets/ first and encrypt in-place):
+#   2. Wire up the host (see "Usage" above), then deploy:
+#        nixos-rebuild switch  (or create-proxmox-resource.sh)
+#      No further manual enrollment steps are required after deployment.
+#
+# Manual fallback (if the script isn't usable):
+#   a. On the FreeIPA server: ipa host-add <fqdn> [--ip-address=<ip>] --force
+#   b. On the FreeIPA server: ipa-getkeytab -s <ipa-server> -p host/<fqdn> -k /tmp/<host>.keytab
+#   c. From the repo root (path must match for sops creation rule to apply):
 #        cp /tmp/<host>.keytab secrets/<host>.keytab
 #        sops -e --input-type binary -i secrets/<host>.keytab
-#      Add secrets/<host>.keytab to .sops.yaml with the host's age key as a
-#      recipient (see the nix-cache.keytab entry for the pattern), then run:
-#        scripts/secrets/sync-host-keys.sh <target>   # if not done yet
-#        sops updatekeys secrets/<host>.keytab
-#      Commit the encrypted file.
+#   d. Commit secrets/<host>.keytab and the updated .sops.yaml, then deploy.
 #
-#   4. nixos-rebuild switch (or create-proxmox-resource.sh) — no further
-#      manual enrollment steps required.
-#
-# vars dependencies: homeDomain, ipaServer
+# vars dependencies: homeDomain, ipaServer, domainControllerIp
 
 { keytabSopsFile, caCertFile }:
 { config, lib, pkgs, vars, ... }: