Debugging Kubernetes containers

Beta

This product or feature is in a pre-release state and might change or have limited support. For more information, see Product launch stages.

The Cloud Code Visual Studio Code extension supports Kubernetes debugging for Python, Node.js, Go, Java, and .NET Core. For each of these languages, launch and attach configuration snippets are provided for a one-click deploying and debugging experience.

Debugging an application

Caution: The debugger may not work in some environments due to known external issues. More details can be found on the troubleshooting page.

• If you created a new application with Cloud Code, no extra set up is required.

  Note: When creating a new application for Go, the debugger is turned off by default. There are instructions in the Dockerfile about how to enable it (by changing the entrypoint to dlv).

• Open VS Code's Debug view from the left taskbar .

• Select '<language of choice>-guestbook' as the debug configuration in the dropdown menu and press the debug start button to attach a debugger session to the Guestbook application. Cloud Code uses the .vscode/launch.json file to locate the pods to attach a debug session to.

• The Debug toolbar will now be open. Click in the margin of app.js to add a breakpoint. When you send a new request to your application, it will pause at that desired line.

• To inspect variables and stack info, use the Debug Sidebar. To interact with the debugging session, use the Debug Console in the bottom pane debugger.

  

Debugging an existing application

Node.js

1. Open the application in VS Code.

2. Start the Node.js application with --inspect=<debugPort> where debugPort comes from the debug configuration. For example: CMD ["node", "--inspect=9229", "index.js"]

   Tip: If the configuration selected is launch, the extension will automatically configure your container for debugging and you won't have to set debugPort.

3. Open VS Code's Debug view and add the debug configuration.

4. Edit configuration attributes like podSelector and debugPort to your liking.

   Tip: Use the podSelector attribute to choose the pod that you want to debug. A typical podSelector is normally:

   "podSelector": { "app": <deployment-name> }

5. Select and launch the configuration with F5.

   For launch (but not attach) configuration, the workspace needs to have a skaffold.yaml. The extension will use Skaffold to deploy the application to the Kubernetes cluster in the current context.

   Also, localhost:${debugPort} will be port-forwarded to debugPort on the container while debugging.

6. The debugging session is now successfully set up!

Python

1. Before you begin, ensure you have the ptvsd module installed on your machine.

2. Also ensure that your Python container has the ptvsd module installed.

   Start the Python application through ptvsd. Match the port specified to the debugPort field in the debug configuration. For example:

   CMD ["python", "-m", "ptvsd", "--port", "", "app.py"]
   

   Tip: If the configuration selected is launch, the extension will automatically configure your container for debugging and you won't have to set debugPort.

3. Open VS Code's Debug view and add the debug configuration.

4. Edit configuration attributes like podSelector and debugPort to your liking.

   Tip: Use the podSelector attribute to choose the pod that you want to debug. A typical podSelector is normally:

   "podSelector": { "app": <deployment-name> }

5. Select and launch the configuration with F5.

   For launch (but not attach) configuration, the workspace needs to have a skaffold.yaml. The extension will use Skaffold to deploy the application to the Kubernetes cluster in the current context.

   Also, localhost:${debugPort} will be port-forwarded to debugPort on the container while debugging.

6. The debugging session is now successfully set up!

Java

1. Before you begin, JVM must be installed on your machine.

2. Start the Java application with -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=<debugPort>,quiet=y where debugPort comes from the debug configuration.

   For example, to start the Java application in debug mode and listen on port debugPort for connection:

   ENTRYPOINT ["java","-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=<debugPort>,quiet=y", "-jar", "my-app-1.0.jar"]
   

   Tip: If the configuration selected is launch, the extension will automatically configure your container for debugging and you won't have to set debugPort.

3. Open VS Code's Debug view and add the debug configuration.

4. Edit configuration attributes like podSelector and debugPort to your liking.

   Tip: Use the podSelector attribute to choose the pod that you want to debug. A typical podSelector is normally:

   "podSelector": { "app": <deployment-name> }

5. Select and launch the configuration with F5.

   For launch (but not attach) configuration, the workspace needs to have a skaffold.yaml. The extension will use Skaffold to deploy the application to the Kubernetes cluster in the current context.

   Also, localhost:${debugPort} will be port-forwarded to debugPort on the container while debugging.

6. The debugging session is now successfully set up!

Go

1. Before you begin, ensure you have the dlv package installed on your machine.

   Also ensure that your Go container has the dlv package installed.

2. Start your Go application through dlv debug.

   The port specified in the starting command should be the same as the debugPort attribute value of the debug configuration. For example:

   CMD ["dlv", "debug", "--headless", "--listen=:<debugPort>", "--log"]
   

   Troubleshooting Tip: When debugging a Go application, the application will hang and wait for a debugger to attach. Attach a debugger for the service to start.

3. Open VS Code's Debug view and add the debug configuration.

4. Edit configuration attributes like podSelector and debugPort to your liking.

   Tip: Use the podSelector attribute to choose the pod that you want to debug. A typical podSelector is normally:

   "podSelector": { "app": <deployment-name> }

5. Select and launch the configuration with F5.

   For launch (but not attach) configuration, the workspace needs to have a skaffold.yaml. The extension will use Skaffold to deploy the application to the Kubernetes cluster in the current context.

   Also, localhost:${debugPort} will be port-forwarded to debugPort on the container while debugging.

6. The debugging session is now successfully set up!

.NET Core

1. Before you begin, ensure you have the vsdbg, the .NET Core command line debugger from Microsoft, installed on your Kubernetes container.

   To do so, uncomment the block that installs vsdbg from the auto-generated Dockerfile:

   RUN apt-get update \
     && apt-get install -y --no-install-recommends unzip \
     && apt-get install -y procps \
     && rm -rf /var/lib/apt/lists/* \
     && curl -sSL https://aka.ms/getvsdbgsh | bash /dev/stdin -v latest -l /vsdbg
   

2. Open VS Code's Debug view and add the debug configuration.

3. Edit configuration attributes like podSelector and debugPort to your liking.

   Tip: Use the podSelector attribute to choose the pod that you want to debug. A typical podSelector is normally:

   "podSelector": { "app": <deployment-name> }

4. Select and launch the configuration with F5.

   For launch (but not attach) configuration, the workspace needs to have a skaffold.yaml. The extension will use Skaffold to deploy the application to the Kubernetes cluster in the current context.

   Also, localhost:${debugPort} will be port-forwarded to debugPort on the container while debugging.

5. The debugging session is now successfully set up!

Configuration attributes

Attribute	Description
debugPort	Debug Port used on the container. Defaults to 9229.
localRoot	Path to the local directory containing the program being debugged. Defaults to ${workspaceFolder}.
podSelector	Set of key-value pairs used to select the debug pod (read more about selector here). A typical podSelector is normally: "podSelector": { "app": <deployment-name> }
protocol	Node.js debug protocol used. Defaults to auto.
remoteRoot	Absolute path to the remote directory containing the program being debugged (on the Kubernetes container). Defaults to /app.

Getting Support

To send feedback, report issues on GitHub, or ask a question on Stack Overflow.