Viewing asset history

Stay organized with collections Save and categorize content based on your preferences.

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

  1. 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
  2. Install the Google Cloud CLI on your local client.

REST

  1. Confirm that you have access to the curl command.

  2. 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)

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.

  1. Ensure that you can call the Cloud Asset API by completing the Configure an account.
  2. 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.
  3. Determine the content type you want to monitor. This is the content-type variable in the examples below.
  4. 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.
  5. 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.

  1. Ensure that you can call the Cloud Asset API by completing the Configure an account.
  2. 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.
  3. 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.
  4. 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