refactor(persistence)!: group the values into existingPersistentVolumeClaim and new

The flat `persistence` dict mixed three concerns: whether persistence is used at all, whether the chart creates the
PersistentVolumeClaim, and how that claim is shaped. The pairs `create`/`claimName` and `enabled`/`mount` were only
meaningful in certain combinations, so an invalid configuration such as `create=true` together with a foreign
`claimName` was silently accepted. The same split into an `existingX`/`new` pair is already used for the Secrets, so
this aligns persistence with the rest of the chart.

`persistence.enabled` now only decides whether a volume is used at all. `persistence.existingPersistentVolumeClaim`
points at a claim managed outside of the chart, and everything under `persistence.new` describes the claim the chart
creates itself. Rendering and naming move into `templates/gitea/_persistentVolumeClaims.tpl` so the Deployment and the
PersistentVolumeClaim derive the claim name from a single helper instead of repeating the value lookups.

Support for `global.storageClass` is dropped. It was a chart-wide override that silently applied to the Gitea claim and
was evaluated through `tpl`, which made the effective storage class hard to predict. The storage class is now set
explicitly via `persistence.new.storageClassName`, which also matches the field name in the PersistentVolumeClaim spec.

BREAKING CHANGE: The `persistence` values were restructured and `global.storageClass` was removed.

- `persistence.create` and `persistence.mount` are gone. Set `persistence.enabled` to use a volume and
  `persistence.existingPersistentVolumeClaim.enabled` to reuse a claim that is not managed by the chart.
- `persistence.claimName` moves to `persistence.existingPersistentVolumeClaim.persistentVolumeClaimName`. A claim
  created by the chart is now named after `gitea.fullname` instead of the default `gitea-shared-storage`.
- `persistence.accessModes`, `annotations`, `labels`, `size` and `subPath` move into `persistence.new`.
- `persistence.volumeName` becomes `persistence.new.persistentVolumeName`.
- `persistence.storageClass` and `global.storageClass` become `persistence.new.storageClassName`.
- `persistence.enabled` now defaults to `false`.

Co-authored-by: Copilot <copilot@github.com>

README.md

@@ -1023,7 +1023,6 @@ To comply with the Gitea helm chart definition of the digest parameter, a "custo
 | ------------------------- | -------------------------------------------------------------------------- | ----- |
 | `global.imageRegistry`    | global image registry override.                                            | `""`  |
 | `global.imagePullSecrets` | global image pull secrets override; can be extended by `imagePullSecrets`. | `[]`  |
-| `global.storageClass`     | global storage class override.                                             | `""`  |
 | `global.hostAliases`      | global hostAliases which will be added to the pod's hosts files.           | `[]`  |
 
 ### deployment
@@ -1288,18 +1287,17 @@ To comply with the Gitea helm chart definition of the digest parameter, a "custo
 ### Persistence
 
 | Name                                                                  | Description                                                                                        | Value               |
