Enable remote debugging Spring Boot apps on Kubernetes

Debugging in software development is one of the techniques involved in the identification of a problem in a program.
(Tracing and Static analysis of the source code are other common techniques)

In this Article, I’ll be focusing on remote debugging Java Spring boot applications from IntelliJ IDE, but still useful for other JVM based applications and IDEs.

JVM Remote debugging:

Remote debugging is very useful to locate errors on running applications. It allows to attach the IDE (source code) with the application process.
Then let us set breakpoints to temporary suspend our app’s execution and watch variable values, execution paths …

In order to remotely debug the target application, we should follow two steps:

- Enable debug agent in server mode on our application; by running it with extra params:

java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar app.jar

- Attach our IDE with exposed debug agent server:

From IntelliJ IDE, create new remote Run/Debug configuration and set the appropriate Host and port:

NB: Make sure that the firewall is allowing access to the specified port.

JVM Remote debugging on Kubernetes:

On Kubernetes we need to overcome two challenges:

1 - Application is running on a docker container:
So we need to adjust our docker file in order to enable debug agent server:

FROM ${BASE_IMAGE}
ARG JAR_FILE
RUN addgroup appli && adduser appli -D -G appli
WORKDIR /home/appli
COPY ${JAR_FILE} app.jar
RUN chown -R appli:appli /home/appli
USER appli
ENTRYPOINT [ “sh”, “-c”, “java $JAVA_OPTS -jar app.jar” ]

We could directly use following Entrypoint:

ENTRYPOINT [ “sh”, “-c”, “java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar app.jar” ]

But that makes us rebuild the docker image for enabling/disabling the remote debugging. And using a variable give us a real flexibility for enabling other cool JVM features, such as VisualVM.

2 - Second challenge is accessing the debug agent server from the IDE:

Therefore, we first need to expose the debug agent port “5005” as containerPort in kubernetes manifest:

spec:
  containers:
    env:
      - name: "JAVA_OPTS"
        value: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"
    ...
    ports:
      ...
      - containerPort: 5005

Note, our environment variable “JAVA_OPTS” is set to the appropriate value.

Now to access the exposed port from our local machine, we have two options:

- Using port-forward:

kubectl port-forward our-app-pod-name 5005:5005

Then from our IDE connect to host “localhost” and port “5005”

- Using a Service NodePort:

apiVersion: v1
kind: Service
metadata:
  name: appservice
spec:
  type: NodePort
  selector:
    app: app
  ports:
  - name: debug-agent
    protocol: TCP 
    port: 5005
    nodePort: 30055
    targetPort: 5005

Then from our IDE connect to host “node-IP” and port “30055”.