Getting started with Cloud Asset Inventory and services

This page describes how to get started with Cloud Asset Inventory and services by exporting asset metadata at a point in time using the Cloud SDK gcloud asset commands.

The Cloud SDK provides the gcloud command-line tool to interact with Cloud Asset Inventory and other Google Cloud services.

Before you begin

  • The gcloud tool uses the Cloud Asset API to access Google Cloud. You must enable the 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
  • 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 --help flag:

gcloud asset --help

The help displayed with the --help flag is also available in the Cloud SDK reference for gcloud asset.

Configuring accounts

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

Configuring a user account

  1. Log 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 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

This service account should be created for the project you're running Cloud Asset API commands from.

  1. 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"
    

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

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

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

Searching assets

  1. To search resource metadata, run the gcloud asset search-all-resources command below. To learn more about how to search resources, see Searching resources.

     gcloud beta asset search-all-resources \
        --scope SCOPE \
        --query QUERY
    

    Where all of the following flags are optional:

    • (Optional) SCOPE: The search result scope is limited within a project, folder, or organization. You must have the cloudasset.assets.searchAllResources permission granted to the caller for the desired scope. The default value is your configured project property. The allowed values are:
      • projects/PROJECT_ID (e.g., "projects/foo")
      • projects/PROJECT_NUMBER (e.g., "projects/12345")
      • folders/FOLDER_NUMBER (e.g., "folders/1234")
      • organizations/ORGANIZATION_NUMBER (e.g., "organizations/123")
    • (Optional) QUERY: The query statement. See How to construct a query for more information. Some examples include:
      • "foo" to find resources whose metadata contains "foo" as a substring.
      • "name : foo" to find resources whose names contain "foo" as a word.
  2. To search Cloud IAM policies, run the gcloud asset search-all-iam-policies command below. To learn more about how to search Cloud IAM policies, see Searching IAM policies.

     gcloud beta asset search-all-iam-policies \
        --scope SCOPE \
        --query QUERY \
    

    Where:

    • (Optional) SCOPE: The search result scope is limited within a project, folder, or organization. You must have the cloudasset.assets.searchAllIamPolicies permission granted to the caller for the desired scope. The default value is your configured project property. The allowed values are:
      • projects/PROJECT_ID (e.g., "projects/foo")
      • projects/PROJECT_NUMBER (e.g., "projects/12345")
      • folders/FOLDER_NUMBER (e.g., "folders/1234")
      • organizations/ORGANIZATION_NUMBER (e.g., "organizations/123")
    • (Optional) QUERY: The query statement. See How to construct a query for more information. Some examples include:
      • "policy : amy@gmail.com": to find Cloud IAM policies that specify user "amy".
      • "policy : compute.admin": to find Cloud IAM policies that specify the Compute Admin (roles/compute.admin) role.
      • "resource : projects/123456": to find Cloud IAM policies that are set on "projects/123456".

Exporting an asset snapshot to Cloud Storage

To export all the asset metadata at a given timestamp to a Cloud Storage file, follow the process below.

  1. Create a new bucket if your project doesn't have an existing Cloud Storage bucket that is available to store exported data.

  2. Export asset metadata within your project with the following command. This command stores the exported snapshot in a Cloud Storage bucket at gs://YOUR_BUCKET/NEW_FILE.

    gcloud asset export \
       --content-type resource \
       --project PROJECT_ID \
       --snapshot-time SNAPSHOT_TIME \
       --output-path "gs://YOUR_BUCKET/NEW_FILE"
    

    Where:

    • PROJECT_ID: The ID of the project that is having its metadata exported. This project can be either the Cloud Asset API-enabled project that you're running the export from, or a different project.
    • (Optional) SNAPSHOT_TIME: The value must be the current time or a time in the past at which you want to take a snapshot of your assets. By default, a snapshot is taken at the current time. See gcloud topic datetimes for information on time formats.
  3. Optional. Run the command displayed in the gcloud tool that appears after running the export command to check the status of the export:

    gcloud asset operations describe projects/PROJECT_ID/operations/ExportAssets/CONTENT_TYPE/OPERATION_NUMBER
    

Viewing an asset snapshot

  1. Go to the Cloud Storage Browser page.
    Open the Cloud Storage Browser page

  2. Open the new file you exported your metadata to.

The export lists the assets and their resource names.

What's next