Uso de Bridge to Kubernetes (VS Code)
Nota
Bridge to Kubernetes se retirará el 30 de abril de 2025. Para obtener más información sobre las alternativas de retirada y código abierto, consulte el problema de GitHub.
Bridge to Kubernetes permite ejecutar y depurar código en el equipo de desarrollo, mientras sigue conectado al clúster de Kubernetes con el resto de la aplicación o los 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 que se ejecuta en el equipo de desarrollo.
Antes de empezar
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).
Prerrequisitos
- Un clúster de Kubernetes con una aplicación que quiera depurar.
- Visual Studio Code que se ejecuta en macOS, Windows 10 o posterior o Linux.
Conéctate al clúster y depura 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:
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.
Abra el área de trabajo de la aplicación que desea 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 para iniciar el proceso de configuración.
Elija el servicio kubernetes que desea redirigir a la versión local.
Todo el tráfico en el clúster de Kubernetes es redirigido para su servicio a la versión de su aplicación que se ejecuta en su ordenador de desarrollo. Bridge to Kubernetes también enruta todo el tráfico saliente de la aplicación a su clúster de Kubernetes.
Importante
Solo puede redirigir los servicios que tienen un único pod.
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 código abierto de Kubernetes y tenga un clúster de Kubernetes con servicios que quiera 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 desee depurar, haga clic con el botón derecho en el servicio y seleccione Depuración: Túnel local.
En este momento, si no tiene instalada ninguna extensión de VS Code que ofrezca funcionalidades de depuración locales, se le redirigirá a Marketplace para seleccionar 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 elija Depurar: Túnel local, omitirá el paso de instalación y continuará directamente con el paso siguiente, Configurar el 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 permitir que Bridge to Kubernetes cree uno o elija no crear uno, en cuyo caso tiene 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 obtener más información sobre esta opción, consulte Uso de funcionalidades 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. Esta configuración de inicio se crea mediante Bridge to Kubernetes, si elige esa opción.
Nota
Se le pedirá que permita que el EndpointManager se ejecute con privilegios administrativos y modifique el archivo de hosts.
El equipo de desarrollo se conecta cuando la barra de estado de VS Code se vuelve naranja y la extensión de Kubernetes muestra que está conectado.
Depuración con Bridge to Kubernetes
Una vez que tu equipo de desarrollo está conectado, el tráfico comienza a redirigirse a tu equipo de desarrollo para el servicio que estás reemplazando.
Nota
En los inicios posteriores, no se le pedirá el nombre del servicio, el puerto, la tarea de inicio o si se va a ejecutar aislado. Estos valores se guardan en .vscode/tasks.json
. Para cambiar estas opciones más adelante, 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. Puede abrir .vscode/launch.json y .vscode/tasks.json para ver las opciones de configuración específicas 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 el uso de 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.
Vaya a la aplicación de ejemplo abriendo la dirección URL pública. Cuando el código alcanza el punto de interrupción, debe abrirse en el depurador. Para reanudar el servicio, presione Ctrl+F5 o seleccione EjecutarContinuar. Vuelva al explorador y compruebe que ve una imagen de marcador de posición para la bicicleta.
Actualización de la aplicación
Cuando realizas cambios en el código localmente, si estos son visibles para otros usuarios que usan el clúster, depende de si estás ejecutando en modo aislado o no. Si está ejecutando 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, detener la tarea de depuración también 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). Una vez que se actualice esta configuración, el equipo de desarrollo permanecerá conectado cuando se detenga y se 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 Desconectar sesión actual.
Configuración adicional
Bridge to Kubernetes puede controlar el tráfico de enrutamiento y la replicación de variables de entorno 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 obtener más información, consulte Configure Bridge to Kubernetes.
Si usa un clúster de AKS que usa la identidad administrada, una característica de seguridad proporcionada por el identificador de Entra de Microsoft, consulte Uso de la identidad administrada con Bridge to Kubernetes para obtener información sobre cómo configurar Bridge to Kubernetes para este escenario.
Uso de registros y diagnósticos
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 la opción Mostrar información de diagnóstico de conexión. Este comando imprime las variables de entorno actuales y las entradas DNS en la salida del registro.
Además, puede encontrar los registros de diagnóstico en el directorio Bridge to Kubernetes
en el directorio TEMP del equipo de desarrollo. En Windows 10, eso está en %TEMP%\Bridge to Kubernetes
. En un Equipo Mac, el directorio TEMP se puede encontrar ejecutando 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 logra redirigiendo tus solicitudes a tu copia de cada servicio afectado, mientras que el resto del tráfico se enruta normalmente. 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 Cómo funciona Bridge to Kubernetes.
Propagación de encabezados
Para usar Bridge to Kubernetes como está diseñado, debe asegurarse de propagar el encabezado Bridge to Kubernetes desde las solicitudes entrantes a cualquier solicitud que los servicios realicen 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 de .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 que el código afecte a cada solicitud, puede crear una clase que herede de System.Net.Http.DelegatingHandler e invalidar el método SendAsync
con código similar al 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 del 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 de 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 mediante 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 de 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 un usuario sin privilegios elevados, debe actualizar el código para que use las variables de entorno del servicio Kubernetes, y configurar VS Code para usarlas, como se describe en el tema variables de entorno del 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 Depurar varios servicios al mismo tiempo.