Synology NAS Setup — Storage for K8s (10.2.10.19)¶

Prerequisites¶

Synology DSM 7.x
BTRFS filesystem
Two available disk groups / storage pools for volume3 (1TB) and volume4 (2TB)

Part A — Synology CSI Driver (iSCSI — Cluster-Managed Storage)¶

The Synology CSI driver lets the k8s cluster dynamically create, resize, and snapshot block volumes (iSCSI LUNs) on the NAS. Existing NFS shares and volumes are not affected — LUNs are stored under /volumeN/@iSCSI/ (hidden dir).

A1. Create DSM User `k8s-csi`¶

Control Panel → User & Group → Create
Username: k8s-csi
Password: strong random (store in vault/sealed-secret)
User group: users only — NOT administrators
Application Permissions → set everything to Deny except:
DSM → Allow (required for API login)
iSCSI Manager (or "SAN Manager" on newer DSM) → Allow
Shared Folder Permissions → No Access on ALL shared folders (k8s-apps, k8s-backups, homes, etc.)
Speed Limit / Quota → optionally set a storage quota

A2. Enable iSCSI Service¶

SAN Manager (install from Package Center if missing)
iSCSI tab → Ensure iSCSI service is Enabled
No need to create targets/LUNs manually — the CSI driver handles this

A3. Firewall — Restrict API Access¶

Control Panel → Security → Firewall → Edit Rules
Add rule: Allow ports 5000-5001 (DSM) + 3260 (iSCSI) from:
10.2.20.200 (k8s-cp-office-1)
10.2.20.100 (k8s-worker-office-1)
10.2.20.101 (k8s-worker-office-2)
Deny all other sources for these ports

A4. Seal the DSM Credentials¶

# On k8s-cp-office-1:
cat <<'EOF' | kubeseal \
  --controller-name sealed-secrets \
  --controller-namespace sealed-secrets \
  -o yaml > synology-csi-client-info.sealed.yaml
apiVersion: v1
kind: Secret
metadata:
  name: synology-csi-client-info
  namespace: synology-csi
type: Opaque
stringData:
  client-info.yml: |
    clients:
      - host: 10.2.10.19
        port: 5001
        https: true
        username: k8s-csi
        password: YOUR_PASSWORD_HERE
EOF

A5. Security Summary¶

Layer	Protection
DSM user `k8s-csi`	No admin rights, no shared-folder access
DSM firewall	Only k8s nodes can reach DSM API + iSCSI
iSCSI isolation	LUNs stored in `@iSCSI/` hidden dir, separate from NFS
StorageClass `location`	Locks LUN creation to specific volume path
K8s RBAC	CSI controller uses dedicated ServiceAccount
Sealed Secrets	DSM password encrypted at rest in git

volume3 and volume4 themselves CANNOT be deleted, resized, or structurally modified by the CSI driver. It only creates/deletes iSCSI LUN files within them.

Part B — NFS Setup (Static Shares — Manual DSM Config)¶

Part B1. Create Storage Pools & Volumes¶

Open Storage Manager → Storage Pool
Create Storage Pool 3 (for app data):
Select disk(s) → RAID type as appropriate (SHR/RAID1 for redundancy or Basic for max space)
Filesystem: Btrfs
Create Volume 3 on Pool 3:
Size: 1 TB
Name: volume3
Create Storage Pool 4 (for backups):
Select disk(s)
Filesystem: Btrfs
Create Volume 4 on Pool 4:
Size: 2 TB
Name: volume4

If the volumes already exist as volume3/volume4, skip to the next step.

2. Create Shared Folders¶

Open Control Panel → Shared Folder
Create shared folder k8s-apps:
Location: Volume 3
Enable data checksum: Yes (Btrfs)
Enable data compression: Yes (Btrfs, optional — saves space for text-heavy data)
Do NOT encrypt
Create shared folder k8s-backups:
Location: Volume 4
Enable data checksum: Yes
Enable data compression: No (backups are often already compressed)

3. Enable NFS¶

Open Control Panel → File Services → NFS
Enable NFS Service
Maximum NFS protocol: NFSv4.1
Click Apply

