feat(docs): adds LCM docs

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 <organization-namespace>` 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

docs/user-guides/plugin/lifecycle.md

@@ -0,0 +1,124 @@
+---
+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 such 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.
+- The PluginDefinition manifests
+- The repository where the PluginDefinitions live in
+
+### Plugin Consumers
+
+People configuring Plugins in their Organizations.
+
+They control the actual resources deployed to their Greenhouse Organization:
+
+- Catalogs
+- PluginDefinitions
+- PluginPresets (& Plugins)
+
+### Involved Resources
+
+#### [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)
+
+PluginPresets allow you to configure a set of Plugins to be deployed to a set of Clusters referencing a PluginDefinition.
+
+### 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.
+
+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
+
+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
+
+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. The tagging convention is `<plugin-name>/<version>` (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": "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] & '/(?<major>\\\\d+)\\\\.(?<minor>\\\\d+)\\\\.(?<patch>\\\\d+)$'})"
+      ]
+    }
+
+  ],
+    ```
+
+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.