Créer des déclencheurs avec Eventarc

Cette page explique comment créer un déclencheur Eventarc pour qu'un service Cloud Run puisse recevoir des événements provenant d'un autre service Google Cloud .

Eventarc est un service Google Cloudqui vous permet de créer des architectures basées sur des événements sans avoir à implémenter, à personnaliser ni à gérer l'infrastructure sous-jacente.

Vous pouvez créer un déclencheur Eventarc en spécifiant des filtres pour le déclencheur et en configurant le routage de l'événement, y compris la source de l'événement et le service Cloud Run cible. Lorsque l'événement ou l'ensemble d'événements spécifiés correspondent aux filtres, votre service Cloud Run est automatiquement appelé en réponse aux événements. Un service qui utilise des déclencheurs Eventarc est appelé un service événementiel. Les événements envoyés à votre service Cloud Run sont reçus sous la forme de requêtes HTTP.

Les requêtes adressées à votre service peuvent être déclenchées par les types d'événements suivants :

Emplacement du déclencheur

Lorsque vous créez un déclencheur Eventarc, vous spécifiez un emplacement pour celui-ci. Il doit correspondre à l'emplacement de la ressource Google Cloud dont vous souhaitez surveiller les événements. Dans la plupart des scénarios, vous devez également déployer votre service Cloud Run événementiel dans la même région. Pour plus d'informations, voir Comprendre les emplacements Eventarc.

Identité du déclencheur

Lorsque vous créez un déclencheur Eventarc, vous spécifiez un compte de service Identity and Access Management (IAM) pour celui-ci. Le déclencheur utilise ce compte de service comme identité par défaut. Nous vous recommandons de spécifier un compte de service géré par l'utilisateur et de lui accorder les autorisations minimales requises.

Avant de commencer

  1. Configurez votre environnement Cloud Run.

  2. Activez les API Artifact Registry, Cloud Build, Cloud Run Admin et Eventarc :

    Activer les API

  3. Accorder les rôles et autorisations IAM requis.

Créer un déclencheur pour les services

Après avoir déployé un service, vous pouvez configurer un déclencheur à l'aide de la console Google Cloud , de Google Cloud CLI ou de Terraform.

Console

  1. Déployez votre service Cloud Run à l'aide de conteneurs ou à partir d'une source.

  2. Dans le Google Cloud console, allez àCloud Run :

    Accédez à Cloud Run

  3. Dans la liste des services, cliquez sur un service existant.

  4. Sur la page d'informations sur le service, accédez à l'onglet Déclencheurs.

  5. Cliquez sur  Ajouter un déclencheur, puis sélectionnez une option.

  6. Dans le volet Déclencheur Eventarc, modifiez les détails du déclencheur comme suit :

    1. Dans le champ Nom du déclencheur, entrez un nom pour le déclencheur ou utilisez le nom par défaut.

    2. Sélectionnez un Trigger type dans la liste pour spécifier l'un des types de déclencheurs suivants :

      • Sources Google pour spécifier des déclencheurs pour Pub/Sub, Cloud Storage, Firestore et d'autres fournisseurs d'événements Google.

      • Tiers pour intégrer des fournisseurs autres que Google qui proposent une source Eventarc. Pour en savoir plus, consultez Événements tiers dans Eventarc.

    3. Sélectionnez un fournisseur d'événements dans la liste Fournisseur d'événements pour choisir un produit qui fournit le type d'événement pour déclencher votre service. Pour obtenir la liste des fournisseurs d'événements, consultez Fournisseurs et destinations d'événements.

    4. Sélectionnez un type d'événement dans la liste Type d'événement. La configuration du déclencheur varie en fonction du type d'événement accepté: Pour en savoir plus, consultez Types d'événements.

    5. Si le champ Région est activé, sélectionnez un emplacement pour le déclencheur Eventarc. En général, l'emplacement d'un déclencheur Eventarc doit correspondre à celui de la ressource Google Cloud dont vous souhaitez surveiller les événements. Dans la plupart des scénarios, vous devez également déployer votre service dans la même région. Consultez la section Comprendre les emplacements Eventarc pour en savoir plus sur les emplacements des déclencheurs Eventarc.

    6. Dans le champ Compte de service, sélectionnez un compte de service. Les déclencheurs Eventarc sont associés à des comptes de service, destinés à être utilisés comme identité lors de l'appel de votre service. Le compte de service de votre déclencheur Eventarc doit être autorisé à appeler votre service. Par défaut, Cloud Run utilise le compte de service Compute Engine par défaut.

    7. Vous pouvez éventuellement spécifier le chemin d'URL du service auquel envoyer la requête entrante. Il s'agit du chemin relatif sur le service de destination auquel les événements du déclencheur doivent être envoyés. Par exemple: /, /route, route et route/subroute.

    8. Si vous le souhaitez, cochez la case Activer la nouvelle tentative en cas d'échec pour activer les nouvelles tentatives en cas d'échec de la remise. Sinon, le comportement par défaut est une seule tentative de remise sans nouvelle tentative. Pour en savoir plus, consultez Événements de nouvelle tentative.

    9. Une fois les champs obligatoires renseignés, cliquez sur Enregistrer le déclencheur.

  7. Après avoir créé le déclencheur, vous pouvez vérifier son état en vous assurant qu'une coche s'affiche dans l'onglet Déclencheurs.

