Viewing asset history

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 during 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

  1. You must enable the Cloud Asset API before you can use the gcloud tool 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 Cloud SDK on your local client.

api

  1. Install oauth2l on your local machine for interacting with the Google OAuth system.
  2. Confirm that you have access to the Unix curl command.
  3. 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
  • 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 within a given timeframe using the Cloud Asset API, follow the process below.

gcloud

To get started with the gcloud tool, review the Cloud SDK 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 Cloud SDK 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 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")
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'
 

api

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 in the gcurl command.

  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.

Set TOKEN Var

To get the access token, run the following command with the ~/credentials.json file.

oauth2l header --json ~/credentials.json cloud-platform

You should see an output similar to the following, with y29.xxxxxx as the access token:

Authorization: Bearer y29.xxxxxxx

Set the TOKEN var to the access token:

TOKEN=y29.xxxxxxx

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 $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 $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 $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