Fix NFS export, security and consolidate firewall rules

Replace no_root_squash with root_squash in NFS export options. With
no_root_squash, any root user on K8s nodes (or root-running pods) had
full root access to all NFS shares. Now squashed root maps to
configurable anonuid/anongid (default 65534/nobody).

Add anonuid and anongid to the exports template so the mapping is
explicit in /etc/exports.

Consolidate UFW firewall configuration and validation into a single
block so all rules, enable, and verification run as one atomic unit
gated on UFW availability.

Change fsid: fsid is needed because we're exporting subdirectories of a FUSE filesystem (mergerfs).
The loop.index starts at 1 and increments. This is fine as long as storage_dirs never changes order.
If we reorder or insert a directory, existing mounts may break because the fsid changed.
So instead, using a hash of the directory name.

Exporting subdirectories instead of the root. We export /mnt/storage/Videos,
/mnt/storage/Music, etc. separately. This means every app that needs access
to a different subdirectory requires its own PV/PVC.
Instead, export /mnt/storage once and use subPath in K8s volume mounts.
This dramatically simplifies the NFS side and reduces the number of NFS connections.

Author: serpro69

docs/guides/how_to_use_nfs_for_persistent_storage.md

@@ -79,6 +79,27 @@ You can have some (or all) of your persistent volumes provisioned on your NAS se
 --8<--
 ```
 
+## NFS Permissions and `root_squash`
+
+The NFS server is configured with `root_squash` (the NFS default). This means any process connecting as root (uid 0) from a K8s node is mapped to the anonymous user on the NFS server. Non-root users pass through unchanged.
+
+The anonymous uid/gid is configured via `nfs_anon_uid`/`nfs_anon_gid` (default `1000`) and should match the `fsGroup` used by your application pods. This ensures that:
+
+- **kubelet `fsGroup` chown** works correctly — the kubelet runs as root, so its chown calls are squashed to uid 1000, which matches the target group
+- **Root-running containers** (e.g., linuxserver.io images that start as root before dropping to `PUID`/`PGID`) create files owned by uid 1000 on the NFS server
+- **Non-root containers** running as uid 1000 can read/write files created by either path above
+
+Your pod spec should set `fsGroup` to match:
+
+```yaml
+spec:
+  securityContext:
+    fsGroup: 1000
+```
+
+!!! tip
+    If your applications use a different uid (e.g., 568 for some Helm charts), override `nfs_anon_uid` and `nfs_anon_gid` in your inventory to match.
+
 ## Reference
 
 - [csi-driver-nfs/charts/README.md@v4.13.0 · kubernetes-csi/csi-driver-nfs](https://github.com/kubernetes-csi/csi-driver-nfs/blob/v4.13.0/charts/README.md)

metal/roles/storage/defaults/main.yml

@@ -3,7 +3,13 @@
 homelab_net_cidr: "10.10.10.0/24"
 
 # Default NFS export options
-default_nfs_options: "rw,sync,no_subtree_check,no_root_squash,insecure"
+default_nfs_options: "rw,sync,no_subtree_check,root_squash,insecure"
+
+# Anonymous uid/gid for root_squash mapping (squashed root becomes this user).
+# Set to match the uid/gid used by application pods (e.g. fsGroup) so that
+# root-running containers and kubelet fsGroup chown operations work correctly.
+nfs_anon_uid: 1000
+nfs_anon_gid: 1000
 
 # Firewall configuration
 manage_firewall: true # Set to false to skip firewall configuration

metal/roles/storage/tasks/nfs_firewall.yml

@@ -2,10 +2,6 @@
 # NFS Firewall Configuration
 # Configures UFW firewall rules for NFS services
 
-# =================================================================
-# FIREWALL DETECTION AND SETUP
-# =================================================================
-
 - name: Check if UFW is installed
   command: which ufw
   register: ufw_check
@@ -30,11 +26,7 @@
   debug:
     msg: "UFW is {{ 'available' if ufw_available.rc == 0 else 'not available' }}"
 
-# =================================================================
-# UFW CONFIGURATION
-# =================================================================
-
-- name: Configure UFW firewall rules
+- name: Configure and validate UFW firewall
   when: ufw_available.rc == 0
   block:
     - name: Check UFW status
@@ -53,18 +45,18 @@
         direction: outgoing
         policy: allow
 
-    - name: Configure TCP ports in firewall
+    - name: Allow SSH access
       ufw:
         rule: allow
-        src: "{{ item.0 }}"
-        port: "{{ item.1 }}"
+        src: "{{ item }}"
+        port: "22"
         proto: tcp
-        comment: "{{ item.1 }}/tcp"
-      loop: "{{ firewall_allowed_networks | product(['22']) | list }}"
+        comment: "SSH 22/tcp"
+      loop: "{{ firewall_allowed_networks }}"
       loop_control:
-        label: "{{ item.0 }} -> {{ item.1 }}/tcp"
+        label: "{{ item }} -> 22/tcp"
 
-    - name: Configure NFS TCP ports in firewall
+    - name: Allow NFS TCP ports
       ufw:
         rule: allow
         src: "{{ item.0 }}"
@@ -75,18 +67,22 @@
       loop_control:
         label: "{{ item.0 }} -> {{ item.1 }}/tcp"
 
-    - name: Configure NFS UDP ports in firewall
+    - name: Allow NFS UDP ports
       ufw:
         rule: allow
         src: "{{ item.0 }}"
         port: "{{ item.1 }}"
         proto: udp
         comment: "NFS {{ item.1 }}/udp"
-      # UDP 2049 to support potential NFSv3 clients
       loop: "{{ firewall_allowed_networks | product(['111', '2049']) | list }}"
       loop_control:
         label: "{{ item.0 }} -> {{ item.1 }}/udp"
 
+    - name: Enable UFW if not active
+      ufw:
+        state: enabled
+      when: "'Status: active' not in ufw_status.stdout"
+
     - name: Display firewall rules
       command: ufw status numbered
       register: ufw_rules
@@ -97,28 +93,15 @@
         msg: "{{ ufw_rules.stdout_lines }}"
       when: ufw_rules.stdout_lines is defined
 
-    - name: Enable UFW if not active
-      ufw:
-        state: enabled
-      when: "'Status: active' not in ufw_status.stdout"
-      register: ufw_enable
-
-# =================================================================
-# FIREWALL VALIDATION
-# =================================================================
-
-- name: Validate firewall allows NFS traffic
-  when: ufw_available.rc == 0
-  block:
-    - name: Check if NFS ports are allowed
+    - name: Verify NFS firewall rules
       shell: |
         set -o pipefail
         ufw status | grep -E '(111|2049|20048)'
       register: nfs_ports_check
       changed_when: false
       failed_when: false
 
-    - name: Verify NFS firewall rules
+    - name: Assert NFS firewall rules are present
       assert:
         that:
           - nfs_ports_check.rc == 0

metal/roles/storage/tasks/nfs_validation.yml

@@ -38,24 +38,12 @@
   changed_when: false
   failed_when: showmount_result.rc != 0
 
-- name: Parse exported directories
-  set_fact:
-    exported_dirs: "{{ showmount_result.stdout_lines[1:] | map('regex_replace', '^(/\\S+).*', '\\1') | list }}"
-  when: showmount_result.stdout_lines | length > 1
-
-- name: Display exported directories
-  debug:
-    msg: "Exported NFS directories: {{ exported_dirs | join(', ') }}"
-  when: exported_dirs is defined
-
-- name: Verify expected exports are present
+- name: Verify /mnt/storage export is present
   assert:
     that:
-      - "'/mnt/storage/' + item in exported_dirs"
-    fail_msg: "NFS export missing: /mnt/storage/{{ item }}"
-    success_msg: "NFS export present: /mnt/storage/{{ item }}"
-  loop: "{{ storage_dirs }}"
-  when: exported_dirs is defined
+      - "'/mnt/storage' in showmount_result.stdout"
+    fail_msg: "NFS export missing: /mnt/storage"
+    success_msg: "NFS export present: /mnt/storage"
 
 - name: Check if ufw firewall is active
   command: ufw status
@@ -161,19 +149,13 @@
         fail_msg: "Cannot reach NFS exports from controller - check firewall and network connectivity"
         success_msg: "NFS exports visible from controller"
 
-    - name: Parse remote exported directories
-      set_fact:
-        remote_exported_dirs: "{{ remote_showmount.stdout_lines[1:] | map('regex_replace', '^(/\\S+).*', '\\1') | list }}"
-      when: remote_showmount.stdout_lines | length > 1
-
-    - name: Verify expected exports visible from controller
+    - name: Verify /mnt/storage export visible from controller
       assert:
         that:
-          - "'/mnt/storage/' + item in remote_exported_dirs"
-        fail_msg: "NFS export not visible from controller: /mnt/storage/{{ item }}"
-        success_msg: "NFS export visible from controller: /mnt/storage/{{ item }}"
-      loop: "{{ storage_dirs }}"
-      when: remote_exported_dirs is defined
+          - "'/mnt/storage' in remote_showmount.stdout"
+        fail_msg: "NFS export not visible from controller: /mnt/storage"
+        success_msg: "NFS export visible from controller: /mnt/storage"
+      when: remote_showmount.rc == 0
 
 - name: NFS validation complete
   debug:

metal/roles/storage/templates/exports.j2

@@ -3,10 +3,8 @@
 #
 # Generated by Ansible - DO NOT EDIT MANUALLY
 
-# Default NFS exports for Kubernetes
-{% for dir in storage_dirs %}
-/mnt/storage/{{ dir }} {{ homelab_net_cidr | default('10.10.10.0/24') }}({{ default_nfs_options }},fsid={{ loop.index }})
-{% endfor %}
+# Single root export — clients mount subdirectories via path (e.g. server:/mnt/storage/Videos)
+/mnt/storage {{ homelab_net_cidr | default('10.10.10.0/24') }}({{ default_nfs_options }},anonuid={{ nfs_anon_uid }},anongid={{ nfs_anon_gid }},fsid=1)
 
 # Custom exports (if defined in inventory)
 {% if nfs_exports is defined %}