From 26e87e4d52e0728d2b9fe7a7230e5a6ec617dd89 Mon Sep 17 00:00:00 2001 From: uwe-mayer Date: Thu, 9 Oct 2025 15:02:13 +0200 Subject: [PATCH 1/7] feat(docs): adds LCM docs --- docs/user-guides/plugin/lifecycle.md | 212 +++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 docs/user-guides/plugin/lifecycle.md diff --git a/docs/user-guides/plugin/lifecycle.md b/docs/user-guides/plugin/lifecycle.md new file mode 100644 index 000000000..20214873a --- /dev/null +++ b/docs/user-guides/plugin/lifecycle.md @@ -0,0 +1,212 @@ +--- +title: "Plugin Lifecycle Management" +linkTitle: "Plugin LCM" +weight: 5 +description: > + Software lifecycle management done the Greenhouse way +--- + +## What is Plugin Lifecycle Management (LCM)? + +When we are talking about Plugin LCM we refer to the active maintenance phase of software provided as Greenhouse Plugins. This includes tasks as: + +- Bug fixing +- Feature shipping +- Dependency updates +- Version upgrades +- and more... + +The following features are offered via Greenhouse: + +| Feature | Status | +|---------------------------|:-----------:| +| Automatic Updates | 🟩 | +| Automatic Rollback on Failing Updates | 🟩 | +| Version Constraining/Pinning | 🟨 | +| Staged Rollout | 🟨 | + +## Involved actors + +### Plugin Developers + +These are the people providing the Plugins that can be used with Greenhouse. These Plugins are offered via (Cluster-)Plugindefinitions. +Plugin developers ensure that PluginDefinition versions follow strict [SemVer](https://semver.org/). + +They control + +- The code of the Plugin including the Helm chart and possible frontend code. +- Default PluginDefinition +- Default Catalog(s) +- The repository the PluginDefinitions and Catalogs live in + +### Plugin Consumers + +People configuring Plugins in their Organizations. + +They control the actual resources deployed to their Greenhouse Organization: + +- Custom Catalogs +- PluginDefinitions +- PluginPresets (& Plugins) + +### Ivolved Resources + +#### [Catalogs](./../../reference/api/index.html#greenhouse.sap/v1alpha1.Catalog) + +Catalogs enable Greenhouse Organizations to import the PluginDefinitions they want to use. Leveraging the underlying [flux](https://fluxcd.io/) machinery, a Catalog item targets a `kustomization.yaml` living in a git repository. + +This might be either + +- the default kustomization provided by Plugin developers +- or a custom kustomization suited to the needs of your Organization + +The Catalog resource allows you to target the `kustomization.yaml` via `branch`, `tag` or `commit` in the `.Spec.Source.Git.Ref` field. + +#### [PluginDefinitions](./../../reference/api/index.htmlgreenhouse.sap/v1alpha1.PluginDefinition) + +PluginDefinitions bundle backend and frontend packages with configuration. Backends are shipped as [Helm charts](https://helm.sh/) and frontends as [React components](https://react.dev/reference/react/Component). + +All PluginDefinitions are versioned (`.Spec.Version`) with [SemVer](https://semver.org/). + +#### [PluginPresets](./../../reference/api/index.htmlgreenhouse.sap/v1alpha1.PluginPresets) + +PluginPresets allow you to configure a set of Plugins to be deployed to a set of Clusters referencing a PluginDefinition. + +🟨 In development: +PluginPresets allow to pin or constrain deployed versions via the `.Spec.PluginDefinitionReference.Version` field with [semantic version constraints](https://jubianchi.github.io/semver-check/). + +### Features + +#### Automatic Updates + +**All** updates and upgrades (`major`, `minor` and `patch`) made to a PluginDefinition are shipped to all referencing Plugin(Presets) by default via the Greenhouse controller if no version constraint is set. + +Greenhouse per default follows a fix forward update strategy. + +We strongly encourage Plugin Consumers to always keep their Plugin versions up to date. All Greenhouse provided processes aim at easing upgrades or provide auto upgrade strategies. + +#### Automatic Rollback on Failure + +The underlying flux machinery's [`.spec.upgrade.remediation` is set to `rollback`](https://fluxcd.io/flux/components/helm/helmreleases/#upgrade-remediation). This will keep the Plugins running even if updates or upgrades fail. + +#### Version Pinning and Constraints + +Until the `Plugin.Spec.PluginDefinitionReference.Version` field and its automation is fully implemented, we suggest to use custom Catalogs to maintain versioned PluginDefinitions in your Organization. You can do so by + +- pinning versions of PluginDefinitions +- pinning version of a Catalog + +versioned in a git repository. + +##### Pinning PluginDefinition versions + +Maintain a `kustomization.yaml` file targeting specific PluginDefinitions as resources, via git `commits`, `tags` or `branches`. +E.g.: + +```yaml +resources: +# reference by branch +- https://raw.githubusercontent.com/cloudoperators/greenhouse-extensions/refs/heads/main/cert-manager/plugindefinition.yaml +# reference by commit +- https://raw.githubusercontent.com/cloudoperators/greenhouse-extensions/6c41128df8d9ff72c63aee7e3d3122468490ea21/ingress-nginx/plugindefinition.yaml +# reference by tag +- https://raw.githubusercontent.com/cloudoperators/greenhouse-extensions/refs/tags/v0.0.2/kube-monitoring/plugindefinition.yaml +``` + +Point your Catalog to this `kustomization.yaml` and **alias** the PluginDefinition `name`: + +```yaml +apiVersion: greenhouse.sap/v1alpha1 +kind: Catalog +metadata: + name: my-custom-catalog + namespace: {{ .Release.Namespace }} +spec: + source: + git: + url: https:// + ref: + branch: main + path: path/to/kustomization + overrides: + - name: cert-manager + alias: cert-manager-custom + - name: ingress-nginx + alias: ingress-nginx-custom + - name: kube-monitoring + alias: kube-monitoring-custom + +``` + +!Note: +> There is currently some restrictions in targeting raw data on Github Enterprise installations with flux. Maintain the `kustomization.yaml` together with the targeted PluginDefinitions in one repository targeted by the Catalog instead. + +##### Pinning Catalogs + +Point your Catalog to an existing `kustomization.yaml` and optionally alias the PluginDefintion `name`: + +```yaml +apiVersion: greenhouse.sap/v1alpha1 +kind: Catalog +metadata: + name: greenhouse-extensions-pinned + namespace: {{ .Release.Namespace }} +spec: + source: + git: + url: https://github.com/cloudoperators/greenhouse-extensions + ref: + sha: + overrides: + - name: alerts + alias: alerts-pinned + - name: audit-logs + alias: audit-logs-pinned + ... + +``` + +#### Staged rollouts + +Until Greenhouse has an inhouse solution for staging rollouts, we suggest you use [renovate](https://github.com/renovatebot/renovate) configuration in combination to `git tags` to stage rollouts of PluginDefinition versions. + +The following steps are needed: + +1. Plugin developers need to `git tag` their PluginDefinitions and/or Catalogs. +2. Have renovate open PRs to update the resources in your `kustomization.yaml` or in your `catalog.yaml`. + + E.g. + + + ```json + "customManagers": [ + { + "customType": "regex", + "description": "Bump kube-monitoring version in kustomize", + "managerFilePatterns": [ + "/(^|/)kustomization\\.ya?ml$/" + ], + "matchStrings": [ + "https://raw.githubusercontent.com/cloudoperators/greenhouse-extensions/refs/tags/(?.*?)/kube-monitoring/plugindefinition.yaml" + ], + "datasource": "git-tags", + "depNameTemplate": "cloudoperators/kube-monitoring" + } + ] + ``` + +3. Maintain different `kustomization.yaml` or `catalog.yaml` for your stages. + + ```md + catalogs/ + ├── bronze/ + │ └── kustomization.yaml + ├── silver/ + │ └── kustomization.yaml + └── gold/ + └── kustomization.yaml + + ``` + + +4. Set renovate PRs to `automerge` and configure a `schedule` for the different stages. With no manual interaction (e.g. blocking PRs) you will roll through your stages based on your schedule. From 217f0419d8a2ff9d482d38305242468358e0ec59 Mon Sep 17 00:00:00 2001 From: Uwe Mayer <115539431+uwe-mayer@users.noreply.github.com> Date: Fri, 24 Oct 2025 10:34:04 +0200 Subject: [PATCH 2/7] Update docs/user-guides/plugin/lifecycle.md Co-authored-by: Akshay Iyyadurai Balasundaram --- docs/user-guides/plugin/lifecycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guides/plugin/lifecycle.md b/docs/user-guides/plugin/lifecycle.md index 20214873a..ee72372cb 100644 --- a/docs/user-guides/plugin/lifecycle.md +++ b/docs/user-guides/plugin/lifecycle.md @@ -49,7 +49,7 @@ They control the actual resources deployed to their Greenhouse Organization: - PluginDefinitions - PluginPresets (& Plugins) -### Ivolved Resources +### Involved Resources #### [Catalogs](./../../reference/api/index.html#greenhouse.sap/v1alpha1.Catalog) From e24fb8c344a0c855a9d91891f5f39b75f6586cc6 Mon Sep 17 00:00:00 2001 From: Uwe Mayer <115539431+uwe-mayer@users.noreply.github.com> Date: Fri, 24 Oct 2025 10:34:15 +0200 Subject: [PATCH 3/7] Update docs/user-guides/plugin/lifecycle.md Co-authored-by: Akshay Iyyadurai Balasundaram --- docs/user-guides/plugin/lifecycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guides/plugin/lifecycle.md b/docs/user-guides/plugin/lifecycle.md index ee72372cb..717cee7b3 100644 --- a/docs/user-guides/plugin/lifecycle.md +++ b/docs/user-guides/plugin/lifecycle.md @@ -37,7 +37,7 @@ They control - The code of the Plugin including the Helm chart and possible frontend code. - Default PluginDefinition - Default Catalog(s) -- The repository the PluginDefinitions and Catalogs live in +- The repository where the PluginDefinitions and Catalogs live in ### Plugin Consumers From 4937f160b665de51157a481c294f1f680da0e668 Mon Sep 17 00:00:00 2001 From: Uwe Mayer <115539431+uwe-mayer@users.noreply.github.com> Date: Fri, 24 Oct 2025 10:34:24 +0200 Subject: [PATCH 4/7] Update docs/user-guides/plugin/lifecycle.md Co-authored-by: Akshay Iyyadurai Balasundaram --- docs/user-guides/plugin/lifecycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guides/plugin/lifecycle.md b/docs/user-guides/plugin/lifecycle.md index 717cee7b3..ddf553c23 100644 --- a/docs/user-guides/plugin/lifecycle.md +++ b/docs/user-guides/plugin/lifecycle.md @@ -8,7 +8,7 @@ description: > ## What is Plugin Lifecycle Management (LCM)? -When we are talking about Plugin LCM we refer to the active maintenance phase of software provided as Greenhouse Plugins. This includes tasks as: +When we are talking about Plugin LCM we refer to the active maintenance phase of software provided as Greenhouse Plugins. This includes tasks such as: - Bug fixing - Feature shipping From 641615b92c114d4a40b7ad142dae9f87293aa90d Mon Sep 17 00:00:00 2001 From: Uwe Mayer <115539431+uwe-mayer@users.noreply.github.com> Date: Fri, 24 Oct 2025 10:34:37 +0200 Subject: [PATCH 5/7] Update docs/user-guides/plugin/lifecycle.md Co-authored-by: Akshay Iyyadurai Balasundaram --- docs/user-guides/plugin/lifecycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guides/plugin/lifecycle.md b/docs/user-guides/plugin/lifecycle.md index ddf553c23..9944c5d9f 100644 --- a/docs/user-guides/plugin/lifecycle.md +++ b/docs/user-guides/plugin/lifecycle.md @@ -168,7 +168,7 @@ spec: #### Staged rollouts -Until Greenhouse has an inhouse solution for staging rollouts, we suggest you use [renovate](https://github.com/renovatebot/renovate) configuration in combination to `git tags` to stage rollouts of PluginDefinition versions. +Until Greenhouse has an inhouse solution for staging rollouts, we suggest you to use [renovate](https://github.com/renovatebot/renovate) configuration in combination to `git tags` to stage rollouts of PluginDefinition versions. The following steps are needed: From 475f2d13dd1ac02e6e5cd005c12f2db0fd5a5b1d Mon Sep 17 00:00:00 2001 From: uwe-mayer Date: Wed, 29 Apr 2026 10:50:08 +0200 Subject: [PATCH 6/7] docs(plugin): update lifecycle docs to reflect current API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update version pinning status to 🟩 (implemented via Catalog git refs) - Fix broken API reference links (missing # separator) - Add Flux GitRepository/Kustomization explanation for Catalogs - Update frontend reference from React components to Juno Applications - Remove outdated 'in development' section about Version field - Add clear explanation of branch/tag/SHA pinning strategies - Fix YAML examples to not use Helm template syntax - Remove TODO HTML comments - Fix typos and grammar --- docs/user-guides/plugin/lifecycle.md | 178 +++++++++++++-------------- 1 file changed, 88 insertions(+), 90 deletions(-) diff --git a/docs/user-guides/plugin/lifecycle.md b/docs/user-guides/plugin/lifecycle.md index 9944c5d9f..2fcf44098 100644 --- a/docs/user-guides/plugin/lifecycle.md +++ b/docs/user-guides/plugin/lifecycle.md @@ -22,7 +22,7 @@ The following features are offered via Greenhouse: |---------------------------|:-----------:| | Automatic Updates | 🟩 | | Automatic Rollback on Failing Updates | 🟩 | -| Version Constraining/Pinning | 🟨 | +| Version Constraining/Pinning | 🟩 | | Staged Rollout | 🟨 | ## Involved actors @@ -35,9 +35,8 @@ Plugin developers ensure that PluginDefinition versions follow strict [SemVer](h They control - The code of the Plugin including the Helm chart and possible frontend code. -- Default PluginDefinition -- Default Catalog(s) -- The repository where the PluginDefinitions and Catalogs live in +- The PluginDefinition manifests +- The repository where the PluginDefinitions live in ### Plugin Consumers @@ -45,7 +44,7 @@ People configuring Plugins in their Organizations. They control the actual resources deployed to their Greenhouse Organization: -- Custom Catalogs +- Catalogs - PluginDefinitions - PluginPresets (& Plugins) @@ -53,33 +52,32 @@ They control the actual resources deployed to their Greenhouse Organization: #### [Catalogs](./../../reference/api/index.html#greenhouse.sap/v1alpha1.Catalog) -Catalogs enable Greenhouse Organizations to import the PluginDefinitions they want to use. Leveraging the underlying [flux](https://fluxcd.io/) machinery, a Catalog item targets a `kustomization.yaml` living in a git repository. +Catalogs enable Greenhouse Organizations to import the PluginDefinitions they want to use. -This might be either +A Catalog resource points to a Git repository that contains PluginDefinition (or ClusterPluginDefinition) manifests. It is defined by: -- the default kustomization provided by Plugin developers -- or a custom kustomization suited to the needs of your Organization +- **`spec.source.git.url`** — the URL of the Git repository containing the PluginDefinition manifests. +- **`spec.source.git.ref`** — an optional Git reference to pin the catalog to a specific `branch`, `tag`, or `sha` (commit). If omitted, defaults to the repository's default branch. +- **`spec.source.path`** — an optional path within the repository where the manifests are located (defaults to the repository root). +- **`spec.overrides`** — an optional list of overrides to rename/alias PluginDefinitions via Kustomize patches. Each override specifies a `name` (original PluginDefinition name) and an `alias` (new name to apply). -The Catalog resource allows you to target the `kustomization.yaml` via `branch`, `tag` or `commit` in the `.Spec.Source.Git.Ref` field. +Under the hood, the Catalog controller creates a Flux [GitRepository](https://fluxcd.io/flux/components/source/gitrepositories/) and a [Kustomization](https://fluxcd.io/flux/components/kustomize/kustomizations/) to continuously sync PluginDefinitions from the referenced Git repository into the Organization namespace. -#### [PluginDefinitions](./../../reference/api/index.htmlgreenhouse.sap/v1alpha1.PluginDefinition) +#### [PluginDefinitions](./../../reference/api/index.html#greenhouse.sap/v1alpha1.PluginDefinition) -PluginDefinitions bundle backend and frontend packages with configuration. Backends are shipped as [Helm charts](https://helm.sh/) and frontends as [React components](https://react.dev/reference/react/Component). +PluginDefinitions bundle backend and frontend packages with configuration. Backends are shipped as [Helm charts](https://helm.sh/) and frontends as [Juno Applications](https://github.com/cloudoperators/juno). All PluginDefinitions are versioned (`.Spec.Version`) with [SemVer](https://semver.org/). -#### [PluginPresets](./../../reference/api/index.htmlgreenhouse.sap/v1alpha1.PluginPresets) +#### [PluginPresets](./../../reference/api/index.html#greenhouse.sap/v1alpha1.PluginPreset) PluginPresets allow you to configure a set of Plugins to be deployed to a set of Clusters referencing a PluginDefinition. -🟨 In development: -PluginPresets allow to pin or constrain deployed versions via the `.Spec.PluginDefinitionReference.Version` field with [semantic version constraints](https://jubianchi.github.io/semver-check/). - ### Features #### Automatic Updates -**All** updates and upgrades (`major`, `minor` and `patch`) made to a PluginDefinition are shipped to all referencing Plugin(Presets) by default via the Greenhouse controller if no version constraint is set. +**All** updates and upgrades (`major`, `minor` and `patch`) made to a PluginDefinition are shipped to all referencing Plugin(Presets) by default via the Greenhouse controller. Greenhouse per default follows a fix forward update strategy. @@ -91,122 +89,122 @@ The underlying flux machinery's [`.spec.upgrade.remediation` is set to `rollback #### Version Pinning and Constraints -Until the `Plugin.Spec.PluginDefinitionReference.Version` field and its automation is fully implemented, we suggest to use custom Catalogs to maintain versioned PluginDefinitions in your Organization. You can do so by - -- pinning versions of PluginDefinitions -- pinning version of a Catalog +Versioning of a PluginDefinition is achieved with the Catalog resource. Since a Catalog references a Git repository via `spec.source.git`, you control which PluginDefinition versions are available in your Organization by controlling the Git reference: -versioned in a git repository. +- **Branch tracking** (e.g. `branch: main`): You always get the latest PluginDefinitions as they are committed to the branch. This is the default behavior and enables automatic updates. +- **Tag pinning** (e.g. `tag: "kube-monitoring/1.2.3"`): You only get PluginDefinitions as of that tagged commit. Updates only happen when you change the tag reference. +- **SHA pinning** (e.g. `sha: "a1b2c3d4e5f6..."`): You freeze to an exact commit. This provides the strongest version guarantee. ##### Pinning PluginDefinition versions -Maintain a `kustomization.yaml` file targeting specific PluginDefinitions as resources, via git `commits`, `tags` or `branches`. -E.g.: +Reference by branch (always track latest): ```yaml -resources: -# reference by branch -- https://raw.githubusercontent.com/cloudoperators/greenhouse-extensions/refs/heads/main/cert-manager/plugindefinition.yaml -# reference by commit -- https://raw.githubusercontent.com/cloudoperators/greenhouse-extensions/6c41128df8d9ff72c63aee7e3d3122468490ea21/ingress-nginx/plugindefinition.yaml -# reference by tag -- https://raw.githubusercontent.com/cloudoperators/greenhouse-extensions/refs/tags/v0.0.2/kube-monitoring/plugindefinition.yaml +apiVersion: greenhouse.sap/v1alpha1 +kind: Catalog +metadata: + name: my-catalog + namespace: my-org +spec: + source: + git: + url: https://github.com/cloudoperators/greenhouse-extensions + ref: + branch: main + path: plugindefinitions ``` -Point your Catalog to this `kustomization.yaml` and **alias** the PluginDefinition `name`: +Reference by tag (pin to a specific release): ```yaml apiVersion: greenhouse.sap/v1alpha1 kind: Catalog metadata: - name: my-custom-catalog - namespace: {{ .Release.Namespace }} + name: my-catalog-pinned + namespace: my-org spec: source: git: - url: https:// + url: https://github.com/cloudoperators/greenhouse-extensions ref: - branch: main - path: path/to/kustomization - overrides: - - name: cert-manager - alias: cert-manager-custom - - name: ingress-nginx - alias: ingress-nginx-custom - - name: kube-monitoring - alias: kube-monitoring-custom - + tag: "kube-monitoring/1.2.3" + path: plugindefinitions ``` -!Note: -> There is currently some restrictions in targeting raw data on Github Enterprise installations with flux. Maintain the `kustomization.yaml` together with the targeted PluginDefinitions in one repository targeted by the Catalog instead. +Reference by commit SHA (freeze to exact state): + +```yaml +apiVersion: greenhouse.sap/v1alpha1 +kind: Catalog +metadata: + name: my-catalog-frozen + namespace: my-org +spec: + source: + git: + url: https://github.com/cloudoperators/greenhouse-extensions + ref: + sha: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" + path: plugindefinitions +``` -##### Pinning Catalogs +##### Overriding PluginDefinition names -Point your Catalog to an existing `kustomization.yaml` and optionally alias the PluginDefintion `name`: +You can use `spec.overrides` to alias PluginDefinitions, for example to run multiple configurations of the same PluginDefinition side by side: ```yaml apiVersion: greenhouse.sap/v1alpha1 kind: Catalog metadata: - name: greenhouse-extensions-pinned - namespace: {{ .Release.Namespace }} + name: my-custom-catalog + namespace: my-org spec: source: git: - url: https://github.com/cloudoperators/greenhouse-extensions + url: https://github.com/my-org/my-plugin-catalog ref: - sha: + branch: main + path: plugindefinitions overrides: - - name: alerts - alias: alerts-pinned - - name: audit-logs - alias: audit-logs-pinned - ... - + - name: cert-manager + alias: cert-manager-custom + - name: ingress-nginx + alias: ingress-nginx-custom + - name: kube-monitoring + alias: kube-monitoring-custom ``` #### Staged rollouts -Until Greenhouse has an inhouse solution for staging rollouts, we suggest you to use [renovate](https://github.com/renovatebot/renovate) configuration in combination to `git tags` to stage rollouts of PluginDefinition versions. +Until Greenhouse has an inhouse solution for staging rollouts, we suggest you use [renovate](https://github.com/renovatebot/renovate) configuration in combination with `git tags` to stage rollouts of PluginDefinition versions. The following steps are needed: -1. Plugin developers need to `git tag` their PluginDefinitions and/or Catalogs. -2. Have renovate open PRs to update the resources in your `kustomization.yaml` or in your `catalog.yaml`. +1. Plugin developers need to `git tag` their PluginDefinitions and/or Catalogs. The tagging convention is `/` (e.g. `kube-monitoring/1.2.3`). + + > **Tip:** Automate this with a CI workflow that reads `.spec.version` from `plugindefinition.yaml` on push to `main` and creates the corresponding git tag. + +2. Have renovate open PRs to update the resources in your Catalogs. The following example shows a renovate configuration for a Catalog maintained with a Helm Chart that expects values to be nested in `common.catalogs`: E.g. - ```json "customManagers": [ - { - "customType": "regex", - "description": "Bump kube-monitoring version in kustomize", - "managerFilePatterns": [ - "/(^|/)kustomization\\.ya?ml$/" - ], - "matchStrings": [ - "https://raw.githubusercontent.com/cloudoperators/greenhouse-extensions/refs/tags/(?.*?)/kube-monitoring/plugindefinition.yaml" - ], - "datasource": "git-tags", - "depNameTemplate": "cloudoperators/kube-monitoring" - } - ] + { + "customType": "jsonata", + "fileFormat": "yaml", + "description": "Update catalog tags in values.yaml (github.com)", + "managerFilePatterns": [ + "/values\\.yaml$/" + ], + "matchStrings": [ + "common.catalogs.*.sources[ref.tag and $match(ref.tag, /^[^\\/]+\\/\\d+\\.\\d+\\.\\d+$/) and $contains(repository, 'github.com')].({\"depName\": $split(ref.tag, '/')[0], \"packageName\": $substringAfter(repository, 'https://github.com/'), \"currentValue\": ref.tag, \"datasource\": 'github-tags', \"registryUrl\": 'https://github.com', \"versioning\": 'regex:^' & $split(ref.tag, '/')[0] & '/(?\\\\d+)\\\\.(?\\\\d+)\\\\.(?\\\\d+)$'})" + ] + } + + ], ``` -3. Maintain different `kustomization.yaml` or `catalog.yaml` for your stages. - - ```md - catalogs/ - ├── bronze/ - │ └── kustomization.yaml - ├── silver/ - │ └── kustomization.yaml - └── gold/ - └── kustomization.yaml - - ``` +1. Maintain different Catalogs for your stages. - -4. Set renovate PRs to `automerge` and configure a `schedule` for the different stages. With no manual interaction (e.g. blocking PRs) you will roll through your stages based on your schedule. +2. Set renovate PRs to `automerge` and configure a `schedule` for the different stages. With no manual interaction (e.g. blocking PRs) you will roll through your stages based on your schedule. From 6bd0bfa037a9b1c4593900ab427ba2300b1ef3d1 Mon Sep 17 00:00:00 2001 From: uwe-mayer Date: Fri, 8 May 2026 15:11:14 +0200 Subject: [PATCH 7/7] PR remarks --- docs/reference/components/catalog.md | 73 ++++++++++++++++--- docs/user-guides/plugin/lifecycle.md | 100 ++------------------------- 2 files changed, 70 insertions(+), 103 deletions(-) diff --git a/docs/reference/components/catalog.md b/docs/reference/components/catalog.md index 795571f08..416bf7c88 100644 --- a/docs/reference/components/catalog.md +++ b/docs/reference/components/catalog.md @@ -3,14 +3,14 @@ title: "Catalogs" weight: 5 --- -A Catalog is a collection of PluginDefinitions that can be made available to Organizations within Greenhouse. +A Catalog is a collection of PluginDefinitions that can be made available to Organizations within Greenhouse. Catalogs allow organization admins to manage the lifecycle of PluginDefinitions by controlling which version of a PluginDefinition is deployed to their cluster fleet. > The Catalog API is currently in **alpha** and is still under active development and is subjected to change. ## Example -The following is an example of a Greenhouse Catalog that reconciles the PluginDefinition manifests stored in a Git Repository. +The following is an example of a Greenhouse Catalog that reconciles the PluginDefinition manifests stored in a Git Repository. ```yaml apiVersion: greenhouse.sap/v1alpha1 @@ -42,13 +42,12 @@ In the above example: - The Catalog is configured to target specific `PluginDefinition` manifests stored in a path within the repository specified under `.spec.sources[].resources[]`. - The Catalog watches for changes in the specified Git Repository branch and reconciles the `PluginDefinitions` in the Organization namespace accordingly. - ## Writing a Catalog Spec ### Sources `.spec.sources` is a list of sources from which the Catalog will fetch PluginDefinition manifests. Currently, only Git repositories are supported as sources. -Each source requires a `repository` URL and a list of `resources` that specify the paths to the PluginDefinition manifests within the repository. +Each source requires a `repository` URL and a list of `resources` that specify the paths to the PluginDefinition manifests within the repository. The `ref` field is used to specify the branch, tag, or commit SHA to fetch from the repository. ⚠️ Each Organization has a dedicated ServiceAccount used to apply the Catalog resources. This ServiceAccount only has permissions to apply PluginDefinitions into the Organization's Namespace. It will not be possible to bring other Kinds using the Catalog. @@ -77,6 +76,59 @@ The priority order is: _sha_ > _tag_ > _branch_. If multiple fields are specifie > When multiple sources are defined with the same repository and ref, a duplicate error will be raised. +#### Examples + +Reference by branch (always track latest — this is the default behavior and enables automatic updates): + +```yaml +apiVersion: greenhouse.sap/v1alpha1 +kind: Catalog +metadata: + name: my-catalog + namespace: my-org +spec: + sources: + - repository: https://github.com/cloudoperators/greenhouse-extensions + resources: + - kube-monitoring/plugindefinition.yaml + ref: + branch: main +``` + +Reference by tag (pin to a specific release — updates only happen when you change the tag): + +```yaml +apiVersion: greenhouse.sap/v1alpha1 +kind: Catalog +metadata: + name: my-catalog-pinned + namespace: my-org +spec: + sources: + - repository: https://github.com/cloudoperators/greenhouse-extensions + resources: + - kube-monitoring/plugindefinition.yaml + ref: + tag: "kube-monitoring/1.2.3" +``` + +Reference by commit SHA (freeze to an exact commit — provides the strongest version guarantee): + +```yaml +apiVersion: greenhouse.sap/v1alpha1 +kind: Catalog +metadata: + name: my-catalog-frozen + namespace: my-org +spec: + sources: + - repository: https://github.com/cloudoperators/greenhouse-extensions + resources: + - kube-monitoring/plugindefinition.yaml + ref: + sha: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" +``` + ### Interval (Optional) `.spec.sources[].interval` is an optional field that specifies how often the Catalog should check for updates in the source repository. @@ -97,7 +149,7 @@ The Secret must be in the same namespace as the Catalog resource. ### Overrides (Optional) -`.spec.sources[].overrides` is an optional field that allows specifying overrides for specific PluginDefinitions in the Catalog. +`.spec.sources[].overrides` is an optional field that allows specifying overrides for specific PluginDefinitions in the Catalog. This can be used to customize certain fields of PluginDefinitions. Currently, you can override the following fields: @@ -107,7 +159,7 @@ Currently, you can override the following fields: ## Working with Catalog -### Configuring Secret for Basic Authentication: +### Configuring Secret for Basic Authentication To authenticate towards a Git repository over HTTPS using basic access authentication (in other words: using a username and password), the referenced Secret is expected to contain `.data.username` and `.data.password` values. @@ -126,7 +178,7 @@ data: > password is the Personal Access Token (PAT) for accessing the Git repository. -### Configure Secret for GitHub App authentication: +### Configure Secret for GitHub App authentication Pre-requisites: @@ -220,6 +272,7 @@ spec: PluginDefinitions can define configuration options with default values in their `.spec.options[]` array. You can override these default values using the `optionsOverride` field in the Catalog overrides. This is useful when you want to: + - Provide different default values for different environments (dev, staging, production) - Customize plugin behavior without modifying the original PluginDefinition - Set organization-specific defaults for plugins @@ -264,12 +317,12 @@ The annotation also blocks the deletion of the Catalog resource until the annota The Catalog resource orchestrates a combination of Flux resources to fetch and apply PluginDefinitions. The Flux resources managed by Catalog have their own reconciliation intervals. To trigger an immediate reconciliation of the Catalog and its managed resources, the annotation `greenhouse.sap/reconcile` can be set. -This can be useful to trigger an immediate reconciliation when the source repository has changed, and you want to apply +This can be useful to trigger an immediate reconciliation when the source repository has changed, and you want to apply the changes without waiting for the next scheduled reconciliation. ### Troubleshooting -Greenhouse uses [FluxCD](https://fluxcd.io/) under the hood to reconcile Catalog sources and +Greenhouse uses [FluxCD](https://fluxcd.io/) under the hood to reconcile Catalog sources and for each source a map of grouped status inventory is shown. Run `kubectl get cat -n ` to see the reconciliation status. @@ -369,7 +422,7 @@ In case of authentication failures due to invalid credentials, you will see erro type: Ready ``` -PluginDefinitions referenced in `.spec.sources[].resources` are accumulated using Flux ArtifactGenerator. Run `kubectl get artifactgenerator generator-9689366613293914683 -n greenhouse` to see the status. +PluginDefinitions referenced in `.spec.sources[].resources` are accumulated using Flux ArtifactGenerator. Run `kubectl get artifactgenerator generator-9689366613293914683 -n greenhouse` to see the status. ```shell NAME AGE READY STATUS diff --git a/docs/user-guides/plugin/lifecycle.md b/docs/user-guides/plugin/lifecycle.md index 2fcf44098..13c516d53 100644 --- a/docs/user-guides/plugin/lifecycle.md +++ b/docs/user-guides/plugin/lifecycle.md @@ -52,16 +52,9 @@ They control the actual resources deployed to their Greenhouse Organization: #### [Catalogs](./../../reference/api/index.html#greenhouse.sap/v1alpha1.Catalog) -Catalogs enable Greenhouse Organizations to import the PluginDefinitions they want to use. +Catalogs enable Greenhouse Organizations to import the PluginDefinitions they want to use. A Catalog resource points to a Git repository that contains PluginDefinition (or ClusterPluginDefinition) manifests and continuously syncs them into the Organization namespace. -A Catalog resource points to a Git repository that contains PluginDefinition (or ClusterPluginDefinition) manifests. It is defined by: - -- **`spec.source.git.url`** — the URL of the Git repository containing the PluginDefinition manifests. -- **`spec.source.git.ref`** — an optional Git reference to pin the catalog to a specific `branch`, `tag`, or `sha` (commit). If omitted, defaults to the repository's default branch. -- **`spec.source.path`** — an optional path within the repository where the manifests are located (defaults to the repository root). -- **`spec.overrides`** — an optional list of overrides to rename/alias PluginDefinitions via Kustomize patches. Each override specifies a `name` (original PluginDefinition name) and an `alias` (new name to apply). - -Under the hood, the Catalog controller creates a Flux [GitRepository](https://fluxcd.io/flux/components/source/gitrepositories/) and a [Kustomization](https://fluxcd.io/flux/components/kustomize/kustomizations/) to continuously sync PluginDefinitions from the referenced Git repository into the Organization namespace. +For full configuration details, see the [Catalog reference documentation](https://cloudoperators.github.io/greenhouse/docs/reference/components/catalog/). #### [PluginDefinitions](./../../reference/api/index.html#greenhouse.sap/v1alpha1.PluginDefinition) @@ -89,90 +82,11 @@ The underlying flux machinery's [`.spec.upgrade.remediation` is set to `rollback #### Version Pinning and Constraints -Versioning of a PluginDefinition is achieved with the Catalog resource. Since a Catalog references a Git repository via `spec.source.git`, you control which PluginDefinition versions are available in your Organization by controlling the Git reference: - -- **Branch tracking** (e.g. `branch: main`): You always get the latest PluginDefinitions as they are committed to the branch. This is the default behavior and enables automatic updates. -- **Tag pinning** (e.g. `tag: "kube-monitoring/1.2.3"`): You only get PluginDefinitions as of that tagged commit. Updates only happen when you change the tag reference. -- **SHA pinning** (e.g. `sha: "a1b2c3d4e5f6..."`): You freeze to an exact commit. This provides the strongest version guarantee. - -##### Pinning PluginDefinition versions - -Reference by branch (always track latest): - -```yaml -apiVersion: greenhouse.sap/v1alpha1 -kind: Catalog -metadata: - name: my-catalog - namespace: my-org -spec: - source: - git: - url: https://github.com/cloudoperators/greenhouse-extensions - ref: - branch: main - path: plugindefinitions -``` - -Reference by tag (pin to a specific release): - -```yaml -apiVersion: greenhouse.sap/v1alpha1 -kind: Catalog -metadata: - name: my-catalog-pinned - namespace: my-org -spec: - source: - git: - url: https://github.com/cloudoperators/greenhouse-extensions - ref: - tag: "kube-monitoring/1.2.3" - path: plugindefinitions -``` - -Reference by commit SHA (freeze to exact state): - -```yaml -apiVersion: greenhouse.sap/v1alpha1 -kind: Catalog -metadata: - name: my-catalog-frozen - namespace: my-org -spec: - source: - git: - url: https://github.com/cloudoperators/greenhouse-extensions - ref: - sha: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" - path: plugindefinitions -``` - -##### Overriding PluginDefinition names - -You can use `spec.overrides` to alias PluginDefinitions, for example to run multiple configurations of the same PluginDefinition side by side: - -```yaml -apiVersion: greenhouse.sap/v1alpha1 -kind: Catalog -metadata: - name: my-custom-catalog - namespace: my-org -spec: - source: - git: - url: https://github.com/my-org/my-plugin-catalog - ref: - branch: main - path: plugindefinitions - overrides: - - name: cert-manager - alias: cert-manager-custom - - name: ingress-nginx - alias: ingress-nginx-custom - - name: kube-monitoring - alias: kube-monitoring-custom -``` +Versioning of a PluginDefinition is achieved with the Catalog resource. Since a Catalog references a Git repository via `spec.source.git`, you control which PluginDefinition versions are available in your Organization by controlling the Git reference. + +For details on how to pin PluginDefinition versions using `spec.source.git.ref`, see the [Catalog Ref configuration](https://cloudoperators.github.io/greenhouse/docs/reference/components/catalog/#ref). + +For details on how to override PluginDefinition names using `spec.overrides`, see [Configuring overrides for PluginDefinitions](https://cloudoperators.github.io/greenhouse/docs/reference/components/catalog/#configuring-overrides-for-plugindefinitions). #### Staged rollouts