feat(docs): Add initial documentation for external secrets

Signed-off-by: Axel Lender <lender@b1-systems.de>

.gitlab-ci.yml

@@ -385,7 +385,8 @@ db-cleanup:
           "STACKIT")
             # In case of STACKIT resources the db content should just be dropped
             echo "[psql] [${ENV_DATABASE}] DROP OWNED BY ${PGUSER} in ${POSTGRES_DATABASE} on ${PGHOST}"
-            psql -c "DROP OWNED BY ${PGUSER}" || true;
+            PGDATABASE=${POSTGRES_DATABASE} # env var PGDATABASE is interpreted by psql
+            psql -c "DROP OWNED BY ${PGUSER};" || true;
             ;;
           "RUN")
             # Usually, e.g. in "RUN" cluster, databases can simply be dropped and recreated
@@ -403,7 +404,7 @@ db-cleanup:
       done;
     # Cleanup Objectstore
     - |
-      export BUCKETS="migrations nextcloud openproject nubus notes"
+      export BUCKETS="migrations nextcloud openproject nubus notes openxchange"
       export AWS_DEFAULT_REGION=""
       export AWS_ENDPOINT=""
       export AWS_ACCESS_KEY_ID=""

README.md

@@ -41,7 +41,7 @@ openDesk currently features the following functional main components:
 | Groupware            | OX App Suite                | GPL-2.0-only (backend), AGPL-3.0-or-later (frontend)                                   | [8.39](https://documentation.open-xchange.com/appsuite/releases/8.39/)                                                       | Online documentation available from within the installed application; [Additional resources](https://documentation.open-xchange.com/) |
 | Knowledge management | XWiki                       | LGPL-2.1-or-later                                                                      | [16.10.5](https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/16.10.5/)                                             | [For the most recent release](https://www.xwiki.org/xwiki/bin/view/Documentation)                                                     |
 | Portal & IAM         | Nubus                       | AGPL-3.0-or-later                                                                      | [1.12.0](https://docs.software-univention.de/nubus-kubernetes-release-notes/1.x/en/1.12.html#version-1-12-0-2025-07-31)      | [Univention's documentation website](https://docs.software-univention.de/n/en/nubus.html)                                             |
-| Project management   | OpenProject                 | GPL-3.0-only                                                                           | [16.2.0](https://www.openproject.org/docs/release-notes/16-2-0/)                                                             | [For the most recent release](https://www.openproject.org/docs/user-guide/)                                                           |
+| Project management   | OpenProject                 | GPL-3.0-only                                                                           | [16.2.1](https://www.openproject.org/docs/release-notes/16-2-1/)                                                             | [For the most recent release](https://www.openproject.org/docs/user-guide/)                                                           |
 | Videoconferencing    | Jitsi                       | Apache-2.0                                                                             | [2.0.9955](https://github.com/jitsi/jitsi-meet/releases/tag/stable%2Fjitsi-meet_9955)                                        | [For the most recent  release](https://jitsi.github.io/handbook/docs/category/user-guide/)                                            |
 | Weboffice            | Collabora                   | MPL-2.0                                                                                | [25.04.2](https://www.collaboraoffice.com/code-25-04-release-notes/)                                                         | Online documentation available from within the installed application; [Additional resources](https://sdk.collaboraonline.com/)        |
 

docs/external-secrets.md

@@ -0,0 +1,40 @@
+<!--
+SPDX-FileCopyrightText: 2025 Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH
+SPDX-License-Identifier: Apache-2.0
+-->
+
+<h1>External Secrets</h1>
+
+This document covers how to utilise external secrets and special requirements.
+
+<!-- TOC -->
+* [General](#general)
+* [Components](#components)
+  * [MinIO](#minio)
+<!-- TOC -->
+
+# General
+
+For most components when set the external secret will supersede e.g. a password in a `values.yaml` file.
+
+The file [`external_secrets.yaml`](/helmfile/environments/default/external_secrets.yaml.gotmpl) lists all possible references to external secrets that are currently implemented in openDesk.
+
+# Components
+
+This section covers information and special requirements to external secrets that some Helm Charts expect.
+
+## MinIO
+
+Like described in the [upstream `values.yaml`](https://github.com/bitnami/charts/blob/main/bitnami/minio/values.yaml#L1595) credentials and information about a user in external secrets listed in `usersExistingSecrets` have to be formatted as follows:
+
+```yaml
+stringData:
+  username1: |
+    username=test-username
+    password=test-password
+    disabled=false
+    policies=readwrite,consoleAdmin,diagnostics
+    setPolicies=fa
+```
+
+Further we need the credentials introduced at MinIO in various other components that didn't implement the special format from MinIO. Hence we have to create key-value-pairs of the passwords for them.

docs/migrations.md

@@ -12,6 +12,7 @@ SPDX-License-Identifier: Apache-2.0
 * [Manual checks/actions](#manual-checksactions)
   * [v1.7.0+](#v170)
     * [Pre-upgrade to v1.7.0+](#pre-upgrade-to-v170)
+    * [Helmfile fix: Ensure enterprise overrides apply when deploying from project root](#helmfile-fix-ensure-enterprise-overrides-apply-when-deploying-from-project-root)
       * [Replace Helm chart: New Notes Helm chart with support for self-signed deployments](#replace-helm-chart-new-notes-helm-chart-with-support-for-self-signed-deployments)
     * [Post-upgrade to v1.7.0+](#post-upgrade-to-v170)
       * [Upstream fix: Provisioning of functional mailboxes](#upstream-fix-provisioning-of-functional-mailboxes)
@@ -128,6 +129,16 @@ If you would like more details about the automated migrations, please read secti
 
 ### Pre-upgrade to v1.7.0+
 
+### Helmfile fix: Ensure enterprise overrides apply when deploying from project root
+
+**Target group:** All openDesk Enterprise deployments initiated from the project root using `helmfile_generic.yaml.gotmpl`
+
+Previously, the default values referenced in `helmfile_generic.yaml.gotmpl` did not include the necessary Enterprise overrides from `helmfile/environment/default-ee-overrides/`.
+
+As a result, when deploying openDesk Enterprise Edition from the project root, the correct Enterprise charts and images for Collabora, Nextcloud, OpenXchange, and Dovecot were not applied. This issue does not affect deployments started at the component level (e.g., `helmfile/apps/collabora`).
+
+Please verify that your deployment uses the correct Enterprise charts and images. If not, migrate to the Enterprise versions before upgrading to openDesk EE v1.7.0.
+
 #### Replace Helm chart: New Notes Helm chart with support for self-signed deployments
 
 **Target group:** All deployments that set `app.notes.enabled: true` (default is `false`).

docs/security.md

@@ -1,4 +1,5 @@
 <!--
+SPDX-FileCopyrightText: 2024-2025 Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH
 SPDX-FileCopyrightText: 2023 Bundesministerium des Innern und für Heimat, PG ZenDiS "Projektgruppe für Aufbau ZenDiS"
 SPDX-License-Identifier: Apache-2.0
 -->
@@ -11,6 +12,7 @@ This document covers the current status of security measures.
 * [Helm Chart Trust Chain](#helm-chart-trust-chain)
 * [Kubernetes Security Enforcements](#kubernetes-security-enforcements)
 * [NetworkPolicies](#networkpolicies)
+* [External Secrets](#external-secrets)
 <!-- TOC -->
 
 # Helm Chart Trust Chain
@@ -49,3 +51,9 @@ security:
   otterizeIntents:
     enabled: true
 ```
+
+# External Secrets
+
+We urge you to use external secrets for your confidential credentials.
+
+For further explanation and documentation please visit [External Secrets](./docs/external-secrets.md).

helmfile/apps/services-external/values-minio.yaml.gotmpl

@@ -19,6 +19,9 @@ apiIngress:
 
 auth:
   rootPassword: {{ .Values.secrets.minio.rootPassword | quote }}
+  existingSecret: {{ .Values.externalSecrets.minio.existingSecret | quote }}
+  rootUserSecretKey: {{ .Values.externalSecrets.minio.rootUserSecretKey | quote }}
+  rootPasswordSecretKey: {{ .Values.externalSecrets.minio.rootPasswordSecretKey | quote }}
 
 commonAnnotations:
   {{ .Values.annotations.servicesExternalMinio.common | toYaml | nindent 2 }}
@@ -222,6 +225,7 @@ provisioning:
           actions:
             - "s3:*"
     {{- end }}
+  {{- if not .Values.externalSecrets.minio.usersExistingSecrets }}
   users:
     - username: {{ .Values.objectstores.migrations.username | quote }}
       password: {{ .Values.secrets.minio.migrationsUser | quote }}
@@ -267,6 +271,9 @@ provisioning:
         - "dovecot-bucket-policy"
       setPolicies: true
     {{- end }}
+  {{- else }}
+  usersExistingSecrets: {{ .Values.externalSecrets.minio.usersExistingSecrets }}
+  {{- end }}
   resources:
     {{ .Values.resources.minio | toYaml | nindent 4 }}
 

helmfile/environments/default/external_secrets.yaml.gotmpl

@@ -0,0 +1,12 @@
+{{/*
+SPDX-FileCopyrightText: 2025 Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH
+SPDX-License-Identifier: Apache-2.0
+*/}}
+---
+externalSecrets:
+  minio:
+    existingSecret: ~
+    rootUserSecretKey: ~
+    rootPasswordSecretKey: ~
+    usersExistingSecrets: []
+...

helmfile/environments/default/images.yaml.gotmpl

@@ -752,7 +752,7 @@ images:
     # upstreamMirrorStartFrom: ["13", "1", "1"]
     registry: "registry.opencode.de"
     repository: "bmi/opendesk/components/supplier/openproject/images-mirror/open_desk"
-    tag: "16.2.0@sha256:e4d50068411a7d5afbaf245211df9b7d18f622fed4b6c3c634bc7f88a3149419"
+    tag: "16.2.1@sha256:4b0c0589ad21b727cf4a7c896f8f446607319ac3ff476855f7576b5eb1173cff"
   openprojectBootstrap:
     # providerCategory: "Platform"
     # providerResponsible: "openDesk"