Guest environment

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.

 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.
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