Getting started with Cloud Asset Inventory

This quickstart shows you how to export asset metadata at a point in time using Cloud Asset Inventory and the Cloud SDK gcloud asset commands.

Before you begin

Before you can start working with Cloud Asset Inventory, you must enable the Cloud Asset Inventory API, the Cloud SDK, and assign permissions. The Cloud SDK provides the gcloud command-line tool to interact with Cloud Asset Inventory and other Google Cloud services. Learn more about the gcloud tool.

Enabling the Cloud Asset Inventory API and Cloud SDK

  1. Sign in to your Google Account.

    If you don't already have one, sign up for a new account.

  2. In the Cloud Console, on the project selector page, select or create a Cloud project.

    Go to the project selector page

  3. Enable the required API.

    Enable the API

  4. Install and initialize the Cloud SDK.

Configuring permissions

To call the Cloud Asset Inventory API, you must first configure permissions.

Searching assets

  1. To search resource metadata, run the following gcloud asset search-all-resources command.

     gcloud asset search-all-resources \
        --scope SCOPE \
        --query QUERY \
        --asset-types ASSET_TYPES,… \
        --order-by ORDER_BY
    

    Where all of the following flags are optional:

    • (Optional) SCOPE: A scope can be a project, a folder, or an organization. The search is limited to the Cloud resources within this scope. The caller must be granted the cloudasset.assets.searchAllResources permission on the desired scope. If not specified, the configured project property will be used. To find the configured project, run: gcloud config get-value project. To change the setting, run: gcloud config set project PROJECT_ID.

      The allowed values are:

      • projects/PROJECT_ID (e.g., "projects/foo-bar")
      • projects/PROJECT_NUMBER (e.g., "projects/12345678")
      • folders/FOLDER_NUMBER (e.g., "folders/1234567")
      • organizations/ORGANIZATION_NUMBER (e.g., "organizations/123456")
    • (Optional) QUERY: The query statement. See how to construct a query for more information. If not specified or empty, it will search all the resources within the specified scope.

      Examples:

      • name:Important to find Cloud resources whose name contains "Important" as a word.
      • displayName:Impor* to find Cloud resources whose display name contains "Impor" as a prefix.
      • description:*por* to find Cloud resources whose description contains "por" as a substring.
      • location:us-west* to find Cloud resources whose location is prefixed with "us-west".
      • labels:prod to find Cloud resources whose labels contain "prod" as a key or value.
      • labels.env:prod to find Cloud resources that have a label "env" and its value is "prod".
      • labels.env:* to find Cloud resources that have a label "env".
      • Important to find Cloud resources that contain "Important" as a word in any of the searchable fields.
      • Impor* to find Cloud resources that contain "Impor" as a prefix in any of the searchable fields.
      • *por* to find Cloud resources that contain "por" as a substring in any of the searchable fields.
      • Important location:(us-west1 OR global) to find Cloud resources that contain "Important" as a word in any of the searchable fields and are also located in the "us-west1" region or the "global" location.
    • (Optional) ASSET_TYPES: A list of asset types to search. If not specified or empty, it will search all the searchable asset types. Example: "cloudresourcemanager.googleapis.com/Project,compute.googleapis.com/Instance" to search project and VM instance resources.

    • (Optional) ORDER_BY: A comma-separated list of fields specifying the sorting order of the results. The default order is ascending. Add " DESC" after the field name to indicate descending order. Redundant space characters are ignored. Example: "location DESC, name". Only string fields in the response are sortable, including name, displayName, description and location.

    To learn more about how to search resources, see Searching resources.

  2. To search IAM policies, run the following gcloud asset search-all-iam-policies command.

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

    Where:

    • (Optional) SCOPE: A scope can be a project, a folder, or an organization. The search is limited to the IAM policies within this scope. The caller must be granted the cloudasset.assets.searchAllIamPolicies permission on the desired scope. If not specified, the configured project property will be used. To find the configured project, run: gcloud config get-value project. To change the setting, run: gcloud config set project PROJECT_ID.

      The allowed values are:

      • projects/PROJECT_ID (e.g., "projects/foo-bar")
      • projects/PROJECT_NUMBER (e.g., "projects/12345678")
      • folders/FOLDER_NUMBER (e.g., "folders/1234567")
      • organizations/ORGANIZATION_NUMBER (e.g., "organizations/123456")
    • (Optional) QUERY: The query statement. See how to construct a query for more information. If not specified or empty, it will search all the IAM policies within the specified scope. Note that the query string is compared against each Cloud IAM policy binding, including its members, roles, and Cloud IAM conditions. The returned Cloud IAM policies will only contain the bindings that match your query. To learn more about the IAM policy structure, see IAM policy doc.

      Examples:

      • policy:amy@gmail.com to find IAM policy bindings that specify user "amy@gmail.com".
      • policy:roles/compute.admin to find IAM policy bindings that specify the Compute Admin role.
      • policy.role.permissions:storage.buckets.update to find Cloud IAM policy bindings that specify a role containing the "storage.buckets.update" permission. Note that if callers don't have iam.roles.get access to a role's included permissions, policy bindings that specify this role will be dropped from the search results.
      • resource:organizations/123456 to find IAM policy bindings that are set on "organizations/123456".
      • Important to find IAM policy bindings that contain "Important" as a word in any of the searchable fields (except for the included permissions).
      • *por* to find IAM policy bindings that contain "por" as a substring in any of the searchable fields (except for the included permissions).
      • resource:(instance1 OR instance2) policy:amy to find IAM policy bindings that are set on resources "instance1" or "instance2" and also specify user "amy".

    To learn more about how to search IAM policies, see Searching IAM policies.

Exporting an asset snapshot to Cloud Storage

To export all the asset metadata at a given timestamp to a Cloud Storage file, complete the following steps.

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

  2. To export asset metadata within your project, run 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 project where Cloud Asset Inventory API is enabled and from which you're running the export, 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. To export the assets of an organization or folder, you can use one of the following flags in place of the --project flag:

    • --organization=ORGANIZATION_ID
    • --folder=FOLDER_ID
  4. (Optional) To check the status of the export, run the following command. It is displayed in the gcloud tool after running the export command.

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

Viewing an asset snapshot

To view an asset snapshot after you've exported it to Cloud Storage, complete the following steps.

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

  2. Open the file where you exported your metadata.

The export file lists the assets and their resource names.

What's next