This is an automated email from the ASF dual-hosted git repository.
squakez pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-k.git
The following commit(s) were added to refs/heads/main by this push:
new b53c48ab1 chore(proposals): v3 CLI redesign
b53c48ab1 is described below
commit b53c48ab18031c0ed04556b1f4d25786dc6b791a
Author: Pasquale Congiusti <[email protected]>
AuthorDate: Thu Nov 19 08:46:25 2026 +0100
chore(proposals): v3 CLI redesign
Ref #6938
Ref #6939
---
proposals/v3-architecture.adoc | 72 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 72 insertions(+)
diff --git a/proposals/v3-architecture.adoc b/proposals/v3-architecture.adoc
index 59ade89ff..839fec3eb 100644
--- a/proposals/v3-architecture.adoc
+++ b/proposals/v3-architecture.adoc
@@ -24,6 +24,8 @@ A new redesign that can introduce certain breaking
compatibility change would be
- Clean the code and make it easier to maintain in the long term.
- Harden security
+NOTE: This redesign affects both the Camel K **operator** and the `kamel`
**CLI**. The changes to the CLI (new command set and separation from the
operator code) are described in the <<CLI>> section.
+
== Goals
The goal of this document is to illustrate the new design at a high level
view. When the new design is approved, it will serve as a reference for all
different developments required to complete a first version 3 of the project.
@@ -71,6 +73,76 @@ The Camel K operator `Pod` will be also much simpler as it
won't require it to b
* Kit reusability
* Managed custom pipeline (external CICD still available)
+== CLI
+
+The `kamel` CLI was born when the project's main purpose was to ease the first
steps of a user with an integration platform: a single `kamel run` command was
able to take care of everything, from the source file to the running
application. The project is now moving towards a more enterprise oriented
approach, where build and deployment are separate concerns (possibly owned by
different actors and tools). The CLI scope must follow the same direction.
+
+=== Command set
+
+The `run` command today concentrates a large amount of logic (modeline
parsing, local source/dependency resolution, traits and properties handling,
waiting and logging, ...) and mixes build and execution in one single step. The
proposal is to remove it entirely, already in the first v3 release, and expose
the lifecycle of an `Integration` through three explicit commands, each one
mapped to a task performed by the operator:
+
+[cols="1,3,3"]
+|===
+|Command |Responsibility |Operator counterpart
+
+|`kamel build`
+|Create (or update) the `Integration`/`Pipe` and trigger an
`IntegrationBuild`. It can optionally wait for the build to complete and stream
its logs. It never starts the application.
+|Build and containerization phase, up to `Build Complete`.
+
+|`kamel deploy`
+|Request the deployment of an `Integration`/`Pipe` which has a successful
build. It fails if the build is not complete. An explicit build (ie, a previous
one, in a rollback scenario) may be selected.
+|Deployment phase (`Deployment` generation and rollout).
+
+|`kamel undeploy`
+|Stop the running workload, keeping the `Integration`/`Pipe` and its builds
available for a later `deploy`. Removal of the resources remains a plain
`kubectl delete`.
+|Scale-down/removal of the runtime resources only.
+|===
+
+The behaviour is: **an `Integration` is never run unless the user explicitly
asks for it, and only once it has been built**. This is the opposite of the
current default (build and run), where skipping the run requires
`--dont-run-after-build`.
+
+NOTE: `deploy` and `undeploy` already exist in v2 (the former being a thin
wrapper that moves an `Integration` from `Build Complete` to `Deploying`). The
work is mostly to make them first class, add `build` and drop `run`. Other
commands (`bind`, `promote`, `log`, `debug`, ...) are not part of this proposal
and will be evaluated separately, based on how much of their logic can be
reused unchanged.
+
+=== Planning items
+
+- Extract from `run` the logic that is still relevant and move it to `build`.
+- Align `deploy` and `undeploy` with the new `IntegrationBuild` model
(including the selection of a specific build).
+- Update docs, examples and e2e tests to use the new commands (the e2e suites
rely heavily on `kamel run`, so this is a significant part of the effort).
+- Document the removal of `run` in the upgrade notes, with the equivalent
`build` + `deploy` sequence.
+
+=== Open points
+
+- Which `run` flags survive and on which command (ie, trait/property/profile
options belong to `build`, while scaling or replicas options may belong to
`deploy`).
+- Whether `modeline` support (source file comments with CLI options) is kept,
and for which command.
+- Whether a shortcut such as `kamel build --deploy` is worth keeping, to
preserve a one-liner developer experience without reintroducing `run`.
+
+=== Decoupling CLI and operator
+
+At the moment the CLI and the operator live in the same Go module and the same
command tree (`pkg/cmd`). The `kamel` binary embeds the operator (`kamel
operator`) and the builder (`kamel builder`), and both share the same business
logic and utility packages. As a consequence, each artifact carries
dependencies it does not need: the CLI pulls in controller, builder and trait
related code (and their transitive dependencies), whereas the operator pulls in
everything which is only relevant t [...]
+
+This has several drawbacks:
+
+- larger binaries and container images, with a bigger surface exposed to CVEs
which are not exploitable by the given artifact;
+- coupled dependency upgrades: a fix required by the operator forces a CLI
release and the other way around;
+- blurred code boundaries, making it harder to reason about which code runs
with the cluster privileges of the operator and which one with the privileges
of a user;
+- the two artifacts can't evolve (or be released) at their own pace.
+
+The proposal is to separate them into two distinct artifacts:
+
+- **`camel-k-operator`**: the operator (including the controllers, traits and
the pieces required to drive the build `Job`). It would have no knowledge of
CLI code.
+- **`kamel`**: a thin client which does only what is needed to create/patch
the custom resources (`Integration`, `Pipe`, `Kamelet`, ...) and to observe
them. It would depend on the `apis` and `client` packages only, and not on
controllers, traits or builder logic.
+
+A possible approach, to be validated by a spike before committing to it:
+
+1. **Dependency analysis**: map the packages imported by `cmd/kamel` and by
the operator entrypoint and identify the shared ones. Everything shared should
be either legitimately common (`pkg/apis`, `pkg/client`, a few `pkg/util`) or
moved/duplicated.
+2. **Break the cross dependencies**: for the code used on both sides (ie,
`pkg/trait`, which the CLI currently imports from `kamelets_support.go`),
expose it from a small and stable package, or leave the validation to the
operator (reporting issues in the CR status).
+3. **Split the entrypoints**: create a dedicated operator entrypoint and keep
`cmd/kamel`, removing the `operator` and `builder` subcommands from the CLI.
The `builder` role becomes the opinionated pipeline of the build `Pod`
described above, so it won't need to be a `kamel` subcommand anymore.
+4. **Evaluate the module layout**: either keep a single Go module with two
separate entrypoints and dependency graphs (cheaper, enforced by lint/CI checks
on allowed imports), or publish the API types in a separate module so they can
be consumed by third parties and by the CLI without importing the whole
operator. The second option brings more isolation at the price of a heavier
release process.
+5. **Build and release**: two separate artifacts, with separate images
(operator, build pipeline) and binaries (CLI), and the related changes in
`Makefile`, CI workflows, Helm chart/Kustomize and the documentation.
+
+The expected benefits are smaller artifacts, a reduced attack surface and a
clearer ownership of what runs in-cluster versus on the user machine. The main
risks are the effort of untangling the shared code and the compatibility of the
existing installation methods (the operator image is currently also the image
where `kamel` is available), which must be listed in the upgrade notes.
+
+This work is independent from the command set changes above, and could start
earlier, since moving the code first makes the later removal of `run` simpler.
+
== Compatibility
The v3 operator will be still compatible with previous v2 Integrations custom
resource. However we should expect that, as soon as a new v3 operator detects
an Integration will rebuild it with the new building system. In this sense we
should expect to break the compatibility: a v3 operator will rebuild any
existing v2 Integration the first time it detects it (unless it runs as Self
Managed Build Integration).