gcloud

  1. Déployez votre service Cloud Run à l'aide de conteneurs ou à partir d'une source.

  2. Exécutez la commande suivante pour créer un déclencheur qui filtre et achemine les événements :

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=LOCATION \
    --destination-run-service=DESTINATION_RUN_SERVICE  \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --max-retry-attempts=1 \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Remplacez les éléments suivants :

    • TRIGGER_NAME : l'ID du déclencheur ou un identifiant complet.
    • LOCATION : l'emplacement du déclencheur Eventarc. Vous pouvez également définir la propriété eventarc/location (par exemple, gcloud config set eventarc/location us-central1).

      Pour éviter tout problème de performances et de résidence des données, l'emplacement doit correspondre à celui du service Google Cloud qui génère les événements. Pour en savoir plus, consultez la page Emplacements Eventarc.

    • DESTINATION_RUN_SERVICE  : nom du service Cloud Run qui reçoit les événements pour le déclencheur. Le service peut se trouver dans l'un des emplacements compatibles avec Cloud Run et ne doit pas nécessairement se trouver au même emplacement que le déclencheur. Cependant, le service doit se trouver dans le même projet que le déclencheur et recevoir des événements sous forme de requêtes HTTP POST envoyées à son chemin d'URL racine (/), à chaque déclenchement de l'événement.
    • DESTINATION_RUN_REGION : (facultatif) emplacement Cloud Run dans lequel se trouve le service Cloud Run de destination. Si elle n'est pas spécifiée, il est supposé que le service se trouve dans la même région que le déclencheur.
    • EVENT_FILTER_TYPE : identifiant de l'événement. Un événement est généré lorsqu'un appel d'API pour la méthode réussit. Pour les opérations de longue durée, l'événement n'est généré qu'à la fin de l'opération et uniquement si l'action s'est bien déroulée. Pour obtenir la liste des types d'événements acceptés, consultez la section Types d'événements Google acceptés par Eventarc.
    • SERVICE_ACCOUNT_NAME : nom de votre compte de service géré par l'utilisateur.
    • PROJECT_ID : ID de votre projet Google Cloud .

    Remarques :

    • L'option --event-filters="type=EVENT_FILTER_TYPE" est obligatoire. Si aucun autre filtre d'événement n'est défini, les événements de toutes les ressources sont mis en correspondance.
    • EVENT_FILTER_TYPE ne peut pas être modifié après sa création. Pour modifier EVENT_FILTER_TYPE, créez un nouveau déclencheur et supprimez l'ancien.
    • Chaque déclencheur peut comporter plusieurs filtres d'événement, séparés par une virgule et spécifiés dans une option --event-filters=[ATTRIBUTE=VALUE,…], ou vous pouvez répéter l'option pour ajouter d'autres filtres. Seuls les événements correspondant à tous les filtres sont envoyés à la destination. Les caractères génériques et les expressions régulières ne sont pas acceptés. Toutefois, lorsque vous utilisez l'option --event-filters-path-pattern, vous pouvez définir un format de chemin d'accès pour les ressources.
    • Vous pouvez également utiliser le flag --max-retry-attempts pour spécifier une seule tentative de distribution d'événement sans nouvelle tentative. La seule valeur valide est 1. Si vous omettez l'indicateur, le comportement standard de nouvelle tentative s'applique. Pour en savoir plus, consultez Événements de nouvelle tentative.
    • D'autres indicateurs sont disponibles. Pour en savoir plus, consultez les sections sur gcloud eventarc triggers create

