Telepresence conecta tu equipo de desarrollo a la red de un clúster Kubernetes: desde tu máquina puedes llamar a los servicios del clúster por su nombre DNS y, además, desviar hacia tu equipo el tráfico que recibe un workload del clúster. Así ejecutas y depuras un servicio en local mientras el resto de microservicios sigue corriendo en el clúster. En este tutorial instalarás Telepresence en Ubuntu 24.04, desplegarás su Traffic Manager, interceptarás un servicio de ejemplo y verás cómo usar las variables de entorno y los volúmenes del pod en tu proceso local.

Requisitos previos

Para seguir esta guía necesitas:

  • Una estación de trabajo con Ubuntu 24.04 (x86_64) y un usuario con privilegios sudo. El daemon local de Telepresence necesita sudo para crear la interfaz de red virtual y configurar el DNS.
  • kubectl instalado y un kubeconfig que apunte a un clúster Kubernetes de desarrollo o staging (por ejemplo, un clúster Kubernetes gestionado de CubePath).
  • Permisos para instalar recursos a nivel de clúster (el Traffic Manager crea un namespace, RBAC y un webhook de admisión). Normalmente esto implica el rol cluster-admin la primera vez.
  • Python 3, que ya viene con Ubuntu, para el servicio local de ejemplo.

Comprueba el acceso al clúster antes de empezar:

kubectl cluster-info
kubectl auth can-i create namespaces

Kubernetes control plane is running at https://your_cluster_endpoint:6443
yes

Paso 1: Instalar el cliente de Telepresence

Telepresence es un proyecto de código abierto (CNCF) que publica un binario estático por plataforma en GitHub. Descarga la última versión para Linux x86_64 en /usr/local/bin:

sudo curl -fL https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-linux-amd64 -o /usr/local/bin/telepresence
sudo chmod a+x /usr/local/bin/telepresence

Si tu equipo es arm64, cambia telepresence-linux-amd64 por telepresence-linux-arm64.

Instala también sshfs, que Telepresence usa para montar en tu equipo los volúmenes del pod interceptado (lo verás en el paso 6):

sudo apt update
sudo apt install sshfs

Comprueba la versión del cliente:

telepresence version

OSS Client : v2.x.y
Root Daemon: not running
User Daemon: not running

Paso 2: Instalar el Traffic Manager en el clúster

El Traffic Manager es el componente de Telepresence que vive dentro del clúster. Coordina las conexiones de los clientes e inyecta un contenedor sidecar (el Traffic Agent) en los pods que interceptes. El cliente incluye su propio chart de Helm, así que no necesitas instalar Helm aparte:

telepresence helm install

Traffic Manager installed successfully

Por defecto se instala en el namespace ambassador. Comprueba que el pod está en ejecución:

kubectl get pods -n ambassador

NAME                               READY   STATUS    RESTARTS   AGE
traffic-manager-6c9d8b7f5d-4kx2p   1/1     Running   0          40s

Cuando actualices el cliente a una versión nueva, actualiza también el Traffic Manager para que ambos coincidan:

telepresence helm upgrade

Paso 3: Desplegar un servicio de ejemplo

Para tener algo que interceptar, despliega un servidor web sencillo en el namespace default y exponlo con un Service en el puerto 80:

kubectl create deployment hello --image=nginxdemos/hello:plain-text --port=80
kubectl expose deployment hello --port=80 --target-port=80
kubectl rollout status deployment/hello

deployment "hello" successfully rolled out

Este contenedor responde con texto plano que incluye el nombre del pod, lo que hace fácil ver si la respuesta viene del clúster o de tu equipo.

Paso 4: Conectar tu equipo al clúster

telepresence connect arranca los daemons locales (te pedirá la contraseña de sudo), crea una interfaz de red virtual y configura el DNS para que los nombres del clúster resuelvan desde tu máquina. Indica el namespace en el que vas a trabajar:

telepresence connect --namespace default

