Debug Kubernetes applications in Cloud Code for Cloud Shell

Note: Debugging support is available for Node.js, Python, Go, Java, and .NET.

Cloud Code lets you debug an application deployed to aGoogle Kubernetes Engine (GKE) cluster by leveragingskaffold debug.

You can debug your application on a local cluster (likeminikube orDocker Desktop),GKE, or any other cloud provider.

With Cloud Code's debugging support, you don't have to completemanual setup like setting up port forwarding or injecting language-specificdebug arguments. Debugging requires a Cloud Code-readyGKE application that includes askaffold.yamlconfiguration file and acloudcode.kubernetes launch configuration.

Debug a GKE application

To begin debugging your GKE application, follow thesesteps:

  1. In the Cloud Code status bar, click the active project name.

    Active project name in status bar

  2. In the Quick Pick menu that appears, selectDebug on Kubernetes.

  3. If your application doesn't have the necessarySkaffold configuration orcloudcode.kubernetes launch configuration, Cloud Codehelps you set these up.

  4. Confirm whether to use the currentKubernetes contextto run the app in (or switch to a preferred one).

  5. If you chose a remote cluster as the context, when prompted, choose an imageregistry to push the images to.

    If your project hasArtifact Registry API enabled and at leastoneArtifact Registry repository, youcan browse to and select an existing Artifact Registry repository.

    The following samples demonstrate how to specify where container images arestored for some common registries:

    Artifact RegistryREGION-docker.pkg.dev/PROJECT_ID/REPO_NAME
    Docker Hubdocker.io/ACCOUNT
    Make sure that you'reproperly authenticated if you're using a private Docker Hub repository.

    To generate the final image repository name, Cloud Codeconcatenates this image registry with the image name specified in theKubernetes manifests. This choice is stored in yourcloudcode.kuberneteslaunch configuration (found in.vscode/launch.json).

    For more information, see theimage registry handling guide.

    Cloud Code builds your containers, pushes themto the registry, applies Kubernetes configurations to the cluster, and waitsfor the rollout.

    After the rollout, Cloud Code automatically port-forwards alldeclared container ports to your machine and displays the URLs in the outputwindow so that you can browse your live application.

  6. For each debuggable container in your application, confirm or enter thedirectory in the remote container where the program you want to debug islocated.

    Alternatively, you can pressESC to skip debugging the container.

    Remote Root prompt

    Cloud Code attaches a debug session for each debuggablecontainer in the application.

    You can now perform the same tasks you normally do when debugging local code,like setting breakpoints and stepping through code, against a live Kubernetescluster.

    By default, when a change to your application is autosaved,Cloud Code redeploys your application and sets up a new debugsession. You can toggle this feature with thewatch flag in your project'slaunch configuration.

  7. To inspect variables and stack info, use theDebug Sidebar.To interact with the debugging session, use theDebug Consolein the bottom pane debugger.

  8. After your session completes, you can use the following contextual menucommands:

    • Open Deployment Logs: Open the application logs of a specificdeployment with the Cloud Code logs explorer.
    • Open Service URL: Open the application service URL of a specificservice in a web browser

  9. If you've turned off watch mode in your launch configuration and you want tomake changes to your application and rebuild and redeploy the application,in the Development sessions pane, pause on the run action and then clickRebuild and redeploy iconRebuild and redeploy the application.

  10. To end the debugging session, clickDebug stop iconStop in the Debug Toolbar.

    After you end the debugging session, all the deployed Kubernetes resourcesare deleted from the cluster.

Configuration details

Note: Cloud Code doesn't modify your local Kubernetesconfigurations. The transformations happen at deploy-time and are visibleonly on the server.

Cloud Code, powered bySkaffold, automaticallyhandles the following configuration details for all supported languages:

  • Port forwarding the debug port so that the debugger can be attached.
  • Attaching a debugger to one or more debuggable containers in your application.If your application has multiple debuggable containers (containers whoselanguage is supported by Cloud Code debug) configured inskaffold.yaml, then a debugger is attached to each debuggable container.
  • Persisting source mapping definitions across sessions; you can customize thesedefinitions by editing your.vscode/launch.json file directly.

Cloud Code also handles the following language-specificconfiguration details:

Node.js

Rewriting the entrypoint to invoke:

node--inspect=localhost:9229

Python

Installing theptvsd moduleusing an Init Container and rewriting the entrypoint to invoke:

python-mptvsd--hostlocalhost--port5678

Go

Installing thedlv debuggerusing an Init Container and rewriting the entrypoint such that the launcheddebug session runs with a debug server only (in headless mode), continues thedebugged process on start, accepts multiple client connections, and listens atlocalhost:56268:

dlvexec--headless--continue--accept-multiclient--listen=localhost:56268--api-version=2,<app>--

Java