-| ------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------- |
-| `persistence.enabled`                             | Enable persistent storage.                                                                         | `true`                 |
-| `persistence.create`                              | Whether to create the persistentVolumeClaim for shared storage.                                    | `true`                 |
-| `persistence.mount`                               | Whether the persistentVolumeClaim should be mounted (even if not created).                         | `true`                 |
-| `persistence.claimName`                           | Use an existing claim to store repository information.                                             | `gitea-shared-storage` |
-| `persistence.size`                                | Size for persistence to store repo information.                                                    | `10Gi`                 |
-| `persistence.accessModes`                         | AccessMode for persistence.                                                                        | `["ReadWriteOnce"]`    |
-| `persistence.labels`                              | Labels for the persistence volume claim to be created.                                             | `{}`                   |
-| `persistence.annotations.helm.sh/resource-policy` | Resource policy for the persistence volume claim.                                                  | `keep`                 |
-| `persistence.storageClass`                        | Name of the storage class to use.                                                                  | `nil`                  |
-| `persistence.subPath`                             | Subdirectory of the volume to mount at.                                                            | `nil`                  |
-| `persistence.volumeName`                          | Name of persistent volume in PVC.                                                                  | `""`                   |
+| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------- |
+| `persistence.enabled`                                                 | Enable persistent storage.                                                                         | `false`             |
+| `persistence.existingPersistentVolumeClaim.enabled`                   | Enable using an existing persistent volume claim.                                                  | `false`             |
+| `persistence.existingPersistentVolumeClaim.persistentVolumeClaimName` | Name of the existing persistent volume claim to use.                                               | `""`                |
+| `persistence.new.annotations.helm.sh/resource-policy`                 | Resource policy for the new persistent volume claim.                                               | `keep`              |
+| `persistence.new.labels`                                              | Labels for the new persistent volume claim.                                                        | `{}`                |
+| `persistence.new.accessModes`                                         | AccessMode for the new persistent volume claim.                                                    | `["ReadWriteOnce"]` |
+| `persistence.new.persistentVolumeName`                                | Name of the persistent volume for the new persistent volume claim.                                 | `""`                |
+| `persistence.new.size`                                                | Size for the new persistent volume claim.                                                          | `10Gi`              |
+| `persistence.new.storageClassName`                                    | Name of the storage class to use for the new persistent volume claim.                              | `""`                |
+| `persistence.new.subPath`                                             | Subdirectory of the volume to mount at for the new persistent volume claim.                        | `""`                |
 | `extraContainers`                                                     | Additional sidecar containers to run in the pod.                                                   | `[]`                |
 | `extraInitVolumeMounts`                                               | Mounts that are only mapped into the init-containers. Can be used for additional preconfiguration. | `[]`                |
 | `extraVolumeMounts`                                                   | **DEPRECATED** Additional volume mounts for init containers and the Gitea main container.          | `[]`                |

templates/_helpers.tpl

@@ -154,17 +154,6 @@ These default to runAsUser 1000 outside OpenShift to preserve existing behavior.
 {{- include "gitea.containerSecurityContext" (list $root $containerSecurityContext) -}}
 {{- end -}}
 
-
-{{/*
-Storage Class
-*/}}
-{{- define "gitea.persistence.storageClass" -}}
-{{- $storageClass :=  (tpl ( default "" .Values.persistence.storageClass) .) | default (tpl ( default "" .Values.global.storageClass) .) }}
-{{- if $storageClass }}
-storageClassName: {{ $storageClass | quote }}
-{{- end }}
-{{- end -}}
-
 {{/*
 Common labels
 */}}

templates/gitea/_initContainers.tpl

@@ -40,8 +40,8 @@
       mountPath: /tmp
     - name: data
       mountPath: /data
-      {{- if .Values.persistence.subPath }}
-      subPath: {{ .Values.persistence.subPath }}
+      {{- if .Values.persistence.new.subPath }}
+      subPath: {{ .Values.persistence.new.subPath }}
       {{- end }}
     {{- include "gitea.init-additional-mounts" . | nindent 4 }}
     {{- with $config.volumeMounts }}
@@ -105,8 +105,8 @@
       mountPath: /tmp
     - name: data
       mountPath: /data
-      {{- if .Values.persistence.subPath }}
-      subPath: {{ .Values.persistence.subPath }}
+      {{- if .Values.persistence.new.subPath }}
+      subPath: {{ .Values.persistence.new.subPath }}
       {{- end }}
     - name: inline-config-sources
       mountPath: /env-to-ini-mounts/inlines/
@@ -168,8 +168,8 @@
       mountPath: {{ .Values.initContainersScriptsVolumeMountPath }}
     - name: data
       mountPath: /data
-      {{- if .Values.persistence.subPath }}
-      subPath: {{ .Values.persistence.subPath }}
+      {{- if .Values.persistence.new.subPath }}
+      subPath: {{ .Values.persistence.new.subPath }}
       {{- end }}
     - name: gpg-private-key
       mountPath: /raw
@@ -292,8 +292,8 @@
       mountPath: /tmp
     - name: data
       mountPath: /data
-      {{- if .Values.persistence.subPath }}
-      subPath: {{ .Values.persistence.subPath }}
+      {{- if .Values.persistence.new.subPath }}
+      subPath: {{ .Values.persistence.new.subPath }}
       {{- end }}
     {{- include "gitea.init-additional-mounts" . | nindent 4 }}
     {{- with $config.volumeMounts }}

templates/gitea/_persistentVolumeClaims.tpl

