Soluciona problemas de fallas en la canalización

Linux

Nota: Image Builder está disponible de forma general, pero tu proyecto debe agregarse a una lista de entidades permitidas antes de que puedas usarlo. Para solicitar acceso, envía el formulario de solicitud de acceso o comunícate con tu equipo de cuentas. Google CloudLa lista de entidades permitidas solo abarca las cuentas de servicio de tu proyecto y no las cuentas de servicio propiedad de Google. Para obtener más información, consulta Cuentas de servicio incluidas en la lista de entidades permitidas.

Si tu canalización de Image Builder falla durante la fase de personalización, revisa los archivos de registro, configura la marca de depuración interactiva en tu VM de trabajador o analiza las imágenes de depuración intermedias para identificar errores de compilación o de secuencia de comandos.

Antes de comenzar

• Si aún no lo hiciste, configura la autenticación. La autenticación verifica tu identidad para acceder a los servicios y las APIs de Google Cloud . Para ejecutar código o muestras desde un entorno de desarrollo local, puedes autenticarte en Compute Engine seleccionando una de las siguientes opciones:

  1. Instala Google Cloud CLI. Después de la instalación, inicializa Google Cloud CLI con el siguiente comando:

     gcloud init

     Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

     Nota: Si ya instalaste gcloud CLI, asegúrate de tener la versión más reciente. Para esto, ejecuta gcloud components update.
  2. Configura una región y una zona predeterminadas.

Revisa los canales de registro

Image Builder escribe registros en varias ubicaciones para ayudarte a diagnosticar fallas en diferentes niveles de la pila:

• Registros del orquestador de Cloud Build: Muestran los pasos de compilación de alto nivel en la consola de Cloud Build. Si falla un paso, se imprimirá un vínculo al directorio de trabajo de Cloud Storage correspondiente.
• Registros del agente de VM de personalización: El agente de personalización captura la salida estándar (stdout) y el error estándar (stderr) de tus pasos de personalización. El organizador sondea estos registros y los transmite directamente a los registros de seguimiento de Cloud Build. Si los registros están truncados o necesitas inspeccionarlos por completo, ve a la carpeta que coincida con tu ID de compilación en el bucket _GCS_WORKDIR.
• Registros de la consola en serie: Si el SO invitado no se inicia, el agente de personalización no puede iniciarse. En estos casos, consulta los registros de la consola en serie. El orquestador transmite la salida del puerto en serie de la VM de trabajador directamente a tu bucket de directorio de trabajo de Cloud Storage. Al final del registro de Cloud Build con errores, se imprime un vínculo al archivo de registro serial.
• Registros del diario del SO invitado: Para solucionar problemas detallados a nivel del sistema en Linux, el agente de personalización sube una copia completa del registro journal del sistema a tu bucket de directorio de trabajo de Cloud Storage al final de la ejecución.

Cómo resolver fallas de secuencias de comandos con la marca de depuración

De forma predeterminada, si falla un paso de personalización, Image Builder finaliza la ejecución y borra la VM de trabajador de inmediato para controlar los costos.

Para depurar secuencias de comandos de forma interactiva, puedes habilitar la marca debug. Esto mantiene activa la VM, lo que te permite conectarte directamente al sistema invitado activo a través de SSH.

Habilita la marca de depuración

En tu archivo imagebuilder.yaml, configura debug: true en el bloque infrastructureConfig:

infrastructureConfig:
  machineType: e2-standard-4
  zone: us-central1-a
  # Enable interactive debugging
  debug: true
  instanceDurationHours: 1.5

Activa la compilación y espera a que falle

Envía tu compilación con los métodos estándar. Si la canalización encuentra un error de secuencia de comandos, sucede lo siguiente:

1. El organizador pausa la ejecución de la compilación.
2. Image Builder no borra la VM de trabajador. Permanecerá en ejecución en tu proyecto.
3. La VM permanece activa durante el tiempo especificado en la propiedad instanceDurationHours antes de la finalización automática.

Conéctate a la VM de trabajador para depurar

Consulta el resultado de la consola de Cloud Build para recuperar el nombre de la instancia de VM de trabajador activa. Abre una terminal y conéctate a la VM de trabajador con gcloud compute ssh:

gcloud compute ssh WORKER_VM_NAME \
    --zone=BUILD_ZONE \
    --project=PROJECT_ID

Si tu archivo imagebuilder.yaml configura externalIP: none, lo que no genera una dirección IP externa, incluye la marca --tunnel-through-iap para conectarte con el reenvío de TCP de Identity-Aware Proxy (IAP):

gcloud compute ssh WORKER_VM_NAME \
    --zone=BUILD_ZONE \
    --project=PROJECT_ID \
    --tunnel-through-iap

Una vez que se establezca la conexión, podrás ejecutar comandos en tiempo real, inspeccionar archivos de destino, analizar procesos en ejecución, revisar los registros del historial del instalador y probar modificaciones de secuencias de comandos directamente en el disco.

Analiza imágenes de depuración intermedias

Como alternativa a mantener activa la VM de trabajador con la marca debug, puedes analizar el estado del disco con la imagen de depuración generada automáticamente:

1. Cuando una compilación falla con debug: false (el valor predeterminado), el orquestador exporta el disco de arranque parcialmente personalizado como una imagen de Compute Engine.
2. La imagen de depuración se nombra con el patrón image-builder-debug-image-BUILD_ID y se asigna a la familia de imágenes image-builder-debug-images.

3. Para inspeccionar el sistema de archivos, crea una instancia de VM temporal con esta imagen de depuración como disco de arranque:

   gcloud compute instances create temp-debug-vm \
       --image-family=image-builder-debug-images \
       --zone=ZONE \
       --project=PROJECT_ID
   

4. Conéctate a la instancia temp-debug-vm para inspeccionar el disco y aislar el motivo por el que falló la personalización.

Cómo resolver los tiempos de espera de Cloud Build

Si una ejecución de la canalización de Image Builder tarda más de lo esperado, el trabajo de Cloud Build se detiene y falla con el estado TIMEOUT.

Los tiempos de compilación pueden variar y suelen ser más largos para los tipos de máquinas más grandes, por lo que debes establecer el tiempo de espera para permitir más tiempo para que se complete la compilación. Si no se configura, el tiempo de espera predeterminado de Cloud Build es de 1 hora (3600s).

Para configurar un tiempo de espera más largo, establece el campo timeout en el nivel raíz de tu archivo cloudbuild.yaml:

options:
  automapSubstitutions: true
  requestedVerifyOption: VERIFIED
  substitutionOption: ALLOW_LOOSE
  dynamicSubstitutions: true
  logging: CLOUD_LOGGING_ONLY

# Increase the overall build timeout (for example, 2 hours)
timeout: '7200s'

Después de actualizar el valor de tiempo de espera, vuelve a ejecutar la compilación y verifica que la canalización de Image Builder pueda ejecutarse hasta completarse.

Para obtener más información sobre el parámetro timeout, consulta timeout en la documentación de Cloud Build.