Créer votre propre système d'alerte

Cloud Build peut vous informer des mises à jour de l'état de vos compilations en vous envoyant des notifications aux canaux sélectionnés. En plus des systèmes d'alerte gérés par Cloud Build, tels que Slack ou SMTP, vous pouvez également utiliser la bibliothèque fournie dans le dépôt cloud-build-notifiers pour créer votre propre système d'alerte.

Cette page explique comment créer votre propre système d'alerte.

Avant de commencer

• Enable the Cloud Build, Cloud Run, Pub/Sub, and Secret Manager APIs.

  Roles required to enable APIs

  To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

  Enable the APIs

• Installez le langage de programmation Go.

  Remarque : Les systèmes d'alerte Cloud Build sont écrits en Go. Pour créer votre propre système d'alerte à l'aide de la bibliothèque fournie par le dépôt cloud-build-notifiers, vous devez installer Go sur votre ordinateur.

• Installez la Google Cloud CLI.

Configurer

1. Ouvrez une fenêtre de terminal sur votre ordinateur.

2. Clonez et accédez au dépôt cloud-build-notifiers :

     git clone https://github.com/GoogleCloudPlatform/cloud-build-notifiers.git && cd cloud-build-notifiers
   

3. Ajoutez un répertoire pour votre propre système d'alerte et accédez-y, où DIRECTORY_NAME est le nom de votre répertoire :

     mkdir DIRECTORY_NAME && cd DIRECTORY_NAME
   

4. Initialisez les modules go dans votre nouveau répertoire, où DIRECTORY_NAME correspond au nom du nouveau répertoire :

     go mod init github.com/GoogleCloudPlatform/cloud-build-notifiers/DIRECTORY_NAME
   

   Un fichier go.mod doit maintenant s'afficher dans votre répertoire.

5. Ajoutez la ligne suivante à votre fichier go.mod pour vous assurer que vous utilisez la dernière version des systèmes d'alerte :

    replace github.com/GoogleCloudPlatform/cloud-build-notifiers/lib/notifiers => ../
   

Vos dépendances sont maintenant configurées et vous êtes prêt à créer votre propre système d'alerte.

Créer votre propre système d'alerte

Le dépôt cloud-build-notifiers contient un répertoire lib/notifiers. Dans le répertoire lib/notifiers, vous trouverez un fichier nommé notifier.go. Ce fichier contient le framework que vous pouvez utiliser pour créer votre propre système d'alerte.

Vous devrez définir dans votre fichier principal deux méthodes pour créer un système d'alerte.

1. Dans le nouveau répertoire, créez un fichier nommé main.go.

2. Dans main.go, importez le framework de la bibliothèque de systèmes d'alerte et toutes les autres dépendances :

   package main
   
   import (
   	"context"
   	"fmt"
   
   	cbpb "cloud.google.com/go/cloudbuild/apiv1/v2/cloudbuildpb"
   	"github.com/GoogleCloudPlatform/cloud-build-notifiers/lib/notifiers"
   	log "github.com/golang/glog"
   	"google.golang.org/protobuf/encoding/prototext"
   )
   

3. Définissez une méthode "main" pour votre système d'alerte. Dans cet exemple, logger correspond au nom du système d'alerte :

   func main() {
   	if err := notifiers.Main(new(logger)); err != nil {
   		log.Fatalf("fatal error: %v", err)
   	}
   }
   

   La méthode main utilise la méthode Main définie dans le fichier notifier.go, qui permet de configurer les fichiers binaires du système d'alerte.

4. Définissez une structure pour votre système d'alerte, où vous définirez les variables de votre interface. Dans cet exemple, logger correspond au nom du système d'alerte :

   type logger struct {
   	filter notifiers.EventFilter
   }
   

