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

Accelerating responsible AI adoption with a new Amazon Web Services (AWS) Generative AI Competency

3 min read - We’re at a watershed moment with generative AI. According to findings from the IBM Institute for Business Value, investment in generative AI is expected to grow nearly four times over the next two to three years. For enterprises that make the right investments in the technology it could deliver a strategic advantage that pays massive dividends. At IBM® we are committed to helping clients navigate this new reality and realize meaningful value from generative AI over the long term. For our…

New 4th Gen Intel Xeon profiles and dynamic network bandwidth shake up the IBM Cloud Bare Metal Servers for VPC portfolio

3 min read - We’re pleased to announce that 4th Gen Intel® Xeon® processors on IBM Cloud Bare Metal Servers for VPC are available on IBM Cloud. Our customers can now provision Intel’s newest microarchitecture inside their own virtual private cloud and gain access to a host of performance enhancements, including more core-to-memory ratios (21 new server profiles/) and dynamic network bandwidth exclusive to IBM Cloud VPC. For anyone keeping track, that’s 3x as many provisioning options than our current 2nd Gen Intel Xeon…

IBM and AWS: Driving the next-gen SAP transformation  

5 min read - SAP is the epicenter of business operations for companies around the world. In fact, 77% of the world’s transactional revenue touches an SAP system, and 92% of the Forbes Global 2000 companies use SAP, according to Frost & Sullivan.   Global challenges related to profitability, supply chains and sustainability are creating economic uncertainty for many companies. Modernizing SAP systems and embracing cloud environments like AWS can provide these companies with a real-time view of their business operations, fueling growth and increasing…

IBM Newsletters

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