@@ -0,0 +1,38 @@
+{{/* vim: set filetype=mustache: */}}
+
+{{/* annotations */}}
+
+{{- define "gitea.persistentVolumeClaim.annotations" -}}
+{{- with .Values.persistence.new.annotations }}
+{{- toYaml . -}}
+{{- end }}
+{{- end }}
+
+{{/* enabled */}}
+
+{{- define "gitea.persistentVolumeClaim.enabled" -}}
+{{- if and .Values.persistence.enabled (not .Values.persistence.existingPersistentVolumeClaim.enabled) -}}
+true
+{{- else -}}
+false
+{{- end }}
+{{- end }}
+
+{{/* labels */}}
+
+{{- define "gitea.persistentVolumeClaim.labels" -}}
+{{ include "gitea.labels" . }}
+{{- with .Values.persistence.new.labels }}
+{{ toYaml . }}
+{{- end }}
+{{- end }}
+
+{{/* name */}}
+
+{{- define "gitea.persistentVolumeClaim.name" -}}
+{{- if .Values.persistence.existingPersistentVolumeClaim.enabled -}}
+{{ required "persistence.existingPersistentVolumeClaim.persistentVolumeClaimName is required when persistence.existingPersistentVolumeClaim.enabled is true" .Values.persistence.existingPersistentVolumeClaim.persistentVolumeClaimName }}
+{{- else -}}
+{{ include "gitea.fullname" . }}
+{{- end }}
+{{- end }}

templates/gitea/deployment.yaml

@@ -145,8 +145,8 @@ spec:
               mountPath: /tmp
             - name: data
               mountPath: /data
-              {{- if .Values.persistence.subPath }}
-              subPath: {{ .Values.persistence.subPath }}
+              {{- if .Values.persistence.new.subPath }}
+              subPath: {{ .Values.persistence.new.subPath }}
               {{- end }}
             {{- include "gitea.container-additional-mounts" . | nindent 12 }}
         {{- if .Values.extraContainers }}
@@ -211,12 +211,10 @@ spec:
             defaultMode: 0100
         {{- end }}
   {{- if .Values.persistence.enabled }}
-    {{- if .Values.persistence.mount }}
         - name: data
           persistentVolumeClaim:
-            claimName: {{ .Values.persistence.claimName }}
-    {{- end }}
-  {{- else if not .Values.persistence.enabled }}
+            claimName: {{ include "gitea.persistentVolumeClaim.name" . }}
+  {{- else }}
         - name: data
           emptyDir: {}
   {{- end }}

templates/gitea/persistentVolumeClaim.yaml

@@ -1,26 +1,33 @@
-{{- if and .Values.persistence.enabled .Values.persistence.create }}
+{{- if eq (include "gitea.persistentVolumeClaim.enabled" .) "true" }}
+---
 kind: PersistentVolumeClaim
 apiVersion: v1
 metadata:
-  name: {{ .Values.persistence.claimName }}
-  namespace: {{ .Values.namespace | default .Release.Namespace }}
+  {{- with (include "gitea.persistentVolumeClaim.annotations" .) }}
   annotations:
-{{ .Values.persistence.annotations | toYaml | indent 4}}
+    {{- . | nindent 4 }}
+  {{- end }}
+  {{- with (include "gitea.persistentVolumeClaim.labels" .) }}
   labels:
-{{ .Values.persistence.labels | toYaml | indent 4}}
+    {{- . | nindent 4 }}
+  {{- end }}
+  name: {{ include "gitea.persistentVolumeClaim.name" . }}
+  namespace: {{ .Release.Namespace }}
 spec:
   accessModes:
   {{- if gt (.Values.deployment.replicas | int) 1 }}
       - ReadWriteMany
   {{- else }}
-    {{- .Values.persistence.accessModes | toYaml | nindent 4 }}
-  {{- end }}
-  volumeMode: Filesystem
-  {{- include "gitea.persistence.storageClass" . | nindent 2 }}
-  {{- with .Values.persistence.volumeName }}
-  volumeName: {{ . }}
+    {{- .Values.persistence.new.accessModes | toYaml | nindent 4 }}
   {{- end }}
   resources:
     requests:
