[camel-k] 03/09: doc(pipeline): more design details

[pc...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

pcongiusti pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-k.git

commit 13916436c5876fd9c507a27386ba68022ec63704
Author: Pasquale Congiusti <pa...@gmail.com>
AuthorDate: Mon Sep 25 16:18:45 2023 +0200

    doc(pipeline): more design details
---
 docs/modules/ROOT/camel_k_pipeline.png             | Bin 0 -> 17355 bytes
 .../ROOT/pages/architecture/cr/camel-catalog.adoc  |   4 +---
 docs/modules/ROOT/pages/pipeline/pipeline.adoc     |  24 +++++++++++++++------
 docs/modules/ROOT/pages/pipeline/tekton.adoc       |   7 +++++-
 .../ROOT/pages/running/runtime-version.adoc        |   2 +-
 5 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/docs/modules/ROOT/camel_k_pipeline.png b/docs/modules/ROOT/camel_k_pipeline.png
new file mode 100644
index 000000000..4150d8dca
Binary files /dev/null and b/docs/modules/ROOT/camel_k_pipeline.png differ
diff --git a/docs/modules/ROOT/pages/architecture/cr/camel-catalog.adoc b/docs/modules/ROOT/pages/architecture/cr/camel-catalog.adoc
index f301dc6e0..ce1a8126f 100644
--- a/docs/modules/ROOT/pages/architecture/cr/camel-catalog.adoc
+++ b/docs/modules/ROOT/pages/architecture/cr/camel-catalog.adoc
@@ -3,9 +3,7 @@
 
 The *CamelCatalog* is a resource that provides metadata related to what is included in the xref:architecture/runtime.adoc[Runtime] in term of Camel components, languages, dataformats and capabilities provided.
 
-Starting from Camel K version 2, it is a dynamic resource which is reconciled and produces as an output a container image required to build the Camel application when using the builder `Pod` strategy. This container image contains all the toolings which will build the artifacts, above all the Quarkus tools required to compile natively.
-
-NOTE: each catalog generates a different builder image starting from Camel K runtime version 1.17. You cannot run a Camel K runtime < 1.17 with Camel K version 2.
+NOTE: each catalog may require to specify a container tool image eventually used by the build process starting from Camel K runtime version 1.17. You cannot run a Camel K runtime < 1.17 with Camel K version 2.
 
 [NOTE]
 ====
diff --git a/docs/modules/ROOT/pages/pipeline/pipeline.adoc b/docs/modules/ROOT/pages/pipeline/pipeline.adoc
index 9555cf5bf..5e593dfb8 100644
--- a/docs/modules/ROOT/pages/pipeline/pipeline.adoc
+++ b/docs/modules/ROOT/pages/pipeline/pipeline.adoc
@@ -1,9 +1,24 @@
 [[build-pipeline]]
 = Build Pipeline
-
 Since version 2.0, we've introduced the concept of `Pipeline` in order to provide a degree of flexibility for those user that want to customize the entire building process. We can think of a pipeline as a series of tasks that can be executed after the project generation and before the artifact publishing into the container registry.
 
-In Camel K version 1 we used to have 2 static tasks: `builder` and `publisher` (named after the strategy adopted, ie, `spectrum`). Now you can include any futher task in the middle by opportunely configuring the Build. Let's see an example:
+In Camel K version 1 we used to have 2 static tasks: `builder` and `publisher` (named after the strategy adopted, ie, `spectrum`). Now you can include any further task in the middle by opportunely configuring the Build. Here a diagram illustrating the pipeline:
+
+image::camel_k_pipeline..png[Camel K Pipeline, width=1024]
+
+We have 3 tasks which are required by Camel K to perform a build and provide a container image which will be used to start a Camel application. The **build** is a Maven process which is in charge to create a maven project based on the Integration sources provided. Then, after the Maven project is created and compiled, you can add any custom task (see section below). With this part we are introducing that level of flexibility required to accommodate any company build process. This part is [...]
+
+In reality we do make use of the custom task in one particular situation. In order to build a Quarkus Native image, the quarkus trait influences the builder in order to include a custom task which takes care of executing the native image compilation. But this is completely hidden to the final user.
+
+Once the build and any customization are over, the **package** task takes care to prepare the context later required by the publishing operations. Basically this task is in charge to copy all artifacts and also prepare a Dockerfile which could be used eventually by the rest of the process. Finally, the **publish** task is in charge to generate and push the container to the registry using all the artifacts generated in the package task.
+
+[[add-custom-tasks]]
+== Add custom user tasks
+As you have seen, the final user can include any optional task after a build operation is performed. We think this is the best moment when any custom operation can be performed as it is the immediate step after the Maven project is generated. And ideally, the context of any custom operation is the project.
+
+NOTE: Please, notice that, since the customization may require any tool not available in the operator container, you will need to run any additional task using builder `pod` strategy.
+
+Let's see an example:
 
 ```yaml
 spec:
@@ -25,11 +40,8 @@ The custom tasks will be executed in the directory where the Camel K runtime Mav
 
 The goal is to let the user perform custom tasks which may result in a success or a failure. If the task executed results in a failure, then, the entire build is stopped and fails accordingly.
 
-WARNING: The custom tasks are only available only when using pod strategy.
-
 [[build-pipeline-trait]]
-== Configuring via builder trait
-
+=== Configuring via builder trait
 We are aware that configuring the `Build` type directly is something that the majority of users won't do. For this reason we're enabling the same feature in the xref:traits:builder.adoc[Builder trait].
 
 Maintaining the example above as a reference, configuring a custom task will be as easy as adding a trait property when running your Integration, for instance, via CLI:
diff --git a/docs/modules/ROOT/pages/pipeline/tekton.adoc b/docs/modules/ROOT/pages/pipeline/tekton.adoc
index b002f995b..b0f143626 100644
--- a/docs/modules/ROOT/pages/pipeline/tekton.adoc
+++ b/docs/modules/ROOT/pages/pipeline/tekton.adoc
@@ -1,9 +1,14 @@
 [[full-fledged-pipeline]]
 = Full fledged Pipeline
 
-If you're running a production grade enterprise system, you likely want to use a full fledged CICD technology. The basic features provided by our xref:pipeline/pipeline.adoc[homemade Pipeline] may be definitely limited in such situation. For those production grade requirements we suggest to integrate one of the many CICD technologies around. One that we want to suggest and for which we provide an opinionated approach is https://tekton.dev/[Tekton CICD].
+If you're running a build process over any external pipeline, you likely want to use that CICD technology in conjunction with Camel K. The features provided by our xref:pipeline/pipeline.adoc[Camel K Pipeline] may be limited in such situation. For those requirements we suggest to integrate one of the many CICD technologies around. One that we want to suggest and for which we provide an opinionated approach is https://tekton.dev/[Tekton CICD].
 
 [[tekton-pipeline]]
 == Integrate with Tekton
 
 Since Camel K version 2 we are supporting a https://hub.tekton.dev/tekton/task/kamel-run[`kamel-run` Task] included in https://hub.tekton.dev/[Tekton Hub]. You can find the instructions and some example to show you how to adopt this technology together with Camel K. The prerequisite is to have Camel K and Tekton operators up and running. The brief guide requires certain previous familiarity with Tekton technology as well.
+
+[[cicd-pipeline]]
+== Integrate with other pipelines
+
+There are many CICD tools and we cannot provide support for every technology. However, Camel K gives you the possibility to run your own build with the CICD technology of choice and operate the Camel application accordingly. What you need to do is to let the CICD technology to provide an Integration custom resource with the container image built by the pipeline, ie: `kamel run test.yaml -t container.image=docker.io/my-org/my-image:xyz`.
\ No newline at end of file
diff --git a/docs/modules/ROOT/pages/running/runtime-version.adoc b/docs/modules/ROOT/pages/running/runtime-version.adoc
index c92e9062e..5e1ccb03a 100644
--- a/docs/modules/ROOT/pages/running/runtime-version.adoc
+++ b/docs/modules/ROOT/pages/running/runtime-version.adoc
@@ -14,7 +14,7 @@ Having the ability to choose the runtime, gives you the ability to specify which
 
 This feature requires the dynamic generation of a builder that contains all the tooling expected by the build phase. In particular, this is a requirement for Quarkus native builds which, from now on, can be only done with builder `Pod` strategy.
 
-When you are creating a new runtime for which a xref:architecture/cr/camel-catalog.adoc[CamelCatalog] does not yest exist, Camel K Operator is in charge to create such a catalog. The creation of a new Catalog binds to the creation of a container image builder which will later be used by the builder `Pod` to build a Camel application which is specific to such a runtime.
+When you are creating a new runtime for which a xref:architecture/cr/camel-catalog.adoc[CamelCatalog] does not yest exist, Camel K Operator is in charge to create such a catalog. Every CamelCatalog may carry the definition of a container image builder which may later be used by the builder `Pod` to build a Camel application which is specific to such a runtime (for instance, when running a Quarkus Native build).
 
 == Pin a runtime version