June 13, 2019 By Stephen Northover 4 min read

This article explains debugging in Kubernetes using VS Code on the desktop and Node running in IBM Cloud.

Understanding the steps required to debug an application running in Kubernetes can be a complicated task for some developers. Programmers expect debugging to “just work” the same way it does on their desktop, but the application is running remotely in a container. In some cases, IDE’s and code editors obscure the steps needed to debug or provide plugins that fail when misconfigured, leaving developers on their own.

This article explains debugging in Kubernetes using VS Code on the desktop and Node running in IBM Cloud, however, the steps apply to other languages.

Debugging in Kubernetes

Debugging an application in Kubernetes requires the following steps:

  1. Start the program in debug mode.
  2. Port forward the debug port.
  3. Attach the debugger to the running program.

Start the program in debug mode

Every program has a main. In Docker, the main is either an ENTRYPOINT or CMD statement. In order to change the way your program is started, you can either modify the main in your Dockerfile or override the container spec in your Kubernetes YAML. Often, the latter is more convenient as it allows you debug without rebuilding your container.

Here is the main for a container, overridden using an args: statement in a YAML deploy file:

        args: ["sh", "-c", "node --inspect --debug-brk server.js"]

At first glance, examining the statement, it may not be obvious what the debug arguments do.

The --inspect argument tells Node that it is running in debug mode. By default, the debug port is 9229. You can override the port if there is a conflict with a port in your application [--inspect], but you must change this number in the appropriate places in the other steps.

The —debug-brk argument tells Node to stop before the first line of your program is executed. This allows you to stop at breakpoints in your main program versus those in callbacks. If you do not specify this flag, your program will run past breakpoints in main because a debugger is required to set a breakpoint and one is not yet running. Callbacks are typically REST entry points that get invoked when you refresh a web page. Most of the time, you will want to stop there.

Note that in versions greater than Node 6, —debug-brk has been replaced with --inspect-brk and you need only to provide one of --inspect or --inspect-brk (but not both, remove --debug-brk).

After you have overridden the main, you’ll need to apply the changes to your running application. If you specify --debug-brk, don’t be surprised that your web pages are not refreshing.  Your server will not be serving any HTTP requests because it is halted in main.

If not done already, you’ll need to ensure in your deployment YAML that replicas is set to 1 to force all traffic to go to the container you will be debugging. This is the default, so if you do not have a replicas: statement, you do not need to add one.

Port forward the debug port

When your program is running under debug, it will be serving debug requests on port 9229. You’ll need to attach a debugger in order to set and respond to break points. The debugger will run on your desktop and listen on a port there, so you’ll need to connect to the remote port. Kubernetes supports port forwarding, but first, you’ll need to use kubectl get pods to get the name of the pod that you just deployed that is running under debug.

Here is the port-forward command that sends remote traffic in Kubernetes on port 9229 to the local port 9229 on your desktop for app-1234-abcd:

$ kubectl port-forward app-1234-abcd 9229:9229
Forwarding from -> 9229
Forwarding from [::1]:9229 -> 9229
Handling connection for 9229
Handling connecting for 9229

Attach the debugger to the running program

At this point, the server is running in debug mode and remote traffic on 9229 is redirected to your desktop. The next step is to attach a debugger. VS Code includes a Node debugger that is easy to understand, use, and configure. If you do not have a launch.json in your .vscode directory in the root of the source for your component, create one.

You can paste in the following entry or use VS Code’s code assist to generate it for you.

    "version": "0.2.0",
    "configurations": [
            "type": "node",
            "request": "attach",
            "name": "Attach to remote Node.js (9229)",
            "address": "",
            "port": 9229

Once you have saved launch.json, attach the debugger to the remote program:

After the debugger has attached, you should see a screen that looks something like this:


When developing and running in Kubernetes, programs are running in containers, and changing code requires rebuilding and deploying new containers. Deploying, port forwarding, and reattaching a debugger can become tedious during development. Tools such as Skaffold support save and redeploy, and IDE and editor plugins can help, but these tools can obscure the debug steps, which are always helpful to understand should something go wrong. 

Happy debugging! 

Learn more about the IBM Cloud Kubernetes Service.


Was this article helpful?

More from Cloud

Think inside the box: Container use cases, examples and applications

5 min read - Container management has come a long way. For decades, managing containerized environments was a relatively simple affair. The modern idea of a computer container originally appeared back in the 1970s, with the concept first being used to help define application code on Unix systems. Modern containerization technology has moved on steadily from those early beginnings, and when companies run containers now, they’re getting a lot more utility for their investment. From small startups to large, established businesses, container frameworks have…

IBM Tech Now: February 26, 2024

< 1 min read - ​Welcome IBM Tech Now, our video web series featuring the latest and greatest news and announcements in the world of technology. Make sure you subscribe to our YouTube channel to be notified every time a new IBM Tech Now video is published. IBM Tech Now: Episode 92 On this episode, we're covering the following topics: IBM watsonx Orders EDGE3 + watsonx G2 Best of Software Awards Stay plugged in You can check out the IBM Blog Announcements for a full…

IBM Cloud delivers enterprise sovereign cloud capabilities

5 min read - As we see enterprises increasingly face geographic requirements around sovereignty, IBM Cloud® is committed to helping clients navigate beyond the complexity so they can drive true transformation with innovative hybrid cloud technologies. We believe this is particularly important with the rise of generative AI. While AI can undoubtedly offer a competitive edge to organizations that effectively leverage its capabilities, we have seen unique concerns from industry to industry and region to region that must be considered—particularly around data. We strongly…

IBM Newsletters

Get our newsletters and topic updates that deliver the latest thought leadership and insights on emerging trends.
Subscribe now More newsletters