Depurar aplicaciones de Kubernetes con Cloud Code para VS Code

Cloud Code te permite depurar una aplicación desplegada 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.

Con la compatibilidad de depuración de Cloud Code, no tienes que completar la configuración manual, como configurar el reenvío de puertos o insertar argumentos de depuración específicos del lenguaje. Para depurar, necesitas una aplicación de GKE preparada para Cloud Code que incluya un archivo de configuración skaffold.yaml y una configuración de inicio cloudcode.kubernetes.

Depurar una aplicación de GKE

Para empezar 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.

    Nombre del proyecto activo en la barra de estado

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

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

  4. Si tu aplicación no tiene la configuración de Skaffold o la configuración de lanzamiento de cloudcode.kubernetes necesarias, Cloud Code te ayudará a configurarlas.

  5. Confirma si quieres usar el contexto de Kubernetes actual para ejecutar la aplicación (o cambia a otro).

  6. Si has elegido un clúster remoto como contexto, cuando se te pida, elige un registro de imágenes al que enviar las imágenes.

    Si tu proyecto tiene la API de Artifact Registry habilitada y al menos un repositorio de Artifact Registry, puedes buscar y seleccionar un repositorio de Artifact Registry.

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

    Artifact Registry REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME
    Docker Hub docker.io/ACCOUNT
    Asegúrate de que te has autenticado correctamente si usas un repositorio privado de Docker Hub.
    Repositorio de contenedores de AWS (ECR) AWS_ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com/APP
    Azure Container Registry (ACR) ACR_NAME.azurecr.io/APP

    Para generar el nombre del repositorio de imágenes final, 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 tu cloudcode.kubernetesconfiguración de inicio (que se encuentra en .vscode/launch.json).

    Para obtener más información, consulta la guía de gestión de registros de imágenes.

    Cloud Code compila tus contenedores, los envía al registro, aplica las configuraciones de Kubernetes al clúster y espera a que se complete el lanzamiento.

    Después del lanzamiento, Cloud Code reenvía automáticamente todos los puertos de contenedor declarados a tu máquina y muestra las URLs en la ventana de salida para que puedas navegar por tu aplicación activa.

  7. En cada contenedor depurable de tu aplicación, confirma o introduce el directorio del contenedor remoto en el que se encuentra el programa que quieres depurar.

    También puedes pulsar ESC para saltarte la depuración del contenedor.

    Petición de acceso root remoto

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

    Ahora puedes realizar las mismas tareas que normalmente haces al depurar código local, como definir puntos de interrupción y recorrer el código, en un clúster de Kubernetes activo.

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

  8. Para inspeccionar variables e información de la pila, usa la barra lateral de depuración. Para interactuar con la sesión de depuración, usa la consola de depuración en el panel inferior del depurador.

  9. Una vez que haya finalizado la sesión, puede usar los siguientes comandos del menú contextual:

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

  10. Si has desactivado el modo de reloj en la configuración de inicio y quieres hacer cambios en la aplicación, así como volver a compilarla y desplegarla, en el panel Sesiones de desarrollo, coloca el cursor sobre la acción de ejecución y haz clic en Icono de recompilación y nuevo despliegue Volver a compilar y desplegar la aplicación.

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

    Cuando finalices la sesión de depuración, todos los recursos de Kubernetes implementados se eliminarán del clúster.

Detalles de la configuración

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

  • Redirigir el puerto de depuración para que se pueda adjuntar el depurador.
  • Adjuntar un depurador a uno o varios contenedores depurables de 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 adjuntará un depurador a cada contenedor depurable.
  • Persistencia de las definiciones de asignación de origen entre sesiones. Puedes personalizar estas definiciones editando directamente el archivo .vscode/launch.json.

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

Node.js

Reescribir el punto de entrada para invocar:

node --inspect=localhost:9229

Python

Instalar el módulo ptvsd con un contenedor Init y reescribir el punto de entrada para invocar:

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

Go

Instalar el depurador dlv mediante un contenedor Init y reescribir el punto de entrada de forma que la sesión de depuración iniciada se ejecute solo con un servidor de depuración (en modo sin interfaz gráfica), continúe el proceso depurado al iniciarse, acepte varias conexiones de cliente y escuche en localhost:56268:

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

Java

Añade un entorno JAVA_TOOLS_OPTIONS con la configuración adecuada del protocolo Java Debug Wire Protocol (JDWP) para que el agente de depuración de JDWP espere una conexión de socket en el puerto 5005 y permita que la máquina virtual empiece a ejecutarse antes de que se conecte el depurador:

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

Para obtener más información sobre la depuración con Skaffold, consulta la documentación de skaffold debug.

Configurar un contenedor

Para preparar el contenedor para la depuración, sigue las instrucciones del lenguaje que estés usando:

Node.js

  • Inicia la aplicación Node.js con --inspect=<debugPort> donde debugPort procede de la configuración de adjuntos. Por ejemplo: CMD ["node", "--inspect=9229", "index.js"]

Python

  • Asegúrate de que el módulo ptvsd esté instalado en tu máquina y en tu contenedor.
  • Inicia la aplicación Python a través de ptvsd. El puerto especificado debe coincidir con el campo debugPort de la configuración de adjuntos. Por ejemplo: 
    CMD ["python", "-m", "ptvsd", "--port", "", "app.py"]

Go

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

  • Inicia tu solicitud de Go a través de 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 adjuntar. Por ejemplo: 

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

    Nota para solucionar problemas: Cuando depures una aplicación Go, la aplicación se detendrá y esperará a que se conecte un depurador. Conecta un depurador para que se inicie el servicio.

Java

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

  • Inicia la aplicación Java con las siguientes opciones, donde debugPort procede de la configuración de adjuntos. 

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

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

    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 que tienes 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

Configurar la conexión

Para asociar un contenedor depurable, debes tener una configuración de asociación de tipo cloudcode.kubernetes.

Añadir un archivo .vscode/launch.json

Si tu proyecto no tiene un archivo launch.json en su carpeta .vscode, puedes añadir uno con el panel Depuración.

  1. Para ir al panel Depuración, haz clic en Icono de depuración Ejecutar y depurar en la barra de actividad.

  2. En el menú desplegable, selecciona Añadir configuración.

  3. Selecciona Cloud Code: Kubernetes como entorno.

    Configurar Cloud Code: Kubernetes como entorno

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

    Seleccionar la opción de configuración de Kubernetes

  5. Selecciona el lenguaje de programación que estés usando.

    De esta forma, se crea y se abre un archivo launch.json para tu proyecto y se crea una configuración de adjuntos.

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

Añade una configuración de adjuntar al archivo .vscode/launch.json

Para añadir una nueva configuración de adjuntos a un archivo .vscode/launch.json, sigue estos pasos:

  1. Abre el archivo launch.json.
  2. Para invocar el Intellisense del fragmento, haz clic en Añadir configuración.
  3. Para añadir una configuración de adjuntar, selecciona el fragmento Cloud Code: Attach to Kubernetes Pod (Cloud Code: adjuntar a pod de Kubernetes) del idioma que estés usando.
  4. Actualice los atributos de la configuración para que coincidan con los de su proyecto. Para obtener más información sobre los atributos de configuración, consulta Atributos de configuración.

Atributos de configuración

Atributo Descripción
debugPort Puerto de depuración usado en el contenedor.
podSelector Conjunto de pares clave-valor que se usa 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 Ruta al directorio local que contiene el programa que se está depurando. El valor predeterminado es ${workspaceFolder}.
remoteRoot Ruta absoluta al directorio remoto que contiene el programa que se está depurando (en el contenedor de Kubernetes).

Adjuntar un depurador a un pod de Kubernetes

Cloud Code para VS Code permite adjuntar un depurador a un pod de Kubernetes para Node.js, Python, Go, Java y .NET. Solo necesitas un contenedor depurable y una configuración de adjuntos de tipo cloudcode.kubernetes.

Para obtener información sobre las diferencias entre adjuntar archivos a un pod de Kubernetes y depurar una aplicación de Kubernetes, consulta Diferencias entre adjuntar un depurador a un pod y depurar una aplicación de Kubernetes.

Para adjuntar un depurador a tu pod de Kubernetes, sigue estos pasos:

  1. Para ir al panel Depuración, haz clic en Icono de depuración Ejecutar y depurar en la barra de actividad.

  2. Selecciona y lanza la configuración pulsando F5.

    • localhost:${debugPort} se reenvía al puerto debugPort del contenedor durante la depuración.

    La sesión de depuración se ha configurado correctamente. Puedes realizar las tareas que haces normalmente al depurar código local, como definir puntos de interrupción y recorrer el código.

  3. Para inspeccionar variables e información de la pila, usa la barra lateral de depuración. Para interactuar con la sesión de depuración, usa la consola de depuración en el panel inferior del depurador.

  4. Para finalizar la sesión de depuración, haz clic en Icono de detener depuración 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 archivos a un pod de Kubernetes Depurar una aplicación de Kubernetes
Depura un solo pod de Kubernetes. Depura todos los contenedores depurables de la aplicación.
La aplicación debe estar ejecutándose en el pod de Kubernetes antes de depurarla. Ejecuta la aplicación en el clúster de Kubernetes y conecta el depurador.
Usa la configuración (./vscode/launch.json) de tipo cloudcode.kubernetes y la solicitud attach. Usa la configuración (./vscode/launch.json) de tipo cloudcode.kubernetes y la solicitud launch.
Para obtener más información, consulta Configuraciones de lanzamiento y de adjuntos.
Configuración de ejemplo: 
{
  "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 ejemplo: 
{
  "name": "Run/Debug on Kubernetes",
  "type": "cloudcode.kubernetes",
  "request": "launch",
  "skaffoldConfig": "${workspaceFolder}/skaffold.yaml",
  "watch": true,
  "cleanUp": true,
  "portForward": true
}
Esta configuración no se puede usar para ejecutar la aplicación. Esta configuración se puede usar para ejecutar o depurar la aplicación.
Esta configuración es específica de cada idioma. Esta configuración no es específica de ningún idioma.
No hay ningún comando específico. Comando Depurar en Kubernetes.
El modo de monitorización no está disponible, por lo que, después de hacer los cambios, debes reiniciar el depurador manualmente. El modo de monitorización permite que Cloud Code reinicie el depurador después de guardar los cambios.

Siguientes pasos

Obtener asistencia

Para enviar comentarios o informar de problemas, visita GitHub o haz una pregunta en Stack Overflow.