Terraform

Pour créer un déclencheur Eventarc pour un service Cloud Run, consultez Créer un déclencheur à l'aide de Terraform.

Créer un déclencheur pour les fonctions

Après avoir déployé une fonction, vous pouvez configurer un déclencheur à l'aide de la console Google Cloud , de Google Cloud CLI ou de Terraform.

Console

Lorsque vous utilisez la console Google Cloud pour créer une fonction, vous pouvez également ajouter un déclencheur à votre fonction. Pour créer un déclencheur pour votre fonction :

  1. Dans la console Google Cloud , accédez à Cloud Run :

    Accédez à Cloud Run

  2. Cliquez sur Écrire une fonction, puis saisissez les détails de la fonction. Pour en savoir plus sur la configuration des fonctions lors du déploiement, consultez Déployer des fonctions.

  3. Dans la section Déclencheur, cliquez sur Ajouter un déclencheur.

  4. Sélectionnez une option.

  5. Dans le volet Déclencheur Eventarc, modifiez les informations du déclencheur comme suit :

    1. Saisissez un nom pour le déclencheur dans le champ Nom du déclencheur ou utilisez le nom par défaut.

    2. Sélectionnez un type de déclencheur dans la liste :

      • Sources Google pour spécifier des déclencheurs pour Pub/Sub, Cloud Storage, Firestore et d'autres fournisseurs d'événements Google.

      • Tiers pour s'intégrer avec des fournisseurs non-Google qui proposent une source Eventarc. Pour en savoir plus, consultez Événements tiers dans Eventarc.

    3. Sélectionnez un fournisseur d'événements dans la liste Fournisseur d'événements pour choisir un produit qui fournit le type d'événement pour déclencher votre fonction. Pour obtenir la liste des fournisseurs d'événements, consultez Fournisseurs et destinations d'événements.

    4. Sélectionnez un type d'événement dans la liste Type d'événement. La configuration du déclencheur varie en fonction du type d'événement accepté: Pour en savoir plus, consultez Types d'événements.

    5. Si le champ Région est activé, sélectionnez un emplacement pour le déclencheur Eventarc. En général, l'emplacement d'un déclencheur Eventarc doit correspondre à l'emplacement de la ressourceGoogle Cloud que vous souhaitez surveiller pour les événements. Dans la plupart des scénarios, vous devez également déployer votre fonction dans la même région. Consultez Comprendre les emplacements Eventarc pour en savoir plus sur les emplacements des déclencheurs Eventarc.

    6. Dans le champ Compte de service, sélectionnez un compte de service. Les déclencheurs Eventarc sont associés à des comptes de service, destinés à être utilisés comme identité lors de l'appel de votre fonction. Le compte de service de votre déclencheur Eventarc doit avoir l'autorisation d'appeler votre fonction. Par défaut, Cloud Run utilise le compte de service Compute Engine par défaut.

    7. Vous pouvez éventuellement spécifier le chemin d'URL du service auquel envoyer la requête entrante. Il s'agit du chemin relatif sur le service de destination auquel les événements du déclencheur doivent être envoyés. Par exemple: /, /route, route et route/subroute.

    8. Si vous le souhaitez, cochez la case Activer la nouvelle tentative en cas d'échec pour activer les nouvelles tentatives en cas d'échec de la remise. Sinon, le comportement par défaut est une seule tentative de remise sans nouvelle tentative. Pour plus d'informations, voir Événements de nouvelle tentative.

  6. Une fois les champs obligatoires renseignés, cliquez sur Enregistrer le déclencheur.

  7. Cliquez sur Créer.

  8. Dans l'onglet Source, modifiez le code source si nécessaire, puis sélectionnez Enregistrer et redéployer.

