feat(docs): adds LCM docs#1465
Open
uwe-mayer wants to merge 8 commits into
Open
Conversation
github-actions
Bot
added
the
documentation
2 tasks
abhijith-darshan
force-pushed
the
docs/catalogs
branch
from
85e689a to
26e87e4
Compare
ibakshay
requested changes
Oct 14, 2025
Contributor
ibakshay
left a comment
ibakshay
left a comment
There was a problem hiding this comment.
Left some minor comments :)
|
|
||
| E.g. | ||
|
|
||
| <!-- TODO: Actually test this config! --> |
Contributor
There was a problem hiding this comment.
Is this TODO still valid?
Contributor
There was a problem hiding this comment.
yes, in progress...
Co-authored-by: Akshay Iyyadurai Balasundaram <akshay.iyyadurai.balasundaram@sap.com>
Co-authored-by: Akshay Iyyadurai Balasundaram <akshay.iyyadurai.balasundaram@sap.com>
Co-authored-by: Akshay Iyyadurai Balasundaram <akshay.iyyadurai.balasundaram@sap.com>
Co-authored-by: Akshay Iyyadurai Balasundaram <akshay.iyyadurai.balasundaram@sap.com>
2 tasks
- 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
uwe-mayer
force-pushed
the
docs/catalogs
branch
from
9c696ac to
475f2d1
Compare
Comment on lines
+90
to
+96
| #### 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. |
Contributor
There was a problem hiding this comment.
all these are documented in Catalog. If something is missing we should enhance it there...
I would just give jump off points https://cloudoperators.github.io/greenhouse/docs/reference/components/catalog/#ref ??
This way if Catalog changes then documentation needs to be updated only in one place.
WDYT?
abhijith-darshan
requested changes
May 8, 2026
Comment on lines
+151
to
+175
| ##### 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 | ||
| ``` |
Contributor
There was a problem hiding this comment.
These are already documented with examples in Catalog...
We should do a single jump off point to - https://cloudoperators.github.io/greenhouse/docs/reference/components/catalog/#configuring-overrides-for-plugindefinitions
Comment on lines
+98
to
+149
| ##### 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 | ||
| ``` |
Contributor
There was a problem hiding this comment.
The individual examples are missing in Catalog documentation for this. I think we should move this to catalog docs and give jump off points
Contributor
There was a problem hiding this comment.
Pull request overview
Adds user-facing documentation describing how Greenhouse plugin lifecycle management (LCM) works, and expands the Catalog reference docs to better explain version pinning via Git refs.
Changes:
- Added a new user guide page describing plugin lifecycle management concepts and available Greenhouse/Flux features.
- Updated the Catalog reference docs with improved formatting and concrete
refexamples (branch/tag/SHA).
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| docs/user-guides/plugin/lifecycle.md | New LCM guide covering actors, resources, update/rollback behavior, version pinning, and staged rollouts. |
| docs/reference/components/catalog.md | Formatting cleanup plus added examples for .spec.sources[].ref usage (branch/tag/SHA). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+53
to
+65
| #### [Catalogs](./../../reference/api/index.html#greenhouse.sap/v1alpha1.Catalog) | ||
|
|
||
| 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. | ||
|
|
||
| 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) | ||
|
|
||
| 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.html#greenhouse.sap/v1alpha1.PluginPreset) |
|
|
||
| ### Plugin Developers | ||
|
|
||
| These are the people providing the Plugins that can be used with Greenhouse. These Plugins are offered via (Cluster-)Plugindefinitions. |
Comment on lines
+85
to
+89
| 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). |
Comment on lines
+122
to
+124
| 1. Maintain different Catalogs for your stages. | ||
|
|
||
| 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. |
|
|
||
| **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. |
|
|
||
| #### Staged rollouts | ||
|
|
||
| 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds documentation on how to do lifecycle management with the Plugin machinery of Greenhouse.
What type of PR is this? (check all applicable)