Guest environment

When you start a virtual machine (VM) instance using Google-provided public images, a guest environment is automatically installed on the VM instance. The guest environment is a set of scripts, daemons, and binaries that read the content of the metadata server to make a VM run properly on Compute Engine. A metadata server is a communication channel for transferring information from a client to the guest operating system.

This document provides an overview of the components of the guest environment, supported operating systems, and explains how to learn when you need to manually install or update the guest environment.

When to manually install or update the guest environment

VM instances created using Google-provided public images include a guest environment that is installed by default.

To check if the guest environment is running on your instance, see validate the guest environment.

In some cases, the installed guest environment can become outdated. If the guest environment is available on your instance but is outdated, update the guest environment.

Otherwise, you might need to manually install the guest environment under the following conditions:

  • You are importing a custom image or a virtual disk to the Compute Engine platform and choosing not to allow an automatic installation of the guest environment.

    When you import virtual disks or custom images, you have the option of letting Compute Engine install the guest environment for you. However, if you choose not to install the guest environment during the import process, then, to install the guest environment, you must follow the manual steps.

  • You are migrating VMs to Compute Engine using Migrate to Virtual Machines.

  • You are using an image that doesn't have the guest environment optimizations for Local SSD disks.

  • You have instances that are using an image that is earlier than v20141218.

If you need to manually install the guest environment, see Installing the guest environment.

Supported operating systems

Each supported operating system that is available on Compute Engine requires specific guest environment packages. Either Google or the owner of the operating system builds these packages. For information about who builds the guest environment packages, see the Notable differences from standard images sections in the Operating system details document.

The Linux guest environment

Whether the Linux guest environment is built by Google or the owner of the operating system, there are some key components that are applicable to all builds.

The base components of a Linux guest environment are provided as deb or rpm packages that are created with the appropriate configurations for the supported distributions.

The following list summarizes the main scripts, daemons, and packages that are packaged in the Linux guest environment:

  • The google-compute-engine package contains the following components:

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

    This package depends on the google-guest-agent and google-compute-engine-oslogin packages.

    To review the source code for this package, see guest-configs on GitHub.

  • The google-guest-agent package contains the guest agent and metadata script executables which runs on the guest OS to support the Compute Engine features. The following features are supported by the Linux guest agent:

    The Linux guest agent communicates with Compute Engine services as follows:

    The Linux guest agent also collects telemetry data from the guest OS to use for analysis and debugging. The telemetry data includes: OS name, OS version, OS kernel release, OS kernel version, and OS agent version. To disable the collection of the telemetry data, set the following metadata at either the VM or project level: disable-guest-telemetry=TRUE.

    As of December 2024, the guest agent installs a secondary systemd unit named google-guest-agent-manager. This unit manages on demand plugins lifecycle.

    To review the source code for this package, see guest-agent on GitHub.

  • The google-compute-engine-oslogin package contains the binaries, modules, and scripts for OS Login. You can use OS Login to manage access to VM instances using Identity and Access Management (IAM) roles.

    The package includes the following:

    • Authorized Keys Command which provides SSH keys from the user's OS Login profile to sshd for authenticating users at login.
    • Name Service Switch (NSS) Modules which provide support for making OS Login user and group information available to the system.
    • Pluggable Authentication Modules (PAM) which provide authorization (and authentication if two-factor support is enabled) support allowing the system to use Google Cloud IAM permissions to control the ability to log into an instance or to perform operations as root (via sudo).
    • google_oslogin_nss_cache which is a utility for updating the local user and group cache.
    • selinux contains SELinux policy definition files and a compiled policy package for configuring SELinux to support OS Login.

    The OS Login components communicate with Compute Engine services as follows:

    To review the source code for this package, see guest-oslogin on GitHub.

  • The gce-disk-expand components communicate with Compute Engine services as follows:

    • Sends logs to the serial port

    To review the source code for this package, see guest-diskexpand on GitHub.

  • The google-osconfig-agent package contains OS Config agent that VM Manager uses to manage OS inventory, patches, and OS policies.

    The scripts communicate with Compute Engine services as follows:

    To review the source code for this agent, see osconfig on GitHub.

