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"]
Scroll to view full table

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
Scroll to view full table

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
Scroll to view full table

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.


More from Cloud

Modernizing child support enforcement with IBM and AWS

7 min read - With 68% of child support enforcement (CSE) systems aging, most state agencies are currently modernizing them or preparing to modernize. More than 20% of families and children are supported by these systems, and with the current constituents of these systems becoming more consumer technology-centric, the use of antiquated technology systems is archaic and unsustainable. At this point, families expect state agencies to have a modern, efficient child support system. The following are some factors driving these states to pursue modernization:…

7 min read

IBM Cloud Databases for Elasticsearch End of Life and pricing changes

2 min read - As part of our partnership with Elastic, IBM is announcing the release of a new version of IBM Cloud Databases for Elasticsearch. We are excited to bring you an enhanced offering of our enterprise-ready, fully managed Elasticsearch. Our partnership with Elastic means that we will be able to offer more, richer functionality and world-class levels of support. The release of version 7.17 of our managed database service will include support for additional functionality, including things like Role Based Access Control…

2 min read

Connected products at the edge

6 min read - There are many overlapping business usage scenarios involving both the disciplines of the Internet of Things (IoT) and edge computing. But there is one very practical and promising use case that has been commonly deployed without many people thinking about it: connected products. This use case involves devices and equipment embedded with sensors, software and connectivity that exchange data with other products, operators or environments in real-time. In this blog post, we will look at the frequently overlooked phenomenon of…

6 min read

SRG Technology drives global software services with IBM Cloud VPC under the hood

4 min read - Headquartered in Ft. Lauderdale, Florida, SRG Technology LLC. (SRGT) is a software development company supporting the education, healthcare and travel industries. Their team creates data systems that deliver the right data in real time to customers around the globe. Whether those customers are medical offices and hospitals, schools or school districts, government agencies, or individual small businesses, SRGT addresses a wide spectrum of software services and technology needs with round-the-clock innovative thinking and fresh approaches to modern data problems. The…

4 min read