astefanutti commented on a change in pull request #2465:
URL: https://github.com/apache/camel-k/pull/2465#discussion_r660741647
##########
File path: docs/modules/ROOT/pages/architecture/traits.adoc
##########
@@ -1,6 +1,58 @@
[[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`.
+
+=== Trait configuration
+
+A Camel K user will provide a trait configuration via CLI (`--trait` or `-t`
flag) or setting via `Integration` metadata. 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.
Review comment:
I'd suggest: or setting directly its configuration into the
`Integration` resource.
##########
File path: docs/modules/ROOT/pages/architecture/traits.adoc
##########
@@ -1,6 +1,58 @@
[[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`.
+
+=== Trait configuration
+
+A Camel K user will provide a trait configuration via CLI (`--trait` or `-t`
flag) or setting via `Integration` metadata. 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.
+
+=== 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:
+
+[source,go]
+----
+type Trait interface {
+ Identifiable
+ client.Injectable
+ InjectContext(context.Context)
+ Configure(environment *Environment) (bool, error)
+ Apply(environment *Environment) error
+ InfluencesKit() bool
+ IsPlatformTrait() bool
+ RequiresIntegrationPlatform() bool
+ IsAllowedInProfile(v1.TraitProfile) bool
+ Order() int
+}
+----
+
+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).
+
+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.
+
+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 functions `InfluencesKit()`, `IsPlatformTrait()` and
`RequiresIntegrationPlatform()` are easy to understand. They are used to
determine if a trait has to influece an `IntegrationKit` build/initiatlization,
if it's a platform trait (ie, needed by the platform itself) or are requiring
the presence of an `IntegrationPlatform`.
Review comment:
I'd suggest: The `InfluencesKit()`, `IsPlatformTrait()` and
`RequiresIntegrationPlatform()` methods ...
##########
File path: docs/modules/ROOT/pages/architecture/traits.adoc
##########
@@ -1,6 +1,58 @@
[[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`.
+
+=== Trait configuration
+
+A Camel K user will provide a trait configuration via CLI (`--trait` or `-t`
flag) or setting via `Integration` metadata. 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.
Review comment:
It may be worth providing an example.
--
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: commits-unsubscr...@camel.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
