Skip to content

chore: Kamelet options must not use a name the kamelet: component takes, such as location - #3201

Merged
oscerd merged 1 commit into
apache:mainfrom
davsclaus:quick-fix/kamelet-reserved-option-names
Nov 18, 2026
Merged

oscerd merged 1 commit into
apache:mainfrom
davsclaus:quick-fix/kamelet-reserved-option-names

Conversation

@davsclaus

Copy link
Copy Markdown
Contributor

Problem

The kamelet: component (KameletComponent.createEndpoint in apache/camel) keeps some parameters of a kamelet: endpoint for itself, before the template sees them:

  • location is read as the place to load the Kamelet YAML from, then removed;
  • templateId, routeId and uuid are removed;
  • block, timeout, failIfNoConsumers, noErrorHandler, advancedOptions, and the endpoint options every endpoint has (bridgeErrorHandler, exceptionHandler, exchangePattern, lazyStartProducer), configure the kamelet: endpoint.

So a Kamelet option with one of these names never reaches the template when it is set as a parameter of kamelet:. Five Kamelets on main have such an option:

Kamelet Option What happens on main with kamelet:<name>?<option>=...
google-vertexai-sink location (required) It does not start: FileNotFoundException: Resource not found: classpath:us-central1/google-vertexai-sink.kamelet.yaml → Cannot find Kamelet with name: google-vertexai-sink. Because the option is required, the Kamelet can never be used with its options as kamelet: parameters.
ibm-cos-sink location It does not start: Resource not found: classpath:us-south/ibm-cos-sink.kamelet.yaml → Cannot find Kamelet with name: ibm-cos-sink. Every example on the documentation page sets location.
ibm-cos-source location Same: Resource not found: classpath:us-south/ibm-cos-source.kamelet.yaml.
pulsar-sink lazyStartProducer Ignored: with lazyStartProducer=true and no Pulsar to reach, the integration still fails to start (Connection refused).
fhir-sink lazyStartProducer Ignored: the fhir: endpoint gets lazyStartProducer=false.

No Kamelet on main has an option named after the other reserved names.

Change

The options are renamed; the template maps the new name to the option of the wrapped component, which keeps its name:

Kamelet Before After Template
google-vertexai-sink location region (required) location: "{{region}}"
ibm-cos-sink location region location: "{{?region}}"
ibm-cos-source location region location: "{{?region}}"
fhir-sink lazyStartProducer lazyStart lazyStartProducer={{lazyStart}}
pulsar-sink lazyStartProducer lazyStart lazyStartProducer={{?lazyStart}}

The descriptions, the google-vertexai-sink and ibm-cos-* documentation partials (the examples used location), and the library copies are updated. The google-vertexai-sink description no longer needs its note about the workaround.

For ibm-cos-*, the option only feeds the service metadata of the ibm-cos endpoint (camel get service --metadata shows location=us-south); the region used to connect is the one of endpointUrl, as the description already said. It is kept, renamed, rather than removed.

Validator rule. CatalogValidator.verifyReservedPropertyNames (kamelets-maven-plugin) fails the build when a Kamelet declares a property whose name, ignoring case, is one of: templateId, routeId, location, uuid, block, timeout, failIfNoConsumers, noErrorHandler, advancedOptions, bridgeErrorHandler, exceptionHandler, exchangePattern, lazyStartProducer. With main's ibm-cos-sink put back, the build fails with:

ERROR: property "location" in kamelet "ibm-cos-sink" has the name of the "location" option of the kamelet: component, which takes it for itself and does not pass it on to the template: choose another name

CatalogValidatorTest covers it, and the developer guide (development.adoc) says which names to avoid.

Breaking change

