From 61a532054e183364d687570b9f73f344379065f7 Mon Sep 17 00:00:00 2001 From: Viktor Barzin Date: Mon, 2 Mar 2026 02:04:47 +0000 Subject: [PATCH] [ci skip] update CLAUDE.md: NFS volume pattern now uses CSI-backed nfs_volume module --- .claude/CLAUDE.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 0f717827..8540cb3d 100755 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -39,17 +39,27 @@ Terragrunt-based infrastructure repository managing a home Kubernetes cluster on ## Key Patterns ### NFS Volume Pattern -**Prefer inline NFS volumes** over separate PV/PVC resources. Use `var.nfs_server` (defined in `terraform.tfvars`, auto-loaded by Terragrunt): +**Use the `nfs_volume` shared module** for all NFS volumes. This creates CSI-backed PV/PVC with soft mount options (`soft,timeo=30,retrans=3`) — no stale mount hangs: ```hcl +module "nfs_data" { + source = "../../modules/kubernetes/nfs_volume" # or ../../../ for sub-stacks + name = "-data" # Must be globally unique (PV is cluster-scoped) + namespace = kubernetes_namespace..metadata[0].name + nfs_server = var.nfs_server + nfs_path = "/mnt/main/" +} + +# In pod spec: volume { name = "data" - nfs { - server = var.nfs_server - path = "/mnt/main/" + persistent_volume_claim { + claim_name = module.nfs_data.claim_name } } ``` -Only use PV/PVC when a Helm chart requires `existingClaim`. +For platform modules, use `source = "../../../../modules/kubernetes/nfs_volume"`. +**StorageClass**: `nfs-truenas` (deployed via `stacks/platform/modules/nfs-csi/`). +**DO NOT use inline `nfs {}` blocks** — they mount with `hard,timeo=600` defaults which hang forever on stale mounts. ### Adding NFS Exports 1. **Create the directory on TrueNAS first**: `ssh root@10.0.10.15 "mkdir -p /mnt/main/ && chmod 777 /mnt/main/"`