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
The following commit(s) were added to refs/heads/main by this push:
new 33156b95e chore(cmd): revert debug deprecation
33156b95e is described below
commit 33156b95e5d866342284355e684943d5d7259568
Author: Pasquale Congiusti <[email protected]>
AuthorDate: Sat Nov 29 09:55:14 2025 +0100
chore(cmd): revert debug deprecation
The `debug` command is still needed as it acts as a proxy toward cluster,
making it easy to debug. Added some documentation to explain how to do that.
---
.../ROOT/images/debugging/camel-k-debugger-1.png | Bin 0 -> 74276 bytes
.../ROOT/images/debugging/camel-k-debugger-2.png | Bin 0 -> 181637 bytes
.../ROOT/images/debugging/remote-debugger.png | Bin 70273 -> 0 bytes
.../ROOT/pages/troubleshooting/debugging.adoc | 85 +++++++++++++--------
pkg/cmd/debug.go | 13 ++--
5 files changed, 60 insertions(+), 38 deletions(-)
diff --git a/docs/modules/ROOT/images/debugging/camel-k-debugger-1.png
b/docs/modules/ROOT/images/debugging/camel-k-debugger-1.png
new file mode 100644
index 000000000..69d58bb63
Binary files /dev/null and
b/docs/modules/ROOT/images/debugging/camel-k-debugger-1.png differ
diff --git a/docs/modules/ROOT/images/debugging/camel-k-debugger-2.png
b/docs/modules/ROOT/images/debugging/camel-k-debugger-2.png
new file mode 100644
index 000000000..b8cc175dd
Binary files /dev/null and
b/docs/modules/ROOT/images/debugging/camel-k-debugger-2.png differ
diff --git a/docs/modules/ROOT/images/debugging/remote-debugger.png
b/docs/modules/ROOT/images/debugging/remote-debugger.png
deleted file mode 100644
index 3accca3e1..000000000
Binary files a/docs/modules/ROOT/images/debugging/remote-debugger.png and
/dev/null differ
diff --git a/docs/modules/ROOT/pages/troubleshooting/debugging.adoc
b/docs/modules/ROOT/pages/troubleshooting/debugging.adoc
index 8eb59e57b..33a5f6e26 100644
--- a/docs/modules/ROOT/pages/troubleshooting/debugging.adoc
+++ b/docs/modules/ROOT/pages/troubleshooting/debugging.adoc
@@ -1,53 +1,76 @@
[[debugging]]
= Debugging Camel K Integrations
-Sometimes an Integration can fail or behave unexpectedly for unknown reasons,
and a developer needs to investigate the cause of such behavior. Attaching a
Java debugger to an integration is a common way to start the investigation.
+Sometimes an Integration can fail or behave unexpectedly for unknown reasons,
and a developer needs to investigate the cause of such behavior. Attaching a
Java debugger to an Integration is a common way to start the investigation.
-Even if the Integration Pods run on a Kubernetes cluster, it's very easy to
attach a Java debugger to the remote Integration container using the CLI.
+Even if the Integration Pods runs on a Kubernetes cluster, it's very easy to
attach a Java debugger to the remote Integration container using the CLI.
-== Debugging with VS Code
+Camel K offers some easy approach and some tool which can turn very useful
when you want to start a remote debugger and acts as you're debugging on a
local machine.
-If you're a VS Code user, you can watch this
link:https://www.youtube.com/watch?v=pFj21YvzZm0&t=53s[video].
+Although technically it is feasible to debug any Camel DSL, in practice, it
can result complicated to add a breakpoint on any non Java DSL. For this
reason, the guidelines provided in this section are specific to Java DSL.
-== Debugging with IntelliJ IDEA
+== Debug a Camel application
-Suppose you've started an Integration using the following command:
+The very first thing to do is to run an application. It's important you have
the source code at hands, as later you will need such a source code for your
IDE as well.
-[source,console]
-----
-$ kamel run examples/Sample.java
-----
+```bash
+$ kamel run src/main/Test.java
+```
-An Integration named `sample` should be running in the cluster. You can use
the `kamel debug` command to put it in _debug_ mode:
+When the application has started. You can use the `kamel debug` command to put
it in _debug_ mode:
-[source,console]
-----
-$ kamel debug sample
-----
+NOTE: make sure you don't debug a production workflow. The debug is stopping
the previous running Pods and restart a new Pod with the specific profile
activated.
-A possible output that you may find is the following:
+```bash
+$ kamel debug test
+```
-[source,console]
-----
-$ kamel debug sample
-Enabling debug mode on integration "sample"...
-[1] Monitoring pod sample-8455c8b985-5cxvc
-[1] exec java
-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005 -cp
./resources:[..omitted..] io.quarkus.runner.GeneratedMain
-[1] Listening for transport dt_socket at address: 5005
+The goal of the **debug** command is to equip the running application with the
JVM configuration required to debug a Java application. Additionally it creates
a proxy toward the port defined (default, `5005`) so that you can execute the
debugger on `localhost` and bridge transparently to the remote cluster.
+
+```bash
+$ kamel debug test
+Enabling debug mode on integration "test"...
+2025-11-25T15:42:02+01:00 DEBUG camel-k First attempt to bootstrap Port
Forward with LabelSelector:
camel.apache.org/debug=true,camel.apache.org/integration=test
+...
Forwarding from 127.0.0.1:5005 -> 5005
Forwarding from [::1]:5005 -> 5005
-----
+[1] Monitoring pod test-64c8ddc7f7-w4njw
+[1] Listening for transport dt_socket at address: 5005
+```
+
+The application is suspendend (which is the default) until a debugger is
attached. From this point onward you can attach your debugger and continue the
debugging on your preferred IDE.
+
+NOTE: you can use any other port and JVM options, see `kamel debug --help`.
+
+== Debugging Camel in VSCode
+
+We are providing some guidelines to illustrate how you can **debug Camel on
VSCode**. Other IDEs may have a different way of achieving the goal, so you may
follow their guidelines as for any other Java application.
-As you can see in the logs, the CLI has configured the integration in debug
mode (see option
`-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005`) and
started forwarding the local port 5005 on the workstation machine (local port
can be changed using the `--port` option) to the container port 5005, where the
JVM is waiting for a debugger.
+You may have noticed that we have started the application in
`src/main/Test.Java`. This is something that is expected by VSCode, as any
regular Java application convention. You can therefore open VSCode and under
the project root folder you can include the following debug configuration:
-The JVM is suspended and waits for a debugger to attach by default: this
behavior can be turned off using the `--suspend=false` option.
+```json
+{
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "type": "java",
+ "name": "Attach to Remote JVM (Kubernetes)",
+ "request": "attach",
+ "hostName": "localhost",
+ "port": 5005,
+ "projectName": "my-java-app",
+ "timeout": 30000
+ }
+ ]
+}
+```
-Last thing to do is, to start a remote debugger on `localhost:5005` with the
**integration file, the Apache Camel project, or the Camel K Runtime project**,
opened on your IDE.
+The file has to be saved under `.vscode/launch.json` of the project root
directory. It basically tells the IDE to connect the debugger as it was on
`localhost:5005`. Then, on your application you can add the breakpoint on the
place you need to investigate. For example:
-The following picture shows the configuration of a remote debugger in IntelliJ
IDEA:
+image::debugging/camel-k-debugger-1.png[Add a breakpoint to a Camel
application on Kubernetes]
-image::debugging/remote-debugger.png[Configuration of the remote debugger in
IntelliJ IDEA]
+At this stage you can start the debugger via "Run >> Start Debugging" option.
The Pod will resume its execution and it will stop when reaching the
breakpoint. Here you will be able to debug according to your specific needs:
-Once you configure a debugger, you can **add breakpoints** to various part of
the code, then connect the debugger to trigger the JVM startup.
+image::debugging/camel-k-debugger-2.png[Debug like a pro any Camel application
on Kubernetes]
-When the debugging session is done, hitting kbd:[Ctrl+c] on the terminal where
the kamel CLI is running will restore the integration to its original status.
+When the debugging session is over, feel free to stop the `kamel debug` via
`CTRL + C`. This will terminate the Integration debugging Pod and will start a
new Pod to continue its work as usual.
diff --git a/pkg/cmd/debug.go b/pkg/cmd/debug.go
index 2a1b482c0..25a3be9f2 100644
--- a/pkg/cmd/debug.go
+++ b/pkg/cmd/debug.go
@@ -42,13 +42,12 @@ func newCmdDebug(rootCmdOptions *RootCmdOptions)
(*cobra.Command, *debugCmdOptio
}
cmd := cobra.Command{
- Use: "debug [integration name]",
- Short: "Debug an integration running on Kubernetes",
- Long: `Set an integration running on the Kubernetes
cluster in debug mode and forward ports in order to connect a remote debugger
running on the local host.`,
- Args: options.validateArgs,
- PreRunE: decode(&options, options.Flags),
- RunE: options.run,
- Deprecated: "Warning: this command is deprecated and will be
removed in the future.",
+ Use: "debug [integration name]",
+ Short: "Debug an integration running on Kubernetes",
+ Long: `Set an integration running on the Kubernetes cluster
in debug mode and forward ports in order to connect a remote debugger running
on the local host.`,
+ Args: options.validateArgs,
+ PreRunE: decode(&options, options.Flags),
+ RunE: options.run,
}
cmd.Flags().Bool("suspend", true, "Suspend the integration on startup,
to let the debugger attach from the beginning")
