This page describes how to export asset metadata and get asset history using the
gcloud asset commands.
The Cloud SDK provides the
gcloud command-line tool to interact
with Cloud Asset Inventory and other Google Cloud Platform services.
Before you begin
gcloudtool uses the Cloud Asset API to access Google Cloud Platform. You must enable the API before you can use the
gcloudtool 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 Cloud SDK on your local client.
Getting started with 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
gcloud asset --help
The help displayed with the
--help flag is also available in the Cloud SDK
Configuring an account
To call the Cloud Asset API, you need a configured user account or service account.
Configuring a user account
Log in with your user account using the following command.
gcloud auth login USER_ACCOUNT_EMAIL
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 config set billing/quota_project PROJECT_ID
Grant your user account the
cloudasset.viewerCloud 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
This service account should be created for the project you're running Cloud Asset API commands from.
If you don't already have a service account, in the project that is Cloud Asset API enabled, create a new service account with the following command.
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \ --display-name "SERVICE_ACCOUNT_DISPLAY_NAME"
Create a private key for your service account.
gcloud iam service-accounts keys create YOUR_FILE_PATH/key.json \ --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
Activate your service account for use with the
gcloudtool with the following command.
gcloud auth activate-service-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \ --key-file=YOUR_FILE_PATH/key.json
Grant your new service account the
cloudasset.viewerCloud 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
Calling gcloud asset
The following are some examples of
gcloud Cloud Asset API
calls on projects. Cloud Asset API calls also work on folders and organizations.
Export all the asset metadata at a given timestamp to a Cloud Storage file. The Cloud Storage bucket you use to store exported metadata must be in the Cloud Asset API enabled project you're running the export from. This method can also be used to export assets for an entire organization or a folder.
The following example exports asset metadata within a project.
gcloud asset export \ --content-type resource \ --project PROJECT_ID \ --output-path "gs://YOUR_BUCKET/NEW_FILE"
Note that PROJECT_ID is the ID of the project that is having its metadata exported. This project can be either the Cloud Asset API enabled project you're running the export from, or a different project.
Check the status of an export.
The following command and the OPERATION_NUMBER are displayed in the
gcloud tool immediately after running an export command.
gcloud asset operations describe projects/PROJECT_ID/operations/ExportAssets/CONTENT_TYPE/OPERATION_NUMBER
Get the history of multiple assets for a given timeframe. This shows you all the create, delete, and update events for the specifed assets over time. This method can be used to get the history of assets within a project or an organization.
The following example gets the history of assets within a project.
gcloud asset get-history --asset-names="//storage.googleapis.com/BUCKET_NAME","otherAssetNames" \ --content-type resource \ --start-time '2018-10-03T00:00:00Z' \ --project PROJECT_ID
Note that the latest possible
start-time of a timeframe is