Utiliser "Bridge to Kubernetes" (VS Code)

Remarque

Bridge to Kubernetes sera mis hors service le 30 avril 2025. Pour plus d’informations sur la mise hors service et les alternatives open source, consultez le problème GitHub.

Bridge to Kubernetes vous permet d’exécuter et de déboguer du code sur votre ordinateur de développement, tout en restant connecté à votre cluster Kubernetes avec le reste de votre application ou services. Dans ce guide, vous allez apprendre à utiliser Bridge to Kubernetes pour rediriger le trafic entre votre cluster Kubernetes et le code s’exécutant sur votre ordinateur de développement.

Avant de commencer

Cet article suppose que vous disposez déjà de votre propre cluster avec une architecture de microservices et que vous souhaitez déboguer l’un des pods de votre cluster. Si vous souhaitez apprendre à utiliser Bridge to Kubernetes avec un exemple d’application existant, consultez Utiliser Bridge to Kubernetes avec un exemple de. Si vous utilisez Azure Kubernetes service et souhaitez utiliser un exemple d’application plus complexe, consultez Bridge to Kubernetes (AKS).

Conditions préalables

• Un cluster Kubernetes avec une application que vous souhaitez déboguer.
• Visual Studio Code s’exécutant sur macOS, Windows 10 ou version ultérieure ou Linux.

Se connecter à votre cluster et déboguer un service

Il existe plusieurs façons de démarrer le processus de débogage avec Bridge to Kubernetes. Si vous démarrez à partir de l’extension Kubernetes open source, sans Bridge to Kubernetes installé, accédez à Installer et utiliser le débogage du tunnel local. Si vous avez déjà installé Bridge to Kubernetes, suivez les étapes suivantes :

1. Sur votre ordinateur de développement, vérifiez que votre contexte actuel est défini sur le cluster et l’espace de noms dans lequel votre application s’exécute.

2. Ouvrez l’espace de travail de l’application que vous souhaitez déboguer dans Visual Studio Code. Dans la vue d’extension Kubernetes sous Clusters, vérifiez que votre cluster et votre espace de noms sont sélectionnés. Ouvrez la palette de commandes (Ctrl+MAJ+P ou Cmd+Maj+P sur un Mac), puis exécutez la commande Bridge to Kubernetes : Configurez pour démarrer le processus de configuration.

3. Choisissez le service Kubernetes que vous souhaitez rediriger vers votre version locale.

   

   Tout le trafic dans le cluster Kubernetes est redirigé pour votre service vers la version de votre application s’exécutant sur votre ordinateur de développement. Pont vers Kubernetes achemine également tout le trafic sortant de l’application vers votre cluster Kubernetes.

   Important

   Vous ne pouvez rediriger les services qui ont qu’un seul pod.

4. Après avoir sélectionné votre service, ignorez la section suivante et poursuivez en suivant les étapes décrites dans Configurer le débogueur pour le débogage du tunnel local avec Bridge to Kubernetes.

Installer et utiliser le débogage du tunnel local

Suivez ces étapes pour commencer à utiliser le débogage de tunnel local lorsque vous disposez de l’extension Open Source Kubernetes installée et que vous disposez d’un cluster Kubernetes avec des services que vous souhaitez déboguer. Les étapes décrites dans cette section vous guident dans l’installation de Bridge to Kubernetes et initient le processus de configuration pour le débogage de tunnel local.

Note

L’extension Kubernetes pour VS Code fournit un point d’entrée d’API qui permet aux auteurs d’extensions de contribuer à d’autres solutions de tunnel local à partir de la Place de marché VS Code. Bridge to Kubernetes est une implémentation possible de la fonctionnalité de débogage du tunnel local.

Il existe deux façons de commencer à utiliser le débogage du tunnel local dans VS Code. La première méthode consiste à ouvrir la palette de commandes (Ctrl+Maj+P ou Cmd+Maj+P sur un Mac) et à taper Kubernetes : Débogage (tunnel local).

