Telepresence: Desarrollo Remoto en Kubernetes
Telepresence permite desarrollar servicios Kubernetes localmente mientras el resto de los microservicios del clúster permanecen en ejecución, interceptando el tráfico real de red hacia tu máquina. Esta guía cubre la instalación y configuración de Telepresence en Linux, la interceptación de tráfico, la depuración local, y los flujos de trabajo con múltiples clústeres.
Requisitos Previos
kubectlconfigurado con acceso al clúster- Permisos de administrador en el clúster (para instalar el Traffic Manager)
- Linux con privilegios sudo (para el daemon local)
- Los servicios a depurar deben tener al menos una réplica corriendo
# Verificar acceso al clúster
kubectl cluster-info
kubectl auth can-i create deployments --all-namespaces
Instalación de Telepresence
# Instalar Telepresence en Linux (amd64)
sudo curl -fL https://app.getambassador.io/download/tel2/linux/amd64/latest/telepresence \
-o /usr/local/bin/telepresence
sudo chmod +x /usr/local/bin/telepresence
# Verificar la instalación
telepresence version
# Instalar el Traffic Manager en el clúster (requiere permisos de cluster-admin)
telepresence helm install
# Verificar que el Traffic Manager está corriendo
kubectl get pods -n ambassador
El Traffic Manager es un componente que se despliega en el clúster y gestiona las interceptaciones de tráfico.
Conexión al Clúster
# Conectar Telepresence al clúster
telepresence connect
# Verificar el estado de la conexión
telepresence status
# La salida muestra algo similar a:
# Root Daemon: Running
# User Daemon: Running
# Kubernetes context: mi-cluster
# Namespace: default
# Intercepts: 0 total
# Listar los servicios disponibles en el clúster
telepresence list
# Puedes acceder directamente a servicios del clúster por su nombre DNS
curl http://api-backend.default.svc.cluster.local:8080/health
# Desconectarse del clúster
telepresence quit
Interceptación de Tráfico
La interceptación captura el tráfico destinado a un servicio del clúster y lo redirige a tu máquina:
# Interceptar todo el tráfico del servicio api-backend
telepresence intercept api-backend --port 8080
# Esto redirige todas las peticiones al servicio api-backend hacia el puerto 8080 de tu máquina
# Ahora puedes ejecutar el servicio localmente y recibir tráfico real del clúster
# En otra terminal, iniciar el servicio localmente
python3 app.py --port 8080
# o
node server.js
# o
./mi-servicio-go
Interceptación parcial basada en cabeceras HTTP (útil en equipo):
# Interceptar solo las peticiones con una cabecera específica
# El resto del tráfico sigue yendo al servicio del clúster
telepresence intercept api-backend \
--port 8080 \
--http-match "x-desarrollador=marc"
# Con esta configuración:
# - Peticiones con "x-desarrollador: marc" van a tu máquina local
# - El resto del tráfico va al servicio del clúster (sin interrumpir a otros)
# Ver las interceptaciones activas
telepresence list --intercepts
# Cancelar una interceptación específica
telepresence leave api-backend
Interceptación con redirección de múltiples puertos:
# Interceptar un servicio que expone múltiples puertos
telepresence intercept mi-servicio \
--port 8080:http \
--port 9090:metrics \
--env-file /tmp/env-servicio.env # Exportar variables de entorno del pod
Depuración Local de Servicios
Telepresence permite depurar servicios con las herramientas locales mientras el tráfico real del clúster llega a tu debugger:
# Workflow completo de depuración para una aplicación Go
# 1. Conectar Telepresence
telepresence connect
# 2. Obtener las variables de entorno del pod en el clúster
telepresence intercept api-go \
--port 8080 \
--env-file /tmp/api-env.env
# 3. Cargar las variables del pod en el entorno local
source /tmp/api-env.env
# 4. Compilar con información de depuración
go build -gcflags="-N -l" -o api-debug ./cmd/api/
# 5. Iniciar el debugger (Delve)
dlv exec ./api-debug \
--headless \
--listen=:2345 \
--api-version=2
# 6. En tu IDE (VS Code, GoLand), conectar el debugger remoto al puerto 2345
# y poner breakpoints en el código
Depuración de aplicaciones Python:
# Depurar una aplicación Flask/FastAPI
telepresence intercept api-python --port 5000 --env-file /tmp/python-env.env
source /tmp/python-env.env
# Ejecutar con debugger de Python (debugpy)
python3 -m debugpy \
--listen 5678 \
--wait-for-client \
app.py
# Conectar VS Code al puerto 5678 para depuración interactiva
Depuración de aplicaciones Node.js:
# Interceptar el servicio Node.js
telepresence intercept api-node --port 3000 --env-file /tmp/node-env.env
source /tmp/node-env.env
# Iniciar con el inspector de Node.js activado
node --inspect=0.0.0.0:9229 src/index.js
# Abrir Chrome: chrome://inspect y conectar al puerto 9229
Preview URLs y Colaboración
# Crear una Preview URL para que otros puedan ver tus cambios
# (requiere cuenta en Ambassador Cloud)
telepresence intercept api-backend \
--port 8080 \
--preview-url true
# La salida incluirá una URL única como:
# https://abc123.preview.edgestack.me
# Esta URL permite que otros probadores accedan a TU versión local
# sin afectar al entorno de desarrollo compartido
# Compartir la URL con el equipo de QA
echo "Preview disponible en: https://abc123.preview.edgestack.me"
Montaje de Volúmenes Remotos
# Montar el sistema de archivos del pod localmente
telepresence intercept mi-servicio \
--port 8080 \
--mount /tmp/mi-servicio-mount
# Acceder a los archivos del contenedor desde tu sistema local
ls /tmp/mi-servicio-mount/etc/config/
cat /tmp/mi-servicio-mount/app/configuracion.yaml
# Copiar archivos de configuración del pod
cp /tmp/mi-servicio-mount/app/config.yaml ./config-produccion.yaml
# Útil para inspeccionar secretos montados como archivos
ls /tmp/mi-servicio-mount/var/secrets/
Flujos con Múltiples Clústeres
# Ver los contextos de kubectl disponibles
kubectl config get-contexts
# Conectar al clúster de staging
telepresence connect --context mi-cluster-staging
# Cambiar entre clústeres
telepresence quit
telepresence connect --context mi-cluster-produccion
# Configurar namespaces específicos
telepresence connect \
--context mi-cluster \
--namespace equipo-backend
# Verificar a qué clúster estás conectado
telepresence status | grep "Kubernetes context"
Script para gestionar múltiples entornos:
#!/bin/bash
# Función para cambiar de entorno con Telepresence
cambiar_entorno() {
local ENTORNO=${1:-staging}
# Desconectar del entorno actual
telepresence quit 2>/dev/null || true
# Conectar al nuevo entorno
case $ENTORNO in
"dev")
telepresence connect --context kind-desarrollo
;;
"staging")
telepresence connect --context mi-cluster-staging --namespace staging
;;
"prod")
echo "ADVERTENCIA: Conectando a producción. ¿Estás seguro? (s/N)"
read -r confirmacion
if [[ $confirmacion == "s" ]]; then
telepresence connect --context mi-cluster-prod --namespace produccion
fi
;;
*)
echo "Entorno desconocido: $ENTORNO"
exit 1
;;
esac
echo "Conectado al entorno: $ENTORNO"
telepresence status
}
# Uso: cambiar_entorno staging
cambiar_entorno "${1:-staging}"
Solución de Problemas
# Ver el estado detallado de Telepresence
telepresence status --verbose
# Ver los logs del daemon de Telepresence
telepresence log --level debug
# Ver los logs del Traffic Manager en el clúster
kubectl logs -n ambassador -l app=traffic-manager -f
# Reinstalar el Traffic Manager si hay problemas
telepresence helm uninstall
telepresence helm install
# Limpiar conexiones colgadas
telepresence quit --stop-daemons
sudo rm -f /var/run/telepresence-*.sock
# Error "Unable to connect": verificar permisos del clúster
kubectl auth can-i get pods --all-namespaces
# Verificar que el webhook de Telepresence está activo
kubectl get mutatingwebhookconfigurations | grep telepresence
La interceptación no captura el tráfico:
# Verificar que el agente de Telepresence está inyectado en el pod
kubectl describe pod <nombre-pod> | grep -i "traffic-agent"
# Si no está inyectado, reiniciar el deployment para que se inyecte
kubectl rollout restart deployment/api-backend
# Verificar que el servicio tiene los selectores correctos
kubectl describe service api-backend | grep Selector
Conclusión
Telepresence elimina el principal punto de fricción del desarrollo en entornos de microservicios: la necesidad de simular todos los servicios dependientes localmente. Al conectar tu entorno local directamente al clúster real, puedes depurar con tus herramientas habituales usando datos y dependencias auténticos de staging o desarrollo. Las interceptaciones con filtros de cabecera hacen posible el trabajo en equipo sin interferir en el entorno compartido.


