Guest environment

Linux Windows

This document provides an overview of the guest environment, which contains scripts, daemons, and binaries that instances need to run on Compute Engine.

The guest environment communicates with the metadata server, which is a per-instance HTTP server that runs alongside every Compute Engine instance. The metadata server provides the instance with essential configuration and operational data. For more information about the types of metadata that's stored on the metadata server, see VM metadata .

The guest environment is automatically installed on Compute Engine instances that are created by using most of the Google-provided public operating system (OS) images. Each OS image requires specific guest environment packages. These packages are built either by Google or the operating system distributor. For a full list of OS images that include the guest environment, see Operating system details .

Guest environment components

The following section describes the packages and services that enable an instance to communicate with Compute Engine.

The guest agent

The central component of the guest environment is the guest agent, which handles tasks like account management, OS Login integration, and network interface management. The guest agent is available for both Linux and Windows operating systems, with the following package names:

Linux: google-guest-agent
Windows: google-compute-engine-windows

For detailed information about the guest agent, including its features, architecture, and how to manage the agent, see Guest agent .

Linux components

The base components of a Linux guest environment are deb or rpm packages. Compute Engine creates these packages with the appropriate configurations for the supported distribution. To see the list of installed packages on your Linux instance, connect to the instance, and run the command provided for your OS version in the Installed packages by operating system version table.

The Linux guest environment includes the following key packages.

Package name

Description

Key interactions

Link to source code on GitHub

google-guest-agent

This package is the guest agent for the Linux environment.

The Linux guest agent contains the scripts that run on the guest OS to support Compute Engine features. For detailed information about the guest agent, including its features, architecture, and how to manage the agent, see Guest agent .

Reads data from and writes data to the VM metadata
Sends logs to the serial port and optionally Cloud Logging

guest-agent

google-compute-engine

Contains the scripts and files required for system initialization and configuration.

This package contains the following:

System init scripts for systemd
System configurations, such as udev rules, sysctl rules, rsyslog configs, and dhcp configs, that are used for hostname setting
Bash scripts that run during instance boot
A gce-resolved.conf file, introduced in October 2024, that ensures that domain lookups for .local Cloud DNS domains route to the metadata server. Without this file, domain lookups route through systemd-resolved , which frequently fails.
If your environment doesn't use .local domains, you can remove the gce-resolved.conf file if it conflicts with your existing configurations.

Works with the following packages to configure instances.

google-guest-agent
google-compute-engine-oslogin

guest-configs

google-compute-engine-oslogin

Contains the necessary binaries, modules, and scripts to manage instance access using OS Login. OS Login lets you manage access to instances by using IAM roles. For more information about OS Login, see OS Login .

This package contains the following:

Authorized Keys Command : a command that uses the public SSH keys to authenticate users at login.
Name Service Switch (NSS) Modules : a service that provides the OS Login user and group information to the system.
Pluggable Authentication Modules (PAM) : a module that provides authorization (and authentication if two-factor support is enabled) support. This module lets the system use Google Cloud IAM permissions to control whether the system can log into an instance or perform operations as root (with sudo ).
google_oslogin_nss_cache : a utility for updating the local user and group cache.
selinux : a package that contains SELinux policy definition files and a compiled policy package for configuring SELinux to support OS Login.

Reads data from and writes data to the VM metadata
Send logs to the serial port and optionally Cloud Logging

guest-oslogin

gce-disk-expand

Contains the components required for resizing a boot disk.

Sends logs to the serial port

gce-disk-expand

google-osconfig-agent

Contains the OS Config agent, which VM Manager uses to manage OS inventory, patches, and policies. For more information about the OS Config agent, see VM Manager .

Reads data from and writes data to the VM metadata

By default, the OS Config agent doesn't collect or send any information until you enable the OS Config agent . After you enable the agent, the agent communicates with the OS Config API service. To review the operations completed by the agent, see VM Manager audit logging .

guest-osconfig

Windows components

