You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by lb...@apache.org on 2020/07/21 08:02:32 UTC
[camel-k] branch master updated: Initial architecture documentation
This is an automated email from the ASF dual-hosted git repository.
lburgazzoli pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel-k.git
The following commit(s) were added to refs/heads/master by this push:
new acf50e8 Initial architecture documentation
acf50e8 is described below
commit acf50e8a968ec6235859374cb0f1a8f01ac64ff4
Author: lburgazzoli <lb...@gmail.com>
AuthorDate: Wed Jul 8 19:08:54 2020 +0200
Initial architecture documentation
---
docs/modules/ROOT/assets/diagrams/README.adoc | 4 ++
.../diagrams/camel-k-operator-control-loop.drawio | 1 +
.../diagrams/camel-k-state-machine-basic.drawio | 1 +
.../diagrams/camel-k-state-machine-build.drawio | 1 +
...mel-k-state-machine-integration-platform.drawio | 1 +
.../camel-k-state-machine-integration.drawio | 1 +
.../camel-k-state-machine-integrationkit.drawio | 1 +
.../assets/diagrams/operator-control-loop.drawio | 1 +
.../architecture/camel-k-operator-control-loop.png | Bin 0 -> 15493 bytes
.../images/architecture/camel-k-operator.jpg | Bin 0 -> 116514 bytes
.../images/architecture/camel-k-runtimes.jpg | Bin 0 -> 121360 bytes
.../architecture/camel-k-state-machine-basic.png | Bin 0 -> 12740 bytes
.../architecture/camel-k-state-machine-build.png | Bin 0 -> 21947 bytes
.../camel-k-state-machine-integration-platform.png | Bin 0 -> 38794 bytes
.../camel-k-state-machine-integration.png | Bin 0 -> 56904 bytes
.../camel-k-state-machine-integrationkit.png | Bin 0 -> 28205 bytes
.../assets/images/architecture/camel-k-traits.jpg | Bin 0 -> 139978 bytes
.../ROOT/assets/images/architecture/camel-k.jpg | Bin 0 -> 129474 bytes
.../images/architecture/operator-control-loop.png | Bin 0 -> 4923 bytes
docs/modules/ROOT/nav.adoc | 9 ++++
.../ROOT/pages/architecture/architecture.adoc | 11 +++++
docs/modules/ROOT/pages/architecture/cr/build.adoc | 27 ++++++++++++
.../ROOT/pages/architecture/cr/camel-catalog.adoc | 9 ++++
.../pages/architecture/cr/integration-kit.adoc | 34 ++++++++++++++
.../architecture/cr/integration-platform.adoc | 35 +++++++++++++++
.../ROOT/pages/architecture/cr/integration.adoc | 36 +++++++++++++++
docs/modules/ROOT/pages/architecture/operator.adoc | 49 +++++++++++++++++++++
docs/modules/ROOT/pages/architecture/runtime.adoc | 6 +++
docs/modules/ROOT/pages/architecture/traits.adoc | 6 +++
29 files changed, 233 insertions(+)
diff --git a/docs/modules/ROOT/assets/diagrams/README.adoc b/docs/modules/ROOT/assets/diagrams/README.adoc
new file mode 100644
index 0000000..aa50d57
--- /dev/null
+++ b/docs/modules/ROOT/assets/diagrams/README.adoc
@@ -0,0 +1,4 @@
+Diagrams
+========
+
+Files generated by https://app.diagrams.net
diff --git a/docs/modules/ROOT/assets/diagrams/camel-k-operator-control-loop.drawio b/docs/modules/ROOT/assets/diagrams/camel-k-operator-control-loop.drawio
new file mode 100644
index 0000000..edc8c7c
--- /dev/null
+++ b/docs/modules/ROOT/assets/diagrams/camel-k-operator-control-loop.drawio
@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2020-07-12T14:12:27.384Z" agent="5.0 (X11)" etag="2d2Qz5dBpfifzbfyRSyL" version="13.4.2" type="device"><diagram id="uLhqvVcLPNciDg8s2euJ" name="Page-1">5VnblpowFP0aH+0CIoiPXjtd09uqD50+ZiADaQNxYhixX98Ewk3QwRlHdKprabKTkGSffQ4n0APTIP7I4Mr/Ql1Eeobmxj0w6xnGyNTFrwS2KWACIwU8ht0U0gtgif8iBWoKjbCL1pWOnFLC8aoKOjQMkcMrGGSMbqrdHiipzrqCHqoBSweSOvoTu9xPUdvUCvwGYc/PZtY11RLArLMC1j506aYEgXkPTBmlPC0F8RQRyV3GSzpusac1XxhDIW8zwKN0YC8W4eaxzyYj3B+Hy7ivj9LLPEESqR2r1fJtRg [...]
\ No newline at end of file
diff --git a/docs/modules/ROOT/assets/diagrams/camel-k-state-machine-basic.drawio b/docs/modules/ROOT/assets/diagrams/camel-k-state-machine-basic.drawio
new file mode 100644
index 0000000..06d5c0a
--- /dev/null
+++ b/docs/modules/ROOT/assets/diagrams/camel-k-state-machine-basic.drawio
@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2020-07-12T09:59:15.990Z" agent="5.0 (X11)" etag="oQLwBsUhoG38y9AXE9Zh" version="13.4.2" type="device"><diagram id="48Lw8YTL3a5nQOH6-A0w" name="Page-1">7VjbctsgEP0aPzajq2M9JnbSZKadpvV02j4SaS3RYKFByJd8fRcZWUg4sevGM562cR7gsCxwzoIWBv54vnovSJF95Amwgeckq4E/GXieG3jeQP07yXqDjNxwA6SCJtqoBab0GTToaLSiCZQdQ8k5k7TogjHPc4hlByNC8GXXbMZZd9SCpGAB05gwG/1GE5npVYROi98BTbNmZNfRLXPSGGugzEjClwbk3wz8seBcbkrz1RiYIq/hZdPv9oXW7cQE5PKQDpO75x/xPf30/PVnSL7zWRx9/fzO33hZEFbpBV [...]
\ No newline at end of file
diff --git a/docs/modules/ROOT/assets/diagrams/camel-k-state-machine-build.drawio b/docs/modules/ROOT/assets/diagrams/camel-k-state-machine-build.drawio
new file mode 100644
index 0000000..f14deed
--- /dev/null
+++ b/docs/modules/ROOT/assets/diagrams/camel-k-state-machine-build.drawio
@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2020-07-13T12:35:22.888Z" agent="5.0 (X11)" etag="e5B2q61YGPAHzRJHm3Ih" version="13.4.2" type="device"><diagram id="0Kwz7zGRW0z1vaULMuBK" name="Page-1">7VtZc+I4EP41PCblS8Y8Bkgme2SWGaYqM09Tii1AFWF5bTmB/fUr2fItAwE7RwWoSqyW1Ja7v+5PhxmYk/XmSwiD1R31EBkYmrcZmNOBYYyAzv8KwTYVANNIBcsQe6lILwRz/B+SQk1KY+yhqNKQUUoYDqpCl/o+cllFBsOQPlebLSip3jWAS9QQzF1ImtJ77LFVKnWAVshvEV6usjvrmqxZw6yxFEQr6NHnksi8HpiTkFKWXq03E0SE7TK7pP1uWmrzgYXIZ4d0uP46C378dXs3iy/+HN9PAme7wRdSyx [...]
\ No newline at end of file
diff --git a/docs/modules/ROOT/assets/diagrams/camel-k-state-machine-integration-platform.drawio b/docs/modules/ROOT/assets/diagrams/camel-k-state-machine-integration-platform.drawio
new file mode 100644
index 0000000..623ef52
--- /dev/null
+++ b/docs/modules/ROOT/assets/diagrams/camel-k-state-machine-integration-platform.drawio
@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2020-07-12T13:44:26.155Z" agent="5.0 (X11)" etag="ggmsOCSB_B5J9U7Vbbn1" version="13.4.2"><diagram id="0Kwz7zGRW0z1vaULMuBK" name="Page-1">7Zxdd5s4EIZ/TS7jw4cl4DJxkm7PbvfkNNvT3d6pRrY5lZEX5CTeX78CxJckbGwj103sXMQMMIDmGTHzQnLlTpavHxK0WnyiISZXjhW+Xrl3V45jB5bDf2WWjbBY0C0s8yQKha02PEX/4XJDYV1HIU5bGzJKCYtWbeOUxjGespYNJQl9aW82o6R91BWaY8XwNEVEtX6NQrYorD6wavtvOJovyiPbllizROXGwpAuUEhfGib3/sqdJJSy4tvydYJJNnrluBT7PXSsrU4swTHrs8P1t/TLs33vAIeu/px+/P3Dtf3tWgTjGZG1 [...]
\ No newline at end of file
diff --git a/docs/modules/ROOT/assets/diagrams/camel-k-state-machine-integration.drawio b/docs/modules/ROOT/assets/diagrams/camel-k-state-machine-integration.drawio
new file mode 100644
index 0000000..17887cd
--- /dev/null
+++ b/docs/modules/ROOT/assets/diagrams/camel-k-state-machine-integration.drawio
@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2020-07-13T17:42:54.243Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/13.0.3 Chrome/80.0.3987.163 Electron/8.2.1 Safari/537.36" etag="nTuvFFSGTvKeo2VpzZrU" version="13.0.3" type="device"><diagram id="0Kwz7zGRW0z1vaULMuBK" name="Page-1">7V1bc5s4FP41foxH3OGxdpK22+1OtulMu4/EyLYmGCjITdxfvxIWNyFsjBG1G9xOC0IcydJ3rjqSJ9p88/o+dqP159CD/kQF3utEu52oqqKr6oT+Bd5uX2IbrGAVI49VKgoe0S+4LzRY4RZ5MKnUw2HoYxRVCxdhEMAFrpS5cRy+VKstQ7/aaOSuYK3g [...]
\ No newline at end of file
diff --git a/docs/modules/ROOT/assets/diagrams/camel-k-state-machine-integrationkit.drawio b/docs/modules/ROOT/assets/diagrams/camel-k-state-machine-integrationkit.drawio
new file mode 100644
index 0000000..b8a0f3e
--- /dev/null
+++ b/docs/modules/ROOT/assets/diagrams/camel-k-state-machine-integrationkit.drawio
@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2020-07-13T10:22:48.207Z" agent="5.0 (X11)" etag="RJWJeBRCgmQmYLY5A1VI" version="13.4.2" type="device"><diagram id="0Kwz7zGRW0z1vaULMuBK" name="Page-1">7Vxtk6I4EP41fhwrEED9ODozu/eyV1O7V7V7HzMSNTUIHsQZvV9/CYaXhCCgxHVrdKt2oAmdkDzdeTppGMDZevcpRpvVl8jHwcAG/m4AHwa2bU2Azf5wyV5IgAcPkmVMfCErBN/IfzgrKKRb4uNEKkijKKBkIwvnURjiOZVkKI6jd7nYIgrkWjdoiSuCb3MUVKXfiU9XB+nYBYX8MybLVVazBcSVNcoKC0GyQn70XhLBxwGcxVFED0fr3QwHvPeyfjnc91RzNW9YjEPa5obHv543f//x+cvz9u736ffZZr [...]
\ No newline at end of file
diff --git a/docs/modules/ROOT/assets/diagrams/operator-control-loop.drawio b/docs/modules/ROOT/assets/diagrams/operator-control-loop.drawio
new file mode 100644
index 0000000..bcf312d
--- /dev/null
+++ b/docs/modules/ROOT/assets/diagrams/operator-control-loop.drawio
@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2020-07-12T14:03:52.590Z" agent="5.0 (X11)" etag="SvOojC_3nr3ceSXHBW-h" version="13.4.2" type="device"><diagram id="uLhqvVcLPNciDg8s2euJ" name="Page-1">3VZNc9MwEP01OcL4Iy7JsbgOnYECQ5ihPar21hbI3oy8jm1+PZIt+QNPM3CABHKJ3ttdr/T0LGvlh3nzRrJDdocJiJXnJM3Kv1l5nrt1PPWnmdYwzpXfM6nkieFGYs+/g000bMUTKGeJhCiIH+ZkjEUBMc04JiXW87QnFPOuB5bCgtjHTCzZLzyhrGc3gTPyt8DTzHZ2HRPJmU02RJmxBOsJ5UcrP5SI1I/yJgSh1bO69HW7Z6LDxCQU9CsFr/JjdX3Xvg+qq83jbfjWiev7F+v+KUcmKrNgM1lqrQKQKE [...]
\ No newline at end of file
diff --git a/docs/modules/ROOT/assets/images/architecture/camel-k-operator-control-loop.png b/docs/modules/ROOT/assets/images/architecture/camel-k-operator-control-loop.png
new file mode 100644
index 0000000..422121d
Binary files /dev/null and b/docs/modules/ROOT/assets/images/architecture/camel-k-operator-control-loop.png differ
diff --git a/docs/modules/ROOT/assets/images/architecture/camel-k-operator.jpg b/docs/modules/ROOT/assets/images/architecture/camel-k-operator.jpg
new file mode 100644
index 0000000..6b6cd96
Binary files /dev/null and b/docs/modules/ROOT/assets/images/architecture/camel-k-operator.jpg differ
diff --git a/docs/modules/ROOT/assets/images/architecture/camel-k-runtimes.jpg b/docs/modules/ROOT/assets/images/architecture/camel-k-runtimes.jpg
new file mode 100644
index 0000000..0b028bb
Binary files /dev/null and b/docs/modules/ROOT/assets/images/architecture/camel-k-runtimes.jpg differ
diff --git a/docs/modules/ROOT/assets/images/architecture/camel-k-state-machine-basic.png b/docs/modules/ROOT/assets/images/architecture/camel-k-state-machine-basic.png
new file mode 100644
index 0000000..933fc6b
Binary files /dev/null and b/docs/modules/ROOT/assets/images/architecture/camel-k-state-machine-basic.png differ
diff --git a/docs/modules/ROOT/assets/images/architecture/camel-k-state-machine-build.png b/docs/modules/ROOT/assets/images/architecture/camel-k-state-machine-build.png
new file mode 100644
index 0000000..68108cb
Binary files /dev/null and b/docs/modules/ROOT/assets/images/architecture/camel-k-state-machine-build.png differ
diff --git a/docs/modules/ROOT/assets/images/architecture/camel-k-state-machine-integration-platform.png b/docs/modules/ROOT/assets/images/architecture/camel-k-state-machine-integration-platform.png
new file mode 100644
index 0000000..8e15e80
Binary files /dev/null and b/docs/modules/ROOT/assets/images/architecture/camel-k-state-machine-integration-platform.png differ
diff --git a/docs/modules/ROOT/assets/images/architecture/camel-k-state-machine-integration.png b/docs/modules/ROOT/assets/images/architecture/camel-k-state-machine-integration.png
new file mode 100644
index 0000000..b3fac14
Binary files /dev/null and b/docs/modules/ROOT/assets/images/architecture/camel-k-state-machine-integration.png differ
diff --git a/docs/modules/ROOT/assets/images/architecture/camel-k-state-machine-integrationkit.png b/docs/modules/ROOT/assets/images/architecture/camel-k-state-machine-integrationkit.png
new file mode 100644
index 0000000..48b1b19
Binary files /dev/null and b/docs/modules/ROOT/assets/images/architecture/camel-k-state-machine-integrationkit.png differ
diff --git a/docs/modules/ROOT/assets/images/architecture/camel-k-traits.jpg b/docs/modules/ROOT/assets/images/architecture/camel-k-traits.jpg
new file mode 100644
index 0000000..ae467ed
Binary files /dev/null and b/docs/modules/ROOT/assets/images/architecture/camel-k-traits.jpg differ
diff --git a/docs/modules/ROOT/assets/images/architecture/camel-k.jpg b/docs/modules/ROOT/assets/images/architecture/camel-k.jpg
new file mode 100644
index 0000000..b3fa15d
Binary files /dev/null and b/docs/modules/ROOT/assets/images/architecture/camel-k.jpg differ
diff --git a/docs/modules/ROOT/assets/images/architecture/operator-control-loop.png b/docs/modules/ROOT/assets/images/architecture/operator-control-loop.png
new file mode 100644
index 0000000..13b1255
Binary files /dev/null and b/docs/modules/ROOT/assets/images/architecture/operator-control-loop.png differ
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 9de8c29..47563a4 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -18,6 +18,15 @@
** xref:configuration/logging.adoc[Logging]
** xref:configuration/dependencies.adoc[Dependencies]
** xref:configuration/configmap-secret.adoc[ConfigMap/Secret]
+* xref:architecture/architecture.adoc[Architecture]
+** xref:architecture/operator.adoc[Operator]
+*** xref:architecture/cr/integration-platform.adoc[IntegrationPlatform]
+*** xref:architecture/cr/integration.adoc[Integration]
+*** xref:architecture/cr/integration-kit.adoc[IntegrationKit]
+*** xref:architecture/cr/build.adoc[Build]
+*** xref:architecture/cr/camel-catalog.adoc[CamelCatalog]
+** xref:architecture/runtime.adoc[Runtime]
+** xref:architecture/traits.adoc[Traits]
* Observability
** xref:observability/monitoring.adoc[Monitoring]
* xref:traits:traits.adoc[Traits]
diff --git a/docs/modules/ROOT/pages/architecture/architecture.adoc b/docs/modules/ROOT/pages/architecture/architecture.adoc
new file mode 100644
index 0000000..b98c107
--- /dev/null
+++ b/docs/modules/ROOT/pages/architecture/architecture.adoc
@@ -0,0 +1,11 @@
+[[architecture]]
+= Architecture
+
+
+image::architecture/camel-k.jpg[Overview]
+
+The *Camel K* platform is based on three concepts:
+
+1. The xref:architecture/operator.adoc[Operator] which is the intelligence that coordinates all the moving parts.
+2. The xref:architecture/runtime.adoc[Runtime] which provides the functionnality to run the integration.
+3. The xref:architecture/traits.adoc[Traits] through wich the behavior of the operator and the runtime can be customized.
diff --git a/docs/modules/ROOT/pages/architecture/cr/build.adoc b/docs/modules/ROOT/pages/architecture/cr/build.adoc
new file mode 100644
index 0000000..62a71ff
--- /dev/null
+++ b/docs/modules/ROOT/pages/architecture/cr/build.adoc
@@ -0,0 +1,27 @@
+[[build]]
+= Build
+
+A *Build* resources, describes the process of assembling a container image that copes with the requirement of an xref:architecture/cr/integration.adoc[Integration] or xref:architecture/cr/integration-kit.adoc[IntegrationKit].
+
+[source,go]
+----
+type Build struct {
+ Spec BuildSpec // <1>
+ Status BuildStatus // <2>
+}
+
+type BuildSpec struct {
+ Tasks []Task // <3>
+}
+----
+<1> The desired state
+<2> The status of the object at current time
+<3> The build tasks
+
+[NOTE]
+====
+the full go definition can be found https://github.com/apache/camel-k/blob/master/pkg/apis/camel/v1/build_types.go[here]
+====
+
+image::architecture/camel-k-state-machine-build.png[life cycle]
+
diff --git a/docs/modules/ROOT/pages/architecture/cr/camel-catalog.adoc b/docs/modules/ROOT/pages/architecture/cr/camel-catalog.adoc
new file mode 100644
index 0000000..37a373f
--- /dev/null
+++ b/docs/modules/ROOT/pages/architecture/cr/camel-catalog.adoc
@@ -0,0 +1,9 @@
+[[camel-catalog]]
+= CamelCatalog
+
+The*CamelCatalog* is a static side resources that provides metadata related to the what it is included in the xref:architecture/runtime.adoc[Runtime] in term of Camel components, languages, dataformats and what capabilities are prvided.
+
+[NOTE]
+====
+the full go definition can be found https://github.com/apache/camel-k/blob/master/pkg/apis/camel/v1/camelcatalog_types.go[here]
+====
\ No newline at end of file
diff --git a/docs/modules/ROOT/pages/architecture/cr/integration-kit.adoc b/docs/modules/ROOT/pages/architecture/cr/integration-kit.adoc
new file mode 100644
index 0000000..0a7a7ab
--- /dev/null
+++ b/docs/modules/ROOT/pages/architecture/cr/integration-kit.adoc
@@ -0,0 +1,34 @@
+[[integration-kit]]
+= IntegrationKit
+
+The *IntegrationKit* is a fundamental side resource which describe a container image created by the camel-k operator as well as the configurations that need to be applied to every integration that is executed on top of it. An *IntegrationKit* does not include any source code or resource file defined by the **Integration** from wcich it has been generated.
+
+[source,go]
+----
+type IntegrationKit struct {
+ Spec IntegrationKitSpec // <1>
+ Status IntegrationKitStatus // <2>
+}
+
+type IntegrationKitSpec struct {
+ Image string // <3>
+ Dependencies []string // <4>
+ Repositories []string // <4>
+ Profile TraitProfile // <5>
+ Traits map[string]TraitSpec // <5>
+ Configuration []ConfigurationSpec // <6>
+}
+----
+<1> The desired state
+<2> The status of the object at current time
+<3> The container image
+<4> The dependencies required by the kit and related repositories (if needed)
+<5> The traits configuration
+<6> The integration configuration (properties, secrets, configmaps)
+
+[NOTE]
+====
+the full go definition can be found https://github.com/apache/camel-k/blob/master/pkg/apis/camel/v1/integrationkit_types.go[here]
+====
+
+image::architecture/camel-k-state-machine-integrationkit.png[life cycle]
diff --git a/docs/modules/ROOT/pages/architecture/cr/integration-platform.adoc b/docs/modules/ROOT/pages/architecture/cr/integration-platform.adoc
new file mode 100644
index 0000000..de93928
--- /dev/null
+++ b/docs/modules/ROOT/pages/architecture/cr/integration-platform.adoc
@@ -0,0 +1,35 @@
+[[integration-platform]]
+= IntegrationPlatform
+
+The *IntegrationPlatform* CR is the resource used to control the behavior of the Camel K Operator.
+
+[source,go]
+----
+type IntegrationPlatform struct {
+ Spec IntegrationPlatformSpec // <1>
+ Status IntegrationPlatformStatus // <2>
+}
+
+type IntegrationPlatformSpec struct {
+ Cluster IntegrationPlatformCluster // <3>
+ Profile TraitProfile // <4>
+ Build IntegrationPlatformBuildSpec // <5>
+ Traits map[string]TraitSpec // <6>
+ Configuration []ConfigurationSpec // <6>
+}
+----
+<1> The desired state
+<2> The status of the object at current time
+<3> The type of the Kubernetes Cluster (Kubernetes or OpenShifr)
+<4> Configures the traits that have to be applied by default (Kubernetes, OpneShift, Knative)
+<5> Configuration options of the image build process such as the type of the builder (buildah, kanico, spectrum) and the maven repositories that have to be configured in order retrieve the artifacts needed by the integrations.
+<6> The traits and configuration options that have to be propagated to each integration.
+
+[NOTE]
+====
+the full go definition can be found https://github.com/apache/camel-k/blob/master/pkg/apis/camel/v1/integrationplatform_types.go[here]
+====
+
+Upon start-up, the operator checks if the *IntegrationPlatform* is ready and if not, it executes all the steps required to be ready to operate:
+
+image::architecture/camel-k-state-machine-integration-platform.png[life cycle]
diff --git a/docs/modules/ROOT/pages/architecture/cr/integration.adoc b/docs/modules/ROOT/pages/architecture/cr/integration.adoc
new file mode 100644
index 0000000..cfa69ab
--- /dev/null
+++ b/docs/modules/ROOT/pages/architecture/cr/integration.adoc
@@ -0,0 +1,36 @@
+[[integration]]
+= Integration
+
+An *Integration* describe the application by listing sources, resources, dependencies and by providing configuration options.
+
+[source,go]
+----
+type Integration struct {
+ Spec IntegrationSpec // <1>
+ Status IntegrationStatus // <2>
+}
+
+type IntegrationSpec struct {
+ Sources []SourceSpec // <3>
+ Flows []Flow // <3>
+ Resources []ResourceSpec // <3>
+ Dependencies []string // <4>
+ Repositories []string // <4>
+ Profile TraitProfile // <5>
+ Traits map[string]TraitSpec // <5>
+ Configuration []ConfigurationSpec // <6>
+}
+----
+<1> The desired state
+<2> The status of the object at current time
+<3> Integration sources and resource files
+<4> The dependencies required by the integration and related repositories (if needed)
+<5> The traits configuration
+<6> The integration configuration (properties, secrets, configmaps)
+
+[NOTE]
+====
+the full go definition can be found https://github.com/apache/camel-k/blob/master/pkg/apis/camel/v1/integration_types.go[here]
+====
+
+image::architecture/camel-k-state-machine-integration.png[life cycle]
diff --git a/docs/modules/ROOT/pages/architecture/operator.adoc b/docs/modules/ROOT/pages/architecture/operator.adoc
new file mode 100644
index 0000000..c4ebc5f
--- /dev/null
+++ b/docs/modules/ROOT/pages/architecture/operator.adoc
@@ -0,0 +1,49 @@
+[[operator]]
+= Operator
+
+image::architecture/camel-k-operator.jpg[overview]
+
+Per the Kubernetes glossary, a controller is an application that implements a control-loop that **observes** the shared state of the cluster through the API server, **evaluates** the changes needed to move the current state toward the desired state and finally applyes the changes to **reconcile** the resources to the desired state.
+
+image::architecture/operator-control-loop.png[control-loop]
+
+This pattern is the foundation of every https://kubernetes.io/docs/concepts/architecture/controller/[Controllers] whipped by default by Kubernetes but can also be used by https://kubernetes.io/docs/concepts/extend-kubernetes/operator[Operators] that are controllers that encode domain specific knowledge and extends the Kubernetes API to create, configure and manage instances of complex applications on behalf of Kubernetes users.
+
+With the Camel K Operator we have moved this pattern to the next level as it goes beyon the tasks to install and maintain applications but it materializes them according to the integration logic expressed through the **Camel DSL**.
+
+The Camel K Operator defines a number of new Kubernetes API through the https://kubernetes.io/docs/concepts/extend-kubernetes/#user-defined-types[**Custom Resource** (CR)] extension mechanism:
+
+* xref:architecture/cr/integration-platform.adoc[IntegrationPlatform]
+* xref:architecture/cr/integration.adoc[Integration]
+* xref:architecture/cr/integration-kit.adoc[IntegrationKit]
+* xref:architecture/cr/build.adoc[Build]
+* xref:architecture/cr/camel-catalog.adoc[CamelCatalog]
+
+All the api conform to the Kubernetes https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md[api conventions].
+
+To manage the interaction with them, a simple control loop was not enough and we ended up with a sort of “Hierarchical Operator Pattern” where the reconcile phase may trigger other controllers and supervises them.
+
+image::architecture/camel-k-operator-control-loop.png[control-loop]
+
+== State Machine
+
+With the exception of the `CamelCatalog`, each CR has a dedicated state machine in charge to orchestrate the transition to the phases each CR need to go through to bring integrations to the desired state.
+
+image::architecture/camel-k-state-machine-basic.png[State Machine]
+
+Each state of the CR is handled by a dedicated handler, named `Action`, defined as follow:
+
+[code,go]
+----
+type Action interface {
+ CanHandle(cr *v1.CR) bool // <1>
+ Handle(ctx context.Context, cr *v1.CR) (*v1.CR, error) // <2>
+}
+----
+<1> Determine if the action can handle the CR as example by looking at the phase of the CR which is store as part of the status sub resource.
+<2> Implement the action and return a non `nil` instance to signal to the controller that the CR need to be updated with the new one, instead if the method returns a `nil` instance, then nothing will happen and unless the CR changes outside the control of the operator, the same action will be invoked on the next interation. This is useful when a CR need to delegate some work to a different controller so the CR won't be moved to the next stage till the sub operation has completed.
+
+[NOTE]
+====
+Since the go language does not yet supoprt generics, there is an `Action` definition per CR, The full list of definitions can be found in the https://github.com/apache/camel-k/tree/master/pkg/controller[controller package]
+====
diff --git a/docs/modules/ROOT/pages/architecture/runtime.adoc b/docs/modules/ROOT/pages/architecture/runtime.adoc
new file mode 100644
index 0000000..fd9939b
--- /dev/null
+++ b/docs/modules/ROOT/pages/architecture/runtime.adoc
@@ -0,0 +1,6 @@
+[[runtime]]
+= Runtime
+
+image::architecture/camel-k-runtimes.jpg[runtimes]
+
+TBD
\ No newline at end of file
diff --git a/docs/modules/ROOT/pages/architecture/traits.adoc b/docs/modules/ROOT/pages/architecture/traits.adoc
new file mode 100644
index 0000000..d264237
--- /dev/null
+++ b/docs/modules/ROOT/pages/architecture/traits.adoc
@@ -0,0 +1,6 @@
+[[traits]]
+= Traits
+
+image::architecture/camel-k-traits.jpg[traits]
+
+TBD