Créer votre propre système d'alerte

Cloud Build peut vous informer des mises à jour de l'état de la compilation en vous envoyant des notifications sur les canaux souhaités. Outre les notifications gérées par Cloud Build, telles que Slack ou SMTP, vous pouvez également utiliser la bibliothèque fournie dans le 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.

  • Installez le SDK Cloud.

Configuration

  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 => ../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 "google.golang.org/genproto/googleapis/devtools/cloudbuild/v1"
            log "github.com/golang/glog"
            "github.com/GoogleCloudPlatform/cloud-build-notifiers/lib/notifiers"
            "github.com/golang/protobuf/proto"
    )
  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 des systèmes 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", proto.MarshalTextString(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 "google.golang.org/genproto/googleapis/devtools/cloudbuild/v1"
            log "github.com/golang/glog"
            "github.com/GoogleCloudPlatform/cloud-build-notifiers/lib/notifiers"
            "github.com/golang/protobuf/proto"
    )
    
    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", proto.MarshalTextString(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
    
  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:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
       --role=roles/iam.serviceAccountTokenCreator
    

    Où :

    • PROJECT_ID est l'ID de votre projet Cloud.
    • PROJECT_NUMBER est le numéro de votre projet 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 de votre projet Cloud.
  7. Lorsque vous activez l'API Pub/Sub, le sujet cloud-builds créé automatiquement doit s'afficher sur la page Sujets Pub/Sub. Si le sujet cloud-builds ne s'affiche pas, exécutez la commande suivante pour le créer manuellement afin de recevoir les 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=cloud-run-pubsub-invoker@PROJECT_ID.iam.gserviceaccount.com
    

    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 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

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

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.

Étape suivante