Kubernetes Telepresence: Remote Debugging und Development ohne Rebuild

TL;DR

• Telepresence erstellt eine bidirektionale Netzwerk-Bridge zwischen lokalem Rechner und Kubernetes-Cluster -- Services im Cluster sind direkt per DNS erreichbar.
• Intercepts leiten Traffic eines Cluster-Services an den lokalen Prozess weiter. Personal Intercepts filtern nach HTTP-Header, sodass andere Entwickler nicht gestoert werden.
• Lokale Prozesse erhalten automatisch die Umgebungsvariablen und Volumes des abgefangenen Pods -- kein manuelles Kopieren noetig.
• IDE-Integration fuer VS Code und IntelliJ ermoeglicht Breakpoint-Debugging direkt gegen Live-Cluster-Traffic.
• Im Vergleich zu Skaffold, Tilt und DevSpace bietet Telepresence den schnellsten Feedback-Loop, weil kein Container-Build noetig ist.

Das Problem: Langsame Inner Development Loops

Der typische Kubernetes-Entwicklungszyklus sieht so aus: Code aendern, Container bauen, Image pushen, Deployment aktualisieren, warten. Bei einem mittelgrossen Java-Service dauert dieser Zyklus 3-8 Minuten. Bei 50 Iterationen pro Tag sind das bis zu 6 Stunden Wartezeit pro Entwickler pro Woche.

Das Kernproblem: Lokale Entwicklung und Cluster-Umgebung sind getrennte Welten. Der Service braucht Zugriff auf Datenbanken, Message-Queues und andere Services im Cluster. Lokal laeuft er entweder gar nicht oder nur mit aufwaendigen Mocks.

Telepresence loest dieses Problem, indem es die lokale Maschine direkt in das Cluster-Netzwerk einbindet. Der lokale Prozess sieht die gleiche Umgebung wie ein Pod im Cluster -- DNS, Services, ConfigMaps, Secrets.

Mehr zum Thema Developer Experience: Kubernetes Developer Experience.

Installation und Setup

# macOS
brew install datawire/blackbird/telepresence-oss

# Linux (amd64)
curl -fL https://app.getambassador.io/download/tel2oss/releases/download/v2.22.0/telepresence-linux-amd64 \
  -o /usr/local/bin/telepresence
chmod +x /usr/local/bin/telepresence

# Version pruefen
telepresence version

# Traffic Manager im Cluster installieren
telepresence helm install

# Verbindung herstellen
telepresence connect

Nach dem connect laeuft ein lokaler Daemon, der:

• DNS-Aufloesung konfiguriert: my-service.production.svc.cluster.local wird vom lokalen Rechner aufgeloest.
• Subnetz-Routing einrichtet: Pod- und Service-CIDRs werden ueber den Cluster geroutet.
• VPN-aehnliche Verbindung zum Cluster aufbaut, ohne dass ein echtes VPN noetig ist.

# Pruefen, ob die Verbindung steht
telepresence status

# DNS-Aufloesung testen
curl http://my-api.default.svc.cluster.local:8080/health

Intercepts: Traffic an den lokalen Prozess leiten

Der Kern-Feature von Telepresence. Ein Intercept leitet eingehenden Traffic eines Cluster-Services an einen lokalen Port weiter.

# Vollstaendiger Intercept: ALLER Traffic wird umgeleitet
telepresence intercept my-api --port 8080:8080 --namespace production

# Lokalen Service starten (z.B. Spring Boot)
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

Was passiert technisch:

1. Telepresence injiziert einen Sidecar-Container in den Ziel-Pod.
2. Der Sidecar leitet eingehenden Traffic ueber den Traffic Manager an den lokalen Rechner.
3. Der lokale Prozess empfaengt die Requests und antwortet direkt.
4. Ausgehende Requests des lokalen Prozesses werden ueber den Cluster geroutet.

Personal Intercepts

In Teams mit mehreren Entwicklern ist ein globaler Intercept problematisch -- aller Traffic landet bei einer Person. Personal Intercepts loesen das:

# Personal Intercept mit Header-Filter
telepresence intercept my-api \
  --port 8080:8080 \
  --namespace production \
  --http-header x-telepresence-id=phillipp

# Nur Requests mit diesem Header werden lokal abgefangen
# Alle anderen Requests gehen weiter an den Cluster-Pod

Fuer das Frontend sendet der Entwickler den Header z.B. per Browser-Extension mit. API-Clients setzen den Header direkt:

# Test mit curl
curl -H "x-telepresence-id: phillipp" \
  http://my-api.production.svc.cluster.local:8080/users

Umgebungsvariablen und Volumes

Telepresence stellt die Umgebung des abgefangenen Pods lokal bereit:

# Umgebungsvariablen des Pods exportieren
telepresence intercept my-api --port 8080 --env-file my-api.env

# Inhalt der .env-Datei
cat my-api.env
# DATABASE_URL=jdbc:postgresql://postgres.production:5432/mydb
# REDIS_HOST=redis-master.production
# KAFKA_BOOTSTRAP_SERVERS=kafka.production:9092
# SECRET_KEY=...

# In der lokalen Shell laden
set -a && source my-api.env && set +a

Volume-Zugriff auf gemountete ConfigMaps und Secrets:

# Intercept mit Volume-Mount
telepresence intercept my-api \
  --port 8080 \
  --namespace production \
  --mount /tmp/telepresence-mounts

# Zugriff auf Pod-Volumes
ls /tmp/telepresence-mounts/var/run/secrets/kubernetes.io/serviceaccount/
# ca.crt  namespace  token