Capture d’écran

Vous pouvez également accéder à votre explorateur de clusters Kubernetes. Ouvrez les ressources du cluster actif et recherchez un service ou un pod que vous souhaitez déboguer, puis cliquez avec le bouton droit sur le service, puis sélectionnez Déboguer : Tunnel local.

À ce stade, si vous n’avez pas d’extension VS Code installée qui offre des fonctionnalités de débogage locales, vous êtes redirigé vers la Place de marché pour sélectionner une extension qui fournit le débogage local. Sélectionnez l’extension Bridge to Kubernetes.

Capture d'écran

Une fois l’extension Bridge to Kubernetes installée, la prochaine fois que vous choisissez Debug : Local Tunnel, vous ignorez l’étape d’installation et passez directement à l’étape suivante, Configurer le débogueur pour le débogage de tunnel local avec Bridge to Kubernetes.

Configurer le débogueur pour le débogage du tunnel local avec Bridge to Kubernetes

La première étape de la configuration du débogueur pour le débogage de tunnel local est que vous êtes invité à entrer le port TCP utilisé par votre application pour s’exécuter localement :

Choisissez une configuration de lancement de débogage que vous utilisez normalement lors de l’exécution locale de votre application. Si vous n’avez pas de configuration de lancement, vous pouvez laisser Bridge to Kubernetes en créer un ou choisir de ne pas en créer un, auquel cas vous devez démarrer votre application ou votre service manuellement. Pour en savoir plus, consultez les configurations de lancement .

Vous avez la possibilité d’exécuter en mode isolé ou non isolé. Si vous exécutez isolé, seules vos demandes sont acheminées vers votre processus local ; d’autres développeurs peuvent utiliser le cluster sans être affectés. Si vous n’exécutez pas en mode isolé, tout le trafic sera redirigé vers votre processus local. Pour plus d’informations sur cette option, consultez Utilisation des fonctionnalités de routage pour le développement en isolation.

Sélectionnez l’icône Déboguer à gauche et sélectionnez la configuration de lancement Kubernetes nouvellement ajoutée, par exemple Lancer via NPM avec Kubernetes, en haut. Cette configuration de lancement est créée par Bridge to Kubernetes, si vous choisissez cette option.

Remarque

Vous serez invité à autoriser l'EndpointManager à exécuter avec élévation de privilèges et à modifier votre fichier hosts.

Votre ordinateur de développement est connecté lorsque la barre d’état VS Code devient orange et que l’extension Kubernetes indique que vous êtes connecté.

Une fois que votre ordinateur de développement est connecté, le trafic commence à rediriger vers votre ordinateur de développement pour le service que vous remplacez.

Note

Lors des lancements suivants, vous ne serez pas invité à entrer le nom du service, le port, la tâche de lancement ou s’il doit s’exécuter isolé. Ces valeurs sont enregistrées dans .vscode/tasks.json. Pour modifier ces paramètres ultérieurement, ouvrez la palette de commandes (Ctrl+MAJ+P ou Cmd+Maj+P sur un Mac) et exécutez la commande Bridge to Kubernetes : Configure. Vous pouvez ouvrir .vscode/launch.json et .vscode/tasks.json pour afficher les paramètres de configuration spécifiques que Bridge to Kubernetes ajoute à votre profil de lancement.

Si votre cluster utilise gRPC C core, une implémentation de gRPC qui utilise c-ares, une variable d'environnement, GRPC_DNS_RESOLVER, est ajoutée à votre profil de lancement avec la valeur native. Cette variable spécifie d’utiliser une solution de contournement pour éviter un délai de 2 minutes lors de la connexion. Pour plus d’informations, consultez ce problème gRPC.

Définir un point d’arrêt

Définissez un point d’arrêt avec F9 ou sélectionnez Exécuter, puis Basculer le point d’arrêt.

