Stocker et gérer les journaux de compilation

Lorsque vous exécutez des compilations, Cloud Build collecte et stocke vos journaux de compilation. Cette page explique comment stocker, afficher et supprimer des journaux de compilation.

Choisir où stocker les journaux de compilation

Vous pouvez configurer Cloud Build pour stocker les journaux de compilation dans Cloud Logging ou dans Cloud Storage en incluant le champ logging dans votre fichier de configuration Cloud Build. Si vous ne spécifiez pas de champ logging dans votre fichier de configuration de compilation, Cloud Build stocke les journaux de compilation à la fois dans Logging et Cloud Storage.

Les étapes suivantes ne stockent les journaux de compilation que dans Logging:

1. Dans votre fichier de configuration de compilation, définissez la valeur logging sur CLOUD_LOGGING_ONLY:

   YAML

   steps:
   - name: 'gcr.io/cloud-builders/docker'
     args: ['build', '-t', 'us-east1-docker.pkg.dev/myproject/myimage', '.']
   options:
     logging: CLOUD_LOGGING_ONLY
   

   JSON

   {
     "steps": [
     {
       "name": "gcr.io/cloud-builders/docker",
       "args": [
         "build",
         "-t",
         "us-east1-docker.pkg.dev/myproject/myimage",
         "."
       ]
     }
     ],
     "options": {
       "logging": "CLOUD_LOGGING_ONLY"
     }
   }
   

2. Utilisez le fichier de configuration de compilation pour démarrer une compilation à l'aide de la ligne de commande, de l'API ou des déclencheurs.

Mappage des champs de journal de compilation sur les champs d'entrée de journal

Vous pouvez configurer le fichier JSON de vos journaux de compilation afin que les champs de journal de compilation spécifiés soient mappés sur les champs LogEntry lorsque le journal de compilation est envoyé à Logging. Par exemple, si votre journal de compilation contient un message, le message s'affiche dans textPayload ou jsonPayload.message dans l'entrée de journal générée. Les champs de journal de compilation qui ne peuvent pas être mappés apparaissent dans l'entrée de journal jsonPayload.

Pour activer le mappage des champs dans vos journaux de compilation, définissez le champ enableStructuredLogging de BuildOptions sur TRUE.

Le tableau suivant présente les champs de journal de compilation qui sont mappés à un champ d'entrée de journal:

Champ BuildLog (JSON)	Champ LogEntry	Description	Remarques
message	textPayload ou jsonPayload.message	Permet aux utilisateurs de définir le message de journal	Doit être une chaîne. Si le journal de compilation ne contient que des champs mappables, le message s'affiche dans textPayload. Sinon, le message s'affiche dans jsonPayload.message. Si le journal de compilation contient plusieurs étapes, l'identifiant de l'étape s'affiche au début du message.
severity	severity	Permet aux utilisateurs de définir le niveau de gravité des journaux.	Doit être un énumération de LogSeverity.

Les champs de journal de compilation suivants ne peuvent pas être mappés et seront supprimés de l'entrée de journal s'ils apparaissent dans un journal de compilation:

• httpRequest
• logging.googleapis.com/insertId
• logging.googleapis.com/labels
• logging.googleapis.com/operation
• logging.googleapis.com/sourceLocation
• logging.googleapis.com/spanId
• logging.googleapis.com/trace
• logging.googleapis.com/trace_sampled
• time
• timestamp
• timestampSeconds
• timestampNanos

Tous les autres champs du journal de compilation apparaîtront dans jsonPayload de l'entrée de journal.

Stocker les journaux de compilation dans le bucket par défaut créé par Google

Par défaut, Cloud Build stocke vos journaux de compilation dans un bucket Cloud Storage créé par Google. Vous pouvez afficher les journaux de compilation stockés dans le bucket Cloud Storage créé par Google, mais vous ne pouvez pas y apporter d'autres modifications. Si vous avez besoin d'exercer un contrôle total sur votre bucket de journaux, stockez-les dans un bucket Cloud Storage créé par l'utilisateur.

Stocker des journaux de compilation dans un bucket créé par l'utilisateur

Autorisations IAM :

