Why kt-connect Beats Telepresence for Kubernetes Local Debugging

Background

Note: The background is a bit verbose; feel free to skip if you just want the core content.

2019

The company only had two Java applications running on a single Tomcat servlet container. Developers installed MySQL and Tomcat locally, debugging on their own machines, while the app team connected directly to the developers' laptops. Deployment meant manually copying a JAR to a cloud server.

Local debugging involved each developer running MySQL and Tomcat on their PC, allowing independent backend changes and direct app‑to‑backend connections.

2020

The team added a CentOS server with MySQL, Tomcat, Redis, RabbitMQ, a dedicated test environment, and Jenkins for automated builds. Spring MVC and Struts2 migrated to Spring Boot, removing the external Tomcat. Developers now ran Spring Boot locally, connecting to the server's MySQL, while the app team used stable endpoints.

2021

Business growth led to Spring Cloud and Dockerizing all middleware. A second backend branch was created, adding more development and test environments. Developers now needed to run a local Eureka and Config Server, and memory became a bottleneck when many microservices were involved.

2022

Further growth required a third branch and a shift from Zuul/Eureka to Spring Cloud Kubernetes, moving the entire runtime to K8s. New PODs received unique IPs, making it impossible for developers to directly connect to middleware ports, increasing operational overhead.

To address this, the kt‑connect tool was introduced, allowing developers to proxy access to all services in a Kubernetes namespace and start only the services they need, greatly reducing CPU and memory usage on their laptops.

Selection

Several approaches exist for proxying access to K8s environments:

1. Port Forwarding

Using Ingress, NodePort, or LoadBalancer to forward traffic. This increases operational workload and is unsuitable for many dynamic branches.

2. VPN

Deploy a VPN pod in each namespace; developers connect via a VPN client. This works but consumes resources for a constantly running VPN service per namespace.

3. Telepresence

Telepresence provides VPN‑like access and can intercept traffic to route it to the local machine, acting as a sidecar. However, version 2.5 requires registration on the commercial Ambassador Cloud, introduces security concerns, and leaves residual resources after use.

Typical Telepresence commands:

telepresence helm install --kubeconfig .\kubeconfig telepresence connect ---kubeconfig .\kubeconfig

Telepresence injects a traffic‑manager pod and runs two daemons on the developer's laptop to establish a bidirectional proxy.

4. kt‑connect

kt‑connect is an open‑source alternative that requires no cloud login, automatically cleans up resources after exit, and is provided by Alibaba. It satisfies the team's needs.

Principle

kt‑connect operates similarly to Telepresence but creates a dedicated pod (kt‑connect‑shadow) only in the selected namespace. It offers four modes:

1. Connect Mode

ktctl.exe connect --kubeconfig .\kubeconfig --namespace feature-N --debug

Acts like a VPN, granting the local machine access to all services in the namespace without affecting other services.

Note: All commands must include --kubeconfig to ensure proper permissions.

Failed to setup port forward local:28344 -> pod kt‑connect‑shadow-gseak:53 error="error upgrading connection: ..."

If routing conflicts occur, exclude the conflicting IP range:

ktctl.exe connect --kubeconfig .\kubeconfig --namespace feature-N --excludeIps 10.0.8.101/32 --debug

2. Exchange Mode

ktctl.exe exchange serviceA --kubeconfig .\kubeconfig --namespace feature-N --expose 12001 --debug

Intercepts all traffic to a specific service and forwards it to a local port, replacing the original pod with a serviceA-kt-exchange pod.

Note: Exchange traffic is one‑way; local‑initiated requests are not proxied unless Connect mode is also running.

Note: If the cluster routes directly to pods (bypassing services), interception may fail.

3. Mesh Mode

kctl.exe mesh serviceA --kubeconfig .\kubeconfig --namespace feature-N --expose 12001 --debug

Both the cluster service and the local service respond, but only requests containing a specific HTTP header (e.g., VERSION: xxxxx) are routed to the local machine. The header can be fixed with --versionMark:

kctl.exe mesh serviceA --kubeconfig .\kubeconfig --namespace feature-N --expose 12001 --debug --versionMark test-version

This mode replaces the original pod with a serviceA-kt-router sidecar that handles header‑based routing.

4. Preview Mode

kctl.exe preview serviceB --kubeconfig .\kubeconfig --namespace feature-N --expose 12001

Deploys a locally running program as a new service in the cluster, useful for developing and previewing new services.