This page describes how to set up and use OS inventory management. For an overview of OS inventory management, see OS inventory management.
Use OS inventory management to collect and view operating system details for your VM instances (VMs). These operating system details include information such as hostname, operating system, and kernel version as well as installed packages, and available package updates for the operating system. For a list of common scenarios for using OS inventory management, review When to use OS inventory management.
Before you begin
- If you want to use the command-line examples in this guide:
- Install or update to the latest version of the gcloud command-line tool.
- Set a default region and zone.
- If you want to use the API examples in this guide, set up API access.
Supported operating systems
For the full list of operating systems and versions that support OS inventory management, see Operating system details. For the most up-to-date operating systems support, see Operating system details.
Overview
Before you can use OS inventory management, you need to configure your VMs to use the feature. To configure your VMs to use OS inventory management, you must complete the following procedures:
- On each VM or on the entire project, enable guest attributes and the OS Inventory metadata keys.
- On each VM, install the OS Config agent.
- (Optional) If you want to integrate with Cloud Asset Inventory, see OS inventory and Cloud Asset Inventory integration
After setting up OS inventory management on your VMs, you can then view operating system details.
OS inventory and Cloud Asset Inventory integration
OS inventory management stores and forwards data to Cloud Asset Inventory. Cloud Asset Inventory is a metadata inventory service that allows you to view, monitor, and analyze assets across Google Cloud. From Cloud Asset Inventory, you can poll the information and view changes in the data.
To access OS inventory data from Cloud Asset Inventory, you need to complete the following setup:
- On your Google Cloud project, enable the OS Config API.
- On your VM or project, enable the OS Config agent metadata keys.
- On each VM, install the OS Config agent.
- On your Google Cloud project, enable the Cloud Asset Inventory API, the Cloud SDK, and assign permissions.
Enable guest attributes and OS inventory management
To enable guest attributes and OS inventory management you need to set some specific metadata keys.
To set custom metadata for
an instance or project, you can use the Google Cloud Console,
the gcloud
command-line tool, or the Compute Engine API. You can set
these attributes at the instance or project level.
Console
You can apply the metadata values on your projects or instances using one of the following options:
Set enable-guest-attributes
and enable-os-inventory
in instance metadata when you create an instance:
- In the Google Cloud Console, go to the VM Instances page.
- Click Create instance.
- On the Create a new instance page, fill in the desired properties for your instance.
In the Metadata section, add the following metadata entries:
enable-guest-attributes
and the value isTRUE
.enable-os-inventory
and the value isTRUE
.
Click Create to create the instance.
Set enable-guest-attributes
and enable-os-inventory
in project-wide metadata so that it applies to all of the instances in your project:
- Go to the Metadata page.
- Click Edit.
Add the following metadata entries:
enable-guest-attributes
and the value isTRUE
.enable-os-inventory
and the value isTRUE
.
Click Save to apply the changes.
Set enable-guest-attributes
and enable-os-inventory
in metadata of an existing instance:
- Go to the VM instances page.
- Click the name of the instance on which you want to set the metadata value.
- At the top of the instance details page, click Edit to edit the instance settings.
Under Custom metadata, add the following metadata entries:
enable-guest-attributes
and the value isTRUE
.enable-os-inventory
and the value isTRUE
.
At the bottom of the instance details page, click Save to apply your changes to the instance.
gcloud
Use the
project-info add-metadata
gcloud
command to enable guest attributes and OS Inventory metadata keys.
You can apply the enable-guest-attributes
and enable-os-inventory
metadata values on your projects or instances using one of the following
options:
Set enable-guest-attributes
and enable-os-inventory
in project-wide
metadata so that it applies to all of the instances in your project.
Replace project-id
with your project ID.
gcloud compute project-info add-metadata \ --project project-id \ --metadata=enable-guest-attributes=true,enable-os-inventory=true
Set enable-guest-attributes
and enable-os-inventory
in metadata of an existing instance.
Replace VM-NAME
with the name of your instance.
gcloud compute instances add-metadata VM-NAME \ --metadata=enable-guest-attributes=true,enable-os-inventory=true
Set enable-guest-attributes
and enable-os-inventory
in instance metadata when you create an instance.
Replace VM-NAME
with the name of your instance.
gcloud compute instances create VM-NAME \ --metadata=enable-guest-attributes=true,enable-os-inventory=true
API
- For instructions on setting project-wide metadata, follow the API instructions for Setting project-wide custom metadata.
- For instructions on setting instance metadata, follow the API instructions for Setting instance metadata.
The following key-value pairs are required as your metadata values:
- Guest attributes:
- Key:
enable-guest-attributes
- Value:
True
- Key:
- OS inventory management:
- Key:
enable-os-inventory
- Value:
True
- Key:
Viewing operating system details
Before you can view operating system details, make sure that you configure your VMs to use OS inventory management.
Viewing inventory data
To view the inventory data for your instance, use the
instances os-inventory describe
command. Replace VM-NAME
with the name of your instance.
To view the inventory data collected for a VM, run the following command:
gcloud compute instances os-inventory describe VM-NAME
To view the types of output details that is returned, review Information provided by OS inventory management.
Listing VMs
To view the list of VMs that have OS inventory management set up, run the instances os-inventory list-instances command.
For example, to list all the VMs that have inventory data, run the following command:
gcloud compute instances os-inventory list-instances
Your output should resemble the following:
NAME ZONE MACHINE_TYPE PREEMPTIBLE INTERNAL_IP EXTERNAL_IP STATUS inventory-instance us-east1-b e2-standard-2 192.0.2.1 RUNNING instance-inventory1 us-west1-b e2-standard-2 192.0.2.2 RUNNING instance-inventory2 asia-east2-b e2-standard-2 192.0.2.3 RUNNING
You can also use filters to narrow down your results. For example, you can list
all VMs that have OS inventory management set up and whose hostname matches
the regex instance-*
by running the following command:
gcloud compute instances os-inventory list-instances --inventory-filter="Hostname~instance-*"
Your output should resemble the following:
NAME ZONE MACHINE_TYPE PREEMPTIBLE INTERNAL_IP EXTERNAL_IP STATUS instance-inventory1 us-west1-b e2-standard-2 192.0.2.2 RUNNING instance-inventory2 asia-east2-b e2-standard-2 192.0.2.3 RUNNING
What's next
- Learn more about OS inventory management.