Créer votre propre système d'alerte

Cloud Build peut vous informer des mises à jour de votre état de compilation en vous envoyant des notifications aux canaux souhaité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

• Activer les API Cloud Build, Cloud Run, Pub/Sub, and Secret Manager.

  Activer les API

• 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 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. Par exemple,

   type logger struct {
   	filter notifiers.EventFilter
   }
   

Vous allez ensuite ajouter 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 souhaité.

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

  Dans l'exemple ci-dessous, 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
  }
  

  Maintenant que votre système d'alerte est défini, vous pouvez suivre les étapes ci-dessous pour le configurer.

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 créer un bucket, où BUCKET_NAME est le nom que vous souhaitez attribuer au bucket, sous réserve des règles de dénomination.

      gsutil mb gs://BUCKET_NAME/
      

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

      gsutil 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
      RUN set -x && apt-get update && 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 du 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 utiliser 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 du 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
   

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

Notifications de test

Pour tester la fonctionnalité de notification 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 la fonctionnalité de notification. 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

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