ls /tmp/telepresence-mounts/etc/config/
# application.yaml  feature-flags.json

IDE-Integration: VS Code und IntelliJ

VS Code

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "java",
      "name": "Debug via Telepresence",
      "request": "launch",
      "mainClass": "com.example.MyApplication",
      "envFile": "${workspaceFolder}/my-api.env",
      "args": "--spring.profiles.active=dev"
    }
  ]
}

Workflow:

1. telepresence intercept my-api --port 8080 --env-file my-api.env
2. In VS Code: Debug-Konfiguration starten
3. Breakpoint setzen
4. Request an den Cluster-Service senden -- Breakpoint wird lokal getroffen

IntelliJ IDEA

Run > Edit Configurations > + > Application
  - Main class: com.example.MyApplication
  - Environment variables: Datei my-api.env importieren
  - VM options: -Dserver.port=8080

Die Telepresence VS Code Extension automatisiert den gesamten Workflow: Intercept starten, Env-Datei generieren und Debug-Session konfigurieren -- alles per Klick.

Praxisbeispiel: Microservice-Debugging

Ein konkretes Szenario: Der order-service liefert unter bestimmten Bedingungen falsche Rabattberechnungen. Der Fehler tritt nur auf, wenn der pricing-service und der inventory-service im Cluster antworten.

# Schritt 1: Mit Cluster verbinden
telepresence connect

# Schritt 2: order-service intercepten
telepresence intercept order-service \
  --port 8080:http \
  --namespace production \
  --env-file order-service.env \
  --mount /tmp/tp-mounts

# Schritt 3: Lokal starten mit Cluster-Umgebung
export $(cat order-service.env | xargs)
./gradlew bootRun

# Schritt 4: Request senden, der den Fehler reproduziert
curl -X POST http://order-service.production:8080/orders \
  -H "Content-Type: application/json" \
  -d '{"items": [{"sku": "K8S-101", "quantity": 5}]}'

Der lokale order-service kommuniziert direkt mit pricing-service und inventory-service im Cluster. Breakpoints treffen, Variablen inspizieren, Fix entwickeln -- ohne Container-Build, ohne Push, ohne Deployment-Wartezeit.

Grundlegende Kubernetes-Konzepte fuer Einsteiger: Kubernetes Hands-on Tutorial.

Telepresence in CI/CD-Pipelines

Telepresence eignet sich auch fuer Integrationstests in der CI/CD-Pipeline:

# .github/workflows/integration-test.yaml
name: Integration Tests
on: [pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Telepresence
        run: |
          curl -fL https://app.getambassador.io/download/tel2oss/releases/download/v2.22.0/telepresence-linux-amd64 \
            -o /usr/local/bin/telepresence
          chmod +x /usr/local/bin/telepresence

      - name: Configure kubeconfig
        run: |
          echo "$KUBECONFIG_DATA" | base64 -d > kubeconfig.yaml
          export KUBECONFIG=kubeconfig.yaml

      - name: Connect and test
        run: |
          telepresence connect
          telepresence intercept order-service \
            --port 8080 --namespace staging \
            --http-header x-ci-run=$GITHUB_RUN_ID
          ./gradlew integrationTest
          telepresence leave order-service
          telepresence quit

Fuer umfassende CI/CD-Strategien: Kubernetes CI/CD Enterprise Scale.

Vergleich: Telepresence vs. Skaffold vs. Tilt vs. DevSpace

Empfehlung: Telepresence fuer Debugging und schnelles Iterieren an einzelnen Services. Skaffold oder Tilt fuer die vollstaendige lokale Entwicklung mit mehreren Services, bei der Container-Builds automatisiert werden sollen.

Best Practices

1. Personal Intercepts als Standard: Globale Intercepts in Shared-Umgebungen vermeiden. Header-basiertes Routing stellt sicher, dass andere Entwickler und Tests nicht gestoert werden.

2. Staging statt Production: Intercepts gegen Production-Cluster sind technisch moeglich, aber riskant. Eine Staging-Umgebung mit realistischen Daten ist der bessere Ansatz.

3. Env-Dateien nicht committen: Die generierten .env-Dateien enthalten Secrets aus dem Cluster. In .gitignore aufnehmen:

echo "*.env" >> .gitignore

4. Intercepts nach Gebrauch beenden: Offene Intercepts verbrauchen Cluster-Ressourcen und koennen Traffic-Routing beeinflussen.

# Einzelnen Intercept beenden
telepresence leave my-api

# Alle Verbindungen trennen
telepresence quit

5. Traffic Manager versionieren: Den Traffic Manager per Helm Chart mit fester Version deployen, damit alle Entwickler die gleiche Version nutzen.

Wie Telepresence in eine groessere Plattform-Strategie passt: Kubernetes Platform Engineering.

Troubleshooting

# Ausfuehrliche Logs fuer Debugging
telepresence connect --log-level debug

# Traffic-Manager-Logs im Cluster
kubectl logs -n ambassador deployment/traffic-manager --tail=50

Verwandte Artikel

• Kubernetes Developer Experience
• Kubernetes Hands-on Tutorial: Erste Schritte
• Kubernetes CI/CD Enterprise Scale
• Kubernetes Backstage Developer Portal
• Kubernetes Platform Engineering

Wenn ihr Telepresence in eurem Team einfuehren wollt oder Unterstuetzung beim Aufbau eines effizienten Kubernetes-Development-Workflows braucht, meldet euch unter /kontakt -- wir helfen von der Einrichtung bis zur IDE-Integration.