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. 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 primitive role (roles/owner)

Initial setup

gcloud

Set up the gcloud command-line tool

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.

Configure an account

To call the Cloud Asset API, you need to configure either a user account or a service account.

Configuring a user account

  1. Sign in with your user account using the following command:

    gcloud auth login USER_ACCOUNT_EMAIL
    

  2. Optional. If the target project you want to call the Cloud Asset API on isn't the same as your Cloud Asset Inventory-enabled project, specify your project with the following command:

    gcloud asset --billing-project PROJECT_ID
    

  3. Grant your user account the Cloud Asset Viewer (roles/cloudasset.viewer) Cloud IAM role on the project whose metadata you want to export. This project can be the same as your Cloud Asset API-enabled project.

    gcloud projects add-iam-policy-binding EXPORT_TARGET_PROJECT_ID \
         --member user:USER_ACCOUNT_EMAIL \
         --role roles/cloudasset.viewer
    

Configuring a service account

  1. If you don't already have a service account, in the project that is Cloud Asset API-enabled, create a new service account:

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
         --display-name "SERVICE_ACCOUNT_DISPLAY_NAME"
    

  2. Create a private key for your service account. The private key will be downloaded to the specified filepath:

    gcloud iam service-accounts keys create YOUR_FILE_PATH/key.json \
         --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    

  3. Activate your service account for use with the gcloud tool:

    gcloud auth activate-service-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
         --key-file=YOUR_FILE_PATH/key.json
    

  4. Grant your new service account the Cloud Asset Viewer (roles/cloudasset.viewer) Cloud IAM role on a project whose metadata you want to export. This project can be the same as your Cloud Asset API-enabled project:

    gcloud projects add-iam-policy-binding EXPORT_TARGET_PROJECT_ID \
         --member serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
         --role roles/cloudasset.viewer
    

api

Downloading the credentials file

A JSON credentials file is needed to call the Cloud Asset API. Download the file by following the process below:

  1. Go to the Credentials page.

  2. Open the Create Credentials dropdown and select OAuth client ID.

  3. If you are creating a Client ID for a new project, you must set up the OAuth consent screen. The consent screen is displayed any time an application using your Client ID requests access to private data. If prompted:

    1. Click Configure consent screen and enter in the required information for your consent screen.

    2. Save your changes to return to creating your Client ID.

  4. On the Create client ID page under Application type, select Other.

  5. Enter a name for the credential, then click Create. A confirmation dialog appears with a client ID and client secret.

  6. Close the confirmation dialog and click the download icon on the right to save your new Client ID JSON file.

  7. Name and move the downloaded JSON file so that the path is ~/credentials.json.

Preparing your environment

Prepare you environment for making calls to the Cloud Asset API by following the process below.

  1. Verify your initial setup with the following command.

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

    You should see an output similar to the following:

    Authorization: Bearer y29.xxxxxxx
    
  2. Define a shell alias to call Google REST APIs from with the following command.

    alias gcurl='curl -H "$(oauth2l header --json ~/credentials.json \
    cloud-platform)" -H "Content-Type: application/json" '
    

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

The commands shown in this section get 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 latest possible start-time of a timeframe is 2018-10-03T00:00:00Z.

  1. Ensure that you can call the Cloud Asset API by completing the initial setup.
  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:

gcloud asset get-history --project='PROJECT_ID' \
  --asset-names='//compute.googleapis.com/projects/test-project/zo\
nes/us-central1-f/instances/instance1' \
  --start-time='2018-10-02T15:01:23.045Z' \
  --end-time='2018-12-05T13:01:21.045Z' --content-type='resource'

Get the history of all Cloud IAM policies of the specified assets in a project:

gcloud asset get-history --project='PROJECT_ID' \
  --asset-names='//cloudresourcemanager.googleapis.com/projects/10\
179387634' --start-time='2018-10-02T15:01:23.045Z' \
  --end-time='2018-12-05T13:01:21.045Z' \
  --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 initial setup.
  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

gcurl -d '{"contentType":"RESOURCE", \
           "assetNames": \
             "//compute.googleapis.com/projects/my_project_id/global/firewalls/default-firewall", \
           "readTimeWindow": {"startTime": "2014-10-02T15:01:23.045123456Z"}}' \
      https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:batchGetAssetsHistory

Get the history of the specified assets in a project, without resource metadata

gcurl -d '{"assetNames": \
             "//compute.googleapis.com/projects/my_project_id/global/firewalls/default-firewall", \
           "readTimeWindow": {"startTime": "2014-10-02T15:01:23.045123456Z"}}' \
      https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:batchGetAssetsHistory

Get the history of all Cloud IAM policies of the specified assets in a project

gcurl -d '{"contentType":"IAM_POLICY", \
           "assetNames": \
             "//compute.googleapis.com/projects/my_project_id/global/firewalls/default-firewall", \
           "readTimeWindow": {"startTime": "2014-10-02T15:01:23.045123456Z"}}' \
      https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:batchGetAssetsHistory