Accédez à l’exemple d’application en ouvrant l’URL publique. Lorsque votre code atteint le point d’arrêt, il doit s’ouvrir dans le débogueur. Pour reprendre le service, appuyez sur Ctrl+F5 ou sélectionnez Exécuter, puis Continuer. Revenez à votre navigateur et vérifiez que vous voyez une image d’espace réservé pour le vélo.

Mettre à jour votre application

Lorsque vous modifiez le code localement, leur visibilité par d'autres utilisateurs du cluster dépend du fait que vous travailliez en mode isolé ou non. Si vous exécutez isolé, vous pouvez apporter des modifications qui n’affectent pas d’autres utilisateurs.

Modifiez votre code, enregistrez vos modifications et appuyez sur Ctrl+Maj+F5 (⇧⌘F5 sur un Mac) ou sélectionnez Exécuter, puis Redémarrer le débogage. Une fois que vous êtes reconnecté, actualisez votre navigateur et validez vos modifications.

Sélectionnez Exécuter, puis Arrêter le débogage ou appuyez sur Maj+F5 pour arrêter le débogueur.

Note

Par défaut, l’arrêt de la tâche de débogage déconnecte également votre ordinateur de développement de votre cluster Kubernetes. Vous pouvez modifier ce comportement en cherchant Bridge to Kubernetes : Disconnect After Debugging dans les paramètres Visual Studio Code et en supprimant la case à cocher en regard de Déconnecter automatiquement lorsque le débogage s’arrête. Après la mise à jour de ce paramètre, votre ordinateur de développement reste connecté lorsque vous arrêtez et démarrez le débogage. Pour déconnecter votre ordinateur de développement de votre cluster, cliquez sur l’extension Bridge to Kubernetes dans la barre d’état, puis choisissez Déconnecter la session actuelle.

Configuration supplémentaire

Le pont vers Kubernetes peut gérer le trafic de routage et répliquer des variables d’environnement sans aucune configuration supplémentaire. Si vous devez télécharger des fichiers montés sur le conteneur dans votre cluster Kubernetes, comme un fichier ConfigMap, vous pouvez créer un KubernetesLocalProcessConfig.yaml pour télécharger ces fichiers sur votre ordinateur de développement. Pour plus d’informations, consultez Configurer Bridge to Kubernetes.

Si vous utilisez un cluster AKS qui utilise une identité managée, une fonctionnalité de sécurité fournie par Microsoft Entra ID, consultez Utiliser une identité managée avec Bridge to Kubernetes pour plus d’informations sur la configuration de Bridge to Kubernetes pour ce scénario.

Utilisation de la journalisation et des diagnostics

La sortie des logs est écrite dans la fenêtre Bridge to Kubernetes après la connexion de votre ordinateur de développement à votre cluster Kubernetes.

Cliquez sur la barre d’état Kubernetes et choisissez Afficher les informations de diagnostic de connexion. Cette commande imprime les variables d’environnement actuelles et les entrées DNS dans la sortie de journalisation.

En outre, vous trouverez les journaux de diagnostic dans le répertoire Bridge to Kubernetes dans le répertoire TEMP de votre ordinateur de développement. Sur Windows 10, c’est dans %TEMP%\Bridge to Kubernetes. Sur un Mac, le répertoire TEMP est disponible en exécutant echo $TMPDIR à partir d’une fenêtre de terminal. Sur Linux, il est /tmp/Bridge to Kubernetes.

Exécution en mode d’isolation

Avec Bridge to Kubernetes, vous pouvez également configurer une version isolée sur laquelle vous travaillez, ce qui signifie que d’autres personnes qui utilisent le cluster ne seront pas affectées par vos modifications. Ce mode d'isolation est effectué en acheminant vos demandes vers votre copie de chaque service concerné, tandis que tout autre trafic est acheminé normalement. Pour accéder à l’URL du point de terminaison local de l’application isolée, lancez le débogueur en mode isolation, ouvrez le menu Kubernetes dans la barre d’état et choisissez l’entrée de point de terminaison. Vous trouverez plus d’informations sur le fonctionnement du routage en mode isolation à How Bridge to Kubernetes Works.

