Uso de Bridge to Kubernetes (VS Code)

Puente a Kubernetes le permite ejecutar y depurar el código en el equipo de desarrollo mientras sigue conectado al clúster de Kubernetes con el resto de aplicaciones o servicios. En esta guía, aprenderá a usar Bridge to Kubernetes para redirigir el tráfico entre el clúster de Kubernetes y el código en ejecución en el equipo de desarrollo.

Antes de comenzar

En este artículo se supone que ya tiene su propio clúster con una arquitectura de microservicios y quiere depurar uno de los pods del clúster. Si quiere obtener información sobre cómo usar Bridge to Kubernetes con una aplicación de ejemplo existente, consulte Uso de Bridge to Kubernetes con un ejemplo. Si usa Azure Kubernetes Service y quiere usar una aplicación de ejemplo más compleja, consulte Bridge to Kubernetes (AKS).

Requisitos previos

• Un clúster de Kubernetes con una aplicación que quiere depurar.
• Visual Studio Code en ejecución en macOS, Windows 10 o posterior, o Linux.

Conexión al clúster y depuración de un servicio

Hay un par de maneras diferentes de iniciar el proceso de depuración con Bridge to Kubernetes. Si va a empezar desde la extensión de Kubernetes de código abierto, sin Bridge to Kubernetes instalado, vaya a Instalación y uso de la depuración de túnel local. Si ya tiene Bridge to Kubernetes instalado, continúe con los pasos siguientes:

1. En el equipo de desarrollo, asegúrese de que el contexto actual está establecido en el clúster y el espacio de nombres en el que se ejecuta la aplicación.

2. Abra el área de trabajo de la aplicación que quiere depurar en Visual Studio Code. En la vista de la extensión de Kubernetes en Clústeres, asegúrese de que el clúster y el espacio de nombres estén seleccionados. Abra la paleta de comandos (CTRL+MAYÚS+P o Cmd+Mayús+P en un equipo Mac) y ejecute el comando Bridge to Kubernetes: Configure (Bridge to Kubernetes: Configurar) para iniciar el proceso de configuración.

3. Elija el servicio de Kubernetes que quiere redirigir a la versión local.

   

   Todo el tráfico del clúster de Kubernetes se redirige para el servicio a la versión de la aplicación que se ejecuta en el equipo de desarrollo. Puente a Kubernetes también enruta todo el tráfico saliente desde la aplicación al clúster de Kubernetes.

   Importante

   Solo puede redirigir servicios que tengan un único pod.

4. Después de seleccionar el servicio, omita la sección siguiente y siga los pasos descritos en Configuración del depurador para la depuración de túnel local con Bridge to Kubernetes.

Instalación y uso de la depuración de túnel local

Siga estos pasos para empezar a usar la depuración de túnel local cuando tenga instalada la extensión de Kubernetes de código abierto y tenga un clúster de Kubernetes con los servicios que quiere depurar. Los pasos de esta sección le llevan a través de la instalación de Bridge to Kubernetes y el inicio del proceso de configuración para la depuración de túnel local.

Nota

La extensión de Kubernetes para VS Code proporciona un punto de entrada de API que permite a los autores de extensiones contribuir con otras soluciones de túnel local desde VS Code Marketplace. Bridge to Kubernetes es una posible implementación de la funcionalidad de depuración de túnel local.

Hay dos maneras de empezar a usar la depuración de túnel local en VS Code. La primera manera de abrir la paleta de comandos (CTRL+MAYÚS+P o Cmd+Mayús+P en un equipo Mac) y escriba Kubernetes: Debug (Local Tunnel) (Kubernetes: Depurar [túnel local]).

Como alternativa, vaya al explorador de clústeres de Kubernetes. Abra los recursos del clúster activo y busque un servicio o pod que quiera depurar, haga clic con el botón derecho en el servicio y seleccione Debug: Local Tunnel (Depurar: túnel local).

En este momento, si no tiene ninguna extensión de VS Code instalada que ofrezca funcionalidades de depuración local, se le redirigirá al marketplace para que seleccione una extensión que proporcione depuración local. Seleccione Extensión Bridge to Kubernetes.

Una vez instalada la extensión Bridge to Kubernetes, la próxima vez que elijaDebug: Local Tunnel (Depurar: túnel local), omitirá el paso de instalación y continuará directamente con el paso siguiente, Configuración del depurador para la depuración de túnel local con Bridge to Kubernetes.

Configuración del depurador para la depuración de túnel local con Bridge to Kubernetes

El primer paso de la configuración del depurador para la depuración de túnel local es que se le pida que escriba el puerto TCP que la aplicación usa para ejecutarse localmente:

