Monitoring asset changes with conditions

This topic shows you how to monitor asset changes with a customized condition. See the general topic for more information about real-time notifications.

Note: Support for conditions is limited. In some cases, creating or updating feeds with conditions might result in a delay or be temporarily unavailable.

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) or temporal_asset.asset.name (of type String). 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 as temporal_asset.asset.name == "//cloudresourcemanager.googleapis.com/projects/12345". In this example, if the input value of temporal_asset.asset.name is //cloudresourcemanager.googleapis.com/projects/12345, then the expression evaluates to true.

• 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 a String contains function, and evaluates to true if the value of temporal_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 a true 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 proper asset_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 condition temporal_asset.asset.resource.data.name != "my_name", if name 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 type cloudresourcemanager.googleapis.com/Project:

  temporal_asset.asset.resource.data.lifecycleState == "ACTIVE"