Telepresence Cheat Sheet

Overview

Telepresence is a CNCF project that creates a network bridge between your local development machine and a remote Kubernetes cluster. It allows you to run a service locally while it behaves as if it were running in the cluster, with access to cluster DNS, environment variables, and volumes. This eliminates the build-push-deploy cycle for inner-loop development.

Telepresence works by deploying a traffic manager to your cluster and running a local daemon. It supports intercepting traffic bound for a cluster service and routing it to your local process, allowing you to debug and develop against live cluster services without deploying containers.

Installation

# macOS
brew install datawire/blackbird/telepresence

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

# Windows
winget install datawire.telepresence

# Verify
telepresence version

# Install traffic manager in cluster
telepresence helm install

Core Commands

Command	Description
telepresence connect	Connect to cluster network
telepresence quit	Disconnect from cluster
telepresence status	Show connection status
telepresence list	List interceptable workloads
telepresence intercept <svc>	Intercept a service
telepresence leave <svc>	Stop intercepting
telepresence helm install	Install traffic manager
telepresence helm uninstall	Remove traffic manager
telepresence gather-logs	Collect debug logs
telepresence version	Show version info

Basic Workflow

Connect to Cluster

# Connect to the current kubectl context
telepresence connect

# Connect to specific namespace
telepresence connect --namespace my-namespace

# Check status
telepresence status

# Access cluster services by DNS
curl http://my-service.my-namespace:8080
curl http://postgres.database:5432

# Disconnect
telepresence quit

Intercept a Service

# List available services
telepresence list -n my-namespace

# Intercept a deployment
telepresence intercept my-service --port 8080:8080 -n my-namespace

# Run local service (traffic goes here now)
python app.py  # listening on port 8080

# Stop intercepting
telepresence leave my-service

# Intercept with environment variables
telepresence intercept my-service --port 8080 --env-file=my-service.env
source my-service.env && python app.py

Personal Intercepts (Filtered)

# Intercept only traffic with specific header
telepresence intercept my-service \
  --port 8080 \
  --http-header x-telepresence-id=my-dev-session

# Now only requests with that header reach your local machine
# Other traffic continues to the cluster service

Configuration

Telepresence Config

# ~/.config/telepresence/config.yml
timeouts:
  agentInstall: 120s
  intercept: 30s
  connectivityCheck: 5s

logLevels:
  userDaemon: info
  rootDaemon: info

images:
  registry: docker.io/datawire
  agentImage: ambassador-telepresence-agent:latest

cluster:
  defaultManagerNamespace: ambassador

Traffic Manager Helm Values

# Install with custom values
telepresence helm install \
  --set agent.resources.requests.cpu=50m \
  --set agent.resources.requests.memory=64Mi \
  --set managerRbac.namespaced=true \
  --set managerRbac.namespaces="{default,staging}"

# Upgrade traffic manager
telepresence helm upgrade

Environment Variable Injection

# Save cluster env vars to file
telepresence intercept my-service --port 8080 --env-file=cluster.env

# cluster.env contents:
# DATABASE_URL=postgres://user:pass@postgres.db:5432/mydb
# REDIS_URL=redis://redis.cache:6379
# API_KEY=production-key-xyz

# Use in your local dev
env $(cat cluster.env | xargs) python app.py

# Or source it
set -a && source cluster.env && set +a
python app.py

Advanced Usage

Volume Mounts

# Mount remote volumes locally
telepresence intercept my-service \
  --port 8080 \
  --mount /tmp/telepresence-mounts

# Access mounted volumes
ls /tmp/telepresence-mounts/var/config/
cat /tmp/telepresence-mounts/etc/my-service/config.yaml

# Disable volume mounts
telepresence intercept my-service --port 8080 --mount false

Docker Integration

# Run intercept inside Docker
telepresence intercept my-service --port 8080 --docker-run \
  -- -p 8080:8080 my-local-image:dev

# Use with Docker Compose
telepresence intercept my-service --port 8080 --docker-run \
  -- --network=host my-service:dev

Multi-Service Development

# Connect once, intercept multiple services
telepresence connect

# Intercept frontend
telepresence intercept frontend --port 3000 &

# Intercept backend
telepresence intercept backend --port 8000 &

# Run both locally
cd frontend && npm run dev &
cd backend && python manage.py runserver &

# Leave all intercepts
telepresence leave frontend
telepresence leave backend

CI/CD Testing Against Cluster

# In CI pipeline: connect and run integration tests
telepresence connect
telepresence intercept my-service --port 8080

# Run tests that need cluster services
pytest tests/integration/

# Cleanup
telepresence leave my-service
telepresence quit

Troubleshooting

Issue	Solution
Connection timeout	Check kubectl context and cluster accessibility
Intercept fails	Verify traffic manager is installed: telepresence helm install
DNS not resolving	Check telepresence status for DNS config
Port conflict	Change local port: --port LOCAL:REMOTE
Agent not injected	Check namespace permissions and pod security
Traffic not routing	Verify port mapping matches the service definition

# Full diagnostics
telepresence gather-logs

# Check status
telepresence status

# Verify traffic manager
kubectl get pods -n ambassador | grep traffic-manager

# Check agent sidecar
kubectl get pods -n my-namespace -o jsonpath='{.items[*].spec.containers[*].name}'

# Reset telepresence
telepresence quit
telepresence helm uninstall
telepresence helm install
telepresence connect

# Debug DNS
telepresence status | grep DNS
nslookup my-service.my-namespace