Elija una configuración de inicio de depuración que use normalmente al ejecutar la aplicación localmente. Si no tiene una configuración de inicio, puede dejar que Bridge to Kubernetes cree una o no crear ninguna, en cuyo caso tendrá que iniciar la aplicación o el servicio manualmente. Más información en Configuraciones de inicio.

Tiene la opción de ejecutar con aislamiento o sin. Si ejecuta con aislamiento, solo sus solicitudes se enrutan a su proceso local. Otros desarrolladores pueden usar el clúster sin verse afectados. Si no ejecuta con aislamiento, todo el tráfico se redirige al proceso local. Para más información sobre esta opción, vea Uso de funciones de enrutamiento para desarrollar de forma aislada.

Seleccione el icono Depurar de la izquierda y seleccione la configuración de inicio de Kubernetes recién agregada, como Launch via NPM with Kubernetes (Iniciar a través de NPM con Kubernetes), en la parte superior. Bridge to Kubernetes crea esta configuración de inicio, si elige esa opción.

Nota

Se le pedirá que permita que EndpointManager se ejecute con privilegios elevados y modifique el archivo hosts.

El equipo de desarrollo está conectado cuando la barra de estado de VS Code se vuelve naranja y la extensión de Kubernetes muestra que está conectado.

Una vez que el equipo de desarrollo está conectado, el tráfico comienza a redirigirse a dicho equipo para el servicio que está reemplazando.

Nota

En los inicios posteriores, no se le pedirá el nombre del servicio, el puerto, la tarea de inicio ni si va a ejecutar con aislamiento. Estos valores se guardan en .vscode/tasks.json. Para cambiar esta configuración más tarde, abra la paleta de comandos (CTRL+MAYÚS+P o Cmd+Mayús+P en un equipo Mac) y ejecute el comando Bridge to Kubernetes: Configure (Bridge to Kubernetes: Configurar). Puede abrir .vscode/launch.json y .vscode/tasks.json para ver los valores de configuración específicos que Bridge to Kubernetes agrega al perfil de inicio.

Si el clúster usa gRPC C core, una implementación de gRPC que usa c-ares, se agrega una variable de entorno al perfil de inicio, GRPC_DNS_RESOLVER, con el valor native. Esta variable especifica que se use una solución alternativa para evitar un retraso de tiempo de 2 minutos al conectarse. Para más información, consulte este problema de gRPC.

Establecer un punto de interrupción

Establezca un punto de interrupción con F9 o mediante la selección de Ejecutar y luego Alternar punto de interrupción.

Abra la dirección URL pública para navegar a la aplicación de ejemplo. Cuando el código alcanza el punto de interrupción, debe abrirse en el depurador. Para reanudar el servicio, pulse Ctrl+F5 o seleccione Ejecutar y Continuar. Vuelva al explorador y compruebe que ve una imagen de marcador de posición para la bicicleta.

Actualización de la aplicación

Al realizar cambios en el código localmente, el hecho de que sean visibles o no para otros usuarios que usen el clúster depende de si se ejecuta en modo aislado o no. Si está ejecutando en modo aislado, puede realizar cambios que no afecten a otros usuarios.

Edite el código, guarde los cambios y presione Ctrl+Mayús+F5 (⇧⌘F5 en un equipo Mac) o seleccione Ejecutar y luego Reiniciar depuración. Después de volver a conectarse, actualice el explorador y valide los cambios.

Seleccione Ejecutar y luego Detener depuración o presione Mayús+F5 para detener el depurador.

Nota

De forma predeterminada, al detener la tarea de depuración también se desconecta el equipo de desarrollo del clúster de Kubernetes. Puede cambiar este comportamiento si busca Bridge to Kubernetes: Disconnect After Debugging (Bridge to Kubernetes: Desconectar después de la depuración) en la configuración de Visual Studio Code y quita la marca situada junto a Disconnect automatically when debugging stops (Desconectar automáticamente cuando se detiene la depuración). Después de actualizar esta configuración, el equipo de desarrollo permanecerá conectado cuando detenga e inicie la depuración. Para desconectar el equipo de desarrollo del clúster, haga clic en la extensión Bridge to Kubernetes en la barra de estado y elija Disconnect current session (Desconectar la sesión actual).

Configuración adicional

Puente a Kubernetes puede controlar el tráfico de enrutamiento y las variables del entorno de replicación sin ninguna configuración adicional. Si necesita descargar los archivos que se montan en el contenedor del clúster de Kubernetes, como un archivo ConfigMap, puede crear un KubernetesLocalProcessConfig.yaml para descargar esos archivos en el equipo de desarrollo. Para más información, consulte Configuración de Bridge to Kubernetes.

