feat(api): user generated Kamelet versioning

[squakez]

With this change, the user will be able to provide an alternative version specification to the main one. This is useful for Kamelets developed by users and published in a cluster for which the user wants to provide a versioning model. The change is backward compatible and optional only. Default behavior will stick to use the spec provided in default.

Closes #4395

Release Note

feat(api): user generated Kamelet versioning

[github-actions]

✔️ Unit test coverage report - coverage increased from 43.7% to 43.8% (+0.1%)

[github-actions]

✔️ Unit test coverage report - coverage increased from 43.7% to 43.8% (+0.1%)

[claudio4j]

This implementation is not compatible with camel core (as documented), not only for Kamelets, but also for the Pipe, since there is an additional version field in the endpoint uri. With this solution Camel K sets an additional divergent element from camel core. So with this implementation a camel run route.yaml would not be possible.
Also inlining the kamelets in the versions field, requires more yaml editing, making harder to maintain a bigger yaml file. kamelets should be simple, but adding the versions adds complexity to it.

Probably an alternative solution is to add support for labels in the metadata, for example: camel.apache.org/kamelet.version: "v1" , but this won't solve the naming problem, as it will duplicate the object name, having the differentiator in the metadata only.

I would say that having a different name (as explained in the linked issue) would be easier to control the old kamelet names, or having a different namespace to have the different versions.

[squakez]

Thanks for you review.

This implementation is not compatible with camel core (as documented), not only for Kamelets, but also for the Pipe, since there is an additional version field in the endpoint uri. With this solution Camel K sets an additional divergent element from camel core. So with this implementation a camel run route.yaml would not be possible. Also inlining the kamelets in the versions field, requires more yaml editing, making harder to maintain a bigger yaml file. kamelets should be simple, but adding the versions adds complexity to it.

As explained in the PR description "This is useful for Kamelets developed by users and published in a cluster for which the user wants to provide a versioning model.". It is an optional field that won't alter existing behavior it is not intended to be necessarily supported by the core but a support for users with a given need. It is useful as it let the user define their versioning in the cluster and it's up to the user to switch version either through the operator or with their internal tooling (ie, mounting the given Kamelet version into a configmap consumable by the running application). Using the Kamelet, as is, would keep using the main spec. I'm testing a multiversion Kamelets with JBang and it works as expected:

$ pwd
/home/squake/workspace/camel-k/e2e/common/traits/files
...
$ camel run kamelet-it-main.yaml --local-kamelet-dir=.
2024-09-03 08:54:27.692  INFO 6809 --- [           main] org.apache.camel.main.MainSupport        : Apache Camel (JBang) 4.7.0 is starting
2024-09-03 08:54:27.886  INFO 6809 --- [           main] org.apache.camel.main.MainSupport        : Using Java 17.0.7 with PID 6809. Started by squake in /home/squake/workspace/camel-k/e2e/common/traits/files
2024-09-03 08:54:28.045  INFO 6809 --- [           main] org.apache.camel.main.ProfileConfigurer  : The application is starting with profile: dev
2024-09-03 08:54:28.931  INFO 6809 --- [           main] he.camel.cli.connector.LocalCliConnector : Camel JBang CLI enabled
2024-09-03 08:54:29.065  INFO 6809 --- [           main] e.camel.impl.engine.AbstractCamelContext : Apache Camel 4.7.0 (kamelet-it-main) is starting
2024-09-03 08:54:29.284  INFO 6809 --- [           main] vertx.core.spi.resolver.ResolverProvider : Using the default address resolver as the dns resolver could not be loaded
2024-09-03 08:54:29.389  INFO 6809 --- [ntloop-thread-0] tform.http.vertx.VertxPlatformHttpServer : Vert.x HttpServer started on 0.0.0.0:8080
2024-09-03 08:54:29.514  INFO 6809 --- [           main] e.camel.impl.engine.AbstractCamelContext : Routes startup (total:1 started:1 kamelets:1)
2024-09-03 08:54:29.514  INFO 6809 --- [           main] e.camel.impl.engine.AbstractCamelContext :     Started route1 (kamelet://my-timer-source)
2024-09-03 08:54:29.514  INFO 6809 --- [           main] e.camel.impl.engine.AbstractCamelContext : Apache Camel 4.7.0 (kamelet-it-main) started in 448ms (build:0ms init:0ms start:448ms)
2024-09-03 08:54:30.449  INFO 6809 --- [ - timer://tick] kamelet-it-main.yaml:23                  : Kamelet Main
2024-09-03 08:54:31.418  INFO 6809 --- [ - timer://tick] kamelet-it-main.yaml:23                  : Kamelet Main
2024-09-03 08:54:32.418  INFO 6809 --- [ - timer://tick] kamelet-it-main.yaml:23                  : Kamelet Main
2024-09-03 08:54:33.419  INFO 6809 --- [ - timer://tick] kamelet-it-main.yaml:23                  : Kamelet Main
2024-09-03 08:54:34.418  INFO 6809 --- [ - timer://tick] kamelet-it-main.yaml:23                  : Kamelet Main
...
$ camel run kamelet-it-v1.yaml --local-kamelet-dir=.
2024-09-03 08:54:41.259  INFO 6906 --- [           main] org.apache.camel.main.MainSupport        : Apache Camel (JBang) 4.7.0 is starting
2024-09-03 08:54:41.456  INFO 6906 --- [           main] org.apache.camel.main.MainSupport        : Using Java 17.0.7 with PID 6906. Started by squake in /home/squake/workspace/camel-k/e2e/common/traits/files
2024-09-03 08:54:41.606  INFO 6906 --- [           main] org.apache.camel.main.ProfileConfigurer  : The application is starting with profile: dev
2024-09-03 08:54:42.405  INFO 6906 --- [           main] he.camel.cli.connector.LocalCliConnector : Camel JBang CLI enabled
2024-09-03 08:54:42.509  INFO 6906 --- [           main] e.camel.impl.engine.AbstractCamelContext : Apache Camel 4.7.0 (kamelet-it-v1) is starting
2024-09-03 08:54:42.717  INFO 6906 --- [           main] vertx.core.spi.resolver.ResolverProvider : Using the default address resolver as the dns resolver could not be loaded
2024-09-03 08:54:42.824  INFO 6906 --- [ntloop-thread-0] tform.http.vertx.VertxPlatformHttpServer : Vert.x HttpServer started on 0.0.0.0:8080
2024-09-03 08:54:42.938  INFO 6906 --- [           main] e.camel.impl.engine.AbstractCamelContext : Routes startup (total:1 started:1 kamelets:1)
2024-09-03 08:54:42.939  INFO 6906 --- [           main] e.camel.impl.engine.AbstractCamelContext :     Started route1 (kamelet://my-timer-source)
2024-09-03 08:54:42.939  INFO 6906 --- [           main] e.camel.impl.engine.AbstractCamelContext : Apache Camel 4.7.0 (kamelet-it-v1) started in 429ms (build:0ms init:0ms start:429ms)
2024-09-03 08:54:43.898  INFO 6906 --- [ - timer://tick] kamelet-it-v1.yaml:23                    : Kamelet Main

You can see that the Integration parameter is not take in account as it is only meaningful for the operator. I can add some more clear description to the API if you think it makes sense.

As for the Pipe it does not introduce any new parameter. The endpoint properties already exists and is an open field. In fact, we are already using the id property with the very same concept, so, it does not affect at all the existing compatibility.

Same for the maintainability point. This is not meant to be something to include in the Kamelet provided in the catalog for the reason you're mentioning. It's up to the user to use and maintain. Completely optional feature.

Probably an alternative solution is to add support for labels in the metadata, for example: camel.apache.org/kamelet.version: "v1" , but this won't solve the naming problem, as it will duplicate the object name, having the differentiator in the metadata only.

I would say that having a different name (as explained in the linked issue) would be easier to control the old kamelet names, or having a different namespace to have the different versions.

[github-actions]

✔️ Unit test coverage report - coverage increased from 43.7% to 43.8% (+0.1%)

[claudio4j]

Good as an optional way for users who don't want to rename kamelets. Thanks for the detailed explanation.