4. Set NFS Permissions¶

For each shared folder:

Open Control Panel → Shared Folder
Select k8s-apps → Edit → NFS Permissions tab
Click Create:
Hostname or IP: 10.2.0.0/16
Privilege: Read/Write
Squash: Map all users to admin (ensures k8s pods can write)
Security: sys
Enable asynchronous: Yes (better performance)
Allow connections from non-privileged ports: Yes
Allow users to access mounted subfolders: Yes
Repeat for k8s-backups

5. Create Subdirectories¶

SSH into the NAS or use File Station to create the directory structure:

# SSH to Synology (enable SSH in Control Panel → Terminal & SNMP)
ssh [email protected]

# App data directories
sudo mkdir -p /volume3/k8s-apps

# Backup directories
sudo mkdir -p /volume4/k8s-backups/longhorn
sudo mkdir -p /volume4/k8s-backups/cnpg

# Set permissions (wide open for NFS — squash handles the mapping)
sudo chmod -R 777 /volume3/k8s-apps
sudo chmod -R 777 /volume4/k8s-backups

6. Configure BTRFS Snapshots (Recommended)¶

Open Snapshot Replication (install from Package Center if missing)
Create snapshot schedule for k8s-backups:
Frequency: Daily at 03:00 (after CNPG nightly backup at 02:00)
Retention: Keep 30 snapshots (rolling 30-day history)
Optionally create snapshot schedule for k8s-apps:
Frequency: Daily at 04:00
Retention: Keep 7 snapshots

This gives you a layered backup strategy: - Layer 1: CNPG → MinIO (in-cluster, point-in-time recovery) - Layer 2: Longhorn volume backups → NFS on NAS - Layer 3: Synology BTRFS snapshots of the NFS shares (immutable point-in-time)

Verification¶

After DSM setup is complete, test from any cluster node:

# From k8s-cp-office-1 (10.2.20.200):
sudo apt install -y nfs-common   # if not already installed
sudo mount -t nfs4 10.2.10.19:/volume3/k8s-apps /mnt
ls /mnt
sudo umount /mnt

sudo mount -t nfs4 10.2.10.19:/volume4/k8s-backups /mnt
ls /mnt
sudo umount /mnt

Then apply the Kubernetes manifests:

# Sealed secret for CNPG backup creds (via ArgoCD — just push to git)
git push  # ArgoCD picks up sealed-secrets/sealed/pg-backup-minio-creds.sealed.yaml

# NFS provisioner (via ArgoCD — just push to git)
git push  # ArgoCD picks up argocd-apps/infra/nfs-provisioner.yaml

# Longhorn backup target is set via Helm values in argocd-apps/infra/longhorn.yaml
# ArgoCD will sync the setting automatically.

What Gets Stored Where¶

Path	Purpose	Size	Protocol
`/volume3/k8s-apps/`	NFS PVCs for office apps (Paperless, Nextcloud, media)	1 TB	NFS
`/volume3/@iSCSI/`	Synology CSI dynamic block volumes	shared w/ volume3	iSCSI
`/volume4/k8s-backups/longhorn/`	Longhorn volume backup snapshots	2 TB shared	NFS
`/volume4/k8s-backups/cnpg/`	Reserved for future direct CNPG WAL shipping	2 TB shared	NFS
`/volume4/@iSCSI/`	Synology CSI backup LUNs	shared w/ volume4	iSCSI

Cluster Permissions — What the K8s Cluster CAN and CANNOT Do¶

CAN (via Synology CSI + NFS provisioner)¶

Create new iSCSI LUNs (dynamic PV provisioning)
Resize iSCSI LUNs (PVC expansion)
Take CSI snapshots of iSCSI LUNs
Delete iSCSI LUNs (when PV reclaim policy is Delete)
Create/delete subdirectories under NFS shares

CANNOT¶

Delete or resize volume3 / volume4
Create or delete storage pools
Modify NFS share settings or permissions
Access shared folders via DSM API (k8s-csi user has no access)
Reach DSM API from outside the k8s subnet (firewall)
See or modify any data outside its own iSCSI LUNs