Launching Telepresence User Daemon
Launching Telepresence Root Daemon
Connected to context your_context, namespace default (https://your_cluster_endpoint:6443)

Comprueba el estado de la conexión:

telepresence status

La salida muestra el Root Daemon y el User Daemon en ejecución, el contexto de Kubernetes y el namespace conectados.

Ahora puedes llamar al Service directamente por su nombre, igual que lo haría otro pod del namespace:

curl http://hello.default

Server address: 10.244.1.23:80
Server name: hello-7d9c6b8f4-xq2lm
Date: 25/Sep/2026:10:12:44 +0000
URI: /
Request ID: 5f0c...

Lista los workloads que se pueden interceptar en el namespace:

telepresence list

hello: ready to engage (traffic-agent not yet installed)

Paso 5: Interceptar el tráfico del servicio

Una intercepción redirige a tu equipo el tráfico que llega al puerto del workload en el clúster. Primero arranca en local el proceso que va a recibir ese tráfico. En este ejemplo, un servidor HTTP de Python en el puerto 8080 que sirve un archivo propio:

mkdir -p ~/hello-local && cd ~/hello-local
echo "Respuesta desde mi equipo local" > index.html
python3 -m http.server 8080

Deja ese proceso en marcha y, en otra terminal, crea la intercepción. La sintaxis de --port es puerto_local:puerto_del_servicio:

telepresence intercept hello --port 8080:80

Using Deployment hello
   Intercept name    : hello
   State             : ACTIVE
   Workload kind     : Deployment
   Destination       : 127.0.0.1:8080
   Service Port Identifier: 80/TCP
   Intercepting      : all TCP requests

La primera vez, Telepresence inyecta el Traffic Agent en el pod, por lo que el deployment se reinicia. Repite la petición al Service:

curl http://hello.default

Respuesta desde mi equipo local

El tráfico que otros pods del clúster envían a hello llega ahora a tu proceso local, y en la terminal del servidor de Python verás las peticiones. Consulta las intercepciones activas con:

telepresence list --intercepts

Para terminar la intercepción y devolver el tráfico al pod original:

telepresence leave hello

Tras leave, curl http://hello.default vuelve a responder con el nombre del pod.

Paso 6: Usar el entorno y los volúmenes del pod

Un servicio real suele necesitar las mismas variables de entorno (URLs de bases de datos, claves de otros servicios) y archivos montados que tiene en el clúster. Telepresence puede exportar el entorno del contenedor interceptado a un archivo y montar sus volúmenes en tu equipo:

telepresence intercept hello --port 8080:80 \
  --env-file ~/hello-local/hello.env \
  --mount ~/hello-local/pod-fs

El archivo hello.env contiene líneas CLAVE=valor con las variables del contenedor. Cárgalo en la shell desde la que arrancas tu servicio con set -a para que se exporten:

set -a
source ~/hello-local/hello.env
set +a
env | grep HELLO_SERVICE

HELLO_SERVICE_HOST=10.96.143.20
HELLO_SERVICE_PORT=80

Los volúmenes del pod (ConfigMaps, Secrets, tokens de la cuenta de servicio) quedan disponibles bajo el directorio de montaje:

ls ~/hello-local/pod-fs/var/run/secrets/kubernetes.io/serviceaccount

ca.crt  namespace  token

Si tu código lee rutas absolutas como /var/run/secrets/..., configura la ruta base mediante una variable de entorno para poder apuntarla al montaje en local.

Paso 7: Depurar el servicio con tu IDE

Como el proceso interceptado corre en tu máquina, puedes usar cualquier depurador. Con una aplicación Python (Flask, FastAPI, etc.), por ejemplo, instala debugpy en el entorno virtual del proyecto y arranca la aplicación esperando a que se conecte el IDE:

python3 -m venv .venv
source .venv/bin/activate
pip install debugpy
python -m debugpy --listen 127.0.0.1:5678 --wait-for-client app.py

En VS Code, crea una configuración de tipo "Python Debugger: Attach" contra 127.0.0.1:5678, pon un breakpoint y lanza una petición al Service desde el clúster o con curl. La ejecución se detendrá en tu código con la petición real.

El mismo patrón sirve para otros lenguajes: node --inspect=127.0.0.1:9229 server.js para Node.js o dlv debug --headless --listen=127.0.0.1:2345 ./cmd/api para Go con Delve. Lo único que importa es que el proceso escuche en el puerto local que pasaste a --port.

Paso 8: Trabajar con varios clústeres o namespaces

Telepresence usa el contexto actual de kubectl, pero puedes elegir otro al conectar. Para cambiar de clúster, desconecta primero:

telepresence quit
kubectl config get-contexts
telepresence connect --context your_staging_context --namespace your_namespace

Comprueba siempre a qué contexto y namespace estás conectado antes de interceptar:

telepresence status

Cuando termines la sesión de trabajo, detén también los daemons locales para restaurar la configuración de red y DNS de tu equipo:

telepresence quit -s

Solución de problemas

telepresence connect falla con un error de versión del Traffic Manager. El cliente y el Traffic Manager deben tener versiones compatibles. Ejecuta telepresence version y, si difieren, telepresence helm upgrade.

La intercepción se queda en estado de espera o falla al inyectar el agente. Revisa que el webhook de admisión existe y los logs del Traffic Manager:

kubectl get mutatingwebhookconfigurations | grep agent-injector
kubectl logs -n ambassador deploy/traffic-manager --tail=50

Comprueba también que el Service selecciona el deployment que intentas interceptar:

kubectl get endpoints hello

Los nombres del clúster no resuelven en local. Asegúrate de estar conectado (telepresence status) y usa el nombre con namespace (servicio.namespace). Si tu equipo usa una VPN que también modifica el DNS, desconéctala para descartar conflictos.

Recoger logs para un informe. telepresence gather-logs empaqueta en un zip los logs de los daemons locales y del clúster.

Conclusión

Has instalado Telepresence, desplegado el Traffic Manager y redirigido a tu equipo el tráfico de un servicio del clúster, con acceso a sus variables de entorno y volúmenes para ejecutarlo y depurarlo en local. Como siguientes pasos, puedes limpiar el ejemplo con kubectl delete deployment,service hello, restringir con RBAC qué usuarios pueden interceptar workloads y documentar en cada repositorio el comando telepresence intercept exacto que necesita el servicio.