This is an automated email from the ASF dual-hosted git repository. oscerd pushed a commit to branch fix/forage-named-bean-overrides in repository https://gitbox.apache.org/repos/asf/camel-kit.git
commit a94f7ccc83a35f0bea59b507644769595e4e9e08 Author: Andrea Cosentino <[email protected]> AuthorDate: Mon Nov 16 10:17:13 2026 +0100 Fix #122: describe Forage named-bean overrides from the environment and system properties The shared Forage guide and the camel-test configuration guide said that environment variables and system properties address only the default-bean key form and cannot target a named bean's key such as forage.myDb.jdbc.url. Forage does not have that limitation: ConfigModule.asNamed builds forage.<name>.<domain>.<prop>, envName() derives FORAGE_<NAME>_<DOMAIN>_<PROP> from it, and ConfigStore checks the environment, then the system property, then the properties files for named modules exactly as for default ones. Both guides now describe the named forms with the same precedence, matching the Forage documentation page, so generated deployment and CI guidance no longer steers users to properties-file edits that are not needed. ResourceConsistencyTest pins the corrected wording in both guides. Co-Authored-By: Claude Fable 5.1 <[email protected]> Signed-off-by: Andrea Cosentino <[email protected]> --- CHANGELOG.md | 3 +++ .../skills/camel-test/guides/test-configuration.md | 2 +- .../src/main/resources/skills/shared/forage.md | 11 ++++++----- .../camel/kit/generator/ResourceConsistencyTest.java | 20 ++++++++++++++++++++ 4 files changed, 30 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0016d747..0d6f7002 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 longer leave a partly initialized workspace (#174). - A preserved Maven wrapper is reported as kept without a proposed copy and points to `--replace-wrapper`; the documentation now describes the wrapper as the exception to `.camel-kit/conflicts/` proposals (#174). +- The shared Forage guide and the camel-test configuration guide no longer claim that environment variables and + system properties can override only default-bean keys: a named bean's `forage.myDb.jdbc.url` is overridden by + `FORAGE_MYDB_JDBC_URL` or `-Dforage.myDb.jdbc.url=...` with the same precedence (#122). - Preserve legitimate init layouts containing unrelated symlinks and normal permissions on new generated files. - Exclude VCS, build and dependency trees from graphs; support up to 256 MiB of recognized sources while retaining per-file limits and validation before XML sniffing. - Derive Claude MCP grants from the workflow manifest and validate catalog cache version components. diff --git a/kit/camel-kit-core/src/main/resources/skills/camel-test/guides/test-configuration.md b/kit/camel-kit-core/src/main/resources/skills/camel-test/guides/test-configuration.md index 4c5e22ed..06ae2071 100644 --- a/kit/camel-kit-core/src/main/resources/skills/camel-test/guides/test-configuration.md +++ b/kit/camel-kit-core/src/main/resources/skills/camel-test/guides/test-configuration.md @@ -51,7 +51,7 @@ camel.component.kafka.autoOffsetReset=earliest > **Note:** the `${CITRUS_TESTCONTAINERS_*}` values above are resolved by > Citrus at test runtime โ this `${}` shape is test-file-specific. Do NOT > generalize `${}` to non-test properties files on the main runtime; > camel-main resolves `{{key}}`, not `${key}` (see properties-generation.md > ยง5.1). -> **Forage override channels:** Forage resolves configuration with precedence env vars > system properties > properties files. In CI, `FORAGE_<DOMAIN>_<PROP>` environment variables (e.g. `FORAGE_JDBC_URL`) address the DEFAULT-bean key form only โ they can override an app's default `forage.*` keys without touching files, but cannot target a NAMED bean's key (`forage.myDb.jdbc.url`). Override a named bean's config through the properties file (e.g. the `forage.myDb.jdbc.*` overrides shown a [...] +> **Forage override channels:** Forage resolves configuration with precedence env vars > system properties > properties files, for default and named beans alike. In CI, `FORAGE_<DOMAIN>_<PROP>` (e.g. `FORAGE_JDBC_URL`) overrides a default-bean key, and `FORAGE_<NAME>_<DOMAIN>_<PROP>` (e.g. `FORAGE_MYDB_JDBC_URL`, or `-Dforage.myDb.jdbc.url=...` as a system property) overrides the named bean's `forage.myDb.jdbc.url` without touching files. The `forage.myDb.jdbc.*` lines shown above are th [...] The snippet above is a fallback pattern. Prefer the route's real property keys and endpoint option names. For example, if the route uses `kafka:orders?groupId=order-writer&autoOffsetReset=latest`, keep the actual topic and group id and diff --git a/kit/camel-kit-core/src/main/resources/skills/shared/forage.md b/kit/camel-kit-core/src/main/resources/skills/shared/forage.md index 620f004a..995cbbb0 100644 --- a/kit/camel-kit-core/src/main/resources/skills/shared/forage.md +++ b/kit/camel-kit-core/src/main/resources/skills/shared/forage.md @@ -151,11 +151,12 @@ forage.myBroker.jms.pool.enabled=true Route usage: `jms:queue:orders?connectionFactory=#myBroker`. -**Configuration precedence:** Forage resolves each key from, highest to lowest: environment variables -(`FORAGE_<DOMAIN>_<PROP>`, e.g. `FORAGE_JDBC_URL`) > system properties (`-Dforage.jdbc.url=...`) > -properties files > defaults. Env vars and system properties only address the DEFAULT-bean key form -(no name segment) โ they cannot target a NAMED bean's key (`forage.myDb.jdbc.url`). Override a named -bean's config through the properties file. +**Configuration precedence:** Forage resolves each key from, highest to lowest: environment variables > +system properties > properties files > defaults. Both override channels address default and named beans alike: +`forage.jdbc.url` is overridden by `FORAGE_JDBC_URL` or `-Dforage.jdbc.url=...`, and a named bean's +`forage.myDb.jdbc.url` by `FORAGE_MYDB_JDBC_URL` or `-Dforage.myDb.jdbc.url=...`. The variable form is the key +upper-cased with every `.` replaced by `_` (`FORAGE_<NAME>_<DOMAIN>_<PROP>`); the system property is the key itself. +Deployment and CI can therefore override a named bean without editing the properties file. ## Catalog queries (never load the whole file) diff --git a/kit/camel-kit-core/src/test/java/org/apache/camel/kit/generator/ResourceConsistencyTest.java b/kit/camel-kit-core/src/test/java/org/apache/camel/kit/generator/ResourceConsistencyTest.java index 52a9950f..674bb796 100644 --- a/kit/camel-kit-core/src/test/java/org/apache/camel/kit/generator/ResourceConsistencyTest.java +++ b/kit/camel-kit-core/src/test/java/org/apache/camel/kit/generator/ResourceConsistencyTest.java @@ -1748,6 +1748,26 @@ class ResourceConsistencyTest { "The Forage compatibility table must be rendered from distribution.properties"); } + @Test + void forageGuidesDescribeNamedBeanOverrideChannels() throws IOException { + Path skills = repositoryRoot().resolve("kit/camel-kit-core/src/main/resources/skills"); + String forage = Files.readString(skills.resolve("shared/forage.md")); + String testConfiguration = Files.readString(skills.resolve("camel-test/guides/test-configuration.md")); + + for (String guide : List.of(forage, testConfiguration)) { + // Forage resolves FORAGE_<NAME>_<DOMAIN>_<PROP> and -Dforage.<name>.<domain>.<prop> for named beans + // with the same precedence as the default-bean form (#122). + assertContainsAll(guide, + "FORAGE_<NAME>_<DOMAIN>_<PROP>", + "FORAGE_MYDB_JDBC_URL", + "-Dforage.myDb.jdbc.url="); + assertFalse(guide.contains("cannot target a NAMED bean"), + "Named-bean keys are overridable from the environment and system properties (#122)"); + assertFalse(guide.contains("DEFAULT-bean key form"), + "The default-bean-only restriction does not exist in Forage (#122)"); + } + } + @Test void commandReferenceDefaultsMatchTheDistribution() throws IOException { DistributionConfig distribution = DistributionConfig.loadBundled();