Si usa un clúster de AKS que usa la identidad administrada, una característica de seguridad proporcionada por Microsoft Entra ID, consulte Uso de identidad administrada con Bridge to Kubernetes para obtener información sobre cómo configurar Bridge to Kubernetes para este escenario.

Uso de registro y diagnóstico

La salida del registro se escribe en la ventana Bridge to Kubernetes después de que el equipo de desarrollo se conecte al clúster de Kubernetes.

Haga clic en la barra de estado de Kubernetes y elija Show connection diagnostics information (Mostrar información de diagnóstico de conexión). Este comando imprime las variables de entorno actuales y las entradas de DNS en la salida del registro.

Además, puede encontrar los registros de diagnóstico en el directorio Bridge to Kubernetes del directorio TEMP del equipo de desarrollo. En Windows 10, está en %TEMP%\Bridge to Kubernetes. En un equipo Mac, para encontrar el directorio TEMP hay que ejecutar echo $TMPDIR desde una ventana de terminal. En Linux, es /tmp/Bridge to Kubernetes.

Ejecución en modo de aislamiento

Con Bridge to Kubernetes, también puede configurar una versión aislada de los servicios en los que está trabajando, lo que significa que otros usuarios que usan el clúster no se verán afectados por los cambios. Este modo de aislamiento se consigue enrutando las solicitudes a la copia de cada servicio afectado, pero enrutando el resto de tráfico con normalidad. Para acceder a la dirección URL del punto de conexión local de la aplicación aislada, inicie el depurador en modo de aislamiento, abra el menú de Kubernetes en la barra de estado y elija la entrada del punto de conexión. Puede encontrar más información sobre cómo funciona el enrutamiento en modo de aislamiento en Funcionamiento de Bridge to Kubernetes.

Propagación de encabezados

Para usar Bridge to Kubernetes en la forma en que se ha diseñado, debe asegurarse de propagar el encabezado Bridge to Kubernetes de las solicitudes entrantes a las solicitudes que realicen los servicios a otros servicios del clúster. Todas las API de solicitud HTTP, independientemente del lenguaje, proporcionan alguna manera específica del marco para hacerlo. Por ejemplo, para el código .NET en C#, puede usar código similar al siguiente:

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);

Nota

Para evitar afectar al código en cada solicitud, puede crear una clase que herede de System.Net.Http.DelegatingHandler y reemplazar el método SendAsync por código similar al del ejemplo anterior. Puede encontrar código que usa esta técnica en la web; un ejemplo es Propagación correcta de "kubernetes-route-as" en Bridge to Kubernetes.

Para los servicios Node.js, puede utilizar un código similar al siguiente, tomado de la muestra todo-app en el Puente al repositorio de 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();
    });

Comunicación con otros servicios

Cuando se comunica con otro servicio en el mismo clúster de Kubernetes, por ejemplo, con una solicitud HTTP, normalmente se usa el nombre de servicio codificado de forma rígida en la dirección URL de la solicitud, pero eso no funcionará en algunos escenarios, como cuando se usa SSH remoto, WSL y Codespaces. En este artículo se describe cómo usar las variables de entorno del servicio de Kubernetes para especificar la dirección URL de conexión para estos escenarios.

Solución de problemas

Si recibe este error al activar la extensión Bridge to Kubernetes:

"Failed to update dependencies: maximum number of retries exceeded" (No se pudieron actualizar las dependencias: se superó el número máximo de reintentos)

En primer lugar, vuelva a intentar la activación con el botón. Si vuelve a producirse el error repetidamente, vea https://github.com/microsoft/mindaro/issues/32.

Cuando se usa Bridge to Kubernetes en una sesión SSH remota, si se produce un error en EndpointManager, el problema podría ser que Bridge to Kubernetes no puede modificar el archivo de hosts debido a un problema de permisos. Para habilitar SSH remoto o ejecutar como usuario sin privilegios elevados, debe actualizar el código para usar variables de entorno de servicio de Kubernetes y configurar VS Code para usarlas, como se describe en el tema Variables de entorno de servicio.

Pasos siguientes

Obtenga más información sobre Bridge to Kubernetes en Cómo funciona Bridge to Kubernetes.

Si necesita depurar varios servicios al mismo tiempo en paralelo, consulte Depuración de varios servicios al mismo tiempo.

Puede encontrar información sobre las características admitidas actualmente y un plan de desarrollo futuro para Bridge to Kubernetes en Plan de desarrollo de Bridge to Kubernetes.