Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Résoudre les problèmes d'échec des pipelines

Linux

Si votre pipeline Image Builder échoue lors de la phase de personnalisation, examinez les fichiers journaux, configurez l'indicateur de débogage interactif sur votre VM de nœud de calcul ou analysez les images de débogage intermédiaires pour identifier les erreurs de compilation ou de script.

Avant de commencer

Si ce n'est pas déjà fait, configurez l'authentification. L'authentification permet de valider votre identité pour accéder aux services et aux API Google Cloud . Pour exécuter du code ou des exemples depuis un environnement de développement local, vous pouvez vous authentifier auprès de Compute Engine en sélectionnant l'une des options suivantes :
1. Installez la Google Cloud CLI. Une fois que la Google Cloud CLI est installée, initialisez-la en exécutant la commande suivante :
```
gcloud init
```
  Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.
  
  Remarque : Si vous avez déjà installé la gcloud CLI, assurez-vous que vous disposez de la dernière version en exécutant gcloud components update.
2. Définissez une région et une zone par défaut.

Examiner les canaux de journalisation

Image Builder écrit des journaux à plusieurs emplacements pour vous aider à diagnostiquer les échecs à différents niveaux de la pile :

Journaux de l'orchestrateur Cloud Build : affichent les étapes de compilation de haut niveau dans la console Cloud Build. Si une étape échoue, un lien vers le répertoire workdir Cloud Storage correspondant est imprimé.
Journaux de l'agent de personnalisation de VM : l'agent de personnalisation capture la sortie standard (stdout) et l'erreur standard (stderr) de vos étapes de personnalisation. L'orchestrateur interroge ces enregistrements et les diffuse directement dans les journaux de trace Cloud Build. Si les journaux sont tronqués ou si vous devez les inspecter en entier, accédez au dossier correspondant à votre ID de compilation dans le bucket _GCS_WORKDIR.
Journaux de la console série : si le système d'exploitation invité ne parvient pas à démarrer, l'agent de personnalisation ne peut pas démarrer. Dans ce cas, consultez les journaux de la console série. L'orchestrateur diffuse la sortie du port série de la VM de nœud de calcul directement dans votre bucket workdir Cloud Storage. Un lien vers le fichier journal série est imprimé à la fin de la trace Cloud Build ayant échoué.
Journaux du système d'exploitation invité : pour résoudre les problèmes au niveau du système sur Linux, l'agent de personnalisation importe une copie complète du journal journal dans votre bucket Cloud Storage workdir à la fin de l'exécution.

Résoudre les échecs de script à l'aide de l'indicateur de débogage

Par défaut, si une étape de personnalisation échoue, Image Builder met fin à l'exécution et supprime immédiatement la VM de nœud de calcul pour contrôler les coûts.

Pour déboguer des scripts de manière interactive, vous pouvez activer le flag debug. La VM reste ainsi active, ce qui vous permet de vous connecter directement au système invité actif à l'aide de SSH.

Activer le flag de débogage

Dans votre fichier imagebuilder.yaml, définissez debug: true sous le bloc infrastructureConfig :

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

Déclencher la compilation et attendre l'échec

Envoyez votre build à l'aide des méthodes standards. Si le pipeline rencontre une erreur de script, les événements suivants se produisent :

L'orchestrateur met en pause l'exécution de la compilation.
Image Builder ne supprime pas la VM de nœud de calcul. Il continue de s'exécuter dans votre projet.
La VM reste active pendant la durée spécifiée dans la propriété instanceDurationHours avant l'arrêt automatique.

Se connecter à la VM du nœud de calcul pour le débogage

Consultez la sortie de la console Cloud Build pour récupérer le nom de l'instance de VM de nœud de calcul active. Ouvrez un terminal et connectez-vous à la VM de nœud de calcul à l'aide de gcloud compute ssh :

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

Si votre fichier imagebuilder.yaml configure externalIP: none, ce qui n'entraîne aucune adresse IP externe, incluez l'indicateur --tunnel-through-iap pour vous connecter à l'aide du transfert TCP d'Identity-Aware Proxy (IAP) :

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

Une fois connecté, vous pouvez exécuter des commandes en temps réel, inspecter les fichiers cibles, analyser les processus en cours d'exécution, examiner les journaux de l'historique du programme d'installation et tester les modifications de script directement sur le disque.

Analyser les images de débogage intermédiaires

Au lieu de maintenir la VM de nœud de calcul active avec le flag debug, vous pouvez analyser l'état du disque à l'aide de l'image de débogage générée automatiquement :

Chaque fois qu'une compilation échoue avec debug: false (valeur par défaut), l'orchestrateur exporte le disque de démarrage partiellement personnalisé en tant qu'image Compute Engine.
L'image de débogage est nommée selon le modèle image-builder-debug-image-BUILD_ID et est attribuée à la famille d'images image-builder-debug-images.
Pour inspecter le système de fichiers, créez une instance de VM temporaire en utilisant cette image de débogage comme disque de démarrage :
```
gcloud compute instances create temp-debug-vm \
    --image-family=image-builder-debug-images \
    --zone=ZONE \
    --project=PROJECT_ID
```
Connectez-vous à l'instance temp-debug-vm pour inspecter le disque et identifier la raison de l'échec de la personnalisation.

Résoudre les problèmes de délai avant expiration de Cloud Build

Si l'exécution d'un pipeline Image Builder prend plus de temps que prévu, le job Cloud Build s'arrête et échoue avec l'état TIMEOUT.

Les temps de compilation peuvent varier et sont généralement plus longs pour les types de machines plus volumineux. Définissez donc le délai avant expiration pour laisser plus de temps à la compilation. Si ce paramètre n'est pas défini, le délai d'expiration Cloud Build par défaut est d'une heure (3600s).

Pour configurer un délai avant expiration plus long, définissez le champ timeout au niveau racine de votre fichier 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'

Après avoir modifié la valeur du délai avant expiration, réexécutez la compilation et vérifiez que le pipeline Image Builder peut s'exécuter jusqu'à la fin.

Pour en savoir plus sur le paramètre timeout, consultez timeout dans la documentation Cloud Build.