Viewing VM Manager data

This topic shows you how to configure Cloud Asset Inventory and VM Manager's OS inventory so that you can view the runtime information of your VMs.

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 CLI or the API.

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

   gcloud

   To set up your environment to use the gcloud CLI to call the Cloud Asset Inventory API, install the Google Cloud CLI 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)

Enabling OS inventory

To enable OS inventory, which is part of the VM Manager suite, complete the relevant steps in Setting up VM Manager.

Setting permissions

Ensure that your account has the cloudasset.assets.exportOSInventories permission on the root resource that contains the assets you want export. You can grant this permission individually, or you can grant one of the following roles on the root resource.

• Cloud Asset Viewer (roles/cloudasset.viewer) role
• Cloud Asset Owner (roles/cloudasset.owner) role

Learn more about configuring permissions and Cloud Asset Inventory IAM roles.

Exporting VM Manager data to BigQuery

Note: Appending the export output to an existing table is not supported. The destination table must be empty or you must overwrite it. To overwrite it, use the --output-bigquery-force flag with the gcloud CLI, or use force with the API.

To export OS inventory snapshot at a given timestamp, complete the following steps.

gcloud

  gcloud asset export \
     --content-type os-inventory \
     --project 'PROJECT_ID' \
     --snapshot-time 'SNAPSHOT_TIME' \
     --bigquery-table 'BIGQUERY_TABLE' \
     --output-bigquery-force

Where:

• PROJECT_ID is the ID of the project whose metadata is being exported. This project can be the one from which you're running the export or a different project.
• SNAPSHOT_TIME (Optional) is the time at which you want to take a snapshot of your assets. The value must be the current time or a time in the past. By default, a snapshot is taken at the current time. For information on time formats, see gcloud topic datetimes.
• BIGQUERY_TABLE is the table to which you're exporting your metadata, in the format projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME.
• --output-bigquery-force overwrites the destination table if it exists.

To export the assets of an organization or folder, you can use one of the following flags in place of --project.

• --organization=ORGANIZATION_ID
• --folder=FOLDER_ID

API

gcurl -d '{"contentType":"OS_INVENTORY", \
  "outputConfig":{ \
    "bigqueryDestination": { \
      "dataset": "projects/PROJECT_ID/datasets/DATASET_ID",\
      "table": "TABLE_NAME", \
      "force": true \
    } \
  }}' \
  https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:exportAssets

To export VM Manager vulnerability reports from a project to BigQuery, use the following gcloud CLI command or the Cloud Asset Inventory API.

gcloud

gcloud asset export \
 --asset-types='osconfig.googleapis.com/VulnerabilityReport' \
 --content-type=resource \
 --project=PROJECT_ID \
 --bigquery-table 'BIGQUERY_TABLE' \
 --output-bigquery-force

API

gcurl -d '{"contentType":"RESOURCE","assetTypes": ["osconfig.googleapis.com/VulnerabilityReport"],
 "outputConfig":{ \
   "bigqueryDestination": { \
     "dataset": "projects/PROJECT_ID/datasets/DATASET_ID",\
     "table": "TABLE_NAME", \
     "force": true  \
   } \
 }}' \
 https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:exportAssets

Learn more about the exportAssets method.

Exporting VM Manager data to Cloud Storage

To export the VM Manager inventory data for all VM instances in a project, use the following gcloud CLI command or the Cloud Asset Inventory API.

gcloud

gcloud asset export \
 --content-type=os-inventory \
 --project=PROJECT_ID \
 --output-path="gs://YOUR_BUCKET/NEW_FILE"

API

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

To export VM Manager vulnerability reports from a project to Cloud Storage, use the following gcloud CLI command or the Cloud Asset Inventory API.

gcloud

gcloud asset export \
 --asset-types='osconfig.googleapis.com/VulnerabilityReport' \
 --content-type=resource \
 --project=PROJECT_ID \
 --output-path="gs://YOUR_BUCKET/NEW_FILE"

API

gcurl -d '{"contentType":"RESOURCE","assetTypes": ["osconfig.googleapis.com/VulnerabilityReport"],
 "outputConfig":{ \
   "gcsDestination": {"uri":"gs://YOUR_BUCKET/NEW_FILE"}}}' \
    https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:exportAssets

Learn more about the exportAssets method.

Getting VM Manager data history

To get the create, delete, and update history of specified assets in a project within a given timeframe using the Cloud Asset API, follow the process below.

Note: Getting the history of assets in a folder isn't supported.

gcloud

To get the history of all OS inventory assets for a specified VM instance in a project, run the gcloud asset get-history command.

YESTERDAY=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ" -d "yesterday")
NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
gcloud asset get-history --project='PROJECT_ID' \
  --asset-names='//compute.googleapis.com/projects/my_project_number/global/instances/instancel' --start-time=$YESTERDAY \
  --end-time=$NOW \
  --content-type='os-inventory'
 