gcloud

Lorsque vous créez une fonction à l'aide de l'gcloud CLI, vous devez d'abord déployer votre fonction, puis créer un déclencheur. Pour créer un déclencheur pour votre fonction, procédez comme suit :

  1. Exécutez la commande suivante dans le répertoire contenant l'exemple de code pour déployer votre fonction :

    gcloud run deploy FUNCTION \
    --source . \
    --function FUNCTION_ENTRYPOINT \
    --base-image BASE_IMAGE_ID \
    --region REGION

    Remplacez les éléments suivants :

    • FUNCTION: le nom de la fonction que vous déployez. Vous pouvez omettre ce paramètre, mais dans ce cas le nom vous sera demandé.

    • FUNCTION_ENTRYPOINT : point d'entrée de votre fonction dans votre code source. Il s'agit du code que Cloud Run exécute lorsque votre fonction s'exécute. La valeur de cette option doit être un nom de fonction ou un nom de classe complet qui existe dans votre code source.

    • BASE_IMAGE_ID : environnement de l'image de base de votre fonction. Pour en savoir plus sur les images de base et les packages inclus dans chaque image, consultez Images de base de l'environnement d'exécution.

    • REGION : Google Cloud région dans laquelle vous souhaitez déployer votre fonction. Par exemple, europe-west1.

  2. Exécutez la commande suivante pour créer un déclencheur qui filtre et achemine les événements :

    gcloud eventarc triggers create TRIGGER_NAME \
    --location=LOCATION \
    --destination-run-service=FUNCTION \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --max-retry-attempts=1 \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Remplacez les éléments suivants :

    • TRIGGER_NAME : l'ID du déclencheur ou un identifiant complet.
    • LOCATION : l'emplacement du déclencheur Eventarc. Vous pouvez également définir la propriété eventarc/location (par exemple, gcloud config set eventarc/location us-central1).

      Pour éviter tout problème de performance et de résidence des données, l'emplacement doit correspondre à l'emplacement de Google Cloud service qui génère des événements. Pour en savoir plus, consultez la page Emplacements Eventarc.

    • FUNCTION : nom de la fonction Cloud Run déployée qui reçoit les événements pour le déclencheur.
    • DESTINATION_RUN_REGION : (facultatif) emplacement Cloud Run dans lequel se trouve la fonction Cloud Run de destination. Si elle n'est pas spécifiée, il est supposé que la fonction se trouve dans la même région que le déclencheur.
    • EVENT_FILTER_TYPE : identifiant de l'événement. Un événement est généré lorsqu'un appel d'API pour la méthode réussit. Pour les opérations de longue durée, l'événement n'est généré qu'à la fin de l'opération et uniquement si l'action s'est bien déroulée. Pour obtenir la liste des types d'événements acceptés, consultez la section Types d'événements Google acceptés par Eventarc.
    • SERVICE_ACCOUNT_NAME : nom de votre compte de service géré par l'utilisateur.
    • PROJECT_ID : ID de votre projet Google Cloud .

    Remarques :

    • L'option --event-filters="type=EVENT_FILTER_TYPE" est obligatoire. Si aucun autre filtre d'événement n'est défini, les événements de toutes les ressources sont mis en correspondance.
    • EVENT_FILTER_TYPE ne peut pas être modifié après sa création. Pour modifier EVENT_FILTER_TYPE, créez un nouveau déclencheur et supprimez l'ancien.
    • Chaque déclencheur peut comporter plusieurs filtres d'événement, séparés par une virgule et spécifiés dans une option --event-filters=[ATTRIBUTE=VALUE,…], ou vous pouvez répéter l'option pour ajouter d'autres filtres. Seuls les événements correspondant à tous les filtres sont envoyés à la destination. Les caractères génériques et les expressions régulières ne sont pas acceptés. Toutefois, lorsque vous utilisez l'option --event-filters-path-pattern, vous pouvez définir un format de chemin d'accès pour les ressources.
    • Vous pouvez également utiliser le flag --max-retry-attempts pour spécifier une seule tentative de distribution d'événement sans nouvelle tentative. La seule valeur valide est 1. Si vous omettez l'option, le comportement de réessai standard s'applique. Pour en savoir plus, consultez Événements de nouvelle tentative.
    • D'autres indicateurs sont disponibles. Pour en savoir plus, consultez les sections sur gcloud eventarc triggers create