Propagation des en-têtes

Pour utiliser Bridge to Kubernetes comme il est conçu, vous devez vous assurer de propager l’en-tête Bridge vers Kubernetes des requêtes entrantes vers toutes les demandes que vos services effectuent vers d’autres services du cluster. Toutes les API de requête HTTP, quel que soit le langage, fournissent un moyen spécifique à l’infrastructure de le faire. Par exemple, pour le code .NET en C#, vous pouvez utiliser du code similaire à ce qui suit :

var request = new HttpRequestMessage();
request.RequestUri = new Uri("http://mywebapi/api/values/1");
if (this.Request.Headers.ContainsKey("kubernetes-route-as"))
{
    // Propagate the dev space routing header
    request.Headers.Add("kubernetes-route-as", this.Request.Headers["kubernetes-route-as"] as IEnumerable<string>);
}
var response = await client.SendAsync(request);

Note

Pour éviter d’affecter le code à chaque requête, vous pouvez créer une classe qui hérite de System.Net.Http.DelegatingHandler et remplacer la méthode SendAsync par du code similaire à l’exemple précédent. Vous pouvez trouver du code à l’aide de cette technique sur le web ; un exemple est Propagation correcte de « kubernetes-route-as » dans Bridge to Kubernetes.

Pour les services Node.js, vous pouvez utiliser du code similaire à ce qui suit, extrait de l’exemple todo-app dans le référentiel Bridge to Kubernetes:

    server.get("/api/stats", function (req, res) {
        var options = {
            host: process.env.STATS_API_HOST,
            path: '/stats',
            method: 'GET'
        };
        const val = req.get('kubernetes-route-as');
        if (val) {
            console.log('Forwarding kubernetes-route-as header value - %s', val);
            options.headers = {
                'kubernetes-route-as': val
            }
        }
        var req = http.request(options, function(statResponse) {
            res.setHeader('Content-Type', 'application/json');
            var responseString = '';
            //another chunk of data has been received, so append it to `responseString`
            statResponse.on('data', function (chunk) {
                responseString += chunk;
            });
            statResponse.on('end', function () {
                res.send(responseString);
            });
        });

        req.on('error', function(e) {
            console.log('problem with request: ' + e.message);
          });

          req.end();
    });

Communication avec d’autres services

Lorsque vous communiquez avec un autre service dans le même cluster Kubernetes, par exemple avec une requête HTTP, vous utilisez généralement le nom du service codé en dur dans l’URL de la requête, mais cela ne fonctionnera pas dans certains scénarios, comme lors de l’utilisation de SSH distant, WSL et Codespaces. Cet article explique comment utiliser les variables d’environnement du service Kubernetes pour spécifier l’URL de connexion pour ces scénarios.

Dépannage

Si vous obtenez cette erreur lors de l’activation de l’extension Bridge to Kubernetes :

« Échec de la mise à jour des dépendances : nombre maximal de tentatives dépassé »

Tout d’abord, réessayez l’activation à l’aide du bouton. En cas d’échec répété, consultez https://github.com/microsoft/mindaro/issues/32.

Lorsque vous utilisez Bridge to Kubernetes dans une session SSH distante, si EndpointManager échoue, le problème peut être que Bridge to Kubernetes ne peut pas modifier le fichier hosts en raison d’un problème d’autorisations. Pour permettre l'utilisation de SSH à distance ou pour fonctionner en tant qu'utilisateur sans privilèges élevés, vous devez mettre à jour votre code pour utiliser des variables d'environnement de service Kubernetes et configurer VS Code pour les utiliser, comme décrit dans la rubrique Variables d'environnement de service.

Étapes suivantes

En savoir plus sur Bridge to Kubernetes à Comment fonctionne Bridge to Kubernetes.

Si vous devez déboguer plusieurs services en même temps en parallèle, consultez Déboguer plusieurs services en même temps.