Note: You can get the history of OS inventory assets for more than one VM instance, but make sure that all instances are in the same project specified by the --project flag.

To get the history of VM Manager vulnerability data for a specific VM in a project, run the following gcloud asset get-history command.

YESTERDAY=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ" -d "yesterday")
NOW=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ")
gcloud asset get-history --project='PROJECT_ID' \
  --asset-names='//osconfig.googleapis.com/projects/my_project_number/global/instances/instancel/vulnerabilityReport' --start-time=$YESTERDAY \
  --end-time=$NOW \
  --content-type='resource'
 

API

The commands shown in this section get the history of a project. To get the history of an organization, use the https://cloudasset.googleapis.com/v1/organizations/ORGANIZATION_NUMBER:batchGetAssetsHistory REST method in the gcurl command.

1. Ensure that you can call the Cloud Asset API by completing the Configure an account.
2. Determine the full resource name of the asset you want to find the history of. See a list of Cloud Asset API-formatted names here. The following example uses //compute.googleapis.com/projects/my_project_number/global/instances/instancel.
3. Determine a start and end time for your timeframe that is in the RFC 3339 UTC format. Only a start time is required. See TimeWindow for more information.
4. Determine at what level you want to get the history of assets. The following example commands demonstrate how to get the history of various kinds of assets.

To get the access token, run the following command with the ~/credentials.json file.

oauth2l header --json ~/credentials.json cloud-platform

You should see an output similar to the following, with y29.xxxxxx as the access token:

Authorization: Bearer y29.xxxxxxx

Set the TOKEN var to the access token:

TOKEN=y29.xxxxxxx

To get the history of all OS inventory assets for a specified VM instance in a project, run the following command.

YESTERDAY=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ" -d "yesterday")
curl -X POST  -H "X-HTTP-Method-Override: GET" \
     -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{"contentType":"OS_INVENTORY", \
          "assetNames": \
            "//compute.googleapis.com/projects/my_project_number/global/instances/instancel", \
          "readTimeWindow": {"startTime": "'$YESTERDAY'"}}' \
     https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:batchGetAssetsHistory

To get the history of VM Manager vulnerability data for a specific VM in a project, run the following command.

YESTERDAY=$(TZ=GMT date +"%Y-%m-%dT%H:%M:%SZ" -d "yesterday")
curl -X POST  -H "X-HTTP-Method-Override: GET" \
     -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{"contentType":"RESOURCE", \
          "assetNames": \
            "//compute.googleapis.com/projects/my_project_number/global/instances/instancel/vulnerabilityReport", \
          "readTimeWindow": {"startTime": "'$YESTERDAY'"}}' \
     https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:batchGetAssetsHistory

Learn more about the batchGetAssetsHistory method.

Monitoring changes of VM Manager data

gcloud

To create a feed using the gcloud asset feeds create command for monitoring VMs with Windows OS installed:

gcloud asset feeds create FEED_ID --project=PROJECT_ID \
--content-type=os-inventory --asset-types="compute.googleapis.com/Instance" \
--pubsub-topic="TOPIC_NAME" --condition-title="CONDITION_TITLE" \
--condition-description="CONDITION_DESCRIPTION" \
--condition-expression="temporal_asset.asset.os_inventory.os_info.short_name == 'windows'"

To create a feed for monitoring the VM vulnerability data in a project, run the following command:

gcloud asset feeds create FEED_ID --project=PROJECT_ID \
--content-type=resource --asset-types="osconfig.googleapis.com/VulnerabilityReport" \
--pubsub-topic="TOPIC_NAME" --condition-title="CONDITION_TITLE" \
--condition-description="CONDITION_DESCRIPTION" \

API

To create a feed using the feeds.create() API for monitoring VMs with Windows OS installed:

curl -H "Authorization: Bearer $TOKEN" \\
    -H "Content-Type: application/json" -X POST \\
    -d '{"feedId": "FEED_ID",
         "feed": { "assetTypes": ["compute.googleapis.com/Instance"],
         "contentType": "OS_INVENTORY",
         "feedOutputConfig": {"pubsubDestination": {"topic":"TOPIC_NAME"}},
         "condition": {"title": "CONDITION_TITLE",
         "description": "CONDITION_DESCRIPTION",
         "expression": "temporal_asset.asset.os_inventory.os_info.short_name == 'windows'"}}}' \\
    https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/feeds

To create a feed for monitoring the VM vulnerability data, use the following method:

curl -H "Authorization: Bearer $TOKEN" \\
    -H "Content-Type: application/json" -X POST \\
    -d '{"feedId": "FEED_ID",
         "feed": { "assetTypes": ["osconfig.googleapis.com/VulnerabilityReport"],
         "contentType": "RESOURCE",
         "feedOutputConfig": {"pubsubDestination": {"topic":"TOPIC_NAME"}},
         "condition": {"title": "CONDITION_TITLE",
         "description": "CONDITION_DESCRIPTION",
          }}}' \\
    https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/feeds

See more details here.