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.
Enable the Cloud Asset Inventory API on the project where you'll be running the API commands.
Enable the Cloud Asset Inventory APIConfigure the permissions that are required to call the Cloud Asset Inventory API using either the gcloud CLI or the API.
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.- Install oauth2l on your local machine so you can interact with the Google OAuth system.
- Confirm that you have access to the Unix
curl
command. 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
)
- Cloud Asset Viewer role (
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
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.
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'
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.
- Ensure that you can call the Cloud Asset API by completing the Configure an account.
- 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
. - 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. - 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.