# Debugging in Kubernetes

IntelliJ IDEA supports the following Kubernetes debugging flows: on-the-fly pod troubleshooting with ephemeral containers and remote debugging with Telepresence, so you can diagnose various issues without leaving your IDE.

Procedure: Enable the Kubernetes plugin

This functionality relies on the [Kubernetes](https://plugins.jetbrains.com/plugin/10485-kubernetes)  plugin, which  is bundled and enabled in IntelliJ IDEA   by default. If the relevant features are not available, make sure that you did not disable the plugin.

> **Note:**
> The Kubernetes plugin is not available in IntelliJ IDEA without the Ultimate subscription.

1. Press `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) to open settings and then select `Plugins`.

2. Open the Installed tab, find the Kubernetes plugin, and select the checkbox next to the plugin name.

## Ephemeral containers

IntelliJ IDEA supports attaching [ephemeral containers](https://kubernetes.io/docs/concepts/workloads/pods/ephemeral-containers/) to running pods without restarting them. This way, you can inspect a live Kubernetes environment, run diagnostic commands, and investigate issues directly inside a running pod.

An ephemeral container is temporarily added to an existing pod for debugging and runs alongside your application containers. For this purpose, IntelliJ IDEA runs the `kubectl debug` command under the hood. You can either attach your custom debug container or use a lightweight BusyBox image, which provides common tools like `ping`, `netstat`, `wget`, and `top` out of the box.

For more details on debugging running pods, refer to the [Kubernetes
documentation](https://kubernetes.io/docs/tasks/debug/debug-application/debug-running-pod/).

Procedure: Attach BusyBox to a running pod

1. Open the [Services](services-tool-window.html) tool window: go to `View | Tool Windows | Services` or press `Alt+8` (Windows), `⌘ 8` (macOS), `⌘ 8` (IntelliJ IDEA Classic (macOS)), `⌘ 8` (macOS System Shortcuts), `Alt+8` (XWin), `Alt+8` (GNOME), `Alt+8` (KDE), `Alt+8` (Emacs), `Alt+8` (Sublime Text), `⌘ 8` (Sublime Text (macOS)), `Alt+8` (NetBeans), `Alt+8` (Visual Studio), `Alt+8` (Visual Studio (macOS)), `Alt+8` (Eclipse), `⌘ 8` (Eclipse (macOS)).

2. Expand the node that lists running pods, right-click the pod you want to debug, and select `Ephemeral Debug Containers | Attach Busybox` from the context menu.

Alternatively, select the required pod, click ![the Ephemeral Container icon](https://resources.jetbrains.com/help/img/idea/2026.2/clouds-kubernetes.icons.newui.ephemeralStoppedContainer.png) on the toolbar, and select Attach Busybox from the dropdown.

![Attach BusyBox](https://resources.jetbrains.com/help/img/idea/2026.2/kubernetes_attach_busybox_container.png)

Procedure: Attach a custom container to a running pod

1. Open the [Services](services-tool-window.html) tool window: go to `View | Tool Windows | Services` or press `Alt+8` (Windows), `⌘ 8` (macOS), `⌘ 8` (IntelliJ IDEA Classic (macOS)), `⌘ 8` (macOS System Shortcuts), `Alt+8` (XWin), `Alt+8` (GNOME), `Alt+8` (KDE), `Alt+8` (Emacs), `Alt+8` (Sublime Text), `⌘ 8` (Sublime Text (macOS)), `Alt+8` (NetBeans), `Alt+8` (Visual Studio), `Alt+8` (Visual Studio (macOS)), `Alt+8` (Eclipse), `⌘ 8` (Eclipse (macOS)).

2. Expand the node that lists running pods, right-click the pod you want to debug, and select `Ephemeral Debug Containers | Attach Custom` from the context menu.

Alternatively, select the required pod, click ![the Ephemeral Container icon](https://resources.jetbrains.com/help/img/idea/2026.2/clouds-kubernetes.icons.newui.ephemeralStoppedContainer.png) on the toolbar, and select Attach Custom from the dropdown.

3. In the Attach Custom Debug Container dialog, use the following fields to customize the `kubectl debug` command for starting and attaching an ephemeral container:

* Pod: select the pod you want to debug from the dropdown.

* Target: specify the target container inside the selected pod.

* Image: start typing the name of an image to use for debugging and then select it from the list of suggestions.

* Executable: specify an absolute path to the shell to run inside the ephemeral container after it starts (for example, `/bin/sh` for BusyBox or `/bin/bash` for Ubuntu).

* Options: provide additional configuration parameters for the debug container. For examples, refer to the [Kubernetes documentation](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_debug/).

![the Attach Custom Debug Container dialog](https://resources.jetbrains.com/help/img/idea/2026.2/kubernetes_attach_custom_container.png)

> **Tip:**
> Hover over the ![the Preview Command](https://resources.jetbrains.com/help/img/idea/2026.2/clouds-kubernetes.icons.newui.consoleCommand.png) icon to preview the resulting `kubectl debug` command.

4. Click Attach to Pod.

When IntelliJ IDEA starts a new ephemeral container and successfully attaches it to the pod, the Console tab opens, where you can run commands and inspect the pod.

![Debug console](https://resources.jetbrains.com/help/img/idea/2026.2/kubernetes_busybox_container_console.png)

If you [attach BusyBox](#attach-busybox-container-to-pod), IntelliJ IDEA automatically uses `sh`. For [custom images](#attach-custom-container-to-pod), the IDE uses the shell specified in the Executable field.

The container is removed when you delete the pod it is attached to.

### Recent commands

When you attach an ephemeral container using the Ephemeral Debug Containers menu, IntelliJ IDEA automatically saves the corresponding `kubectl debug` command. You can access and rerun it later from the Recent section.

![Recent commands](https://resources.jetbrains.com/help/img/idea/2026.2/kubernetes_recent_commands.png)

Procedure: Start an ephemeral container using a recent command

1. Open the [Services](services-tool-window.html) tool window: go to `View | Tool Windows | Services` or press `Alt+8` (Windows), `⌘ 8` (macOS), `⌘ 8` (IntelliJ IDEA Classic (macOS)), `⌘ 8` (macOS System Shortcuts), `Alt+8` (XWin), `Alt+8` (GNOME), `Alt+8` (KDE), `Alt+8` (Emacs), `Alt+8` (Sublime Text), `⌘ 8` (Sublime Text (macOS)), `Alt+8` (NetBeans), `Alt+8` (Visual Studio), `Alt+8` (Visual Studio (macOS)), `Alt+8` (Eclipse), `⌘ 8` (Eclipse (macOS)).

2. Expand the node that lists running pods and right-click the pod you want to debug. Select Ephemeral Debug Containers and the required recent command from the context menu.

Alternatively, select the required pod, click ![the Ephemeral Container icon](https://resources.jetbrains.com/help/img/idea/2026.2/clouds-kubernetes.icons.newui.ephemeralStoppedContainer.png) on the toolbar, and select the recent command from the dropdown.

Procedure: Manage recent commands

1. Access recent commands:

* In the Settings dialog (`Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS))), select `Build, Execution, Deployment | Kubernetes | Cluster Interaction`.