5. Ajoutez la fonctionnalité de système d'alerte. L'interface du système d'alerte est définie par deux méthodes :

   • SetUp : la méthode SetUp accepte une configuration, récupère les secrets, et extrait de la configuration les filtres spécifiés pour les stocker en tant que prédicat CEL (Common Expression Language) pouvant être utilisé pour envoyer des notifications. Pour en savoir plus sur le langage CEL, consultez le dépôt cel-spec.

   • SendNotification : la méthode SendNotification permet d'envoyer des notifications au canal ou au service sélectionné.

     La définition du système d'alerte est disponible dans notifier.go et dans la documentation Go.

     Dans l'exemple suivant, l'interface du système d'alerte est définie à l'aide des méthodes SetUp et SendNotification pour imprimer les journaux de compilation, avec logger comme nom de votre système d'alerte :

     func (h *logger) SetUp(_ context.Context, cfg *notifiers.Config, _ notifiers.SecretGetter, _ notifiers.BindingResolver) error {
     	prd, err := notifiers.MakeCELPredicate(cfg.Spec.Notification.Filter)
     	if err != nil {
     		return fmt.Errorf("failed to create CELPredicate: %w", err)
     	}
     	h.filter = prd
     	return nil
     }
     
     func (h *logger) SendNotification(ctx context.Context, build *cbpb.Build) error {
     	// Include custom functionality here.
     	// This example logs the build.
     	if h.filter.Apply(ctx, build) {
     		log.V(1).Infof("printing build\n%s", prototext.Format(build))
     	} else {
     		log.V(1).Infof("build (%q, %q) did NOT match CEL filter", build.ProjectId, build.Id)
     	}
     
     	return nil
     }
     

     Votre fichier main.go final doit ressembler au fichier suivant. Dans cet exemple, logger est utilisé comme nom du système d'alerte.

     package main
     
     import (
     	"context"
     	"fmt"
     
     	cbpb "cloud.google.com/go/cloudbuild/apiv1/v2/cloudbuildpb"
     	"github.com/GoogleCloudPlatform/cloud-build-notifiers/lib/notifiers"
     	log "github.com/golang/glog"
     	"google.golang.org/protobuf/encoding/prototext"
     )
     
     
     func main() {
     	if err := notifiers.Main(new(logger)); err != nil {
     		log.Fatalf("fatal error: %v", err)
     	}
     }
     
     
     type logger struct {
     	filter notifiers.EventFilter
     }
     
     
     func (h *logger) SetUp(_ context.Context, cfg *notifiers.Config, _ notifiers.SecretGetter, _ notifiers.BindingResolver) error {
     	prd, err := notifiers.MakeCELPredicate(cfg.Spec.Notification.Filter)
     	if err != nil {
     		return fmt.Errorf("failed to create CELPredicate: %w", err)
     	}
     	h.filter = prd
     	return nil
     }
     
     func (h *logger) SendNotification(ctx context.Context, build *cbpb.Build) error {
     	// Include custom functionality here.
     	// This example logs the build.
     	if h.filter.Apply(ctx, build) {
     		log.V(1).Infof("printing build\n%s", prototext.Format(build))
     	} else {
     		log.V(1).Infof("build (%q, %q) did NOT match CEL filter", build.ProjectId, build.Id)
     	}
     
     	return nil
     }
     

   Configurez ensuite votre système d'alerte.

Configurer les notifications

1. Rédigez un fichier de configuration du système d'alerte pour configurer votre système d'alerte et filtrer les événements de compilation :

   Dans l'exemple de fichier de configuration du système d'alerte suivant, le champ filter utilise le langage CEL avec la variable disponible, build, pour filtrer les événements de compilation à l'état SUCCESS :

   apiVersion: cloud-build-notifiers/v1
   kind: YourNotifier
   metadata:
     name: logging-sample
   spec:
     notification:
       filter: build.status == Build.Status.SUCCESS

   Où :

   • logging-sample correspond au nom du système d'alerte.

   Pour en savoir plus sur les champs supplémentaires que vous pouvez filtrer, consultez la ressource Build. Pour obtenir d'autres exemples de filtrage, consultez la section Utiliser le CEL pour filtrer les événements de compilation.

