Utiliser Bridge to Kubernetes (VS Code)

Bridge to Kubernetes vous permet d’exécuter et de déboguer du code sur votre ordinateur de développement tout en étant toujours connecté à votre cluster Kubernetes avec le reste de votre application ou de vos services. Ce guide vous explique comment utiliser Bridge to Kubernetes pour rediriger le trafic entre votre cluster Kubernetes et le code qui s’exécute sur votre ordinateur de développement.

Avant de commencer

Cet article part du principe 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. Si vous utilisez Azure Kubernetes Service et souhaitez utiliser un exemple d’application plus complexe, consultez Bridge to Kubernetes (AKS).

Prérequis

• 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.

Connexion à votre cluster et débogage d’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) et exécutez la commande Bridge to Kubernetes : Configurer 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. Bridge to Kubernetes reroute également tout le trafic sortant de l’application vers votre cluster Kubernetes.

   Important

   Vous ne pouvez rediriger que les services qui n’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 l’extension Kubernetes open source est 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 démarrent le processus de configuration pour le débogage de tunnel local.

Notes

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 façon est d’ouvrir la palette de commandes (Ctrl+Maj+P ou Cmd+Maj+P sur un Mac) et de taper Kubernetes : Débogage (tunnel local).

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 faites un clic droit sur le service et 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.

Une fois l’extension Bridge to Kubernetes installée, la prochaine fois que vous choisissez Déboguer : Tunnel local, vous ignorerez l’étape d’installation et passerez directement à l’étape suivante, Configurer le débogueur pour le débogage du tunnel local avec Bridge to Kubernetes.

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

Lors de la première étape de configuration du débogueur pour le débogage de tunnel local, 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 une ou choisir de ne pas en créer une, auquel cas vous devez démarrer votre application ou votre service manuellement. Pour plus d’informations, consultez Configurations de lancement.

Vous avez la possibilité d’exécuter isolément ou non. Si vous exécutez isolément, seules vos demandes sont routées vers votre processus local ; d’autres développeurs peuvent utiliser le cluster sans être affectés. Si vous n’exécutez pas isolément, tout le trafic est 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. Si vous choisissez cette option, cette configuration de lancement est créée par Bridge to Kubernetes.

Notes

Il vous sera demandé d’autoriser EndpointManager à exécuter des tâches élevées et à modifier votre fichier d’hôtes.

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

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

Notes

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 de manière isolée. 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), puis exécutez la commande Bridge to Kubernetes : Configurer. 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 est ajoutée à votre profil de lancement, GRPC_DNS_RESOLVER, 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 apportez des modifications de code localement, le fait qu’elles soient visibles ou non par d’autres utilisateurs du cluster dépend du fait que vous exécutez de manière isolée ou non. Si vous exécutez isolément, vous pouvez apporter des modifications qui n’affectent pas les 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.

Notes

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 recherchant Bridge to Kubernetes : Déconnecter après le débogage dans les paramètres Visual Studio Code et en décochant la case en regard de Déconnecter automatiquement à la fin du débogage. Après la mise à jour de ce paramètre, votre ordinateur de développement reste connecté quand 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 active.

Configuration supplémentaire

Bridge to Kubernetes peut gérer le trafic de routage et répliquer les variables d’environnement sans aucune configuration supplémentaire. Si vous devez télécharger des fichiers montés sur le conteneur de votre cluster Kubernetes, tel qu’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 de journalisation 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, puis 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, vous le trouverez dans %TEMP%\Bridge to Kubernetes. Sur un Mac, vous pouvez trouver le répertoire TEMP en exécutant echo $TMPDIR à partir d’une fenêtre de terminal. Sur Linux, il s’agit de /tmp/Bridge to Kubernetes.

Exécution en mode d’isolation

Avec Bridge to Kubernetes, vous pouvez également configurer une version isolée des services sur lesquels vous travaillez, ce qui signifie que les autres utilisateurs du cluster ne seront pas affectés par vos modifications. Ce mode d’isolation est effectué en acheminant vos requêtes vers votre copie de chaque service concerné, mais en acheminant normalement tout autre trafic. Pour accéder à l’URL du point de terminaison local de l’application isolée, lancez le débogueur en mode d’isolation, ouvrez le menu Kubernetes dans la barre d’état et choisissez l’entrée de point de terminaison. Pour plus d’informations sur le fonctionnement du routage en mode d’isolation, consultez Fonctionnement de Bridge to Kubernetes.

Propagation des en-têtes

Pour bien utiliser Bridge to Kubernetes, vous devez veiller à propager l’en-tête Bridge to Kubernetes des requêtes entrantes vers toutes les requêtes 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 d’effectuer cette opération. 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);

Notes

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 ; par exemple, Propager correctement « kubernetes-route-as » dans Bridge to Kubernetes.

Pour les services Node.js, vous pouvez utiliser du code semblable à 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 de 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 nouvelles tentatives dépassées »

Tout d’abord, réessayez l’activation à l’aide du bouton. Si elle ne réussit pas à plusieurs reprises, 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 activer SSH distant ou exécuter en tant qu’utilisateur non élevé, 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

Pour en savoir plus sur Bridge to Kubernetes, consultez 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.

Des informations sur les fonctionnalités actuellement prises en charge et une feuille de route future pour Bridge to Kubernetes sont disponibles sur Feuille de route Bridge to Kubernetes.