diff --git a/docs/enhanced-configuration/idp-federation.md b/docs/enhanced-configuration/idp-federation.md index e01ace6a..04a83046 100644 --- a/docs/enhanced-configuration/idp-federation.md +++ b/docs/enhanced-configuration/idp-federation.md @@ -44,9 +44,9 @@ We will provide additional documents regarding user provisioning in the future, - UDM REST API: - Build a provisioning solution by yourself using the [UDM REST API](https://docs.software-univention.de/developer-reference/5.0/en/udm/rest-api.html). - The API gives you full control over the contents of the IAM in order to create, update or delete users and groups. - - Directory Connector: + - Nubus Directory Importer: - It is based on a Python one-way directory synchronization for users and groups. - - We will provide more details on this approach soon one the tool is made publicly available. + - Please find more details in the [upstream product's documentation](https://docs.software-univention.de/nubus-kubernetes-operation/latest/en/howto-connect-external-iam.html). - Ad-hoc provisioning (AHP) - This feature is currently not available in the openDesk Keycloak, but there are plans by the Supplier Univention to make it available. - Ad-hoc provisioning creates an user account on the fly during a users first login. diff --git a/docs/enhanced-configuration/separate-mail-matrix-domain.md b/docs/enhanced-configuration/separate-mail-matrix-domain.md index f0f5a8dd..01e0bca7 100644 --- a/docs/enhanced-configuration/separate-mail-matrix-domain.md +++ b/docs/enhanced-configuration/separate-mail-matrix-domain.md @@ -9,6 +9,10 @@ SPDX-License-Identifier: Apache-2.0 * [Example configuration](#example-configuration) * [Mail domain](#mail-domain) * [Matrix domain](#matrix-domain) + * [DNS](#dns) + * [Webserver](#webserver) + * [Content Security Policy](#content-security-policy) + * [.well-known](#well-known) # Use case @@ -59,7 +63,9 @@ or via environment variable export MATRIX_DOMAIN=my_organization.tld ``` -This setup requires also a different DNS setup: +### DNS + +The following changes apply to the standard DNS: | Record name | Type | Value | Comment | | -------------------------------- | ---- | -------------------------------------- | ---------------------------------------------------------------------------------- | @@ -67,6 +73,14 @@ This setup requires also a different DNS setup: *Note:* `matrix.opendesk.domain.tld` in the "Value" column can also be the IP address where synapse TLS port is listening to. +### Webserver + +#### Content Security Policy + +The webserver of `my_organization.tld` should add `*.opendesk.domain.tld` to it's CSP header. + +#### .well-known + If you want to use other Matrix clients, e.g., Element Messenger for [iOS](https://apps.apple.com/de/app/element-messenger/id1083446067) or [Android](https://play.google.com/store/apps/details?id=im.vector.app), @@ -82,4 +96,4 @@ you need to create a JSON file with the following contents that is served from ``` This ensures clients know where to find the Matrix protocol endpoint when users specify `my_organization.tld` -as their homeserver. \ No newline at end of file +as their homeserver. diff --git a/docs/getting-started.md b/docs/getting-started.md index 222a5929..226db3fd 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -52,7 +52,7 @@ files. > All configuration options and their default values can be found in files at `helmfile/environments/default/` For the following guide, we will use `dev` as environment, where variables can be set in -`helmfile/environments/dev/values.yaml`. +`helmfile/environments/dev/values.yaml.gotmpl`. ## DNS @@ -115,13 +115,13 @@ All available apps and their default value can be found in `helmfile/environment | Memcached | `memcached.enabled` | `true` | Cache Database | | MinIO | `minio.enabled` | `true` | Object Storage | | Nextcloud | `nextcloud.enabled` | `true` | File share | +| Nubus | `nubus.enabled` | `true` | Identity Management & Portal | | OpenProject | `openproject.enabled` | `true` | Project management | | OX Appsuite | `oxAppsuite.enabled` | `true` | Groupware | | Provisioning | `oxConnector.enabled` | `true` | Backend provisioning | | Postfix | `postfix.enabled` | `true` | MTA | | PostgreSQL | `postgresql.enabled` | `true` | Database | | Redis | `redis.enabled` | `true` | Cache Database | -| Nubus | `nubus.enabled` | `true` | Identity Management & Portal | | XWiki | `xwiki.enabled` | `true` | Knowledge management | Exemplary, Jitsi can be disabled like: @@ -201,16 +201,15 @@ cluster: ### Ingress -By default, the `ingressClassName` is empty to choose your default ingress controller, you may want to customize it by -setting: +By default, the `ingressClassName` is empty to choose your default ingress controller. You may want to customize it by +setting the following attribute to the name of the currently only supported ingress controller `ingress-nginx` (see +[requirements.md](./requirements.md)) for reference) within your deployment if that is not the clusters default ingress. ```yaml ingress: - ingressClassName: "cilium" + ingressClassName: "name-of-my-nginx-ingress" ``` -**Note:** Please check the [requirements.md](./requirements.md) for the supported Ingress controllers. - ### Container runtime Some apps require specific configuration for the container runtime. You can set your container runtime like `cri-o`, diff --git a/docs/migrations.md b/docs/migrations.md index fd0c7c0f..5952ec9c 100644 --- a/docs/migrations.md +++ b/docs/migrations.md @@ -6,14 +6,17 @@ SPDX-License-Identifier: Apache-2.0

Upgrade migrations

* [Disclaimer](#disclaimer) -* [From v0.9.0](#from-v090) - * [Automated migrations](#automated-migrations) - * [Updated IAM component Nubus](#updated-iam-component-nubus) - * [Manual cleanup](#manual-cleanup) -* [From v0.8.1](#from-v081) - * [Updated `cluster.networking.cidr`](#updated-clusternetworkingcidr) - * [Updated customizable template attributes](#updated-customizable-template-attributes) - * [`migrations` S3 bucket](#migrations-s3-bucket) +* [Releases upgrades](#releases-upgrades) + * [From v0.9.0](#from-v090) + * [Automated migrations](#automated-migrations) + * [Updated IAM component Nubus](#updated-iam-component-nubus) + * [Manual cleanup](#manual-cleanup) + * [From v0.8.1](#from-v081) + * [Updated `cluster.networking.cidr`](#updated-clusternetworkingcidr) + * [Updated customizable template attributes](#updated-customizable-template-attributes) + * [`migrations` S3 bucket](#migrations-s3-bucket) +* [Related components and artefacts](#related-components-and-artefacts) + * [Development](#development) # Disclaimer @@ -24,14 +27,16 @@ Though we try to ease the pain when it comes to 0.x upgrades. That is what this Limitations: - We assume that the PV reclaim policy is set to `delete`, so expect that PVs get deleted as soon as the related PVC was deleted and will cover an explicit delete for PVs. -# From v0.9.0 +# Releases upgrades -## Automated migrations +## From v0.9.0 -### Updated IAM component Nubus +### Automated migrations -openDesk is integrating the latest [Nubus](https://www.univention.de/produkte/nubus/) development from Univention. The new redundant and scalable LDAP requires migration activities. These have been automated to avoid manual interaction. The `run_2` of the openDesk -upgrade migrations executes the following steps +#### Updated IAM component Nubus + +openDesk is integrating the latest [Nubus](https://www.univention.de/produkte/nubus/) development from Univention. The now redundant and scalable LDAP requires migration activities. These have been automated to avoid manual interaction. The `run_2` of the openDesk +upgrade migrations executes the following steps: - Stage PRE: - Delete service `ums-keycloak`, as it will be recreated headless. @@ -40,7 +45,7 @@ upgrade migrations executes the following steps - Stage POST: - Restart Keycloak. -#### Manual cleanup +##### Manual cleanup Currently we do not execute possible cleanup steps as part of the migrations POST stage. So you might want to remove the no longer used PVCs after successful upgrade: ``` @@ -49,14 +54,14 @@ kubectl -n ${NAMESPACE} delete pvc shared-data-ums-ldap-server-0 kubectl -n ${NAMESPACE} delete pvc shared-run-ums-ldap-server-0 ``` -# From v0.8.1 +## From v0.8.1 -## Updated `cluster.networking.cidr` +### Updated `cluster.networking.cidr` - Action: `cluster.networking.cidr` is now an array (was a string until 0.8.1), please update your setup accordingly if you explicitly set this value. - Reference:[cluster.yaml](https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk/-/blob/main/helmfile/environments/default/cluster.yaml) -## Updated customizable template attributes +### Updated customizable template attributes - Action: Please ensure you update you custom deployment values according with the updated default value structure. - References: @@ -65,7 +70,28 @@ kubectl -n ${NAMESPACE} delete pvc shared-run-ums-ldap-server-0 - `monitoring.` prefix for `prometheus.*` and `graphana.*`, see [monitoring.yaml](https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk/-/blob/main/helmfile/environments/default/monitoring.yaml). - `smtp.` prefix for `localpartNoReply`, see [smtp.yaml](https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk/-/blob/main/helmfile/environments/default/smtp.yaml). -## `migrations` S3 bucket +### `migrations` S3 bucket - Action: For self managed/external S3/object storages, please ensure you add a bucket `migrations` to your S3. - Reference: `objectstores.migrations` in [objectstores.yaml](https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk/-/blob/main/helmfile/environments/default/objectstores.yaml) + +# Related components and artefacts + +openDesk comes with two upgrade steps as part of the deployment, they can be found in the folder [/helmfile/apps](../helmfile/apps/) as all other components: + +- `migrations-pre`: Is the very first app that gets deployed. +- `migrations-post`: Is the last app that gets deployed. + +Both migrations have to be deployed exclusively at their first/last position and not in parallel with other components. + +The status of the upgrade migrations is tracked in the ConfigMap `migrations-status`, more details can be found in the [README.md of the related container image](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/images/opendesk-migrations/README.md). + +## Development + +When a new upgrade migration is required, ensure to address the following list: + +- Update the generated release version file [`global.generated.yaml`](../helmfile/environments/default/global.generated.yaml) at least on the patch level to test the upgrade in your feature branch as well as trigger it in the `develop` branch after the feature branch was merged. The set value gets overwritten during the release process with the release's actual version number. +- You have to implement the migration logic as a runner script in the [`opendesk-migrations`](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/images/opendesk-migrations) image. Please find more instructions in the linked repository. +- You most likely have to update the [`opendesk-migrations` Helm chart](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/charts/opendesk-migrations) within the `rules` section of the [`role.yaml`](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/charts/opendesk-migrations/-/blob/main/charts/opendesk-migrations/templates/role.yaml) to provide the permissions required for the execution of your migration's logic. +- You have to set the runner's ID you want to execute in the [migrations.yaml.gotmpl](../helmfile/shared/migrations.yaml.gotmpl). See also the `migrations.*` section of [the Helm chart's README.md](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/charts/opendesk-migrations/-/blob/main/charts/opendesk-migrations/README.md). +- Update the [`charts.yaml`](../helmfile/environments/default/charts.yaml) and [`images.yaml`](../helmfile/environments/default/images.yaml) to reflect the newer releases of the `opendesk-migrations` Helm chart and container image.