Attaching a debugger to a Kubernetes pod

Cloud Code supports attaching a debugger to a Kubernetes pod for Node.js, Python, Go, Java and .NET. All you need is a debuggable container and an attach configuration of type cloudcode.kubernetes.

For information about how attaching to a Kubernetes pod differs from Debugging a Kubernetes application, see Attaching to a Kubernetes pod vs Debugging a Kubernetes application.

Setting up a container

To prepare your container for debugging, follow the instructions for the language you're using:

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 stop 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 the following options, where debugPort comes from the attach configuration. 

    -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=,quiet=y

    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, 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 Activity bar) 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

    This creates and opens a launch.json file for your project and creates 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, see Configuration attributes.

    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. To invoke the snippet Intellisense, click Add Configuration.
  3. Select the Cloud Code: Attach to Kubernetes Pod snippet for the language you're using.

  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 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 Debug stop icon Stop in 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.
The application must be 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'.
For more information, see Launch versus 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 can't be used to run the application. This configuration can be used to run or debug the application.
This configuration is language specific. This configuration is language agnostic.
No dedicated command. Debug on Kubernetes command.
Watch mode isn't available, so after making changes you restart the debugger manually. Watch mode lets Cloud Code restart the debugger after you save changes.

Getting Support

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