The old option names did work through another path: Kamelet properties set as camel.kamelet.<name>.<option> (or camel.kamelet.<name>.<routeId>.<option>) reach the template, because only the kamelet: URI parameters are taken by the component. Verified on main: camel.kamelet.ibm-cos-sink.location=us-south gives the ibm-cos endpoint location=us-south, and camel.kamelet.pulsar-sink.lazyStartProducer=true lets the integration start without Pulsar. Camel K passes the properties of a Pipe in this form (camel.kamelet.<name>.<id>.<option>, see pkg/util/bindings in camel-k), so Pipes on Camel K that set location or lazyStartProducer worked, and must now use the new name:

  • google-vertexai-sink: the old name now fails at startup: Route template google-vertexai-sink the following mandatory parameters must be provided: region (verified with camel.kamelet.google-vertexai-sink.location).
  • ibm-cos-*: the old name is ignored; only the service metadata loses the region.
  • fhir-sink, pulsar-sink: the old name is ignored, so the connection is made at startup again, and the integration may fail to start when the server cannot be reached.

The renames are added to the upgrade notes in #3190, for the Camel 4.24 upgrade guide (apache/camel#30331).

Verification

Camel JBang 4.24.0-SNAPSHOT, camel run route.yaml --local-kamelet-dir=<dir>, with main's Kamelets and with this branch's. No cloud account: dummy credentials.

Kamelet Kamelet on main, old option as kamelet: parameter This branch, new option as kamelet: parameter Wrapped endpoint on this branch First message on this branch
ibm-cos-sink Fails: Resource not found: classpath:us-south/ibm-cos-sink.kamelet.yaml, Cannot find Kamelet with name: ibm-cos-sink region: us-south: starts ibm-cos://my-bucket?...&location=us-south&...; camel get service --metadata: location=us-south Fails on the dummy API key: Token retrieval from IAM service failed
ibm-cos-source Fails: Resource not found: classpath:us-south/ibm-cos-source.kamelet.yaml, Cannot find Kamelet with name: ibm-cos-source region: us-south: starts ibm-cos://my-bucket?...&location=us-south&... Polling fails on the dummy API key
google-vertexai-sink Fails: Resource not found: classpath:us-central1/google-vertexai-sink.kamelet.yaml, Cannot find Kamelet with name: google-vertexai-sink region: us-central1: starts (*) google-vertexai://my-project-123:us-central1:gemini-2.5-flash?operation=generateText Reaches Google, fails for the made-up project: 403 PERMISSION_DENIED ... project my-project-123
pulsar-sink lazyStartProducer: true, no Pulsar: fails to start, Connection refused lazyStart: true, no Pulsar: starts pulsar://persistent/public/default/test?...&lazyStartProducer=true&... Still waiting for the broker when stopped
fhir-sink lazyStartProducer: true: starts, but the fhir: endpoint has lazyStartProducer=false lazyStart: true: starts fhir: endpoint has lazyStartProducer=true Not sent

(*) With plain camel run, the Vertex AI endpoint fails to start, after the Kamelet is loaded, with NoClassDefFoundError: com/google/protobuf/RuntimeVersion$RuntimeDomain: the Vertex AI client needs a newer protobuf than JBang has on its classpath, whatever the Kamelet. It ran with --dep=com.google.protobuf:protobuf-java:4.35.1. This is a JBang classpath problem and is not fixed here.

Build: ./mvnw clean verify -DskipTests and ./mvnw clean verify pass.

Claude Code on behalf of Claus Ibsen

🤖 Generated with Claude Code

…es, such as location

The kamelet: component keeps some parameters of a kamelet: endpoint for
itself: location is where it loads the Kamelet from, templateId, routeId
and uuid are removed, and block, timeout, failIfNoConsumers,
noErrorHandler, advancedOptions, bridgeErrorHandler, exceptionHandler,
exchangePattern and lazyStartProducer configure the kamelet: endpoint.
A Kamelet option with one of these names never reaches the template
when it is given as a parameter of the kamelet: endpoint.

- google-vertexai-sink: location -> region (required; the Kamelet could
  not start with kamelet:google-vertexai-sink?location=...). Mapped to
  the location of the google-vertexai component.
- ibm-cos-sink, ibm-cos-source: location -> region. Mapped to the
  location of the ibm-cos component, which only shows it in the service
  metadata; the region used is the one of endpointUrl.
- fhir-sink, pulsar-sink: lazyStartProducer -> lazyStart. Mapped to the
  lazyStartProducer of the fhir and pulsar components.

The catalog validator now fails the build on a Kamelet property with
one of these names, and the developer guide says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants