feat: Add support for existingSecret for htpasswd authentication (#180)

Andrea-Gallicchio · Andrea Gallicchio · web-flow · commit 97fcd0347bcb · 2026-01-14T08:08:56.000+01:00
* Add support for existingSecret for htpasswd authentication

Add support for referencing an existing Kubernetes secret for htpasswd authentication, avoiding plain text passwords in `values.yaml`.

- Add `secrets.existingSecretHtpasswd` to reference an existing secret
- Add `secrets.existingSecretHtpasswdKey` to specify the key name (defaults to "htpasswd")
- Update templates to support both generated and existing secrets
- Add README documentation

```yaml
secrets:
  existingSecretHtpasswd: "my-htpasswd-secret"
  existingSecretHtpasswdKey: "htpasswd"  # Optional
```

Create the secret:
```bash
kubectl create secret generic my-htpasswd-secret \
  --from-file=htpasswd=/path/to/htpasswd
```

If both `secrets.htpasswd` and `secrets.existingSecretHtpasswd` are set, the existing secret takes precedence.

* Improve template readability and remove misleading checksum annotation

Address review feedback from Copilot suggestions:
- Remove checksum annotation for existingSecretHtpasswd that only tracked secret name/key but not actual content, which was misleading
- Refactor inline conditionals for subPath and secretName to multi-line if-else blocks for better template readability
- Add documentation note about manual pod restart requirement when updating external secrets

---------

Co-authored-by: Andrea Gallicchio &lt;andrea.gallicchio@extern.aroundhome.de&gt;
diff --git a/README.md b/README.md
@@ -134,6 +134,8 @@ and their default values.
 | `fullnameOverride`                 | Set resource fullname override                                                   | `""`                           |
 | `useSecretHtpasswd`                | Use htpasswd from `.Values.secrets.htpasswd`. This require helm v3.2.0 or above. | `false`                        |
 | `secrets.htpasswd`                 | user and password list to generate htpasswd.                                     | `[]`                           |
+| `secrets.existingSecretHtpasswd`   | Existing secret containing htpasswd file (alternative to `secrets.htpasswd`)     | `""`                           |
+| `secrets.existingSecretHtpasswdKey` | Key in the existing secret that contains the htpasswd file content              | `"htpasswd"`                   |
 | `ingress.enabled`                  | Enable/Disable Ingress                                                           | `false`                        |
 | `ingress.className`                | Ingress Class Name (k8s `>=1.18` required)                                       | `""`                           |
 | `ingress.labels`                   | Ingress Labels                                                                   | `{}`                           |
@@ -191,6 +193,47 @@ secrets:
 This config will create a htpasswd file with user "verdaccio", If in config
 'htpasswd' auth is used. You can login using this credentials.
 
+### Use existing secret for htpasswd
+
+Instead of providing plain text credentials in `values.yaml`, you can reference an
+existing Kubernetes secret containing the htpasswd file. This is more secure as it
+avoids storing passwords in plain text in your values files.
+
+When `secrets.existingSecretHtpasswd` is set, the chart will use the specified
+secret instead of generating one from `secrets.htpasswd`. The secret must contain
+a key with the htpasswd file content (default key: `htpasswd`, configurable via
+`secrets.existingSecretHtpasswdKey`).
+
+#### Example
+
+```yaml
+secrets:
+  # Reference an existing secret instead of providing plain text credentials
+  existingSecretHtpasswd: "my-htpasswd-secret"
+  existingSecretHtpasswdKey: "htpasswd"  # Optional, defaults to "htpasswd"
+```
+
+The existing secret should contain the htpasswd file content in the specified key.
+You can create such a secret using:
+
+```bash
+kubectl create secret generic my-htpasswd-secret \
+  --from-file=htpasswd=/path/to/htpasswd
+```
+
+> **Note**: If both `secrets.htpasswd` and `secrets.existingSecretHtpasswd` are set,
+> `secrets.existingSecretHtpasswd` takes precedence and no secret will be generated
+> from `secrets.htpasswd`.
+
+> **Important**: When using an existing secret, pods will **not** automatically restart
+> when the secret content is updated. This is a limitation of Kubernetes - it doesn't
+> track changes to external secrets. You need to manually trigger a pod restart after
+> updating the secret:
+>
+> ```bash
+> kubectl rollout restart deployment/<release-name>-verdaccio
+> ```
+
 ### Custom ConfigMap
 
 When creating a new chart with this chart as a dependency, CustomConfigMap can
diff --git a/charts/verdaccio/Chart.yaml b/charts/verdaccio/Chart.yaml
@@ -1,7 +1,7 @@
 apiVersion: v2
 description: A lightweight private node.js proxy registry
 name: verdaccio
-version: 4.28.0
+version: 4.29.0
 appVersion: 6.2.3
 home: https://verdaccio.org
 icon: https://cdn.verdaccio.dev/logos/default.png
diff --git a/charts/verdaccio/templates/deployment.yaml b/charts/verdaccio/templates/deployment.yaml
@@ -32,7 +32,9 @@ spec:
     metadata:
       annotations:
         checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
+        {{- if and .Values.secrets.htpasswd (not .Values.secrets.existingSecretHtpasswd) }}
         checksum/htpasswd-secret: {{ toJson .Values.secrets.htpasswd | sha256sum }}
+        {{- end }}
         {{- if .Values.secretEnvVars }}
         checksum/env-secret: {{ include (print $.Template.BasePath "/secret.yaml") . | sha256sum }}
         {{- end }}
@@ -129,10 +131,14 @@ spec:
             - mountPath: /verdaccio/storage
               name: storage
               readOnly: false
-            {{- if .Values.secrets.htpasswd }}
+            {{- if or .Values.secrets.htpasswd .Values.secrets.existingSecretHtpasswd }}
             - mountPath: /verdaccio/storage/htpasswd
               name: htpasswd
+              {{- if .Values.secrets.existingSecretHtpasswd }}
+              subPath: {{ .Values.secrets.existingSecretHtpasswdKey | default "htpasswd" }}
+              {{- else }}
               subPath: htpasswd
+              {{- end }}
               readOnly: true
             {{- end }}
             - mountPath: /verdaccio/conf
@@ -146,10 +152,14 @@ spec:
       - name: config
         configMap:
           name: {{ .Values.existingConfigMap | default (include "verdaccio.fullname" .) }}
-      {{- if .Values.secrets.htpasswd }}
+      {{- if or .Values.secrets.htpasswd .Values.secrets.existingSecretHtpasswd }}
       - name: htpasswd
         secret:
+          {{- if .Values.secrets.existingSecretHtpasswd }}
+          secretName: {{ .Values.secrets.existingSecretHtpasswd }}
+          {{- else }}
           secretName: {{ include "verdaccio.fullname" . }}-htpasswd
+          {{- end }}
       {{- end }}
       {{- if .Values.cachingNginx.enabled }}
       - name: config-volume
diff --git a/charts/verdaccio/templates/htpasswd-secret.yaml b/charts/verdaccio/templates/htpasswd-secret.yaml
@@ -1,4 +1,4 @@
-{{- if .Values.secrets.htpasswd }}
+{{- if and .Values.secrets.htpasswd (not .Values.secrets.existingSecretHtpasswd) }}
 apiVersion: v1
 kind: Secret
 type: Opaque
diff --git a/charts/verdaccio/templates/statefulset.yaml b/charts/verdaccio/templates/statefulset.yaml
@@ -25,7 +25,9 @@ spec:
     metadata:
       annotations:
         checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
+        {{- if and .Values.secrets.htpasswd (not .Values.secrets.existingSecretHtpasswd) }}
         checksum/htpasswd-secret: {{ toJson .Values.secrets.htpasswd | sha256sum }}
+        {{- end }}
         {{- if .Values.secretEnvVars }}
         checksum/env-secret: {{ include (print $.Template.BasePath "/secret.yaml") . | sha256sum }}
         {{- end }}
@@ -122,10 +124,14 @@ spec:
             - mountPath: /verdaccio/storage
               name: storage
               readOnly: false
-            {{- if .Values.secrets.htpasswd }}
+            {{- if or .Values.secrets.htpasswd .Values.secrets.existingSecretHtpasswd }}
             - mountPath: /verdaccio/storage/htpasswd
               name: htpasswd
+              {{- if .Values.secrets.existingSecretHtpasswd }}
+              subPath: {{ .Values.secrets.existingSecretHtpasswdKey | default "htpasswd" }}
+              {{- else }}
               subPath: htpasswd
+              {{- end }}
               readOnly: true
             {{- end }}
             - mountPath: /verdaccio/conf
@@ -139,10 +145,14 @@ spec:
       - name: config
         configMap:
           name: {{ .Values.existingConfigMap | default (include "verdaccio.fullname" .) }}
-      {{- if .Values.secrets.htpasswd }}
+      {{- if or .Values.secrets.htpasswd .Values.secrets.existingSecretHtpasswd }}
       - name: htpasswd
         secret:
+          {{- if .Values.secrets.existingSecretHtpasswd }}
+          secretName: {{ .Values.secrets.existingSecretHtpasswd }}
+          {{- else }}
           secretName: {{ include "verdaccio.fullname" . }}-htpasswd
+          {{- end }}
       {{- end }}
       {{- if .Values.cachingNginx.enabled }}
       - name: config-volume
diff --git a/charts/verdaccio/values.yaml b/charts/verdaccio/values.yaml
@@ -264,6 +264,12 @@ secrets:
   #   password: "test"
   # - username: "blah"
   #   password: "blah"
+  # Existing secret containing htpasswd file
+  # If set, the secret will be used instead of generating one from secrets.htpasswd
+  # The secret must contain a key with the htpasswd file content (default key: "htpasswd")
+  existingSecretHtpasswd: ""
+  # Key in the existing secret that contains the htpasswd file content
+  existingSecretHtpasswdKey: "htpasswd"
 
 # Annotations to set on the deployment
 annotations: {}

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-{{- if .Values.secrets.htpasswd }}`
	`1`	`+{{- if and .Values.secrets.htpasswd (not .Values.secrets.existingSecretHtpasswd) }}`
`2`	`2`	`apiVersion: v1`
`3`	`3`	`kind: Secret`
`4`	`4`	`type: Opaque`