Telepresence Troubleshooting Guide¶

# Check kubectl connectivity
kubectl cluster-info

# Check current context
kubectl config current-context

# Try with specific context
telepresence connect --context your-context

# Check RBAC permissions
kubectl auth can-i create mutatingwebhookconfigurations

# Check traffic manager status
kubectl get pods -n ambassador

# View logs
kubectl logs -n ambassador deployment/traffic-manager

# Uninstall and reinstall
telepresence uninstall --everything
telepresence connect

# Check for resource constraints
kubectl describe pod -n ambassador -l app=traffic-manager

# Check intercept status
telepresence list
telepresence status

# Verify local service is running
netstat -an | grep 5000
# or
lsof -i :5000

# Check for port conflicts
telepresence intercept backend --port 5001:5000 --namespace telepresence-demo

# View detailed logs
telepresence quit
telepresence loglevel debug
telepresence connect

# Check DNS configuration
telepresence status

# Test DNS resolution
ping dataservice.telepresence-demo.svc.cluster.local

# Try alternative DNS
telepresence quit
telepresence connect --dns=google

# On macOS, reset DNS
sudo killall -HUP mDNSResponder

# Check if running with proper permissions
# On macOS/Linux, might need to run with sudo for the first connection
sudo telepresence connect

# Check cluster admin permissions
kubectl auth can-i '*' '*' --all-namespaces

# Contact cluster admin if lacking permissions

# Find what's using the port
lsof -i :5000

# Kill the process
kill -9 <PID>

# Use a different local port
telepresence intercept backend --port 5001:5000 --namespace telepresence-demo
# Then run your app on port 5001

# Check network connectivity
ping 8.8.8.8

# Restart telepresence
telepresence quit
telepresence connect

# Check cluster health
kubectl get nodes
kubectl top nodes

# Reduce intercept scope
telepresence intercept backend --port 5000 --http-match=auto

# Capture environment to file
telepresence intercept backend \
  --port 5000 \
  --namespace telepresence-demo \
  --env-file=.env.cluster

# Load in your shell
source .env.cluster

# Then run your app
python app.py

# Or use with Docker
telepresence intercept backend \
  --port 5000 \
  --docker-run -- \
  --env-file .env.cluster \
  my-image

# List all intercepts
telepresence list

# Leave specific intercept
telepresence leave backend

# Leave all intercepts
telepresence leave --all

# Use different ports for different services
telepresence intercept backend --port 5000
telepresence intercept frontend --port 3000

# Enable volume mounts with intercept
telepresence intercept backend \
  --port 5000 \
  --mount=true \
  --mount-type=sshfs

# Check mount location
ls ~/telepresence/telepresence-demo/

# Alternative: use docker mode
telepresence intercept backend \
  --port 5000 \
  --docker-run \
  -- \
  -v ~/telepresence/telepresence-demo:/mnt/volumes \
  my-image

# Show detailed status
telepresence status

# Enable debug logging
telepresence loglevel debug

# Show version information
telepresence version

# Show all intercepts across namespaces
telepresence list --all-namespaces

# Test cluster connectivity
telepresence test

# View background daemon logs (macOS)
tail -f ~/Library/Logs/telepresence/*.log

# View background daemon logs (Linux)
journalctl -u telepresence -f