This is an automated email from the ASF dual-hosted git repository. astefanutti pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/camel-k.git
commit bf213e747bf60f38c8a97c41aec2650c73959367 Author: Pasquale Congiusti <[email protected]> AuthorDate: Wed Jun 30 12:26:13 2021 +0200 doc(architecture): trait configuration link --- docs/modules/ROOT/pages/architecture/traits.adoc | 22 +++++++--------- docs/modules/traits/pages/traits.adoc | 33 ++++++++++++++++++++++-- 2 files changed, 40 insertions(+), 15 deletions(-) diff --git a/docs/modules/ROOT/pages/architecture/traits.adoc b/docs/modules/ROOT/pages/architecture/traits.adoc index f83ba6d..203445c 100644 --- a/docs/modules/ROOT/pages/architecture/traits.adoc +++ b/docs/modules/ROOT/pages/architecture/traits.adoc @@ -11,6 +11,7 @@ This page is dedicated to developers/engineers willing to dive more in the low l NOTE: This document reflects Camel K version 1.5. It may not reflect slight changes developed after this review. +[[traits-life-cycle]] == Traits life cycle Traits are typically used to tune several aspects of an `Integration`. However, you will learn that we are using the same concept to influence the build of `IntegrationKits`. Therefore, we can distinguish between those traits that can be applied to either one or the other type. Another important thing to know is that the platform uses this mechanism to perform many common (hidden to the user) operations. We use to identify those trait as **platform traits**. Misusing a platform trait, ma [...] @@ -23,17 +24,12 @@ Another important concept related to the trait lifecycle is the **trait profile* A profile is useful to identify on which kind of cluster a trait has to run: vanilla `Kubernetes`, `Openshift` or OpenShift/Kubernetes clusters powered by `Knative`. The default is to allow a trait on any profile; each trait can specify a different behavior (ie, running a trait only for a profile as it happens with `Knative`). +[[traits-configuration]] === Trait configuration -A Camel K user will provide a trait configuration via CLI (`--trait` or `-t` flag) or setting directly its configuration into the `Integration` resource. Each trait has a unique id and can expose any kind of parameter ie, `kamel run -t [trait-id].[key]=[value]`. The operator will transform that _key_ and _value_ in the related trait variable. - -As an example, let's see what to do when you want to set an additional `JVM` classpath pointing to a known dependency on your `Integration`: - -[source,console] ----- -$ kamel run --trait jvm.classpath=/path/to/my.jar MyIntegration.java ----- +A Camel K user will provide a trait configuration via CLI (`--trait` or `-t` flag) or setting directly its configuration into the `Integration` resource. Each trait has a unique id and can expose any kind of parameter ie, `kamel run -t [trait-id].[key]=[value]`. The operator will transform that _key_ and _value_ in the related trait variable. You can have a further look at the xref:traits:traits.adoc#traits-configuration[configuration details]. +[[traits-interface]] === Trait interface In order to understand better the logic behind the trait managment, let's have a look at the `https://github.com/apache/camel-k/blob/main/pkg/trait/trait_types.go#L70[Trait]` interface: @@ -54,12 +50,12 @@ type Trait interface { } ---- -Each trait will implement this interface. The most important functions that will be invoked by the xref:architecture/operator.adoc[Operator] are `Configure()` and `Apply()`. Basically, the `Configure()` function will set those inputs aforementioned (each trait has its own). The function is in charge to verify also the correctness of those expected parameters, where it makes sense (ie, a well expected `Kubernetes` resource name). +Each trait will implement this interface. The most important methods that will be invoked by the xref:architecture/operator.adoc[Operator] are `Configure()` and `Apply()`. Basically, the `Configure()` method will set those inputs aforementioned (each trait has its own). The method is in charge to verify also the correctness of those expected parameters, where it makes sense (ie, a well expected `Kubernetes` resource name). -Once configured, the `Apply()` function will be called along the build or initialization phase in order to do the business logic expected for it. The `environment` variable will give you all the below resources you will need to perform your operation (ie, the `Integration` or any Kubernetes resource attached to it). You can have a deeper look at the `https://github.com/apache/camel-k/blob/main/pkg/trait/trait_types.go#L188[Environment]` struct. +Once configured, the `Apply()` method will be called along the build or initialization phase in order to do the business logic expected for it. The `environment` variable will give you all the below resources you will need to perform your operation (ie, the `Integration` or any Kubernetes resource attached to it). You can have a deeper look at the `https://github.com/apache/camel-k/blob/main/pkg/trait/trait_types.go#L188[Environment]` struct. -The `Order()` function helps in resolving the order of execution of different traits. As every trait can be expected to be run before or after another trait, or any other controller operation. +The `Order()` method helps in resolving the order of execution of different traits. As every trait can be expected to be run before or after another trait, or any other controller operation. -The `InfluencesKit()`, `IsPlatformTrait()` and `RequiresIntegrationPlatform()` functions are easy to understand. They are used to determine if a trait has to influence an `IntegrationKit` build/initialization, if it's a platform trait (ie, needed by the platform itself) or are requiring the presence of an `IntegrationPlatform`. +The `InfluencesKit()`, `IsPlatformTrait()` and `RequiresIntegrationPlatform()` methods are easy to understand. They are used to determine if a trait has to influence an `IntegrationKit` build/initialization, if it's a platform trait (ie, needed by the platform itself) or are requiring the presence of an `IntegrationPlatform`. -Finally, through the `IsAllowedInProfile()` function we can override the default behavior (allow the trait for any profile). We must specify the profile we expect for this trait to be executed properly. +Finally, through the `IsAllowedInProfile()` method we can override the default behavior (allow the trait for any profile). We must specify the profile we expect for this trait to be executed properly. diff --git a/docs/modules/traits/pages/traits.adoc b/docs/modules/traits/pages/traits.adoc index 8f3a999..1f21359 100644 --- a/docs/modules/traits/pages/traits.adoc +++ b/docs/modules/traits/pages/traits.adoc @@ -8,6 +8,7 @@ Camel K provide sensible defaults for all such traits, taking into account the d the integration is going to run into. However, it's possible for a **expert user** to configure them in order to obtain a different behavior. +[[traits-configuration]] == Configuration Each trait has a unique ID that can be used to configure it using the command line tool. @@ -31,8 +32,36 @@ NOTE: Some traits are applicable only to specific platforms (see the "profiles" A trait may have additional properties that can be configured by the end user. -See the trait description pages for more information on a specific trait: +[[traits-integration-spec]] +=== Configure the Integration spec -There are indexCount:[] traits. +Let's use a further example to show how to configure a trait in an `Integration`. If you want to set an additional `JVM` classpath pointing to a known dependency, we can use the CLI as we've seen above: + +[source,console] +---- +$ kamel run --trait jvm.classpath=/path/to/my.jar MyIntegration.java +---- + +The command is creating an `Integration` with the configuration below: + +[source,yaml] +---- +apiVersion: camel.apache.org/v1 +kind: Integration +metadata: + name: my-integration +spec: + traits: + jvm: + configuration: + classpath: /path/to/my.jar +... +---- + +The `.spec.traits` holds an array of traits, identified by their id (`jvm`, in this case). Then, the `.jvm.configuration.classpath` is the property we want to set. If you need to set a trait directly in the `Integration` spec, then, you should proceed in the way illustrated above. + +[[traits-list]] +== List of available traits +There are indexCount:[] traits. See each trait description page for more information on a specific trait: indexList::[]