All Google-provided Windows OS images are preconfigured with the GooGet tool and Google Cloud repositories. GooGet installs and maintains the guest environment for Windows instances. If you need to install GooGet and set up repositories, see Packaging and package distribution in the compute-image-windows GitHub repository. To see the list of installed packages on your Windows instance, connect to the instance and run googet installed .

The Windows guest environment includes the following key packages:

Package name

Description

Key interactions

Link to source code on GitHub

google-compute-engine-windows

This package is the guest agent for the Windows environment.

The Windows guest agent contains the scripts that run on the guest OS to support Compute Engine features. For detailed information about the guest agent, including its features, architecture, and how to manage the agent, see Guest agent .

Reads data from and writes data to the VM metadata
Sends logs to the Windows Application Event Log, serial port, and Cloud Logging

guest-agent

google-compute-engine-sysprep

Contains scripts for generalizing a Windows instance in preparation for creating an OS image. The package also includes the instance_setup.ps1 script that runs on first boot to configure the new instance.

Reads data from and writes data to the VM metadata
Sends logs to the Windows Application Event Log and serial port

sysprep

google-compute-engine-metadata-scripts

Contains scripts and binaries that run sysprep-specialize , startup , and shutdown scripts.

Reads data from and writes data to the VM metadata
Reads data from Cloud Storage locations when the sysprep-specialize-script-url and windows-startup-script-url are used
Sends logs to the Windows Application Event Log, serial port, and Cloud Logging

google_metadata_script_runner

google-compute-engine-powershell

Contains a PowerShell module. This module provides common functions that PowerShell scripts in the other Windows guest environment scripts use.

Sends logs to the Windows Application Event Log and the serial port

PowerShell

google-compute-engine-auto-updater

Contains scripts that update the Compute Engine packages daily.

This package isn't installed by default. This approach lets you maintain the stability of your environment by controlling the update process. If your environment can tolerate updates without disruption, you can install this package to ensure your guest environment packages are updated automatically.

To install this package, use the following command: googet -noconfirm install google-compute-engine-auto-updater

Reads data from VM metadata
Calls the GooGet agent to send logs to the Windows Application Event Log and console

auto_updater

google-compute-engine-diagnostics

Contains a binary that collects diagnostic information from the instance and saves the information to a Cloud Storage bucket. The Windows guest agent executes the binary.

Saves data to a Cloud Storage bucket

diagnostics

certgen

Contains a binary that creates a certificate on the instance.

certgen

GooGet

Contains a binary that installs and maintains the guest environment for Windows instances.

Reads data from the Google Cloud repositories located at packages.cloud.google.com

GooGet

google-compute-engine-vss

Installs the Compute Engine VSS agent and provider that takes persistent disk snapshots using Microsoft's Volume Shadow Copy Service (VSS)

Communicates with the Google Cloud snapshot service

vss

google-osconfig-agent

Contains the OS Config agent, which VM Manager uses to manage OS inventory, patches, and policies. For more information about the OS Config agent, see VM Manager .

Reads data from and writes data to the VM metadata

By default the OS Config agent doesn't collect or send any information until you enable the OS Config agent . After you enable the agent, the agent communicates with the OS Config API service. To review the operations the agent completes, see VM Manager audit logging .

guest-osconfig

Compute Engine Windows drivers

Contains several drivers to ensure proper functionality and performance of instances. The GooGet package manager manages these drivers and publishes them to Google Cloud repositories.

The following Compute Engine drivers are maintained for Windows OS images:

Driver type	Driver package name
Ethernet adapter	`google-compute-engine-driver-netkvm`
SCSI disk	`google-compute-engine-driver-vioscsi`
Display adapter	`google-compute-engine-driver-gga`
Crash handler	`google-compute-engine-driver-pvpanic`
Virtio memory balloon driver	`google-compute-engine-driver-balloon`
Google virtual NIC	`google-compute-engine-driver-gvnic`

To install or upgrade a specific driver, run the following command:

googet install DRIVER_PACKAGE_NAME

compute-windows-drivers

What's next

Learn how to Install the guest environment .
Learn about the guest agent .