This page explains how to view the history of assets. The Cloud Asset API allows you to view the event change history of multiple assets whose time window overlaps with a given timeframe within the past five weeks. The event change history shows you all create, delete, and update events for the specified assets over time.
Before you begin
gcloud CLI
- You must enable the Cloud Asset API before you can use the gcloud CLI to
access Cloud Asset Inventory. Note that the API only needs to be enabled
on the project you'll be running Cloud Asset API commands from.
Enable the Cloud Asset Inventory API - Install the Google Cloud CLI on your local client.
REST
- Confirm that you have access to the
curl
command. Ensure that your account has been granted one of the following roles on your project, folder, or organization:
- Cloud Asset Viewer (
roles/cloudasset.viewer
) - Owner basic role (
roles/owner
)
- Cloud Asset Viewer (
Configure an account
Depending on the
contentType
parameter of the API request, to call the Cloud Asset API, your account must be
granted a role that contains the following permissions on the root/parent
resource (project or organization) that contains assets you want to get history
for:
cloudasset.assets.exportResource
(for both Resource and Relationship)cloudasset.assets.exportIamPolicy
cloudasset.assets.exportOrgPolicy
cloudasset.assets.exportAccessPolicy
If your account has been granted the Cloud Asset Viewer
(roles/cloudasset.viewer
) role, the Cloud Asset Owner
(roles/cloudasset.owner
) role, or the Owner (roles/owner
) basic role on the
resource root, it already has sufficient permissions to call Cloud Asset API.
Otherwise, follow the steps on the
Configuring Permissions page.
Getting asset history
To get the create, delete, and update history of specified assets in a project whose time window overlaps with a given timeframe using the Cloud Asset API, follow the process below.
gcloud CLI
To get started with the gcloud CLI, review the
Google Cloud CLI Documentation.
You can get help for the tool, resources, and commands by using the --help
flag:
gcloud asset --help
The help text displayed with the --help
flag is also available in the
Google Cloud CLI reference for
gcloud asset
.
The gcloud asset get-history
shown in this section gets the history
of a project. To get the history of an organization, use the
--organization=ORGANIZATION_ID
flag in your command.
The following example gets the history of assets within a project.
Note that the start-time
must be after the current time minus 35 days.
- Ensure that you can call the Cloud Asset API by completing the Configure an account.
- Determine the full resource name of the asset you want to find the history of. See a list of Cloud Asset API-formatted names here. This is the asset-names variable in the following examples.
- Determine the content type you want to monitor. This is the
content-type
variable in the examples below. - Determine a start and end time for your timeframe that is in the
RFC 3339 UTC format. Only a start time is required. See
TimeWindow
for more information. - Determine at what level you want to get the history of assets. The following example commands demonstrate how to get the history of various kinds of assets.
Get the history of the specified assets in a project, including all resource metadata
YESTERDAY=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ" -d "yesterday") NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ") gcloud asset get-history --project='PROJECT_ID' \ --asset-names='//compute.googleapis.com/projects/test-project/zo\ nes/us-central1-f/instances/instance1' \ --start-time=$YESTERDAY \ --end-time=$NOW --content-type='resource'
Get the history of all IAM policies of the specified assets in a project
YESTERDAY=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ" -d "yesterday") NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ") gcloud asset get-history --project='PROJECT_ID' \ --asset-names='//cloudresourcemanager.googleapis.com/projects/10\ 179387634' --start-time=$YESTERDAY \ --end-time=$NOW \ --content-type='iam-policy'
Get the history of all relationships of the specified assets in a project
YESTERDAY=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ" -d "yesterday") NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ") gcloud asset get-history --project='PROJECT_ID' \ --asset-names='//compute.googleapis.com/projects/test/zones/us-central1/instances/1' --start-time=$YESTERDAY \ --end-time=$NOW \ --content-type='relationship'
Get the history of specified relationships of the specified assets in a project
YESTERDAY=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ" -d "yesterday") NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ") gcloud asset get-history --project='PROJECT_ID' \ --asset-names='//compute.googleapis.com/projects/test/zones/us-central1/instances/1' --start-time=$YESTERDAY \ --relationship-types='INSTANCE_TO_INSTANCEGROUP' --end-time=$NOW \ --content-type='relationship'
REST
The commands shown in this section get the history of a project. To get the
history of an organization, use the https://cloudasset.googleapis.com/v1/organizations/ORGANIZATION_NUMBER:batchGetAssetsHistory
REST method.
- Ensure that you can call the Cloud Asset API by completing the Configure an account.
- Determine the
full resource name
of the asset you want to find the history of. See a list of
Cloud Asset API-formatted names here.
The following example uses
//compute.googleapis.com/projects/my_project_id/global/firewalls/default-firewall
. - Determine a start and end time for your timeframe that is in the RFC 3339 UTC format.
Only a start time is required. See
TimeWindow
for more information. - Determine at what level you want to get the history of assets. The following example commands demonstrate how to get the history of various kinds of assets.
Get the history of the specified assets in a project, including all resource metadata
YESTERDAY=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ" -d "yesterday") curl -X POST -H "X-HTTP-Method-Override: GET" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{"contentType":"RESOURCE", \ "assetNames": \ "//compute.googleapis.com/projects/my_project_id/global/firewalls/default-firewall", \ "readTimeWindow": {"startTime": "'$YESTERDAY'"}}' \ https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:batchGetAssetsHistory
Get the history of the specified assets in a project, without resource metadata
YESTERDAY=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ" -d "yesterday") curl -X POST -H "X-HTTP-Method-Override: GET" \ -H "Authorization: Bearer $(gcloud auth print-access-token)"\ -H "Content-Type: application/json" \ -d '{"assetNames": \ "//compute.googleapis.com/projects/my_project_id/global/firewalls/default-firewall", \ "readTimeWindow": {"startTime": "'$YESTERDAY'"}}' \ https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:batchGetAssetsHistory
Get the history of all IAM policies of the specified assets in a project
YESTERDAY=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ" -d "yesterday") curl -X POST -H "X-HTTP-Method-Override: GET" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{"contentType":"IAM_POLICY", \ "assetNames": \ "//compute.googleapis.com/projects/my_project_id/global/firewalls/default-firewall", \ "readTimeWindow": {"startTime": "'$YESTERDAY'"}}' \ https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:batchGetAssetsHistory
Get the history of all relationships of the specified assets in a project
YESTERDAY=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ" -d "yesterday") curl -X POST -H "X-HTTP-Method-Override: GET" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{"contentType":"RELATIONSHIP", \ "assetNames": \ "//compute.googleapis.com/projects/test/zones/us-central1/instances/1", \ "readTimeWindow": {"startTime": "'$YESTERDAY'"}}' \ https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:batchGetAssetsHistory
Get the history of specified relationships of the specified assets in a project
YESTERDAY=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ" -d "yesterday") curl -X POST -H "X-HTTP-Method-Override: GET" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{"contentType":"RELATIONSHIP", \ "assetNames": \ "//compute.googleapis.com/projects/test/zones/us-central1/instances/1", \ "relationshipTypes": "'INSTANCE_TO_INSTANCEGROUP'" "readTimeWindow": {"startTime": "'$YESTERDAY'"}}' \ https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:batchGetAssetsHistory
Get the history of ALL relationships on the specified assets in a project
YESTERDAY=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ" -d "yesterday") gcurl -d '{"contentType":"RELATIONSHIP", \ "assetNames": \ "//compute.googleapis.com/projects/test/zones/us-central1/instances/1", \ "readTimeWindow": {"startTime": "'$YESTERDAY'"}}' \ https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:batchGetAssetsHistory
Get the history of specified relationships on the specified assets in a project
YESTERDAY=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ" -d "yesterday") gcurl -d '{"contentType":"RELATIONSHIP", \ "assetNames": \ "//compute.googleapis.com/projects/test/zones/us-central1/instances/1", \ "relationshipTypes": "INSTANCE_TO_INSTANCEGROUP", \ "readTimeWindow": {"startTime": "'$YESTERDAY'"}}' \ https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:batchGetAssetsHistory