From 6fd445fe2832d5d4de30400e4fbf8296f58a6b44 Mon Sep 17 00:00:00 2001 From: Pasquale Congiusti Date: Thu, 14 Sep 2023 16:57:20 +0200 Subject: [PATCH] chore(doc): describe build strategies Closes #3336 --- .github/workflows/builder.yml | 2 +- docs/modules/ROOT/nav-end.adoc | 4 +-- docs/modules/ROOT/nav.adoc | 9 +++-- .../pages/architecture/incremental-image.adoc | 9 +++++ .../installation/advanced/build-config.adoc | 33 +++++++++++++++++++ .../camel/v1/integrationplatform_types.go | 4 +-- 6 files changed, 51 insertions(+), 10 deletions(-) create mode 100644 docs/modules/ROOT/pages/architecture/incremental-image.adoc create mode 100644 docs/modules/ROOT/pages/installation/advanced/build-config.adoc diff --git a/.github/workflows/builder.yml b/.github/workflows/builder.yml index 5f3f40f0fe..9938707fd5 100644 --- a/.github/workflows/builder.yml +++ b/.github/workflows/builder.yml @@ -74,7 +74,7 @@ jobs: strategy: fail-fast: false matrix: - publisher: ["Spectrum", Jib"] + publisher: ["Spectrum", "Jib"] steps: - name: Checkout code diff --git a/docs/modules/ROOT/nav-end.adoc b/docs/modules/ROOT/nav-end.adoc index eea1b4cf0e..94c49c055d 100644 --- a/docs/modules/ROOT/nav-end.adoc +++ b/docs/modules/ROOT/nav-end.adoc @@ -58,8 +58,7 @@ ** xref:traits:toleration.adoc[Toleration] ** xref:traits:tracing.adoc[Tracing] // End of autogenerated code - DO NOT EDIT! (trait-nav) -* Pipelines -** xref:pipeline/pipeline.adoc[Basic] +* xref:pipeline/pipeline.adoc[Pipelines] ** xref:pipeline/tekton.adoc[Tekton] * Scaling ** xref:scaling/integration.adoc[Integrations] @@ -84,6 +83,7 @@ *** xref:architecture/cr/camel-catalog.adoc[CamelCatalog] ** xref:architecture/runtime.adoc[Runtime] ** xref:architecture/traits.adoc[Traits] +** xref:architecture/incremental-image.adoc[Incremental Image] * API ** xref:apis/camel-k.adoc[Camel K API] ** xref:apis/kamelets.adoc[Kamelets API] diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 18de9adab2..d665b66090 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,7 +1,10 @@ * xref:installation/installation.adoc[Installation] ** xref:installation/advanced/maven.adoc[Configuring Maven] ** xref:installation/registry/registry.adoc[Configuring Registry] +** xref:contributing/upgrade.adoc[Upgrade] +** xref:contributing/uninstalling.adoc[Uninstalling] ** xref:installation/advanced/advanced.adoc[Advanced] +*** xref:installation/advanced/build-config.adoc[Build tuning] *** xref:installation/advanced/kustomize.adoc[Install Using Kustomize] *** xref:installation/advanced/network.adoc[Network architecture] *** xref:installation/advanced/resources.adoc[Resource management] @@ -9,10 +12,7 @@ *** xref:installation/advanced/http-proxy.adoc[HTTP Proxy] *** xref:installation/advanced/multi-architecture.adoc[Multi Architecture] *** xref:installation/advanced/offline.adoc[Offline] -** xref:contributing/upgrade.adoc[Upgrade] -** xref:contributing/uninstalling.adoc[Uninstalling] -* Command Line Interface -** xref:cli/cli.adoc[Kamel CLI] +* xref:cli/cli.adoc[Command Line Interface] ** xref:cli/file-based-config.adoc[File-based Config] ** xref:cli/modeline.adoc[Modeline] * xref:running/running.adoc[Run an Integration] @@ -23,4 +23,3 @@ ** xref:running/run-from-github.adoc[Run from GitHub] ** xref:running/promoting.adoc[Promote an Integration] ** xref:running/knative-sink.adoc[Knative Sinks] - diff --git a/docs/modules/ROOT/pages/architecture/incremental-image.adoc b/docs/modules/ROOT/pages/architecture/incremental-image.adoc new file mode 100644 index 0000000000..6e84545468 --- /dev/null +++ b/docs/modules/ROOT/pages/architecture/incremental-image.adoc @@ -0,0 +1,9 @@ += Incremental image + +One of the goal of Camel K is to provide a Cloud Native experience for Camel developers. It means basically to have a quick build of the application based on the Camel route you provide and an execution that should be as fast as possible. + +In order to reduce the time to build and execute an application we adopt various strategies. If an application has a container with all the dependencies required, then, we just reuse such container, having an immediate start of your application. And then we have the concept of **incremental image**. + +If you're familiar with Camel K architecture, you know that an Integration uses an IntegrationKit, which is, a reusable resource containing all the dependencies and capabilities required to run a certain "class" of Camel applications. The IntegrationKit is bound to a container image stored in a registry. + +When the IntegrationKit is created, it uses as a base image a JDK based container and add certain applications layers on top of it. However, instead of using always the same root base image, we check if an IntegrationKit with a subset of dependencies already exists, sparing quite some time on the generation of the new container image. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/installation/advanced/build-config.adoc b/docs/modules/ROOT/pages/installation/advanced/build-config.adoc new file mode 100644 index 0000000000..0a16301fae --- /dev/null +++ b/docs/modules/ROOT/pages/installation/advanced/build-config.adoc @@ -0,0 +1,33 @@ += Build configuration + +The default installation provides some default configuration in order to perform a build and the publishing of the application in the container registry. In order to provide a more customized user experience, we provide two build configuration which you can use: **Build Strategy** and **Publish Strategy**. + +[[build-strategy]] +== Build strategy + +The build strategy is used to control the behavior of the application build from the Integration source. This is equivalent to the Maven process building a Java application. You can configure the operator to run this operation either as a routine (or thread) in the same operator application, or to spin off a Kubernetes Pod and execute the build in a new separate application. + +The `routine` strategy (default) is in general faster as it does not require Kubernetes to create any new resource, however it consumes a high amount of memory and may slow down any other process run in the same Camel K operator Pod. In general is a good strategy, but you need to consider the trade off if you have multiple concurrent builds at the same time. + +The `pod` strategy is **always** used when running a Quarkus native build (as it requires certain tools not available in the operator container). You can also use this strategy when you want to have a higher level of concurrency. Although a bit slower (it requires Kubernetes to spin off a new Pod), this strategy will guarantee the execution of each parallel build in a timely manner. + +NOTE: the `pod` strategy was also required when using the now deprecated Buildah or Kaniko publishing strategy. + +Beside the build strategy, there are other configuration you can fine tune for each single build (via builder trait) or in the `.spec.build.buildConfiguration` of the IntegrationPlatform if you want to apply such configuration to all your builds. See the Builder trait page for more information. + +The most relevant are the `resource` and `limit` parameters which can be used to control how much resources to give to builder Pods. Then you can configure the `orderStrategy`, setting a `sequential` (single build), `fifo` (parallel build started in FIFO order) or `dependencies` (parallel build holding those applications which may depends on other because of ** xref:architecture/incremental-image.adoc[incremental image]). Finally you can include any `mavenProfile` to the build in order to influence the behavior of the build (ie, adding any plugin or configuration you can use when xref:pipeline/pipeline.adoc[running a pipeline]). + +[[publish-strategy]] +== Publish strategy + +The publish strategy is used to control the behavior of the creation of the container after a build. Basically it create a container image from the application built in the previous step and store as a container in the xref:installation/registry/registry.adoc[registry] configured. + +The operator has 3 different strategy which you can adopt: Spectrum (default in plain Kubernetes profile), S2I (default in Openshift profile) and Jib. + +Each configuration provides a set of technologies which are supporting the creation of a container image and the storage into a container registry. https://github.com/container-tools/spectrum[Spectrum] is a lightweight technology based on https://github.com/google/go-containerregistry[go-containerregistry]. It creates a raw image on top of a base image and push very quickly to a registry. + +https://access.redhat.com/documentation/es-es/openshift_container_platform/4.2/html/builds/understanding-image-builds#build-strategy-s2i_understanding-image-builds[S2I] is an efficient technology integrated in Openshift, reason why it is enabled by default in such a profile. + +https://cloud.google.com/java/getting-started/jib[Jib] is a technology that transform a Java project into a container image and is configurable directly in Maven. + +NOTE: you may define your own publishing technology by using xref:pipeline/pipeline.adoc[pipelines]. \ No newline at end of file diff --git a/pkg/apis/camel/v1/integrationplatform_types.go b/pkg/apis/camel/v1/integrationplatform_types.go index dd4b3b72d4..4b5f8a01bf 100644 --- a/pkg/apis/camel/v1/integrationplatform_types.go +++ b/pkg/apis/camel/v1/integrationplatform_types.go @@ -154,11 +154,11 @@ type IntegrationPlatformBuildPublishStrategy string const ( // IntegrationPlatformBuildPublishStrategyBuildah uses Buildah project (https://buildah.io/) // in order to push the incremental images to the image repository. It can be used with `pod` BuildStrategy. - // Deprecated: use Spectrum, Jib or S2I instead + // Deprecated: use Spectrum, Jib or S2I instead. IntegrationPlatformBuildPublishStrategyBuildah IntegrationPlatformBuildPublishStrategy = "Buildah" // IntegrationPlatformBuildPublishStrategyKaniko uses Kaniko project (https://github.com/GoogleContainerTools/kaniko) // in order to push the incremental images to the image repository. It can be used with `pod` BuildStrategy. - // Deprecated: use Spectrum, Jib or S2I instead + // Deprecated: use Spectrum, Jib or S2I instead. IntegrationPlatformBuildPublishStrategyKaniko IntegrationPlatformBuildPublishStrategy = "Kaniko" // IntegrationPlatformBuildPublishStrategyS2I uses the Source to Images (S2I) feature // (https://docs.openshift.com/container-platform/4.9/openshift_images/create-images.html#images-create-s2i_create-images)