Attaching a debugger to a Kubernetes pod

The Cloud Code VS Code extension supports attaching a debugger to a Kubernetes pod. All you need to have is a debuggable container and an attach configuration of type cloudcode.kubernetes.

Setting up a container

You will have to ensure that the container you'd like to debug is debug-ready. Below are the language specific instructions to set up containers to do so.

Node.js

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

Python

  • Ensure you have the ptvsd module installed on your machine and in your container.
  • Start the Python application through ptvsd. Match the port specified to the debugPort field in the attach configuration. For example: 
    CMD ["python", "-m", "ptvsd", "--port", "", "app.py"]

Go

  • Ensure you have the dlv package installed on your machine and your Go container.

  • Start your Go application through dlv debug.

    The port specified in the starting command should be the same as the debugPort attribute value in the attach 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.

Java

  • Ensure that JVM is installed on your machine.

  • Start the Java application with -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=<debugPort>,quiet=y where debugPort comes from the attach 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"]

.NET Core

  • Ensure you have the vsdbg, the .NET Core command line debugger from Microsoft, installed on your Kubernetes container.

    For example: 

    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

Setting up an attach configuration

To attach to a debuggable container from VS Code, you need to have an attach configuration of type cloudcode.kubernetes.

Projects that don't have .vscode/launch.json file

If your project doesn't have a launch.json file in its .vscode folder, you can add one using the Debug panel.

  1. Navigate to the Debug panel (using the Debug view icon Debug icon from the left taskbar) and select Add Configuration from the dropdown menu.

    Adding configuration using the debug panel

  2. Select Cloud Code: Kubernetes as the environment.

    Setting Cloud Code: Kubernetes as the environment

  3. Select Attach to Kubernetes Pod option. Select Kubernetes configuration option

  4. Select the corresponding programming language.

    Selecting a preferred programming language

  5. This will create and open a launch.json file for your project as well as create an attach configuration for you. You can now update configuration attributes in this file to match those of your project. For more information on configuration attributes, refer to this table.

    Configuration attributes displayed in an open launch.json file

Projects that have .vscode/launch.json file

To add a new attach configuration to an existing .vscode/launch.json:

  1. Open the launch.json file.
  2. Press the Add Configuration button that invokes the snippet Intellisense.
  3. Select one of the Cloud Code: Attach to Kubernetes Pod snippets for the desired language.

  4. This will add an attach configuration. You can now update attributes in this configuration to match those of your project. For more information on configuration attributes, refer to this table.

    Add Kubernetes attach configuration

Configuration attributes

Attribute Description
debugPort Debug port used on the container.
podSelector Set of key-value pairs used to select the debug pod (for more information, refer to guide on selectors). A typical podSelector is normally:

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

localRoot Path to the local directory containing the program being debugged. Defaults to ${workspaceFolder}.
remoteRoot Absolute path to the remote directory containing the program being debugged (on the Kubernetes container).

Attaching a debugger to a Kubernetes pod

Once you have set up the configuration and the container:

  1. Open VS Code's Debug view Debug icon.
  2. Select and launch the configuration with F5.
    • localhost:${debugPort} will be port-forwarded to debugPort on the container while debugging.
  3. The debugging session is now successfully set up!
  4. You can now perform all the tasks you normally do when debugging local code, like setting breakpoints and stepping through code.

  5. 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.

    App paused at breakpoint and variables and call stack sections populated with values in scope

  6. To end the debugging session, click the stop icon on the Debug Toolbar.

Attaching to a Kubernetes pod vs Debugging a Kubernetes application

Attaching to a Kubernetes pod Debugging a Kubernetes application
Debugs a single Kubernetes pod Debugs all the debuggable containers in the application
You'll have to ensure that the application is running in the Kubernetes pod before debugging. Runs the application on the Kubernetes cluster and attaches the debugger.
Uses configuration (.vscode/launch.json) of type 'cloudcode.kubernetes' and request 'attach'. Uses configuration (.vscode/launch.json) of type 'cloudcode.kubernetes' and request 'launch'.
launch verses attach configurations.
Sample Config: 
{
  "name": "Attach to Kubernetes Pod (NodeJS)",
  "type": "cloudcode.kubernetes",
  "request": "attach",
  "language": "Node",
  "debugPort": 9229,
  "podSelector": {
     "app": "hello-world"
  },
  "localRoot": "${workspaceFolder}",
  "remoteRoot": "/app"
}
Sample Config: 
{
  "name": "Run/Debug on Kubernetes",
  "type": "cloudcode.kubernetes",
  "request": "launch",
  "skaffoldConfig": "${workspaceFolder}/skaffold.yaml",
  "watch": true,
  "cleanUp": true,
  "portForward": true
}
This configuration cannot be used to run the application This configuration can be used for both running or debugging the application.
This configuration is language specific This configuration is language agnostic
No dedicated command 'Debug on Kubernetes' command

Getting Support

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