Docs

Docs

Local Development Mode with Telepresence

Running an Application in Development Mode with Control Center.

Control Center is designed to run applications in a production environment, providing access to all necessary cluster resources such as databases and identity providers. However, testing new code often requires access to these resources. This can be challenging to replicate locally.

To streamline the development process, you can use Telepresence, an open-source tool for running an application in development mode on a local machine, while seamlessly accessing cluster resources.

This guide explains how to set up Telepresence to intercept traffic from your cluster and forward it to your local development environment. By doing so, you can use development tools like debuggers, Spring DevTools, JRebel, and Vaadin Copilot while your application interacts with real cluster resources.

Understanding Telepresence

Telepresence creates a bidirectional network proxy between your local machine and the Kubernetes cluster. It intercepts traffic intended for your application’s pod and redirects it to your local development environment.

This use of Telepresence allows you to run your application locally, while it communicates with other services in the cluster as if it were running inside the cluster. It also lets you use local development tools to debug and hot-reload your application — while avoiding the overhead of building and deploying your application to the cluster after every change.

Warning
Don’t Use Telepresence In Production
Telepresence modifies the network behavior of your cluster by replacing your application’s deployment with a proxy. This can affect other users and services in the cluster. Therefore, use Telepresence with a local or development cluster, not with a production cluster.

Prerequisites

To run an application in development mode locally with Control Center, there are a few requirements. The first and most obvious one is that Control Center should be running (see Getting Started). Also, your application needs to be deployed as a production build in the cluster (see Application Deployment).

Make sure you have access to the cluster where Control Center is running. Finally, a local development environment should be set up for your application.

Local Cluster

For development purposes, it’s advisable to use a local Kubernetes cluster to prevent any unintended side effects on a production environment. You can set up a local cluster using tools like these:

These tools allow you to run a Kubernetes cluster on your local machine, providing a safe environment for testing and development.

Installing Telepresence

Telepresence needs to be installed both locally and in your cluster. The next sections provide information on how to do both.

Install Locally

Follow the official Telepresence installation guide to install Telepresence on your development machine.

On macOS, starting with version 10.15 (i.e., Catalina), additional configuration might be required due to increased security restrictions. Refer to the Telepresence macOS troubleshooting guide for detailed instructions.

Install in the Cluster

Install the Telepresence Traffic Manager in your cluster using Helm like this:

telepresence helm install

For detailed installation options, refer to the Telepresence Traffic Manager documentation.

Preparing Application

To ensure your application can access cluster resources while running locally, you’ll need to update your application’s configuration.

Create or modify the application.properties (or application.yaml) file in src/main/resources/ with the following content:

spring.application.name=my-vaadin-app
spring.main.cloud-platform=KUBERNETES
spring.cloud.kubernetes.client.namespace=control-center

Replace 'my-vaadin-app' with the actual name of your application and 'control-center' with the namespace where Control Center is deployed.

The spring.cloud.kubernetes.client.namespace property specifies the namespace for Kubernetes client interactions. Setting spring.main.cloud-platform to 'KUBERNETES' enables Kubernetes-specific features in Spring.

Intercepting Traffic

To intercept cluster traffic and redirect it to your local application, connect Telepresence to the control-center namespace like so:

telepresence connect -n control-center

You can then intercept your application’s traffic and map it to port 8080 on your local machine like this:

telepresence intercept my-vaadin-app --port 8080

Telepresence replaces your application’s deployment in the cluster with a proxy that redirects traffic to your local machine. Your application should now interact with cluster resources as if it were running inside the cluster.

Using Development Tools

With Telepresence installed and configured, you can now run your application from your IDE and leverage development tools such as debuggers, Spring DevTools, JRebel, and Vaadin Copilot.

This setup allows for rapid development and testing against real cluster resources without the overhead of deploying to the cluster after every change.

Cleaning Up

After you’ve finished testing, it’s important to restore the cluster to its original state. Always clean Telepresence sessions to avoid unintended traffic redirection and to restore your application’s deployment in the cluster.

First, leave the interception, which stops redirecting traffic:

telepresence leave my-vaadin-app

Next, quit Telepresence and thereby disconnect from the cluster:

telepresence quit

Troubleshooting & More Resources

As mentioned earlier, using Telepresence in a production cluster can disrupt services if not managed carefully. Therefore, use a dedicated development or staging cluster to avoid impacting production workloads.

If you encounter issues with Telepresence, refer to the Telepresence Troubleshooting Guide for solutions to common problems.

For macOS users, especially for the latest versions, additional network and security configurations may be necessary. See the macOS-specific troubleshooting section for guidance.

Below is a list of additional resources you may find helpful: