feat: improve deployment modes and persistence validation

- Add validation for Deployment with PVC and multiple replicas
- Add validation for webhook component with PVC
- Update documentation with detailed deployment modes
- Document persistence limitations for all components
- Add examples for different deployment scenarios

Author: aleksandrovpa

README.md

@@ -1,7 +1,7 @@
 [![Artifact HUB](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/n8n)](https://artifacthub.io/packages/helm/open-8gears/n8n)
 
 > [!NOTE]
-> The n8n Helm chart is growing in pooularity.
+> The n8n Helm chart is growing in popularity.
 > We're looking for additional passionate maintainers and contributors
 > to improve and maintain this chart, governance, development, documentation and CI/CD workflows.
 > If you're interested in making a difference,
@@ -361,6 +361,98 @@ main:
   tolerations: []
   affinity: {}
 
+## Deployment Modes
+
+### Main Component
+
+The main n8n component can be deployed in two modes:
+
+1. **Deployment (default)**:
+   - Suitable for Community Edition
+   - Limited to 1 replica when using persistent storage (PVC)
+   - Can use multiple replicas only with `emptyDir` storage (data will be lost on pod restart)
+
+```yaml
+main:
+  replicaCount: 1  # Must be 1 with persistent storage
+  statefulSet:
+    enabled: false
+  persistence:
+    enabled: true
+    type: dynamic
+    size: 10Gi
+```
+
+2. **StatefulSet**:
+   - Required for multiple replicas with persistent storage
+   - Requires n8n Enterprise license
+   - Each pod gets its own persistent volume
+
+```yaml
+main:
+  replicaCount: 3  # Can be >1 with StatefulSet
+  statefulSet:
+    enabled: true
+  persistence:
+    enabled: true
+    type: dynamic
+    size: 10Gi
+  extraEnv:
+    N8N_MULTI_MAIN_SETUP_ENABLED:
+      value: "true"  # Required for multiple replicas
+```
+
+### Worker Component
+
+The worker component can be deployed either as Deployment or StatefulSet:
+
+```yaml
+worker:
+  enabled: true
+  count: 2
+  statefulSet:
+    enabled: true  # or false for Deployment
+  persistence:
+    enabled: true
+    size: 5Gi
+```
+
+### Webhook Component
+
+The webhook component is deployed as a Deployment and has the same limitations as the main component when using persistent storage:
+
+1. **With Persistent Storage**:
+   - Limited to 1 replica when using PVC
+   - Data is preserved between pod restarts
+
+```yaml
+webhook:
+  enabled: true
+  replicaCount: 1  # Must be 1 with persistent storage
+  persistence:
+    enabled: true
+    type: dynamic
+    size: 5Gi
+```
+
+2. **Without Persistent Storage or with emptyDir**:
+   - Can use multiple replicas
+   - Data is lost on pod restarts
+
+```yaml
+webhook:
+  enabled: true
+  replicaCount: 3  # Can be >1
+  persistence:
+    enabled: true
+    type: emptyDir  # or enabled: false
+  deploymentStrategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxSurge: 25%
+      maxUnavailable: 25%
+```
+
 ## High Availability Setup
 
 The chart supports two deployment modes for the main n8n component:
@@ -517,6 +609,7 @@ worker:
 
   # here you can override the livenessProbe for the main container
   # it may be used to increase the timeout for the livenessProbe (e.g., to resolve issues like
+
   livenessProbe:
     httpGet:
       path: /healthz
@@ -543,6 +636,12 @@ worker:
   # List of initialization containers belonging to the pod. Init containers are executed in order prior to containers being started.
   # See https://kubernetes.io/docs/concepts/workloads/pods/init-containers/
   initContainers: []
+  #    - name: init-data-dir
+  #      image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
+  #      command: [ "/bin/sh", "-c", "mkdir -p /home/node/.n8n/" ]
+  #      volumeMounts:
+  #        - name: data
+  #          mountPath: /home/node/.n8n
 
   service:
     annotations: {}

charts/n8n/Chart.yaml

@@ -1,6 +1,6 @@
 apiVersion: v2
 name: n8n
-version: 1.0.4
+version: 1.1.0
 appVersion: 1.81.4
 type: application
 description: "Helm Chart for deploying n8n on Kubernetes, a fair-code workflow automation platform with native AI capabilities for technical teams. Easily automate tasks across different services."

charts/n8n/templates/_helpers.tpl

@@ -125,3 +125,15 @@ app.kubernetes.io/instance: {{ .Release.Name }}
 {{- fail "Webhook processes rely on Valkey. Please set valkey.enabled=true when webhook.enabled=true" -}}
 {{- end -}}
 {{- end }}
+
+{{/*
+Validate values for n8n deployment
+*/}}
+{{- define "n8n.validateValues" -}}
+{{- if and (not .Values.main.statefulSet.enabled) (gt (int .Values.main.replicaCount) 1) (ne .Values.main.persistence.type "emptyDir") -}}
+{{- fail "\nERROR: Invalid configuration\nWhen using Deployment (statefulSet.enabled=false) with persistent storage, replicaCount must be 1.\nTo use multiple replicas either:\n  1. Enable StatefulSet (requires Enterprise license)\n  2. Use emptyDir for persistence (data will be lost on pod restart)" -}}
+{{- end -}}
+{{- if and .Values.webhook.enabled .Values.webhook.persistence.enabled (ne .Values.webhook.persistence.type "emptyDir") (gt (int .Values.webhook.replicaCount) 1) -}}
+{{- fail "\nERROR: Invalid webhook configuration\nWhen using persistent storage for webhook component, replicaCount must be 1.\nTo use multiple replicas either:\n  1. Disable persistence\n  2. Use emptyDir for persistence (data will be lost on pod restart)" -}}
+{{- end -}}
+{{- end -}}

charts/n8n/templates/deployment.webhook.yaml

@@ -1,6 +1,7 @@
 {{- if .Values.webhook.enabled }}
 {{- /* Validate Valkey/Redis configuration */}}
 {{- include "n8n.validateValkey" . }}
+{{- include "n8n.validateValues" . }}
 apiVersion: apps/v1
 kind: Deployment
 metadata:

charts/n8n/templates/deployment.yaml

@@ -1,4 +1,5 @@
 {{- if not .Values.main.statefulSet.enabled }}
+{{- include "n8n.validateValues" . }}
 apiVersion: apps/v1
 kind: Deployment
 metadata: