Depurar aplicaciones de Kubernetes en Cloud Code para Cloud Shell

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

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

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

    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.

  6. 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 se guarda automáticamente un cambio en tu aplicación, Cloud Code vuelve a desplegarla 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.

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

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

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

  10. 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 Depuración 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