Attach a debugger to a Kubernetes pod in Cloud Code for VS Code

Cloud Code for VS 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

  • Make sure that 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

  • Make sure that 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

  • Make sure 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

  • Make sure that 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 a .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. To navigate to the Debug panel, click Debug icon Run and Debug in the Activity bar.

  2. Select Add Configuration from the drop-down menu.

  3. Select Cloud Code: Kubernetes as the environment.

    Setting Cloud Code: Kubernetes as the environment

  4. Select the Attach to Kubernetes Pod option.

    Select Kubernetes configuration option

  5. Select the programming language you're using.

    This creates and opens a launch.json file for your project and creates an attach configuration for you.

  6. Update configuration attributes in the launch.json file to match those of your project. For more information on configuration attributes, see Configuration attributes.

Projects that have .vscode/launch.json file

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

  1. Open the launch.json file.
  2. To invoke the snippet Intellisense, click Add Configuration.
  3. To add an attach configuration, select the Cloud Code: Attach to Kubernetes Pod snippet for the language you're using.
  4. Update attributes in the configuration to match those of your project. For more information on configuration attributes, see Configuration attributes.

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, see the guide on selectors). The following sample shows a typical `podSelector`:

"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

After you have set up the configuration and the container:

  1. To navigate to the Debug panel, click Debug icon Run and Debug in the Activity bar.
  2. Select and launch the configuration by pressing F5.

    • localhost:${debugPort} is port-forwarded to debugPort on the container while debugging.

    The debugging session is now successfully set up. You can perform the tasks you normally do when debugging local code, like setting breakpoints and stepping through code.

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

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