Debug a WebApp as if it were running in a Kubernetes cluster with Telepresence

🧠 My path before adopting Telepresence

Before discovering Telepresence, I had been actively surveying tools to develop and debug Kubernetes services locally.

For a while, there was a Visual Studio extension called Bridge to Kubernetes that enabled this kind of hybrid debugging directly from the IDE.

👉 However, the project was officially removed from the Visual Studio and VS Code marketplaces on April 30, 2025, and the repository was archived shortly after.

It was through a GitHub issue that I discovered Telepresence.

I favored this tool after noticing it is part of the Cloud Native Computing Foundation, which for me is a strong signal of maturity and seriousness.

Prerequisites

• Basic Kubernetes knowledge
• kubectl installed and configured locally
• Access rights to the target Kubernetes cluster and namespace

The example below uses a .NET WebApp, but the same principle applies to other stacks/languages.

Installation

1. On your local machine

First, install the client locally.

Follow the official instructions depending on your OS: https://telepresence.io/docs/install/client

2. On the target cluster

Once the client is installed, install the Traffic Manager, which enables interception in the Kubernetes cluster.

Since I have multiple remote environments, I first select the target context:

kubectl config use-context AKS-FUNERAL-DEV --namespace=funeral-saas-dev

I also set the namespace where the target application runs. This simplifies Telepresence commands (no need to pass the namespace each time).

It also ensures the Telepresence server-side components are installed in the correct namespace. Otherwise, Traffic Manager is installed in its own namespace.

telepresence helm install

Then connect:

telepresence connect

⚠️ If errors occur during these steps, it is often due to insufficient cluster permissions (see FAQ below).

Choose the pod to intercept

The workload must already be deployed in the cluster. Supported types include:

• StatefulSet
• Deployment
• ReplicaSet

List workloads (via kubectl, K9s, or Headlamp) to identify the target.

Example:

• Target StatefulSet: funeral-orders-api

Retrieve and transform environment variables

Goals:

• Enter the pod
• Run a transformation script
• Export variables to a file

Example command:

kubectl exec -n funeral-saas-dev funeral-orders-api-0 -it -- /bin/bash \
  ./s/entrypoint.sh printenv > envs.txt

The envs.txt file will contain all variables required for local execution.

Inject variables into launchSettings.json

At this point, we have the environment variables from the remote pod. The goal is to recreate locally the same runtime context as in Kubernetes.

In other words, make the local app:

• connect to the same databases
• use the same internal endpoints
• load the same secrets (or dev equivalents)
• behave as if it were running in the cluster

We need to convert:

KEY=VALUE

into JSON usable by Visual Studio/.NET.

Suggested steps (with VS Code)

1. Open envs.txt
2. Escape " if needed (for JSON values)
3. Enable Regex mode
4. Find:

^(\w+)=(.*)$

1. Replace with:

"$1": "$2",

1. Validate the resulting JSON

Then paste into:

"environmentVariables": { }

inside the target profile in launchSettings.json.

Tip: use a dedicated profile (e.g., PodInterception) to avoid Git confusion.

Kestrel ports must match those declared in the interception.

Clean up variables

Before running locally, ensure critical variables don’t block debugging.

Important:

• COMPlus_EnableDiagnostics / DOTNET_EnableDiagnostics must be 1

Intercept the service

Start interception:

telepresence intercept funeral-orders-api --port 8080:api

Explanation:

• 8080: local port
• api: port declared on the Kubernetes service

Useful options:

--env-file example-app-intercept.env --env-syntax json

If Traffic Manager is installed in another namespace, specify it in the service name.

Verify interception

List active interceptions:

telepresence list

Expected output:

• state: ACTIVE
• workload: StatefulSet
• redirection: 10.x.x.x -> 127.0.0.1:8080

Stop interception

Return to normal:

telepresence leave funeral-orders-api

Wait a few minutes for Kubernetes to restore the original pod.

FAQ

Breakpoints not hit in Visual Studio

Check if you imported environment variables like:

COMPlus_EnableDiagnostics or DOTNET_EnableDiagnostics.

They must be set to 1. If 0, debugging will not work.

See Microsoft docs: https://learn.microsoft.com/en-us/dotnet/core/runtime-config/debugging-profiling#enable-diagnostics

Error: violates PodSecurity

Example message:

pods "funeral-orders-api" is forbidden: violates PodSecurity "baseline:latest"

Cause:

• Traffic Manager requires NET_ADMIN
• PodSecurity policy may be too restrictive

Workaround (use carefully):

kubectl get ns funeral-saas-dev --show-labels
kubectl label ns funeral-saas-dev pod-security.kubernetes.io/enforce=privileged --overwrite

⚠️ Development environments only — this weakens security constraints.

Sources

• https://telepresence.io/docs/howtos/engage
• https://telepresence.io/docs/reference/cli/telepresence_intercept
• https://kubernetes.io/docs/tasks/configure-pod-container/enforce-standards-namespace-labels
• https://kubernetes.io/docs/concepts/security/pod-security-admission

---

Article based on real Kubernetes experience. Cluster, namespace, and service names were simplified/anonymized for publication.