Terraform

Pour créer un déclencheur Eventarc pour une fonction Cloud Run, consultez Créer un déclencheur à l'aide de Terraform.

Définir le délai de confirmation Pub/Sub

Les fonctions Cloud Run basées sur des événements sont implémentées à l'aide d'Eventarc en combinaison avec un abonnement Pub/Sub. Par défaut, le délai de confirmation (ack) de cet abonnement Pub/Sub est de 10 secondes. Ce paramètre est insuffisant pour de nombreuses fonctions et peut entraîner des exécutions en double indésirables.

Nous vous recommandons de définir le délai ack de votre service ou fonction sur la valeur maximale de 600 secondes, comme suit :

Console

Une fois votre fonction déployée, procédez comme suit pour modifier le délai ack de la fonction :

  1. Dans le Google Cloud console, allez àCloud Run :

    Accédez à Cloud Run

  2. Recherchez la fonction que vous souhaitez mettre à jour dans la liste des services, puis cliquez dessus pour en afficher les détails.

  3. Ouvrez l'onglet Déclencheurs.

  4. Cliquez sur le nom du déclencheur pour ouvrir les détails du déclencheur .

  5. Cliquez sur le lien Topic pour ouvrir le volet d'édition du sujet.

  6. Cliquez sur le nom de l'ID de l'abonnement pour accéder au volet de l'abonnement, puis cliquez sur Modifier en haut de la page.

  7. Définissez la valeur du délai de confirmation sur 600, puis cliquez sur Mettre à jour pour enregistrer la modification.

gcloud

Définissez le délai ack par déclencheur sur la valeur maximale de 600 secondes. Notez que les commandes suivantes font référence à des variables (TRIGGER_NAME et LOCATION) dont vous avez défini les valeurs lors des étapes précédentes.

## Per Cloud Run function:

# Update Ack Deadline to max (600s)
SUBSCRIPTION_ID=$(gcloud eventarc triggers describe "$TRIGGER_NAME" --location $LOCATION --format json | jq -r '.transport.pubsub.subscription')
gcloud pubsub subscriptions update "$SUBSCRIPTION_ID" --ack-deadline=600

Effectuez une mise à jour groupée de tous les déclencheurs de services et de fonctions pour définir leur délai ack sur 600 secondes :

### Match all Cloud Run service triggers and update all deadlines to 600s (max timeout)
### This will change ALL Cloud Run services and Cloud Run functions
TRIGGER_NAMES=($(gcloud eventarc triggers list | awk '/Cloud Run service/ {print $1}'))

if [ ${#TRIGGER_NAMES[@]} -eq 0 ]; then
  echo "No matching triggers found"
fi

for trigger in "${TRIGGER_NAMES[@]}"; do
echo "Updating ack deadline for trigger: $trigger"
SUBSCRIPTION_ID=$(gcloud eventarc triggers describe "$trigger" --location $LOCATION --format json | jq -r '.transport.pubsub.subscription')

if [ -z "$SUBSCRIPTION_ID" ]; then
    echo "Error: Could not retrieve subscription ID for trigger: $trigger"
    continue # Skip to the next trigger
fi
gcloud pubsub subscriptions update "$SUBSCRIPTION_ID" --ack-deadline=600
echo "Ack deadline updated for subscription: $SUBSCRIPTION_ID"
done

Afficher l'ID et la source CloudEvent

Pour afficher l'ID et la source CloudEvent qui ont déclenché votre service, consultez les ressources suivantes dans les journaux de service Cloud Run :

  • LogEntry.labels.run.googleapis.com/cloud_event_id
  • LogEntry.labels.run.googleapis.com/cloud_event_source

Étapes suivantes