Viewing Asset Relationships

This topic shows you how to view the asset relationships for your organization, folder, or project to Cloud Storage bucket or BigQuery table.

Asset relationships

Many cloud assets are connected by relationships. For example, an instanceGroup contains an Instance. Relationships show as related assets to the source assets. For example, if you export INSTANCE_TO_INSTANCEGROUP relationships for asset type compute.googleapis.com/Instance, it outputs the Instance assets, whose related_assets represent instance groups it belongs to.

Before you begin

Before you begin, complete the following steps.

  1. Enable the Cloud Asset Inventory API on the project where you'll be running the API commands.
    Enable the Cloud Asset Inventory API

  2. Configure the permissions that are required to call the Cloud Asset Inventory API using either the gcloud tool or the API.

  3. Complete the following steps to set up your environment.

    gcloud

    To set up your environment to use the gcloud tool to call the Cloud Asset Inventory API, install the Cloud SDK on your local client.

    API

    To set up your environment to call the Cloud Asset Inventory API with the Unix curl command, complete the following steps.

    1. Install oauth2l on your local machine so you can interact with the Google OAuth system.
    2. Confirm that you have access to the Unix curl command.
    3. Ensure that you grant your account one of the following roles on your project, folder, or organization.

      • Cloud Asset Viewer role (roles/cloudasset.viewer)
      • Owner basic role (roles/owner)
  4. You need cloudasset.assets.exportResource permission to view asset relationships.

  5. Prepare export destination. You can use a Cloud Storage bucket or you can use a BigQuery table.

Exporting an asset relationship snapshot

These commands can store the exported relationship in a Cloud Storage bucket at gs://<var>YOUR_BUCKET/NEW_FILE</var> or a BigQuery table according to the output configuration in the requests. The following examples show how to export relationships under a project to a Cloud Storage bucket. To export the relationships of an organization or folder, replace the --project flag with --organization or --folder. To export relationships to [BigQuery], specify a [BigQuery] table for --output-path.

Exporting all supported relationships

To export an asset relationship snapshot at a given timestamp for all supported relationships, run the following command.

gcloud

gcloud beta asset export \
   --content-type relationship \
   --project PROJECT_ID \
   --output-path "gs://YOUR_BUCKET/NEW_FILE"

API

gcurl -d '{"contentType":"RELATIONSHIP", "outputConfig":{"gcsDestination": \
         {"uri":"gs://YOUR_BUCKET/NEW_FILE"}}}' \
          https://cloudasset.googleapis.com/v1p7beta1/projects/PROJECT_NUMBER:exportAssets

Exporting specified relationships

To export specified relationships in a project with asset types they attached to, run the following command.

gcloud

gcloud beta asset export \
 --content-type relationship \
 --project PROJECT_ID \
 --relationship-types INSTANCE_TO_INSTANCEGROUP \
 --output-path "gs://YOUR_BUCKET/NEW_FILE"

API

gcurl -d '{"contentType":"RELATIONSHIP", "relationshipTypes": "INSTANCE_TO_INSTANCEGROUP", "outputConfig":{"gcsDestination": \
         {"uri":"gs://YOUR_BUCKET/NEW_FILE"}}}' \
          https://cloudasset.googleapis.com/v1p7beta1/projects/PROJECT_NUMBER:exportAssets

Exporting all relationships on specific asset types

To export all supported relationships in a project that have an asset type that starts with compute.googleapis.com, run the following command.

gcloud

gcloud beta asset export \
 --content-type relationship \
 --project PROJECT_ID \
 --asset-types compute.googleapis.com.* \
 --output-path "gs://YOUR_BUCKET/NEW_FILE"

API

gcurl -d '{"contentType":"RELATIONSHIP", "assetTypes": "compute.googleapis.com.*", "outputConfig":{"gcsDestination": \
         {"uri":"gs://YOUR_BUCKET/NEW_FILE"}}}' \
          https://cloudasset.googleapis.com/v1p7beta1/projects/PROJECT_NUMBER:exportAssets

Exporting specified relationships with specified asset types

To export specified relationships in a project with asset type compute.googleapis.com/Instance, run the following command.

gcloud

gcloud beta asset export \
 --content-type relationship \
 --project PROJECT_ID \
 --asset-types compute.googleapis.com/Instance
 --relationship-types INSTANCE_TO_INSTANCEGROUP \
 --output-path "gs://YOUR_BUCKET/NEW_FILE"

API

gcurl -d '{"contentType":"RELATIONSHIP", "assetTypes": "compute.googleapis.com/Instance", "relationshipTypes": "INSTANCE_TO_INSTANCEGROUP", "outputConfig":{"gcsDestination": \
         {"uri":"gs://YOUR_BUCKET/NEW_FILE"}}}' \
          https://cloudasset.googleapis.com/v1p7beta1/projects/PROJECT_NUMBER:exportAssets

Checking the status of an export

To check the status of an export, run the following commands.

gcloud

To check the status of the export, you can run the following command. It is displayed in the gcloud tool after running the export command.

gcloud asset operations describe OPERATION_ID

API

To view the status of your export, run the following command with the operation ID returned in the response to your export.

  1. You can find the OPERATION_ID in the name field of the response to the export, which is formatted as follows:

    "name": "projects/PROJECT_NUMBER/operations/ExportAssets/CONTENT_TYPE/OPERATION_ID"
    
  2. To check the status of your export, run following command with the OPERATION_ID:

    gcurl https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/operations/ExportAssets/CONTENT_TYPE/OPERATION_ID
    

Viewing a relationship snapshot

If you exported your results to a Cloud Storage bucket, complete these steps to view them.

If you exported your results to a BigQuery table, complete these steps to view them.