* Open the Sevices tool window (`Alt+8` (Windows), `⌘ 8` (macOS), `⌘ 8` (IntelliJ IDEA Classic (macOS)), `⌘ 8` (macOS System Shortcuts), `Alt+8` (XWin), `Alt+8` (GNOME), `Alt+8` (KDE), `Alt+8` (Emacs), `Alt+8` (Sublime Text), `⌘ 8` (Sublime Text (macOS)), `Alt+8` (NetBeans), `Alt+8` (Visual Studio), `Alt+8` (Visual Studio (macOS)), `Alt+8` (Eclipse), `⌘ 8` (Eclipse (macOS))). Right-click any running pod and select `Ephemeral Debug Containers | Edit Recents` from the context menu.

2. Navigate to the Ephemeral Debug Containers section.

* To add a new command that you can preconfigure and quickly start new ephemeral containers, click ![the Plus icon](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.expui.general.add.svg). In the Add Debug Parameters dialog, you can specify an image, executable, and options for the `kubectl debug` command.

* To remove a command from recents, select it in the table and click ![the Minus icon](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.expui.general.remove.svg).

* To edit an existing command, select it in the table and click ![the Edit icon](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.expui.general.edit.svg). In the Add Debug Parameters dialog, change the image, executable, and options for the `kubectl debug` command.

