Docs

Docs

Local Development Mode with Telepresence

Run an application in development mode with Control Center using Telepresence.

Control Center is intended for production environments, where applications rely on cluster-managed resources such as databases and identity providers. For development workflows, replicating these dependencies locally can be challenging.

To enable faster iteration and debugging, Control Center supports local development using Telepresence, an open-source tool that allows running an application on a developer machine while accessing live resources inside a Kubernetes cluster.

How Telepresence Works

Telepresence creates a network proxy between the local machine and the Kubernetes cluster. It intercepts traffic destined for a pod and forwards it to a process running locally. This allows development tools like debuggers, Vaadin Copilot, Spring DevTools, and JRebel, to be used while the application runs against real cluster services.

Warning

Telepresence replaces a pod in the cluster with a local proxy. This can affect services and users depending on that deployment. For this reason, Telepresence should only be used in a local or non-production environment. See Local Environment Setup for more information.

Prerequisites

Before starting, ensure the following:

  • Control Center is installed and running (see Getting Started)

  • The application is deployed as a production build in the cluster (see Application Deployment)

  • Access is available to the cluster where Control Center is running

  • A working local development environment is set up for the application

Installing Telepresence

Telepresence must be installed both locally and in the cluster.

Tip

IntelliJ IDEA has built-in support for installing and configuring Telepresence. This integration simplifies traffic interception and cluster connectivity directly from the IDE. See Remote debugging using Telepresence.

Install the Client Locally

Follow the official instructions for client installation on your platform.

Note

For macOS 10.15 and later, additional configuration may be required due to system security settings. Refer to the macOS troubleshooting guide.

Install the Traffic Manager in the Cluster

To install the cluster-side component (Traffic Manager):

Source code
Terminal
telepresence helm install

More details and configuration options are available at Install/Uninstall the Traffic Manager.

Configuring the Application

Development-specific configuration should be placed in a profile-scoped configuration file to prevent it from leaking into production builds. The following example shows how to scope the properties file to the Spring dev profile.

Source code
application-dev.properties
spring.application.name=my-vaadin-app
spring.main.cloud-platform=kubernetes
spring.cloud.kubernetes.client.namespace=vaadin
application-dev.properties
application-dev.yaml
application-dev.yaml

Replace my-vaadin-app with the actual name of the application and vaadin with the namespace where the application is deployed.

Note

The profile is only active during local development by explicitly enabling it when running the application.

Intercepting Application Traffic

To route cluster traffic to a local instance of the application:

  1. Connect Telepresence to the cluster namespace:

    Source code
    Terminal
    telepresence connect -n vaadin

  2. Intercept the application and forward traffic to the local port (e.g., 8080):

    Source code
    Terminal
    telepresence intercept my-vaadin-app --port 8080

Telepresence replaces the application’s pod with a proxy that redirects requests to the local machine.

Running in Development Mode

With interception in place, the application can be launched locally from the IDE or terminal. Development tools such as debuggers or live reload function normally while the application connects to live services in the cluster.

Use the appropriate command depending on the build tool:

Source code
Terminal
./gradlew bootRun --args='--spring.profiles.active=dev'
Terminal
Terminal
Terminal
Tip

In IntelliJ IDEA and other IDEs, the active profile can be set in the Run/Debug Configuration for the application. Open the run configuration, locate the Spring Boot section, and enter dev in the Active profiles field. This automatically enables the development-specific configuration when running from the IDE.

Cleaning Up

To restore the cluster state and remove the local proxy:

  1. Leave the interception:

    Source code
    Terminal
    telepresence leave my-vaadin-app

  2. Disconnect from the cluster:

    Source code
    Terminal
    telepresence quit

These steps restore the original deployment and prevent traffic from being redirected.

Troubleshooting and Resources

For help with common issues, see the official Telepresence documentation: