feat(api): user generated Kamelet versioning

addons/keda/keda_test.go

@@ -129,21 +129,23 @@ func TestKameletAutoDetection(t *testing.T) {
 				},
 			},
 			Spec: camelv1.KameletSpec{
-				Definition: &camelv1.JSONSchemaProps{
-					Properties: map[string]camelv1.JSONSchemaProp{
-						"a": {
-							XDescriptors: []string{
-								"urn:keda:metadata:a",
+				KameletSpecBase: camelv1.KameletSpecBase{
+					Definition: &camelv1.JSONSchemaProps{
+						Properties: map[string]camelv1.JSONSchemaProp{
+							"a": {
+								XDescriptors: []string{
+									"urn:keda:metadata:a",
+								},
 							},
-						},
-						"b": {
-							XDescriptors: []string{
-								"urn:keda:metadata:bb",
+							"b": {
+								XDescriptors: []string{
+									"urn:keda:metadata:bb",
+								},
 							},
-						},
-						"c": {
-							XDescriptors: []string{
-								"urn:keda:authentication:cc",
+							"c": {
+								XDescriptors: []string{
+									"urn:keda:authentication:cc",
+								},
 							},
 						},
 					},
@@ -245,21 +247,23 @@ func TestPipeAutoDetection(t *testing.T) {
 				},
 			},
 			Spec: camelv1.KameletSpec{
-				Definition: &camelv1.JSONSchemaProps{
-					Properties: map[string]camelv1.JSONSchemaProp{
-						"a": {
-							XDescriptors: []string{
-								"urn:keda:metadata:a",
+				KameletSpecBase: camelv1.KameletSpecBase{
+					Definition: &camelv1.JSONSchemaProps{
+						Properties: map[string]camelv1.JSONSchemaProp{
+							"a": {
+								XDescriptors: []string{
+									"urn:keda:metadata:a",
+								},
 							},
-						},
-						"b": {
-							XDescriptors: []string{
-								"urn:keda:metadata:bb",
+							"b": {
+								XDescriptors: []string{
+									"urn:keda:metadata:bb",
+								},
 							},
-						},
-						"c": {
-							XDescriptors: []string{
-								"urn:keda:authentication:cc",
+							"c": {
+								XDescriptors: []string{
+									"urn:keda:authentication:cc",
+								},
 							},
 						},
 					},

docs/modules/ROOT/pages/kamelets/kamelets-dev.adoc

@@ -331,6 +331,52 @@ If everything goes right, you should get some tweets in the logs after the integ
 
 Refer to the xref:kamelets/kamelets-user.adoc[Kamelets User Guide] for more information on how to use it in different contexts (like Knative, Kafka, etc.).
 
+== Kamelet versions
+
+The catalog containing a set of Kamelets is generally developed in order to be used with a given Camel version (see the Apache Camel Kamelets catalog). However, when publishing the Kamelet to the cluster you may want to maintain more than one version for any reason (ie, to use a different dependency and be able to support multiple runtimes). You can therefore use the `.spec.versions` parameter to optionally maintain a set of alternative versions beside the main (and default) one.
+
+.my-timer-source.yaml
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1
+kind: Kamelet
+metadata:
+  name: my-timer-source
+spec:
+  definition:
+    title: "Timer Example"
+  types:
+    out:
+      mediaType: text/plain
+  template:
+    from:
+      uri: timer:tick
+      steps:
+        - setBody:
+            constant: "Kamelet Main"
+        - to: "kamelet:sink"
+  versions:
+    v2:
+      definition:
+        title: "Timer Example 2"
+      types:
+        out:
+          mediaType: text/plain
+      template:
+        from:
+          uri: timer:tick
+          steps:
+            - setBody:
+                constant: "Kamelet V2"
+            - to: "kamelet:sink"
+----
+
+NOTE: make sure the overall content fits into 1 MiB, which is the storage limit for a Custom Resource.
+
+This is a way to handle multiple version on Kubernetes and may not be supported out of the box by Camel core. If the Integration will require specifically to use `kamelet:my-timer-source?kameletVersion=v2`, then, the operator will mount properly the specification on the running application.
+
+The `.spec.versions` field may not be necessarily supported by the core as it's meant to provide a way to handle versioning on the cluster only. The runtime must be provided with a materialized Kamelet file with the chosen spec (the operator is in charge of that).
+
 == Kamelet data types
 
 A Kamelet usually encapsulates a specific functionality and serves a very opinionated use case with well-defined input parameters and outcome.

docs/modules/ROOT/pages/kamelets/kamelets-user.adoc

@@ -218,6 +218,21 @@ You can now write an integration that uses the Kamelet with the named configurat
 You can run this integration without specifying other parameters, the Kamelet endpoint will be implicitly configured by the Camel K operator that will
 automatically mount the secret into the integration Pod.
 
+=== Kamelet versioning
+
+Kamelets provided in a catalog are generally meant to work with a given runtime version (the same for which they are released). However, when you create a Kamelet and publish to a cluster, you may want to store and use different versions. If the Kamelet is provided with more than the `main` version, then, you can specify which version to use in your Integration by adding the version parameter. For instance:
+
+[source,yaml]
+.kamlet-namedconfig-route.yaml
+----
+- from:
+    uri: "timer:tick?kameletVersion=v2"
+    steps:
+      - to: "log:info"
+----
+
+The operator will be able to automatically pick the right version and use it at runtime. If no version is specified, then you will use the default one.
+
 [[kamelets-usage-binding]]
 == Binding Kamelets in Pipes
 

docs/modules/ROOT/partials/apis/camel-k-crds.adoc

@@ -1756,7 +1756,7 @@ the expected schema for the data type
 
 *Appears on:*
 
-* <<#_camel_apache_org_v1_KameletSpec, KameletSpec>>
+* <<#_camel_apache_org_v1_KameletSpecBase, KameletSpecBase>>
 
 DataTypesSpec represents the specification for a set of data types.
 
@@ -2005,7 +2005,7 @@ ErrorHandlerType a type of error handler (ie, sink).
 
 *Appears on:*
 
-* <<#_camel_apache_org_v1_KameletSpec, KameletSpec>>
+* <<#_camel_apache_org_v1_KameletSpecBase, KameletSpecBase>>
 
 EventTypeSpec represents a specification for an event type.
 Deprecated: In favor of using DataTypeSpec.
@@ -3864,7 +3864,7 @@ XDescriptors is a list of extended properties that trigger a custom behavior in
 
 * <<#_camel_apache_org_v1_DataTypeSpec, DataTypeSpec>>
 * <<#_camel_apache_org_v1_EventTypeSpec, EventTypeSpec>>
-* <<#_camel_apache_org_v1_KameletSpec, KameletSpec>>
+* <<#_camel_apache_org_v1_KameletSpecBase, KameletSpecBase>>
 
 JSONSchemaProps is a JSON-Schema following Specification Draft 4 (http://json-schema.org/).
 
@@ -4129,6 +4129,39 @@ KameletSpec specifies the configuration required to execute a Kamelet.
 |Field
 |Description
 
+|`KameletSpecBase` +
+*xref:#_camel_apache_org_v1_KameletSpecBase[KameletSpecBase]*
+|(Members of `KameletSpecBase` are embedded into this type.)
+
+
+
+
+|`versions` +
+*xref:#_camel_apache_org_v1_KameletSpecBase[map[string\]github.com/apache/camel-k/v2/pkg/apis/camel/v1.KameletSpecBase]*
+|
+
+
+the optional versions available for this Kamelet. This field may not be taken in account by Camel core and is meant to support
+any user defined versioning model on cluster only. If the user wants to use any given version, she must materialize a file with the given version spec
+as the `main` Kamelet spec on the runtime.
+
+
+|===
+
+[#_camel_apache_org_v1_KameletSpecBase]
+=== KameletSpecBase
+
+*Appears on:*
+
+* <<#_camel_apache_org_v1_KameletSpec, KameletSpec>>
+
+KameletSpecBase specifies the base configuration of a Kamelet.
+
+[cols="2,2a",options="header"]
+|===
+|Field
+|Description
+
 |`definition` +
 *xref:#_camel_apache_org_v1_JSONSchemaProps[JSONSchemaProps]*
 |
@@ -5474,7 +5507,7 @@ string
 * <<#_camel_apache_org_v1_IntegrationKitSpec, IntegrationKitSpec>>
 * <<#_camel_apache_org_v1_IntegrationSpec, IntegrationSpec>>
 * <<#_camel_apache_org_v1_IntegrationStatus, IntegrationStatus>>
-* <<#_camel_apache_org_v1_KameletSpec, KameletSpec>>
+* <<#_camel_apache_org_v1_KameletSpecBase, KameletSpecBase>>
 
 SourceSpec defines the configuration for one or more routes to be executed in a certain Camel DSL language.
 
@@ -5687,7 +5720,7 @@ a JibTask, for Jib strategy
 
 *Appears on:*
 
-* <<#_camel_apache_org_v1_KameletSpec, KameletSpec>>
+* <<#_camel_apache_org_v1_KameletSpecBase, KameletSpecBase>>
 
 Template is an unstructured object representing a Kamelet template in YAML/JSON DSL.
 

e2e/common/traits/files/.camel-jbang/camel-jbang-run.properties

@@ -0,0 +1,25 @@
+loggingLevel=info
+loggingColor=true
+loggingJson=false
+camel.jbang.localKameletDir=file\:.
+camel.main.modeline=true
+camel.jbang.compileWorkDir=.camel-jbang/compile
+camel.jbang.health=false
+camel.jbang.metrics=false
+camel.jbang.console=false
+camel.jbang.verbose=false
+camel.jbang.camel-version=4.7.0
+camel.jbang.springBootVersion=3.3.1
+camel.jbang.quarkusVersion=3.12.0
+camel.jbang.kameletsVersion=4.7.0
+camel.main.name=kamelet-it-v1
+camel.main.routesIncludePattern=file\:kamelet-it-v1.yaml
+dependency=mvn\:org.apache.camel\:camel-kamelet\:4.7.0
+dependency=mvn\:org.apache.camel\:camel-yaml-dsl\:4.7.0
+dependency=mvn\:org.apache.camel\:camel-core-languages\:4.7.0
+dependency=mvn\:org.apache.camel\:camel-rest\:4.7.0
+dependency=mvn\:org.apache.camel\:camel-rest-openapi\:4.7.0
+dependency=mvn\:org.apache.camel\:camel-platform-http\:4.7.0
+camel.jbang.platform-http.port=8080
+kamelet=my-timer-source
+dependency=mvn\:org.apache.camel\:camel-timer\:4.7.0

e2e/common/traits/files/kamelet-it-main.yaml

@@ -0,0 +1,23 @@
+# camel-k: language=yaml
+
+# ---------------------------------------------------------------------------
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ---------------------------------------------------------------------------
+
+- from:
+    uri: "kamelet:my-timer-source"
+    steps:
+      - log: "${body}"

e2e/common/traits/files/kamelet-it-v1.yaml

@@ -0,0 +1,23 @@
+# camel-k: language=yaml
+
+# ---------------------------------------------------------------------------
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ---------------------------------------------------------------------------
+
+- from:
+    uri: "kamelet:my-timer-source?kameletVersion=v1"
+    steps:
+      - log: "${body}"

e2e/common/traits/files/my-timer-source.kamelet.yaml

@@ -0,0 +1,66 @@
+# ---------------------------------------------------------------------------
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ---------------------------------------------------------------------------
+
+apiVersion: camel.apache.org/v1
+kind: Kamelet
+metadata:
+  name: my-timer-source
+  labels:
+    camel.apache.org/kamelet.type: "source"
+spec:
+  definition:
+    title: "Timer Example"
+    description: "Produces periodic events with a custom payload"
+  types:
+    out:
+      mediaType: text/plain
+  template:
+    from:
+      uri: timer:tick
+      steps:
+        - setBody:
+            constant: "Kamelet Main"
+        - to: "kamelet:sink"
+  versions:
+    v1:
+      definition:
+        title: "Timer Example 1"
+        description: "Produces periodic events with a custom payload"
+      types:
+        out:
+          mediaType: text/plain
+      template:
+        from:
+          uri: timer:tick
+          steps:
+            - setBody:
+                constant: "Kamelet V1"
+            - to: "kamelet:sink"
+    v2:
+      definition:
+        title: "Timer Example 2"
+        description: "Produces periodic events with a custom payload"
+      types:
+        out:
+          mediaType: text/plain
+      template:
+        from:
+          uri: timer:tick
+          steps:
+            - setBody:
+                constant: "Kamelet V2"
+            - to: "kamelet:sink"