Pour stocker les journaux de compilation dans votre propre bucket Cloud Storage, vous devez d'abord accorder les autorisations IAM nécessaires au compte de service que vous utilisez pour la compilation:

• Si votre bucket Cloud Storage et Cloud Build se trouvent dans le même projet Google Cloud et que vous utilisez l'ancien compte de service Cloud Build, il dispose par défaut des autorisations IAM nécessaires. Aucune autorisation supplémentaire n'est requise.

• Dans le cas contraire, attribuez le rôle Storage Admin au compte de service que vous utilisez pour la compilation:

  1. Ouvrez la page "IAM" du projet dans lequel se trouve votre bucket Cloud Storage :

     Ouvrir la page IAM

  2. Cliquez sur Accorder l'accès.

  3. Saisissez l'adresse e-mail du compte de service.

  4. Sélectionnez Cloud Storage > Administrateur de l'espace de stockage.

  5. Cliquez sur Enregistrer.

Pour spécifier un bucket Cloud Storage où stocker les journaux de compilation, suivez les étapes suivantes :

1. Dans votre projet Google Cloud, créez un bucket Cloud Storage sans règle de conservation définie pour stocker vos journaux de compilation.

2. Dans votre fichier de configuration de compilation, ajoutez un champ logsBucket pointant vers le bucket Cloud Storage que vous avez créé pour stocker les journaux de compilation. Voici un exemple de fichier de configuration de compilation contenant des instructions pour créer une image de conteneur et stocker les journaux de compilation dans le bucket nommé mylogsbucket :

   YAML

       steps:
       - name: 'gcr.io/cloud-builders/docker'
         args: [ 'build', '-t', 'us-east1-docker.pkg.dev/myproject/myimage', '.' ]
       logsBucket: 'gs://mylogsbucket'
       options:
         logging: GCS_ONLY
   

   JSON

       {
         "steps": [
          {
            "name": "gcr.io/cloud-builders/docker",
            "args": [
              "build",
              "-t",
              "us-east1-docker.pkg.dev/myproject/myimage",
              "."
            ]
          }
          ],
          "logsBucket": "gs://mylogsbucket",
          "options": {
            "logging": "GCS_ONLY"
          }
       }
   

3. Utilisez le fichier de configuration de compilation pour démarrer une compilation à l'aide de la ligne de commande, de l'API ou des déclencheurs.

Une fois la compilation terminée, Cloud Build stockera les journaux dans le bucket Cloud Storage que vous avez spécifié dans le fichier de configuration de compilation.

Stocker les journaux de compilation dans un bucket régionalisé appartenant à l'utilisateur

Par défaut, Cloud Build stocke les journaux de compilation dans une région spécifiée par Google, qui peut être différente de l'emplacement où vous exécutez une compilation. L'option defaultLogsBucketBehavior vous permet de configurer Cloud Build pour qu'il utilise un bucket de journaux par défaut dans votre propre projet et dans la même région que la compilation. Cette configuration vous permet de mieux contrôler l'emplacement des données de vos journaux, ce qui peut vous aider à respecter les exigences de résidence des données.

Des frais seront facturés pour le stockage des journaux dans votre propre projet. Pour en savoir plus sur les tarifs, consultez la page Tarifs de Cloud Storage.

Configurez Cloud Build pour utiliser des journaux régionalisés appartenant à l'utilisateur:

1. Accordez les autorisations IAM nécessaires.

   • Si vous utilisez l'ancien compte de service Cloud Build, il dispose par défaut des autorisations IAM nécessaires. Aucune autorisation supplémentaire n'est requise.

   • Pour les autres comptes de service, attribuez le rôle Storage Admin au compte de service que vous utilisez pour la compilation. Pour savoir comment attribuer un rôle à un compte de service, consultez la page Attribuer des rôles au projet.

2. Dans votre fichier de configuration de compilation, ajoutez l'option defaultLogsBucketBehavior et définissez sa valeur sur REGIONAL_USER_OWNED_BUCKET:

   YAML

   steps:
   - name: 'gcr.io/cloud-builders/docker'
     args: [ 'build', '-t', 'us-central1-docker.pkg.dev/myproject/myrepo/myimage', '.' ]
   options:
     defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET
   

   JSON

   {
     "steps": [
       {
         "name": "gcr.io/cloud-builders/docker",
         "args": [
           "build",
           "-t",
           "us-central1-docker.pkg.dev/myproject/myrepo/myimage",
           "."
         ]
       }
       ],
       "options": {
         "defaultLogsBucketBehavior": "REGIONAL_USER_OWNED_BUCKET"
       }
   }
   

