diff --git a/docs/v3/README_de.md b/docs/v3/README_de.md index 015f9cf..0fc6d53 100644 --- a/docs/v3/README_de.md +++ b/docs/v3/README_de.md @@ -15,8 +15,13 @@ Die Dokumentation wird Entwickler:innen von einem minimalen lauffähigen Dogu zu ## Verfügbare Konzepte +- [Dogu-V3-Artefakte verstehen](concepts/artifacts_de.md) - [Die Multinode-Laufzeitumgebung verstehen](concepts/multinode-environment_de.md) +## Verfügbare Referenz + +- [Kompendium der Dogu-V3-Artefakte](reference/compendium_de.md) + ## Inhaltliche Abgrenzung - **Erste Schritte** enthalten ausführbare, durchgängige Anleitungen. Der Quickstart behandelt nur den kleinsten lauffähigen Happy Path. diff --git a/docs/v3/best-practices/helm-chart_de.md b/docs/v3/best-practices/helm-chart_de.md new file mode 100644 index 0000000..ef85681 --- /dev/null +++ b/docs/v3/best-practices/helm-chart_de.md @@ -0,0 +1,20 @@ +# Best Practices für Dogu-Helm-Charts + +Dieses Dokument beschreibt die Best-Practices, die es bei der Erstellung von Dogu-Helm-Charts zu beachten gilt. + +## Vorsicht beim Umbenennen von Kubernetes-Ressourcen + +Eine Änderung von `metadata.name` erzeugt ein anderes Kubernetes-Objekt. Die Auswirkungen hängen von Ressourcenart und Controller ab: Referenzen können ungültig werden, ein Controller kann neue Credentials ausstellen und zustandsbehaftete Ressourcen können getrennt oder verwaist werden. Aus einer Umbenennung folgt nicht automatisch, dass Kubernetes die zugrunde liegenden Daten löscht. Tritt eine oder mehrere der oben genannte Punkte ein, kann dies zu einer erheblichen Betriebsstörung führen. + +Prüfen Sie vor einer Namensänderung diese Beziehungen: + +| Beziehung | Typisches Risiko | +| --- | --- | +| PVC- und Claim-Referenzen | Ein Workload startet nicht, wenn der referenzierte Claim fehlt. Ein neuer Claim kann an einen anderen Speicher gebunden werden; ob das bisherige Volume und der zugrunde liegende Speicher nach dem Löschen des alten Claims erhalten bleiben, hängt von der Reclaim Policy des PersistentVolume ab. | +| Service, Clients und Selektoren | Clients und `Exposition`-Ressourcen können weiterhin den alten Service referenzieren; geänderte Selektoren können außerdem dazu führen, dass ein Service keine Endpoints mehr besitzt. | +| Exposition-Ziel | Externer Zugriff kann auf einen nicht mehr vorhandenen Service oder Port zeigen. | +| ServiceAccountRequest und verwaltetes Secret | Ein neuer Request kann Credentials neu erzeugen, während die Anwendung noch das alte Secret erwartet. | +| Andere Integrationsressourcen | Authentifizierungs- oder Menüintegration kann dupliziert, ersetzt oder getrennt werden. | +| Backup und Aufbewahrung | Prüfen Sie Selektionslabels sowie Restore- und Aufbewahrungsverhalten der betroffenen Ressource. | + +Behandeln Sie die Umbenennung zustandsbehafteter oder extern referenzierter Ressourcen als **Migration**: Aktualisieren Sie alle Referenzen, prüfen Sie Backup- und Aufbewahrungsverhalten und entfernen Sie das alte Objekt erst, nachdem der neue Pfad validiert wurde. diff --git a/docs/v3/best-practices/helm-chart_en.md b/docs/v3/best-practices/helm-chart_en.md new file mode 100644 index 0000000..ab68e91 --- /dev/null +++ b/docs/v3/best-practices/helm-chart_en.md @@ -0,0 +1,20 @@ +# Best Practices for Dogu-Helm-Charts + +This document describes the best practices to follow when creating Dogu Helm charts. + +## Take care when renaming Kubernetes resources + +Changing `metadata.name` creates a different Kubernetes object. The impact depends on the resource and its controller: references can break, a controller can issue new credentials, and stateful resources can become disconnected or orphaned. A rename does not by itself mean that Kubernetes deletes the underlying data. If one or more of the above-mentioned issues occur, this can lead to a significant operational disruption. + +Before changing a name, check these relationships: + +| Relationship | Typical risk | +| --- | --- | +| PVC and claim references | A workload fails to start if the referenced claim does not exist. A new claim can bind different storage; whether the previous volume and its underlying storage remain after the old claim is deleted depends on the PersistentVolume reclaim policy. | +| Service, clients and selectors | Clients and `Exposition` resources can continue to reference the old Service; selector changes can also leave a Service without endpoints. | +| Exposition target | External access can point to a Service or port that no longer exists. | +| ServiceAccountRequest and managed Secret | A new request can regenerate credentials while the application still expects the old Secret. | +| Other integration resources | Authentication or menu integration can be duplicated, replaced or disconnected. | +| Backup and retention | Verify selection labels and restore or retention behavior for the affected resource. | + +Treat renames of stateful or externally referenced resources as **migrations**: update every reference, verify backup and retention behavior, and retire the old object only after the new path has been validated. diff --git a/docs/v3/concepts/artifacts_de.md b/docs/v3/concepts/artifacts_de.md new file mode 100644 index 0000000..a58ee1c --- /dev/null +++ b/docs/v3/concepts/artifacts_de.md @@ -0,0 +1,229 @@ +# Dogu Artefakte + +Ein Dogu ist eine betriebsbereite Anwendung innerhalb des Cloudogu Ecosystems (CES) – wie z. B. SCM-Manager, Jenkins oder SonarQube –, die nahtlos in die Plattform integriert ist. + +Mit dem Generationenwechsel ab Version 3 (V3) vollzieht das Ecosystem einen entscheidenden Schritt in Richtung cloud-nativer Standards: Das Helm-Chart wird zum zentralen Release-Artefakt und primären Format für die Paketierung, Versionierung und Bereitstellung eines Dogus. Durch die Ausbringung über Helm wird ein zusätzliches, plattformspezifisches Deskriptorformat (wie das bisherige `dogu.json`) überflüssig. Dies vereinfacht das Artefakt-Management und bettet die Anwendung nahtlos in das Kubernetes-Ökosystem ein. Container-Images bleiben separate Artefakte, auf die das Helm-Chart verweist. + +## Das Chart als Dogu-Deskriptor + +Im Helm-Chart dient die `Chart.yaml` als führendes Manifest zur Bereitstellung zentraler Metadaten. Die Datei regelt sowohl die Identifikation des Charts als auch dessen Paket-Abhängigkeiten. Darüber hinaus existieren weitere Manifeste, die für die Integration in das CES eine entscheidende Rolle spielen. Nachfolgend werden die wichtigsten Artefakte und deren Bedeutung für ein Dogu V3 detailliert beschrieben. Zu den Top-Level-Dateien im Helm-Chart gehören: + +``` +k8s/ +└─ helm/ + ├─ templates/ + │ └─ ... + ├─ Chart.yaml + ├─ chart-patch-tpl.yaml + ├─ dogu-upgrade.yaml + ├─ dogu-values-metadata.yaml + ├─ values.yaml + └─ values.schema.json +``` + +Diese Artefakte werden hier in Reihenfolge der Relevanz beschrieben. + +### `Chart.yaml` + +In der `Chart.yaml` befinden sich Metadaten, die ein Dogu beschreiben. Im Chart werden zwei Versionen unterschieden. +Die Dogu-Version entspricht der Version des Charts (`version`), während die App-Version (`appVersion`) die Version der fachlichen Anwendung innerhalb des Dogus beschreibt. Beide Versionen sind voneinander unabhängig und dürfen sich unterscheiden. So könnte beispielsweise Redmine als Dogu in Version `45.7.0` veröffentlicht werden, während die enthaltene Redmine-Anwendung die App-Version `6.1.2` besitzt. + +Neben den [Helm-Standardfeldern](https://helm.sh/docs/topics/charts/#the-chartyaml-file) werden in der `Chart.yaml` plattformspezfische Annotations verwendet, die durch den Prefix `dogu.cloudogu.com/` gekennzeichnet sind. Dieser Prefix kennzeichnet Dogu-Metadaten im Helm-Chart und grenzt sie von allgemeinen Kubernetes- oder Helm-Annotations ab. Folgende plattformspezifische Annotations werden aktuell unterstützt: + +- `api-version`: Die Dogu-API-Version, z.b. `v3` +- `display-name`: Der Anzeigename eines Dogus falls `name` Attribut der `Chart.yaml` nicht zur Anzeige verwendet werden soll +- `application.`: Definiert weitere Anwendungen, die im Chart enthalten sind. `` entspricht dem technischen Namen der enthaltenen Anwendung, wobei der Annotation-Wert eine nicht leere Versionsangabe als String enthält + +Unbekannte Annotations mit dem Prefix `dogu.cloudogu.com/` sind zulässig, werden jedoch von plattformspezifischen Komponenten ignoriert, sofern sie nicht Teil der festgelegten Pflichtmetadaten sind. Als Pflichtfelder in der `Chart.yaml` gelten die Felder: + +- `name` +- `version` +- `appVersion` +- `description` +- `annotations.dogu.cloudogu.com/api-version` + +Ein Beispiel für eine gültige `Chart.yaml` für ein Dogu könnte wie folgt aussehen: + +```yaml +apiVersion: v2 +name: redmine +description: Redmine als Cloudogu EcoSystem Dogu +type: application +version: 45.7.0 +appVersion: 6.1.2 +home: https://cloudogu.com/ecosystem +sources: + - https://github.com/cloudogu/redmine +icon: https://dogu.cloudogu.com/api/v3/dogus/official/redmine/icon.svg +keywords: + - projectmanagement + - issue + - development +maintainers: + - name: Cloudogu GmbH + email: hello@cloudogu.com +annotations: + dogu.cloudogu.com/api-version: v3 + dogu.cloudogu.com/display-name: Redmine + dogu.cloudogu.com/application.redmine: "6.1.2" + dogu.cloudogu.com/application.postgresql: "16.8" +``` + +### `values.yaml` + +Die `values.yaml` dient als öffentliche Schnittstelle für die Konfiguration von Helm-Charts. Sie enthält Standardwerte, die für die Templates des Helm-Charts verwendet werden. Helm erlaubt es bei der Installation die Werte aus der `values.yaml` zu überschreiben, in dem es die übergebenen Werte mit den Standardwerten aus dem Helm-Chart zusammenführt. + +### `values.schema.json` + +Für die `values.yaml` kann mithilfe der `values.schema.json` ein Schema in Form eines JSON-Schemas definiert werden, um die resultierenden Werte des Helm-Charts zu validieren. Da die Entwickler einer Anwendung am besten über den erforderlichen Input und dessen korrekte Struktur Bescheid wissen, sollte diese Schemadatei stets fester Bestandteil des Dogu-Helm-Charts sein. Der Dogu-Operator nutzt sie, um bei der Installation oder Aktualisierung eine automatisierte Validierung der Values durchzuführen und fehlerhafte Konfigurationen frühzeitig abzufangen. + +### `dogu-values-metadata.yaml` + +Für die Plattform können globale Konfigurationsparameter existieren, die nicht immer durch bestehende Werte aus der `values.yaml` eines Helm-Charts abgebildet werden können. So kann für die Plattform bspw. ein globales Log-Level gesetzt werden, welches für alle Dogus angewendet wird. Um diesem Umstand Rechnung zu tragen, wurde die `dogu-values-metadata.yaml` eingeführt. Durch sie können plattformspezifische Konfigurationen auf die Werte des Helm-Charts eines Dogus angewendet werden, indem in ihr das Mapping zwischen einzelnen Werten definiert wird. Plattformspezifische Konfigurationen werden in der Dogu-CR definiert und durch den Dogu-Operator angewendet. Folgend wird exemplarisch das Mapping des Log-Levels auf zwei Anwendungen eines Helm-Charts gezeigt: + +```yaml +apiVersion: v1 +metavalues: + # Plattformspezifische Konfigurationwert + mainLogLevel: + keys: + # ohne Mapping wird der Konfigurationswert ohne Änderung an die values.yaml durchgereicht + - path: controllerManager.env.loglevel + # mit Mapping wird erst der Konfigurationswert abgebildet (z. B. panic -> error) und dann weitergereicht + # Pfad zum Wert in der values.yaml für Hauptanwendung + - path: app.env.loglevel + mapping: + DEBUG: debug + INFO: info + WARN: error + ERROR: error + # Pfad zum Wert in der values.yaml für zweite Anwendung + - path: loglevel + mapping: + DEBUG: 1 + INFO: 2 + WARN: 3 + ERROR: 4 +``` + +**Dogu-CR, die den Konfigurationswert setzt:** + +```yaml +apiVersion: k8s.cloudogu.com/v1 +kind: Dogu +metadata: + name: my-dogu +spec: + name: official/my-dogu + version: 1.2.3-4 + mappedValues: + mainLogLevel: ERROR +``` + +Um plattformspezifische Konfigurationen treffen zu können, sollte ein Dogu-Helm-Chart die `dogu-values-metadata.yaml` stets mit ausliefern. Für konfigurationslose Dogus ist diese Datei optional. + +### `dogu-upgrade.yaml` + +Ein wesentlicher Bestandteil des CES ist die Ausführung von Dogu-Upgrades, die unter normalen Umständen manuelle Aktionen des Administrators benötigen. Im CES sollen die Upgrade-Prozesse automatisiert durch den Dogu-Operator ausgeführt werden. Ein wichtiger Bestandteil hierfür sind Migrationspfade zwischen einzelnen Dogu-Versionen. Diese werden in der `dogu-upgrade.yaml` abgebildet und während eines Upgrades durch den Dogu-Operator validiert. In der `dogu-upgrade.yaml` werden grundsätzlich erlaubte Versionssprünge definiert: + +```yaml +upgrades: + # Upgrades innerhalb des Pfades sind ohne Migration erlaubt. + - from: ">=1.0.0 <=1.7.0" + to: "1.8.0" + # Upgrade bringt Migration mit. + - from: ">=1.8.0 <2.0.0" + to: "2.0.0" + isMigration: true + helmTimeout: 15m + scaleSelectors: + - matchLabels: + dogu.name: nexus +``` + +### `chart-patch-tpl.yaml` + +Eine besondere Herausforderung für den Betrieb der Plattform sind sogenannte Air-Gapped-Umgebungen, die isoliert von anderen Umgebungen – insbesondere dem Internet – betrieben werden. Für solche Umgebungen werden sowohl die benötigten Helm-Charts als auch Container Images in eine interne OCI-Registry innerhalb der isolierten Umgebung gespiegelt, wodurch sich die Bezugsquellen der Images aus dem Helm-Chart ändern. Mit Hilfe der `chart-patch-tpl.yaml` können die Referenzen der Images durch ein Mirroring-Tool für die Zielumgebung aufgelöst und überschrieben werden. + +**`chart-patch-tpl.yaml` am Beispiel des Nexus-Dogus** + +```yaml +apiVersion: v1 +values: + images: + nexus: registry.cloudogu.com/official/nexus:3.86.2-6 + nexusSaManager: registry.cloudogu.com/k8s/service-account-producer-sidecar:0.1.2 + postgresql: docker.io/library/postgres:14.18 +patches: + values.yaml: + nexus: + image: + registry: "{{ registryFrom .images.nexus }}" + repository: "{{ repositoryFrom .images.nexus }}" + tag: "{{ tagFrom .images.nexus }}" + saManager: + image: + registry: "{{ registryFrom .images.nexusSaManager }}" + repository: "{{ repositoryFrom .images.nexusSaManager }}" + tag: "{{ tagFrom .images.nexusSaManager }}" + postgresql: + image: + registry: "{{ registryFrom .images.postgresql }}" + repository: "{{ repositoryFrom .images.postgresql }}" + tag: "{{ tagFrom .images.postgresql }}" +``` + +Die `chart-patch-tpl.yaml` sollte stets Bestandteil des Dogu-Helm-Charts sein, um die im Helm-Chart referenzierten Container Images in eine Air-Gapped-Umgebung spiegeln zu können. + + +## Templates und die Anbindung an die Plattform + +In den Templates des Helm-Charts werden alle Kubernetes-Ressourcen zur Verfügung gestellt, um die Anwendung auf der Plattform ausführbar zu machen. Zu diesen Ressourcen zählen auch Custom Resources Definitions (CRDs), die von Cloudogu bereitgestellt werden und als API für die Plattform dienen. In diesem Abschnitt werden die einzelnen CRDs für die Integration in das CES genauer beschrieben. + +### AuthRegistration + +Das CES bietet seinen Nutzer die Möglichkeit des Single Sign-On (SSO). Damit ein Dogu den SSO nutzen kann, muss es sich mithilfe der [`AuthRegistration-CR`](https://github.com/cloudogu/k8s-auth-registration-lib/blob/main/docs/operations/auth_registration_de.md) beim Identity-Provider (IdP) der Plattform registrieren. Aktuell werden die Authentifizierungsprotokolle `CAS`, `OAUTH` und `OIDC` unterstützt. Mit der Registration beim IdP werden zugleich Credentials in einem Secret bereitgestellt, die von dem Dogu für Anfragen gegen den IdP genutzt werden können. + +Eine `AuthRegistration` provisioniert nur die serverseitige Integration beim IdP. Die Anwendung muss das ausgewählte Authentifizierungsprotokoll weiterhin selbst implementieren. + +### WarpMenuEntry + +Für die zentrale Navigation auf der Plattform wird das Warp-Menü verwendet. Wenn ein Dogu im Warp-Menü angezeigt werden soll, muss für jeden internen, für Anwender:innen sichtbaren Einstiegspunkt eine [`WarpMenuEntry-CR`](https://github.com/cloudogu/k8s-warp-menu-entry-lib/blob/main/docs/operations/warp_menu_entry_de.md) bereitgestellt werden. Je nach Bedarf kann ein Dogu keinen, einen oder mehrere Einträge definieren. + +Jeder Eintrag enthält einen deutschen und englischen Anzeigenamen, eine Kategorie sowie einen relativen Pfad zum Dogu. Das Warp-Menü macht die Anwendung nicht grundsätzlich erreichbar. Der relative Pfad muss zu einer unabhängig funktionierenden HTTP-Exposition passen. + +### Exposition + +Soll ein Dogu von außen erreichbar sein, muss hierfür eine oder mehrere [`Exposition-CR`](https://github.com/cloudogu/k8s-exposition-lib/blob/main/docs/operations/exposition_cr_de.md) deklariert werden. Die `Exposition` definiert, wie ein Service von außerhalb der Plattform erreichbar gemacht wird. Sie unterstützt HTTP-Routen (Layer 7) sowie rohe TCP- und UDP-Ports (Layer 4). Für HTTP-Routen können zusätzlich Path-Rewrites definiert werden. Auf Layer 4 Ebene kann es zu Kollisionen kommen, wenn zwei oder mehrere `Expositions` den gleichen Port für das gleiche Protokoll anfragen. In diesem Fall wird keine der betroffenen `Expositions` angewendet, solang der Konflikt besteht. Der Administrator wird hierüber im Status der CR informiert. + +### ServiceAccountRequest / ServiceAccountProducer + +Im CES ist es möglich, dass verschiedene Dogus/Components miteinander interagieren. Hierfür muss für ein zugreifendes Dogu/Component (Consumer) ein entsprechender ServiceAccount beim Ziel-Dogu/-Component (Producer) erstellt werden. Diese Service-Account-Beziehung ist also frei wählbar und ist nicht nur auf Dogus unter sich fest gelegt. Dieser Mechanismus erlaubt auch Ringabhängigkeiten zwischen Producer und Consumer. + +Die ServiceAccount-Erstellung lässt sich deklarativ über die CRDs [`ServiceAccountRequest`](https://github.com/cloudogu/k8s-serviceaccount-lib/blob/main/docs/operations/serviceaccountrequest_cr_de.md) und [`ServiceAccountProducer`](https://github.com/cloudogu/k8s-serviceaccount-lib/blob/main/docs/operations/serviceaccountproducer_cr_de.md) steuern. + +**`ServiceAccountProducer`** + +Bietet ein Producer eine Schnittstelle an, die von anderen Dogus genutzt werden kann, muss es eine `ServiceAccountProducer-CR` bereitstellen. Die `ServiceAccountProducer`-CR definiert, wie Service-Accounts für Consumer erstellt werden und welche Parameter unterstützt werden. Ferner beschreibt die CR die Struktur, wie die Werte nach dem Erstellen eines Service-Accounts vom Producer zurückgegeben werden. Jeder zurückgegebene Wert wird als Schlüssel in das vom anfragenden Consumer referenzierte Secret geschrieben. + +**`ServiceAccountRequest`** + +Benötigt ein Consumer einen Service-Account bei einem Producer, muss es diesen über die `ServiceAccountRequest-CR` anfordern, indem ein Producer benannt wird und optional Parameter übergeben werden. Die resultieren Credentials des Requests werden durch den Operator in ein referenziertes Kubernetes-Secret des konsumierenden Dogus geschrieben. Ist keine Referenz zu einem Secret im `ServiceAccountRequest` deklariert, wird ein Secret mit dem Namen der ServiceAccountRequest-Ressource erstellt. Die CR bildet das Gegenstück zum `ServiceAccountProducer`. + +## Abgrenzung zu Dogu V2 + +In Dogu V2 wird ein Dogu mithilfe des plattformspezifischen Deskriptorformats `dogu.json` beschrieben, in dem zugleich die Konfiguration sowie die Nutzung der Plattform-API beschrieben ist. In Dogu V3 findet ein Wechsel hin zum [HELM](https://helm.sh/de/), dem De-facto-Standard von Kubernetes zur Paketverwaltung, statt. Viele Inhalte der bisherigen `dogu.json` werden dadurch entweder als Kubernetes-Ressourcen, oder als gesonderte Dogu-spezifische Dateien in das Helm-Chart verschoben. Die folgende Tabelle zeigt, wie die einzelnen Felder aus der `dogu.json` im neuen Dogu-Helm-Chart abgebildet werden. + +| Feld in `dogu.json` | Behandlung in Dogu V3 | +|--------------------------------------------------------------------|----------------------------------------------------------------------------------------| +| `Name`, `Version`, `DisplayName`, `Description`, `URL`, `Logo` | Metadaten des `Chart.yaml` | +| `Image` | Container-Image-Referenzen in `chart-patch-tpl.yaml` | +| `Dependencies` | Zusätzliche Workloads oder exteren Abhängigkeiten via ServiceAccount-CRs | +| `ServiceAccounts` | ServiceAccount-CRs | +| `Volumes` | Kubernetes-PVCs und Volume-Definitionen | +| `ExposedCommands` | Entfällt als API | +| `ExposedPorts` | Exposition-CRs | +| `Tags`, `Category` | Katalog-Metadaten in `Chart.yaml`; Warp-Menü über WarpMenu-CR | +| `Configuration` | `values.yaml`, `dogu-values-metadata.yaml` und `values.schema.json` | +| `HealthChecks` | Kubernetes-Probes in Pod-Spezifikation | +| `Capabilities`, `EnvironmentVariables`, `Properties`, `Privileged` | entfallen oder werden als Kubernetes-/Helm-Konzepte abgebildet | diff --git a/docs/v3/concepts/artifacts_en.md b/docs/v3/concepts/artifacts_en.md new file mode 100644 index 0000000..eb4e3b7 --- /dev/null +++ b/docs/v3/concepts/artifacts_en.md @@ -0,0 +1,229 @@ +# Dogu Artifacts + +A Dogu is a ready-to-run application within the Cloudogu EcoSystem (CES) – such as SCM-Manager, Jenkins or SonarQube – that is seamlessly integrated into the platform. + +With the generational change starting from version 3 (V3), the CES takes a step toward cloud-native standards: the Helm chart becomes the central release artifact and the primary format for packaging, versioning and deploying a Dogu. By deploying through Helm, an additional, platform-specific descriptor format (such as the previous `dogu.json`) becomes obsolete. This simplifies artifact management and embeds the application seamlessly into the Kubernetes ecosystem. Container images remain separate artifacts that the Helm chart references. + +## The Chart as the Dogu Descriptor + +Within the Helm chart, the `Chart.yaml` serves as the leading manifest for providing central metadata. The file provides both the identification of the chart and its package dependencies. In addition, there are further manifests that play an important role in the integration into the CES. The following sections describe the most important artifacts and their significance for a Dogu V3 in detail. The top-level files in the Helm chart include: + +``` +k8s/ +└─ helm/ + ├─ templates/ + │ └─ ... + ├─ Chart.yaml + ├─ chart-patch-tpl.yaml + ├─ dogu-upgrade.yaml + ├─ dogu-values-metadata.yaml + ├─ values.yaml + └─ values.schema.json +``` + +These artifacts are described in order of relevance. + +### `Chart.yaml` + +The `Chart.yaml` contains metadata that describe a Dogu. Two versions are distinguished within the chart. +The Dogu version corresponds to the version of the chart (`version`), while the app version (`appVersion`) describes the version of the actual application contained within the Dogu. Both versions are independent of each other and may differ. For example, Redmine could be published as a Dogu in version `45.7.0`, while the contained Redmine application has the app version `6.1.2`. + +In addition to the [Helm standard fields](https://helm.sh/docs/topics/charts/#the-chartyaml-file), the `Chart.yaml` uses platform-specific annotations that are marked with the prefix `dogu.cloudogu.com/`. This prefix identifies Dogu metadata within the Helm chart and distinguishes it from general Kubernetes or Helm annotations. The following platform-specific annotations are currently supported: + +- `api-version`: The Dogu API version, e.g. `v3` +- `display-name`: The display name of a Dogu if the `name` attribute of the `Chart.yaml` should not be used for display +- `application.`: Defines additional applications contained in the chart. `` corresponds to the technical name of the contained application, whereby the annotation value contains a non-empty version specification as a string + +Unknown annotations with the prefix `dogu.cloudogu.com/` are permitted but are ignored by platform-specific components, as long they are not part of the defined mandatory metadata. The following fields are considered mandatory in the `Chart.yaml`: + +- `name` +- `version` +- `appVersion` +- `description` +- `annotations.dogu.cloudogu.com/api-version` + +An example of a valid `Chart.yaml` for a Dogu could look as follows: + +```yaml +apiVersion: v2 +name: redmine +description: Redmine als Cloudogu EcoSystem Dogu +type: application +version: 45.7.0 +appVersion: 6.1.2 +home: https://cloudogu.com/ecosystem +sources: + - https://github.com/cloudogu/redmine +icon: https://dogu.cloudogu.com/api/v3/dogus/official/redmine/icon.svg +keywords: + - projectmanagement + - issue + - development +maintainers: + - name: Cloudogu GmbH + email: hello@cloudogu.com +annotations: + dogu.cloudogu.com/api-version: v3 + dogu.cloudogu.com/display-name: Redmine + dogu.cloudogu.com/application.redmine: "6.1.2" + dogu.cloudogu.com/application.postgresql: "16.8" +``` + +### `values.yaml` + +The `values.yaml` serves as the public interface for configuring Helm charts. It contains default values that are used for the Helm chart's templates. During installation, Helm allows the values from the `values.yaml` to be overridden by merging the supplied values with the default values from the Helm chart. + +### `values.schema.json` + +For the `values.yaml`, a schema can be defined in the form of a JSON schema using the `values.schema.json` to validate the resulting values of the Helm chart. Since the developers of an application know best what input is required and its correct structure, this schema file should always be an integral part of the Dogu Helm chart. The Dogu operator uses it to perform automated validation of the values during installation or update and to catch faulty configurations early. + +### `dogu-values-metadata.yaml` + +For the platform there can be global configuration parameters that cannot always be represented by existing values from a Helm chart's `values.yaml`. For example, a global log level can be set for the platform that is applied to all Dogus. To account this, the `dogu-values-metadata.yaml` was introduced. Through it, platform-specific configurations can be applied to the values of a Dogu's Helm chart by defining the mapping between individual values within it. Platform-specific configurations are defined in the Dogu CR and applied by the Dogu operator. The following example shows the mapping of the log level onto two applications of a Helm chart: + +```yaml +apiVersion: v1 +metavalues: + # Platform-specific configuration value + mainLogLevel: + keys: + # without a mapping the configuration value is passed through to the values.yaml unchanged + - path: controllerManager.env.loglevel + # with a mapping the configuration value is first translated (e.g. panic -> error) and then passed on + # path to the value in the values.yaml for the main application + - path: app.env.loglevel + mapping: + DEBUG: debug + INFO: info + WARN: error + ERROR: error + # path to the value in the values.yaml for the second application + - path: loglevel + mapping: + DEBUG: 1 + INFO: 2 + WARN: 3 + ERROR: 4 +``` + +**Dogu CR that sets the configuration value:** + +```yaml +apiVersion: k8s.cloudogu.com/v1 +kind: Dogu +metadata: + name: my-dogu +spec: + name: official/my-dogu + version: 1.2.3-4 + mappedValues: + mainLogLevel: ERROR +``` + +To be able to make platform-specific configurations, a Dogu Helm chart should always ship the `dogu-values-metadata.yaml`. For Dogus without configuration this file is optional. + +### `dogu-upgrade.yaml` + +An essential part of the CES is the execution of Dogu upgrades, which under normal circumstances require manual actions by the administrator. In the CES, upgrade processes are to be executed automatically by the Dogu operator. An important part for this are migration paths between individual Dogu versions. These are represented in the `dogu-upgrade.yaml` and validated by the Dogu operator during an upgrade. In the `dogu-upgrade.yaml`, the fundamentally permitted version jumps are defined: + +```yaml +upgrades: + # Upgrades within the path are allowed without migration. + - from: ">=1.0.0 <=1.7.0" + to: "1.8.0" + # Upgrade includes a migration. + - from: ">=1.8.0 <2.0.0" + to: "2.0.0" + isMigration: true + helmTimeout: 15m + scaleSelectors: + - matchLabels: + dogu.name: nexus +``` + +### `chart-patch-tpl.yaml` + +A particular challenge for operating the platform are so-called air-gapped environments, which are run in isolation from other environments – in particular the internet. For such environments, both the required Helm charts and container images are mirrored into an internal OCI registry within the isolated environment, which changes the sources from which the images are obtained in the Helm chart. With the help of the `chart-patch-tpl.yaml`, the image references can be resolved and overwritten for the target environment by a mirroring tool. + +**`chart-patch-tpl.yaml` using the Nexus Dogu as an example** + +```yaml +apiVersion: v1 +values: + images: + nexus: registry.cloudogu.com/official/nexus:3.86.2-6 + nexusSaManager: registry.cloudogu.com/k8s/service-account-producer-sidecar:0.1.2 + postgresql: docker.io/library/postgres:14.18 +patches: + values.yaml: + nexus: + image: + registry: "{{ registryFrom .images.nexus }}" + repository: "{{ repositoryFrom .images.nexus }}" + tag: "{{ tagFrom .images.nexus }}" + saManager: + image: + registry: "{{ registryFrom .images.nexusSaManager }}" + repository: "{{ repositoryFrom .images.nexusSaManager }}" + tag: "{{ tagFrom .images.nexusSaManager }}" + postgresql: + image: + registry: "{{ registryFrom .images.postgresql }}" + repository: "{{ repositoryFrom .images.postgresql }}" + tag: "{{ tagFrom .images.postgresql }}" +``` + +The `chart-patch-tpl.yaml` should always be part of the Dogu Helm chart in order to be able to mirror the container images referenced in the Helm chart into an air-gapped environment. + + +## Templates and the Connection to the Platform + +The Helm chart's templates provide all Kubernetes resources required to make the application runnable on the platform. These resources also include Custom Resource Definitions (CRDs) that are provided by Cloudogu and serve as the API for the platform. This section describes the individual CRDs for the CES integration in more detail. + +### AuthRegistration + +The CES offers its users the option of Single Sign-On (SSO). For a Dogu to be able to use SSO, it must register at the platform's identity provider (IdP) using the [`AuthRegistration-CR`](https://github.com/cloudogu/k8s-auth-registration-lib/blob/main/docs/operations/auth_registration_en.md). Currently the authentication protocols `CAS`, `OAUTH` and `OIDC` are supported. Registration with the IdP simultaneously provides credentials in a Secret that can be used by the Dogu for requests against the IdP. + +An `AuthRegistration` only provisions the server-side integration at the IdP. The application must still implement the selected authentication protocol itself. + +### WarpMenuEntry + +The Warp menu is used for central navigation on the platform. If a Dogu should be shown in the Warp menu, a [`WarpMenuEntry-CR`](https://github.com/cloudogu/k8s-warp-menu-entry-lib/blob/main/docs/operations/warp_menu_entry_en.md) must be provided for each internal entry point that is visible to users. Depending on the need, a Dogu can define no entries, one entry, or multiple entries. + +Each entry contains a German and an English display name, a category, and a relative path to the Dogu. The Warp menu does not make the application reachable by itself. The relative path must match an independently functioning HTTP exposition. + +### Exposition + +If a Dogu is supposed to be reachable from the outside, one or more [`Exposition-CR`](https://github.com/cloudogu/k8s-exposition-lib/blob/main/docs/operations/exposition_cr_en.md) must be declared for this purpose. The `Exposition` defines how a service is made reachable from outside the platform. It supports HTTP routes (Layer 7) as well as raw TCP and UDP ports (Layer 4). For HTTP routes, path rewrites can additionally be defined. At the Layer 4 level, collisions can occur if two or more `Expositions` request the same port for the same protocol. In this case, none of the affected `Expositions` are applied as long as the conflict persists. The administrator is informed about this in the status of the CR. + +### ServiceAccountRequest / ServiceAccountProducer + +In the CES it is possible for different Dogus/Components to interact with each other. For this, an appropriate ServiceAccount must be created at the target Dogu/Component (Producer) for an accessing Dogu/Component (Consumer). This service-account relationship can therefore be freely chosen and is not limited to Dogus only. This mechanism also allows cyclical dependencies between producers and consumers. + +ServiceAccount creation can be controlled declaratively via the CRDs [`ServiceAccountRequest`](https://github.com/cloudogu/k8s-serviceaccount-lib/blob/main/docs/operations/serviceaccountrequest_cr_en.md) and [`ServiceAccountProducer`](https://github.com/cloudogu/k8s-serviceaccount-lib/blob/main/docs/operations/serviceaccountproducer_cr_en.md). + +**`ServiceAccountProducer`** + +If a Producer offers an interface that can be used by other Dogus, it must provide a `ServiceAccountProducer-CR`. The `ServiceAccountProducer`-CR defines how service accounts are created for the Consumer and which parameters are supported. Furthermore, the CR describes values that the Producer returns after creating a service account. Each returned value is written as a key into the Secret referenced by the requesting the Consumer. + +**`ServiceAccountRequest`** + +If a Consumer needs a service account for a Producer, it must request this via the `ServiceAccountRequest-CR` by naming a producer and optionally passing parameters. The resulting credentials of the request are written by the operator into a referenced Kubernetes Secret of the Consumer. If no reference to a Secret is declared in the `ServiceAccountRequest`, a Secret with the name of the ServiceAccountRequest resource is created. The CR is the counterpart to the `ServiceAccountProducer`. + +## Distinction from Dogu V2 + +In Dogu V2, a Dogu is described using the platform-specific descriptor format `dogu.json`, in which both the configuration and the use of the platform API are described at the same time. In Dogu V3, a switch to [HELM](https://helm.sh/), the de-facto standard of Kubernetes for package management, takes place. As a result, much of the content of the previous `dogu.json` is moved either into Kubernetes resources or into separate Dogu-specific files within the Helm chart. The following table shows how the individual fields from the `dogu.json` are represented in the new Dogu Helm chart. + +| Field in `dogu.json` | Handling in Dogu V3 | +|--------------------------------------------------------------------|----------------------------------------------------------------------------------------| +| `Name`, `Version`, `DisplayName`, `Description`, `URL`, `Logo` | Metadata of the `Chart.yaml` | +| `Image` | Container image references in `chart-patch-tpl.yaml` | +| `Dependencies` | Additional workloads or external dependencies via ServiceAccount CRs | +| `ServiceAccounts` | ServiceAccount CRs | +| `Volumes` | Kubernetes PVCs and volume definitions | +| `ExposedCommands` | No longer exists as an API | +| `ExposedPorts` | Exposition CRs | +| `Tags`, `Category` | Catalog metadata in `Chart.yaml`; Warp menu via WarpMenu CR | +| `Configuration` | `values.yaml`, `dogu-values-metadata.yaml` and `values.schema.json` | +| `HealthChecks` | Kubernetes probes in the pod specification | +| `Capabilities`, `EnvironmentVariables`, `Properties`, `Privileged` | no longer exist or are represented as Kubernetes/Helm concepts | diff --git a/docs/v3/reference/compendium_de.md b/docs/v3/reference/compendium_de.md new file mode 100644 index 0000000..b113ba3 --- /dev/null +++ b/docs/v3/reference/compendium_de.md @@ -0,0 +1,23 @@ +# Kompendium der Dogu-V3-Artefakte + +Dieses Kompendium gibt einen Überblick über die Artefakte und APIs - den CES-Integrationsressourcen - von Dogu V3. Eine Einführung in ihr Zusammenspiel finden Sie unter [Dogu-Artefakte](../concepts/artifacts_de.md). + +## Chart-Artefakte und APIs + +| Artefakt / API | Zweck | Referenzdokumentation | +| --- | --- | --- | +| Helm-Chart | Führendes Dogu-Paket; enthält Metadaten, Standardwerte, Templates und Begleitdateien | [Helm-Chart-Format](https://helm.sh/docs/topics/charts/) | +| `Chart.yaml` | Dogu-Identität und Discovery-Metadaten; `version` ist die Dogu-Version, `appVersion` die Version der verpackten Anwendung | [Helm-`Chart.yaml`](https://helm.sh/docs/topics/charts/#the-chartyaml-file) | +| `values.yaml` | Standardwerte und öffentliche Konfigurationsschnittstelle | [Helm-Values](https://helm.sh/docs/chart_template_guide/values_files/) | +| `values.schema.json` | Validiert die zusammengeführten Values | [Helm-Schemadateien](https://helm.sh/docs/topics/charts/#schema-files) | +| `dogu-values-metadata.yaml` | Ordnet CES-Konfigurationsschlüssel wie einen globalen Log-Level Chart-Values zu | [dogu-values-metadata.yaml](../concepts/artifacts_de.md#dogu-values-metadatayaml) | +| `templates/` | Rendert Workloads, Services, PVCs, Probes und optionale CES-Integrationsressourcen | [Helm-Templates](https://helm.sh/docs/chart_template_guide/) und Verträge der Kubernetes-/CRD-Verantwortlichen | +| `chart-patch-tpl.yaml` | Listet alle vom Chart referenzierten Container-Images auf und löst deren Referenzen über ein Spiegelungswerkzeug für Air-Gapped-Umgebungen auf | [chart-patch-tpl.yaml](../concepts/artifacts_de.md#chart-patch-tplyaml) | +| `dogu-upgrade.yaml` | Beschreibt gültige Übergänge zwischen Dogu-Versionen und optionale Parameter zur Upgrade-Koordination | [dogu-upgrade.yaml](../concepts/artifacts_de.md#dogu-upgradeyaml) | +| Container-Images | Stellen die Anwendung sowie referenzierte Sidecar- und Init-Container bereit | [Kubernetes-Images](https://kubernetes.io/docs/concepts/containers/images/) | +| `AuthRegistration` | Deklariert bei Teilnahme an CES-Authentifizierung die Registrierung | [AuthRegistration](../concepts/artifacts_de.md#authregistration) | +| `Exposition` | Verbindet bei Bedarf einen Chart-Service mit CES-bereitgestelltem externen Zugriff | [Exposition](../concepts/artifacts_de.md#exposition) | +| `ServiceAccountRequest` | Fordert bei Bedarf technische Credentials von einem Producer an | [ServiceAccountRequest](../concepts/artifacts_de.md#serviceaccountrequest--serviceaccountproducer) | +| `ServiceAccountProducer` | Deklariert, dass das Dogu technische Accounts anbietet | [ServiceAccountProducer](../concepts/artifacts_de.md#serviceaccountrequest--serviceaccountproducer) | +| `WarpMenuEntry` | Deklariert bei einem sichtbaren CES-Pfad einen Eintrag im Warp-Menü | [WarpMenuEntry](../concepts/artifacts_de.md#warpmenuentry) | +| Dogu-Registry-Daten | Verbinden technische Chart-Metadaten mit außerhalb des Charts gepflegten Berechtigungs-, Marketing- oder Vertriebsdaten | — | diff --git a/docs/v3/reference/compendium_en.md b/docs/v3/reference/compendium_en.md new file mode 100644 index 0000000..4da5371 --- /dev/null +++ b/docs/v3/reference/compendium_en.md @@ -0,0 +1,23 @@ +# Dogu V3 Artifact Compendium + +This compendium provides an overview of the artifacts and APIs - the CES integration resources - of Dogu V3. For an introduction to how they work together, read [Dogu Artifacts](../concepts/artifacts_en.md). + +## Chart artifacts and APIs + +| Artifact / API | Purpose | Reference documentation | +| --- | --- | --- | +| Helm chart | Leading Dogu package; contains metadata, defaults, templates and companion files | [Helm chart format](https://helm.sh/docs/topics/charts/) | +| `Chart.yaml` | Dogu identity and discovery metadata; `version` is the Dogu version, `appVersion` the packaged application version | [Helm `Chart.yaml`](https://helm.sh/docs/topics/charts/#the-chartyaml-file) | +| `values.yaml` | Default values and public chart configuration interface | [Helm values](https://helm.sh/docs/chart_template_guide/values_files/) | +| `values.schema.json` | Validates the merged values | [Helm schema files](https://helm.sh/docs/topics/charts/#schema-files) | +| `dogu-values-metadata.yaml` | Maps CES configuration keys, such as a global log level, to chart values | [dogu-values-metadata.yaml](../concepts/artifacts_en.md#dogu-values-metadatayaml) | +| `templates/` | Renders workloads, Services, PVCs, probes and optional CES integration resources | [Helm templates](https://helm.sh/docs/chart_template_guide/) and owning Kubernetes/CRD contracts | +| `chart-patch-tpl.yaml` | Lists every container image referenced by the chart and resolves the references through a mirroring tool for air-gapped environments | [chart-patch-tpl.yaml](../concepts/artifacts_en.md#chart-patch-tplyaml) | +| `dogu-upgrade.yaml` | Describes valid Dogu-version transitions and optional parameters for upgrade coordination | [dogu-upgrade.yaml](../concepts/artifacts_en.md#dogu-upgradeyaml) | +| Container images | Provide the application and any sidecar and init containers referenced by the chart | [Kubernetes images](https://kubernetes.io/docs/concepts/containers/images/) | +| `AuthRegistration` | Declares authentication registration when the Dogu participates in CES authentication | [AuthRegistration](../concepts/artifacts_en.md#authregistration) | +| `Exposition` | Connects a chart Service to CES-provided external access when needed | [Exposition](../concepts/artifacts_en.md#exposition) | +| `ServiceAccountRequest` | Requests technical credentials from a producer when another CES service is needed | [ServiceAccountRequest](../concepts/artifacts_en.md#serviceaccountrequest--serviceaccountproducer) | +| `ServiceAccountProducer` | Declares that the Dogu offers technical accounts | [ServiceAccountProducer](../concepts/artifacts_en.md#serviceaccountrequest--serviceaccountproducer) | +| `WarpMenuEntry` | Declares a Warp menu entry when the Dogu has a user-facing CES path | [WarpMenuEntry](../concepts/artifacts_en.md#warpmenuentry) | +| Dogu Registry data | Combines technical chart metadata with entitlement and marketing or sales data maintained outside the chart | — |