This is an automated email from the ASF dual-hosted git repository.
nferraro pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-k.git
commit a0644223291e463c646b466f691a75c29eef43f4
Author: nicolaferraro <ni.ferr...@gmail.com>
AuthorDate: Mon Dec 20 11:50:39 2021 +0100
Fix #1107: add documentation
---
addons/keda/duck/v1alpha1/zz_generated.deepcopy.go | 25 +++++
addons/keda/keda.go | 24 +++--
.../bases/camel.apache.org_kameletbindings.yaml | 15 +--
config/crd/bases/camel.apache.org_kamelets.yaml | 8 +-
docs/modules/ROOT/nav.adoc | 2 +-
docs/modules/ROOT/pages/kamelets/kamelets-dev.adoc | 119 +++++++++++++++++++++
.../modules/ROOT/pages/kamelets/kamelets-user.adoc | 39 +++++++
docs/modules/ROOT/partials/apis/crds-html.adoc | 2 +-
docs/modules/traits/pages/keda.adoc | 42 +++++++-
helm/camel-k/crds/crd-kamelet-binding.yaml | 15 +--
helm/camel-k/crds/crd-kamelet.yaml | 8 +-
resources/traits.yaml | 42 ++++++--
12 files changed, 300 insertions(+), 41 deletions(-)
diff --git a/addons/keda/duck/v1alpha1/zz_generated.deepcopy.go
b/addons/keda/duck/v1alpha1/zz_generated.deepcopy.go
index b551c7f..9762e39 100644
--- a/addons/keda/duck/v1alpha1/zz_generated.deepcopy.go
+++ b/addons/keda/duck/v1alpha1/zz_generated.deepcopy.go
@@ -137,6 +137,31 @@ func (in *ScaledObjectSpec) DeepCopyInto(out
*ScaledObjectSpec) {
*out = new(v1.ObjectReference)
**out = **in
}
+ if in.PollingInterval != nil {
+ in, out := &in.PollingInterval, &out.PollingInterval
+ *out = new(int32)
+ **out = **in
+ }
+ if in.CooldownPeriod != nil {
+ in, out := &in.CooldownPeriod, &out.CooldownPeriod
+ *out = new(int32)
+ **out = **in
+ }
+ if in.IdleReplicaCount != nil {
+ in, out := &in.IdleReplicaCount, &out.IdleReplicaCount
+ *out = new(int32)
+ **out = **in
+ }
+ if in.MinReplicaCount != nil {
+ in, out := &in.MinReplicaCount, &out.MinReplicaCount
+ *out = new(int32)
+ **out = **in
+ }
+ if in.MaxReplicaCount != nil {
+ in, out := &in.MaxReplicaCount, &out.MaxReplicaCount
+ *out = new(int32)
+ **out = **in
+ }
if in.Triggers != nil {
in, out := &in.Triggers, &out.Triggers
*out = make([]ScaleTriggers, len(*in))
diff --git a/addons/keda/keda.go b/addons/keda/keda.go
index 90641e3..4911a76 100644
--- a/addons/keda/keda.go
+++ b/addons/keda/keda.go
@@ -62,27 +62,34 @@ const (
)
// The KEDA trait can be used for automatic integration with KEDA autoscalers.
+// The trait can be either manually configured using the `triggers` option or
automatically configured
+// via markers in the Kamelets.
+//
+// For information on how to use KEDA enabled Kamelets with the KEDA trait,
refer to
+// xref:kamelets/kamelets-user.adoc#kamelet-keda-user[the KEDA section in the
Kamelets user guide].
+// If you want to create Kamelets that contain KEDA metadata, refer to
+// xref:kamelets/kamelets-dev.adoc#kamelet-keda-dev[the KEDA section in the
Kamelets development guide].
//
// The KEDA trait is disabled by default.
//
// +camel-k:trait=keda.
type kedaTrait struct {
trait.BaseTrait `property:",squash"`
- // Enables automatic configuration of the trait.
+ // Enables automatic configuration of the trait. Allows the trait to
infer KEDA triggers from the Kamelets.
Auto *bool `property:"auto" json:"auto,omitempty"`
- // Convert metadata properties to camelCase (needed because trait
properties use kebab-case). Disabled by default.
+ // Convert metadata properties to camelCase (needed because Camel K
trait properties use kebab-case from command line). Disabled by default.
CamelCaseConversion *bool `property:"camel-case-conversion"
json:"camelCaseConversion,omitempty"`
- // Set the spec->replicas field on the top level controller to an
explicit value if missing, to allow KEDA to recognize it as a scalable resource
+ // Set the spec->replicas field on the top level controller to an
explicit value if missing, to allow KEDA to recognize it as a scalable resource.
HackControllerReplicas *bool `property:"hack-controller-replicas"
json:"hackControllerReplicas,omitempty"`
- // Interval (seconds) to check each trigger on (minimum 10 seconds)
+ // Interval (seconds) to check each trigger on (minimum 10 seconds).
PollingInterval *int32 `property:"polling-interval"
json:"pollingInterval,omitempty"`
- // The wait period between the last active trigger reported and scaling
the resource back to 0
+ // The wait period between the last active trigger reported and scaling
the resource back to 0.
CooldownPeriod *int32 `property:"cooldown-period"
json:"cooldownPeriod,omitempty"`
- // Enabling this property allows KEDA to scale the resource down to the
specified number of replicas
+ // Enabling this property allows KEDA to scale the resource down to the
specified number of replicas.
IdleReplicaCount *int32 `property:"idle-replica-count"
json:"idleReplicaCount,omitempty"`
- // Minimum number of replicas
+ // Minimum number of replicas.
MinReplicaCount *int32 `property:"min-replica-count"
json:"minReplicaCount,omitempty"`
- // Maximum number of replicas
+ // Maximum number of replicas.
MaxReplicaCount *int32 `property:"max-replica-count"
json:"maxReplicaCount,omitempty"`
// Definition of triggers according to the KEDA format. Each trigger
must contain `type` field corresponding
// to the name of a KEDA autoscaler and a key/value map named
`metadata` containing specific trigger options.
@@ -244,6 +251,7 @@ func (t *kedaTrait) hackControllerReplicas(e
*trait.Environment) error {
if e.Integration.Spec.Replicas == nil {
one := int32(1)
e.Integration.Spec.Replicas = &one
+ // Update the Integration directly as the spec section
is not merged by default
if err := e.Client.Update(e.Ctx, e.Integration); err !=
nil {
return err
}
diff --git a/config/crd/bases/camel.apache.org_kameletbindings.yaml
b/config/crd/bases/camel.apache.org_kameletbindings.yaml
index 6ad5d2e..0891d1f 100644
--- a/config/crd/bases/camel.apache.org_kameletbindings.yaml
+++ b/config/crd/bases/camel.apache.org_kameletbindings.yaml
@@ -5848,8 +5848,9 @@ spec:
uniqueItems:
type: boolean
x-descriptors:
- description: The list of descriptors that
determine
- which UI components to use on different
views
+ description: XDescriptors is a list of
extended
+ properties that trigger a custom
behavior in
+ external systems
items:
type: string
type: array
@@ -6062,8 +6063,9 @@ spec:
uniqueItems:
type: boolean
x-descriptors:
- description: The list of descriptors that
determine
- which UI components to use on different
views
+ description: XDescriptors is a list of
extended
+ properties that trigger a custom
behavior in
+ external systems
items:
type: string
type: array
@@ -6281,8 +6283,9 @@ spec:
uniqueItems:
type: boolean
x-descriptors:
- description: The list of descriptors
that determine
- which UI components to use on
different views
+ description: XDescriptors is a list of
extended
+ properties that trigger a custom
behavior
+ in external systems
items:
type: string
type: array
diff --git a/config/crd/bases/camel.apache.org_kamelets.yaml
b/config/crd/bases/camel.apache.org_kamelets.yaml
index 8dd01d6..dada3b0 100644
--- a/config/crd/bases/camel.apache.org_kamelets.yaml
+++ b/config/crd/bases/camel.apache.org_kamelets.yaml
@@ -193,8 +193,8 @@ spec:
uniqueItems:
type: boolean
x-descriptors:
- description: The list of descriptors that determine
which
- UI components to use on different views
+ description: XDescriptors is a list of extended
properties
+ that trigger a custom behavior in external systems
items:
type: string
type: array
@@ -405,8 +405,8 @@ spec:
uniqueItems:
type: boolean
x-descriptors:
- description: The list of descriptors that
determine
- which UI components to use on different views
+ description: XDescriptors is a list of
extended properties
+ that trigger a custom behavior in external
systems
items:
type: string
type: array
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 5ece5cd..890e733 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -63,7 +63,7 @@
** xref:traits:jolokia.adoc[Jolokia]
** xref:traits:jvm.adoc[Jvm]
** xref:traits:kamelets.adoc[Kamelets]
-** xref:traits:keda.adoc[KEDA]
+** xref:traits:keda.adoc[Keda]
** xref:traits:knative-service.adoc[Knative Service]
** xref:traits:knative.adoc[Knative]
** xref:traits:logging.adoc[Logging]
diff --git a/docs/modules/ROOT/pages/kamelets/kamelets-dev.adoc
b/docs/modules/ROOT/pages/kamelets/kamelets-dev.adoc
index 688c66c..2904ec0 100644
--- a/docs/modules/ROOT/pages/kamelets/kamelets-dev.adoc
+++ b/docs/modules/ROOT/pages/kamelets/kamelets-dev.adoc
@@ -1427,3 +1427,122 @@ If everything goes well, you should receive a message
during the test execution.
For a more specific test that checks also the content sent to Telegram, you
should add additional Gherking steps
to get and verify the actual message via other Telegram APIs. We're not going
in so much details for this example,
but the Gherkin file highlighted above is a good approximation of the backbone
you'll find in tests for Kamelets of type "sink".
+
+== KEDA Integration
+
+Kamelets of type `source` can be augmented with https://keda.sh/[KEDA]
metadata to automatically configure autoscalers.
+
+The additional KEDA metadata is needed for the following purposes:
+
+- Map Kamelet properties to corresponding KEDA parameters
+- Distinguish which KEDA parameters are needed for authentication (and need to
be placed in a `Secret`)
+- Mark KEDA parameters as required to signal an error during reconciliation
+
+[[kamelet-keda-dev]]
+=== Basic properties to KEDA parameter mapping
+
+Any Kamelet property can be mapped to a KEDA parameter by simply declaring the
mapping in the `x-descriptors` list.
+For example:
+
+.aws-sqs-source.kamelet.yaml
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1alpha1
+kind: Kamelet
+metadata:
+ name: aws-sqs-source
+ labels:
+ camel.apache.org/kamelet.type: "source"
+spec:
+ definition:
+ # ...
+ properties:
+ queueNameOrArn:
+ title: Queue Name
+ description: The SQS Queue Name or ARN
+ type: string
+ x-descriptors:
+ - urn:keda:metadata:queueURL # <1>
+ - urn:keda:required # <2>
+# ...
+----
+<1> The Kamelet property `queueNameOrArn` corresponds to a KEDA metadata
parameter named `queueURL`
+<2> The `queueURL` parameter is required by KEDA
+
+In the example above, the `queueNameOrArn` Kamelet property is declared to
correspond to a KEDA *metadata* parameter named `queueURL`, using the
`urn:keda:metadata:` prefix.
+The `queueURL` parameter is documented in the
https://keda.sh/docs/2.5/scalers/aws-sqs/[the KEDA AWS SQS Queue scaler]
together with other options
+required by KEDA to configure an autoscaler (it can be a full queue URL or a
simple queue name).
+By using the marker descriptor `urn:keda:required`, it is also marked as
required by KEDA.
+
+The `queueURL` is a *metadata* parameter for the autoscaler. In order to
configure *authentication* parameters, the syntax is slightly different:
+
+.aws-sqs-source.kamelet.yaml
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1alpha1
+kind: Kamelet
+metadata:
+ name: aws-sqs-source
+ labels:
+ camel.apache.org/kamelet.type: "source"
+spec:
+ definition:
+ # ...
+ properties:
+ # ...
+ accessKey:
+ title: Access Key
+ description: The access key obtained from AWS
+ type: string
+ format: password
+ x-descriptors:
+ - urn:alm:descriptor:com.tectonic.ui:password
+ - urn:camel:group:credentials
+ - urn:keda:authentication:awsAccessKeyID <1>
+ - urn:keda:required
+# ...
+----
+<1> The Kamelet property `access` corresponds to a KEDA authentication
parameter named `awsAccessKeyID`
+
+This time the property mapping uses the `urn:keda:authentication:` prefix,
declaring it as a KEDA authentication parameter.
+The difference between the two approaches is that authentication parameters
will be injected into a secret by the Camel K
+operator and linked to the KEDA ScaledObject using a TriggerAuthentication
(refer to the https://keda.sh/[KEDA documentation] for more info).
+
+=== Advanced KEDA property mapping
+
+There are cases where KEDA requires some static values to be set in a
ScaledObject or also values computed from multiple Kamelet properties.
+To deal with these cases it's possible to use annotations on the Kamelet
prefixed with `camel.apache.org/keda.metadata.` (for metadata parameters)
+or `camel.apache.org/keda.authentication.` (for authentication parameters).
Those annotations can contain plain fixed values or also *templates* (using the
Go syntax).
+
+For example:
+
+.my-source.kamelet.yaml
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1alpha1
+kind: Kamelet
+metadata:
+ name: my-source
+ labels:
+ camel.apache.org/kamelet.type: "source"
+ annotations:
+ camel.apache.org/keda.authentication.sasl: "plaintext" # <1>
+ camel.apache.org/keda.metadata.queueLength: "5" # <2>
+ camel.apache.org/keda.metadata.queueAddress:
"https://myhost.com/queues/{{.queueName}}"; # <3>
+spec:
+ definition:
+ # ...
+ properties:
+ queueName:
+ title: Queue Name
+ description: The Queue Name
+ type: string
+# ...
+----
+<1> An authentication parameter with a fixed value
+<2> A metadata parameter with a fixed value
+<3> A metadata parameter with a valued computed from a template
+
+When using the template syntax, all Kamelet properties are available as
fields. The default values are used in case they are missing from the user
configuration.
+
+For information on how to use Kamelets with KEDA, see the
xref:kamelets/kamelets-user.adoc#kamelet-keda-user[KEDA section in the user
guide].
diff --git a/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc
b/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc
index c8b5689..7896031 100644
--- a/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc
+++ b/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc
@@ -615,3 +615,42 @@ Kamelets, however, can also contain additional sources in
the `spec` -> `sources
(not necessarily route templates) and will be added once to all the
integrations where the Kamelet is used.
They main role is to do advanced configuration of the integration context
where the Kamelet is used, such as registering
beans in the registry or adding customizers.
+
+[[kamelet-keda-user]]
+== KEDA enabled Kamelets
+
+Some Kamelets are enhanced with KEDA metadata to allow users to automatically
configure autoscalers on them.
+Kamelets with KEDA features can be distinguished by the presence of the
annotation `camel.apache.org/keda.type`,
+which is set to the name of a specific KEDA autoscaler.
+
+A KEDA enabled Kamelet can be used in the same way as any other Kamelet, in a
binding or in an integration.
+KEDA autoscalers are not enabled by default: they need to be manually enabled
by the user via the `keda` trait.
+
+In a KameletBinding, the KEDA trait can be enabled using annotations:
+
+.my-keda-binding.yaml
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1alpha1
+kind: KameletBinding
+metadata:
+ name: my-keda-binding
+ annotations:
+ trait.camel.apache.org/keda.enabled: "true"
+spec:
+ source:
+ # ...
+ sink:
+ # ...
+----
+
+In an integration, it can be enabled using `kamel run` args, for example:
+
+[source,shell]
+----
+kamel run my-keda-integration.yaml -t keda.enabled=true
+----
+
+NOTE: Make sure that the `my-keda-integration` uses at least one KEDA enabled
Kamelet, otherwise enabling KEDA (without other options) will have no effect.
+
+For information on how to create KEDA enabled Kamelets, see the
xref:kamelets/kamelets-dev.adoc#kamelet-keda-dev[KEDA section in the
development guide].
diff --git a/docs/modules/ROOT/partials/apis/crds-html.adoc
b/docs/modules/ROOT/partials/apis/crds-html.adoc
index ed34383..131c061 100644
--- a/docs/modules/ROOT/partials/apis/crds-html.adoc
+++ b/docs/modules/ROOT/partials/apis/crds-html.adoc
@@ -6007,7 +6007,7 @@ bool
</em>
</td>
<td>
-<p>The list of descriptors that determine which UI components to use on
different views</p>
+<p>XDescriptors is a list of extended properties that trigger a custom
behavior in external systems</p>
</td>
</tr>
</tbody>
diff --git a/docs/modules/traits/pages/keda.adoc
b/docs/modules/traits/pages/keda.adoc
index a73dabd..6f0fcac 100644
--- a/docs/modules/traits/pages/keda.adoc
+++ b/docs/modules/traits/pages/keda.adoc
@@ -1,9 +1,16 @@
= Keda Trait
// Start of autogenerated code - DO NOT EDIT! (description)
-The Keda trait can be used for automatic integration with Keda autoscalers.
+The KEDA trait can be used for automatic integration with KEDA autoscalers.
+The trait can be either manually configured using the `triggers` option or
automatically configured
+via markers in the Kamelets.
-The Keda trait is disabled by default.
+For information on how to use KEDA enabled Kamelets with the KEDA trait, refer
to
+xref:kamelets/kamelets-user.adoc#kamelet-keda-user[the KEDA section in the
Kamelets user guide].
+If you want to create Kamelets that contain KEDA metadata, refer to
+xref:kamelets/kamelets-dev.adoc#kamelet-keda-dev[the KEDA section in the
Kamelets development guide].
+
+The KEDA trait is disabled by default.
This trait is available in the following profiles: **Kubernetes, Knative,
OpenShift**.
@@ -29,15 +36,40 @@ The following configuration options are available:
| keda.auto
| bool
-| Enables automatic configuration of the trait.
+| Enables automatic configuration of the trait. Allows the trait to infer KEDA
triggers from the Kamelets.
| keda.camel-case-conversion
| bool
-| Convert metadata properties to camelCase (needed because trait properties
use kebab-case). Enabled by default.
+| Convert metadata properties to camelCase (needed because Camel K trait
properties use kebab-case from command line). Disabled by default.
+
+| keda.hack-controller-replicas
+| bool
+| Set the spec->replicas field on the top level controller to an explicit
value if missing, to allow KEDA to recognize it as a scalable resource.
+
+| keda.polling-interval
+| int32
+| Interval (seconds) to check each trigger on (minimum 10 seconds).
+
+| keda.cooldown-period
+| int32
+| The wait period between the last active trigger reported and scaling the
resource back to 0.
+
+| keda.idle-replica-count
+| int32
+| Enabling this property allows KEDA to scale the resource down to the
specified number of replicas.
+
+| keda.min-replica-count
+| int32
+| Minimum number of replicas.
+
+| keda.max-replica-count
+| int32
+| Maximum number of replicas.
| keda.triggers
| []github.com/apache/camel-k/addons/keda.kedaTrigger
-| Triggers
+| Definition of triggers according to the KEDA format. Each trigger must
contain `type` field corresponding
+to the name of a KEDA autoscaler and a key/value map named `metadata`
containing specific trigger options.
|===
diff --git a/helm/camel-k/crds/crd-kamelet-binding.yaml
b/helm/camel-k/crds/crd-kamelet-binding.yaml
index 6ad5d2e..0891d1f 100644
--- a/helm/camel-k/crds/crd-kamelet-binding.yaml
+++ b/helm/camel-k/crds/crd-kamelet-binding.yaml
@@ -5848,8 +5848,9 @@ spec:
uniqueItems:
type: boolean
x-descriptors:
- description: The list of descriptors that
determine
- which UI components to use on different
views
+ description: XDescriptors is a list of
extended
+ properties that trigger a custom
behavior in
+ external systems
items:
type: string
type: array
@@ -6062,8 +6063,9 @@ spec:
uniqueItems:
type: boolean
x-descriptors:
- description: The list of descriptors that
determine
- which UI components to use on different
views
+ description: XDescriptors is a list of
extended
+ properties that trigger a custom
behavior in
+ external systems
items:
type: string
type: array
@@ -6281,8 +6283,9 @@ spec:
uniqueItems:
type: boolean
x-descriptors:
- description: The list of descriptors
that determine
- which UI components to use on
different views
+ description: XDescriptors is a list of
extended
+ properties that trigger a custom
behavior
+ in external systems
items:
type: string
type: array
diff --git a/helm/camel-k/crds/crd-kamelet.yaml
b/helm/camel-k/crds/crd-kamelet.yaml
index 8dd01d6..dada3b0 100644
--- a/helm/camel-k/crds/crd-kamelet.yaml
+++ b/helm/camel-k/crds/crd-kamelet.yaml
@@ -193,8 +193,8 @@ spec:
uniqueItems:
type: boolean
x-descriptors:
- description: The list of descriptors that determine
which
- UI components to use on different views
+ description: XDescriptors is a list of extended
properties
+ that trigger a custom behavior in external systems
items:
type: string
type: array
@@ -405,8 +405,8 @@ spec:
uniqueItems:
type: boolean
x-descriptors:
- description: The list of descriptors that
determine
- which UI components to use on different views
+ description: XDescriptors is a list of
extended properties
+ that trigger a custom behavior in external
systems
items:
type: string
type: array
diff --git a/resources/traits.yaml b/resources/traits.yaml
index 7bd54bf..a6c05b8 100755
--- a/resources/traits.yaml
+++ b/resources/traits.yaml
@@ -576,8 +576,14 @@ traits:
- Kubernetes
- Knative
- OpenShift
- description: The Keda trait can be used for automatic integration with Keda
autoscalers.
- The Keda trait is disabled by default.
+ description: The KEDA trait can be used for automatic integration with KEDA
autoscalers.
+ The trait can be either manually configured using the `triggers` option or
automatically
+ configured via markers in the Kamelets. For information on how to use KEDA
enabled
+ Kamelets with the KEDA trait, refer to
xref:kamelets/kamelets-user.adoc#kamelet-keda-user[the
+ KEDA section in the Kamelets user guide]. If you want to create Kamelets
that
+ contain KEDA metadata, refer to
xref:kamelets/kamelets-dev.adoc#kamelet-keda-dev[the
+ KEDA section in the Kamelets development guide]. The KEDA trait is
disabled by
+ default.
properties:
- name: enabled
type: bool
@@ -585,14 +591,38 @@ traits:
property.
- name: auto
type: bool
- description: Enables automatic configuration of the trait.
+ description: Enables automatic configuration of the trait. Allows the
trait to
+ infer KEDA triggers from the Kamelets.
- name: camel-case-conversion
type: bool
- description: Convert metadata properties to camelCase (needed because
trait properties
- use kebab-case). Enabled by default.
+ description: Convert metadata properties to camelCase (needed because
Camel K
+ trait properties use kebab-case from command line). Disabled by default.
+ - name: hack-controller-replicas
+ type: bool
+ description: Set the spec->replicas field on the top level controller to
an explicit
+ value if missing, to allow KEDA to recognize it as a scalable resource.
+ - name: polling-interval
+ type: int32
+ description: Interval (seconds) to check each trigger on (minimum 10
seconds).
+ - name: cooldown-period
+ type: int32
+ description: The wait period between the last active trigger reported and
scaling
+ the resource back to 0.
+ - name: idle-replica-count
+ type: int32
+ description: Enabling this property allows KEDA to scale the resource down
to
+ the specified number of replicas.
+ - name: min-replica-count
+ type: int32
+ description: Minimum number of replicas.
+ - name: max-replica-count
+ type: int32
+ description: Maximum number of replicas.
- name: triggers
type: '[]github.com/apache/camel-k/addons/keda.kedaTrigger'
- description: Triggers
+ description: Definition of triggers according to the KEDA format. Each
trigger
+ must contain `type` field correspondingto the name of a KEDA autoscaler
and
+ a key/value map named `metadata` containing specific trigger options.
- name: knative-service
platform: false
profiles:
