Debug une WebApp comme si elle tournait sur un cluster Kubernetes avec Telepresence

🧠 Mon petit cheminement avant d’adopter Telepresence

Avant de découvrir Telepresence, j’avais fait une veille active sur les outils permettant de développer et déboguer des services Kubernetes en local.

Pendant un moment, il existait une extension dans Visual Studio appelée Bridge to Kubernetes’ - qui permettait justement de faire ce type de debug hybride directement depuis l’IDE.

👉 Cependant, le projet a été officiellement retiré des marketplaces Visual Studio et Visual Studio Code le 30 avril 2025, et le dépôt a été archivé peu après.

C’est via une issue sur GitHub, que je suis tombé sur Telepresence.

J’ai privilégié cet outil en m’apercevant qu’il fait partie de la Cloud Native Computing Foundation, ce qui est un gage - pour moi en tout cas, de sérieux !

Prérequis

• Avoir des connaissances de bases sur K8S
• Avoir kubectl installé et configuré sur la machine.
• Disposer des droits d’accès au cluster K8S et au namespace ciblé.

L’exemple ci-dessous se base sur une WebApp développé en .NET. Mais le principe peut être reproduit avec d’autres plateformes/langage de développements !

Installation

1. Sur votre machine local

Pour commencer, il faut tout d’abord installer le client sur son poste local.

Selon l’OS utilisé, par ici se trouve la documentation à suivre pour l’installer.

2. Sur le cluster ciblé

Une fois le client installé, il faut à présent installer Trafic Manager, qui est l’élément qui va permettre l’interception dans un cluster K8S.

Ayant plusieurs environnements distant, je vais donc d’abord sélectionner celui qui m’intéresse avec une commande Kube:

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

On peut voir que je sélectionne aussi le namespace. C’est opportun de set celui où se trouve l’application qu’on souhaite intercepter. En effet, ça simplifiera les commandes telepresence : pas besoin d’indiquer à chaque fois le namespace où se trouve l’application.

De plus, cela va permettre d’installer le client Telepresence requis sur le serveur, directement dans le bon namespace. Dans le cas contraire, Trafic Manager sera installé sur un namespace dédié.

telepresence helm install

Puis se connecter au cluster via Telepresence :

telepresence connect

⚠️ Si une erreur survient, lors de ces 2 dernières étapes, cela peut être lié aux droits sur le cluster, voir la FAQ, plus bas

Choisir le pod à intercepter

Le workload doit déjà être déployé dans le cluster. Les types supportés par Telepresence sont notamment :

• StatefulSet
• Deployment
• ReplicaSet

Lister les workloads (via kubectl, K9s ou Headlamp) afin d’identifier celui à intercepter.

Exemple :

• StatefulSet ciblé : funeral-orders-api

Récupérer et transformer les variables d’environnement

Objectifs :

• Entrer dans le pod
• Exécuter un script de transformation
• Exporter les variables dans un fichier texte

Commande type :

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

Le fichier envs.txt contiendra toutes les variables nécessaires au bon fonctionnement local.

Intégrer les variables dans launchSettings.json

À ce stade, nous avons récupéré toutes les variables d’environnement du pod distant.
L’objectif est maintenant de recréer localement le même contexte d’exécution que dans K8S.

Autrement dit, faire en sorte que mon application locale :

• se connecte aux mêmes bases
• utilise les mêmes endpoints internes
• charge les mêmes secrets (ou plutôt leurs équivalents en dev)
• et se comporte comme si elle tournait réellement dans le cluster

Il faut donc convertir le format :

CLE=VALEUR

que j’ai sur mon env distant, en format JSON exploitable par Visual Studio/.NET.

Étapes proposées (avec VS Code)

1. Ouvrir envs.txt
2. Échapper les guillemets " si nécessaire (cas de valeurs JSON)
3. Activer le mode Regex
4. Rechercher :

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

1. Remplacer par :

"$1": "$2",

1. Vérifier que le JSON final est valide

Une fois validé, coller les variables dans la section :

"environmentVariables": { }

du profil ciblé dans launchSettings.json.

Conseil : utiliser un profil dédié (ex. PodInterception) afin d’éviter toute confusion lors des commits Git.

Les ports Kestrel doivent correspondre à ceux déclarés lors de l’interception.

Nettoyage des variables

Avant d’exécuter l’application locale, vérifier que certaines variables critiques ne bloquent pas le debug.

Points d’attention :

• COMPlus_EnableDiagnostics / DOTNET_EnableDiagnostics doit être à 1

Intercepter le service

Lancer l’interception :

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

Explications :

• 8080 : port local
• api : port déclaré côté service Kubernetes

Options utiles :

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

Si Telepresence (Traffic Manager) est installé dans un autre namespace, préciser le namespace dans le nom du service.

Vérifier l’interception

Lister les interceptions actives :

telepresence list

Exemple de sortie attendue :

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

Arrêter une interception

Pour revenir à l’état initial :

telepresence leave funeral-orders-api

Attendre quelques minutes que Kubernetes redéploie le pod original.

FAQ

Point d’arrêt sur Visual Studio n’est pas atteint

Vérifier si vous n’avez pas récupérer une variable d’environnement comme

COMPlus_EnableDiagnostics ou DOTNET_EnableDiagnostics. Si c’est le cas, il faut absolument que la valeur soit à 1. 0 impliquera que le debug ne fonctionne pas !

Voir la documentation Microsoft à ce sujet.

Erreur : violates PodSecurity

Message type :

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

Cause :

• L’application Traffic Manager, qui est installé sur le cluster K8S, requiert la capacité NET_ADMIN
• La politique PodSecurity peut être trop restrictive

Solution (exemple, à manier avec précaution) :

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

⚠️ À n’utiliser que sur des environnements de développement. En effet, on peut voir qu’on redéfinit les règles de sécurités : pas très cool !

Sources

• Code and debug an application locally - Telepresence
• Telepresence CLI - commande telepresence intercept
• Enforce Pod Security Standards with Namespace Labels - Kubernetes
• Pod Security Admission - Concepts Kubernetes

---

Article basé sur un retour d’expérience réel en environnement Kubernetes. Les noms de clusters, namespaces et services ont été volontairement simplifiés et anonymisés pour publication.