Kubernetes has become the de facto standard for deploying and managing containerized applications at scale. However, debugging applications within a Kubernetes cluster introduces new challenges for developers. In this guide, I will explain the necessary steps to set up debugging for a Kubernetes application using IntelliJ IDEA.
I have created a sample Spring boot application to demonstrate it. It can be accessed form my github repo food-for-techies/k8s-debug. Application contains both Dockerfile and Kubernetes deployment descriptor, so that you can directly build, test and verify the steps listed below.
Configure Kubernetes YAML for Debugging
The first step is to modify its Kubernetes YAML configuration. You need to open the debugging port, which is typically port 5005. To do this, include the debug port in both the Deployment and Service specifications within your YAML file. This will allow remote debugging sessions to connect to the application running in the cluster. After change deployment YAML should have following snippet under containers
ports:
- name: http-port
containerPort: 8080
protocol: TCP
- name: debug-port
containerPort: 5005
protocol: TCP
and service YAML should have following snippet under spec:
ports:
- protocol: TCP
port: 8080
name: http-port
targetPort: 8080
- protocol: TCP
port: 5005
name: debug-port
targetPort: 5005
Set Up Environment Variables for Debugging
Next, you will need to add an environment variable to your container configuration. This variable sets the necessary JVM options to enable debugging. Add the JAVA_TOOL_OPTIONS environment variable with the appropriate value to your container's specification in the YAML file. After change container section in deployment should have following snippet:
env:
- name: JAVA_TOOL_OPTIONS
value: '-Xdebug -agentlib:jdwp=transport=dt_socket,address=0.0.0.0:5005,server=y,suspend=n'
Note that debug port which was configured in deployment and service YAML definition should match the port in address. You are free to use any port but same port should be used at all places. In my case I am using port 5005.
Establish Port Forwarding with Kubernetes
With the configuration in place, you can now set up port forwarding to allow your local machine to access the debug port on the Kubernetes cluster. Use the kubectl command to forward local ports to the corresponding ports on the cluster.
kubectl port-forward service/<your-app-service> 8080:80 5005:5005
Replace <your-app-service> with the name the service running in your cluster. Also, above command assumes service is running in default namespace. If that is not the case, you need to specify the correct namespace using -n option.
Create a Debug Configuration in IntelliJ IDEA
Open IntelliJ IDEA and navigate to the debug configurations by clicking on 'Run' > 'Edit Configurations'. Create a new remote debug configuration by selecting the '+' icon and choosing 'Remote'. Set the port to 5005, which matches the port specified in the YAML file and the port forwarding command.
Set Breakpoints in Your Application Code
With IntelliJ IDEA configured, you can now set breakpoints in your application code as you would normally do. These breakpoints will enable you to pause execution and inspect the state of your application when it's running inside the Kubernetes cluster.
Initiate a Debugging Session
Finally, to start a debugging session, hit the debug icon in IntelliJ IDEA. Then, trigger a request to your application that would hit the code where you've set the breakpoints. IntelliJ IDEA will pause the execution at the breakpoints, allowing you to inspect variables, evaluate expressions, and step through the code.
By following these steps, you can effectively debug a Kubernetes application directly from IntelliJ IDEA.
I hope this helps.
