Depura aplicaciones de Kubernetes con Cloud Code para VS Code

Nota: La compatibilidad con la depuración está disponible para Node.js, Python, Go, Java y .NET.

Cloud Code te permite depurar una aplicación implementada en un clúster de Google Kubernetes Engine (GKE) mediante skaffold debug.

Puedes depurar tu aplicación en un clúster local (como minikube o Docker Desktop), GKE o cualquier otro proveedor de servicios en la nube.

Gracias a la compatibilidad con la depuración de Cloud Code, no tienes que completar una configuración manual, como la redirección de puertos o la inserción de argumentos de depuración específicos de un lenguaje. La depuración requiere una aplicación de GKE lista para Cloud Code que incluya un archivo de configuración skaffold.yaml y una configuración de inicio cloudcode.kubernetes.

Depura una aplicación de GKE

Para comenzar a depurar tu aplicación de GKE, sigue estos pasos:

1. En la barra de estado de Cloud Code, haz clic en el nombre del proyecto activo.

   

2. En el menú de selección rápida que aparece, selecciona Debug on Kubernetes.

3. Si se te solicita, autentica tus credenciales para ejecutar y depurar una aplicación de manera local.

4. Si tu aplicación no tiene la configuración necesaria de Skaffold o la configuración de inicio cloudcode.kubernetes, Cloud Code te ayuda a configurarlas.

5. Confirma si quieres usar el contexto de Kubernetes actual para ejecutar la app (o cambia al que prefieras).

6. Si elegiste un clúster remoto como contexto, cuando se te solicite, elige un registro de imágenes para enviarlas. Si usas Container Registry, puedes navegar a un registro existente o especificar el nombre de uno que quieras crear. Si tu proyecto tiene habilitada la API de Artifact Registry y al menos un repositorio de Artifact Registry, puedes explorar y seleccionar un repositorio de Artifact Registry existente.

   En los siguientes ejemplos, se muestra cómo especificar dónde se almacenan las imágenes de contenedor para algunos registros comunes:

   Artifact Registry	{region}-docker.pkg.dev/{project_id}/{repo-name}
   Container Registry	gcr.io/{project_id}
   Docker Hub	docker.io/{account} Asegúrate de estar autenticado correctamente si usas un repositorio privado de Docker Hub.
   AWS Container Repository (ECR)	{aws_account_id}.dkr.ecr.{region}.amazonaws.com/{my-app}
   Azure Container Registry (ACR)	{my_acr_name}.azurecr.io/{my-app}

   Para generar el nombre final del repositorio de imágenes, Cloud Code concatena este registro de imágenes con el nombre de la imagen especificado en los manifiestos de Kubernetes. Esta opción se almacena en la configuración de inicio de cloudcode.kubernetes (que se encuentra en .vscode/launch.json).

   Para obtener más información, consulta la guía de manejo del registro de imágenes.

   A continuación, Cloud Code compila los contenedores, los envía al registro, aplica las configuraciones de Kubernetes al clúster y espera el lanzamiento.

   Cuando finaliza el lanzamiento, Cloud Code redirecciona automáticamente todos los puertos de contenedor declarados a tu máquina y muestra las URL en la ventana de resultado para que puedas explorar la aplicación en vivo.

7. Para cada contenedor depurable de tu aplicación, confirma o ingresa el directorio en el contenedor remoto donde se encuentra el programa que deseas depurar.

   También puedes presionar ESC para omitir la depuración del contenedor.

   

   Cloud Code adjunta una sesión de depuración para cada contenedor depurable en la aplicación.

   Ahora puedes realizar las mismas tareas que sueles hacer cuando depuras código local, como establecer puntos de interrupción y revisar el código paso a paso, en un clúster activo de Kubernetes.

   De forma predeterminada, cuando guardas un cambio en tu aplicación, Cloud Code vuelve a implementarla y configura una sesión de depuración nueva. Puedes activar o desactivar esta función con la marca watch en la configuración de inicio de tu proyecto.

8. Usa la barra lateral de depuración para revisar la información sobre las variables y la pila. Usa la consola de depuración ubicada en el depurador del panel inferior si deseas interactuar con la sesión de depuración.

9. Una vez finalizada la sesión, puedes usar los siguientes comandos del menú contextual:

   • Abrir registros de implementación: Abre los registros de aplicación de una implementación específica con el explorador de registros de Cloud Code.
   • Open Service URL: Abre la URL del servicio de la aplicación de un servicio específico en un navegador web.

10. Si desactivaste el modo de supervisión en la configuración de inicio y quieres realizar cambios en la aplicación, volver a compilarla y volver a implementarla, en el panel Sesiones de desarrollo, pausa en la acción de ejecución y haz clic en Volver a compilar y volver a implementar la aplicación.

11. Con el objetivo de finalizar la sesión de depuración, haz clic en Detener en la barra de herramientas de depuración.

    Una vez que finalices la sesión de depuración, todos los recursos de Kubernetes implementados se borrarán del clúster.

Detalles de configuración

Nota: Cloud Code no modifica la configuración local de Kubernetes. Las transformaciones ocurren en el momento de la implementación y solo son visibles en el servidor.

Cloud Code, con la tecnología de Skaffold, administra automáticamente los siguientes detalles de configuración para todos los lenguajes compatibles:

• Redireccionar el puerto de depuración para poder conectar el depurador
• Conectar un depurador a uno o más contenedores depurables en tu aplicación. Si tu aplicación tiene varios contenedores depurables (contenedores cuyo lenguaje es compatible con la depuración de Cloud Code) configurados en skaffold.yaml, se adjunta un depurador a cada contenedor depurable.
• Conserva las definiciones de asignación de fuentes en todas las sesiones. Para personalizar estas definiciones, edita directamente el archivo .vscode/launch.json.

Cloud Code también controla los siguientes detalles de configuración específicos del lenguaje:

Node.js

Reescribe el punto de entrada que se invocará:

node --inspect=localhost:9229

Python

Instala el módulo ptvsd mediante un contenedor Init y reescribe el punto de entrada que se invocará:

python -m ptvsd --host localhost --port 5678

Go

Instala el depurador dlv mediante un contenedor Init y reescribe el punto de entrada de modo que la sesión de depuración iniciada se ejecute solo con un servidor de depuración (en modo sin interfaz gráfica) continúa el proceso de depuración en el inicio, acepta varias conexiones de clientes y escucha en localhost:56268:

  dlv exec --headless --continue --accept-multiclient --listen=localhost:56268 --api-version=2, <app> --

Java

Agregar un entorno JAVA_TOOLS_OPTIONS con la configuración adecuada del protocolo de cable de depuración de Java (JDWP) de modo que el agente de depuración de JDWP escuche una conexión de socket en el puerto 5005 y permita que la VM comience a ejecutarse antes de conectar el depurador:

  jdwp=transport=dt_socket,server=y,suspend=n,address=5005,quiet=y

Para obtener más detalles sobre la depuración con tecnología de Skaffold, consulta la documentación de skaffold debug.

Configura tu contenedor

A fin de preparar tu contenedor para la depuración, sigue las instrucciones correspondientes al lenguaje que usas:

Node.js

• Inicia la aplicación de Node.js con --inspect=<debugPort>, en el que debugPort proviene de la configuración de conexión. Por ejemplo: CMD ["node", "--inspect=9229", "index.js"]

Python

• Asegúrate de tener instalado el módulo ptvsd en tu máquina y en tu contenedor.
• Inicia la aplicación de Python a través de ptvsd. Haz coincidir el puerto especificado con el campo debugPort en la configuración de conexión. Por ejemplo:

  CMD ["python", "-m", "ptvsd", "--port", "", "app.py"]
  

Go

• Asegúrate de tener instalado el paquete dlv en tu máquina y tu contenedor de Go.

• Inicia tu aplicación de Go con dlv debug.

  El puerto especificado en el comando de inicio debe ser el mismo que el valor del atributo debugPort en la configuración de conexión. Por ejemplo:

  CMD ["dlv", "debug", "--headless", "--listen=:<debugPort>", "--log"]
  

  Sugerencia para solucionar problemas: Cuando depures una aplicación de Go, esta se paralizará y esperará a que se adjunte un depurador. Adjunta un depurador para que el servicio se inicie.

Java

• Asegúrate de que la JVM esté instalada en tu máquina.

• Inicia la aplicación de Java con las siguientes opciones, en las que debugPort proviene de la configuración de conexión.

  -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=,quiet=y
  

  Por ejemplo, para iniciar la aplicación de Java en modo de depuración y escucha la conexión en el puerto debugPort:

  ENTRYPOINT ["java","-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=<debugPort>,quiet=y", "-jar", "my-app-1.0.jar"]
  

.NET Core

• Asegúrate de tener instalado vsdbg, el depurador de línea de comandos de .NET Core de Microsoft, en tu contenedor de Kubernetes.

  Por ejemplo:

  RUN apt-get update 
  
    && apt-get install -y --no-install-recommends unzip 
  
    && apt-get install -y procps 
  
    && rm -rf /var/lib/apt/lists/* 
  
    && curl -sSL https://aka.ms/getvsdbgsh | bash /dev/stdin -v latest -l /dbg/netcore/vsdbg
  

Establece la configuración de conexión

Para conectarte a un contenedor depurable, debes tener una configuración de conexión de tipo cloudcode.kubernetes.

Agrega un archivo .vscode/launch.json

Si tu proyecto no tiene un archivo launch.json en la carpeta .vscode, puedes agregar uno mediante el panel Depurar.

1. Para navegar al panel Debug, haz clic en Run and Debug en la barra de actividad.

2. Selecciona Add Configuration en el menú desplegable.

3. Selecciona Cloud Code: Kubernetes como entorno.

   

4. Selecciona la opción Attach to Kubernetes Pod (Adjuntar al Pod de Kubernetes).

   

5. Selecciona el lenguaje de programación que usas.

   Se creará y abrirá un archivo launch.json para tu proyecto, y se creará una configuración de conexión por ti.

6. Actualiza los atributos de configuración del archivo launch.json para que coincidan con los de tu proyecto. Para obtener más información sobre los atributos de configuración, consulta Atributos de configuración.

Agrega una configuración de conexión al archivo .vscode/launch.json

Para agregar una nueva configuración de conexión a un archivo .vscode/launch.json existente, sigue estos pasos:

1. Abre el archivo launch.json.
2. Para invocar el fragmento Intellisense, haz clic en Agregar configuración.
3. Para agregar una configuración de conexión, selecciona el fragmento Cloud Code: Attach to Kubernetes Pod correspondiente al lenguaje que usas.
4. Actualiza los atributos de la configuración para que coincidan con los de tu proyecto. Para obtener más información sobre los atributos de configuración, consulta Atributos de configuración.

Atributos de la configuración

Atributo	Descripción
debugPort	Puerto de depuración usado en el contenedor.
podSelector	Es el conjunto de pares clave-valor que se usan para seleccionar el Pod de depuración. Para obtener más información, consulta la guía sobre selectores. En el siguiente ejemplo, se muestra un podSelector típico: "podSelector": { "app": <deployment-name> }
localRoot	La ruta de acceso al directorio local que contiene el programa en depuración. La configuración predeterminada es ${workspaceFolder}.
remoteRoot	La ruta de acceso absoluta del directorio remoto que contiene el programa en depuración (en el contenedor de Kubernetes).

Adjunta un depurador a tu Pod de Kubernetes

Cloud Code para VS Code admite adjuntar un depurador a un pod de Kubernetes para Node.js, Python, Go, Java y .NET. Todo lo que necesitas es un contenedor depurable y una configuración de conexión del tipo cloudcode.kubernetes.

Si deseas obtener información sobre las diferencias entre adjuntar a un pod de Kubernetes y depurar una aplicación de Kubernetes, consulta En qué se diferencia adjuntar un depurador a un pod de la depuración de una aplicación de Kubernetes.

Para adjuntar un depurador a tu Pod de Kubernetes, realiza las siguientes tareas:

1. Para navegar al panel Debug, haz clic en Run and Debug en la barra de actividad.

2. Presiona F5 para seleccionar y, luego, iniciar la configuración.

   • Se reenvía el puerto de localhost:${debugPort} a debugPort en el contenedor durante la depuración.

   Se configuró correctamente la sesión de depuración. Puedes realizar las tareas que sueles realizar cuando depuras código local, como establecer interrupciones y revisar el código.

3. Usa la barra lateral de depuración para revisar la información sobre las variables y la pila. Usa la consola de depuración ubicada en el depurador del panel inferior si deseas interactuar con la sesión de depuración.

4. Para finalizar la sesión de depuración, haz clic en Detener en la barra de herramientas de depuración.

Diferencias entre adjuntar un depurador a un Pod y depurar una aplicación de Kubernetes

Adjuntar a un Pod de Kubernetes	Depura una aplicación de Kubernetes
Depura un solo Pod de Kubernetes.	Depura todos los contenedores depurables de la aplicación.
La aplicación debe ejecutarse en el Pod de Kubernetes antes de la depuración.	Ejecuta la aplicación en el clúster de Kubernetes y adjunta el depurador.
Usa la configuración (.vscode/launch.json) del tipo cloudcode.kubernetes y solicita attach.	Usa la configuración (.vscode/launch.json) del tipo cloudcode.kubernetes y solicita launch. Para obtener más información, consulta Comparación de configuraciones de inicio y conexión.
Configuración de muestra: { "name": "Attach to Kubernetes Pod (NodeJS)", "type": "cloudcode.kubernetes", "request": "attach", "language": "Node", "debugPort": 9229, "podSelector": { "app": "hello-world" }, "localRoot": "${workspaceFolder}", "remoteRoot": "/app" }	Configuración de muestra: { "name": "Run/Debug on Kubernetes", "type": "cloudcode.kubernetes", "request": "launch", "skaffoldConfig": "${workspaceFolder}/skaffold.yaml", "watch": true, "cleanUp": true, "portForward": true }
No se puede usar esta configuración para ejecutar la aplicación.	Esta configuración se puede usar para ejecutar o depurar la aplicación.
Esta configuración es específica para cada lenguaje.	Esta configuración no es específica para cada lenguaje.
No hay un comando dedicado.	Depurar en Kubernetes.
El modo de observación no está disponible, por lo que, después de realizar cambios, reinicia el depurador de forma manual.	El modo de supervisión permite que Cloud Code reinicie el depurador después de guardar los cambios.

¿Qué sigue?

• Usa la sincronización de archivos y la recarga en caliente para acelerar el desarrollo.
• Configura un entorno de desarrollo continuo en Cloud Code.
• Consulta los registros de Kubernetes en Cloud Code.

Obtener asistencia

Si deseas enviar comentarios, informa problemas en GitHub o haz preguntas en Stack Overflow.