Adds StatefulSet support (#549)

* Adds StatefulSet support

# Conflicts:
#	helm/opengist/templates/pvc.yaml

* Adds statefulset support for replicaCount gt 1

* Improves the setup of multiple replicas in a stateful set

* Adds config wrangling logic to the secret template

* Adds shared PV functionality

* Adds missing pvc-shared template

* Adds stateful set and documentation

---------

Co-authored-by: Guillem Riera <guillem@rieragalm.es>

helm/opengist/values.yaml

@@ -32,6 +32,34 @@ strategy:
     maxSurge: "100%"
     maxUnavailable: 0
 
+## StatefulSet configuration
+## Enables StatefulSet workload instead of Deployment (required for volumeClaimTemplates or stable pod identities).
+##
+## Single-replica SQLite example (default behavior):
+##   statefulSet.enabled: true
+##   replicaCount: 1
+##   persistence.mode: perReplica  # or omit (default)
+##   # Creates one PVC per pod via volumeClaimTemplates (RWO)
+##
+## Multi-replica requirements (replicaCount > 1):
+##   1. External database: config.db-uri must be postgres:// or mysql:// (SQLite NOT supported)
+##   2. Shared storage: Use ONE of:
+##      a) Existing claim:  persistence.existingClaim: "my-rwx-pvc"
+##      b) Chart-created:   persistence.mode: shared + persistence.create.enabled: true + accessModes: [ReadWriteMany]
+##   3. Chart will FAIL FAST if constraints are not met to prevent data divergence
+##
+## Persistence decision tree:
+##   - persistence.existingClaim set         → mount that PVC directly (no volumeClaimTemplates)
+##   - persistence.mode=shared + create.*    → chart creates single RWX PVC, all pods mount it
+##   - persistence.mode=perReplica (default) → volumeClaimTemplates (one PVC/pod, RWO typically)
+##   - persistence.enabled=false             → emptyDir (ephemeral)
+
+statefulSet:
+  enabled: false
+  podManagementPolicy: OrderedReady
+  updateStrategy:
+    type: RollingUpdate
+
 ## Security Context settings
 ## ref: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/
 podSecurityContext:
@@ -99,20 +127,66 @@ serviceAccount:
   annotations: {}
   name: ""
 
-## Set persistence using a Persistent Volume Claim
-## If more than 2 replicas are set, the access mode must be ReadWriteMany
+## Persistent storage for /opengist data directory
 ## ref: https://kubernetes.io/docs/concepts/storage/persistent-volumes/
 persistence:
   enabled: true
+
+  ## Persistence mode controls how storage is provisioned:
+  ##
+  ## perReplica (DEFAULT):
+  ##   - StatefulSet creates one PVC per replica via volumeClaimTemplates
+  ##   - Typically RWO (ReadWriteOnce) storage
+  ##   - Safe ONLY for replicaCount=1 (multi-replica causes data divergence)
+  ##   - Use when: single-node dev/test, no horizontal scaling needed
+  ##
+  ## shared:
+  ##   - Single RWX (ReadWriteMany) PVC shared by all replicas
+  ##   - Required for replicaCount > 1
+  ##   - Two provisioning paths:
+  ##     a) existingClaim: "my-rwx-pvc" (you manage the PVC lifecycle)
+  ##     b) existingClaim: "" + create.enabled: true (chart creates PVC automatically)
+  ##   - Use when: multi-replica HA, horizontal scaling, shared file access
+  ##
+  ## WARNING: Switching modes after initial deploy requires manual data migration:
+  ##   1. Scale down to 1 replica
+  ##   2. Create/provision RWX PVC and copy data
+  ##   3. Update values: mode=shared, existingClaim or create.enabled
+  ##   4. Scale up
+  mode: perReplica
+
+  ## Reference an existing PVC (takes precedence over create.*)
+  ## When set:
+  ##   - Chart will NOT create a PVC
+  ##   - StatefulSet mounts this claim directly (no volumeClaimTemplates)
+  ##   - Must be RWX for replicaCount > 1
+  ## Example: existingClaim: "opengist-shared-rwx"
   existingClaim: ""
-  storageClass: ""
+
+  ## Common persistence parameters (apply to perReplica mode OR as defaults for create.*)
+  storageClass: ""       # Empty = cluster default
   labels: {}
   annotations:
-    helm.sh/resource-policy: keep
+    helm.sh/resource-policy: keep  # Prevents PVC deletion on helm uninstall
   size: 5Gi
   accessModes:
-    - ReadWriteOnce
-  subPath: ""
+    - ReadWriteOnce      # perReplica default; override to [ReadWriteMany] if using existingClaim
+  subPath: ""            # Optional subpath within volume
+
+  ## Chart-managed PVC creation (ONLY for mode=shared when existingClaim is empty)
+  ## Renders templates/pvc-shared.yaml
+  create:
+    enabled: true
+    nameSuffix: shared   # PVC name: <release-name>-shared
+    storageClass: ""     # Empty = cluster default; override if you need specific storage class
+    size: 5Gi            # Override top-level persistence.size if needed
+    accessModes:
+      - ReadWriteMany    # REQUIRED for multi-replica; NFS/CephFS/Longhorn RWX/etc.
+    labels: {}
+    annotations: {}
+    ## Example for specific storage:
+    ##   storageClass: "nfs-client"
+    ##   size: 20Gi
 
 extraVolumes: []
 extraVolumeMounts: []