-      storage: {{ .Values.persistence.size }}
+      storage: {{ .Values.persistence.new.size }}
+  {{- with .Values.persistence.new.storageClassName }}
+  storageClassName: {{ . }}
+  {{- end }}
+  volumeMode: Filesystem
+  {{- with .Values.persistence.new.persistentVolumeName }}
+  volumeName: {{ . }}
+  {{- end }}
 {{- end }}

templates/gitea/secret_config.yaml

@@ -37,8 +37,8 @@ stringData:
       {{- end }}
     {{- end }}
 
-    {{- if eq (first .Values.persistence.accessModes) "ReadWriteOnce" -}}
-      {{- fail "When using multiple replicas, a RWX file system is required and persistence.accessModes[0] must be set to ReadWriteMany." -}}
+    {{- if eq (first .Values.persistence.new.accessModes) "ReadWriteOnce" -}}
+      {{- fail "When using multiple replicas, a RWX file system is required and persistence.new.accessModes[0] must be set to ReadWriteMany." -}}
     {{- end }}
     {{- if .Values.gitea.config.indexer -}}
       {{- if eq .Values.gitea.config.indexer.ISSUE_INDEXER_TYPE "bleve" -}}

unittests/helm/deployment/HA.yaml

@@ -17,6 +17,7 @@ tests:
       deployment:
         replicas: 2
       persistence:
+        new:
           accessModes:
             - ReadWriteMany
       gitea:
@@ -34,13 +35,14 @@ tests:
         replicas: 2
     asserts:
       - failedTemplate:
-          errorMessage: "When using multiple replicas, a RWX file system is required and persistence.accessModes[0] must be set to ReadWriteMany."
+          errorMessage: "When using multiple replicas, a RWX file system is required and persistence.new.accessModes[0] must be set to ReadWriteMany."
   - it: fails with multiple replicas and bleve issue indexer
     template: templates/gitea/secret_config.yaml
     set:
       deployment:
         replicas: 2
       persistence:
+        new:
           accessModes:
             - ReadWriteMany
       gitea:
@@ -56,6 +58,7 @@ tests:
       deployment:
         replicas: 2
       persistence:
+        new:
           accessModes:
             - ReadWriteMany
       gitea:

unittests/helm/deployment/storage-class-configuration.yaml

@@ -1,39 +1,17 @@
-# File: tests/gitea-storageclass-tests.yaml
-
-suite: storage class configuration tests
-
+chart:
+  appVersion: 1.27.3
 release:
-  name: gitea-storageclass-tests
+  name: gitea-unittests
   namespace: testing
-
+suite: Storage class configuration tests
 templates:
   - templates/gitea/persistentVolumeClaim.yaml
-
 tests:
-  - it: should set storageClassName when persistence.storageClass is defined
-    template: templates/gitea/persistentVolumeClaim.yaml
+  - it: Set storageClassName when persistence.new.storageClassName is defined
     set:
-      persistence.storageClass: "my-storage-class"
-    asserts:
-      - equal:
-          path: "spec.storageClassName"
-          value: "my-storage-class"
-
-  - it: should set global.storageClass when persistence.storageClass is not defined
-    template: templates/gitea/persistentVolumeClaim.yaml
-    set:
-      global.storageClass: "default-storage-class"
+      persistence.enabled: true
+      persistence.new.storageClassName: my-storage-class
     asserts:
       - equal:
           path: spec.storageClassName
-          value: "default-storage-class"
-
-  - it: should set storageClassName when persistence.storageClass is defined and global.storageClass is defined
-    template: templates/gitea/persistentVolumeClaim.yaml
-    set:
-      global.storageClass: "default-storage-class"
-      persistence.storageClass: "my-storage-class"
-    asserts:
-      - equal:
-          path: spec.storageClassName
-          value: "my-storage-class"
+          value: my-storage-class

unittests/helm/persistentVolumeClaim/persistentVolumeClaim.yaml

@@ -0,0 +1,29 @@
+chart:
+  appVersion: 1.27.3 # renovate: datasource=docker registryUrl=https://docker.gitea.com depName=gitea
+release:
+  name: gitea-unittests
+  namespace: testing
+suite: PVC template
+templates:
+  - templates/gitea/persistentVolumeClaim.yaml
+tests:
+  - it: Skip persistentVolumeClaim if persistentVolumeClaim is disabled
+    set:
+      persistence.enabled: false
+    asserts:
+      - hasDocuments:
+          count: 0
+
+  - it: Render persistentVolumeClaim with default values
+    set:
+      persistence.enabled: true
+      persistence.new.storageClassName: "my-storage-class"
+    asserts:
+      - containsDocument:
+          apiVersion: v1
+          kind: PersistentVolumeClaim
+          name: gitea-unittests
+          namespace: testing
+      - equal:
+          path: spec.storageClassName
+          value: "my-storage-class"

