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

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