The Windows guest environment

The following list summarizes the packages that are a part of the Windows guest environment:

  • The google-compute-engine-windows package contains the Windows guest agent. The Windows guest agent is used to support the following processes:

    The Windows guest agent communicates with Compute Engine services as follows: + Reads data from and writes data to the VM metadata + Sends logs to the Windows Application Event Log, serial port, and Cloud Logging

    The Windows guest agent also collects telemetry data from the guest OS to use for analysis and debugging. The telemetry data includes: OS name, OS version, OS kernel release, OS kernel version, and OS agent version. To disable the collection of the telemetry data, set the following metadata at either the VM or project level: disable-guest-telemetry=TRUE.

    As of December 2024, the guest agent installs a secondary system service named GCEAgentManager. This service manages on demand plugins lifecycle.

    To review the source code for this agent, see guest-agent on GitHub.

  • The google-compute-engine-sysprep package contains scripts that are for generalizing a Windows instance in preparation for creating an image. The package also includes the instance_setup.ps1 script which is used on first boot to configure the new instance.

    The scripts communicate with Compute Engine services as follows:

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

    To review the source code for this agent, see compute-image-windows on GitHub

  • The google-compute-engine-metadata-scripts package contains scripts and binaries that are used for running the Compute Engine, sysprep-specialize, startup and shutdown scripts.

    The scripts communicate with Compute Engine services as follows:

    • Reads data from and writes data to the VM metadata
    • Reads 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

    To review the source code for this agent, see compute-image-windows on GitHub

  • The google-compute-engine-powershell package contains a PowerShell module. This module contains common functions that are used by PowerShell scripts in the other Windows Guest Environment scripts.

    The scripts communicates with the following Compute Engine services:

    • The logging function in the PowerShell module by default sends logs to the Windows Application Event Log and serial port.

    To review the source code for this agent, see compute-image-windows on GitHub.

  • The google-compute-engine-auto-updater package contains scripts that are used for updating the Compute Engine packages daily. This package is no longer installed by default.

    The scripts communicate with Compute Engine services as follows:

    • Reads data from VM metadata
    • Calls the Googet agent to sends logs to the Windows Application Event Log and console

    To review the source code for this agent, see compute-image-windows on GitHub.

  • The google-compute-engine-diagnostics package contains a binary that is used for obtaining diagnostic information from the instance and saves the information to a Cloud Storage bucket. The binary is executed by the Windows guest agent.

    The scripts communicate with Compute Engine services as follows:

    • Saves data to a Cloud Storage bucket

    To review the source code for this agent, see compute-image-tools on GitHub

  • The certgen package contains a binary that creates a certificate on the instance.

    To review the source code for this agent, see compute-image-windows on GitHub.

  • The googet package contains a binary that is a package manager used to install and maintain the guest environment.

    The scripts communicate with Compute Engine services by reading data from the Google Cloud repositories at packages.cloud.google.com.

    To review the source code for this agent, see googet on GitHub.

  • The google-compute-engine-vss package installs the Compute Engine VSS agent and provider that are used for taking a persistent disk snapshot using the Microsoft's Volume Shadow Copy Service (VSS).

    The scripts communicate with Compute Engine services as follows:

    • Communicates with the Google Cloud snapshot service

    To review the source code for this agent, see compute-image-windows on GitHub

  • The google-osconfig-agent package contains OS Config agent which is used by VM Manager for managing OS inventory, patches, and OS policies.

    The scripts communicate with Compute Engine services as follows:

    To review the source code for this agent, see osconfig on GitHub.

Compute Engine Windows drivers

The following Compute Engine drivers are maintained for Windows images:

Driver type 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

Each driver is packaged using GooGet and published to Google Cloud repositories. Source code for the drivers is at compute-windows-drivers on GitHub. All Google Cloud Windows images are preconfigured with the GooGet tool and Google Cloud repositories. If you need to install GooGet and set up repositories yourself, see Packaging and package distribution.

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

googet install DRIVER_PACKAGE_NAME

What's next

For step-by-step instructions about installing the guest environment, see Installing the guest environment.