3. Utilisez le fichier de configuration de compilation pour démarrer une compilation à l'aide de la ligne de commande, de l'API ou des déclencheurs.

   Lorsque vous exécutez votre compilation, Cloud Build crée le nouveau bucket de journaux dans la région où vous exécutez votre compilation, puis stocke les journaux de compilation dans ce bucket. Les builds suivants dans le même projet et la même région utiliseront le bucket existant par défaut.

Si vous définissez l'option defaultLogsBucketBehavior, puis créez des compilations dans plusieurs régions, Cloud Build crée plusieurs buckets pour vos journaux de compilation.

Les journaux de compilation régionalisés stockés dans votre propre projet ne sont soumis à aucune règle de conservation. Ce paramètre est immuable.

Priorité entre les paramètres de journaux

Si vous ajoutez l'option defaultLogsBucketBehavior à un fichier de configuration de compilation existant et que vous avez déjà configuré les options logging ou logsBucket, nous vous recommandons de supprimer ces paramètres pour éviter les conflits.

Plus précisément, defaultLogsBucketBehavior ne fonctionnera pas si vous avez configuré les éléments suivants:

• logging: CLOUD_LOGGING_ONLY pour stocker vos journaux de compilation dans Cloud Logging.
• logging: NONE pour désactiver la journalisation.

Lorsque vous exécutez une compilation sans options de journalisation définies dans votre configuration de compilation, Cloud Build définit logging: LEGACY et stocke les journaux dans le bucket Cloud Storage par défaut créé par Google. Si vous ajoutez defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET, cette option remplace logging: LEGACY.

Afficher les journaux de compilation

Autorisations IAM :

• Si vos journaux de compilation se trouvent dans Logging, attribuez le rôle Lecteur de journaux au projet sur lequel la compilation est configurée pour les comptes principaux qui souhaitent afficher les journaux de compilation:

  1. Ouvrez la page "IAM" :

     Ouvrir la page IAM

  2. Sélectionnez votre projet et cliquez sur Ouvrir.

  3. Dans le tableau des autorisations, recherchez l'ID de l'adresse e-mail du compte principal et cliquez sur l'icône en forme de crayon.

  4. Sélectionnez le rôle Logging > Lecteur de journaux.

  5. Cliquez sur Enregistrer.

• Si vos journaux de compilation se trouvent dans le bucket Cloud Storage par défaut créé par Google, accordez le rôle Lecteur de projet au projet sur lequel la compilation est configurée pour les comptes principaux qui souhaitent afficher les journaux de compilation:

  1. Ouvrez la page "IAM" :

     Ouvrir la page IAM

  2. Sélectionnez votre projet et cliquez sur Ouvrir.

  3. Dans le tableau des autorisations, recherchez l'ID de l'adresse e-mail du compte principal et cliquez sur l'icône en forme de crayon.

  4. Sélectionnez le rôle Projet > Lecteur.

  5. Cliquez sur Enregistrer.

  Remarque :Les rôles de propriétaire et d'éditeur de projet permettent également aux comptes principaux d'afficher les journaux de compilation du bucket Cloud Storage par défaut. En effet, le rôle "Propriétaire" inclut les autorisations du rôle "Éditeur", qui inclut lui-même les autorisations du rôle "Lecteur". Pour afficher les journaux de compilation dans le bucket Cloud Storage par défaut, nous vous recommandons d'attribuer le rôle de lecteur de projet pour qu'il soit conforme au principe de sécurité du moindre privilège.
  Remarque :Pour éviter d'accorder le rôle de lecteur de projet de base, stockez les journaux de compilation dans un bucket spécifié par l'utilisateur. Nous vous recommandons cette pratique, en particulier si vos compilations sont appelées à l'aide de déclencheurs et que vous souhaitez uniquement accorder des autorisations d'accès pour appeler des compilations et afficher leur progression.

  Si vos journaux de compilation se trouvent dans un bucket Cloud Storage créé ou détenu par l'utilisateur, attribuez le rôle Lecteur des objets de l'espace de stockage aux comptes principaux qui souhaitent les consulter:

  1. Ouvrez la page "IAM" :

     Ouvrir la page IAM

  2. Sélectionnez votre projet et cliquez sur Ouvrir.

  3. Dans le tableau des autorisations, recherchez l'ID de l'adresse e-mail du compte principal et cliquez sur l'icône en forme de crayon.

  4. Sélectionnez le rôle Cloud Storage > Lecteur des objets de l'espace de stockage.

  5. Cliquez sur Enregistrer.