## Telepresence

[Telepresence](https://telepresence.io/docs/quick-start) is a tool that lets you access services in a Kubernetes cluster, debug them, make, and test changes as if the services were running on your computer locally.

The Kubernetes plugin provides integration with Telepresence allowing you to:

* [Connect to Telepresence](#connect-to-telepresence) to access a service in the cluster by its DNS name.

* [Intercept a service](#intercept-traffic-from-cluster) to route traffic from the cluster to your local environment.

Procedure: Connect to Telepresence

1. Open the [Services](services-tool-window.html) tool window: select `View | Tool Windows | Services` or press `Alt+8` (Windows), `⌘ 8` (macOS), `⌘ 8` (IntelliJ IDEA Classic (macOS)), `⌘ 8` (macOS System Shortcuts), `Alt+8` (XWin), `Alt+8` (GNOME), `Alt+8` (KDE), `Alt+8` (Emacs), `Alt+8` (Sublime Text), `⌘ 8` (Sublime Text (macOS)), `Alt+8` (NetBeans), `Alt+8` (Visual Studio), `Alt+8` (Visual Studio (macOS)), `Alt+8` (Eclipse), `⌘ 8` (Eclipse (macOS)).

2. Right-click your Kubernetes cluster and select  Connect Telepresence. Alternatively, click ![Telepresence icon](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.expui.actions.split.svg) in the toolbar. When prompted, enter your administrator account password required to start the Telepresence daemon. On Windows, allow `telepresence.exe` to be executed.

> **Tip:**
> On macOS and Linux, if Telepresence is not installed on your computer, a notification will appear, providing you with the option to install it. Telepresence will be installed in `/usr/local/bin`. Similarly, if [Traffic Manager](https://www.getambassador.io/docs/telepresence-oss/latest/install/manager) is not installed in the cluster, IntelliJ IDEA will prompt you to install it.
>
>
>
> For Windows, follow the [Telepresence installation documentation](https://www.getambassador.io/docs/telepresence/latest/install?os=windows).
>
>
>
> ![Install Traffic Manager](https://resources.jetbrains.com/help/img/idea/2026.2/kubernetes_install_traffic_manager.png)

3. After installing Telepresence and Traffic Manager, click  Connect Telepresence  again.

You can now access services in the Kubernetes cluster by their DNS names as if the cluster were running on your workstation. For example, if you have an application that accepts requests to `hello-node:9001`, you can access it by its name.

![Telepresence Connect](https://resources.jetbrains.com/help/img/idea/2026.2/kubernetes_connect_telepresence_check.animated.gif)

Procedure: Intercept traffic from the cluster

Intercepts allow you to take traffic going to a service in the Kubernetes cluster and route it to the local service.

1. On the toolbar, click ![Telepresence icon](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.expui.actions.split.svg) (Create New Interception) and then click Create new interception.

2. In the window that opens, in the Service list, select a workload to intercept. This can be a Deployment, a ReplicaSet, or a StatefulSet.

In the Ports field, specify the port on which the local instance of your service is running.

![Telepresence Intercept](https://resources.jetbrains.com/help/img/idea/2026.2/kubernetes_telepresence_intercept.png)

If the service is intercepted successfully, you can access it locally and use the IDE features to try, debug, and profile your application running in the cluster.

Procedure: Quit Telepresence

Telepresence interacts with one cluster at a time, so you may need to stop it before connecting to another cluster. Quitting Telepresence will stop all active intercepts.

1. Open the [Services](services-tool-window.html) tool window: select `View | Tool Windows | Services` or press `Alt+8` (Windows), `⌘ 8` (macOS), `⌘ 8` (IntelliJ IDEA Classic (macOS)), `⌘ 8` (macOS System Shortcuts), `Alt+8` (XWin), `Alt+8` (GNOME), `Alt+8` (KDE), `Alt+8` (Emacs), `Alt+8` (Sublime Text), `⌘ 8` (Sublime Text (macOS)), `Alt+8` (NetBeans), `Alt+8` (Visual Studio), `Alt+8` (Visual Studio (macOS)), `Alt+8` (Eclipse), `⌘ 8` (Eclipse (macOS)).

2. Right-click your Kubernetes cluster and select Quit Telepresence. Alternatively, click ![Quit Telepresence icon](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.expui.general.exit.svg) in the toolbar.

### Run the application with interception

In IntelliJ IDEA, with a single click, you can run your local application and, at the same time, redirect traffic destined for a service in your Kubernetes cluster to this local application.

This is achieved by configuring a tunnel (a Telepresence intercept) to your Kubernetes cluster and [adding it as a Before launch
task to your run configuration](#add-interception-in-your-run-configuration). Each time you[run this run configuration](#run-application-and-intercept-service), IntelliJ IDEA creates a Telepresence intercept allowing you to debug your remote application as if it was running locally.

> **Tip:**
> This feature is currently supported for the following run/debug configurations:
>
>
>
> * Application (for Java applications), Kotlin, and Spring Boot
>
> * Go Build
>
> * Python, Django, Flask, and FastAPI
>
> * Node.js, Bun, and Deno
>
> * Cargo

Procedure: Add interception to your run configuration

1. Make sure that:

* The original instance of your service is deployed and running in your Kubernetes cluster, and the source code of its local instance is opened in your editor.

* Your IntelliJ IDEA instance is [connected to your Kubernetes cluster](kubernetes.html#add-cluster).

2. Click ![](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.expui.gutter.run.svg) in the gutter near the main class declaration and select Add Tunnel for Remote Debug. This action is available if you have at least one cluster connected in IntelliJ IDEA.

![Add Tunnel for Remote Debug](https://resources.jetbrains.com/help/img/idea/2026.2/connect_telepresence_from_editor.png)

Alternatively, if a run/debug configuration already exists for your application, click ![](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.expui.general.moreVertical.svg) in the run widget and select Add Tunnel for Remote Debug.

3. In the Add Kubernetes Tunnel to Run Configuration window that opens, select a cluster and namespace and click Connect to Cluster. When prompted, enter your administrator account password required to start the Telepresence daemon.

> **Tip:**
> If Telepresence is not installed on your computer or if [Traffic Manager](https://www.getambassador.io/docs/telepresence-oss/latest/install/manager) is not installed in your cluster, a corresponding notification will appear, and IntelliJ IDEA will help you install them.

4. If you are successfully connected to the cluster, configure the intercept parameters:

* In the Service list, select a workload to intercept

* In the Ports field, specify the port on which the local instance of your service is running.

* Optionally specify additional options to the `telepresence intercept` command.

![Add Kubernetes Tunnel to Run Configuration](https://resources.jetbrains.com/help/img/idea/2026.2/telepresence_create_intercept_window.png)

If you want to check the output of the Telepresence commands, expand the Output  section. This section will be automatically expanded if you get any errors while connecting to Telepresence.

5. Click Save Configuration. To check the intercept parameters, IntelliJ IDEA will create an intercept and then leave it.

The intercept parameters are saved as a Add Tunnel for Debug before launch task in a new run configuration. To distinguish it from other run configurations, this run configuration name will include the (Telepresence) suffix, for example, MyApp (Telepresence).

You are now ready to [run your
application and intercept its remote version](#run-application-and-intercept-service).

Procedure: Run the application with interception

1. In the run widget, select a run configuration with the (Telepresence) suffix.

![Run the application with interception](https://resources.jetbrains.com/help/img/idea/2026.2/telepresence_select_run_configuration.png)

2. Click ![](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.expui.gutter.run.svg) to run it or ![](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.expui.run.debug.svg) to start the debugger session.

This will run your local application, and at the same time it will run the `telepresence intercept` command with the parameters specified above.

Telepresence now intercepts all traffic going to a service in your cluster and routes it to your local application. You can locally code and debug your intercepted service.

The Services tool window will show the created intercept under the Telepresence interception node. The root node of your Kubernetes cluster will also display the generated telepresence command and related logs.

![Telepresence Interception in the Services tool window](https://resources.jetbrains.com/help/img/idea/2026.2/telepresence_services_tool_window.png)

When you stop this application (by clicking ![](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.expui.run.stop.svg)), IntelliJ IDEA also stops the intercept (`telepresence leave`).