How kt‑connect Simplifies Kubernetes Local Debugging: A Practical Guide

Background

In 2019 the company ran only two Java applications on a single Tomcat container; developers installed MySQL and Tomcat locally, compiled JARs, and manually deployed them to a cloud server.

2020

The team added a CentOS server with MySQL, Tomcat, Redis, RabbitMQ, a separate test environment, and Jenkins for automated builds. Spring MVC and Struts2 were migrated to Spring Boot, eliminating the need for local MySQL installations; developers ran Spring Boot locally and connected directly to the server's MySQL.

2021

Business growth led to a shift from Spring Boot to the Spring Cloud suite and from Linux binaries to Docker images for all middleware. A second backend code branch was created to handle multiple product lines.

2022

Further growth required a third branch, and the architecture moved to Spring Cloud Kubernetes, aligning the runtime with K8s. New branches introduced many POD IPs, making direct access to cluster services from developers' laptops impossible, prompting the search for a proxy tool.

Selection of Proxy Tools

1. Port Forwarding

Using Ingress, NodePort, or LoadBalancer to forward traffic, but this adds operational overhead and does not scale well for dynamic branch environments.

2. VPN

Deploying a VPN pod in each namespace allows laptops to connect, but each namespace consumes a VPN pod’s resources.

3. Telepresence

Telepresence provides VPN‑like access plus traffic interception, allowing a local machine to act as a POD. However, recent versions require registration on the commercial Ambassador Cloud platform, introducing security concerns and extra cleanup steps.

4. kt‑connect

kt‑connect is an open‑source alternative that works without cloud registration and automatically cleans up after use.

Principle

Like Telepresence, kt‑connect creates a temporary pod in the target namespace and deploys a kt‑connect‑shadow image. It offers four modes:

1. Connect Mode

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

This acts as a VPN, granting the laptop access to all services in the specified namespace without exposing the laptop to other cluster traffic.

Note 1: All commands require --kubeconfig with sufficient permissions.

Note 2: If port‑forwarding fails with a “socket operation was attempted to an unreachable host” error, add --excludeIps to avoid routing conflicts, e.g.,

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

This intercepts all traffic to serviceA and forwards it to a local port, enabling direct debugging of the service. The interception is one‑way; local‑initiated requests still need a Connect session.

3. Mesh Mode

ktctl.exe mesh serviceA --kubeconfig .kubeconfig --namespace feature‑N --expose 12001 --debug

Both the cluster service and the local instance respond, but only requests containing a specific HTTP header (e.g., VERSION: xxxx) are routed to the local machine, preserving normal service operation for other users. The header value can be fixed with --versionMark, e.g., --versionMark test‑version.

4. Preview Mode

ktctl.exe preview serviceB --kubeconfig .kubeconfig --namespace feature‑N --expose 12001

This deploys a locally running program as a new Service in the cluster, useful for rapid development and preview of new services.