Adding an environmentJAVA_TOOLS_OPTIONS with the appropriate Java DebugWire Protocol (JDWP) configuration such that the JDWP debugging agent listensfor a socket connection on port 5005 and allows the VM to begin executingbefore the debugger is attached:

jdwp=transport=dt_socket,server=y,suspend=n,address=5005,quiet=y

For more details on Skaffold-powered debugging, see theskaffold debug documentation.

Set up your container

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

Node.js

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

Python

  • Make sure that you have theptvsd moduleinstalled on your machine and in your container.
  • Start the Python application throughptvsd. Match the port specified tothedebugPort field in theattach configuration.For example:
    CMD["python","-m","ptvsd","--port","","app.py"]

Go

  • Make sure that you have thedlv packageinstalled on your machine and your Go container.

  • Start your Go application throughdlv debug.

    The port specified in the starting command should be the same as thedebugPort attribute value in theattach configuration.For example:

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

    Troubleshooting Tip: When debugging a Go application, the applicationwill stop and wait for a debugger to attach. Attach a debugger for theservice to start.

Java

  • Make sure that JVM is installed on your machine.

  • Start the Java application with the following options, wheredebugPortcomes from theattach configuration.

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

    For example, to start the Java application in debug mode andlisten on portdebugPort 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 thevsdbg, the .NET Corecommand line debugger from Microsoft, installed on yourKubernetes container.

    For example:

    RUNapt-getupdate
      &&apt-getinstall-y--no-install-recommendsunzip
      &&apt-getinstall-yprocps
      &&rm-rf/var/lib/apt/lists/*
      &&curl-sSLhttps://aka.ms/getvsdbgsh|bash/dev/stdin-vlatest-l/dbg/netcore/vsdbg

Set up your attach configuration

To attach to a debuggable container, you need to have anattach configurationof typecloudcode.kubernetes.

Add a .vscode/launch.json file

If your project doesn't have alaunch.json file in its.vscodefolder, you can add one using the Debug panel.

  1. To navigate to the Debug panel, clickDebug iconDebugin the Activity bar.

  2. SelectAdd Configuration from the drop-down menu.

  3. SelectCloud Code: Kubernetes as the environment.

    Setting Cloud Code: Kubernetes as the environment

  4. Select theAttach to Kubernetes Pod option.

    Select Kubernetes configuration option

  5. Select the programming language you're using.

    This creates and opens alaunch.json file for your project and creates anattach configuration for you.

  6. Update configuration attributes in thelaunch.json file to match those ofyour project. For more information on configuration attributes, seeConfiguration attributes.

Add an attach configuration to your .vscode/launch.json file

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

  1. Open thelaunch.json file.
  2. To invoke the snippet Intellisense, clickAdd Configuration.
  3. To add an attach configuration, select theCloud Code: Attach to Kubernetes Pod snippet for the language you'reusing.
  4. Update attributes in the configuration to match those of yourproject. For more information on configuration attributes, seeConfiguration attributes.

Configuration attributes

AttributeDescription
debugPortDebug port used on the container.
podSelectorSet of key-value pairs used to select the debug pod. For more information, see theguide on selectors). The following sample shows a typicalpodSelector:

"podSelector": { "app": <deployment-name> }
localRootPath to the local directory containing the program being debugged. Defaults to ${workspaceFolder}.
remoteRootAbsolute path to the remote directory containing the program being debugged (on the Kubernetes container).

Attach a debugger to your Kubernetes pod

Cloud Code for Cloud Shell supports attaching a debugger to a Kubernetes pod forNode.js, Python, Go, Java and .NET. All you need is adebuggable container and anattach configuration of typecloudcode.kubernetes.

For information about how attaching to a Kubernetes pod differs fromdebugging a Kubernetes application, seeHow attaching a debugger to a pod differs from debugging a Kubernetes application.

To attach a debugger to your Kubernetes pod, perform the following tasks:

  1. To navigate to the Debug panel, clickDebug iconDebugin the Activity bar.

  2. Select and launch the configuration by pressingF5.

    • localhost:${debugPort} is port-forwarded todebugPort onthe container while debugging.

    The debugging session is now successfully set up. You can perform the tasksyou normally do when debugging local code, like setting breakpoints andstepping through code.

  3. To inspect variables and stack info, use theDebug Sidebar.To interact with the debugging session, use theDebug Consolein the bottom pane debugger.

  4. To end the debugging session, clickDebug stop iconStopin the Debug Toolbar.

How attaching a debugger to a pod differs from debugging a Kubernetes application

Attach to a Kubernetes podDebug 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.
Usesconfiguration (.vscode/launch.json) of typecloudcode.kubernetes and requestattach.Usesconfiguration (.vscode/launch.json) of typecloudcode.kubernetes and requestlaunch.
For more information, seeLaunch 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 not language specific.
No dedicated command.Debug on Kubernetes command.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.