On Compute Engine you can manage the operating systems that are running on your virtual machines (VMs) by using VM Manager.
To review the steps needed to set up your VMs to use VM Manager, see Setup overview.
After setting up VM Manager, you can view audit logs for API operations performed with the OS Config API, see Viewing VM Manager audit logs.
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.
Setup overview
To set up VM Manager, complete the following steps:
On your Google Cloud project, enable the OS Config API.
Enable the OS Config agent by setting project or instance metadata. You can either set instance metadata on each VM or project metadata that applies to all VMs in your project.
If your VM is running within a private VPC network and does not have public internet access, enable Private Google Access.
On each VM, check that you have an enabled service account. A service account is enabled by default for VMs created using the
gcloud
command-line tool or the Google Cloud Console. You do not need to grant any IAM roles to this service account.On each VM, check if the OS Config agent is installed.
On each VM, if the agent is not already installed, install the OS Config agent.
Optional. On either your project or on each VM, disable the features that you don't need.
Supported operating systems
For the full list of operating systems and versions that support VM Manager, see Operating system details.
Enabling the OS Config service API
In your Cloud project, enable the OS Config API. To enable the API run the following command:
gcloud services enable osconfig.googleapis.com
Setting the metadata values
On your Cloud project or VM, set the enable-osconfig
metadata value
to TRUE
. Setting the enable-osconfig
metadata value to TRUE
enables the
following:
- OS patch management
- OS configuration management
- OS inventory management. For OS inventory management to work, you must also
set the
enable-guest-attributes
metadata value toTRUE
.
Console
You can apply the metadata values on your Cloud projects or VMs using one of the following options:
Option 1: Set
enable-osconfig
in project-wide metadata, so that it applies to all of the VMs in your project.In the Google Cloud Console, go to the Metadata page.
Click Edit.
Add the following metadata entry:
Key:
enable-osconfig
Value:TRUE
For OS inventory management to work, you need to set both
enable-osconfig
andenable-guest-attributes
:- Key:
enable-osconfig
Value:TRUE
- Key:
enable-guest-attributes
Value:TRUE
- Key:
Click Save to apply the changes.
Option 2: Set
enable-osconfig
in VM metadata when you create an instance.In the Google Cloud Console, go to the VM instances page.
Click Create.
On the Create an instance page, set the properties you want for your VM.
Expand Management, security, disks, networking, sole tenancy.
In the Metadata section, add the following metadata entries:
Key:
enable-osconfig
Value:TRUE
.For OS inventory management to work, you need to set both
enable-osconfig
andenable-guest-attributes
:- Key:
enable-osconfig
Value:TRUE
- Key:
enable-guest-attributes
Value:TRUE
- Key:
Click Create to create the instance.
Option 3: Set
enable-osconfig
in metadata of an existing VM.In the Google Cloud Console, go to the VM instances page.
Click the name of the VM for which you want to set the metadata value.
On the Instance details page, click Edit to edit the settings.
Under Custom metadata, add the following metadata entries:
Key:
enable-osconfig
Value:TRUE
.For OS inventory management to work, you need to set both
enable-osconfig
andenable-guest-attributes
:- Key:
enable-osconfig
Value:TRUE
- Key:
enable-guest-attributes
Value:TRUE
- Key:
Click Save to apply your changes to the VM.
gcloud
Use the
project-info add-metadata
or the
instances add-metadata
gcloud
command
with the --metadata=enable-osconfig=TRUE
flag.
You can apply the metadata values on your projects or VMs using one of the following options:
Option 1: Set
enable-osconfig
in project-wide metadata, so that it applies to all of the instances in your project:gcloud compute project-info add-metadata \ --project PROJECT_ID \ --metadata=enable-osconfig=TRUE
For OS inventory management to work, you need to set both
enable-osconfig
andenable-guest-attributes
:gcloud compute project-info add-metadata \ --project PROJECT_ID \ --metadata=enable-guest-attributes=TRUE,enable-osconfig=TRUE
Replace
PROJECT_ID
with your project ID.Option 2: Set
enable-osconfig
in metadata of an existing instance.gcloud compute instances add-metadata VM_NAME \ --metadata=enable-osconfig=TRUE
For OS inventory management to work, you need to set both
enable-osconfig
andenable-guest-attributes
:gcloud compute instances add-metadata VM_NAME \ --metadata=enable-guest-attributes=TRUE,enable-osconfig=TRUE
Replace
VM_NAME
with the name of your VM.Option 3: Set
enable-osconfig
in instance metadata when you create an instance.gcloud compute instances create VM_NAME \ --metadata=enable-osconfig=TRUE
For OS inventory management to work, you need to set both
enable-osconfig
andenable-guest-attributes
:gcloud compute instances create VM_NAME \ --metadata=enable-guest-attributes=TRUE,enable-osconfig=TRUE
Replace
VM_NAME
with the name of your VM.
API
You can set the metadata value at either the Cloud project or instance level.
- 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 pair is required as part of the metadata property:
- Key:
enable-osconfig
Value:TRUE
For OS inventory management, also add the following key-value pair:
- Key:
enable-guest-attributes
Value:TRUE
Checking if the OS Config agent is installed
The OS Config agent is installed by default on Red Hat Enterprise Linux (RHEL),
Debian, CentOS, and Windows images that have a build date of v20200114
or later.
Linux
To check whether your Linux VM has the agent installed, run the following command:
sudo systemctl status google-osconfig-agent
If the agent is installed and running, the output resembles the following:
google-osconfig-agent.service - Google OSConfig Agent Loaded: loaded (/lib/systemd/system/google-osconfig-agent.service; enabled; vendor preset: Active: active (running) since Wed 2020-01-15 00:14:22 UTC; 6min ago Main PID: 369 (google_osconfig) Tasks: 8 (limit: 4374) Memory: 102.7M CGroup: /system.slice/google-osconfig-agent.service └─369 /usr/bin/google_osconfig_agent
If the agent is not installed, install the OS Config agent.
Windows
To check whether your Windows VM has the agent installed, run the following command:
PowerShell Get-Service google_osconfig_agent
If the agent is installed and running, the output resembles the following:
Status Name DisplayName ------ ---- ----------- Running google_osconfig... Google OSConfig Agent
If the agent is not installed, install the OS Config agent.
Installing the OS Config agent
Before you follow these steps to install the agent, check if the agent is already running on your VM.
On each VM, install the OS Config agent. You can install the OS Config agent by using one of the following options:
- Install the agent manually using the terminal.
- Use a startup script on your VMs.
- Automate the installation of OS Config on multiple VMs by using a Google Cloud's operations suite agent policy.
Installing the agent manually
Use this option to install the OS Config agent on an existing VM.
To install the agent, complete the following steps:
Connect to the VM that you want to install the OS Config agent on.
Install the OS Config agent.
Windows Server
To install the OS Config agent on a Windows server, run the following command:
googet -noconfirm install google-osconfig-agent
Ubuntu
To install the OS Config agent on an Ubuntu VM, run the following commands:
Set up the Ubuntu repository.
For Ubuntu 16.04, run the following commands:
Add the Ubuntu repository.
sudo su -c "echo 'deb http://packages.cloud.google.com/apt google-compute-engine-xenial-stable main'> \ /etc/apt/sources.list.d/google-compute-engine.list"
Import the Google Cloud public key.
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | \ sudo apt-key add -
For Ubuntu 18.04 and later versions, run the following commands:
Add the Ubuntu repository.
sudo su -c "echo 'deb http://packages.cloud.google.com/apt google-compute-engine-bionic-stable main' > \ /etc/apt/sources.list.d/google-compute-engine.list"
Import the Google Cloud public key.
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | \ sudo apt-key add -
Install the OS Config agent.
sudo apt update sudo apt -y install google-osconfig-agent
Debian
To install the OS Config agent on a Debian VM, run the following commands:
sudo apt update sudo apt -y install google-osconfig-agent
Adding the Google Cloud repository and public key
If you are using a VM instance that was not created from a Google-provided image or got a "unable to locate package" error message, complete the following steps to add the Google Cloud repository and import the public key.
After you add the repository and import the key, you can then run the commands to install the OS Config agent.
For Debian 9 (Stretch), run the following commands:
Add the Debian repository.
sudo su -c "echo 'deb http://packages.cloud.google.com/apt \ google-compute-engine-stretch-stable main'> /etc/apt/sources.list.d/google-compute-engine.list"
Import the Google Cloud public key.
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | \ sudo apt-key add -
For Debian 10 (Buster), run the following commands:
Add the Debian repository.
sudo su -c "echo 'deb http://packages.cloud.google.com/apt \ google-compute-engine-buster-stable main'> /etc/apt/sources.list.d/google-compute-engine.list"
Import the Google Cloud public key.
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | \ sudo apt-key add -
RHEL/CentOS
To install the OS Config agent on a RHEL 7/8 or CentOS 7/8 VM, run the following command:
sudo yum -y install google-osconfig-agent
SLES/openSUSE
To install the OS Config agent on a SLES or openSUSE VM, run the following commands:
Set up the SLES repository.
For SLES 12, run the following command:
sudo su -c "cat > /etc/zypp/repos.d/google-compute-engine.repo <<EOM [google-compute-engine] name=Google Compute Engine baseurl=https://packages.cloud.google.com/yum/repos/google-compute-engine-sles12-stable enabled=1 gpgcheck=1 repo_gpgcheck=1 gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg EOM"
For SLES 15 and OpenSUSE 15, run the following command:
sudo su -c "cat > /etc/zypp/repos.d/google-compute-engine.repo <<EOM [google-compute-engine] name=Google Compute Engine baseurl=https://packages.cloud.google.com/yum/repos/google-compute-engine-sles15-stable enabled=1 gpgcheck=1 repo_gpgcheck=1 gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg EOM"
Import the GPG keys for Google Cloud.
sudo rpm --import https://packages.cloud.google.com/yum/doc/yum-key.gpg \ --import https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
Install the OS Config agent.
sudo zypper -n --gpg-auto-import-keys install google-osconfig-agent
Installing the agent using a startup script
You can also use the manual installation commands to create a startup script that installs the OS Config agent during VM creation.
- Copy the manual commands for your operating system.
Provide the startup script to your VM creation method.
For example, if you are using the
gcloud compute instances create
command to create a new Debian 9 VM, your command resembles the following:gcloud compute instances create VM_NAME \ --image-family=debian-9 --image-project=debian-cloud \ --metadata startup-script='#! /bin/bash sudo apt update sudo apt -y install google-osconfig-agent'
Replace
VM_NAME
with the name of your VM.Verify that the startup script completes. To verify whether the startup script completes, review the logs or check the serial console.
Disabling features that you don't need
For features that you might not need, you can disable them by
setting the following metadata values:
osconfig-disabled-features=FEATURE1,FEATURE2
.
Replace FEATURE1,FEATURE2
with any of
the following values:
- OS inventory management:
osinventory
- OS patch management:
tasks
- OS configuration management:
guestpolicies
You can set these values using either the Google Cloud Console,
the gcloud
command-line tool, or the Compute Engine API.
Console
You can disable the metadata values on your Cloud projects or VMs by using one of the following options:
Option 1: Disable feature in project-wide metadata so that it applies to all of the instances in your project.
In the Google Cloud Console, go to the Metadata page.
Click Edit.
Add the following metadata entry:
Key:
osconfig-disabled-features
Value:FEATURE1,FEATURE2
For example:
Key:osconfig-disabled-features
Value:osinventory,guestpolicies
Click Save to apply the changes.
Option 2: Disable feature in metadata of an existing VM.
In the Google Cloud Console, go to the VM instances page.
Click the name of the VM on which you want to set the metadata value.
On the Instance details page, click Edit to edit the VM settings.
Under Custom metadata, add the following metadata entries:
Key:
osconfig-disabled-features
Value:FEATURE1,FEATURE2
For example:
Key:osconfig-disabled-features
Value:osinventory
Click Save to apply your changes to the VM.
gcloud
Use the
project-info add-metadata
or the
instances add-metadata
gcloud
command
with the --metadata=osconfig-disabled-features
flag.
If you are disabling multiple features, the flag must have the format
--metadata=^:^osconfig-disabled-features=FEATURE1,FEATURE2
.
See example 2.
Examples
Example 1
To disable OS patch management at the Cloud project level using
the gcloud
command-line tool, run the following command:
gcloud compute project-info add-metadata \ --project PROJECT_ID \ --metadata=osconfig-disabled-features=tasks
Example 2
To disable OS configuration management and OS inventory management at
the project level using the gcloud
command-line tool, run the following command:
gcloud compute project-info add-metadata \ --project PROJECT_ID \ --metadata=^:^osconfig-disabled-features=osinventory,guestpolicies
Replace PROJECT_ID
with your project ID.
API
You can set the metadata value at either the Cloud project or instance level.
- 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 pair is required as part of the metadata property:
- Key:
osconfig-disabled-features
- Value: Can be any one or a combination of the following flags:
osinventory
tasks
guestpolicies
Updating the OS Config agent
To update the OS Config agent, you need to update the package for your operating system.
CentOS/RHEL
To update the agent on CentOS and RHEL operating systems, run the following command:
sudo yum update google-osconfig-agent
Debian/Ubuntu
To update the agent on Debian and Ubuntu operating systems, run the following commands:
sudo apt update sudo apt install google-osconfig-agent
SLES
To update the agent on SLES, run the following command:
sudo zypper -n update google-osconfig-agent
Windows
To update the agent on Windows operating systems, run the following command:
googet update google-osconfig-agent
Requirements for an active OS Config agent
For the OS Config agent to be considered active and billable, it must satisfy all of the following requirements:
- VM Manager must be set up.
The VM must be in
RUNNING
state and the OS Config agent must be communicating with the OS Config service.If a VM is stopped, suspended, or disconnected from the network, the agent on that VM is not counted as an active agent.
Verify the setup
After completing the setup procedure, you can verify the setup by using the verification checklist.
What's next?
- Create a guest policy.
- View operating system details.
- Create patch jobs.
- Learn more about the VM Manager.