2. Importez votre fichier de configuration du système d'alerte dans un bucket Cloud Storage :

   1. Si vous n'avez pas de bucket Cloud Storage, exécutez la commande suivante pour en créer un, où BUCKET_NAME est le nom que vous souhaitez attribuer au bucket, sous réserve des règles de dénomination.

      gcloud storage buckets create gs://BUCKET_NAME/
      

   2. Importez le fichier de configuration du système d'alerte dans votre bucket :

      gcloud storage cp CONFIG_FILE_NAME gs://BUCKET_NAME/CONFIG_FILE_NAME
      

      Où :

      • BUCKET_NAME est le nom du bucket.
      • CONFIG_FILE_NAME est le nom de votre fichier de configuration.

3. Compilez et déployez votre système d'alerte :

   1. Créez un fichier Dockerfile pour logging-sample :

      
      FROM golang AS build-env
      COPY . /go-src/
      WORKDIR /go-src/
      RUN go build -o /go-app .
      
      # From the Cloud Run docs:
      # https://cloud.google.com/run/docs/tutorials/pubsub#looking_at_the_code
      # Use the official Debian slim image for a lean production container.
      # https://hub.docker.com/_/debian
      # https://docs.docker.com/develop/develop-images/multistage-build/#use-multi-stage-builds
      FROM debian:buster-slim
      # Modify sources.list to point to the Debian archive
      RUN sed -i 's|deb.debian.org|archive.debian.org|g' /etc/apt/sources.list && \
          sed -i 's|security.debian.org|archive.debian.org/debian-security|g' /etc/apt/sources.list && \
          sed -i '/buster-updates/d' /etc/apt/sources.list && \
          echo "deb http://archive.debian.org/debian buster-updates main contrib non-free" >> /etc/apt/sources.list && \
          set -x && \
          apt-get update --allow-releaseinfo-change && \
          DEBIAN_FRONTEND=noninteractive apt-get install -y ca-certificates && \
          rm -rf /var/lib/apt/lists/*
      
      
      FROM gcr.io/distroless/base
      COPY --from=build-env /go-app /
      ENTRYPOINT ["/go-app", "--v=1", "--alsologtostderr"]
      

   2. Compilez et déployez le système d'alerte à l'aide du fichier cloudbuild.yaml suivant.

      steps:
      - # Build the binary and put it into the builder image.
        name: gcr.io/cloud-builders/docker
        args: ['build', '--tag=gcr.io/$PROJECT_ID/logging-sample', '.']
      
      - # Push the container image to Container Registry
        name: gcr.io/cloud-builders/docker
        args: ['push', 'gcr.io/$PROJECT_ID/logging-sample']
      
      - # Deploy to Cloud Run
        name: google/cloud-sdk
        args: 
          - gcloud
          - run
          - deploy
          - logging-sample-notifier
          - --platform=managed
          - --region=us-central1
          - --image=gcr.io/$PROJECT_ID/logging-sample
          - --no-allow-unauthenticated
          - --update-env-vars=CONFIG_PATH=${_CONFIG_PATH}
      
      # Push the image with tags.
      images:
      - gcr.io/$PROJECT_ID/logging-sample

      Où :

      • _CONFIG_PATH est le chemin d'accès à la configuration de votre système d'alerte, tel que gs://BUCKET_NAME/CONFIG_FILE_NAME.yaml.

   Pour exécuter le fichier cloudbuild.yaml, transmettez le chemin d'accès au système d'alerte en tant que variable de substitution.

    gcloud builds submit .  --substitutions=_CONFIG_PATH=gs://BUCKET_NAME/CONFIG_FILE_NAME
   

   Remarque : Cloud Build héberge les images de système d'alerte existantes dans Artifact Registry. Étant donné que vous créez votre propre système d'alerte plutôt que d'utiliser l'un des hôtes Cloud Build, vous devez compiler votre système d'alerte pour en créer une image. Pour consulter un exemple de fichier cloudbuild.yaml correspondant à un autre type de système d'alerte, tel que le système d'alerte pour slack, consultez la section buildtest.cloudbuild.yaml. Pour consulter un exemple de fichier Dockerfile utilisé dans le fichier buildtest.cloudbuild.yaml, consultez la section Dockerfile.

4. Accordez des autorisations Pub/Sub pour créer des jetons d'authentification dans votre projet :

    gcloud projects add-iam-policy-binding PROJECT_ID \
      --member=serviceAccount:[e-mail] \
      --role=roles/iam.serviceAccountTokenCreator
   

   Où :

   • PROJECT_ID est l'ID de votre projet Google Cloud  ;
   • PROJECT_NUMBER est le numéro de votre projet Google Cloud .

5. Créez un compte de service pour représenter l'identité de votre abonnement Pub/Sub :

   gcloud iam service-accounts create cloud-run-pubsub-invoker \
     --display-name "Cloud Run Pub/Sub Invoker"
   

   Vous pouvez utiliser cloud-run-pubsub-invoker ou un nom unique dans votre projet Google Cloud .

6. Accordez au compte de service cloud-run-pubsub-invoker l'autorisation Cloud Run Invoker :

   gcloud run services add-iam-policy-binding SERVICE_NAME \
      --member=serviceAccount:cloud-run-pubsub-invoker@PROJECT_ID.iam.gserviceaccount.com \
      --role=roles/run.invoker
   

   Où :

   • SERVICE_NAME correspond au nom du service Cloud Run dans lequel vous déployez l'image.
   • PROJECT_ID est l'ID de votre projet Google Cloud  ;

7. Créez le sujet cloud-builds pour recevoir des messages de mise à jour de compilation pour votre système d'alerte :

   gcloud pubsub topics create cloud-builds
   

   Vous pouvez également définir un nom de sujet personnalisé dans votre fichier de configuration de compilation afin que les messages soient envoyés à ce sujet personnalisé. Dans ce cas, vous devez créer un sujet portant le même nom de sujet personnalisé :

   gcloud pubsub topics create topic-name
   

   Pour en savoir plus, consultez Sujets Pub/Sub pour les notifications de compilation.

8. Créez un abonné push Pub/Sub pour votre système d'alerte :

    gcloud pubsub subscriptions create subscriber-id \
      --topic=cloud-builds \
      --push-endpoint=service-url \
      --push-auth-service-account=[e-mail]
   

   Où :

   • subscriber-id est le nom que vous souhaitez donner à votre abonnement.
   • service-url est l'URL générée par Cloud Run pour votre nouveau service.
   • project-id est l'ID de votre projet Google Cloud  ;

Les notifications pour votre projet Cloud Build sont maintenant configurées. Vous recevrez une notification dans votre canal la prochaine fois que vous appellerez une compilation correspondant au filtre que vous avez configuré.

Tester les notifications

Pour tester les notifications de l'exemple utilisé dans ce guide, vous pouvez appeler une compilation en exécutant la commande gcloud builds submit.

Dans l'exemple suivant, nous spécifions success.yaml comme chemin de configuration. L'exécution de cette commande devrait entraîner une compilation minimale réussie. Vous devriez également voir une sortie de vos journaux de compilation.

 gcloud builds submit --no-source --config=success.yaml

Où success.yaml correspond à :

 steps:
 - name: busybox
   args: ["true"]

Dans l'exemple suivant, nous spécifions failure.yaml comme chemin de configuration. L'exécution de cette commande doit entraîner l'échec de la compilation. Au lieu de voir la sortie de vos journaux de compilation, un résultat vous informe qu'il n'y a pas de correspondance pour les filtres CEL spécifiés dans votre source.

gcloud builds submit --no-source --config=failure.yaml

Où failure.yaml correspond à :

 steps:
 - name: busybox
   args: ["false"]

Si vous avez créé un système d'alerte configuré pour effectuer une tâche autre que consigner la sortie dans les journaux de service Cloud Run, vous pouvez également exécuter la commande gcloud builds submit pour tester vos notifications. Pour examiner les erreurs associées à votre compilation, consultez les journaux Cloud Run de votre service. Pour en savoir plus, consultez la section Afficher les journaux dans Cloud Run.

Étapes suivantes

• En savoir plus sur les systèmes d'alerte Cloud Build
• Découvrez comment vous abonner aux notifications de compilation.