unittests/helm/pvc/pvc-configuration.yaml

@@ -1,19 +0,0 @@
-suite: PVC template
-release:
-  name: gitea-unittests
-  namespace: testing
-templates:
-  - templates/gitea/persistentVolumeClaim.yaml
-tests:
-  - it: Storage Class using TPL
-    set:
-      global.persistence.storageClass: "storage-class"
-      persistence.enabled: true
-      persistence.create: true
-      persistence.storageClass: "{{ .Values.global.persistence.storageClass }}"
-    asserts:
-      - isKind:
-          of: PersistentVolumeClaim
-      - equal:
-          path: spec.storageClassName
-          value: "storage-class"

values.yaml

@@ -5,7 +5,6 @@
 #
 ## @param global.imageRegistry global image registry override.
 ## @param global.imagePullSecrets global image pull secrets override; can be extended by `imagePullSecrets`.
-## @param global.storageClass global storage class override.
 ## @param global.hostAliases global hostAliases which will be added to the pod's hosts files.
 global:
   imageRegistry: ""
@@ -14,7 +13,6 @@ global:
   ##   - myRegistryKeySecretName
   ##
   imagePullSecrets: []
-  storageClass: ""
   hostAliases: []
   # - ip: 192.168.137.2
   #   hostnames:
@@ -887,31 +885,33 @@ serviceAccount:
   labels: {}
 
 ## @section Persistence
-## @param persistence.enabled Enable persistent storage.
-## @param persistence.create Whether to create the persistentVolumeClaim for shared storage.
-## @param persistence.mount Whether the persistentVolumeClaim should be mounted (even if not created).
-## @param persistence.claimName Use an existing claim to store repository information.
-## @param persistence.size Size for persistence to store repo information.
-## @param persistence.accessModes AccessMode for persistence.
-## @param persistence.labels Labels for the persistence volume claim to be created.
-## @param persistence.annotations.helm.sh/resource-policy Resource policy for the persistence volume claim.
-## @param persistence.storageClass Name of the storage class to use.
-## @param persistence.subPath Subdirectory of the volume to mount at.
-## @param persistence.volumeName Name of persistent volume in PVC.
 persistence:
-  enabled: true
-  create: true
-  mount: true
-  claimName: gitea-shared-storage
-  size: 10Gi
-  accessModes:
-    - ReadWriteOnce
-  labels: {}
-  storageClass:
-  subPath:
-  volumeName: ""
+  ## @param persistence.enabled Enable persistent storage.
+  enabled: false
+
+  ## @param persistence.existingPersistentVolumeClaim.enabled Enable using an existing persistent volume claim.
+  ## @param persistence.existingPersistentVolumeClaim.persistentVolumeClaimName Name of the existing persistent volume claim to use.
+  existingPersistentVolumeClaim:
+    enabled: false
+    persistentVolumeClaimName: ""
+
+  ## @param persistence.new.annotations.helm.sh/resource-policy Resource policy for the new persistent volume claim.
+  ## @param persistence.new.labels Labels for the new persistent volume claim.
+  ## @param persistence.new.accessModes AccessMode for the new persistent volume claim.
+  ## @param persistence.new.persistentVolumeName Name of the persistent volume for the new persistent volume claim.
+  ## @param persistence.new.size Size for the new persistent volume claim.
+  ## @param persistence.new.storageClassName Name of the storage class to use for the new persistent volume claim.
+  ## @param persistence.new.subPath Subdirectory of the volume to mount at for the new persistent volume claim.
+  new:
     annotations:
       helm.sh/resource-policy: keep
+    labels: {}
+    accessModes:
+      - ReadWriteOnce
+    persistentVolumeName: ""
+    size: 10Gi
+    storageClassName: ""
+    subPath: ""
 
 ## @param extraContainers Additional sidecar containers to run in the pod.
 extraContainers: []