Cloud Asset Inventory Quickstart

This guide walks you through exporting a snapshot and getting the history of assets in a project using a Compute Engine virtual machine (VM) instance and the Cloud Asset API. You can also call the Cloud Asset API for an entire organization. See the Cloud Asset Inventory overview for more information.

Before you begin

  1. Enable the Cloud Asset API for your project.

  2. Apply one of the following roles on your project or organization.

    • roles/viewer
    • roles/cloudasset.viewer Roles that encompass one of these roles also grant access. For more information on roles and permissions, see Understanding roles.

Setting up your instance

  1. Create a new service account if you don't have an existing service account within your project.
  2. Grant your service account the viewer or cloudasset.viewer role to enable the Cloud Asset API.
  3. Create a new bucket if your project doesn't have an existing Cloud Storage bucket that is available to store exported data.
  4. Set up a new Compute Engine VM instance by going to the Create an instance page and selecting your Service account.

    Go to the Create instance page

  5. Under Access scopes, select Allow full access to all Cloud APIs.
  6. Launch your instance by clicking Create.

Exporting an asset snapshot

To export all the asset metadata of your project using the Cloud Asset API, follow the process below. To export asset metadata for an organization, use https://cloudasset.googleapis.com/v1beta1/organizations/ORGANIZATION_NUMBER:exportAssets in the curl command instead.

  1. Go to the VM Instance page.

    Go to the VM Instance page

  2. Open a web SSH client connected to the instance by clicking the SSH button next to the instance listing.
  3. In the web SSH client, generate an auth token for your service account with the following call.

    TOKEN=$(gcloud auth print-access-token)
    
  4. Export all the asset metadata of your project using the following curl command:

    curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
         -d '{"contentType":"RESOURCE", "outputConfig":{"gcsDestination":{"uri":"gs://YOUR_BUCKET/NEW_FILE"}}}' \
            https://cloudasset.googleapis.com/v1beta1/projects/PROJECT_NUMBER:exportAssets
    

You can also export asset metadata on a more granular level using the following commands:

Export Cloud IAM policies in a project

curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{"contentType":"IAM_POLICY", "outputConfig":{"gcsDestination":{"uri":"gs://YOUR_BUCKET/NEW_FILE"}}}' \
        https://cloudasset.googleapis.com/v1beta1/projects/PROJECT_NUMBER:exportAssets

Export all asset names without metadata in a project

curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{"outputConfig":{"gcsDestination":{"uri":"gs://YOUR_BUCKET/NEW_FILE"}}}' \
        https://cloudasset.googleapis.com/v1beta1/projects/PROJECT_NUMBER:exportAssets

Viewing an asset snapshot

To see your exported assets, go to the Cloud Storage Browser page and open the new file. The export lists the assets and their resource names.

Checking the status of an export

Exporting assets is a long running process that for most organizations takes seconds. This process can take longer for large organizations with many projects and assets. The operation number of an export is used to check the status of an export request.

To check the status of an export:

  1. Get the operation number from the name field of the response.

    "name": "projects/PROJECT_NUMBER/operations/ExportAssets/OPERATION_NUMBER"
    
  2. Open the web SSH client for your instance and enter the following curl command.

    curl -H "Authorization: Bearer $TOKEN" \
         -H "Content-Type: application/json" \
            https://cloudasset.googleapis.com/v1beta1/projects/PROJECT_NUMBER/operations/ExportAssets/OPERATION_NUMBER
    

A response similar to the following is returned. The done field is set to true if the export process has been completed.

{
  "name": "projects/PROJECT_NUMBER/operations/ExportAssets/OPERATION_NUMBER",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.asset.v1beta1.ExportAssetsRequest",
    "parent": "projects/PROJECT_NUMBER",
    "outputConfig": {
      "gcsDestination": {
        "uri": "gs://YOUR_BUCKET/NEW_FILE"
      }
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.asset.v1beta1.ExportAssetsResponse",
    "readTime": [timestamp],
    "outputConfig": {
      "gcsDestination": {
        "uri": "gs://YOUR_BUCKET/NEW_FILE"
      }
    }
  }
}

Getting the history of assets

To get the create, delete, and update history of specifed assets in a project within a given timeframe using the Cloud Asset API, follow the process below.

To get the update history for an organization, use https://cloudasset.googleapis.com/v1beta1/projects/ORGANIZATION_NUMBER:batchGetAssetsHistory in the curl command instead.

  1. Go to the VM Instance page.

    Go to the VM Instance page

  2. Open a web SSH client connected to your instance by clicking the SSH button next to the instance listing.
  3. In the web SSH client, generate an auth token for your service account with the following call:

    TOKEN=$(gcloud auth print-access-token)
    
  4. Determine the full resource name of the asset you want to find the history of. The following example uses //compute.googleapis.com/projects/PROJECT_ID/global/firewalls/default-firewall.

  5. 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.

  6. Get the history of the specified assets in a project, including all resource metadata:

    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/PROJECT_ID/global/firewalls/default-firewall", \
                      "readTimeWindow": {"startTime": "2014-10-02T15:01:23.045123456Z"}}' \
                 https://cloudasset.googleapis.com/v1beta1/projects/PROJECT_NUMBER:batchGetAssetsHistory

The history will be returned in the following format:

{
  "assets": [
    {
      "window": {
        "startTime": 

You can export asset metadata history on a more granular level using the following commands:

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

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": "2014-10-02T15:01:23.045123456Z"}}' \
             https://cloudasset.googleapis.com/v1beta1/projects/PROJECT_NUMBER:batchGetAssetsHistory

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

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": "2014-10-02T15:01:23.045123456Z"}}' \
             https://cloudasset.googleapis.com/v1beta1/projects/PROJECT_NUMBER:batchGetAssetsHistory
Was this page helpful? Let us know how we did:

Send feedback about...

Resource Manager Documentation