From c7460065e6a12d2b2f022d700bb458ad23eb37f8 Mon Sep 17 00:00:00 2001 From: Henry Bobka Date: Tue, 21 Jul 2026 09:44:20 +0200 Subject: [PATCH 01/16] #90 Document Dogu V3 artifacts and API mapping --- docs/v3/README.md | 5 ++ docs/v3/README_de.md | 5 ++ docs/v3/concepts/artifacts.md | 64 +++++++++++++++++++++++ docs/v3/concepts/artifacts_de.md | 64 +++++++++++++++++++++++ docs/v3/images/artifacts.puml | 66 ++++++++++++++++++++++++ docs/v3/images/artifacts.svg | 1 + docs/v3/images/artifacts_de.puml | 66 ++++++++++++++++++++++++ docs/v3/images/artifacts_de.svg | 1 + docs/v3/images/dogu-json-to-v3.puml | 71 ++++++++++++++++++++++++++ docs/v3/images/dogu-json-to-v3.svg | 1 + docs/v3/images/dogu-json-to-v3_de.puml | 71 ++++++++++++++++++++++++++ docs/v3/images/dogu-json-to-v3_de.svg | 1 + docs/v3/reference/compendium.md | 57 +++++++++++++++++++++ docs/v3/reference/compendium_de.md | 57 +++++++++++++++++++++ 14 files changed, 530 insertions(+) create mode 100644 docs/v3/concepts/artifacts.md create mode 100644 docs/v3/concepts/artifacts_de.md create mode 100644 docs/v3/images/artifacts.puml create mode 100644 docs/v3/images/artifacts.svg create mode 100644 docs/v3/images/artifacts_de.puml create mode 100644 docs/v3/images/artifacts_de.svg create mode 100644 docs/v3/images/dogu-json-to-v3.puml create mode 100644 docs/v3/images/dogu-json-to-v3.svg create mode 100644 docs/v3/images/dogu-json-to-v3_de.puml create mode 100644 docs/v3/images/dogu-json-to-v3_de.svg create mode 100644 docs/v3/reference/compendium.md create mode 100644 docs/v3/reference/compendium_de.md diff --git a/docs/v3/README.md b/docs/v3/README.md index 4e7a775..3924943 100644 --- a/docs/v3/README.md +++ b/docs/v3/README.md @@ -15,8 +15,13 @@ The documentation will guide developers from a minimal working Dogu to more deta ## Available concepts +- [Understand Dogu V3 artifacts](concepts/artifacts.md) - [Understand the Multinode runtime environment](concepts/multinode-environment.md) +## Available reference + +- [Dogu V3 artifact compendium](reference/compendium.md) + ## Content boundaries - **Getting started** contains executable end-to-end instructions. The quick start covers only the smallest working happy path. 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/concepts/artifacts.md b/docs/v3/concepts/artifacts.md new file mode 100644 index 0000000..41d1259 --- /dev/null +++ b/docs/v3/concepts/artifacts.md @@ -0,0 +1,64 @@ +# Understand Dogu V3 Artifacts + +A Dogu V3 is a Helm chart. Think of the chart as the package that keeps the Dogu's identity, configuration interface, workload definitions and optional CES integrations together. Container images remain separate artifacts referenced by that package. + +![A Dogu V3 Helm chart containing metadata, configuration, companion files and templates that render Kubernetes and CES resources and reference container images](../images/artifacts.svg) + +## The chart is the leading artifact + +`Chart.yaml` identifies the package. Its `version` is the **Dogu version** and follows the chart lifecycle. `appVersion` is the version of the packaged upstream application; it is informative and can differ. A packaging fix can therefore change `version` without changing `appVersion`. + +The accepted metadata set includes standard Helm fields and Dogu annotations. In particular, `name`, `version`, `appVersion`, `description` and `annotations.dogu.cloudogu.com/api-version` are required by the target architecture. The [artifact compendium](../reference/compendium.md) records the detailed status and contract for each artifact. + +## Configuration belongs to the package + +- `values.yaml` supplies safe defaults and is the chart's configuration interface. +- `values.schema.json` validates the final values accepted by Helm. +- `dogu-values-metadata.yaml` maps CES-wide configuration keys to values when such mappings are needed. It is optional for a Dogu without configurable values. + +These files complement one another: defaults are not validation, and validation is not a CES mapping. Do not put credentials into values. + +## Templates become the running Dogu + +Files below `templates/` render ordinary Kubernetes resources: for example Deployments or StatefulSets, Services, probes, PVCs, ConfigMaps and Secret references. When the application needs a CES capability, the same chart can render the corresponding integration resource: + +- `AuthRegistration` for CES authentication; +- `Exposition` for external access; +- `ServiceAccountRequest` or `ServiceAccountProducer` for technical credentials; and +- `WarpMenuEntry` for a shared-menu entry. + +These declarations describe relationships and intent. Their runtime reconciliation, status and routing details belong to [the Multinode runtime environment](multinode-environment.md). + +## Companion files and images + +In the accepted V3 target architecture, `chart-patch-tpl.yaml` supplies the Dogu Registry and mirroring tools with all container-image references used by the chart. This includes application, sidecar, init-container, dependency and external images. `ces-mirror` uses these references to mirror images and rewrite them for the target registry. + +## How Dogu V3 replaces `dogu.json` + +V3 does not have a project-local `dogu.json`. Its former responsibilities move to standard chart metadata, chart values and schemas, rendered Kubernetes resources, companion files, CES custom resources, or the Dogu Registry API. Some deprecated or generic V2 fields are removed. For other fields, the accepted architecture does not define a general V3 replacement. The artifact compendium explains the destination of every V2 field. + +![V2 dogu.json responsibilities distributed to Chart.yaml, chart values and schemas, CES configuration metadata, Kubernetes resources, CES custom resources, Dogu Registry data, removed fields and fields without a general V3 destination](../images/dogu-json-to-v3.svg) + +The complete field-by-field disposition is in the [artifact compendium](../reference/compendium.md). + +## 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. + +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. + +## Where to continue + +- The [artifact compendium](../reference/compendium.md) explains which artifacts are required, who is responsible for them and where to find their documentation. +- Read [the Multinode runtime environment](multinode-environment.md) for what happens after chart resources are installed. diff --git a/docs/v3/concepts/artifacts_de.md b/docs/v3/concepts/artifacts_de.md new file mode 100644 index 0000000..f86172b --- /dev/null +++ b/docs/v3/concepts/artifacts_de.md @@ -0,0 +1,64 @@ +# Dogu-V3-Artefakte verstehen + +Ein Dogu V3 ist ein Helm-Chart. Das Chart ist das Paket, das Identität, Konfigurationsschnittstelle, Workload-Definitionen und optionale CES-Integrationen eines Dogus zusammenhält. Container-Images bleiben separate Artefakte, auf die dieses Paket verweist. + +![Ein Dogu-V3-Helm-Chart mit Metadaten, Konfiguration, Begleitdateien und Templates, die Kubernetes- und CES-Ressourcen rendern und Container-Images referenzieren](../images/artifacts_de.svg) + +## Das Chart ist das führende Artefakt + +`Chart.yaml` identifiziert das Paket. Die `version` ist die **Dogu-Version** und folgt dem Chart-Lebenszyklus. `appVersion` bezeichnet informativ die Version der verpackten Herstelleranwendung und darf abweichen. Eine reine Packaging-Korrektur kann daher `version` ändern, ohne `appVersion` zu ändern. + +Die akzeptierte Metadatenmenge umfasst Helm-Standardfelder und Dogu-Annotationen. Insbesondere sind `name`, `version`, `appVersion`, `description` und `annotations.dogu.cloudogu.com/api-version` in der Zielarchitektur verpflichtend. Das [Artefakt-Kompendium](../reference/compendium_de.md) beschreibt die Aufgabe und Verwendung jedes Artefakts. + +## Konfiguration gehört in das Paket + +- `values.yaml` liefert sichere Standardwerte und ist die Konfigurationsschnittstelle des Charts. +- `values.schema.json` validiert die endgültigen, von Helm angenommenen Values. +- `dogu-values-metadata.yaml` ordnet bei Bedarf CES-weite Konfigurationsschlüssel Chart-Values zu. Für ein Dogu ohne konfigurierbare Werte ist die Datei optional. + +Die Dateien ergänzen einander: Standardwerte sind keine Validierung, und Validierung ist keine CES-Zuordnung. Credentials gehören nicht in Values. + +## Templates werden zum laufenden Dogu + +Dateien unter `templates/` rendern normale Kubernetes-Ressourcen, beispielsweise Deployments oder StatefulSets, Services, Probes, PVCs, ConfigMaps und Secret-Referenzen. Benötigt die Anwendung eine CES-Funktion, kann dasselbe Chart die passende Integrationsressource rendern: + +- `AuthRegistration` für CES-Authentifizierung, +- `Exposition` für externen Zugriff, +- `ServiceAccountRequest` oder `ServiceAccountProducer` für technische Credentials und +- `WarpMenuEntry` für einen Eintrag im gemeinsamen Menü. + +Diese Deklarationen beschreiben Beziehungen und Absicht. Laufzeit-Reconciliation, Status und Routing-Details erklärt [die Multinode-Laufzeitumgebung](multinode-environment_de.md). + +## Begleitdateien und Images + +In der akzeptierten V3-Zielarchitektur stellt `chart-patch-tpl.yaml` der Dogu Registry und den Spiegelungswerkzeugen alle vom Chart verwendeten Container-Image-Referenzen bereit. Dazu gehören Anwendungs-, Sidecar-, Init-Container-, Abhängigkeits- und externe Images. `ces-mirror` verwendet diese Referenzen, um Images zu spiegeln und für die Ziel-Registry umzuschreiben. + +## Wie Dogu V3 die `dogu.json` ersetzt + +V3 besitzt keine projektlokale `dogu.json`. Deren bisherige Aufgaben wandern in Standard-Chart-Metadaten, Chart-Values und Schemata, gerenderte Kubernetes-Ressourcen, Begleitdateien, CES-Custom-Resources oder die Dogu-Registry-API. Einige veraltete oder generische V2-Felder entfallen. Für andere Felder definiert die akzeptierte Architektur keinen allgemeinen V3-Ersatz. Das Artefakt-Kompendium erklärt das Ziel jedes V2-Feldes. + +![Aufgaben der V2-Datei dogu.json werden auf Chart.yaml, Chart-Values und Schemata, CES-Konfigurationsmetadaten, Kubernetes-Ressourcen, CES-Custom-Resources, Dogu-Registry-Daten, entfallene Felder und Felder ohne allgemeines V3-Ziel verteilt](../images/dogu-json-to-v3_de.svg) + +Die vollständige Zuordnung jedes Feldes enthält das [Artefakt-Kompendium](../reference/compendium_de.md). + +## 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. + +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. + +## So geht es weiter + +- Im [Artefakt-Kompendium](../reference/compendium_de.md) erfahren Sie, welche Artefakte benötigt werden, wer dafür verantwortlich ist und wo die zugehörige Dokumentation zu finden ist. +- Lesen Sie [die Multinode-Laufzeitumgebung](multinode-environment_de.md), um zu verstehen, was nach der Installation der Chart-Ressourcen geschieht. diff --git a/docs/v3/images/artifacts.puml b/docs/v3/images/artifacts.puml new file mode 100644 index 0000000..74945ea --- /dev/null +++ b/docs/v3/images/artifacts.puml @@ -0,0 +1,66 @@ +@startuml +!pragma layout smetana +skinparam backgroundColor white +skinparam defaultFontColor #392A25 +skinparam ArrowColor #00426B +skinparam rectangleBorderColor #1978A3 +skinparam rectangleBackgroundColor #23A3DD +skinparam rectangleRoundCorner 0 +skinparam shadowing false +hide stereotype +left to right direction + + + +rectangle "Helm chart" as chart <> { + together { + rectangle "Chart.yaml\nidentity + versions" as metadata <> + rectangle "values.yaml\nvalues.schema.json\ndogu-values-\nmetadata.yaml" as config <> + rectangle "Image metadata\nchart-patch-tpl.yaml" as imageMetadata <> + rectangle "Upgrade metadata\ndogu-upgrade.yaml" as upgradeMetadata <> + } + rectangle "templates/" as templates +} + +cloud "Referenced\ncontainer images" as images #FCFAF4 +rectangle "Platform tooling\nDogu Registry · ces-mirror" as tooling <> +rectangle "Dogu Operator" as operator <> +rectangle "Rendered release resources" as rendered <> { + together { + rectangle "Kubernetes resources\nworkloads · Services · PVCs" as k8s <> + rectangle "CES integration resources\nAuthRegistration · Exposition\nServiceAccountRequest / Producer\nWarpMenuEntry" as ces <> + } +} + +chart -[hidden]right-> rendered +rendered -[hidden]right-> images +metadata --> templates +config --> templates +templates --> k8s +templates --> ces +imageMetadata --> tooling +tooling --> images +upgradeMetadata --> operator +k8s --> images +@enduml diff --git a/docs/v3/images/artifacts.svg b/docs/v3/images/artifacts.svg new file mode 100644 index 0000000..726b352 --- /dev/null +++ b/docs/v3/images/artifacts.svg @@ -0,0 +1 @@ +Helm chartRendered release resourcesReferencedcontainer imagesPlatform toolingDogu Registry · ces-mirrorDogu OperatorChart.yamlidentity + versionsvalues.yamlvalues.schema.jsondogu-values-metadata.yamlImage metadatachart-patch-tpl.yamlUpgrade metadatadogu-upgrade.yamltemplates/Kubernetes resourcesworkloads · Services · PVCsCES integration resourcesAuthRegistration · ExpositionServiceAccountRequest / ProducerWarpMenuEntry \ No newline at end of file diff --git a/docs/v3/images/artifacts_de.puml b/docs/v3/images/artifacts_de.puml new file mode 100644 index 0000000..2638eee --- /dev/null +++ b/docs/v3/images/artifacts_de.puml @@ -0,0 +1,66 @@ +@startuml +!pragma layout smetana +skinparam backgroundColor white +skinparam defaultFontColor #392A25 +skinparam ArrowColor #00426B +skinparam rectangleBorderColor #1978A3 +skinparam rectangleBackgroundColor #23A3DD +skinparam rectangleRoundCorner 0 +skinparam shadowing false +hide stereotype +left to right direction + + + +rectangle "Helm-Chart" as chart <> { + together { + rectangle "Chart.yaml\nIdentität + Versionen" as metadata <> + rectangle "values.yaml\nvalues.schema.json\ndogu-values-\nmetadata.yaml" as config <> + rectangle "Image-Metadaten\nchart-patch-tpl.yaml" as imageMetadata <> + rectangle "Upgrade-Metadaten\ndogu-upgrade.yaml" as upgradeMetadata <> + } + rectangle "templates/" as templates +} + +cloud "Referenzierte\nContainer-Images" as images #FCFAF4 +rectangle "Plattformwerkzeuge\nDogu Registry · ces-mirror" as tooling <> +rectangle "Dogu Operator" as operator <> +rectangle "Gerenderte Release-Ressourcen" as rendered <> { + together { + rectangle "Kubernetes-Ressourcen\nWorkloads · Services · PVCs" as k8s <> + rectangle "CES-Integrationsressourcen\nAuthRegistration · Exposition\nServiceAccountRequest / Producer\nWarpMenuEntry" as ces <> + } +} + +chart -[hidden]right-> rendered +rendered -[hidden]right-> images +metadata --> templates +config --> templates +templates --> k8s +templates --> ces +imageMetadata --> tooling +tooling --> images +upgradeMetadata --> operator +k8s --> images +@enduml diff --git a/docs/v3/images/artifacts_de.svg b/docs/v3/images/artifacts_de.svg new file mode 100644 index 0000000..3389e5c --- /dev/null +++ b/docs/v3/images/artifacts_de.svg @@ -0,0 +1 @@ +Helm-ChartGerenderte Release-RessourcenReferenzierteContainer-ImagesPlattformwerkzeugeDogu Registry · ces-mirrorDogu OperatorChart.yamlIdentität + Versionenvalues.yamlvalues.schema.jsondogu-values-metadata.yamlImage-Metadatenchart-patch-tpl.yamlUpgrade-Metadatendogu-upgrade.yamltemplates/Kubernetes-RessourcenWorkloads · Services · PVCsCES-IntegrationsressourcenAuthRegistration · ExpositionServiceAccountRequest / ProducerWarpMenuEntry \ No newline at end of file diff --git a/docs/v3/images/dogu-json-to-v3.puml b/docs/v3/images/dogu-json-to-v3.puml new file mode 100644 index 0000000..b1c822e --- /dev/null +++ b/docs/v3/images/dogu-json-to-v3.puml @@ -0,0 +1,71 @@ +@startuml +!pragma layout smetana +skinparam backgroundColor white +skinparam defaultFontColor #392A25 +skinparam ArrowColor #00426B +skinparam rectangleBorderColor #1978A3 +skinparam rectangleBackgroundColor #23A3DD +skinparam rectangleRoundCorner 0 +skinparam shadowing false +hide stereotype +left to right direction + + + +rectangle "V2 dogu.json responsibilities" as v2 <> { + rectangle "Identity, versions,\ndiscovery metadata" as a <> + rectangle "Workloads, ports, storage,\nhealth and security" as b <> + rectangle "Configuration" as c <> + rectangle "CES integrations" as d <> + rectangle "Defined catalogue and\npublication data" as e <> + rectangle "Fields removed without\nreplacement" as f <> + rectangle "Category and other fields without\na general V3 destination" as g <> + + g -[hidden]right-> f + f -[hidden]right-> e + e -[hidden]right-> d + d -[hidden]right-> c + c -[hidden]right-> b + b -[hidden]right-> a +} + +rectangle "Dogu V3 destinations" as v3 <> { + rectangle "Chart.yaml\nmetadata" as chart <> + rectangle "Helm templates →\nKubernetes resources" as helm <> + rectangle "Chart values + schema +\ndogu-values-metadata.yaml" as config <> + rectangle "CES custom resources" as ces <> + rectangle "Chart.yaml + Dogu Registry +\nexternal marketing/sales data" as registry <> + rectangle "Removed" as removed <> + rectangle "No general V3\ndestination defined" as noGeneral <> + + noGeneral -[hidden]right-> removed + removed -[hidden]right-> registry + registry -[hidden]right-> ces + ces -[hidden]right-> config + config -[hidden]right-> helm + helm -[hidden]right-> chart +} + +a --> chart +b --> helm +c --> config +d --> ces +e --> registry +f --> removed +g --> noGeneral +@enduml diff --git a/docs/v3/images/dogu-json-to-v3.svg b/docs/v3/images/dogu-json-to-v3.svg new file mode 100644 index 0000000..97ce0ae --- /dev/null +++ b/docs/v3/images/dogu-json-to-v3.svg @@ -0,0 +1 @@ +V2 dogu.json responsibilitiesDogu V3 destinationsIdentity, versions,discovery metadataWorkloads, ports, storage,health and securityConfigurationCES integrationsDefined catalogue andpublication dataFields removed withoutreplacementCategory and other fields withouta general V3 destinationChart.yamlmetadataHelm templates →Kubernetes resourcesChart values + schema +dogu-values-metadata.yamlCES custom resourcesChart.yaml + Dogu Registry +external marketing/sales dataRemovedNo general V3destination defined \ No newline at end of file diff --git a/docs/v3/images/dogu-json-to-v3_de.puml b/docs/v3/images/dogu-json-to-v3_de.puml new file mode 100644 index 0000000..ac325d4 --- /dev/null +++ b/docs/v3/images/dogu-json-to-v3_de.puml @@ -0,0 +1,71 @@ +@startuml +!pragma layout smetana +skinparam backgroundColor white +skinparam defaultFontColor #392A25 +skinparam ArrowColor #00426B +skinparam rectangleBorderColor #1978A3 +skinparam rectangleBackgroundColor #23A3DD +skinparam rectangleRoundCorner 0 +skinparam shadowing false +hide stereotype +left to right direction + + + +rectangle "Aufgaben der V2-Datei dogu.json" as v2 <> { + rectangle "Identität, Versionen,\nDiscovery-Metadaten" as a <> + rectangle "Workloads, Ports, Speicher,\nHealth und Sicherheit" as b <> + rectangle "Konfiguration" as c <> + rectangle "CES-Integrationen" as d <> + rectangle "Definierte Katalog- und\nVeröffentlichungsdaten" as e <> + rectangle "Ersatzlos entfernte\nFelder" as f <> + rectangle "Kategorie und andere Felder ohne\nallgemeines V3-Ziel" as g <> + + g -[hidden]right-> f + f -[hidden]right-> e + e -[hidden]right-> d + d -[hidden]right-> c + c -[hidden]right-> b + b -[hidden]right-> a +} + +rectangle "Ziele in Dogu V3" as v3 <> { + rectangle "Chart.yaml\nMetadaten" as chart <> + rectangle "Helm-Templates →\nKubernetes-Ressourcen" as helm <> + rectangle "Chart-Values + Schema +\ndogu-values-metadata.yaml" as config <> + rectangle "CES-Custom-Resources" as ces <> + rectangle "Chart.yaml + Dogu Registry +\nexterne Marketing-/Vertriebsdaten" as registry <> + rectangle "Entfällt" as removed <> + rectangle "Kein allgemeines\nV3-Ziel festgelegt" as noGeneral <> + + noGeneral -[hidden]right-> removed + removed -[hidden]right-> registry + registry -[hidden]right-> ces + ces -[hidden]right-> config + config -[hidden]right-> helm + helm -[hidden]right-> chart +} + +a --> chart +b --> helm +c --> config +d --> ces +e --> registry +f --> removed +g --> noGeneral +@enduml diff --git a/docs/v3/images/dogu-json-to-v3_de.svg b/docs/v3/images/dogu-json-to-v3_de.svg new file mode 100644 index 0000000..60cae0f --- /dev/null +++ b/docs/v3/images/dogu-json-to-v3_de.svg @@ -0,0 +1 @@ +Aufgaben der V2-Datei dogu.jsonZiele in Dogu V3Identität, Versionen,Discovery-MetadatenWorkloads, Ports, Speicher,Health und SicherheitKonfigurationCES-IntegrationenDefinierte Katalog- undVeröffentlichungsdatenErsatzlos entfernteFelderKategorie und andere Felder ohneallgemeines V3-ZielChart.yamlMetadatenHelm-Templates →Kubernetes-RessourcenChart-Values + Schema +dogu-values-metadata.yamlCES-Custom-ResourcesChart.yaml + Dogu Registry +externe Marketing-/VertriebsdatenEntfälltKein allgemeinesV3-Ziel festgelegt \ No newline at end of file diff --git a/docs/v3/reference/compendium.md b/docs/v3/reference/compendium.md new file mode 100644 index 0000000..eb20419 --- /dev/null +++ b/docs/v3/reference/compendium.md @@ -0,0 +1,57 @@ +# Dogu V3 Artifact Compendium + +This compendium provides an overview of the artifacts and APIs of Dogu V3. For an introduction to how they work together, read [Understand Dogu V3 Artifacts](../concepts/artifacts.md). + +## Chart artifacts and APIs + +| Artifact / API | Purpose | When needed | Owner | Reference documentation | +| --- | --- | --- | --- | --- | +| Helm chart | Leading Dogu package; contains metadata, defaults, templates and companion files | Always | Dogu developer | [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 | Always | Dogu developer; consumed by Dogu tooling | [Helm `Chart.yaml`](https://helm.sh/docs/topics/charts/#the-chartyaml-file) | +| `values.yaml` | Safe defaults and public chart configuration interface | Always, according to the Helm chart convention | Dogu developer | [Helm values](https://helm.sh/docs/chart_template_guide/values_files/) | +| `values.schema.json` | Validates the merged values | When the Dogu exposes configurable values | Dogu developer | [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 | For CES-wide configuration mappings; optional for a configuration-free Dogu | Dogu developer; consumed by Dogu Operator | — | +| `templates/` | Renders workloads, Services, PVCs, probes and optional CES integration resources | Always | Dogu developer | [Helm templates](https://helm.sh/docs/chart_template_guide/) and owning Kubernetes/CRD contracts | +| `chart-patch-tpl.yaml` | Lists or resolves every container image referenced by the chart for the Dogu Registry and mirroring tools | Whenever the chart references container images, which is normally every Dogu | Dogu developer; consumed by the Dogu Registry and mirroring tools | — | +| `dogu-upgrade.yaml` | Describes valid Dogu-version transitions and optional parameters for upgrade coordination | The accepted ADRs do not yet define when the file must be present | Dogu developer; consumed by the Dogu Operator | — | +| Container images | Provide the application and any sidecar and init containers referenced by the chart | For every container rendered by the chart | Image producer; references owned by Dogu developer | [Kubernetes images](https://kubernetes.io/docs/concepts/containers/images/) | +| `AuthRegistration` | Declares authentication registration when the Dogu participates in CES authentication | When the Dogu uses CES authentication | k8s-auth-registration-lib owns the API; Dogu developer declares it | [AuthRegistration v1 API](https://github.com/cloudogu/k8s-auth-registration-lib/tree/develop/api/v1) | +| `Exposition` | Connects a chart Service to CES-provided external access when needed | When the Dogu needs external access | k8s-exposition-lib owns the API; Dogu developer declares it | [Exposition v1 API](https://github.com/cloudogu/k8s-exposition-lib/tree/develop/api/v1) | +| `ServiceAccountRequest` | Requests technical credentials from a producer when another CES service is needed | When the Dogu needs technical credentials from another CES service | k8s-serviceaccount-lib owns the API; consumer declares it | [Service account v2 API](https://github.com/cloudogu/k8s-serviceaccount-lib/tree/develop/api/v2) | +| `ServiceAccountProducer` | Declares that the Dogu offers technical accounts | When the Dogu provides technical accounts | k8s-serviceaccount-lib owns the API; producer declares it | [Service account v2 API](https://github.com/cloudogu/k8s-serviceaccount-lib/tree/develop/api/v2) | +| `WarpMenuEntry` | Declares a shared-menu entry when the Dogu has a user-facing CES path | When the Dogu provides a user-facing CES path | k8s-warp-menu-entry-lib owns the API; Dogu developer declares it | [WarpMenuEntry v1 API](https://github.com/cloudogu/k8s-warp-menu-entry-lib/tree/develop/api/v1) | +| Dogu Registry data | Combines technical chart metadata with entitlement and marketing or sales data maintained outside the chart | For publication, discovery and entitlement through the Dogu Registry | Cloudogu | — | + +## Complete V2 `dogu.json` disposition + +The following table lists every V2 `dogu.json` field and its accepted V3 destination where one exists. These mappings are not automatic conversions and do not necessarily preserve every V2 behavior. Where the accepted architecture defines no general V3 destination, the table states that explicitly. + +| V2 field | V3 destination | Disposition and status | +| --- | --- | --- | +| `Name` | `Chart.yaml` + registry namespace | Chart `name` is the simple technical name; the qualified namespace comes from registry context. | +| `Version` | `Chart.yaml` | Becomes chart `version`, the Dogu version. `appVersion` separately identifies the application. | +| `PublishedAt` | Dogu Registry v3 API | Included as publication metadata in the accepted API design. Its source and authoring workflow are not yet defined. | +| `DisplayName` | `Chart.yaml` | Dogu annotation `dogu.cloudogu.com/display-name`; optional in accepted target metadata. | +| `Description` | `Chart.yaml` | Standard `description`; required in the accepted target metadata. | +| `Category` | No concrete V3 field defined | The accepted architecture treats it as catalogue metadata but defines neither a `Chart.yaml` field nor an external source. It is independent of `WarpMenuEntry`. | +| `Tags` | `Chart.yaml` | Use Helm `keywords` for general search terms. Define menu entries separately with `WarpMenuEntry`. | +| `Logo` | `Chart.yaml` | Store the URL of the Dogu logo in the Helm `icon` field. | +| `URL` | `Chart.yaml` | Store the project or original vendor website in the Helm `home` field. | +| `Image` | Companion file + Kubernetes workloads | Image references are defined in the container specs. `chart-patch-tpl.yaml` also makes them discoverable by platform tooling. | +| `ExposedPorts` | Helm/Kubernetes + CES CR | Kubernetes Service plus `Exposition` when external access is needed. | +| `ExposedCommands` | Removed / purpose-specific V3 mechanisms | There is no generic V3 `ExposedCommands` API. Implement upgrade migrations with init containers or Helm hook Jobs. Assess other lifecycle or custom commands separately. | +| `Volumes` | Helm/Kubernetes resources | PVCs, volumes and volume mounts. Backup and retention must be declared/documented separately; no automatic field conversion. | +| `HealthCheck` | Helm/Kubernetes resources | Deprecated V2 single check. Map TCP or HTTP checks to an appropriate Kubernetes probe where the signal is equivalent; the accepted architecture defines no direct V3 equivalent for the V2 `state` check. | +| `HealthChecks` | Helm/Kubernetes resources | Model applicable checks as startup, readiness or liveness probes according to their purpose. This does not automatically preserve every V2 check type or consumer behavior. | +| `ServiceAccounts` | CES CRs | `ServiceAccountRequest` and, for offered accounts, `ServiceAccountProducer`. | +| `Privileged` | Removed | There is no direct V3 equivalent. The V2 field mounted the Docker socket; Kubernetes privileged mode or a security context is not an equivalent replacement. Define only the pod and container permissions the application requires. | +| `Security` | Helm/Kubernetes resources | Map supported controls to pod or container security contexts and capabilities. The accepted architecture does not define a shared V3 security baseline. | +| `Configuration` | Chart values, schema and companion metadata | `values.yaml`, `values.schema.json` and, for CES mappings, `dogu-values-metadata.yaml`. | +| `Properties` | Removed | The generic V2 field has no general V3 replacement. Use a concrete Helm, Kubernetes or CES API only when that API defines the required behavior. | +| `EnvironmentVariables` | Helm/Kubernetes resources | Explicit container `env`/`envFrom`, normally sourced from values, ConfigMaps or Secrets as appropriate. | +| `Dependencies` | Helm/Kubernetes resources or CES service-account CRs | Model service dependencies with `ServiceAccountRequest` where appropriate and other requirements explicitly in the chart. The accepted architecture defines no generic replacement for all V2 client, package or version checks. | +| `OptionalDependencies` | Optional `ServiceAccountRequest` or purpose-specific chart resources | Use an optional request for optional service-account dependencies. The accepted architecture defines no generic contract that preserves every V2 optional-dependency and version-check behavior. | + +## Related concept + +Return to [Understand Dogu V3 Artifacts](../concepts/artifacts.md), or continue with [the Multinode runtime environment](../concepts/multinode-environment.md). diff --git a/docs/v3/reference/compendium_de.md b/docs/v3/reference/compendium_de.md new file mode 100644 index 0000000..56c3868 --- /dev/null +++ b/docs/v3/reference/compendium_de.md @@ -0,0 +1,57 @@ +# Kompendium der Dogu-V3-Artefakte + +Dieses Kompendium gibt einen Überblick über die Artefakte und APIs von Dogu V3. Eine Einführung in ihr Zusammenspiel finden Sie unter [Dogu-V3-Artefakte verstehen](../concepts/artifacts_de.md). + +## Chart-Artefakte und APIs + +| Artefakt / API | Zweck | Wann benötigt? | Verantwortung | Referenzdokumentation | +| --- | --- | --- | --- | --- | +| Helm-Chart | Führendes Dogu-Paket; enthält Metadaten, Standardwerte, Templates und Begleitdateien | Immer | Dogu-Entwickler:in | [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 | Immer | Dogu-Entwickler:in; konsumiert von Dogu-Tooling | [Helm-`Chart.yaml`](https://helm.sh/docs/topics/charts/#the-chartyaml-file) | +| `values.yaml` | Sichere Standardwerte und öffentliche Konfigurationsschnittstelle | Immer, gemäß Helm-Chart-Konvention | Dogu-Entwickler:in | [Helm-Values](https://helm.sh/docs/chart_template_guide/values_files/) | +| `values.schema.json` | Validiert die zusammengeführten Values | Wenn das Dogu konfigurierbare Werte anbietet | Dogu-Entwickler:in | [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 | Für CES-weite Konfigurationszuordnungen; bei einem konfigurationslosen Dogu optional | Dogu-Entwickler:in; konsumiert vom Dogu Operator | — | +| `templates/` | Rendert Workloads, Services, PVCs, Probes und optionale CES-Integrationsressourcen | Immer | Dogu-Entwickler:in | [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 für die Dogu Registry und Spiegelungswerkzeuge auf beziehungsweise löst sie auf | Wenn das Chart Container-Images referenziert, also normalerweise bei jedem Dogu | Dogu-Entwickler:in; konsumiert von der Dogu Registry und Spiegelungswerkzeugen | — | +| `dogu-upgrade.yaml` | Beschreibt gültige Übergänge zwischen Dogu-Versionen und optionale Parameter zur Upgrade-Koordination | Die akzeptierten ADRs legen noch nicht fest, wann die Datei vorhanden sein muss | Dogu-Entwickler:in; konsumiert vom Dogu Operator | — | +| Container-Images | Stellen die Anwendung sowie referenzierte Sidecar- und Init-Container bereit | Für jeden vom Chart gerenderten Container | Image-Produzent; Referenzen durch Dogu-Entwickler:in | [Kubernetes-Images](https://kubernetes.io/docs/concepts/containers/images/) | +| `AuthRegistration` | Deklariert bei Teilnahme an CES-Authentifizierung die Registrierung | Wenn das Dogu die CES-Authentifizierung nutzt | k8s-auth-registration-lib verantwortet die API; Deklaration durch Dogu-Entwickler:in | [AuthRegistration-v1-API](https://github.com/cloudogu/k8s-auth-registration-lib/tree/develop/api/v1) | +| `Exposition` | Verbindet bei Bedarf einen Chart-Service mit CES-bereitgestelltem externen Zugriff | Wenn das Dogu extern erreichbar sein soll | k8s-exposition-lib verantwortet die API; Deklaration durch Dogu-Entwickler:in | [Exposition-v1-API](https://github.com/cloudogu/k8s-exposition-lib/tree/develop/api/v1) | +| `ServiceAccountRequest` | Fordert bei Bedarf technische Credentials von einem Producer an | Wenn das Dogu technische Credentials eines anderen CES-Dienstes benötigt | k8s-serviceaccount-lib verantwortet die API; Deklaration durch Consumer | [Service-Account-v2-API](https://github.com/cloudogu/k8s-serviceaccount-lib/tree/develop/api/v2) | +| `ServiceAccountProducer` | Deklariert, dass das Dogu technische Accounts anbietet | Wenn das Dogu technische Accounts bereitstellt | k8s-serviceaccount-lib verantwortet die API; Deklaration durch Producer | [Service-Account-v2-API](https://github.com/cloudogu/k8s-serviceaccount-lib/tree/develop/api/v2) | +| `WarpMenuEntry` | Deklariert bei einem sichtbaren CES-Pfad einen Eintrag im gemeinsamen Menü | Wenn das Dogu einen sichtbaren CES-Pfad bereitstellt | k8s-warp-menu-entry-lib verantwortet die API; Deklaration durch Dogu-Entwickler:in | [WarpMenuEntry-v1-API](https://github.com/cloudogu/k8s-warp-menu-entry-lib/tree/develop/api/v1) | +| Dogu-Registry-Daten | Verbinden technische Chart-Metadaten mit außerhalb des Charts gepflegten Berechtigungs-, Marketing- oder Vertriebsdaten | Für Veröffentlichung, Discovery und Berechtigungsprüfung über die Dogu Registry | Cloudogu | — | + +## Vollständige Zuordnung der V2-`dogu.json` + +Die folgende Tabelle führt jedes Feld der V2-`dogu.json` und, soweit vorhanden, sein akzeptiertes V3-Ziel auf. Die Zuordnungen sind keine automatische Konvertierung und erhalten nicht zwangsläufig jedes V2-Verhalten. Wo die akzeptierte Architektur kein allgemeines V3-Ziel definiert, benennt die Tabelle diese Grenze ausdrücklich. + +| V2-Feld | V3-Ziel | Zuordnung und Status | +| --- | --- | --- | +| `Name` | `Chart.yaml` + Registry-Namespace | Chart-`name` ist der einfache technische Name; der qualifizierte Namespace stammt aus dem Registry-Kontext. | +| `Version` | `Chart.yaml` | Wird zur Chart-`version`, der Dogu-Version. `appVersion` bezeichnet getrennt die Anwendung. | +| `PublishedAt` | Dogu-Registry-v3-API | Ist im akzeptierten API-Entwurf als Veröffentlichungsinformation enthalten. Quelle und Pflegeprozess sind noch nicht festgelegt. | +| `DisplayName` | `Chart.yaml` | Dogu-Annotation `dogu.cloudogu.com/display-name`; in den akzeptierten Zielmetadaten optional. | +| `Description` | `Chart.yaml` | Standardfeld `description`; in den akzeptierten Zielmetadaten verpflichtend. | +| `Category` | Kein konkretes V3-Feld festgelegt | Die akzeptierte Architektur behandelt die Kategorie als Katalogmetadatum, definiert aber weder ein `Chart.yaml`-Feld noch eine externe Quelle. Sie ist unabhängig von `WarpMenuEntry`. | +| `Tags` | `Chart.yaml` | Allgemeine Suchbegriffe werden als Helm-`keywords` gepflegt. Menüeinträge werden separat mit `WarpMenuEntry` definiert. | +| `Logo` | `Chart.yaml` | Die URL zum Dogu-Logo wird im Helm-Feld `icon` hinterlegt. | +| `URL` | `Chart.yaml` | Die Projekt- oder Herstellerwebsite wird im Helm-Feld `home` hinterlegt. | +| `Image` | Begleitdatei + Kubernetes-Workloads | Image-Referenzen werden in den Container-Specs definiert. `chart-patch-tpl.yaml` macht sie zusätzlich für Plattformwerkzeuge auffindbar. | +| `ExposedPorts` | Helm/Kubernetes + CES-CR | Kubernetes-Service plus `Exposition`, wenn externer Zugriff benötigt wird. | +| `ExposedCommands` | Entfällt / zweckgebundene V3-Mechanismen | Eine generische V3-`ExposedCommands`-API existiert nicht. Upgrade-Migrationen werden mit Init-Containern oder Helm-Hook-Jobs umgesetzt. Andere Lifecycle- oder benutzerdefinierte Befehle müssen separat betrachtet werden. | +| `Volumes` | Helm-/Kubernetes-Ressourcen | PVCs, Volumes und Volume-Mounts. Backup und Retention separat deklarieren/dokumentieren; keine automatische Feldkonvertierung. | +| `HealthCheck` | Helm-/Kubernetes-Ressourcen | Veralteter einzelner V2-Check. TCP- oder HTTP-Checks werden einer passenden Kubernetes-Probe zugeordnet, wenn das Signal gleichwertig ist; für den V2-Check vom Typ `state` definiert die akzeptierte Architektur kein direktes V3-Äquivalent. | +| `HealthChecks` | Helm-/Kubernetes-Ressourcen | Geeignete Checks werden entsprechend ihrem Zweck als Startup-, Readiness- oder Liveness-Probes modelliert. Dadurch bleiben nicht automatisch jeder V2-Check-Typ und jedes Consumer-Verhalten erhalten. | +| `ServiceAccounts` | CES-CRs | `ServiceAccountRequest` und bei angebotenen Accounts `ServiceAccountProducer`. | +| `Privileged` | Entfällt | Es gibt keinen direkten V3-Ersatz. Das V2-Feld band den Docker-Socket ein; der Kubernetes-Privileged-Modus oder ein Security Context ist kein gleichwertiger Ersatz. Im Chart werden nur die tatsächlich benötigten Pod- und Container-Berechtigungen definiert. | +| `Security` | Helm-/Kubernetes-Ressourcen | Unterstützte Einstellungen werden über Pod- oder Container-Sicherheitskontexte und Capabilities abgebildet. Die akzeptierte Architektur legt keine gemeinsame V3-Sicherheitsbaseline fest. | +| `Configuration` | Chart-Values, Schema und Begleitmetadaten | `values.yaml`, `values.schema.json` und für CES-Zuordnungen `dogu-values-metadata.yaml`. | +| `Properties` | Entfällt | Für das generische V2-Feld gibt es keinen allgemeinen V3-Ersatz. Ein konkretes Helm-, Kubernetes- oder CES-Konzept wird nur verwendet, wenn dessen API das benötigte Verhalten definiert. | +| `EnvironmentVariables` | Helm-/Kubernetes-Ressourcen | Explizite Container-Felder `env` und `envFrom`, je nach Inhalt aus Values, ConfigMaps oder Secrets gespeist. | +| `Dependencies` | Helm-/Kubernetes-Ressourcen oder CES-Service-Account-CRs | Service-Abhängigkeiten werden, soweit passend, mit `ServiceAccountRequest` abgebildet; andere Anforderungen werden explizit im Chart modelliert. Die akzeptierte Architektur definiert keinen generischen Ersatz für sämtliche V2-Client-, Paket- und Versionsprüfungen. | +| `OptionalDependencies` | Optionaler `ServiceAccountRequest` oder zweckgebundene Chart-Ressourcen | Für optionale Service-Account-Abhängigkeiten wird ein optionaler Request verwendet. Die akzeptierte Architektur definiert keinen generischen Vertrag, der sämtliche V2-Semantiken für optionale Abhängigkeiten und Versionsprüfungen erhält. | + +## Zugehöriges Konzept + +Zurück zu [Dogu-V3-Artefakte verstehen](../concepts/artifacts_de.md) oder weiter zur [Multinode-Laufzeitumgebung](../concepts/multinode-environment_de.md). From 4b67e71ddf048da2d91f7e0b432c0953f2c52492 Mon Sep 17 00:00:00 2001 From: Henry Bobka Date: Tue, 21 Jul 2026 14:48:56 +0200 Subject: [PATCH 02/16] #90 Align dogu-json-to-v3 diagram boxes to equal height --- docs/v3/images/dogu-json-to-v3.puml | 8 ++++---- docs/v3/images/dogu-json-to-v3.svg | 2 +- docs/v3/images/dogu-json-to-v3_de.puml | 8 ++++---- docs/v3/images/dogu-json-to-v3_de.svg | 2 +- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/v3/images/dogu-json-to-v3.puml b/docs/v3/images/dogu-json-to-v3.puml index b1c822e..7f00767 100644 --- a/docs/v3/images/dogu-json-to-v3.puml +++ b/docs/v3/images/dogu-json-to-v3.puml @@ -30,8 +30,8 @@ rectangle { rectangle "V2 dogu.json responsibilities" as v2 <> { rectangle "Identity, versions,\ndiscovery metadata" as a <> rectangle "Workloads, ports, storage,\nhealth and security" as b <> - rectangle "Configuration" as c <> - rectangle "CES integrations" as d <> + rectangle "Configuration\n " as c <> + rectangle "CES\nintegrations" as d <> rectangle "Defined catalogue and\npublication data" as e <> rectangle "Fields removed without\nreplacement" as f <> rectangle "Category and other fields without\na general V3 destination" as g <> @@ -48,9 +48,9 @@ rectangle "Dogu V3 destinations" as v3 <> { rectangle "Chart.yaml\nmetadata" as chart <> rectangle "Helm templates →\nKubernetes resources" as helm <> rectangle "Chart values + schema +\ndogu-values-metadata.yaml" as config <> - rectangle "CES custom resources" as ces <> + rectangle "CES custom\nresources" as ces <> rectangle "Chart.yaml + Dogu Registry +\nexternal marketing/sales data" as registry <> - rectangle "Removed" as removed <> + rectangle "Removed\n " as removed <> rectangle "No general V3\ndestination defined" as noGeneral <> noGeneral -[hidden]right-> removed diff --git a/docs/v3/images/dogu-json-to-v3.svg b/docs/v3/images/dogu-json-to-v3.svg index 97ce0ae..55a5d70 100644 --- a/docs/v3/images/dogu-json-to-v3.svg +++ b/docs/v3/images/dogu-json-to-v3.svg @@ -1 +1 @@ -V2 dogu.json responsibilitiesDogu V3 destinationsIdentity, versions,discovery metadataWorkloads, ports, storage,health and securityConfigurationCES integrationsDefined catalogue andpublication dataFields removed withoutreplacementCategory and other fields withouta general V3 destinationChart.yamlmetadataHelm templates →Kubernetes resourcesChart values + schema +dogu-values-metadata.yamlCES custom resourcesChart.yaml + Dogu Registry +external marketing/sales dataRemovedNo general V3destination defined \ No newline at end of file +V2 dogu.json responsibilitiesDogu V3 destinationsIdentity, versions,discovery metadataWorkloads, ports, storage,health and securityConfiguration CESintegrationsDefined catalogue andpublication dataFields removed withoutreplacementCategory and other fields withouta general V3 destinationChart.yamlmetadataHelm templates →Kubernetes resourcesChart values + schema +dogu-values-metadata.yamlCES customresourcesChart.yaml + Dogu Registry +external marketing/sales dataRemoved No general V3destination defined \ No newline at end of file diff --git a/docs/v3/images/dogu-json-to-v3_de.puml b/docs/v3/images/dogu-json-to-v3_de.puml index ac325d4..8064a30 100644 --- a/docs/v3/images/dogu-json-to-v3_de.puml +++ b/docs/v3/images/dogu-json-to-v3_de.puml @@ -30,8 +30,8 @@ rectangle { rectangle "Aufgaben der V2-Datei dogu.json" as v2 <> { rectangle "Identität, Versionen,\nDiscovery-Metadaten" as a <> rectangle "Workloads, Ports, Speicher,\nHealth und Sicherheit" as b <> - rectangle "Konfiguration" as c <> - rectangle "CES-Integrationen" as d <> + rectangle "Konfiguration\n " as c <> + rectangle "CES-\nIntegrationen" as d <> rectangle "Definierte Katalog- und\nVeröffentlichungsdaten" as e <> rectangle "Ersatzlos entfernte\nFelder" as f <> rectangle "Kategorie und andere Felder ohne\nallgemeines V3-Ziel" as g <> @@ -48,9 +48,9 @@ rectangle "Ziele in Dogu V3" as v3 <> { rectangle "Chart.yaml\nMetadaten" as chart <> rectangle "Helm-Templates →\nKubernetes-Ressourcen" as helm <> rectangle "Chart-Values + Schema +\ndogu-values-metadata.yaml" as config <> - rectangle "CES-Custom-Resources" as ces <> + rectangle "CES-Custom-\nResources" as ces <> rectangle "Chart.yaml + Dogu Registry +\nexterne Marketing-/Vertriebsdaten" as registry <> - rectangle "Entfällt" as removed <> + rectangle "Entfällt\n " as removed <> rectangle "Kein allgemeines\nV3-Ziel festgelegt" as noGeneral <> noGeneral -[hidden]right-> removed diff --git a/docs/v3/images/dogu-json-to-v3_de.svg b/docs/v3/images/dogu-json-to-v3_de.svg index 60cae0f..13e0d78 100644 --- a/docs/v3/images/dogu-json-to-v3_de.svg +++ b/docs/v3/images/dogu-json-to-v3_de.svg @@ -1 +1 @@ -Aufgaben der V2-Datei dogu.jsonZiele in Dogu V3Identität, Versionen,Discovery-MetadatenWorkloads, Ports, Speicher,Health und SicherheitKonfigurationCES-IntegrationenDefinierte Katalog- undVeröffentlichungsdatenErsatzlos entfernteFelderKategorie und andere Felder ohneallgemeines V3-ZielChart.yamlMetadatenHelm-Templates →Kubernetes-RessourcenChart-Values + Schema +dogu-values-metadata.yamlCES-Custom-ResourcesChart.yaml + Dogu Registry +externe Marketing-/VertriebsdatenEntfälltKein allgemeinesV3-Ziel festgelegt \ No newline at end of file +Aufgaben der V2-Datei dogu.jsonZiele in Dogu V3Identität, Versionen,Discovery-MetadatenWorkloads, Ports, Speicher,Health und SicherheitKonfiguration CES-IntegrationenDefinierte Katalog- undVeröffentlichungsdatenErsatzlos entfernteFelderKategorie und andere Felder ohneallgemeines V3-ZielChart.yamlMetadatenHelm-Templates →Kubernetes-RessourcenChart-Values + Schema +dogu-values-metadata.yamlCES-Custom-ResourcesChart.yaml + Dogu Registry +externe Marketing-/VertriebsdatenEntfällt Kein allgemeinesV3-Ziel festgelegt \ No newline at end of file From 192697c9811972b16e84c6d47261779e01dac2ef Mon Sep 17 00:00:00 2001 From: Henry Bobka Date: Tue, 21 Jul 2026 15:04:38 +0200 Subject: [PATCH 03/16] #90 Improve Dogu V3 artifacts diagram layout and mapping --- docs/v3/images/artifacts.puml | 59 ++++++++++++++++++-------------- docs/v3/images/artifacts.svg | 2 +- docs/v3/images/artifacts_de.puml | 59 ++++++++++++++++++-------------- docs/v3/images/artifacts_de.svg | 2 +- 4 files changed, 68 insertions(+), 54 deletions(-) diff --git a/docs/v3/images/artifacts.puml b/docs/v3/images/artifacts.puml index 74945ea..402115b 100644 --- a/docs/v3/images/artifacts.puml +++ b/docs/v3/images/artifacts.puml @@ -8,7 +8,7 @@ skinparam rectangleBackgroundColor #23A3DD skinparam rectangleRoundCorner 0 skinparam shadowing false hide stereotype -left to right direction +top to bottom direction -rectangle "Helm chart" as chart <> { - together { - rectangle "Chart.yaml\nidentity + versions" as metadata <> - rectangle "values.yaml\nvalues.schema.json\ndogu-values-\nmetadata.yaml" as config <> - rectangle "Image metadata\nchart-patch-tpl.yaml" as imageMetadata <> - rectangle "Upgrade metadata\ndogu-upgrade.yaml" as upgradeMetadata <> - } - rectangle "templates/" as templates +rectangle "Helm chart — the Dogu V3 package" as chart <> { + rectangle "Chart.yaml\nidentity + discovery metadata" as metadata <> + rectangle "values.yaml\nvalues.schema.json" as config <> + rectangle "dogu-values-metadata.yaml\nCES config mapping" as valuesMeta <> + rectangle "chart-patch-tpl.yaml\ncontainer image references" as imageMeta <> + rectangle "dogu-upgrade.yaml\nupgrade coordination" as upgradeMeta <> + rectangle "templates/\nrender workloads + CES CRs" as templates <> + + metadata -[hidden]right-> config + config -[hidden]right-> valuesMeta + imageMeta -[hidden]right-> upgradeMeta + upgradeMeta -[hidden]right-> templates } -cloud "Referenced\ncontainer images" as images #FCFAF4 -rectangle "Platform tooling\nDogu Registry · ces-mirror" as tooling <> -rectangle "Dogu Operator" as operator <> rectangle "Rendered release resources" as rendered <> { - together { - rectangle "Kubernetes resources\nworkloads · Services · PVCs" as k8s <> - rectangle "CES integration resources\nAuthRegistration · Exposition\nServiceAccountRequest / Producer\nWarpMenuEntry" as ces <> - } + rectangle "Kubernetes resources\nworkloads · Services · PVCs" as k8s <> + rectangle "CES integration resources\nAuthRegistration · Exposition\nServiceAccountRequest / Producer\nWarpMenuEntry" as ces <> + k8s -[hidden]right-> ces } -chart -[hidden]right-> rendered -rendered -[hidden]right-> images -metadata --> templates +rectangle "Dogu Registry\nces-mirror" as registry <> +rectangle "Dogu Operator" as operator <> +cloud "Referenced\ncontainer images" as images #FCFAF4 + config --> templates templates --> k8s templates --> ces -imageMetadata --> tooling -tooling --> images -upgradeMetadata --> operator k8s --> images + +metadata --> registry +imageMeta --> registry +registry --> images + +valuesMeta --> operator +upgradeMeta --> operator @enduml diff --git a/docs/v3/images/artifacts.svg b/docs/v3/images/artifacts.svg index 726b352..4e01dc6 100644 --- a/docs/v3/images/artifacts.svg +++ b/docs/v3/images/artifacts.svg @@ -1 +1 @@ -Helm chartRendered release resourcesReferencedcontainer imagesPlatform toolingDogu Registry · ces-mirrorDogu OperatorChart.yamlidentity + versionsvalues.yamlvalues.schema.jsondogu-values-metadata.yamlImage metadatachart-patch-tpl.yamlUpgrade metadatadogu-upgrade.yamltemplates/Kubernetes resourcesworkloads · Services · PVCsCES integration resourcesAuthRegistration · ExpositionServiceAccountRequest / ProducerWarpMenuEntry \ No newline at end of file +Helm chart — the Dogu V3 packageRendered release resourcesDogu Registryces-mirrorDogu OperatorReferencedcontainer imagesChart.yamlidentity + discovery metadatavalues.yamlvalues.schema.jsondogu-values-metadata.yamlCES config mappingchart-patch-tpl.yamlcontainer image referencesdogu-upgrade.yamlupgrade coordinationtemplates/render workloads + CES CRsKubernetes resourcesworkloads · Services · PVCsCES integration resourcesAuthRegistration · ExpositionServiceAccountRequest / ProducerWarpMenuEntry \ No newline at end of file diff --git a/docs/v3/images/artifacts_de.puml b/docs/v3/images/artifacts_de.puml index 2638eee..7c3cf4a 100644 --- a/docs/v3/images/artifacts_de.puml +++ b/docs/v3/images/artifacts_de.puml @@ -8,7 +8,7 @@ skinparam rectangleBackgroundColor #23A3DD skinparam rectangleRoundCorner 0 skinparam shadowing false hide stereotype -left to right direction +top to bottom direction -rectangle "Helm-Chart" as chart <> { - together { - rectangle "Chart.yaml\nIdentität + Versionen" as metadata <> - rectangle "values.yaml\nvalues.schema.json\ndogu-values-\nmetadata.yaml" as config <> - rectangle "Image-Metadaten\nchart-patch-tpl.yaml" as imageMetadata <> - rectangle "Upgrade-Metadaten\ndogu-upgrade.yaml" as upgradeMetadata <> - } - rectangle "templates/" as templates +rectangle "Helm-Chart — das Dogu-V3-Paket" as chart <> { + rectangle "Chart.yaml\nIdentität + Discovery-Metadaten" as metadata <> + rectangle "values.yaml\nvalues.schema.json" as config <> + rectangle "dogu-values-metadata.yaml\nCES-Konfigurationsmapping" as valuesMeta <> + rectangle "chart-patch-tpl.yaml\nContainer-Image-Referenzen" as imageMeta <> + rectangle "dogu-upgrade.yaml\nUpgrade-Koordination" as upgradeMeta <> + rectangle "templates/\nrendert Workloads + CES-CRs" as templates <> + + metadata -[hidden]right-> config + config -[hidden]right-> valuesMeta + imageMeta -[hidden]right-> upgradeMeta + upgradeMeta -[hidden]right-> templates } -cloud "Referenzierte\nContainer-Images" as images #FCFAF4 -rectangle "Plattformwerkzeuge\nDogu Registry · ces-mirror" as tooling <> -rectangle "Dogu Operator" as operator <> rectangle "Gerenderte Release-Ressourcen" as rendered <> { - together { - rectangle "Kubernetes-Ressourcen\nWorkloads · Services · PVCs" as k8s <> - rectangle "CES-Integrationsressourcen\nAuthRegistration · Exposition\nServiceAccountRequest / Producer\nWarpMenuEntry" as ces <> - } + rectangle "Kubernetes-Ressourcen\nWorkloads · Services · PVCs" as k8s <> + rectangle "CES-Integrationsressourcen\nAuthRegistration · Exposition\nServiceAccountRequest / Producer\nWarpMenuEntry" as ces <> + k8s -[hidden]right-> ces } -chart -[hidden]right-> rendered -rendered -[hidden]right-> images -metadata --> templates +rectangle "Dogu Registry\nces-mirror" as registry <> +rectangle "Dogu Operator" as operator <> +cloud "Referenzierte\nContainer-Images" as images #FCFAF4 + config --> templates templates --> k8s templates --> ces -imageMetadata --> tooling -tooling --> images -upgradeMetadata --> operator k8s --> images + +metadata --> registry +imageMeta --> registry +registry --> images + +valuesMeta --> operator +upgradeMeta --> operator @enduml diff --git a/docs/v3/images/artifacts_de.svg b/docs/v3/images/artifacts_de.svg index 3389e5c..34104dd 100644 --- a/docs/v3/images/artifacts_de.svg +++ b/docs/v3/images/artifacts_de.svg @@ -1 +1 @@ -Helm-ChartGerenderte Release-RessourcenReferenzierteContainer-ImagesPlattformwerkzeugeDogu Registry · ces-mirrorDogu OperatorChart.yamlIdentität + Versionenvalues.yamlvalues.schema.jsondogu-values-metadata.yamlImage-Metadatenchart-patch-tpl.yamlUpgrade-Metadatendogu-upgrade.yamltemplates/Kubernetes-RessourcenWorkloads · Services · PVCsCES-IntegrationsressourcenAuthRegistration · ExpositionServiceAccountRequest / ProducerWarpMenuEntry \ No newline at end of file +Helm-Chart — das Dogu-V3-PaketGerenderte Release-RessourcenDogu Registryces-mirrorDogu OperatorReferenzierteContainer-ImagesChart.yamlIdentität + Discovery-Metadatenvalues.yamlvalues.schema.jsondogu-values-metadata.yamlCES-Konfigurationsmappingchart-patch-tpl.yamlContainer-Image-Referenzendogu-upgrade.yamlUpgrade-Koordinationtemplates/rendert Workloads + CES-CRsKubernetes-RessourcenWorkloads · Services · PVCsCES-IntegrationsressourcenAuthRegistration · ExpositionServiceAccountRequest / ProducerWarpMenuEntry \ No newline at end of file From 5d85ee0077afa2ab1abbdbad7dc8f80b167fba6c Mon Sep 17 00:00:00 2001 From: Nico Franzeck Date: Mon, 3 Aug 2026 15:11:14 +0200 Subject: [PATCH 04/16] Refactor docs: - Describe artifacts in more detail and link them to the corrensponding docs in the crds - Delete charts and replace them with tables - Move specific instructions to best practice --- docs/v3/best-practices/helm-chart_de.md | 20 ++ docs/v3/best-practices/helm-chart_en.md | 20 ++ docs/v3/concepts/artifacts.md | 64 ---- docs/v3/concepts/artifacts_de.md | 273 ++++++++++++++---- docs/v3/concepts/multinode-environment.md | 200 ------------- docs/v3/concepts/multinode-environment_de.md | 200 ------------- docs/v3/images/artifacts.puml | 73 ----- docs/v3/images/artifacts.svg | 1 - docs/v3/images/artifacts_de.puml | 73 ----- docs/v3/images/artifacts_de.svg | 1 - docs/v3/images/dogu-json-to-v3.puml | 71 ----- docs/v3/images/dogu-json-to-v3.svg | 1 - docs/v3/images/dogu-json-to-v3_de.puml | 71 ----- docs/v3/images/dogu-json-to-v3_de.svg | 1 - docs/v3/images/multinode-lifecycle.puml | 47 --- docs/v3/images/multinode-lifecycle.svg | 1 - docs/v3/images/multinode-lifecycle_de.puml | 47 --- docs/v3/images/multinode-lifecycle_de.svg | 1 - docs/v3/images/multinode-request-routing.puml | 45 --- docs/v3/images/multinode-request-routing.svg | 1 - .../images/multinode-request-routing_de.puml | 45 --- .../images/multinode-request-routing_de.svg | 1 - docs/v3/images/multinode-system-context.puml | 75 ----- docs/v3/images/multinode-system-context.svg | 1 - .../images/multinode-system-context_de.puml | 75 ----- .../v3/images/multinode-system-context_de.svg | 1 - 26 files changed, 258 insertions(+), 1151 deletions(-) create mode 100644 docs/v3/best-practices/helm-chart_de.md create mode 100644 docs/v3/best-practices/helm-chart_en.md delete mode 100644 docs/v3/concepts/artifacts.md delete mode 100644 docs/v3/concepts/multinode-environment.md delete mode 100644 docs/v3/concepts/multinode-environment_de.md delete mode 100644 docs/v3/images/artifacts.puml delete mode 100644 docs/v3/images/artifacts.svg delete mode 100644 docs/v3/images/artifacts_de.puml delete mode 100644 docs/v3/images/artifacts_de.svg delete mode 100644 docs/v3/images/dogu-json-to-v3.puml delete mode 100644 docs/v3/images/dogu-json-to-v3.svg delete mode 100644 docs/v3/images/dogu-json-to-v3_de.puml delete mode 100644 docs/v3/images/dogu-json-to-v3_de.svg delete mode 100644 docs/v3/images/multinode-lifecycle.puml delete mode 100644 docs/v3/images/multinode-lifecycle.svg delete mode 100644 docs/v3/images/multinode-lifecycle_de.puml delete mode 100644 docs/v3/images/multinode-lifecycle_de.svg delete mode 100644 docs/v3/images/multinode-request-routing.puml delete mode 100644 docs/v3/images/multinode-request-routing.svg delete mode 100644 docs/v3/images/multinode-request-routing_de.puml delete mode 100644 docs/v3/images/multinode-request-routing_de.svg delete mode 100644 docs/v3/images/multinode-system-context.puml delete mode 100644 docs/v3/images/multinode-system-context.svg delete mode 100644 docs/v3/images/multinode-system-context_de.puml delete mode 100644 docs/v3/images/multinode-system-context_de.svg 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..a951867 --- /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. + +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..875efe0 --- /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. + +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. \ No newline at end of file diff --git a/docs/v3/concepts/artifacts.md b/docs/v3/concepts/artifacts.md deleted file mode 100644 index 41d1259..0000000 --- a/docs/v3/concepts/artifacts.md +++ /dev/null @@ -1,64 +0,0 @@ -# Understand Dogu V3 Artifacts - -A Dogu V3 is a Helm chart. Think of the chart as the package that keeps the Dogu's identity, configuration interface, workload definitions and optional CES integrations together. Container images remain separate artifacts referenced by that package. - -![A Dogu V3 Helm chart containing metadata, configuration, companion files and templates that render Kubernetes and CES resources and reference container images](../images/artifacts.svg) - -## The chart is the leading artifact - -`Chart.yaml` identifies the package. Its `version` is the **Dogu version** and follows the chart lifecycle. `appVersion` is the version of the packaged upstream application; it is informative and can differ. A packaging fix can therefore change `version` without changing `appVersion`. - -The accepted metadata set includes standard Helm fields and Dogu annotations. In particular, `name`, `version`, `appVersion`, `description` and `annotations.dogu.cloudogu.com/api-version` are required by the target architecture. The [artifact compendium](../reference/compendium.md) records the detailed status and contract for each artifact. - -## Configuration belongs to the package - -- `values.yaml` supplies safe defaults and is the chart's configuration interface. -- `values.schema.json` validates the final values accepted by Helm. -- `dogu-values-metadata.yaml` maps CES-wide configuration keys to values when such mappings are needed. It is optional for a Dogu without configurable values. - -These files complement one another: defaults are not validation, and validation is not a CES mapping. Do not put credentials into values. - -## Templates become the running Dogu - -Files below `templates/` render ordinary Kubernetes resources: for example Deployments or StatefulSets, Services, probes, PVCs, ConfigMaps and Secret references. When the application needs a CES capability, the same chart can render the corresponding integration resource: - -- `AuthRegistration` for CES authentication; -- `Exposition` for external access; -- `ServiceAccountRequest` or `ServiceAccountProducer` for technical credentials; and -- `WarpMenuEntry` for a shared-menu entry. - -These declarations describe relationships and intent. Their runtime reconciliation, status and routing details belong to [the Multinode runtime environment](multinode-environment.md). - -## Companion files and images - -In the accepted V3 target architecture, `chart-patch-tpl.yaml` supplies the Dogu Registry and mirroring tools with all container-image references used by the chart. This includes application, sidecar, init-container, dependency and external images. `ces-mirror` uses these references to mirror images and rewrite them for the target registry. - -## How Dogu V3 replaces `dogu.json` - -V3 does not have a project-local `dogu.json`. Its former responsibilities move to standard chart metadata, chart values and schemas, rendered Kubernetes resources, companion files, CES custom resources, or the Dogu Registry API. Some deprecated or generic V2 fields are removed. For other fields, the accepted architecture does not define a general V3 replacement. The artifact compendium explains the destination of every V2 field. - -![V2 dogu.json responsibilities distributed to Chart.yaml, chart values and schemas, CES configuration metadata, Kubernetes resources, CES custom resources, Dogu Registry data, removed fields and fields without a general V3 destination](../images/dogu-json-to-v3.svg) - -The complete field-by-field disposition is in the [artifact compendium](../reference/compendium.md). - -## 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. - -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. - -## Where to continue - -- The [artifact compendium](../reference/compendium.md) explains which artifacts are required, who is responsible for them and where to find their documentation. -- Read [the Multinode runtime environment](multinode-environment.md) for what happens after chart resources are installed. diff --git a/docs/v3/concepts/artifacts_de.md b/docs/v3/concepts/artifacts_de.md index f86172b..fd56189 100644 --- a/docs/v3/concepts/artifacts_de.md +++ b/docs/v3/concepts/artifacts_de.md @@ -1,64 +1,227 @@ -# Dogu-V3-Artefakte verstehen +# 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 +``` + +### `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/` gekenntzeichnet sind. Dieser Prefix kennzeichnet Dogu-Metadaten im Helm-Chart und grenzt sie von allgemeinen Kubernetes- oder Helm-Annotations ab. Folgende plattformspezische 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 plattformspezischen 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 Konfigurationparameter existieren, die nicht immer durch bestehende Werte aus der `values.yaml` eines Helm-Charts abgebildet werden können. So kann für die Plattform bespielsweise ein globales Log-Level gesetzt werden, welches für alle Dogus angewendet wird. Um diesem Umstand Rechnug 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: + # Plattformspezische 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 plattformspezische 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 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:innnen 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 -Ein Dogu V3 ist ein Helm-Chart. Das Chart ist das Paket, das Identität, Konfigurationsschnittstelle, Workload-Definitionen und optionale CES-Integrationen eines Dogus zusammenhält. Container-Images bleiben separate Artefakte, auf die dieses Paket verweist. +Im CES (Cloudogu EcoSystem) ist es möglich, dass verschiedene Dogus miteinander interagieren. Hierfür muss für ein zugreifendes Dogu (Consumer) ein entsprechender ServiceAccount beim Ziel-Dogu (Producer) erstellt werden. -![Ein Dogu-V3-Helm-Chart mit Metadaten, Konfiguration, Begleitdateien und Templates, die Kubernetes- und CES-Ressourcen rendern und Container-Images referenzieren](../images/artifacts_de.svg) +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. -## Das Chart ist das führende Artefakt +**`ServiceAccountProducer`** -`Chart.yaml` identifiziert das Paket. Die `version` ist die **Dogu-Version** und folgt dem Chart-Lebenszyklus. `appVersion` bezeichnet informativ die Version der verpackten Herstelleranwendung und darf abweichen. Eine reine Packaging-Korrektur kann daher `version` ändern, ohne `appVersion` zu ändern. +Bietet ein Dogu eine Schnittstelle an, die von anderen Dogus genutzt werden kann, muss es eine `ServiceAccountProducer-CR` bereitstellen. Die `ServiceAccountProducer` definiert, wie Service-Accounts für das Dogu erstellt werden und welche Parameter unterstützt werden. Ferner beschreibt die CR Werte, die das Dogu - der Producer - nach dem Erstellen eines Service-Accounts zurückgibt. Jeder zurückgegebene Wert wird als Schlüssel in das vom anfragenden Dogu - dem Consumer - referenzierte Secret geschrieben. -Die akzeptierte Metadatenmenge umfasst Helm-Standardfelder und Dogu-Annotationen. Insbesondere sind `name`, `version`, `appVersion`, `description` und `annotations.dogu.cloudogu.com/api-version` in der Zielarchitektur verpflichtend. Das [Artefakt-Kompendium](../reference/compendium_de.md) beschreibt die Aufgabe und Verwendung jedes Artefakts. +**`ServiceAccountRequest`** -## Konfiguration gehört in das Paket +Benötigt ein Dogu einen Service-Account bei einem anderen Dogu, 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 Name der ServiceAccountRequest-Ressource erstellt. Die CR bildet das Gegenstück zum `ServiceAccountProducer`. -- `values.yaml` liefert sichere Standardwerte und ist die Konfigurationsschnittstelle des Charts. -- `values.schema.json` validiert die endgültigen, von Helm angenommenen Values. -- `dogu-values-metadata.yaml` ordnet bei Bedarf CES-weite Konfigurationsschlüssel Chart-Values zu. Für ein Dogu ohne konfigurierbare Werte ist die Datei optional. +## Abgrenzung zu Dogu V2 -Die Dateien ergänzen einander: Standardwerte sind keine Validierung, und Validierung ist keine CES-Zuordnung. Credentials gehören nicht in Values. +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. -## Templates werden zum laufenden Dogu - -Dateien unter `templates/` rendern normale Kubernetes-Ressourcen, beispielsweise Deployments oder StatefulSets, Services, Probes, PVCs, ConfigMaps und Secret-Referenzen. Benötigt die Anwendung eine CES-Funktion, kann dasselbe Chart die passende Integrationsressource rendern: - -- `AuthRegistration` für CES-Authentifizierung, -- `Exposition` für externen Zugriff, -- `ServiceAccountRequest` oder `ServiceAccountProducer` für technische Credentials und -- `WarpMenuEntry` für einen Eintrag im gemeinsamen Menü. - -Diese Deklarationen beschreiben Beziehungen und Absicht. Laufzeit-Reconciliation, Status und Routing-Details erklärt [die Multinode-Laufzeitumgebung](multinode-environment_de.md). - -## Begleitdateien und Images - -In der akzeptierten V3-Zielarchitektur stellt `chart-patch-tpl.yaml` der Dogu Registry und den Spiegelungswerkzeugen alle vom Chart verwendeten Container-Image-Referenzen bereit. Dazu gehören Anwendungs-, Sidecar-, Init-Container-, Abhängigkeits- und externe Images. `ces-mirror` verwendet diese Referenzen, um Images zu spiegeln und für die Ziel-Registry umzuschreiben. - -## Wie Dogu V3 die `dogu.json` ersetzt - -V3 besitzt keine projektlokale `dogu.json`. Deren bisherige Aufgaben wandern in Standard-Chart-Metadaten, Chart-Values und Schemata, gerenderte Kubernetes-Ressourcen, Begleitdateien, CES-Custom-Resources oder die Dogu-Registry-API. Einige veraltete oder generische V2-Felder entfallen. Für andere Felder definiert die akzeptierte Architektur keinen allgemeinen V3-Ersatz. Das Artefakt-Kompendium erklärt das Ziel jedes V2-Feldes. - -![Aufgaben der V2-Datei dogu.json werden auf Chart.yaml, Chart-Values und Schemata, CES-Konfigurationsmetadaten, Kubernetes-Ressourcen, CES-Custom-Resources, Dogu-Registry-Daten, entfallene Felder und Felder ohne allgemeines V3-Ziel verteilt](../images/dogu-json-to-v3_de.svg) - -Die vollständige Zuordnung jedes Feldes enthält das [Artefakt-Kompendium](../reference/compendium_de.md). - -## 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. - -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. - -## So geht es weiter - -- Im [Artefakt-Kompendium](../reference/compendium_de.md) erfahren Sie, welche Artefakte benötigt werden, wer dafür verantwortlich ist und wo die zugehörige Dokumentation zu finden ist. -- Lesen Sie [die Multinode-Laufzeitumgebung](multinode-environment_de.md), um zu verstehen, was nach der Installation der Chart-Ressourcen geschieht. +| 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/multinode-environment.md b/docs/v3/concepts/multinode-environment.md deleted file mode 100644 index 6dae8eb..0000000 --- a/docs/v3/concepts/multinode-environment.md +++ /dev/null @@ -1,200 +0,0 @@ -# Understand the Multinode Runtime Environment - -A Dogu V3 is delivered as a Helm chart and runs as a namespaced application in a Multinode Cloudogu EcoSystem (CES). The chart describes the application workloads and may opt into CES capabilities through Kubernetes custom resources. - -This page explains the resulting responsibilities and interactions. It is not a general Kubernetes or Helm tutorial. - -## The mental model - -![System context of a Dogu V3](../images/multinode-system-context.svg) - -The responsibilities are deliberately split: - -| Area | Dogu chart | CES platform | -| --- | --- | --- | -| Application | Defines Deployments, StatefulSets, Jobs, containers, probes and internal Services | Schedules and runs the resulting Kubernetes resources | -| Lifecycle | Supplies chart metadata, defaults, validation and optional migration logic | Resolves the chart, validates the requested transition and reconciles the Helm release | -| Configuration | Defines supported values, safe defaults and a schema | Supplies instance-specific values through the Dogu resource | -| Persistent data | Defines PVCs and volume mounts needed by the application | Provides the configured StorageClasses and binds volumes | -| External access | Defines a Service and, when needed, an `Exposition` | Reconciles gateway routes and external ports | -| Authentication | Defines an `AuthRegistration` and consumes its credential Secret | Registers the client with the identity provider and publishes credentials | -| Technical access to another CES service | Defines a `ServiceAccountRequest` to request access or a `ServiceAccountProducer` to offer access | Mediates credential creation and stores credentials in a Secret | -| Warp Menu | Defines zero or more `WarpMenuEntry` resources for internal application pages | Validates the entries and renders the shared menu | - -The chart remains responsible for making the application work. CES controllers provide integrations; they do not infer missing application configuration from a container image. - -## Namespace and Kubernetes context - -A Dogu and its namespaced resources are installed together in the namespace selected by the CES. A chart must therefore be namespace-independent: - -- use `.Release.Namespace` rather than hard-coding `ecosystem` or another namespace; -- derive names from `.Release.Name` and chart helper templates instead of assuming a fixed Helm release name; -- reference Services, ConfigMaps, Secrets and custom resources within the release namespace unless a documented API explicitly states otherwise; and -- never derive application behavior from a developer's local `kubectl` context. - -When diagnosing a cluster, first verify the context and always make the namespace explicit: - -```shell -kubectl config current-context -kubectl get dogu -A -kubectl -n get pods,services,pvc -``` - -The Dogu Registry namespace in a name such as `official/my-dogu`, the OCI repository path and the Kubernetes runtime namespace are different concepts. Do not use one as a substitute for another. - -## Helm release and Dogu lifecycle - -The Dogu custom resource represents the platform's desired state. In a Blueprint-managed CES, change the Blueprint; the Blueprint Operator owns the derived Dogu resource. Modify a Dogu resource directly only when the deployment procedure explicitly identifies it as the source of truth. Do not modify the generated Helm release directly. - -![Dogu V3 reconciliation and lifecycle](../images/multinode-lifecycle.svg) - -The intended flow is: - -1. A Dogu resource requests a specific Dogu/chart version. -2. The Dogu Operator resolves and validates the chart and its metadata. -3. Helm validates the merged values and installs or upgrades the release. -4. Kubernetes starts the chart workloads. -5. CES controllers reconcile integration resources independently. -6. The status fields on the Dogu and integration resources report progress or failure. - -Reconciliation is continuous. A successful `helm template` or resource creation does not mean that the Dogu is ready. Workloads, PVCs and every required integration must also become ready. - -### Upgrades - -The Dogu version is the chart `version`; `appVersion` records the packaged application's version. The two versions may differ. In the accepted target architecture, `dogu-upgrade.yaml` describes valid transitions between Dogu/chart versions and the parameters that the Dogu Operator needs to coordinate an upgrade. A chart can supply migration logic through Kubernetes-native mechanisms such as init containers or Helm hook Jobs. Migration logic must be: - -- safe to retry after a Pod or controller restart or when a Job runs again; -- explicit about the source and target Dogu/chart versions and relevant application versions; -- compatible with the chart's volume access modes; -- observable through useful Job logs and workload status. - -The Dogu Operator must coordinate values and workload scaling when migration containers or hook Jobs need existing workloads or `ReadWriteOnce` volumes. A chart may implement migrations with init containers or Jobs started by Helm upgrade hooks. `dogu-upgrade.yaml` is the platform-level contract for valid version transitions; hook annotations alone do not replace that contract. The platform does not automatically execute V2 `pre-upgrade.sh` or `post-upgrade.sh` scripts. - -### Reconciliation and status - -Inspect status before inspecting controller internals: - -```shell -kubectl -n get dogu -o yaml -kubectl -n get exposition,authregistration,serviceaccountrequest,warpmenuentry -kubectl -n describe -``` - -The APIs do not share a common readiness condition. Check their API-specific success conditions: - -- Exposition: `Valid`, `IngressesReady`, `NetworkPolicyReady`, `IngressTCPRoutesCreated`, `IngressUDPRoutesCreated` and `LoadBalancerPortsAllocated` as applicable; -- AuthRegistration: `Completed` and `CredentialsPublished`; -- ServiceAccountRequest: `ServiceAccountReady`; and -- WarpMenuEntry: `Ready` and `Visible`. - -Use `metadata.generation` and the condition fields `status`, `reason`, `message` and `observedGeneration` where supported by the API. A resource that exists but does not report its API-specific success conditions is not successfully integrated yet. - -## Configuration - -Treat `values.yaml` as the chart's public configuration interface: - -1. provide safe defaults so a normal installation needs few overrides; -2. document values that partners or instance operators are expected to change; -3. validate the final value structure with `values.schema.json`; and -4. use `dogu-values-metadata.yaml` for CES-wide mapped settings such as the root log level when required by the V3 contract. - -Instance-specific overrides are supplied through the Dogu resource and merged by the platform. In a Blueprint-managed CES, define these overrides in the Blueprint instead of editing the derived Dogu resource. Do not require operators to patch Deployments, StatefulSets or Helm release Secrets after installation; reconciliation can overwrite those changes. - -Passwords, tokens and private keys must not be committed to `values.yaml` or rendered into ConfigMaps. Consume a namespaced Kubernetes Secret or a credential Secret produced by a CES integration controller. The V3 architecture does not currently define one generic sensitive-values mechanism, so document each Secret contract in the chart. - -## Storage and PVCs - -V3 charts define their own Kubernetes PVCs and volume mounts. Unlike V2, a Dogu can use multiple volumes, for example, separate volumes for the application and database. - -Document for each PVC: - -- what data it contains, -- which workload uses it, -- the required access mode, -- the default size and -- whether `storageClassName` is configurable. - -Do not hard-code a cluster-specific StorageClass. Define, document and test the retention behavior for persistent data when the Dogu is uninstalled. - -## Service exposition and request routing - -An application stays cluster-internal until the chart declares external access. Create a normal Kubernetes Service for the target workload and one or more [`Exposition`](https://github.com/cloudogu/k8s-exposition-lib) resources containing the required HTTP, TCP or UDP routes. Do not create a platform Ingress or Traefik resource directly. - -![Request routing from a client to a Dogu](../images/multinode-request-routing.svg) - -For HTTP routes, the Exposition identifies the target Service and port, the CES-relative path and an optional path rewrite. Design applications to work below a path such as `/my-dogu`; do not assume they run at `/`. Use TCP or UDP routes only when the application protocol cannot run through the HTTP gateway. Requested external ports can conflict; inspect `LoadBalancerPortsAllocated` and its reason to determine whether allocation succeeded. - -The service-discovery controller owns the generated gateway resources. Helm tracks the Service and Exposition rendered by the Dogu chart; the chart must not patch the generated routes. - -## Identity provider and authentication - -To participate in CES single sign-on, declare an [`AuthRegistration`](https://github.com/cloudogu/k8s-auth-registration-lib) (`k8s.cloudogu.com/v1`). It specifies the protocol (`CAS`, `OIDC` or `OAUTH`), the consumer, and any optional logout URL and parameters. - -The authentication controller registers the client and publishes credentials to a Secret. Mount or read that Secret in the application; never duplicate the credentials in chart values. Read `status.resolvedSecretRef` and the `Completed` and `CredentialsPublished` conditions when troubleshooting. - -An AuthRegistration only provisions the client-side integration. The application must still implement the selected authentication protocol, construct CES-path-aware callback and logout URLs, and handle unavailable or rotated credentials. - -## Two types of service account - -### Kubernetes workload ServiceAccount - -A Kubernetes `ServiceAccount` provides a Pod with an identity for Kubernetes API access. If the application requires this access, configure a namespaced ServiceAccount, set `serviceAccountName` on the workload and grant only the required Role permissions. Use cluster-wide RBAC only when explicitly required. - -### CES service-account credentials - -A [`ServiceAccountRequest`](https://github.com/cloudogu/k8s-serviceaccount-lib) (`k8s.cloudogu.com/v2`) requests technical credentials from another Dogu or component. The Service Account Operator provides them in a managed Secret. - -The consuming application and its chart must: - -- follow the producer's documented parameter and Secret-key contract; -- mount the credential Secret with `optional: true` when `ServiceAccountRequest.spec.optional` is `true`; -- ensure that the application reloads rotated credentials or restart the workload; and -- leave the managed Secret unchanged. - -A Dogu that offers accounts must declare a `ServiceAccountProducer` and implement its configured producer strategy. The HTTP strategy is typically exposed through an adapter such as the [service-account-producer sidecar](https://github.com/cloudogu/service-account-producer-sidecar). Consult the [`ServiceAccountProducer` API](https://github.com/cloudogu/k8s-serviceaccount-lib/tree/develop/api/v2) for the complete contract. Containers in the same Dogu normally do not need this CES-wide mechanism. Inspect `ServiceAccountReady` when credentials are unavailable. - -## Warp Menu - -Declare a [`WarpMenuEntry`](https://github.com/cloudogu/k8s-warp-menu-entry-lib) (`k8s.cloudogu.com/v1`) for each internal user-facing entry point. A Dogu may define zero or more entries. - -Each entry supplies German and English display names, a category key and a CES-relative path. External URLs are not allowed in `WarpMenuEntry` resources; the platform manages them centrally. Set `disabled: true` to retain a declaration without rendering it. Use the `Ready` and `Visible` status conditions to diagnose an entry that does not appear. - -The Warp Menu does not expose the application. Its path must correspond to an independently working HTTP Exposition. - -## Labels and selectors - -Use the recommended Kubernetes application labels consistently on the chart resources: - -```yaml -app.kubernetes.io/name: -app.kubernetes.io/instance: -app.kubernetes.io/version: -app.kubernetes.io/managed-by: -helm.sh/chart: - -``` - -Use only stable identity labels such as `app.kubernetes.io/name` and `app.kubernetes.io/instance` in workload selectors. Version and chart labels must not be part of a selector because their values change during upgrades. - -Do not use general labels such as `app: ces` to select resources belonging to a specific Dogu. Add Dogu-specific labels only when required by a documented CES contract. - -## Resource ownership - -Every resource should have one clear manager: - -- Define application resources and CES integration custom resources in the chart. Helm manages these resources. -- Integration controllers manage the resources they generate, such as gateway routes or credential Secrets. Do not include these generated resources in the chart or modify them manually. -- Adopt existing Secrets or PVCs only through a documented procedure. - -Document and test the deletion behavior of persistent or externally managed resources. - -## Pre-release checklist - -Use this checklist before handing over a chart and when testing it in a partner CES: - -- [ ] The chart renders with any release name and namespace, and `values.schema.json` validates its values. -- [ ] Workloads define probes, resource requests and limits, and stable selectors. -- [ ] Storage and uninstall behavior is documented and tested. -- [ ] External paths use Exposition resources, and Warp Menu paths work. -- [ ] Authentication and technical-account credentials are consumed from Secrets without being exposed. -- [ ] Every CES integration used by the Dogu reports a successful status. -- [ ] Installation, upgrades, reconciliation after configuration changes and uninstallation are tested against the targeted CES release. diff --git a/docs/v3/concepts/multinode-environment_de.md b/docs/v3/concepts/multinode-environment_de.md deleted file mode 100644 index a20093a..0000000 --- a/docs/v3/concepts/multinode-environment_de.md +++ /dev/null @@ -1,200 +0,0 @@ -# Die Multinode-Laufzeitumgebung verstehen - -Ein Dogu V3 wird als Helm-Chart ausgeliefert und läuft als namensraumgebundene Anwendung in einem Multinode Cloudogu EcoSystem (CES). Das Chart beschreibt die Anwendungs-Workloads und kann über Kubernetes-Custom-Resources gezielt CES-Funktionen nutzen. - -Diese Seite erklärt die daraus entstehenden Verantwortlichkeiten und Interaktionen. Sie ist keine allgemeine Kubernetes- oder Helm-Einführung. - -## Das mentale Modell - -![Systemkontext eines Dogu V3](../images/multinode-system-context_de.svg) - -Die Verantwortlichkeiten sind bewusst getrennt: - -| Bereich | Dogu-Chart | CES-Plattform | -| --- | --- | --- | -| Anwendung | Definiert Deployments, StatefulSets, Jobs, Container, Probes und interne Services | Plant und betreibt die resultierenden Kubernetes-Ressourcen | -| Lebenszyklus | Liefert Chart-Metadaten, Standardwerte, Validierung und optionale Migrationslogik | Ermittelt das Chart, validiert den gewünschten Übergang und gleicht das Helm-Release mit dem Sollzustand ab | -| Konfiguration | Definiert unterstützte Values, sichere Standardwerte und ein Schema | Liefert instanzspezifische Values über die Dogu-Ressource | -| Persistente Daten | Definiert die benötigten PVCs und Volume-Mounts | Stellt konfigurierte StorageClasses bereit und bindet Volumes | -| Externer Zugriff | Definiert einen Service und bei Bedarf eine `Exposition` | Gleicht Gateway-Routen und externe Ports mit dem Sollzustand ab | -| Authentifizierung | Definiert eine `AuthRegistration` und verwendet deren Credential-Secret | Registriert den Client beim Identity Provider und veröffentlicht Credentials | -| Technischer Zugriff auf einen anderen CES-Dienst | Definiert einen `ServiceAccountRequest` oder beim Anbieten eines Zugangs einen `ServiceAccountProducer` | Vermittelt die Credential-Erzeugung und speichert Credentials in einem Secret | -| Warp-Menü | Definiert null oder mehrere `WarpMenuEntry`-Ressourcen für interne Anwendungsseiten | Validiert die Einträge und rendert das gemeinsame Menü | - -Das Chart bleibt dafür verantwortlich, dass die Anwendung funktioniert. CES-Controller stellen Integrationen bereit; sie leiten keine fehlende Anwendungskonfiguration aus einem Container-Image ab. - -## Namespace und Kubernetes-Kontext - -Ein Dogu und seine namensraumgebundenen Ressourcen werden gemeinsam in dem vom CES gewählten Namespace installiert. Ein Chart muss deshalb unabhängig vom konkreten Namespace sein: - -- Verwenden Sie `.Release.Namespace`, statt `ecosystem` oder einen anderen Namespace fest einzutragen. -- Leiten Sie Namen aus `.Release.Name` und Chart-Helper-Templates ab, statt einen festen Helm-Release-Namen anzunehmen. -- Referenzieren Sie Services, ConfigMaps, Secrets und Custom Resources innerhalb des Namespace des Releases, sofern eine dokumentierte API nichts anderes vorgibt. -- Leiten Sie Anwendungsverhalten niemals aus dem lokalen `kubectl`-Kontext einer entwickelnden Person ab. - -Prüfen Sie bei der Diagnose eines Clusters zuerst den Kontext und geben Sie den Namespace immer explizit an: - -```shell -kubectl config current-context -kubectl get dogu -A -kubectl -n get pods,services,pvc -``` - -Der Dogu-Registry-Namespace in einem Namen wie `official/my-dogu`, der OCI-Repository-Pfad und der Kubernetes-Laufzeit-Namespace sind unterschiedliche Konzepte. Keines davon darf als Ersatz für ein anderes verwendet werden. - -## Helm-Release und Dogu-Lebenszyklus - -Die Dogu-Custom-Resource beschreibt den Sollzustand aus Sicht der Plattform. In einem Blueprint-verwalteten CES ändern Administrator:innen den Blueprint; der Blueprint-Operator verwaltet die daraus abgeleitete Dogu-Ressource. Verändern Sie eine Dogu-Ressource nur dann direkt, wenn das Bereitstellungsverfahren sie ausdrücklich als führende Konfigurationsquelle ausweist. Verändern Sie das erzeugte Helm-Release nicht direkt. - -![Reconciliation und Lebenszyklus eines Dogu V3](../images/multinode-lifecycle_de.svg) - -Der vorgesehene Ablauf ist: - -1. Eine Dogu-Ressource fordert ein Dogu und eine Chart-Version an. -2. Der Dogu Operator ermittelt und validiert das Chart und seine Metadaten. -3. Helm validiert die zusammengeführten Values und installiert oder aktualisiert das Release. -4. Kubernetes startet die Workloads aus dem Chart. -5. CES-Controller gleichen die Integrationsressourcen unabhängig voneinander mit dem Sollzustand ab. -6. Statusinformationen an der Dogu-Ressource und den Integrationsressourcen melden Fortschritt oder Fehler. - -Reconciliation läuft kontinuierlich. Ein erfolgreiches `helm template` oder die bloße Existenz einer Ressource bedeuten noch nicht, dass das Dogu bereit ist. Auch die Workloads, PVCs und alle benötigten Integrationen müssen betriebsbereit sein. - -### Upgrades - -Die Dogu-Version entspricht der Chart-`version`; `appVersion` enthält die Version der verpackten Anwendung. Beide Versionen dürfen voneinander abweichen. In der akzeptierten Zielarchitektur beschreibt `dogu-upgrade.yaml` gültige Übergänge zwischen Dogu-/Chart-Versionen und Parameter, die der Dogu Operator zur Koordination eines Upgrades benötigt. Ein Chart kann Migrationslogik durch Kubernetes-native Mechanismen wie Init-Container oder Helm-Hook-Jobs bereitstellen. Migrationslogik muss: - -- nach einem Pod- oder Controller-Neustart oder einer erneuten Job-Ausführung sicher wiederholbar sein, -- Quell- und Zielversion des Dogus/Charts sowie relevante Anwendungsversionen explizit berücksichtigen, -- mit den Volume-Access-Modes des Charts kompatibel sein, -- durch aussagekräftige Job-Logs und Workload-Status beobachtbar sein. - -Der Dogu Operator muss Values und die Skalierung der Workloads koordinieren, wenn Migrationscontainer oder Hook-Jobs auf bestehende Workloads oder `ReadWriteOnce`-Volumes zugreifen. Ein Chart kann Migrationen mit Init-Containern oder durch Helm-Upgrade-Hooks gestarteten Jobs umsetzen. `dogu-upgrade.yaml` bildet den plattformweiten Vertrag für gültige Versionsübergänge; Hook-Annotationen allein ersetzen diesen Vertrag nicht. Die Plattform führt V2-`pre-upgrade.sh`- oder `post-upgrade.sh`-Skripte nicht automatisch aus. - -### Reconciliation und Status - -Prüfen Sie zuerst den Status, bevor Sie Controller-interne Details untersuchen: - -```shell -kubectl -n get dogu -o yaml -kubectl -n get exposition,authregistration,serviceaccountrequest,warpmenuentry -kubectl -n describe -``` - -Die APIs verwenden keine gemeinsame Readiness-Condition. Prüfen Sie ihre API-spezifischen Erfolgsbedingungen: - -- Exposition: je nach Nutzung `Valid`, `IngressesReady`, `NetworkPolicyReady`, `IngressTCPRoutesCreated`, `IngressUDPRoutesCreated` und `LoadBalancerPortsAllocated`, -- AuthRegistration: `Completed` und `CredentialsPublished`, -- ServiceAccountRequest: `ServiceAccountReady` und -- WarpMenuEntry: `Ready` und `Visible`. - -Verwenden Sie `metadata.generation` sowie die Condition-Felder `status`, `reason`, `message` und `observedGeneration`, sofern die API das jeweilige Feld bereitstellt. Eine vorhandene Ressource ohne ihre API-spezifischen Erfolgsbedingungen ist noch nicht erfolgreich integriert. - -## Konfiguration - -Behandeln Sie die `values.yaml` als öffentliche Konfigurationsschnittstelle des Charts: - -1. Stellen Sie sichere Standardwerte bereit, sodass für eine normale Installation nur wenige Values überschrieben werden müssen. -2. Dokumentieren Sie Values, die Partner oder Instanzbetreiber:innen ändern sollen. -3. Validieren Sie die Struktur der endgültigen Values mit `values.schema.json`. -4. Verwenden Sie `dogu-values-metadata.yaml` für CES-weit abgebildete Einstellungen wie den Root-Loglevel, wenn der V3-Vertrag dies verlangt. - -Instanzspezifische Overrides werden über die Dogu-Ressource geliefert und durch die Plattform zusammengeführt. Definieren Sie diese Overrides in einem Blueprint-verwalteten CES im Blueprint, statt die abgeleitete Dogu-Ressource zu verändern. Verlangen Sie nicht, dass Betreiber:innen nach der Installation Deployments, StatefulSets oder Helm-Release-Secrets patchen; Reconciliation kann solche Änderungen überschreiben. - -Passwörter, Token und private Schlüssel dürfen weder in `values.yaml` eingecheckt noch in ConfigMaps ausgegeben werden. Verwenden Sie ein namensraumgebundenes Kubernetes-Secret oder ein Credential-Secret eines CES-Integrationscontrollers. Die V3-Architektur definiert aktuell keinen einheitlichen Mechanismus für vertrauliche Values; dokumentieren Sie deshalb jeden Secret-Vertrag im Chart. - -## Storage und PVCs - -V3-Charts definieren die benötigten Kubernetes-PVCs und Volume-Mounts selbst. Anders als bei V2 kann ein Dogu mehrere Volumes verwenden, beispielsweise getrennt für Anwendung und Datenbank. - -Dokumentieren Sie für jeden PVC: - -- welche Daten er enthält, -- welcher Workload ihn verwendet, -- den benötigten Zugriffsmodus, -- die Standardgröße und -- ob `storageClassName` konfigurierbar ist. - -Tragen Sie keine clusterspezifische StorageClass fest ein. Legen Sie fest und testen Sie, ob persistente Daten bei einer Deinstallation erhalten bleiben sollen. - -## Service-Exposition und Request-Routing - -Eine Anwendung bleibt clusterintern, bis das Chart externen Zugriff deklariert. Erstellen Sie einen normalen Kubernetes-Service für den Ziel-Workload und eine oder mehrere [`Exposition`](https://github.com/cloudogu/k8s-exposition-lib)-Ressourcen mit den benötigten HTTP-, TCP- oder UDP-Routen. Erstellen Sie keine plattformspezifischen Ingress- oder Traefik-Ressourcen direkt. - -![Request-Routing von einem Client zu einem Dogu](../images/multinode-request-routing_de.svg) - -Bei HTTP-Routen bezeichnet die Exposition den Ziel-Service und -Port, den CES-relativen Pfad und ein optionales Path-Rewrite. Anwendungen müssen unter einem Pfad wie `/my-dogu` funktionieren; sie dürfen nicht voraussetzen, unter `/` zu laufen. Verwenden Sie TCP- oder UDP-Routen nur, wenn das Anwendungsprotokoll nicht über das HTTP-Gateway laufen kann. Angeforderte externe Ports können kollidieren; `LoadBalancerPortsAllocated` und dessen Begründung zeigen, ob die Zuweisung erfolgreich war. - -Der Service-Discovery-Controller besitzt die erzeugten Gateway-Ressourcen. Helm verwaltet den vom Dogu-Chart erzeugten Service und die `Exposition`; das Chart darf die erzeugten Routen nicht verändern. - -## Identity Provider und Authentifizierung - -Um am CES-Single-Sign-on teilzunehmen, deklarieren Sie eine [`AuthRegistration`](https://github.com/cloudogu/k8s-auth-registration-lib) (`k8s.cloudogu.com/v1`). Sie enthält das Protokoll (`CAS`, `OIDC` oder `OAUTH`), den Consumer sowie optional Logout-URL und Parameter. - -Der Authentifizierungscontroller registriert den Client und veröffentlicht Credentials in einem Secret. Mounten oder lesen Sie dieses Secret in der Anwendung; duplizieren Sie die Credentials niemals in Chart-Values. Zur Fehleranalyse dienen `status.resolvedSecretRef` sowie die Conditions `Completed` und `CredentialsPublished`. - -Eine AuthRegistration provisioniert nur die clientseitige Integration. Die Anwendung muss das ausgewählte Authentifizierungsprotokoll weiterhin selbst implementieren, mit CES-Pfaden kompatible Callback- und Logout-URLs bilden und mit nicht verfügbaren oder rotierten Credentials umgehen. - -## Zwei Arten von Service-Accounts - -### Kubernetes-Workload-ServiceAccount - -Ein Kubernetes-`ServiceAccount` stellt einem Pod eine Identität für den Zugriff auf die Kubernetes-API bereit. Wenn die Anwendung diesen Zugriff benötigt, konfigurieren Sie einen namensraumgebundenen ServiceAccount, setzen Sie `serviceAccountName` im Workload und gewähren Sie über eine Role nur die erforderlichen Rechte. Verwenden Sie clusterweite RBAC nur, wenn sie ausdrücklich erforderlich ist. - -### CES-Service-Account-Credentials - -Ein [`ServiceAccountRequest`](https://github.com/cloudogu/k8s-serviceaccount-lib) (`k8s.cloudogu.com/v2`) fordert technische Credentials eines anderen Dogus oder einer Komponente an. Der Service Account Operator stellt sie in einem verwalteten Secret bereit. - -Die konsumierende Anwendung und ihr Chart müssen: - -- den dokumentierten Parameter- und Secret-Key-Vertrag des Producers einhalten, -- das Credential-Secret mit `optional: true` einbinden, wenn `ServiceAccountRequest.spec.optional` den Wert `true` hat, -- sicherstellen, dass die Anwendung rotierte Credentials neu lädt, oder den Workload neu starten und -- das verwaltete Secret unverändert lassen. - -Ein Dogu, das Accounts anbietet, muss einen `ServiceAccountProducer` deklarieren und die darin konfigurierte Producer-Strategie implementieren. Die HTTP-Strategie wird üblicherweise über einen Adapter wie den [service-account-producer-Sidecar](https://github.com/cloudogu/service-account-producer-sidecar) bereitgestellt. Den vollständigen Vertrag beschreibt die [`ServiceAccountProducer`-API](https://github.com/cloudogu/k8s-serviceaccount-lib/tree/develop/api/v2). Container desselben Dogus benötigen diesen CES-weiten Mechanismus normalerweise nicht. Wenn Credentials fehlen, prüfen Sie `ServiceAccountReady`. - -## Warp-Menü - -Deklarieren Sie einen [`WarpMenuEntry`](https://github.com/cloudogu/k8s-warp-menu-entry-lib) (`k8s.cloudogu.com/v1`) für jeden internen, für Benutzer:innen sichtbaren Einstiegspunkt. Je nach Bedarf kann ein Dogu keinen, einen oder mehrere Einträge definieren. - -Jeder Eintrag enthält je einen deutschen und einen englischen Anzeigenamen, einen Kategorie-Key und einen CES-relativen Pfad. Externe URLs sind in `WarpMenuEntry`-Ressourcen nicht erlaubt; die Plattform verwaltet sie zentral. Mit `disabled: true` bleibt eine Deklaration erhalten, ohne angezeigt zu werden. Die Status-Conditions `Ready` und `Visible` helfen bei der Diagnose eines fehlenden Eintrags. - -Das Warp-Menü macht die Anwendung nicht erreichbar. Sein Pfad muss zu einer unabhängig funktionierenden HTTP-Exposition passen. - -## Labels und Selektoren - -Verwenden Sie die empfohlenen Kubernetes-App-Labels konsistent auf den Ressourcen des Charts: - -```yaml -app.kubernetes.io/name: -app.kubernetes.io/instance: -app.kubernetes.io/version: -app.kubernetes.io/managed-by: -helm.sh/chart: - -``` - -Verwenden Sie für Workload-Selektoren nur stabile Identitätslabels wie `app.kubernetes.io/name` und `app.kubernetes.io/instance`. Versions- und Chart-Labels dürfen nicht Teil eines Selektors sein, da sich ihre Werte bei einem Upgrade ändern. - -Verwenden Sie keine allgemeinen Labels wie `app: ces`, um Ressourcen eines bestimmten Dogus auszuwählen. Fügen Sie Dogu-spezifische Labels nur hinzu, wenn ein dokumentierter CES-Vertrag dies verlangt. - -## Ressourcenverantwortung - -Jede Ressource sollte von genau einer Stelle verwaltet werden: - -- Definieren Sie Anwendungs- und CES-Integrationsressourcen im Chart. Helm verwaltet diese Ressourcen. -- Integrationscontroller verwalten die von ihnen erzeugten Ressourcen, beispielsweise Gateway-Routen oder Credential-Secrets. Nehmen Sie diese erzeugten Ressourcen nicht in das Chart auf und verändern Sie sie nicht manuell. -- Übernehmen Sie bestehende Secrets oder PVCs nur mit einem dokumentierten Verfahren. - -Dokumentieren und testen Sie das Löschverhalten persistenter oder extern verwalteter Ressourcen. - -## Checkliste vor einem Release - -Verwenden Sie diese Checkliste vor der Übergabe eines Charts und bei Tests in einem Partner-CES: - -- [ ] Das Chart rendert mit beliebigen Release-Namen und Namespaces und `values.schema.json` validiert seine Values. -- [ ] Workloads definieren Probes, Resource-Requests und -Limits sowie stabile Selektoren. -- [ ] Storage- und Deinstallationsverhalten sind dokumentiert und getestet. -- [ ] Für externe Pfade werden `Exposition`-Ressourcen verwendet, und die Pfade der Warp-Menü-Einträge funktionieren. -- [ ] Credentials für die Authentifizierung und technische Accounts werden Secrets entnommen, ohne offengelegt zu werden. -- [ ] Jede vom Dogu verwendete CES-Integration meldet einen erfolgreichen Status. -- [ ] Installation, Upgrades, Reconciliation nach Konfigurationsänderungen und Deinstallation sind gegen die vorgesehene CES-Version getestet. diff --git a/docs/v3/images/artifacts.puml b/docs/v3/images/artifacts.puml deleted file mode 100644 index 402115b..0000000 --- a/docs/v3/images/artifacts.puml +++ /dev/null @@ -1,73 +0,0 @@ -@startuml -!pragma layout smetana -skinparam backgroundColor white -skinparam defaultFontColor #392A25 -skinparam ArrowColor #00426B -skinparam rectangleBorderColor #1978A3 -skinparam rectangleBackgroundColor #23A3DD -skinparam rectangleRoundCorner 0 -skinparam shadowing false -hide stereotype -top to bottom direction - - - -rectangle "Helm chart — the Dogu V3 package" as chart <> { - rectangle "Chart.yaml\nidentity + discovery metadata" as metadata <> - rectangle "values.yaml\nvalues.schema.json" as config <> - rectangle "dogu-values-metadata.yaml\nCES config mapping" as valuesMeta <> - rectangle "chart-patch-tpl.yaml\ncontainer image references" as imageMeta <> - rectangle "dogu-upgrade.yaml\nupgrade coordination" as upgradeMeta <> - rectangle "templates/\nrender workloads + CES CRs" as templates <> - - metadata -[hidden]right-> config - config -[hidden]right-> valuesMeta - imageMeta -[hidden]right-> upgradeMeta - upgradeMeta -[hidden]right-> templates -} - -rectangle "Rendered release resources" as rendered <> { - rectangle "Kubernetes resources\nworkloads · Services · PVCs" as k8s <> - rectangle "CES integration resources\nAuthRegistration · Exposition\nServiceAccountRequest / Producer\nWarpMenuEntry" as ces <> - k8s -[hidden]right-> ces -} - -rectangle "Dogu Registry\nces-mirror" as registry <> -rectangle "Dogu Operator" as operator <> -cloud "Referenced\ncontainer images" as images #FCFAF4 - -config --> templates -templates --> k8s -templates --> ces -k8s --> images - -metadata --> registry -imageMeta --> registry -registry --> images - -valuesMeta --> operator -upgradeMeta --> operator -@enduml diff --git a/docs/v3/images/artifacts.svg b/docs/v3/images/artifacts.svg deleted file mode 100644 index 4e01dc6..0000000 --- a/docs/v3/images/artifacts.svg +++ /dev/null @@ -1 +0,0 @@ -Helm chart — the Dogu V3 packageRendered release resourcesDogu Registryces-mirrorDogu OperatorReferencedcontainer imagesChart.yamlidentity + discovery metadatavalues.yamlvalues.schema.jsondogu-values-metadata.yamlCES config mappingchart-patch-tpl.yamlcontainer image referencesdogu-upgrade.yamlupgrade coordinationtemplates/render workloads + CES CRsKubernetes resourcesworkloads · Services · PVCsCES integration resourcesAuthRegistration · ExpositionServiceAccountRequest / ProducerWarpMenuEntry \ No newline at end of file diff --git a/docs/v3/images/artifacts_de.puml b/docs/v3/images/artifacts_de.puml deleted file mode 100644 index 7c3cf4a..0000000 --- a/docs/v3/images/artifacts_de.puml +++ /dev/null @@ -1,73 +0,0 @@ -@startuml -!pragma layout smetana -skinparam backgroundColor white -skinparam defaultFontColor #392A25 -skinparam ArrowColor #00426B -skinparam rectangleBorderColor #1978A3 -skinparam rectangleBackgroundColor #23A3DD -skinparam rectangleRoundCorner 0 -skinparam shadowing false -hide stereotype -top to bottom direction - - - -rectangle "Helm-Chart — das Dogu-V3-Paket" as chart <> { - rectangle "Chart.yaml\nIdentität + Discovery-Metadaten" as metadata <> - rectangle "values.yaml\nvalues.schema.json" as config <> - rectangle "dogu-values-metadata.yaml\nCES-Konfigurationsmapping" as valuesMeta <> - rectangle "chart-patch-tpl.yaml\nContainer-Image-Referenzen" as imageMeta <> - rectangle "dogu-upgrade.yaml\nUpgrade-Koordination" as upgradeMeta <> - rectangle "templates/\nrendert Workloads + CES-CRs" as templates <> - - metadata -[hidden]right-> config - config -[hidden]right-> valuesMeta - imageMeta -[hidden]right-> upgradeMeta - upgradeMeta -[hidden]right-> templates -} - -rectangle "Gerenderte Release-Ressourcen" as rendered <> { - rectangle "Kubernetes-Ressourcen\nWorkloads · Services · PVCs" as k8s <> - rectangle "CES-Integrationsressourcen\nAuthRegistration · Exposition\nServiceAccountRequest / Producer\nWarpMenuEntry" as ces <> - k8s -[hidden]right-> ces -} - -rectangle "Dogu Registry\nces-mirror" as registry <> -rectangle "Dogu Operator" as operator <> -cloud "Referenzierte\nContainer-Images" as images #FCFAF4 - -config --> templates -templates --> k8s -templates --> ces -k8s --> images - -metadata --> registry -imageMeta --> registry -registry --> images - -valuesMeta --> operator -upgradeMeta --> operator -@enduml diff --git a/docs/v3/images/artifacts_de.svg b/docs/v3/images/artifacts_de.svg deleted file mode 100644 index 34104dd..0000000 --- a/docs/v3/images/artifacts_de.svg +++ /dev/null @@ -1 +0,0 @@ -Helm-Chart — das Dogu-V3-PaketGerenderte Release-RessourcenDogu Registryces-mirrorDogu OperatorReferenzierteContainer-ImagesChart.yamlIdentität + Discovery-Metadatenvalues.yamlvalues.schema.jsondogu-values-metadata.yamlCES-Konfigurationsmappingchart-patch-tpl.yamlContainer-Image-Referenzendogu-upgrade.yamlUpgrade-Koordinationtemplates/rendert Workloads + CES-CRsKubernetes-RessourcenWorkloads · Services · PVCsCES-IntegrationsressourcenAuthRegistration · ExpositionServiceAccountRequest / ProducerWarpMenuEntry \ No newline at end of file diff --git a/docs/v3/images/dogu-json-to-v3.puml b/docs/v3/images/dogu-json-to-v3.puml deleted file mode 100644 index 7f00767..0000000 --- a/docs/v3/images/dogu-json-to-v3.puml +++ /dev/null @@ -1,71 +0,0 @@ -@startuml -!pragma layout smetana -skinparam backgroundColor white -skinparam defaultFontColor #392A25 -skinparam ArrowColor #00426B -skinparam rectangleBorderColor #1978A3 -skinparam rectangleBackgroundColor #23A3DD -skinparam rectangleRoundCorner 0 -skinparam shadowing false -hide stereotype -left to right direction - - - -rectangle "V2 dogu.json responsibilities" as v2 <> { - rectangle "Identity, versions,\ndiscovery metadata" as a <> - rectangle "Workloads, ports, storage,\nhealth and security" as b <> - rectangle "Configuration\n " as c <> - rectangle "CES\nintegrations" as d <> - rectangle "Defined catalogue and\npublication data" as e <> - rectangle "Fields removed without\nreplacement" as f <> - rectangle "Category and other fields without\na general V3 destination" as g <> - - g -[hidden]right-> f - f -[hidden]right-> e - e -[hidden]right-> d - d -[hidden]right-> c - c -[hidden]right-> b - b -[hidden]right-> a -} - -rectangle "Dogu V3 destinations" as v3 <> { - rectangle "Chart.yaml\nmetadata" as chart <> - rectangle "Helm templates →\nKubernetes resources" as helm <> - rectangle "Chart values + schema +\ndogu-values-metadata.yaml" as config <> - rectangle "CES custom\nresources" as ces <> - rectangle "Chart.yaml + Dogu Registry +\nexternal marketing/sales data" as registry <> - rectangle "Removed\n " as removed <> - rectangle "No general V3\ndestination defined" as noGeneral <> - - noGeneral -[hidden]right-> removed - removed -[hidden]right-> registry - registry -[hidden]right-> ces - ces -[hidden]right-> config - config -[hidden]right-> helm - helm -[hidden]right-> chart -} - -a --> chart -b --> helm -c --> config -d --> ces -e --> registry -f --> removed -g --> noGeneral -@enduml diff --git a/docs/v3/images/dogu-json-to-v3.svg b/docs/v3/images/dogu-json-to-v3.svg deleted file mode 100644 index 55a5d70..0000000 --- a/docs/v3/images/dogu-json-to-v3.svg +++ /dev/null @@ -1 +0,0 @@ -V2 dogu.json responsibilitiesDogu V3 destinationsIdentity, versions,discovery metadataWorkloads, ports, storage,health and securityConfiguration CESintegrationsDefined catalogue andpublication dataFields removed withoutreplacementCategory and other fields withouta general V3 destinationChart.yamlmetadataHelm templates →Kubernetes resourcesChart values + schema +dogu-values-metadata.yamlCES customresourcesChart.yaml + Dogu Registry +external marketing/sales dataRemoved No general V3destination defined \ No newline at end of file diff --git a/docs/v3/images/dogu-json-to-v3_de.puml b/docs/v3/images/dogu-json-to-v3_de.puml deleted file mode 100644 index 8064a30..0000000 --- a/docs/v3/images/dogu-json-to-v3_de.puml +++ /dev/null @@ -1,71 +0,0 @@ -@startuml -!pragma layout smetana -skinparam backgroundColor white -skinparam defaultFontColor #392A25 -skinparam ArrowColor #00426B -skinparam rectangleBorderColor #1978A3 -skinparam rectangleBackgroundColor #23A3DD -skinparam rectangleRoundCorner 0 -skinparam shadowing false -hide stereotype -left to right direction - - - -rectangle "Aufgaben der V2-Datei dogu.json" as v2 <> { - rectangle "Identität, Versionen,\nDiscovery-Metadaten" as a <> - rectangle "Workloads, Ports, Speicher,\nHealth und Sicherheit" as b <> - rectangle "Konfiguration\n " as c <> - rectangle "CES-\nIntegrationen" as d <> - rectangle "Definierte Katalog- und\nVeröffentlichungsdaten" as e <> - rectangle "Ersatzlos entfernte\nFelder" as f <> - rectangle "Kategorie und andere Felder ohne\nallgemeines V3-Ziel" as g <> - - g -[hidden]right-> f - f -[hidden]right-> e - e -[hidden]right-> d - d -[hidden]right-> c - c -[hidden]right-> b - b -[hidden]right-> a -} - -rectangle "Ziele in Dogu V3" as v3 <> { - rectangle "Chart.yaml\nMetadaten" as chart <> - rectangle "Helm-Templates →\nKubernetes-Ressourcen" as helm <> - rectangle "Chart-Values + Schema +\ndogu-values-metadata.yaml" as config <> - rectangle "CES-Custom-\nResources" as ces <> - rectangle "Chart.yaml + Dogu Registry +\nexterne Marketing-/Vertriebsdaten" as registry <> - rectangle "Entfällt\n " as removed <> - rectangle "Kein allgemeines\nV3-Ziel festgelegt" as noGeneral <> - - noGeneral -[hidden]right-> removed - removed -[hidden]right-> registry - registry -[hidden]right-> ces - ces -[hidden]right-> config - config -[hidden]right-> helm - helm -[hidden]right-> chart -} - -a --> chart -b --> helm -c --> config -d --> ces -e --> registry -f --> removed -g --> noGeneral -@enduml diff --git a/docs/v3/images/dogu-json-to-v3_de.svg b/docs/v3/images/dogu-json-to-v3_de.svg deleted file mode 100644 index 13e0d78..0000000 --- a/docs/v3/images/dogu-json-to-v3_de.svg +++ /dev/null @@ -1 +0,0 @@ -Aufgaben der V2-Datei dogu.jsonZiele in Dogu V3Identität, Versionen,Discovery-MetadatenWorkloads, Ports, Speicher,Health und SicherheitKonfiguration CES-IntegrationenDefinierte Katalog- undVeröffentlichungsdatenErsatzlos entfernteFelderKategorie und andere Felder ohneallgemeines V3-ZielChart.yamlMetadatenHelm-Templates →Kubernetes-RessourcenChart-Values + Schema +dogu-values-metadata.yamlCES-Custom-ResourcesChart.yaml + Dogu Registry +externe Marketing-/VertriebsdatenEntfällt Kein allgemeinesV3-Ziel festgelegt \ No newline at end of file diff --git a/docs/v3/images/multinode-lifecycle.puml b/docs/v3/images/multinode-lifecycle.puml deleted file mode 100644 index 79648dd..0000000 --- a/docs/v3/images/multinode-lifecycle.puml +++ /dev/null @@ -1,47 +0,0 @@ -@startuml -skinparam backgroundColor white -skinparam shadowing false -skinparam ActorBorderColor #00426B -skinparam ActorFontColor #392A25 -skinparam NoteBackgroundColor #FCFAF4 -skinparam NoteBorderColor #23A3DD -skinparam NoteFontColor #392A25 -skinparam maxMessageSize 180 -skinparam sequence { - ArrowColor #00426B - ArrowFontColor #392A25 - LifeLineBorderColor #1978A3 - ParticipantBackgroundColor #23A3DD - ParticipantBorderColor #1978A3 - ParticipantFontColor #FFFFFF -} - -participant "CES\noperator" as user -participant "Dogu\nresource" as dogu -participant "Dogu\nOperator" as operator -participant "OCI\nregistry" as registry -participant "Helm\nrelease" as helm -participant "Kubernetes" as kubernetes -participant "Integration\ncontrollers" as integrations - -user -> dogu : create or change desired version/config -dogu -> operator : reconciliation event -operator -> registry : resolve chart + metadata -registry --> operator : chart package -operator -> operator : validate metadata, config, upgrade path - -operator -> helm : install / upgrade / uninstall -helm -> kubernetes : apply chart resources -kubernetes --> helm : workload/resource result -integrations -> kubernetes : reconcile integration CRs -integrations -> kubernetes : update integration CR status -helm --> operator : release result -operator -> dogu : on success: update conditions and installed version -operator -> dogu : on failure: set failing condition with reason - -note over dogu,integrations -Reconciliation repeats until desired and actual state converge. -Resource creation alone does not imply readiness. -end note - -@enduml diff --git a/docs/v3/images/multinode-lifecycle.svg b/docs/v3/images/multinode-lifecycle.svg deleted file mode 100644 index 06b2940..0000000 --- a/docs/v3/images/multinode-lifecycle.svg +++ /dev/null @@ -1 +0,0 @@ -CESDoguDoguOCIHelmKubernetesIntegrationCESoperatorCESoperatorDoguresourceDoguresourceDoguOperatorDoguOperatorOCIregistryOCIregistryHelmreleaseHelmreleaseKubernetesKubernetesIntegrationcontrollersIntegrationcontrollerscreate or change desiredversion/configreconciliation eventresolve chart + metadatachart packagevalidate metadata, config,upgrade pathinstall / upgrade / uninstallapply chart resourcesworkload/resource resultreconcile integration CRsupdate integration CRstatusrelease resulton success: updateconditions and installedversionon failure: set failingcondition with reasonReconciliation repeats until desired and actual state converge.Resource creation alone does not imply readiness. \ No newline at end of file diff --git a/docs/v3/images/multinode-lifecycle_de.puml b/docs/v3/images/multinode-lifecycle_de.puml deleted file mode 100644 index 04cf552..0000000 --- a/docs/v3/images/multinode-lifecycle_de.puml +++ /dev/null @@ -1,47 +0,0 @@ -@startuml -skinparam backgroundColor white -skinparam shadowing false -skinparam ActorBorderColor #00426B -skinparam ActorFontColor #392A25 -skinparam NoteBackgroundColor #FCFAF4 -skinparam NoteBorderColor #23A3DD -skinparam NoteFontColor #392A25 -skinparam maxMessageSize 180 -skinparam sequence { - ArrowColor #00426B - ArrowFontColor #392A25 - LifeLineBorderColor #1978A3 - ParticipantBackgroundColor #23A3DD - ParticipantBorderColor #1978A3 - ParticipantFontColor #FFFFFF -} - -participant "CES-\nAdministrator:in" as user -participant "Dogu-\nRessource" as dogu -participant "Dogu\nOperator" as operator -participant "OCI-\nRegistry" as registry -participant "Helm-\nRelease" as helm -participant "Kubernetes" as kubernetes -participant "Integrations-\ncontroller" as integrations - -user -> dogu : gewünschte Version/Konfiguration erstellen oder ändern -dogu -> operator : Reconciliation-Ereignis -operator -> registry : Chart + Metadaten ermitteln -registry --> operator : Chart-Paket -operator -> operator : Metadaten, Konfiguration und Upgrade-Pfad validieren - -operator -> helm : installieren / aktualisieren / deinstallieren -helm -> kubernetes : Chart-Ressourcen anwenden -kubernetes --> helm : Workload-/Ressourcenergebnis -integrations -> kubernetes : Integrations-CRs abgleichen -integrations -> kubernetes : Status der Integrations-CRs aktualisieren -helm --> operator : Release-Ergebnis -operator -> dogu : bei Erfolg: Conditions und installierte Version aktualisieren -operator -> dogu : bei Fehler: fehlgeschlagene Condition mit Begründung setzen - -note over dogu,integrations -Reconciliation wird wiederholt, bis Soll- und Istzustand übereinstimmen. -Die bloße Erstellung einer Ressource bedeutet nicht, dass sie bereit ist. -end note - -@enduml diff --git a/docs/v3/images/multinode-lifecycle_de.svg b/docs/v3/images/multinode-lifecycle_de.svg deleted file mode 100644 index f92a1a2..0000000 --- a/docs/v3/images/multinode-lifecycle_de.svg +++ /dev/null @@ -1 +0,0 @@ -CES-Dogu-DoguOCI-Helm-KubernetesIntegrations-CES-Administrator:inCES-Administrator:inDogu-RessourceDogu-RessourceDoguOperatorDoguOperatorOCI-RegistryOCI-RegistryHelm-ReleaseHelm-ReleaseKubernetesKubernetesIntegrations-controllerIntegrations-controllergewünschteVersion/Konfigurationerstellen oder ändernReconciliation-EreignisChart + MetadatenermittelnChart-PaketMetadaten, Konfigurationund Upgrade-Pfadvalidiereninstallieren / aktualisieren /deinstallierenChart-RessourcenanwendenWorkload-/RessourcenergebnisIntegrations-CRsabgleichenStatus der Integrations-CRsaktualisierenRelease-Ergebnisbei Erfolg: Conditions undinstallierte Versionaktualisierenbei Fehler:fehlgeschlagene Conditionmit Begründung setzenReconciliation wird wiederholt, bis Soll- und Istzustand übereinstimmen.Die bloße Erstellung einer Ressource bedeutet nicht, dass sie bereit ist. \ No newline at end of file diff --git a/docs/v3/images/multinode-request-routing.puml b/docs/v3/images/multinode-request-routing.puml deleted file mode 100644 index e6e4bf9..0000000 --- a/docs/v3/images/multinode-request-routing.puml +++ /dev/null @@ -1,45 +0,0 @@ -@startuml -skinparam backgroundColor white -skinparam shadowing false -skinparam ActorBorderColor #00426B -skinparam ActorFontColor #392A25 -skinparam NoteBackgroundColor #FCFAF4 -skinparam NoteBorderColor #23A3DD -skinparam NoteFontColor #392A25 -skinparam sequence { - ArrowColor #00426B - ArrowFontColor #392A25 - LifeLineBorderColor #1978A3 - ParticipantBackgroundColor #23A3DD - ParticipantBorderColor #1978A3 - ParticipantFontColor #FFFFFF -} - -actor "Browser / API client" as client -participant "CES Gateway" as gateway -participant "Kubernetes Service" as service -participant "Dogu Pod" as pod -participant "Exposition CR" as exposition -participant "Service Discovery" as discovery -participant "Generated route\nconfiguration" as route - -== Control plane: route reconciliation == -exposition -> discovery : service + port + path + rewrite -discovery -> route : reconcile -route -> gateway : configure route -discovery -> exposition : update API-specific conditions - -== Data plane: request processing == -client -> gateway : HTTPS request to /my-dogu/... -gateway -> service : match route, forward / optionally rewrite -service -> pod : target port -pod --> service : response -service --> gateway : response -gateway --> client : HTTPS response - -note over exposition,route -Helm tracks Service + Exposition. -The Exposition controls generated routes through controller ownership. -end note - -@enduml diff --git a/docs/v3/images/multinode-request-routing.svg b/docs/v3/images/multinode-request-routing.svg deleted file mode 100644 index 77addf8..0000000 --- a/docs/v3/images/multinode-request-routing.svg +++ /dev/null @@ -1 +0,0 @@ -Browser . API clientCES GatewayKubernetes ServiceDogu PodExposition CRService DiscoveryGenerated routeBrowser / API clientBrowser / API clientCES GatewayCES GatewayKubernetes ServiceKubernetes ServiceDogu PodDogu PodExposition CRExposition CRService DiscoveryService DiscoveryGenerated routeconfigurationGenerated routeconfigurationControl plane: route reconciliationservice + port + path + rewritereconcileconfigure routeupdate API-specific conditionsData plane: request processingHTTPS request to /my-dogu/...match route, forward / optionally rewritetarget portresponseresponseHTTPS responseHelm tracks Service + Exposition.The Exposition controls generated routes through controller ownership. \ No newline at end of file diff --git a/docs/v3/images/multinode-request-routing_de.puml b/docs/v3/images/multinode-request-routing_de.puml deleted file mode 100644 index ef75862..0000000 --- a/docs/v3/images/multinode-request-routing_de.puml +++ /dev/null @@ -1,45 +0,0 @@ -@startuml -skinparam backgroundColor white -skinparam shadowing false -skinparam ActorBorderColor #00426B -skinparam ActorFontColor #392A25 -skinparam NoteBackgroundColor #FCFAF4 -skinparam NoteBorderColor #23A3DD -skinparam NoteFontColor #392A25 -skinparam sequence { - ArrowColor #00426B - ArrowFontColor #392A25 - LifeLineBorderColor #1978A3 - ParticipantBackgroundColor #23A3DD - ParticipantBorderColor #1978A3 - ParticipantFontColor #FFFFFF -} - -actor "Browser / API-Client" as client -participant "CES-Gateway" as gateway -participant "Kubernetes-Service" as service -participant "Dogu-Pod" as pod -participant "Exposition-CR" as exposition -participant "Service Discovery" as discovery -participant "Erzeugte Routen-\nkonfiguration" as route - -== Steuerungsebene: Routenabgleich == -exposition -> discovery : Service + Port + Pfad + Rewrite -discovery -> route : abgleichen -route -> gateway : Route konfigurieren -discovery -> exposition : API-spezifische Conditions aktualisieren - -== Datenebene: Request-Verarbeitung == -client -> gateway : HTTPS-Request an /my-dogu/... -gateway -> service : Route anwenden, weiterleiten / optional umschreiben -service -> pod : Ziel-Port -pod --> service : Response -service --> gateway : Response -gateway --> client : HTTPS-Response - -note over exposition,route -Helm verwaltet Service + Exposition. -Die Exposition steuert erzeugte Routen über die Controller-Verantwortung. -end note - -@enduml diff --git a/docs/v3/images/multinode-request-routing_de.svg b/docs/v3/images/multinode-request-routing_de.svg deleted file mode 100644 index decbbce..0000000 --- a/docs/v3/images/multinode-request-routing_de.svg +++ /dev/null @@ -1 +0,0 @@ -Browser . API-ClientCES-GatewayKubernetes-ServiceDogu-PodExposition-CRService DiscoveryErzeugte Routen-Browser / API-ClientBrowser / API-ClientCES-GatewayCES-GatewayKubernetes-ServiceKubernetes-ServiceDogu-PodDogu-PodExposition-CRExposition-CRService DiscoveryService DiscoveryErzeugte Routen-konfigurationErzeugte Routen-konfigurationSteuerungsebene: RoutenabgleichService + Port + Pfad + RewriteabgleichenRoute konfigurierenAPI-spezifische Conditions aktualisierenDatenebene: Request-VerarbeitungHTTPS-Request an /my-dogu/...Route anwenden, weiterleiten / optional umschreibenZiel-PortResponseResponseHTTPS-ResponseHelm verwaltet Service + Exposition.Die Exposition steuert erzeugte Routen über die Controller-Verantwortung. \ No newline at end of file diff --git a/docs/v3/images/multinode-system-context.puml b/docs/v3/images/multinode-system-context.puml deleted file mode 100644 index eb9b7f9..0000000 --- a/docs/v3/images/multinode-system-context.puml +++ /dev/null @@ -1,75 +0,0 @@ -@startuml -skinparam backgroundColor white -skinparam shadowing false -skinparam componentStyle rectangle -hide stereotype -skinparam defaultTextAlignment center -skinparam ArrowColor #00426B -skinparam ArrowFontColor #392A25 -skinparam ActorBorderColor #00426B -skinparam ActorFontColor #392A25 -skinparam rectangle { - BackgroundColor #FCFAF4 - BorderColor #00426B - FontColor #392A25 -} -skinparam component { - BackgroundColor #23A3DD - BorderColor #1978A3 - FontColor #FFFFFF -} -skinparam cloud { - BackgroundColor #FCFAF4 - BorderColor #1978A3 - FontColor #392A25 -} -skinparam artifact { - BackgroundColor #FCFAF4 - BorderColor #1978A3 - FontColor #392A25 -} -skinparam database { - BackgroundColor #FCFAF4 - BorderColor #1978A3 - FontColor #392A25 -} - - - -actor "Dogu developer" as developer -cloud "OCI registry" as registry -artifact "Dogu V3 Helm chart" as chart - -rectangle "Multinode CES" { - component "Dogu lifecycle\n(Dogu Operator + Helm)" as lifecycle - - rectangle "Dogu namespace" <> { - component "Application workloads\nand Services" as workloads - component "CES integration CRs\nExposition · AuthRegistration\nServiceAccountRequest / Producer\nWarpMenuEntry" as crs - } - - component "CES integration controllers" as controllers - component "Gateway · Identity Provider\nCredential Secrets · Warp Menu" as services - database "Persistent volumes" as storage -} - -developer --> registry :  publishes chart + images -registry --> chart :  supplies chart and metadata -chart --> lifecycle :  resolved and validated -lifecycle --> workloads :  reconciles release resources -lifecycle --> crs :  reconciles release resources -crs <--> controllers :  watches CRs + reports status -controllers --> services :  creates + updates -workloads --> storage :  mounts PVCs -workloads --> services :  consumes CES capabilities - -@enduml diff --git a/docs/v3/images/multinode-system-context.svg b/docs/v3/images/multinode-system-context.svg deleted file mode 100644 index b7f2e6a..0000000 --- a/docs/v3/images/multinode-system-context.svg +++ /dev/null @@ -1 +0,0 @@ -Multinode CESDogu namespaceDogu lifecycle(Dogu Operator + Helm)CES integration controllersGateway · Identity ProviderCredential Secrets · Warp MenuPersistent volumesApplication workloadsand ServicesCES integration CRsExposition · AuthRegistrationServiceAccountRequest / ProducerWarpMenuEntryDogu developerOCI registryDogu V3 Helm chart publishes chart + images supplies chart and metadata resolved and validated reconciles release resources reconciles release resources watches CRs + reports status creates + updates mounts PVCs consumes CES capabilities \ No newline at end of file diff --git a/docs/v3/images/multinode-system-context_de.puml b/docs/v3/images/multinode-system-context_de.puml deleted file mode 100644 index cc0e3c3..0000000 --- a/docs/v3/images/multinode-system-context_de.puml +++ /dev/null @@ -1,75 +0,0 @@ -@startuml -skinparam backgroundColor white -skinparam shadowing false -skinparam componentStyle rectangle -hide stereotype -skinparam defaultTextAlignment center -skinparam ArrowColor #00426B -skinparam ArrowFontColor #392A25 -skinparam ActorBorderColor #00426B -skinparam ActorFontColor #392A25 -skinparam rectangle { - BackgroundColor #FCFAF4 - BorderColor #00426B - FontColor #392A25 -} -skinparam component { - BackgroundColor #23A3DD - BorderColor #1978A3 - FontColor #FFFFFF -} -skinparam cloud { - BackgroundColor #FCFAF4 - BorderColor #1978A3 - FontColor #392A25 -} -skinparam artifact { - BackgroundColor #FCFAF4 - BorderColor #1978A3 - FontColor #392A25 -} -skinparam database { - BackgroundColor #FCFAF4 - BorderColor #1978A3 - FontColor #392A25 -} - - - -actor "Dogu-Entwickler:in" as developer -cloud "OCI-Registry" as registry -artifact "Dogu-V3-Helm-Chart" as chart - -rectangle "Multinode-CES" { - component "Dogu-Lebenszyklus\n(Dogu Operator + Helm)" as lifecycle - - rectangle "Dogu-Namespace" <> { - component "Anwendungs-Workloads\nund Services" as workloads - component "CES-Integrations-CRs\nExposition · AuthRegistration\nServiceAccountRequest / Producer\nWarpMenuEntry" as crs - } - - component "CES-Integrationscontroller" as controllers - component "Gateway · Identity Provider\nCredential-Secrets · Warp-Menü" as services - database "Persistente Volumes" as storage -} - -developer --> registry :  veröffentlicht Chart + Images -registry --> chart :  liefert Chart und Metadaten -chart --> lifecycle :  ermittelt und validiert -lifecycle --> workloads :  gleicht Release-Ressourcen ab -lifecycle --> crs :  gleicht Release-Ressourcen ab -crs <--> controllers :  überwacht CRs + meldet Status -controllers --> services :  erstellt + aktualisiert -workloads --> storage :  bindet PVCs ein -workloads --> services :  nutzt CES-Funktionen - -@enduml diff --git a/docs/v3/images/multinode-system-context_de.svg b/docs/v3/images/multinode-system-context_de.svg deleted file mode 100644 index a0504e5..0000000 --- a/docs/v3/images/multinode-system-context_de.svg +++ /dev/null @@ -1 +0,0 @@ -Multinode-CESDogu-NamespaceDogu-Lebenszyklus(Dogu Operator + Helm)CES-IntegrationscontrollerGateway · Identity ProviderCredential-Secrets · Warp-MenüPersistente VolumesAnwendungs-Workloadsund ServicesCES-Integrations-CRsExposition · AuthRegistrationServiceAccountRequest / ProducerWarpMenuEntryDogu-Entwickler:inOCI-RegistryDogu-V3-Helm-Chart veröffentlicht Chart + Images liefert Chart und Metadaten ermittelt und validiert gleicht Release-Ressourcen ab gleicht Release-Ressourcen ab überwacht CRs + meldet Status erstellt + aktualisiert bindet PVCs ein nutzt CES-Funktionen \ No newline at end of file From 4eff2a015ec3d01b073e12d09c9e53a581ac430d Mon Sep 17 00:00:00 2001 From: Nico Franzeck Date: Mon, 3 Aug 2026 15:52:07 +0200 Subject: [PATCH 05/16] Provide English version artifacts_en.md --- docs/v3/concepts/artifacts_en.md | 227 +++++++++++++++++++++++++++++++ 1 file changed, 227 insertions(+) create mode 100644 docs/v3/concepts/artifacts_en.md diff --git a/docs/v3/concepts/artifacts_en.md b/docs/v3/concepts/artifacts_en.md new file mode 100644 index 0000000..7ecd296 --- /dev/null +++ b/docs/v3/concepts/artifacts_en.md @@ -0,0 +1,227 @@ +# 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 +``` + +### `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 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 to interact with each other. For this, an appropriate ServiceAccount must be created at the target Dogu (Producer) for an accessing Dogu (Consumer). + +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 Dogu offers an interface that can be used by other Dogus, it must provide a `ServiceAccountProducer-CR`. The `ServiceAccountProducer` defines how service accounts are created for the Dogu and which parameters are supported. Furthermore, the CR describes values that the Dogu – the Producer – returns after creating a service account. Each returned value is written as a key into the Secret referenced by the requesting Dogu – the Consumer. + +**`ServiceAccountRequest`** + +If a Dogu needs a service account for another Dogu, 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 consuming Dogu. 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 | From 48c4c830a6d9c138a9c27f6cb0671ef9d77c8992 Mon Sep 17 00:00:00 2001 From: Nico Franzeck Date: Mon, 3 Aug 2026 16:52:57 +0200 Subject: [PATCH 06/16] Refactor comopendium: - Remove columns "Owner" and "When needed" - link to concepts to have a single link hop to the repo - remove chapter that listed all dogu v2 fields --- docs/v3/reference/compendium.md | 57 ------------------------- docs/v3/reference/compendium_de.md | 68 ++++++++---------------------- docs/v3/reference/compendium_en.md | 23 ++++++++++ 3 files changed, 40 insertions(+), 108 deletions(-) delete mode 100644 docs/v3/reference/compendium.md create mode 100644 docs/v3/reference/compendium_en.md diff --git a/docs/v3/reference/compendium.md b/docs/v3/reference/compendium.md deleted file mode 100644 index eb20419..0000000 --- a/docs/v3/reference/compendium.md +++ /dev/null @@ -1,57 +0,0 @@ -# Dogu V3 Artifact Compendium - -This compendium provides an overview of the artifacts and APIs of Dogu V3. For an introduction to how they work together, read [Understand Dogu V3 Artifacts](../concepts/artifacts.md). - -## Chart artifacts and APIs - -| Artifact / API | Purpose | When needed | Owner | Reference documentation | -| --- | --- | --- | --- | --- | -| Helm chart | Leading Dogu package; contains metadata, defaults, templates and companion files | Always | Dogu developer | [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 | Always | Dogu developer; consumed by Dogu tooling | [Helm `Chart.yaml`](https://helm.sh/docs/topics/charts/#the-chartyaml-file) | -| `values.yaml` | Safe defaults and public chart configuration interface | Always, according to the Helm chart convention | Dogu developer | [Helm values](https://helm.sh/docs/chart_template_guide/values_files/) | -| `values.schema.json` | Validates the merged values | When the Dogu exposes configurable values | Dogu developer | [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 | For CES-wide configuration mappings; optional for a configuration-free Dogu | Dogu developer; consumed by Dogu Operator | — | -| `templates/` | Renders workloads, Services, PVCs, probes and optional CES integration resources | Always | Dogu developer | [Helm templates](https://helm.sh/docs/chart_template_guide/) and owning Kubernetes/CRD contracts | -| `chart-patch-tpl.yaml` | Lists or resolves every container image referenced by the chart for the Dogu Registry and mirroring tools | Whenever the chart references container images, which is normally every Dogu | Dogu developer; consumed by the Dogu Registry and mirroring tools | — | -| `dogu-upgrade.yaml` | Describes valid Dogu-version transitions and optional parameters for upgrade coordination | The accepted ADRs do not yet define when the file must be present | Dogu developer; consumed by the Dogu Operator | — | -| Container images | Provide the application and any sidecar and init containers referenced by the chart | For every container rendered by the chart | Image producer; references owned by Dogu developer | [Kubernetes images](https://kubernetes.io/docs/concepts/containers/images/) | -| `AuthRegistration` | Declares authentication registration when the Dogu participates in CES authentication | When the Dogu uses CES authentication | k8s-auth-registration-lib owns the API; Dogu developer declares it | [AuthRegistration v1 API](https://github.com/cloudogu/k8s-auth-registration-lib/tree/develop/api/v1) | -| `Exposition` | Connects a chart Service to CES-provided external access when needed | When the Dogu needs external access | k8s-exposition-lib owns the API; Dogu developer declares it | [Exposition v1 API](https://github.com/cloudogu/k8s-exposition-lib/tree/develop/api/v1) | -| `ServiceAccountRequest` | Requests technical credentials from a producer when another CES service is needed | When the Dogu needs technical credentials from another CES service | k8s-serviceaccount-lib owns the API; consumer declares it | [Service account v2 API](https://github.com/cloudogu/k8s-serviceaccount-lib/tree/develop/api/v2) | -| `ServiceAccountProducer` | Declares that the Dogu offers technical accounts | When the Dogu provides technical accounts | k8s-serviceaccount-lib owns the API; producer declares it | [Service account v2 API](https://github.com/cloudogu/k8s-serviceaccount-lib/tree/develop/api/v2) | -| `WarpMenuEntry` | Declares a shared-menu entry when the Dogu has a user-facing CES path | When the Dogu provides a user-facing CES path | k8s-warp-menu-entry-lib owns the API; Dogu developer declares it | [WarpMenuEntry v1 API](https://github.com/cloudogu/k8s-warp-menu-entry-lib/tree/develop/api/v1) | -| Dogu Registry data | Combines technical chart metadata with entitlement and marketing or sales data maintained outside the chart | For publication, discovery and entitlement through the Dogu Registry | Cloudogu | — | - -## Complete V2 `dogu.json` disposition - -The following table lists every V2 `dogu.json` field and its accepted V3 destination where one exists. These mappings are not automatic conversions and do not necessarily preserve every V2 behavior. Where the accepted architecture defines no general V3 destination, the table states that explicitly. - -| V2 field | V3 destination | Disposition and status | -| --- | --- | --- | -| `Name` | `Chart.yaml` + registry namespace | Chart `name` is the simple technical name; the qualified namespace comes from registry context. | -| `Version` | `Chart.yaml` | Becomes chart `version`, the Dogu version. `appVersion` separately identifies the application. | -| `PublishedAt` | Dogu Registry v3 API | Included as publication metadata in the accepted API design. Its source and authoring workflow are not yet defined. | -| `DisplayName` | `Chart.yaml` | Dogu annotation `dogu.cloudogu.com/display-name`; optional in accepted target metadata. | -| `Description` | `Chart.yaml` | Standard `description`; required in the accepted target metadata. | -| `Category` | No concrete V3 field defined | The accepted architecture treats it as catalogue metadata but defines neither a `Chart.yaml` field nor an external source. It is independent of `WarpMenuEntry`. | -| `Tags` | `Chart.yaml` | Use Helm `keywords` for general search terms. Define menu entries separately with `WarpMenuEntry`. | -| `Logo` | `Chart.yaml` | Store the URL of the Dogu logo in the Helm `icon` field. | -| `URL` | `Chart.yaml` | Store the project or original vendor website in the Helm `home` field. | -| `Image` | Companion file + Kubernetes workloads | Image references are defined in the container specs. `chart-patch-tpl.yaml` also makes them discoverable by platform tooling. | -| `ExposedPorts` | Helm/Kubernetes + CES CR | Kubernetes Service plus `Exposition` when external access is needed. | -| `ExposedCommands` | Removed / purpose-specific V3 mechanisms | There is no generic V3 `ExposedCommands` API. Implement upgrade migrations with init containers or Helm hook Jobs. Assess other lifecycle or custom commands separately. | -| `Volumes` | Helm/Kubernetes resources | PVCs, volumes and volume mounts. Backup and retention must be declared/documented separately; no automatic field conversion. | -| `HealthCheck` | Helm/Kubernetes resources | Deprecated V2 single check. Map TCP or HTTP checks to an appropriate Kubernetes probe where the signal is equivalent; the accepted architecture defines no direct V3 equivalent for the V2 `state` check. | -| `HealthChecks` | Helm/Kubernetes resources | Model applicable checks as startup, readiness or liveness probes according to their purpose. This does not automatically preserve every V2 check type or consumer behavior. | -| `ServiceAccounts` | CES CRs | `ServiceAccountRequest` and, for offered accounts, `ServiceAccountProducer`. | -| `Privileged` | Removed | There is no direct V3 equivalent. The V2 field mounted the Docker socket; Kubernetes privileged mode or a security context is not an equivalent replacement. Define only the pod and container permissions the application requires. | -| `Security` | Helm/Kubernetes resources | Map supported controls to pod or container security contexts and capabilities. The accepted architecture does not define a shared V3 security baseline. | -| `Configuration` | Chart values, schema and companion metadata | `values.yaml`, `values.schema.json` and, for CES mappings, `dogu-values-metadata.yaml`. | -| `Properties` | Removed | The generic V2 field has no general V3 replacement. Use a concrete Helm, Kubernetes or CES API only when that API defines the required behavior. | -| `EnvironmentVariables` | Helm/Kubernetes resources | Explicit container `env`/`envFrom`, normally sourced from values, ConfigMaps or Secrets as appropriate. | -| `Dependencies` | Helm/Kubernetes resources or CES service-account CRs | Model service dependencies with `ServiceAccountRequest` where appropriate and other requirements explicitly in the chart. The accepted architecture defines no generic replacement for all V2 client, package or version checks. | -| `OptionalDependencies` | Optional `ServiceAccountRequest` or purpose-specific chart resources | Use an optional request for optional service-account dependencies. The accepted architecture defines no generic contract that preserves every V2 optional-dependency and version-check behavior. | - -## Related concept - -Return to [Understand Dogu V3 Artifacts](../concepts/artifacts.md), or continue with [the Multinode runtime environment](../concepts/multinode-environment.md). diff --git a/docs/v3/reference/compendium_de.md b/docs/v3/reference/compendium_de.md index 56c3868..0cd0131 100644 --- a/docs/v3/reference/compendium_de.md +++ b/docs/v3/reference/compendium_de.md @@ -1,57 +1,23 @@ # Kompendium der Dogu-V3-Artefakte -Dieses Kompendium gibt einen Überblick über die Artefakte und APIs von Dogu V3. Eine Einführung in ihr Zusammenspiel finden Sie unter [Dogu-V3-Artefakte verstehen](../concepts/artifacts_de.md). +Dieses Kompendium gibt einen Überblick über die Artefakte und APIs 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 | Wann benötigt? | Verantwortung | Referenzdokumentation | -| --- | --- | --- | --- | --- | -| Helm-Chart | Führendes Dogu-Paket; enthält Metadaten, Standardwerte, Templates und Begleitdateien | Immer | Dogu-Entwickler:in | [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 | Immer | Dogu-Entwickler:in; konsumiert von Dogu-Tooling | [Helm-`Chart.yaml`](https://helm.sh/docs/topics/charts/#the-chartyaml-file) | -| `values.yaml` | Sichere Standardwerte und öffentliche Konfigurationsschnittstelle | Immer, gemäß Helm-Chart-Konvention | Dogu-Entwickler:in | [Helm-Values](https://helm.sh/docs/chart_template_guide/values_files/) | -| `values.schema.json` | Validiert die zusammengeführten Values | Wenn das Dogu konfigurierbare Werte anbietet | Dogu-Entwickler:in | [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 | Für CES-weite Konfigurationszuordnungen; bei einem konfigurationslosen Dogu optional | Dogu-Entwickler:in; konsumiert vom Dogu Operator | — | -| `templates/` | Rendert Workloads, Services, PVCs, Probes und optionale CES-Integrationsressourcen | Immer | Dogu-Entwickler:in | [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 für die Dogu Registry und Spiegelungswerkzeuge auf beziehungsweise löst sie auf | Wenn das Chart Container-Images referenziert, also normalerweise bei jedem Dogu | Dogu-Entwickler:in; konsumiert von der Dogu Registry und Spiegelungswerkzeugen | — | -| `dogu-upgrade.yaml` | Beschreibt gültige Übergänge zwischen Dogu-Versionen und optionale Parameter zur Upgrade-Koordination | Die akzeptierten ADRs legen noch nicht fest, wann die Datei vorhanden sein muss | Dogu-Entwickler:in; konsumiert vom Dogu Operator | — | -| Container-Images | Stellen die Anwendung sowie referenzierte Sidecar- und Init-Container bereit | Für jeden vom Chart gerenderten Container | Image-Produzent; Referenzen durch Dogu-Entwickler:in | [Kubernetes-Images](https://kubernetes.io/docs/concepts/containers/images/) | -| `AuthRegistration` | Deklariert bei Teilnahme an CES-Authentifizierung die Registrierung | Wenn das Dogu die CES-Authentifizierung nutzt | k8s-auth-registration-lib verantwortet die API; Deklaration durch Dogu-Entwickler:in | [AuthRegistration-v1-API](https://github.com/cloudogu/k8s-auth-registration-lib/tree/develop/api/v1) | -| `Exposition` | Verbindet bei Bedarf einen Chart-Service mit CES-bereitgestelltem externen Zugriff | Wenn das Dogu extern erreichbar sein soll | k8s-exposition-lib verantwortet die API; Deklaration durch Dogu-Entwickler:in | [Exposition-v1-API](https://github.com/cloudogu/k8s-exposition-lib/tree/develop/api/v1) | -| `ServiceAccountRequest` | Fordert bei Bedarf technische Credentials von einem Producer an | Wenn das Dogu technische Credentials eines anderen CES-Dienstes benötigt | k8s-serviceaccount-lib verantwortet die API; Deklaration durch Consumer | [Service-Account-v2-API](https://github.com/cloudogu/k8s-serviceaccount-lib/tree/develop/api/v2) | -| `ServiceAccountProducer` | Deklariert, dass das Dogu technische Accounts anbietet | Wenn das Dogu technische Accounts bereitstellt | k8s-serviceaccount-lib verantwortet die API; Deklaration durch Producer | [Service-Account-v2-API](https://github.com/cloudogu/k8s-serviceaccount-lib/tree/develop/api/v2) | -| `WarpMenuEntry` | Deklariert bei einem sichtbaren CES-Pfad einen Eintrag im gemeinsamen Menü | Wenn das Dogu einen sichtbaren CES-Pfad bereitstellt | k8s-warp-menu-entry-lib verantwortet die API; Deklaration durch Dogu-Entwickler:in | [WarpMenuEntry-v1-API](https://github.com/cloudogu/k8s-warp-menu-entry-lib/tree/develop/api/v1) | -| Dogu-Registry-Daten | Verbinden technische Chart-Metadaten mit außerhalb des Charts gepflegten Berechtigungs-, Marketing- oder Vertriebsdaten | Für Veröffentlichung, Discovery und Berechtigungsprüfung über die Dogu Registry | Cloudogu | — | - -## Vollständige Zuordnung der V2-`dogu.json` - -Die folgende Tabelle führt jedes Feld der V2-`dogu.json` und, soweit vorhanden, sein akzeptiertes V3-Ziel auf. Die Zuordnungen sind keine automatische Konvertierung und erhalten nicht zwangsläufig jedes V2-Verhalten. Wo die akzeptierte Architektur kein allgemeines V3-Ziel definiert, benennt die Tabelle diese Grenze ausdrücklich. - -| V2-Feld | V3-Ziel | Zuordnung und Status | +| Artefakt / API | Zweck | Referenzdokumentation | | --- | --- | --- | -| `Name` | `Chart.yaml` + Registry-Namespace | Chart-`name` ist der einfache technische Name; der qualifizierte Namespace stammt aus dem Registry-Kontext. | -| `Version` | `Chart.yaml` | Wird zur Chart-`version`, der Dogu-Version. `appVersion` bezeichnet getrennt die Anwendung. | -| `PublishedAt` | Dogu-Registry-v3-API | Ist im akzeptierten API-Entwurf als Veröffentlichungsinformation enthalten. Quelle und Pflegeprozess sind noch nicht festgelegt. | -| `DisplayName` | `Chart.yaml` | Dogu-Annotation `dogu.cloudogu.com/display-name`; in den akzeptierten Zielmetadaten optional. | -| `Description` | `Chart.yaml` | Standardfeld `description`; in den akzeptierten Zielmetadaten verpflichtend. | -| `Category` | Kein konkretes V3-Feld festgelegt | Die akzeptierte Architektur behandelt die Kategorie als Katalogmetadatum, definiert aber weder ein `Chart.yaml`-Feld noch eine externe Quelle. Sie ist unabhängig von `WarpMenuEntry`. | -| `Tags` | `Chart.yaml` | Allgemeine Suchbegriffe werden als Helm-`keywords` gepflegt. Menüeinträge werden separat mit `WarpMenuEntry` definiert. | -| `Logo` | `Chart.yaml` | Die URL zum Dogu-Logo wird im Helm-Feld `icon` hinterlegt. | -| `URL` | `Chart.yaml` | Die Projekt- oder Herstellerwebsite wird im Helm-Feld `home` hinterlegt. | -| `Image` | Begleitdatei + Kubernetes-Workloads | Image-Referenzen werden in den Container-Specs definiert. `chart-patch-tpl.yaml` macht sie zusätzlich für Plattformwerkzeuge auffindbar. | -| `ExposedPorts` | Helm/Kubernetes + CES-CR | Kubernetes-Service plus `Exposition`, wenn externer Zugriff benötigt wird. | -| `ExposedCommands` | Entfällt / zweckgebundene V3-Mechanismen | Eine generische V3-`ExposedCommands`-API existiert nicht. Upgrade-Migrationen werden mit Init-Containern oder Helm-Hook-Jobs umgesetzt. Andere Lifecycle- oder benutzerdefinierte Befehle müssen separat betrachtet werden. | -| `Volumes` | Helm-/Kubernetes-Ressourcen | PVCs, Volumes und Volume-Mounts. Backup und Retention separat deklarieren/dokumentieren; keine automatische Feldkonvertierung. | -| `HealthCheck` | Helm-/Kubernetes-Ressourcen | Veralteter einzelner V2-Check. TCP- oder HTTP-Checks werden einer passenden Kubernetes-Probe zugeordnet, wenn das Signal gleichwertig ist; für den V2-Check vom Typ `state` definiert die akzeptierte Architektur kein direktes V3-Äquivalent. | -| `HealthChecks` | Helm-/Kubernetes-Ressourcen | Geeignete Checks werden entsprechend ihrem Zweck als Startup-, Readiness- oder Liveness-Probes modelliert. Dadurch bleiben nicht automatisch jeder V2-Check-Typ und jedes Consumer-Verhalten erhalten. | -| `ServiceAccounts` | CES-CRs | `ServiceAccountRequest` und bei angebotenen Accounts `ServiceAccountProducer`. | -| `Privileged` | Entfällt | Es gibt keinen direkten V3-Ersatz. Das V2-Feld band den Docker-Socket ein; der Kubernetes-Privileged-Modus oder ein Security Context ist kein gleichwertiger Ersatz. Im Chart werden nur die tatsächlich benötigten Pod- und Container-Berechtigungen definiert. | -| `Security` | Helm-/Kubernetes-Ressourcen | Unterstützte Einstellungen werden über Pod- oder Container-Sicherheitskontexte und Capabilities abgebildet. Die akzeptierte Architektur legt keine gemeinsame V3-Sicherheitsbaseline fest. | -| `Configuration` | Chart-Values, Schema und Begleitmetadaten | `values.yaml`, `values.schema.json` und für CES-Zuordnungen `dogu-values-metadata.yaml`. | -| `Properties` | Entfällt | Für das generische V2-Feld gibt es keinen allgemeinen V3-Ersatz. Ein konkretes Helm-, Kubernetes- oder CES-Konzept wird nur verwendet, wenn dessen API das benötigte Verhalten definiert. | -| `EnvironmentVariables` | Helm-/Kubernetes-Ressourcen | Explizite Container-Felder `env` und `envFrom`, je nach Inhalt aus Values, ConfigMaps oder Secrets gespeist. | -| `Dependencies` | Helm-/Kubernetes-Ressourcen oder CES-Service-Account-CRs | Service-Abhängigkeiten werden, soweit passend, mit `ServiceAccountRequest` abgebildet; andere Anforderungen werden explizit im Chart modelliert. Die akzeptierte Architektur definiert keinen generischen Ersatz für sämtliche V2-Client-, Paket- und Versionsprüfungen. | -| `OptionalDependencies` | Optionaler `ServiceAccountRequest` oder zweckgebundene Chart-Ressourcen | Für optionale Service-Account-Abhängigkeiten wird ein optionaler Request verwendet. Die akzeptierte Architektur definiert keinen generischen Vertrag, der sämtliche V2-Semantiken für optionale Abhängigkeiten und Versionsprüfungen erhält. | - -## Zugehöriges Konzept - -Zurück zu [Dogu-V3-Artefakte verstehen](../concepts/artifacts_de.md) oder weiter zur [Multinode-Laufzeitumgebung](../concepts/multinode-environment_de.md). +| 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..25d5dbf --- /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 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 | — | From e81ac0dcb6cc7114c9819d73a5991b66aa24d007 Mon Sep 17 00:00:00 2001 From: nfranzeck <125264216+nfranzeck@users.noreply.github.com> Date: Mon, 10 Aug 2026 14:07:39 +0200 Subject: [PATCH 07/16] Update docs/v3/concepts/artifacts_de.md Co-authored-by: Philipp Pixel --- docs/v3/concepts/artifacts_de.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/v3/concepts/artifacts_de.md b/docs/v3/concepts/artifacts_de.md index fd56189..40603d2 100644 --- a/docs/v3/concepts/artifacts_de.md +++ b/docs/v3/concepts/artifacts_de.md @@ -82,7 +82,7 @@ Für die Plattform können globale Konfigurationparameter existieren, die nicht ```yaml apiVersion: v1 metavalues: - # Plattformspezische Konfigurationwert + # Plattformspezifische Konfigurationwert mainLogLevel: keys: # ohne Mapping wird der Konfigurationswert ohne Änderung an die values.yaml durchgereicht From c852b2e49355450e25ec649232da2ee4d426d121 Mon Sep 17 00:00:00 2001 From: nfranzeck <125264216+nfranzeck@users.noreply.github.com> Date: Mon, 10 Aug 2026 14:07:59 +0200 Subject: [PATCH 08/16] Update docs/v3/concepts/artifacts_de.md fix typo Co-authored-by: Philipp Pixel --- docs/v3/concepts/artifacts_de.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/v3/concepts/artifacts_de.md b/docs/v3/concepts/artifacts_de.md index 40603d2..b9db8a3 100644 --- a/docs/v3/concepts/artifacts_de.md +++ b/docs/v3/concepts/artifacts_de.md @@ -32,7 +32,7 @@ Neben den [Helm-Standardfeldern](https://helm.sh/docs/topics/charts/#the-chartya - `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 plattformspezischen Komponenten ignoriert, sofern sie nicht Teil der festgelegten Pflichtmetadaten sind. Als Pflichtfelder in der `Chart.yaml` gelten die Felder: +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` From aca84a443eac3802fe7b93717c72dc67e52a376f Mon Sep 17 00:00:00 2001 From: nfranzeck <125264216+nfranzeck@users.noreply.github.com> Date: Mon, 10 Aug 2026 14:08:19 +0200 Subject: [PATCH 09/16] Update docs/v3/concepts/artifacts_de.md fix typo Co-authored-by: Philipp Pixel --- docs/v3/concepts/artifacts_de.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/v3/concepts/artifacts_de.md b/docs/v3/concepts/artifacts_de.md index b9db8a3..d2abea9 100644 --- a/docs/v3/concepts/artifacts_de.md +++ b/docs/v3/concepts/artifacts_de.md @@ -118,7 +118,7 @@ spec: mainLogLevel: ERROR ``` -Um plattformspezische 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. +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` From 0f446058976742c79fe3e12f86791e9b24d1d6b5 Mon Sep 17 00:00:00 2001 From: nfranzeck <125264216+nfranzeck@users.noreply.github.com> Date: Mon, 10 Aug 2026 14:08:49 +0200 Subject: [PATCH 10/16] Update docs/v3/concepts/artifacts_de.md fix typos Co-authored-by: Philipp Pixel --- docs/v3/concepts/artifacts_de.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/v3/concepts/artifacts_de.md b/docs/v3/concepts/artifacts_de.md index d2abea9..5e40dfd 100644 --- a/docs/v3/concepts/artifacts_de.md +++ b/docs/v3/concepts/artifacts_de.md @@ -26,7 +26,7 @@ k8s/ 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/` gekenntzeichnet sind. Dieser Prefix kennzeichnet Dogu-Metadaten im Helm-Chart und grenzt sie von allgemeinen Kubernetes- oder Helm-Annotations ab. Folgende plattformspezische Annotations werden aktuell unterstützt: +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 From be872570d03093d022e37d517ce9c2a5a8680e3d Mon Sep 17 00:00:00 2001 From: nfranzeck <125264216+nfranzeck@users.noreply.github.com> Date: Mon, 10 Aug 2026 14:09:20 +0200 Subject: [PATCH 11/16] Update docs/v3/concepts/artifacts_de.md fix typos Co-authored-by: Philipp Pixel --- docs/v3/concepts/artifacts_de.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/v3/concepts/artifacts_de.md b/docs/v3/concepts/artifacts_de.md index 5e40dfd..6b389ab 100644 --- a/docs/v3/concepts/artifacts_de.md +++ b/docs/v3/concepts/artifacts_de.md @@ -77,7 +77,7 @@ Für die `values.yaml` kann mithilfe der `values.schema.json` ein Schema in Form ### `dogu-values-metadata.yaml` -Für die Plattform können globale Konfigurationparameter existieren, die nicht immer durch bestehende Werte aus der `values.yaml` eines Helm-Charts abgebildet werden können. So kann für die Plattform bespielsweise ein globales Log-Level gesetzt werden, welches für alle Dogus angewendet wird. Um diesem Umstand Rechnug 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: +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 From 35d21fc2e11bb18e438d6509720eb7dbc5371a37 Mon Sep 17 00:00:00 2001 From: nfranzeck <125264216+nfranzeck@users.noreply.github.com> Date: Mon, 10 Aug 2026 14:09:45 +0200 Subject: [PATCH 12/16] Update docs/v3/concepts/artifacts_de.md fix typo Co-authored-by: Philipp Pixel --- docs/v3/concepts/artifacts_de.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/v3/concepts/artifacts_de.md b/docs/v3/concepts/artifacts_de.md index 6b389ab..23d7f08 100644 --- a/docs/v3/concepts/artifacts_de.md +++ b/docs/v3/concepts/artifacts_de.md @@ -186,7 +186,7 @@ Eine `AuthRegistration` provisioniert nur die serverseitige Integration beim IdP ### 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:innnen 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. +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. From edd5c85fbb2cf3ec0e7ca3a162e7a395238949d9 Mon Sep 17 00:00:00 2001 From: nfranzeck <125264216+nfranzeck@users.noreply.github.com> Date: Mon, 10 Aug 2026 14:10:26 +0200 Subject: [PATCH 13/16] Update docs/v3/concepts/artifacts_de.md Co-authored-by: Philipp Pixel --- docs/v3/concepts/artifacts_de.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/v3/concepts/artifacts_de.md b/docs/v3/concepts/artifacts_de.md index 23d7f08..51dd38a 100644 --- a/docs/v3/concepts/artifacts_de.md +++ b/docs/v3/concepts/artifacts_de.md @@ -196,7 +196,7 @@ Soll ein Dogu von außen erreichbar sein, muss hierfür eine oder mehrere [`Expo ### ServiceAccountRequest / ServiceAccountProducer -Im CES (Cloudogu EcoSystem) ist es möglich, dass verschiedene Dogus miteinander interagieren. Hierfür muss für ein zugreifendes Dogu (Consumer) ein entsprechender ServiceAccount beim Ziel-Dogu (Producer) erstellt werden. +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. From 92bee3dfe550c4568bac55c7d51bf93e5a6b35b7 Mon Sep 17 00:00:00 2001 From: nfranzeck <125264216+nfranzeck@users.noreply.github.com> Date: Mon, 10 Aug 2026 14:12:22 +0200 Subject: [PATCH 14/16] Update docs/v3/concepts/artifacts_de.md Co-authored-by: Philipp Pixel --- docs/v3/concepts/artifacts_de.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/v3/concepts/artifacts_de.md b/docs/v3/concepts/artifacts_de.md index 51dd38a..6c03c9d 100644 --- a/docs/v3/concepts/artifacts_de.md +++ b/docs/v3/concepts/artifacts_de.md @@ -206,7 +206,7 @@ Bietet ein Dogu eine Schnittstelle an, die von anderen Dogus genutzt werden kann **`ServiceAccountRequest`** -Benötigt ein Dogu einen Service-Account bei einem anderen Dogu, 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 Name der ServiceAccountRequest-Ressource erstellt. Die CR bildet das Gegenstück zum `ServiceAccountProducer`. +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 From fde2048e50abd7b3e460ceb5423532b62125eca9 Mon Sep 17 00:00:00 2001 From: nfranzeck <125264216+nfranzeck@users.noreply.github.com> Date: Mon, 10 Aug 2026 14:15:07 +0200 Subject: [PATCH 15/16] Update docs/v3/concepts/artifacts_de.md Co-authored-by: Philipp Pixel --- docs/v3/concepts/artifacts_de.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/v3/concepts/artifacts_de.md b/docs/v3/concepts/artifacts_de.md index 6c03c9d..e2984da 100644 --- a/docs/v3/concepts/artifacts_de.md +++ b/docs/v3/concepts/artifacts_de.md @@ -202,7 +202,7 @@ Die ServiceAccount-Erstellung lässt sich deklarativ über die CRDs [`ServiceAcc **`ServiceAccountProducer`** -Bietet ein Dogu eine Schnittstelle an, die von anderen Dogus genutzt werden kann, muss es eine `ServiceAccountProducer-CR` bereitstellen. Die `ServiceAccountProducer` definiert, wie Service-Accounts für das Dogu erstellt werden und welche Parameter unterstützt werden. Ferner beschreibt die CR Werte, die das Dogu - der Producer - nach dem Erstellen eines Service-Accounts zurückgibt. Jeder zurückgegebene Wert wird als Schlüssel in das vom anfragenden Dogu - dem Consumer - referenzierte Secret geschrieben. +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`** From f85e998d213fc7f6d4e9f8012718410c6002060d Mon Sep 17 00:00:00 2001 From: Nico Franzeck Date: Mon, 10 Aug 2026 14:39:26 +0200 Subject: [PATCH 16/16] Update docs with suggestions from review --- docs/v3/best-practices/helm-chart_de.md | 2 +- docs/v3/best-practices/helm-chart_en.md | 4 ++-- docs/v3/concepts/artifacts_de.md | 4 +++- docs/v3/concepts/artifacts_en.md | 10 ++++++---- docs/v3/reference/compendium_de.md | 2 +- docs/v3/reference/compendium_en.md | 2 +- 6 files changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/v3/best-practices/helm-chart_de.md b/docs/v3/best-practices/helm-chart_de.md index a951867..ef85681 100644 --- a/docs/v3/best-practices/helm-chart_de.md +++ b/docs/v3/best-practices/helm-chart_de.md @@ -4,7 +4,7 @@ Dieses Dokument beschreibt die Best-Practices, die es bei der Erstellung von Dog ## 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. +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: diff --git a/docs/v3/best-practices/helm-chart_en.md b/docs/v3/best-practices/helm-chart_en.md index 875efe0..ab68e91 100644 --- a/docs/v3/best-practices/helm-chart_en.md +++ b/docs/v3/best-practices/helm-chart_en.md @@ -4,7 +4,7 @@ This document describes the best practices to follow when creating Dogu Helm cha ## 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. +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: @@ -17,4 +17,4 @@ Before changing a name, check these relationships: | 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. \ No newline at end of file +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 index e2984da..a58ee1c 100644 --- a/docs/v3/concepts/artifacts_de.md +++ b/docs/v3/concepts/artifacts_de.md @@ -21,6 +21,8 @@ k8s/ └─ 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. @@ -176,7 +178,7 @@ Die `chart-patch-tpl.yaml` sollte stets Bestandteil des Dogu-Helm-Charts sein, u ## 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 genauer beschrieben. +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 diff --git a/docs/v3/concepts/artifacts_en.md b/docs/v3/concepts/artifacts_en.md index 7ecd296..eb4e3b7 100644 --- a/docs/v3/concepts/artifacts_en.md +++ b/docs/v3/concepts/artifacts_en.md @@ -21,6 +21,8 @@ k8s/ └─ 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. @@ -176,7 +178,7 @@ The `chart-patch-tpl.yaml` should always be part of the Dogu Helm chart in order ## 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 in more detail. +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 @@ -196,17 +198,17 @@ If a Dogu is supposed to be reachable from the outside, one or more [`Exposition ### ServiceAccountRequest / ServiceAccountProducer -In the CES it is possible for different Dogus to interact with each other. For this, an appropriate ServiceAccount must be created at the target Dogu (Producer) for an accessing Dogu (Consumer). +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 Dogu offers an interface that can be used by other Dogus, it must provide a `ServiceAccountProducer-CR`. The `ServiceAccountProducer` defines how service accounts are created for the Dogu and which parameters are supported. Furthermore, the CR describes values that the Dogu – the Producer – returns after creating a service account. Each returned value is written as a key into the Secret referenced by the requesting Dogu – the Consumer. +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 Dogu needs a service account for another Dogu, 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 consuming Dogu. 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`. +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 diff --git a/docs/v3/reference/compendium_de.md b/docs/v3/reference/compendium_de.md index 0cd0131..b113ba3 100644 --- a/docs/v3/reference/compendium_de.md +++ b/docs/v3/reference/compendium_de.md @@ -1,6 +1,6 @@ # Kompendium der Dogu-V3-Artefakte -Dieses Kompendium gibt einen Überblick über die Artefakte und APIs von Dogu V3. Eine Einführung in ihr Zusammenspiel finden Sie unter [Dogu- Artefakte](../concepts/artifacts_de.md). +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 diff --git a/docs/v3/reference/compendium_en.md b/docs/v3/reference/compendium_en.md index 25d5dbf..4da5371 100644 --- a/docs/v3/reference/compendium_en.md +++ b/docs/v3/reference/compendium_en.md @@ -1,6 +1,6 @@ # Dogu V3 Artifact Compendium -This compendium provides an overview of the artifacts and APIs of Dogu V3. For an introduction to how they work together, read [Dogu Artifacts](../concepts/artifacts_en.md). +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