Remote debugging using Telepresence

Last modified: 19 March 2025

Telepresence 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

  1. Open the Services tool window: select View | Tool Windows | Services or press .

  2. Right-click your Kubernetes cluster and select Connect Telepresence. Alternatively, click Telepresence icon 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 is not installed in the cluster, IntelliJ IDEA will prompt you to install it.

    For Windows, follow Telepresence installation documentation.

    Install Traffic Manager

  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.

https://resources.jetbrains.com/help/img/idea/2025.1/kubernetes_connect_telepresence_check.png
Gif

Intercept traffic from 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 (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

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.

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 tool window: select View | Tool Windows | Services or press .

  2. Right-click your Kubernetes cluster and select Quit Telepresence. Alternatively, click Quit Telepresence icon in the toolbar.

Run 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 in your run configuration. Each time you run this run configuration, IntelliJ IDEA creates a Telepresence intercept allowing you to debug your remote application as if it was running locally.

To accomplish this, you should:

  1. Create run a configuration with an intercept.

  2. Run the application using this run configuration.

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

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.

  2. Click 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

    Alternatively, if a run/debug configuration already exists for your application, click 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 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

    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 with interception

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

    Run application with interception

  2. Click to run it or 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 Services tool window

When you stop this application (by clicking ), IntelliJ IDEA also stops the intercept (telepresence leave).