Pour afficher les journaux de compilation dans Cloud Build:

Console

1. Ouvrez la page Cloud Build dans la console Google Cloud.

   Ouvrir la page Cloud Build

2. Sélectionnez votre projet et cliquez sur Ouvrir.

3. Dans le menu déroulant Région, sélectionnez la région pour votre build.

4. Sur la page Historique de compilation, cliquez sur une compilation spécifique.

5. Sur la page Informations sur le build, sous Steps (Étapes), cliquez sur Build summary (Résumé de la compilation) pour afficher tout le journal de la compilation ou cliquez sur une étape spécifique de compilation pour consulter son journal.

   

6. Si vos journaux sont stockés dans Logging, dans le panneau Journaux de compilation, cliquez sur l'icône pour les afficher dans l'explorateur de journaux.

   

gcloud

Exécutez la commande gcloud builds log, où build-id correspond à l'ID de la compilation pour laquelle vous souhaitez obtenir des journaux de compilation. L'ID de compilation s'affiche à la fin du processus lorsqu'une demande de compilation est envoyée à l'aide de la commande gcloud builds submit, ou dans la colonne ID lorsque vous exécutez la commande gcloud builds list.

gcloud builds log build-id

Pour afficher les journaux de compilation dans GitHub et GitHub Enterprise:

Si vous créez un déclencheur GitHub ou GitHub Enterprise et que vous spécifiez --include-logs-with-status comme option, vous pouvez afficher vos journaux de compilation dans GitHub et GitHub Enterprise.

Pour afficher les journaux de compilation dans GitHub et GitHub Enterprise:

1. Accédez au dépôt associé à votre déclencheur.

2. Accédez à votre liste de commits.

3. Recherchez la ligne du commit pour lequel vous souhaitez afficher les journaux de compilation.

4. Cliquez sur l'icône de résultat dans la ligne de votre commit.

   Une liste des vérifications associées à votre commit s'affiche.

5. Cliquez sur Détails pour la ligne pour laquelle vous souhaitez afficher les journaux de compilation.

   La page Récapitulatif associée à votre commit s'affiche. Si vous avez créé un déclencheur à l'aide de l'indicateur --include-logs-with-status, vos journaux de compilation s'affichent dans la section Details (Détails) de la page.

Remarque :Le compte de service que vous avez utilisé pour le déclencheur doit inclure le rôle roles/logging.viewer pour pouvoir envoyer les journaux de compilation à GitHub.

Supprimer des journaux de compilation

Vous ne pouvez pas supprimer les journaux de compilation dans le bucket de journaux créé par Google.

Pour supprimer des journaux de compilation dans un bucket de journaux créé par l'utilisateur, procédez comme suit :

1. Attribuez le rôle Administrateur des objets de l'espace de stockage à l'utilisateur ou au compte de service qui supprime les journaux.

2. Supprimez les journaux de compilation en suivant les instructions de suppression des objets Cloud Storage de la section Supprimer des objets.

Pour supprimer le bucket de journaux créé par l'utilisateur, procédez comme suit :

1. Attribuez le rôle Administrateur de l'espace de stockage à l'utilisateur ou au compte de service qui supprime le bucket de journaux.

2. Supprimez le bucket de journaux en suivant les instructions de suppression de bucket de la section Supprimer des buckets.

Étape suivante

• Découvrez les journaux d'audit créés par Cloud Build.
• Découvrez comment afficher les résultats de la compilation.
• Apprenez-en plus sur les autorisations IAM pour Cloud Build.