Cette page explique comment créer et gérer des flux dans un projet.
Présentation
Pour recevoir des notifications en temps réel concernant les modifications de ressources et de stratégies, vous pouvez créer un flux et vous y abonner. Lors de la configuration du flux, vous pouvez spécifier que vous souhaitez surveiller les modifications des types de ressources, des stratégies IAM, des règles d'accès et des règles d'administration au sein d'une organisation, un dossier, un projet ou des ressources spécifiques. Vous pouvez également ajouter des conditions à votre flux, de façon à recevoir des notifications uniquement pour certains types de modifications apportées à un élément. Une fois votre flux configuré, vous recevez immédiatement des notifications à chaque modification des éléments spécifiés, envoyés via Pub/Sub (au format TemporalAsset). Les notifications en temps réel se connectent à vos charges de travail existantes. Cette fonctionnalité vous permet de fusionner des actions. Par exemple, vous pouvez créer une fonction Cloud pour annuler une modification de ressource une fois celle-ci détectée.
Avant de commencer
Activez l'API Cloud Asset pour votre projet.
Si vous n'avez pas de compte de service existant dans votre projet, créez un compte de service.
Accordez à votre compte de service les autorisations pour appeler l'API pour les flux en temps réel. Les autorisations suivantes sont nécessaires pour chaque opération :
Autorisation Description cloudasset.feeds.create
etcloudasset.assets.exportResource
Créez des flux cloudasset.feeds.update
etcloudasset.assets.exportResource
Mettre à jour des flux cloudasset.feeds.delete
Supprimer des flux cloudasset.feeds.get
Obtenir des flux cloudasset.feeds.list
Répertorier des flux Attribuer le rôle de Propriétaire d'éléments Cloud (
roles/cloudasset.owner
) à votre compte de service accorde toutes les autorisations liées à l'API Cloud Asset, y compris celles répertoriées dans le tableau précédent. Pour en savoir plus sur les rôles et les autorisations, consultez la page Comprendre les rôles.Créez un sujet Pub/Sub si vous n'en avez pas déjà un. Assurez-vous que
service-PROJECT_NUMBER@gcp-sa-cloudasset.iam.gserviceaccount.com
dispose de l'autorisationpubsub.topics.publish
sur le sujet, où PROJECT_NUMBER est le numéro du projet compatible avec l'API Cloud Asset à partir duquel vous souhaitez créer le flux. Par défaut, ce compte de service dispose de l'autorisationpubsub.topics.publish
sur tous les sujets de ce projet compatible avec l'API Cloud Asset.Le compte de service sera créé en appelant l'API une fois, ou vous pouvez utiliser la commande suivante :
gcloud beta services identity create --service=cloudasset.googleapis.com --project=PROJECT_ID
Configurer votre environnement
GCLOUD
Si le SDK Cloud n'est pas installé, installez le SDK Cloud sur votre client local.
Mettez à jour tous vos composants installés vers la dernière version si vous avez installé le SDK Cloud.
Activez l'API Resource Manager pour votre projet.
API
Configurez une nouvelle instance de VM Compute Engine en accédant à la page Créer une instance et en sélectionnant le compte de service dans votre projet.
Dans la section Champs d'application de l'accès, sélectionnez Autoriser l'accès complet à toutes les API Cloud.
Lancez votre instance en cliquant sur Créer.
Accédez à la page Instance de VM.
Ouvrez un client Web SSH connecté à l'instance en cliquant sur SSH à côté de la liste des instances.
Dans le client Web SSH, générez un jeton d'authentification pour votre compte de service en exécutant l'appel suivant :
TOKEN=$(gcloud auth application-default print-access-token)
Les appels d'API suivants supposent que vous créez et gérez des flux sur un projet. Si vous souhaitez créer et gérer des flux pour une organisation ou un dossier, utilisez /projects/PROJECT_NUMBER/
avec /organizations/ORGANIZATION_NUMBER/
ou /folders/FOLDER_NUMBER/
.
Créer un flux
Vous pouvez créer jusqu'à 200 flux par élément. Cette limite ne s'applique qu'aux flux qui suivent directement cet élément et ne compte pas les flux de ses enfants. Par exemple, si vous avez 10 projets sous une organisation, chaque projet peut comporter jusqu'à 200 flux, et chaque organisation peut également comporter jusqu'à 200 flux.
Pour créer un flux, vous pouvez utiliser l'une des options suivantes :
- FEED_ID est l'identifiant unique du flux d'éléments attribué par le client.
- ASSET_NAME est une liste des noms complets d'éléments pour lesquels vous souhaitez recevoir des notifications de modification.
- ASSET_TYPE est une liste des types d'éléments pour lesquels vous souhaitez recevoir des notifications de modification.
- CONTENT_TYPE est le type de contenu d'éléments pour lesquels vous souhaitez recevoir des notifications de modification.
- TOPIC_NAME est le nom du sujet Pub/Sub pour publier des notifications.
- CONDITION_TITLE est le titre de la condition à appliquer au flux.
- CONDITION_DESCRIPTION est la description de la condition à appliquer au flux.
CONDITION_EXPRESSION est l'expression de la condition à appliquer au flux.
GCLOUD
Pour créer un flux à l'aide de la commande gcloud asset feeds create
pour des projets, des dossiers et des organisations, procédez comme suit :
Projets :
gcloud asset feeds create FEED_ID --project=PROJECT_ID --asset-names="ASSET_NAME" --content-type=CONTENT_TYPE --asset-types="ASSET_TYPE" --pubsub-topic="TOPIC_NAME" --condition-title="CONDITION_TITLE" --condition-description="CONDITION_DESCRIPTION" --condition-expression="CONDITION_EXPRESSION"
Dossiers :
gcloud asset feeds create FEED_ID --folder=FOLDER_ID --asset-names="ASSET_NAME" --content-type=CONTENT_TYPE --asset-types="ASSET_TYPE" --pubsub-topic="TOPIC_NAME" --condition-title="CONDITION_TITLE" --condition-description="CONDITION_DESCRIPTION" --condition-expression="CONDITION_EXPRESSION"
Organisations :
gcloud asset feeds create FEED_ID --organization=ORGANIZATION_ID --asset-names="ASSET_NAME" --content-type=CONTENT_TYPE --asset-types="ASSET_TYPE" --pubsub-topic="TOPIC_NAME" --condition-title="CONDITION_TITLE" --condition-description="CONDITION_DESCRIPTION" --condition-expression="CONDITION_EXPRESSION"
API
Pour créer un flux à l'aide de l'API feeds.create()
pour des projets, des dossiers et des organisations, procédez comme suit :
- Projets :
curl -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" -X POST \ -d '{"feedId": "FEED_ID", "feed": { "assetNames": ["ASSET_NAME"], "assetTypes": ["ASSET_TYPE"], "contentType": "CONTENT_TYPE", "feedOutputConfig": {"pubsubDestination": {"topic":"TOPIC_NAME"}}, "condition": {"title": "CONDITION_TITLE", "description": "CONDITION_DESCRIPTION", "expression": "CONDITION_EXPRESSION"}}}' \ https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/feeds
- Dossiers :
curl -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" -X POST \ -d '{"feedId": "FEED_ID", "feed": { "assetNames": ["ASSET_NAME"], "assetTypes": ["ASSET_TYPE"], "contentType": "CONTENT_TYPE", "feedOutputConfig": {"pubsubDestination": {"topic":"TOPIC_NAME"}}, "condition": {"title": "CONDITION_TITLE", "description": "CONDITION_DESCRIPTION", "expression": "CONDITION_EXPRESSION"}}}' \ https://cloudasset.googleapis.com/v1/folders/FOLDER_NUMBER/feeds
- Organisations :
curl -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" -X POST \ -d '{"feedId": "FEED_ID", "feed": { "assetNames": ["ASSET_NAME"], "assetTypes": ["ASSET_TYPE"], "contentType": "CONTENT_TYPE", "feedOutputConfig": {"pubsubDestination": {"topic":"TOPIC_NAME"}}, "condition": {"title": "CONDITION_TITLE", "description": "CONDITION_DESCRIPTION", "expression": "CONDITION_EXPRESSION"}}}' \ https://cloudasset.googleapis.com/v1/organizations/ORGANIZATION_NUMBER/feeds
Cloud Asset Inventory définit une notification pour tout élément qui correspond à au moins un des paramètres ASSET de votre flux ET correspond également à l'expression de condition, si elle est spécifiée. Par exemple, si vous spécifiez ASSET_TYPE, ASSET_NAME et CONDITION_EXPRESSION, vous définissez des notifications pour les éléments qui correspondent à ASSET_TYPE ou ASSET_NAME, et respectent la condition CONDITION_EXPRESSION.
Les commandes suivantes créent des notifications à partir du sujet Pub/Sub quick_start_topic
lorsque du contenu est modifié dans le bucket Cloud Storage quick_start_bucket
ou dans des tables BigQuery :
GCLOUD
gcloud asset feeds create quick_start_feed --project=PROJECT_ID --asset-names="//storage.googleapis.com/quick_start_bucket" --content-type=resource --asset-types="bigquery.googleapis.com/Table" --pubsub-topic="projects/PROJECT_ID/topics/quick_start_topic"
API
curl -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" -X POST \ -d '{"feedId": "quick_start_feed", "feed": { "assetNames": ["storage.googleapis.com/quick_start_bucket"], "assetTypes": ["bigquery.googleapis.com/Table"], "contentType": "RESOURCE", "feedOutputConfig": {"pubsubDestination": {"topic":"projects/PROJECT_ID/topics/quick_start_topic"}}}}' \ https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/feeds
Les expressions régulières sont également acceptées pour le champ ASSET_TYPE
. Les commandes suivantes créent des notifications à partir du sujet Pub/Sub quick_start_topic
lorsque du contenu est modifié dans les ressources dont le type d'élément commence par "compute.googleapis.com". Consultez la section RE2 pour connaître la syntaxe d'expression régulière acceptée.
GCLOUD
gcloud asset feeds create quick_start_feed --project=PROJECT_ID --content-type=resource --asset-types="compute.googleapis.com.*" --pubsub-topic="projects/PROJECT_ID/topics/quick_start_topic"
API
curl -H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json" -X POST
-d '{"feedId": "quick_start_feed", "feed": { "assetTypes": ["compute.googleapis.com.*"], "contentType": "RESOURCE", "feedOutputConfig": {"pubsubDestination": {"topic":"projects/PROJECT_ID/topics/quick_start_topic"}}}}'
https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/feeds
Pour obtenir un flux que vous avez créé, utilisez la commande suivante :
GCLOUD
gcloud asset feeds describe FEED_ID --project=PROJECT_ID
API
curl -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/feeds/FEED_ID
Le flux est renvoyé au format suivant, où FULL_NAME_FEED est l'identifiant du flux avec sa ressource parent :
{ "name": "FULL_NAME_FEED", "assetTypes": ["ASSET_TYPES"], "assetNames": ["ASSET_NAMES"], "contentType": "CONTENT_TYPES", "feedOutputConfig": { "pubsubDestination": { "topic": "TOPIC_NAME" } }, "condition": { "title": "CONDITION_TITLE", "description": "CONDITION_DESCRIPTION", "expression": "CONDITION_EXPRESSION" } }
Recevoir des mises à jour
Après avoir créé un flux, abonnez-vous aux mises à jour à partir du sujet Pub/Sub que vous avez spécifié dans le flux. Un nouveau flux peut prendre jusqu'à cinq minutes pour commencer à envoyer des notifications. Une notification est envoyée pour chaque modification apportée à un élément qui correspond à assetNames
ou assetTypes
, et satisfait la condition
dans le flux.
Pour en savoir plus sur Pub/Sub, consultez le Guide Pub/Sub.
Mettre à jour un flux
Pour mettre à jour les attributs d'un flux, vous devez spécifier le chemin d'accès à l'attribut dans update_mask
et la valeur de cet attribut. La commande suivante met à jour les valeurs assetNames
et topic
d'un flux sur un projet.
GCLOUD
gcloud asset feeds update FEED_ID --project=PROJECT_ID --add-asset-names=ASSET_NAME --pubsub-topic="TOPIC"
API
curl -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" -X PATCH \ -d '{"feed": {"assetNames": [ASSET_NAME], "feedOutputConfig": {"pubsubDestination": {"topic":TOPIC}}}, "update_mask": {"paths": ["asset_names", "feed_output_config.pubsub_destination.topic"]}}' \ https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/feeds/FEED_ID
Supprimer un flux
Si vous ne souhaitez plus être informé des modifications apportées aux éléments, exécutez la commande suivante pour supprimer un flux dans un projet.
GCLOUD
gcloud asset feeds delete FEED_ID --project=PROJECT_ID
API
curl -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" -X DELETE \ https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/feeds/FEED_ID
Ajouter une condition à un flux
Pour afficher uniquement un certain type de modification pour un élément donné, vous pouvez ajouter une condition à votre flux.
L'objet condition
est facultatif. Si un flux ne comporte pas d'objet condition
, la destination configurée reçoit toutes les modifications apportées aux éléments.
L'objet condition
présente la structure suivante :
"condition": { "title": ... "description": ... "expression": ... }
Title
et description
sont facultatifs. Ces champs peuvent vous aider à identifier et à décrire la condition.
Le champ expression
définit l'expression utilisée pour évaluer la notification dans le CEL (Common Expression Language). L'expression de condition peut contenir plusieurs instructions, qui sont combinées à l'aide d'opérateurs logiques, conformément aux spécifications du langage CEL.
Utiliser le langage CEL
Le CEL (Common Expression Language) est le langage d'expression utilisé pour spécifier une condition de flux. Il est conçu pour exprimer des expressions logiques basées sur des attributs. Pour en savoir plus, consultez la documentation sur la spécification CEL et sa définition de langage.
Dans une condition de flux, le langage CEL est utilisé pour prendre des décisions booléennes sur la base des données d'attribut. Une expression de condition se compose d'une ou plusieurs instructions qui sont combinées à l'aide d'opérateurs logiques (&&
, ||
ou !
). Chaque instruction exprime une règle de contrôle basée sur des attributs qui s'applique à TemporalAsset
pour déterminer si la notification est envoyée.
Les caractéristiques de langage CEL suivantes sont les plus importantes pour les conditions de flux :
- Variables : les conditions utilisent des variables pour exprimer un attribut donné, comme
temporal_asset.deleted
(de type Booléen) outemporal_asset.asset.name
(de type Chaîne). Ces variables sont renseignées avec des valeurs basées sur le contexte lors de l'exécution. - Opérateurs : chaque type de données, tel que Chaîne, accepte un ensemble d'opérateurs pouvant être utilisés pour créer une expression logique. Le plus souvent, les opérateurs sont utilisés pour comparer la valeur contenue dans une variable avec une valeur littérale, telle que
temporal_asset.asset.name == "//cloudresourcemanager.googleapis.com/projects/12345"
. Dans cet exemple, si la valeur d'entrée detemporal_asset.asset.name
est//cloudresourcemanager.googleapis.com/projects/12345
, l'expression renvoietrue
. - Fonctions : une fonction est un opérateur composé pour les types de données qui acceptent des opérations plus complexes. Dans les expressions de condition, il existe des fonctions prédéfinies qui peuvent être utilisées conjointement avec un type de données spécifique. Par exemple,
temporal_asset.asset.name.contains("keyword")
utilise une Chaîne contenant une fonction, et renvoietrue
si la valeur detemporal_asset.asset.name
contient "keyword". - Opérateurs logiques : les conditions acceptent trois opérateurs logiques qui peuvent être utilisés pour créer des expressions logiques complexes à partir d'expressions simples :
&&
,||
et!
. Ces opérateurs logiques permettent d'utiliser plusieurs variables d'entrée dans une expression de condition. Par exemple :temporal_asset.deleted && temporal_asset.window.start_time.getFullYear() > 2020
combine deux conditions simples et requiert que les deux conditions soient remplies pour produire un résultat d'évaluation globaltrue
.
Pour en savoir plus sur les caractéristiques des éléments CEL, consultez la section définition de langage.
Utiliser des variables de condition
Les variables de condition vous permettent de créer des conditions sur différents attributs. Les variables de condition acceptées sont les suivantes :
- temperaral_asset : modification actuelle de l'élément au format TemporalAsset. Si la condition renvoie "true",
TemporalAsset
est envoyé à la destination configurée.
Exemples d'expressions de condition
L'expression de condition suivante envoie des notifications concernant les événements de création :
!temporal_asset.deleted &&
temporal_asset.prior_asset_state == google.cloud.asset.v1.TemporalAsset.PriorAssetState.DOES_NOT_EXIST
L'expression de condition suivante envoie des notifications pour les ressources situées dans les dossiers 12345
et 23456
:
"folders/12345" in temporal_asset.asset.ancestors ||
"folders/23456" in temporal_asset.asset.ancestors
L'expression de condition suivante envoie des notifications lorsque de nouvelles règles autorisées sont ajoutées aux pare-feu, en supposant que asset_type
est déjà défini sur compute.googleapis.com/Firewall
dans le flux.
size(temporal_asset.asset.resource.data.allowed) >
size(temporal_asset.prior_asset.resource.data.allowed)
L'expression de condition suivante envoie des notifications pour les instances de VM avec le type de machine n1-standard-1
, en supposant que asset_type
est déjà défini sur compute.googleapis.com/Instance
dans le flux.
temporal_asset.asset.resource.data.machineType.endsWith("/machineTypes/n1-standard-1")
L'expression de condition suivante envoie des notifications pour les buckets de stockage avec des stratégies IAM pour allUsers
, en supposant que asset_type
est défini sur storage.googleapis.com/Bucket
et que content_type
est défini sur IAM_POLICY
dans le flux.
temporal_asset.asset.iam_policy.bindings.exists(b, b.members.exists(m, m == "allUsers"))
Limites connues
La plupart des noms de variables dans les expressions de condition sont représentés dans snake_case. Les noms de variables des sous-champs de
data
dans l'objet Resource, qui sont représentés dans camelCase, sont la seule exception.Les expressions de condition sont limitées à 1 000 caractères.
Certaines validations sur les expressions de condition sont effectuées lors de la création ou de la mise à jour du flux. Toutefois, ces validations ne sont pas exhaustives, en particulier pour les conditions définies dans le champ
temporal_asset.asset.resource.data
, qui possèdent un type dynamique. Nous vous recommandons d'utiliser des conditions de flux simples avec leasset_type
approprié spécifié dans le flux. Si des erreurs de validation se produisent pendant l'évaluation, la notification n'est pas envoyée et les erreurs sont consignées. Découvrez comment afficher les journaux.Pour les types dynamiques dans
temporal_asset.asset.resource.data
, les conditions spécifiées sur les champs absents déclenchent des erreurs d'exécution et les notifications ne sont pas publiées. Par exemple, pour la conditiontemporal_asset.asset.resource.data.name != "my_name"
, si le champname
est manquant dans une mise à jour, l'évaluation échoue et vous ne recevez pas de notifications. Si votre condition ne fonctionne qu'en présence de certains champs, vérifiez la condition pour vous assurer qu'elle est correctement évaluée.Les types d'énumérations statiques peuvent être représentés sous forme de noms de chemin complets ou d'entiers bruts. Par exemple, les expressions suivantes sont valides pour
prior_asset_state
:temporal_asset.prior_asset_state == google.cloud.asset.v1.TemporalAsset.PriorAssetState.DOES_NOT_EXIST
et
temporal_asset.prior_asset_state == 3
Les types d'énumérations dynamiques dans
temporal_asset.asset.resource.data
sont représentés par des chaînes brutes. Par exemple, l'expression suivante est valide pour le type d'élémentcloudresourcemanager.googleapis.com/Project
:temporal_asset.asset.resource.data.lifecycleState == "ACTIVE"
Dépannage
Cette section explique comment résoudre les problèmes courants.
Échec de la création ou de la mise à jour d'un flux
Si vous ne parvenez pas à créer ou à mettre à jour un flux et que vous recevez le message d'erreur Fail to use
[TOPIC_NAME] as feed output destination
, cela signifie qu'un problème est survenu lors de la publication du message dans le sujet que vous avez spécifié dans la destination de sortie du flux. Pour résoudre le problème, procédez comme suit :
- Vérifiez que vous avez spécifié le bon nom de sujet.
- Assurez-vous que le compte de service (
service-[PROJECT_NUMBER]@gcp-sa-cloudasset.iam.gserviceaccount.com
) dispose de l'autorisationpubsub.topics.publish
sur le sujet, où[PROJECT_NUMBER]
est le numéro du projet compatible avec Cloud Asset Inventory à partir duquel vous envisagez de créer le flux.
Échec de réception des mises à jour de ressources ou de stratégies IAM
Si vous ne recevez pas de notifications pour les mises à jour de ressources ou de stratégies IAM, vérifier les configurations suivantes peut vous aider.
- Assurez-vous que les métadonnées ont été modifiées sur vos éléments. Le flux en temps réel n'envoie des mises à jour que lorsque les métadonnées des types de ressources acceptés sont modifiées. Les opérations telles que l'importation d'un nouveau fichier dans votre bucket Cloud Storage ne déclenchent pas de modification des métadonnées.
- Assurez-vous que vos éléments correspondent à l'un des critères que vous avez spécifiés dans le flux, à savoir les noms et les types d'éléments.
- Consultez les journaux pour voir si des erreurs se sont produites lors de la publication des mises à jour sur votre sujet.
Utiliser Cloud Logging
Cette section explique comment configurer et afficher Logging pour les flux en temps réel de Cloud Asset Inventory.
Lorsque les flux en temps réel ne parviennent pas à envoyer des ressources ou des mises à jour de stratégie IAM via Pub/Sub, Cloud Asset Inventory consigne l'état et le message d'erreur via Logging. Logging est activé par défaut. Découvrez les tarifs de la suite des opérations Google Cloud.
Afficher les journaux de la suite des opérations Google Cloud
Pour afficher les journaux, accédez à la visionneuse de journaux.
La journalisation du flux en temps réel est indexée par un sujet Pub/Sub. Pour afficher tous les journaux, sélectionnez Sujet Cloud Pub/Sub > Tous les ID de sujet dans le premier menu déroulant. Pour afficher les journaux correspondant au sujet spécifié dans votre flux, sélectionnez un seul ID de sujet dans la liste.
Le codage UTF-8 est appliqué aux champs de journaux. Les caractères qui ne sont pas au format UTF-8 sont remplacés par des points d'interrogation.
Informations consignées
Les entrées de journal de flux en temps réel contiennent les types d'informations suivants :
- Informations générales figurant dans la plupart des journaux Google Cloud, telles que la gravité, l'ID de projet, le numéro de projet ou l'horodatage.
- Champs de journal de flux en temps réel dans
jsonPayload
, qui contiennent le nom de l'élément, la configuration de sortie du flux, l'état d'erreur lors de la publication de mises à jour de ressources ou de stratégies IAM.
Le tableau suivant indique les types d'informations contenus dans chaque champ.
Champ | Type et description |
---|---|
name |
|
asset_name |
Nom complet de l'élément qui doit recevoir les mises à jour. Par exemple :
|
feed_output_config |
Configuration de sortie du flux définissant où les mises à jour des éléments sont publiées. |
condition |
Condition de flux qui détermine si une mise à jour d'éléments doit être publiée. |
error_status |
État en cas d'échec de publication des mises à jour d'éléments dans un flux. |