You can receive real-time notifications about resource and policy changes by creating and subscribing to a feed.
When you create the feed, you can specify that you want to monitor changes of supported resource types, IAM policies, access policies, and organization policies in an organization, folder, project. Additionally, you can add conditions to your feed so that you only receive notifications for certain types of changes to an asset.
After creating a feed, you receive notifications through Pub/Sub whenever the specified assets change. The first message published to the Pub/Sub topic is a welcome message in the format of a string, and all following messages are in the format of a TemporalAsset.
Here's a sample Pub/Sub message for the RESOURCE content type.
{
"asset":{
"ancestors":[
"projects/000000000000",
"folders/000000000000",
"organizations/000000000000"
],
"assetType":"storage.googleapis.com/Bucket",
"name":"//storage.googleapis.com/my-bucket",
"resource":{
"data":{
LATEST_ASSET_METADATA
},
"discoveryDocumentUri":"https://www.googleapis.com/discovery/v1/apis/storage/v1/rest",
"discoveryName":"Bucket",
"location":"us",
"parent":"//cloudresourcemanager.googleapis.com/projects/000000000000",
"version":"v1"
},
"updateTime":"2024-01-30T00:00:00.000000Z"
},
"priorAsset":{
"ancestors":[
"projects/000000000000",
"folders/000000000000",
"organizations/000000000000"
],
"assetType":"storage.googleapis.com/Bucket",
"name":"//storage.googleapis.com/my-bucket",
"resource":{
"data":{
PREVIOUS_ASSET_METADATA
},
"discoveryDocumentUri":"https://www.googleapis.com/discovery/v1/apis/storage/v1/rest",
"discoveryName":"Bucket",
"location":"us",
"parent":"//cloudresourcemanager.googleapis.com/projects/000000000000",
"version":"v1"
},
"updateTime":"2024-01-29T00:00:00.000000Z"
},
"priorAssetState":"PRESENT",
"window":{
"startTime":"2024-01-30T00:00:00.000000Z"
}
}
To learn more about Pub/Sub or how to set up subscriptions, see the Pub/Sub documentation.
Before you begin
Enable the Cloud Asset Inventory API in the project you're running Cloud Asset Inventory commands from.
Make sure your account has the correct role to call the Cloud Asset Inventory API. For individual permissions for each call type, see Permissions.
Create a Pub/Sub topic, if you don't have one already.
Limitations
It can take up to 10 minutes for any feed creation, update, or deletion to take effect.
The project where a feed is created must outlive the feed. This is because the service account used to publish to the destination Pub/Sub topic is located in that project. A feed no longer functions and is deleted as soon as project deletion is permanent.
You can create up to 200 feeds on a parent. This limit only applies to feeds directly following a parent and does not count the feeds of its children. For example, if you have 10 projects in an organization, each project can have up to 200 feeds, and the organization can also have up to 200 feeds.
Create feeds
gcloud
gcloud asset feeds create FEED_ID \ --SCOPE \ --billing-project=BILLING_PROJECT_ID \ --pubsub-topic=projects/TOPIC_PROJECT_ID/topics/TOPIC_ID \ --asset-names=ASSET_NAME_1,ASSET_NAME_2,... \ --asset-types=ASSET_TYPE_1,ASSET_TYPE_2,... \ --content-type=CONTENT_TYPE \ --relationship-types=RELATIONSHIP_TYPE_1,RELATIONSHIP_TYPE_2,... \ --condition-title="CONDITION_TITLE" \ --condition-description="CONDITION_DESCRIPTION" \ --condition-expression="CONDITION_EXPRESSION"
Provide the following values:
-
SCOPE: Use one of the following values:-
project=PROJECT_ID, wherePROJECT_IDis the ID of the project to create the feed in. -
folder=FOLDER_ID, whereFOLDER_IDis the ID of the folder to create the feed in.How to find the ID of a Google Cloud folder
Google Cloud console
To find the ID of a Google Cloud folder, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher list box in the menu bar.
- Select your organization from the list box.
- Search for your folder name. The folder ID is shown next to the folder name.
gcloud CLI
You can retrieve the ID of a Google Cloud folder that's located at the organization level with the following command:
gcloud resource-manager folders list \ --organization=$(gcloud organizations describe ORGANIZATION_NAME \ --format="value(name.segment(1))") \ --filter='"DISPLAY_NAME":"TOP_LEVEL_FOLDER_NAME"' \ --format="value(ID)"
Where TOP_LEVEL_FOLDER_NAME is a partial or full string match for the folder's name. Remove the
--formatflag to see more information about the found folders.The previous command doesn't return the IDs of subfolders within folders. To do so, run the following command using a top level folder's ID:
gcloud resource-manager folders list --folder=FOLDER_ID
-
-
organization=ORGANIZATION_ID, whereORGANIZATION_IDis the ID of the organization to create the feed in.How to find the ID of a Google Cloud organization
Google Cloud console
To find the ID of a Google Cloud organization, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher list box in the menu bar.
- Select your organization from the list box.
- Click the All tab. The organization ID is shown next to the organization name.
gcloud CLI
You can retrieve the ID of a Google Cloud organization with the following command:
gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"
-
-
FEED_ID: A unique asset feed identifier.-
BILLING_PROJECT_ID: Optional. The project ID that the default Cloud Asset Inventory service agent is in that has permissions to manage your Pub/Sub topic. Read more about setting the billing project. -
TOPIC_PROJECT_ID: The ID of the project where the Pub/Sub topic is located. -
TOPIC_ID: The ID of the Pub/Sub topic to publish notifications to. - At least one of the following asset definitions:
ASSET_NAME_#: Optional. A comma-separated list of asset full names.ASSET_TYPE_#: Optional. A comma-separated list of searchable asset types. RE2-compatible regular expressions are supported. If the regular expression doesn't match any supported asset type, anINVALID_ARGUMENTerror is returned. When--asset-typesisn't specified, all asset types are returned.
CONTENT_TYPE: Optional. The content type of the metadata that you want to retrieve. When--content-typeisn't specified, only basic information is returned, such as asset names, the last time the assets were updated, and what projects, folders, and organizations they belong to.-
RELATIONSHIP_TYPE_#: Optional. Requires access to the Security Command Center Premium or Enterprise tier. A comma-separated list of asset relationship types that you want to retrieve. You must setCONTENT_TYPEtoRELATIONSHIPfor this to work. - If adding an optional feed condition, include the following details
in your command:
CONDITION_TITLE: A title to assign to the feed condition.-
CONDITION_DESCRIPTION: A description to assign to the feed condition. CONDITION_EXPRESSION: The condition expression to apply to the feed.
See the gcloud CLI reference for all options.
Example
Run the following command to create a feed in the my-topic Pub/Sub topic
that notifies when changes are made to the following resources in the my-project
project.
- The
my-bucketCloud Storage bucket - Any BigQuery table
gcloud asset feeds create my-feed \ --project=my-project \ --pubsub-topic=projects/my-project/topics/my-topic \ --asset-names=//storage.googleapis.com/my-bucket \ --asset-types=bigquery.googleapis.com/Table \ --content-type=resource
Example response
assetNames:
- //storage.googleapis.com/my-bucket
assetTypes:
- bigquery.googleapis.com/Table
condition: {}
contentType: RESOURCE
feedOutputConfig:
pubsubDestination:
topic: projects/my-project/topics/my-topic
name: projects/000000000000/feeds/my-feed
REST
HTTP method and URL:
POST https://cloudasset.googleapis.com/v1/SCOPE_PATH/feeds
Headers:
X-Goog-User-Project: BILLING_PROJECT_ID
Request JSON body:
{ "feedId": "FEED_ID", "feed": { "assetNames": [ "ASSET_NAME_1", "ASSET_NAME_2", "..." ], "assetTypes": [ "ASSET_TYPE_1", "ASSET_TYPE_2", "..." ], "contentType": "CONTENT_TYPE", "relationshipTypes": [ "RELATIONSHIP_TYPE_1", "RELATIONSHIP_TYPE_2", "..." ], "feedOutputConfig": { "pubsubDestination": { "topic": "projects/TOPIC_PROJECT_ID/topics/TOPIC_ID" } }, "condition": { "title": "CONDITION_TITLE", "description": "CONDITION_DESCRIPTION", "expression": "CONDITION_EXPRESSION" } } }
Provide the following values:
-
SCOPE_PATH: Use one of the following values:The allowed values are:
-
projects/PROJECT_ID, wherePROJECT_IDis the ID of the project to create the feed in. -
projects/PROJECT_NUMBER, wherePROJECT_NUMBERis the number of the project to create the feed in.How to find a Google Cloud project number
Google Cloud console
To find a Google Cloud project number, complete the following steps:
-
Go to the Welcome page in the Google Cloud console.
- Click the switcher list box in the menu bar.
-
Select your organization from the list box, and then search for your project name. The project name, project number, and project ID are shown near the Welcome heading.
Up to 4,000 resources are displayed. If you don't see the project you're looking for, go to the Manage resources page and filter the list using the name of that project.
gcloud CLI
You can retrieve a Google Cloud project number with the following command:
gcloud projects describe PROJECT_ID --format="value(projectNumber)"
-
-
folders/FOLDER_ID, whereFOLDER_IDis the ID of the folder to create the feed in.How to find the ID of a Google Cloud folder
Google Cloud console
To find the ID of a Google Cloud folder, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher list box in the menu bar.
- Select your organization from the list box.
- Search for your folder name. The folder ID is shown next to the folder name.
gcloud CLI
You can retrieve the ID of a Google Cloud folder that's located at the organization level with the following command:
gcloud resource-manager folders list \ --organization=$(gcloud organizations describe ORGANIZATION_NAME \ --format="value(name.segment(1))") \ --filter='"DISPLAY_NAME":"TOP_LEVEL_FOLDER_NAME"' \ --format="value(ID)"
Where TOP_LEVEL_FOLDER_NAME is a partial or full string match for the folder's name. Remove the
--formatflag to see more information about the found folders.The previous command doesn't return the IDs of subfolders within folders. To do so, run the following command using a top level folder's ID:
gcloud resource-manager folders list --folder=FOLDER_ID
-
-
organizations/ORGANIZATION_ID, whereORGANIZATION_IDis the ID of the organization to create the feed in.How to find the ID of a Google Cloud organization
Google Cloud console
To find the ID of a Google Cloud organization, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher list box in the menu bar.
- Select your organization from the list box.
- Click the All tab. The organization ID is shown next to the organization name.
gcloud CLI
You can retrieve the ID of a Google Cloud organization with the following command:
gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"
-
-
-
BILLING_PROJECT_ID: The project ID that the default Cloud Asset Inventory service agent is in that has permissions to manage your Pub/Sub topic. Read more about setting the billing project. FEED_ID: A unique asset feed identifier.- At least one of the following asset definitions:
ASSET_NAME_#: Optional. An array of asset full names.ASSET_TYPE_#: Optional. An array of searchable asset types. RE2-compatible regular expressions are supported. If the regular expression doesn't match any supported asset type, anINVALID_ARGUMENTerror is returned. WhenassetTypesisn't specified, all asset types are returned.
CONTENT_TYPE: Optional. The content type of the metadata that you want to retrieve. WhencontentTypeisn't specified, only basic information is returned, such as asset names, the last time the assets were updated, and what projects, folders, and organizations they belong to.-
RELATIONSHIP_TYPE_#: Optional. Requires access to the Security Command Center Premium or Enterprise tier. A comma-separated list of asset relationship types that you want to retrieve. You must setCONTENT_TYPEtoRELATIONSHIPfor this to work. -
TOPIC_PROJECT_ID: The ID of the project where the Pub/Sub topic is located. -
TOPIC_ID: The ID of the Pub/Sub topic to publish notifications to. - If adding an optional feed condition, include the following details
in your command:
CONDITION_TITLE: A title to assign to the feed condition.-
CONDITION_DESCRIPTION: A description to assign to the feed condition. CONDITION_EXPRESSION: The condition expression to apply to the feed.
See the REST reference for all options.
Command examples
Run one of the following commands to create a feed in the my-topic Pub/Sub
topic that notifies when changes are made to the following resources in the
my-project project.
- The
my-bucketCloud Storage bucket - Any BigQuery table
curl (Linux, macOS, or Cloud Shell)
curl -X POST \ -H "X-Goog-User-Project: BILLING_PROJECT_ID" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "feedId": "my-feed", "feed": { "assetNames": [ "//storage.googleapis.com/my-bucket" ], "assetTypes": [ "bigquery.googleapis.com/Table" ], "contentType": "RESOURCE", "feedOutputConfig": { "pubsubDestination": { "topic": "projects/my-project/topics/my-topic" } } } }' \ https://cloudasset.googleapis.com/v1/projects/my-project/feeds
PowerShell (Windows)
$cred = gcloud auth print-access-token $headers = @{ "X-Goog-User-Project" = "BILLING_PROJECT_ID"; "Authorization" = "Bearer $cred" } $body = @" { "feedId": "my-feed", "feed": { "assetNames": [ "//storage.googleapis.com/my-bucket" ], "assetTypes": [ "bigquery.googleapis.com/Table" ], "contentType": "RESOURCE", "feedOutputConfig": { "pubsubDestination": { "topic": "projects/my-project/topics/my-topic" } } } } "@ Invoke-WebRequest ` -Method POST ` -Headers $headers ` -ContentType: "application/json; charset=utf-8" ` -Body $body ` -Uri "https://cloudasset.googleapis.com/v1/projects/my-project/feeds" | Select-Object -Expand Content
Example response
{ "name": "projects/000000000000/feeds/my-feed", "assetNames": [ "//storage.googleapis.com/my-bucket" ], "assetTypes": [ "bigquery.googleapis.com/Table" ], "contentType": "RESOURCE", "feedOutputConfig": { "pubsubDestination": { "topic": "projects/my-project/topics/my-topic" } } }
Go
To learn how to install and use the client library for Cloud Asset Inventory, see Cloud Asset Inventory client libraries.
To authenticate to Cloud Asset Inventory, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Asset Inventory, see Cloud Asset Inventory client libraries.
To authenticate to Cloud Asset Inventory, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Asset Inventory, see Cloud Asset Inventory client libraries.
To authenticate to Cloud Asset Inventory, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Asset Inventory, see Cloud Asset Inventory client libraries.
To authenticate to Cloud Asset Inventory, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Asset Inventory, see Cloud Asset Inventory client libraries.
To authenticate to Cloud Asset Inventory, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Get feeds
gcloud
gcloud asset feeds describe FEED_ID \ --SCOPE \ --billing-project=BILLING_PROJECT_ID
Provide the following values:
-
SCOPE: Use one of the following values:-
project=PROJECT_ID, wherePROJECT_IDis the ID of the project that the feed is in. -
folder=FOLDER_ID, whereFOLDER_IDis the ID of the folder that the feed is in.How to find the ID of a Google Cloud folder
Google Cloud console
To find the ID of a Google Cloud folder, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher list box in the menu bar.
- Select your organization from the list box.
- Search for your folder name. The folder ID is shown next to the folder name.
gcloud CLI
You can retrieve the ID of a Google Cloud folder that's located at the organization level with the following command:
gcloud resource-manager folders list \ --organization=$(gcloud organizations describe ORGANIZATION_NAME \ --format="value(name.segment(1))") \ --filter='"DISPLAY_NAME":"TOP_LEVEL_FOLDER_NAME"' \ --format="value(ID)"
Where TOP_LEVEL_FOLDER_NAME is a partial or full string match for the folder's name. Remove the
--formatflag to see more information about the found folders.The previous command doesn't return the IDs of subfolders within folders. To do so, run the following command using a top level folder's ID:
gcloud resource-manager folders list --folder=FOLDER_ID
-
-
organization=ORGANIZATION_ID, whereORGANIZATION_IDis the ID of the organization that the feed is in.How to find the ID of a Google Cloud organization
Google Cloud console
To find the ID of a Google Cloud organization, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher list box in the menu bar.
- Select your organization from the list box.
- Click the All tab. The organization ID is shown next to the organization name.
gcloud CLI
You can retrieve the ID of a Google Cloud organization with the following command:
gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"
-
-
-
BILLING_PROJECT_ID: The project ID that the default Cloud Asset Inventory service agent is in that has permissions to manage your Pub/Sub topic. Read more about setting the billing project. FEED_ID: A unique asset feed identifier.
See the gcloud CLI reference for all options.
Example response
assetNames:
- //storage.googleapis.com/my-bucket
assetTypes:
- bigquery.googleapis.com/Table
condition: {}
contentType: RESOURCE
feedOutputConfig:
pubsubDestination:
topic: projects/my-project/topics/my-topic
name: projects/000000000000/feeds/my-feed
REST
HTTP method and URL:
GET https://cloudasset.googleapis.com/v1/SCOPE_PATH/feeds/FEED_ID
Headers:
X-Goog-User-Project: BILLING_PROJECT_ID
Provide the following values:
-
SCOPE_PATH: Use one of the following values:The allowed values are:
-
projects/PROJECT_ID, wherePROJECT_IDis the ID of the project that the feed is in. -
projects/PROJECT_NUMBER, wherePROJECT_NUMBERis the number of the project that the feed is in.How to find a Google Cloud project number
Google Cloud console
To find a Google Cloud project number, complete the following steps:
-
Go to the Welcome page in the Google Cloud console.
- Click the switcher list box in the menu bar.
-
Select your organization from the list box, and then search for your project name. The project name, project number, and project ID are shown near the Welcome heading.
Up to 4,000 resources are displayed. If you don't see the project you're looking for, go to the Manage resources page and filter the list using the name of that project.
gcloud CLI
You can retrieve a Google Cloud project number with the following command:
gcloud projects describe PROJECT_ID --format="value(projectNumber)"
-
-
folders/FOLDER_ID, whereFOLDER_IDis the ID of the folder that the feed is in.How to find the ID of a Google Cloud folder
Google Cloud console
To find the ID of a Google Cloud folder, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher list box in the menu bar.
- Select your organization from the list box.
- Search for your folder name. The folder ID is shown next to the folder name.
gcloud CLI
You can retrieve the ID of a Google Cloud folder that's located at the organization level with the following command:
gcloud resource-manager folders list \ --organization=$(gcloud organizations describe ORGANIZATION_NAME \ --format="value(name.segment(1))") \ --filter='"DISPLAY_NAME":"TOP_LEVEL_FOLDER_NAME"' \ --format="value(ID)"
Where TOP_LEVEL_FOLDER_NAME is a partial or full string match for the folder's name. Remove the
--formatflag to see more information about the found folders.The previous command doesn't return the IDs of subfolders within folders. To do so, run the following command using a top level folder's ID:
gcloud resource-manager folders list --folder=FOLDER_ID
-
-
organizations/ORGANIZATION_ID, whereORGANIZATION_IDis the ID of the organization that the feed is in.How to find the ID of a Google Cloud organization
Google Cloud console
To find the ID of a Google Cloud organization, complete the following steps:
-
Go to the Google Cloud console.
- Click the switcher list box in the menu bar.
- Select your organization from the list box.
- Click the All tab. The organization ID is shown next to the organization name.
gcloud CLI
You can retrieve the ID of a Google Cloud organization with the following command:
gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"
-
-
-
BILLING_PROJECT_ID: The project ID that the default Cloud Asset Inventory service agent is in that has permissions to manage your BigQuery datasets and tables. Read more about setting the billing project. FEED_ID: A unique asset feed identifier.
See the REST reference for all options.
Command examples
Run one of the following commands to get a specific feed.
curl (Linux, macOS, or Cloud Shell)
curl -X GET \ -H "X-Goog-User-Project: BILLING_PROJECT_ID" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ https://cloudasset.googleapis.com/v1/projects/my-project/feeds/my-feed
PowerShell (Windows)
$cred = gcloud auth print-access-token $headers = @{ "X-Goog-User-Project" = "BILLING_PROJECT_ID"; "Authorization" = "Bearer $cred" } Invoke-WebRequest ` -Method GET ` -Headers $headers ` -Uri "https://cloudasset.googleapis.com/v1/projects/my-project/feeds/my-feed" | Select-Object -Expand Content
Example response
{ "name": "projects/000000000000/feeds/my-feed", "assetNames": [ "//storage.googleapis.com/my-bucket" ], "assetTypes": [ "bigquery.googleapis.com/Table" ], "contentType": "RESOURCE", "feedOutputConfig": { "pubsubDestination": { "topic": "projects/my-project/topics/my-topic" } } }
Go
To learn how to install and use the client library for Cloud Asset Inventory, see Cloud Asset Inventory client libraries.
To authenticate to Cloud Asset Inventory, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.