flavours documentation

[gazarenkov]

Description

Added upstream documentation for flavours framework, api and implementations as well as accompanying improvements.

Which issue(s) does this PR fix or relate to

https://redhat.atlassian.net/browse/RHIDP-11505

PR acceptance criteria

• Tests
• Documentation

How to test changes / Special notes to the reviewer

[rhdh-qodo-merge]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (1) 📎 Requirement gaps (0)

1. lightspeed-credentials Secret not defined 📘 Rule violation ✧ Quality

Description

The new Lightspeed documentation references a Secret (lightspeed-credentials) in a Kubernetes
manifest snippet but does not include a corresponding Secret stub manifest in the same doc/example
block. Users attempting to apply the example would hit a missing dependency error.

Code

docs/lightspeed.md[R94-103]

+```yaml
+spec:
+  application:
+    extraEnvs:
+      secrets:
+        - name: lightspeed-credentials
+```
+
+Ensure the secret contains the necessary authentication keys for AI service access.
+

Evidence

PR Compliance ID 1 requires that Kubernetes examples include all referenced dependent resources
(like Secrets) in the same example set. The snippet in docs/lightspeed.md references
lightspeed-credentials but provides no Secret manifest alongside it.

Rule 1: Include all dependent Kubernetes resources in example manifests
docs/lightspeed.md[94-103]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/lightspeed.md` contains a Kubernetes example that references a Secret (`lightspeed-credentials`) but does not provide a stub Secret manifest in the same example set.

## Issue Context
Compliance requires example manifests to be self-contained for referenced resources like Secrets/ConfigMaps, so users can conceptually `kubectl apply -f` the example bundle without missing-object errors.

## Fix Focus Areas
- docs/lightspeed.md[88-103]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Missing testdata fixtures 🐞 Bug ≡ Correctness

Description

New tests call addToDefaultConfig() with YAML filenames that are not present under
pkg/model/testdata; addToDefaultConfig panics on read failure, so the unit test suite will fail at
runtime.

Code

pkg/model/configmapenvs_test.go[223]

+	testObj := createBackstageTest(bs).withDefaultConfig(true).addToDefaultConfig("configmap-envs.yaml", "multi-cm-envs.yaml")

Evidence

addToDefaultConfig() reads test YAML from pkg/model/testdata/<fileName> and panics if the file
cannot be read. The new tests reference fixture names (e.g., multi-cm-envs.yaml,
raw-cm-files-custom-path.yaml, multi-cm-files.yaml) via addToDefaultConfig(), so if those files are
missing the tests will panic immediately.

pkg/model/model_tests.go[72-94]
pkg/model/configmapenvs_test.go[211-226]
pkg/model/configmapfiles_test.go[117-141]
pkg/model/configmapfiles_test.go[272-279]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
New unit tests call `addToDefaultConfig(..., <fixture>.yaml)` with fixture filenames that are not available under `pkg/model/testdata/`. `addToDefaultConfig()` panics if the file can’t be read, so the tests will fail at runtime.

## Issue Context
`addToDefaultConfig()` reads `testdata/<name>` and `panic(err)` on failure.

## Fix Focus Areas
- Add the missing fixture files under `pkg/model/testdata/` **or** update the tests to reference existing fixtures.
- Ensure the new fixtures match the expected shapes (multi-object ConfigMaps, custom mount path cases).

### Files/lines to edit
- pkg/model/model_tests.go[72-94]
- pkg/model/configmapenvs_test.go[209-247]
- pkg/model/configmapfiles_test.go[117-162]
- pkg/model/configmapfiles_test.go[272-298]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Flavour merge order unstable 🐞 Bug ≡ Correctness

Description

docs/configuration.md states flavours merge “in the order specified”, but GetEnabledFlavours()
collects enabled flavours by ranging over a map, producing nondeterministic ordering and therefore
unstable merge precedence between flavours.

Code

docs/configuration.md[R373-379]

+Flavours extend the default configuration system by organizing pre-configured settings in `/default-config/flavours/<flavour-name>/`. Each flavour includes a `metadata.yaml` file controlling default enablement behavior. When multiple flavours are specified, configurations merge additively in the order specified, with later entries overriding earlier ones when conflicts occur.
+
+Different file types use appropriate merge strategies:
+- Kubernetes objects use kyaml deep merge
+- Dynamic plugins merge by package name
+- App configs mount as multiple files for Backstage's internal merging
+- Extra configs maintain multiple ConfigMaps/Secrets

Evidence

The documentation explicitly promises ordered merging. However, GetEnabledFlavours builds the
enabled flavour list by iterating a Go map, which does not preserve any stable or user-specified
order; collectConfigSources then applies flavours in the provided slice order, so the merge order is
effectively random and can vary between reconciliations.

docs/configuration.md[371-379]
pkg/model/flavour.go[32-71]
pkg/model/default-config.go[54-85]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Docs claim flavour configs merge in the user-specified order, but the controller currently returns enabled flavours in nondeterministic order due to Go map iteration. This can make merges non-repeatable and cause conflicting flavour configs to win unpredictably.

## Issue Context
- `GetEnabledFlavours()` builds `result` by ranging over `allFlavours` (a map).
- `collectConfigSources()` merges configs in the order of the `flavours` slice.

## Fix Focus Areas
- Return enabled flavours in a deterministic order:
 - Preserve `spec.flavours` order for explicitly listed flavours.
 - Place implicitly enabled-by-default flavours in a stable order (e.g., sorted by name or filesystem order) relative to explicit ones (define and document the rule).
- Optionally update docs if the intended ordering semantics differ.

### Files/lines to edit
- pkg/model/flavour.go[32-71]
- pkg/model/default-config.go[54-85]
- docs/configuration.md[371-379]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more

[rhdh-qodo-merge]

Review Summary by Qodo

Add Flavours documentation and enhance configuration guides with tests

📝 Documentation ✨ Enhancement 🧪 Tests

Walkthroughs

Description

• Added comprehensive Flavours documentation covering overview, capabilities, and usage patterns
• Introduced Lightspeed flavour documentation with installation, configuration, and features
• Updated Orchestrator documentation to reference new flavour-based configuration system
• Enhanced configuration documentation with detailed mount path and subPath behavior explanations
• Added multi-object support documentation for ConfigMaps and Secrets
• Added comprehensive test coverage for multi-object ConfigMap configurations
• Fixed import statement formatting in generated deepcopy files across API versions
• Removed commented-out code from ConfigMapEnvs implementation

Diagram

flowchart LR
  A["Documentation Updates"] --> B["Flavours System"]
  A --> C["Configuration Guide"]
  A --> D["Lightspeed Flavour"]
  A --> E["Orchestrator Flavour"]
  F["Test Enhancements"] --> G["Multi-Object Tests"]
  G --> H["ConfigMap Envs"]
  G --> I["ConfigMap Files"]
  J["Code Cleanup"] --> K["Import Formatting"]
  J --> L["Remove Dead Code"]

Loading

File Changes

1. api/v1alpha3/zz_generated.deepcopy.go Formatting +1/-1

Fix import statement formatting in v1alpha3

api/v1alpha3/zz_generated.deepcopy.go

---

2. api/v1alpha4/zz_generated.deepcopy.go Formatting +1/-1

Fix import statement formatting in v1alpha4

api/v1alpha4/zz_generated.deepcopy.go

---

3. api/v1alpha5/zz_generated.deepcopy.go Formatting +1/-1

Fix import statement formatting in v1alpha5

api/v1alpha5/zz_generated.deepcopy.go

---

View more (7)

4. api/v1alpha6/zz_generated.deepcopy.go Formatting +1/-1

Fix import statement formatting in v1alpha6

api/v1alpha6/zz_generated.deepcopy.go

---

5. pkg/model/configmapenvs.go Code cleanup +0/-5

Remove commented-out code from setMetaInfo method

pkg/model/configmapenvs.go

---

6. pkg/model/configmapenvs_test.go 🧪 Tests +92/-0

Add multi-object ConfigMap environment tests

pkg/model/configmapenvs_test.go

---

7. pkg/model/configmapfiles_test.go 🧪 Tests +110/-0

Add multi-object ConfigMap files and mount path tests

pkg/model/configmapfiles_test.go

---

8. docs/configuration.md 📝 Documentation +196/-8

Add Flavours documentation and enhance configuration details

docs/configuration.md

---

9. docs/lightspeed.md 📝 Documentation +154/-0

Add comprehensive Lightspeed flavour documentation

docs/lightspeed.md

---

10. docs/orchestrator.md 📝 Documentation +11/-1

Update Orchestrator documentation with flavour support

docs/orchestrator.md

---

[github-actions]

PR images are available:

1. https://quay.io/rhdh-community/operator:0.10.0-pr-2641-ce9b585
2. https://quay.io/rhdh-community/operator-bundle:0.10.0-pr-2641-ce9b585
3. https://quay.io/rhdh-community/operator-catalog:0.10.0-pr-2641-ce9b585

[github-actions]

PR images are available:

1. https://quay.io/rhdh-community/operator:0.10.0-pr-2641-a08e683
2. https://quay.io/rhdh-community/operator-bundle:0.10.0-pr-2641-a08e683
3. https://quay.io/rhdh-community/operator-catalog:0.10.0-pr-2641-a08e683

[github-actions]

PR images are available:

1. https://quay.io/rhdh-community/operator:0.10.0-pr-2641-17d0c9e
2. https://quay.io/rhdh-community/operator-bundle:0.10.0-pr-2641-17d0c9e
3. https://quay.io/rhdh-community/operator-catalog:0.10.0-pr-2641-17d0c9e

[gabemontero]

just some minor tweaks @gazarenkov as well as pulling in a couple of folks from @redhat-developer/rhdh-ai to cross reference

[Jdubrick]

Gave it an initial read through. I know currently we are discussing whether or not MCP should ship with Lightspeed as part of the default install, or if it should be omitted since it is in developer preview. I think since there is more than just Lightspeed changes in these docs, if we need to revisit and update it to remove MCP down the line from this documentation that is okay as to not hold up the PR.

Wdyt @gabemontero @johnmcollier @gazarenkov

[github-actions]

PR images are available:

1. https://quay.io/rhdh-community/operator:0.10.0-pr-2641-37cba1e
2. https://quay.io/rhdh-community/operator-bundle:0.10.0-pr-2641-37cba1e
3. https://quay.io/rhdh-community/operator-catalog:0.10.0-pr-2641-37cba1e

[github-actions]

PR images are available:

1. https://quay.io/rhdh-community/operator:0.10.0-pr-2641-557ae66
2. https://quay.io/rhdh-community/operator-bundle:0.10.0-pr-2641-557ae66
3. https://quay.io/rhdh-community/operator-catalog:0.10.0-pr-2641-557ae66

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

PR images are available:

1. https://quay.io/rhdh-community/operator:0.10.0-pr-2641-91a2047
2. https://quay.io/rhdh-community/operator-bundle:0.10.0-pr-2641-91a2047
3. https://quay.io/rhdh-community/operator-catalog:0.10.0-pr-2641-91a2047