This topic shows you how to monitor asset changes with a customized condition. See the general topic for more information about real-time notifications.
Overview
To view only a certain type of change for a given asset, you can add a condition to your feed.
The condition
object is optional. If a feed does not have a condition
object, the configured destination receives all changes to the assets.
The condition
object has the following structure:
"condition": {
"title": "...",
"description": "...",
"expression": "..."
}
Title
and description
are optional. These fields can help you identify and
describe the condition.
The expression
field defines the expression used to evaluate the notification
in Common Expression Language (CEL). The
condition expression can contain multiple statements, and statements are
combined using logic operators, following CEL language specification.
Using CEL
Common Expression Language (CEL) is the expression language used to specify a feed condition. It is tailored to express attribute-based logic expressions. For more information, see the CEL spec and its language definition.
In a feed condition, CEL is used to make boolean decisions based on attribute
data. A condition expression consists of one or more statements that are joined
using logic operators (&&
, ||
). Each statement expresses an attribute-based
control rule that applies to the TemporalAsset
to determine whether the
notification is sent.
The following CEL features are the most important for feed conditions:
Variables: Conditions use variables to express a given attribute, such as
temporal_asset.deleted
(of type Boolean) ortemporal_asset.asset.name
(of typeString
). These variables are populated with values based on the context at runtime.Operators: Every data type, such as
String
, supports a set of operators that can be used to create a logic expression. Most commonly, operators are used to compare the value contained in a variable with a literal value, such astemporal_asset.asset.name == "//cloudresourcemanager.googleapis.com/projects/12345"
. In this example, if the input value oftemporal_asset.asset.name
is//cloudresourcemanager.googleapis.com/projects/12345
, then the expression evaluates totrue
.Functions: A function is a compound operator for data types that support more complex operations. In condition expressions, there are predefined functions that can be used in conjunction with a given data type. For example,
temporal_asset.asset.name.contains("keyword")
uses aString
contains function, and evaluates totrue
if the value oftemporal_asset.asset.name
contains "keyword".Logical operators: Conditions support logical operators that can be used to build complex logic expressions from simple expression statements:
&&
and||
. These logical operators make it possible to use multiple input variables in a condition expression. For example:temporal_asset.deleted && temporal_asset.window.start_time.getFullYear() > 2020
joins two simple statements, and requires both statements to be met in order to produce atrue
overall evaluation result.
For more information about CEL features, see the language definition.
Using condition variables
Condition variables allow you to create conditions on different attributes. Supported condition variables are:
- temporal_asset: The current Asset change in TemporalAsset
format. If the condition evaluates to true, the
TemporalAsset
is sent to the configured destination.
Example condition expressions
The following condition expression sends notifications on creation events:
temporal_asset.deleted == false &&
temporal_asset.prior_asset_state == google.cloud.asset.v1.TemporalAsset.PriorAssetState.DOES_NOT_EXIST
The following condition expression sends notifications for resources that are
located in folders 12345
and 23456
:
"folders/12345" in temporal_asset.asset.ancestors ||
"folders/23456" in temporal_asset.asset.ancestors
The following condition expression sends notifications when new allowed rules
are added to firewalls, assuming asset_type
is already set to
compute.googleapis.com/Firewall
in the feed.
size(temporal_asset.asset.resource.data.allowed) >
size(temporal_asset.prior_asset.resource.data.allowed)
The following condition expression sends notifications for VM instances with
n1-standard-1
machine type, assuming asset_type
is already set to
compute.googleapis.com/Instance
in the feed.
temporal_asset.asset.resource.data.machineType.endsWith('/machineTypes/n1-standard-1')
The following condition expression sends notifications for storage buckets with
any IAM policies for allUsers
, assuming asset_type
is set to
storage.googleapis.com/Bucket
and content_type
is set to IAM_POLICY
in the
feed.
temporal_asset.asset.iam_policy.bindings.exists(b, b.members.exists(m, m == "allUsers"))
The following condition expression sends a notification when a storage bucket with a
test
key in its label is deleted:
temporal_asset.deleted == true && temporal_asset.prior_asset_state == google.cloud.asset.v1.TemporalAsset.PriorAssetState.PRESENT && "test" in temporal_asset.prior_asset.resource.data.labels
Known limitations
Most variable names in condition expressions are represented in snake_case. The only exception is the variable names of the sub-fields of
data
in Resource object, which are represented in camelCase.Condition expressions have a length limit of 3000 characters.
Some validations on condition expressions are performed during feed creation/update time. However, such validations are not comprehensive, especially for conditions set on
temporal_asset.asset.resource.data
field, which has dynamic type. We recommend simple feed conditions with the properasset_type
specified in feed. If validation errors happen during evaluation time, the notification is not sent and errors are logged. Learn about viewing logs.For dynamic types in
temporal_asset.asset.resource.data
, conditions specified on absent fields trigger runtime errors and notification are not published. For example, for conditiontemporal_asset.asset.resource.data.name != "my_name"
, ifname
field is missing in an update, the evaluation fails and you do not receive notifications. If your condition only works in the presence of certain fields, check the existence in the condition to ensure it is properly evaluated.Static enum types could be represented as either fully qualified path names or raw integers. For example, the following expressions are valid for
prior_asset_state
:temporal_asset.prior_asset_state == google.cloud.asset.v1.TemporalAsset.PriorAssetState.DOES_NOT_EXIST
and
temporal_asset.prior_asset_state == 3
Dynamic enum types in
temporal_asset.asset.resource.data
are represented as raw strings. For example, the following expression is valid for asset typecloudresourcemanager.googleapis.com/Project
:temporal_asset.asset.resource.data.lifecycleState == "ACTIVE"