astefanutti commented on a change in pull request #2465:
URL: https://github.com/apache/camel-k/pull/2465#discussion_r661225412
##########
File path: docs/modules/ROOT/pages/architecture/traits.adoc
##########
@@ -1,6 +1,65 @@
[[traits]]
= Traits
-image::architecture/camel-k-traits.jpg[traits]
+image::architecture/camel-k-traits.jpg[traits, width=1024]
-TBD
+Traits are high level named features of Camel K that can be enabled/disabled
or configured to customize the behavior of the final `Integration`. You can
think a **trait** as a possible way to tune your `Integration` on the running
platform. Through the configuration of a trait, you will be able to specify
certain characteristics configuring low level details, if you need to.
+
+Advanced users will find very useful to configure certain facets of the
deployments or to control how to manage the cluster resources. Most of the
times you need to interact with the cluster, you will need to configure a trait
that control such cluster behavior (think at the `Pod`, `Container`, `Service`
traits which map to the `Kubernetes` resources of the same name).
+
+This page is dedicated to developers/engineers willing to dive more in the low
level details of Camel K development. You can find a complete list of available
traits and how to configure them in the xref:traits:traits.adoc[trait section].
+
+NOTE: This document reflects Camel K version 1.5. It may not reflect slight
changes developed after this review.
+
+== 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, may result in execution errors.
+
+Another important concept related to the trait lifecycle is the **trait
profile**. At this time, Camel K is supporting the following profiles:
+
+* Kubernetes
+* Openshift
+* Knative
+
+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`).
+
+=== 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
+----
+
Review comment:
Here, I'd suggest to add something like:
> Or directly by editing the Integration resource, e.g.:
> ```yaml
> apiVersion: camel.apache.org/v1
> kind: Integration
> metadata:
> name: example
> spec:
> traits:
> jvm:
> configuration:
> classpath:
```
##########
File path: docs/modules/ROOT/pages/architecture/traits.adoc
##########
@@ -1,6 +1,65 @@
[[traits]]
= Traits
-image::architecture/camel-k-traits.jpg[traits]
+image::architecture/camel-k-traits.jpg[traits, width=1024]
-TBD
+Traits are high level named features of Camel K that can be enabled/disabled
or configured to customize the behavior of the final `Integration`. You can
think a **trait** as a possible way to tune your `Integration` on the running
platform. Through the configuration of a trait, you will be able to specify
certain characteristics configuring low level details, if you need to.
+
+Advanced users will find very useful to configure certain facets of the
deployments or to control how to manage the cluster resources. Most of the
times you need to interact with the cluster, you will need to configure a trait
that control such cluster behavior (think at the `Pod`, `Container`, `Service`
traits which map to the `Kubernetes` resources of the same name).
+
+This page is dedicated to developers/engineers willing to dive more in the low
level details of Camel K development. You can find a complete list of available
traits and how to configure them in the xref:traits:traits.adoc[trait section].
+
+NOTE: This document reflects Camel K version 1.5. It may not reflect slight
changes developed after this review.
+
+== 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, may result in execution errors.
+
+Another important concept related to the trait lifecycle is the **trait
profile**. At this time, Camel K is supporting the following profiles:
+
+* Kubernetes
+* Openshift
+* Knative
+
+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`).
+
+=== 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
+----
+
Review comment:
Here, I'd suggest to add something like:
> Or directly by editing the Integration resource, e.g.:
> ```yaml
> apiVersion: camel.apache.org/v1
> kind: Integration
> metadata:
> name: example
> spec:
> traits:
> jvm:
> configuration:
> classpath:
> ```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
