This document provides an overview of the guest agent architecture. The guestagent is a critical component of the guest environment. The guest environmentcontains scripts, daemons, and binaries that instances need to run on Compute Engine.For more information, seeGuest environment.

The guest agent sets up services and defines minimum configurations forfeatures such as snapshot script execution, Windows failover, OS login, andmetadata-based SSH authentication. For more information about core functions ofthe guest agent, seeGuest agent functionality.

Guest agent architecture

Starting with version20250901.00, the guest agent architecture isupdated from a monolithic design to a modern, plugin-based system. Thisevolution improves flexibility, reliability, and extensibility.

• Monolithic architecture: guest agents earlier than20250901.00feature a single, unified process centered around the metadata server'sdescription of instances. The metadata server is a per-instance HTTP serverthat runs alongside every Compute Engine instance. For moreinformation about the metadata server, seeVM metadata.

  The guest agent long polls the metadata server and takes actionbased on state changes. With this architecture, the agent's state is sharedacross all tasks such as SSH and network setup.This monolithic approach lacked interface and component isolation. Changesor feature introductions in one area of the agent affect the entire systemsimultaneously. This pattern makes feature additions and testing coveragechallenging.

• Plugin-based architecture: starting with version20250901.00, theguest agent is divided into distinct, independent plugins managed by acentral manager. Each plugin can interact with the metadata server and, asdirected by a central manager, makes changes as needed. Thismodular approach ensures that a crash in one plugin does not affect the coreagent or other plugins.

The plugin-based architecture

This architecture is built around a central manager that controls variousplugins, separating core functionalities from optional, service-specificplugins, referred to as extensions.

Key components

The following diagram shows the key components of the guest agent and theirinteractions.

• Core plugin: this plugin encapsulates the functionality of the originalguest agent. It performs the essential tasks that your instance needs to runon Google Cloud. These include tasks such as the following:

  • Network configuration: sets up the primary network interface to enablecommunication.
  • SSH access: manages user SSH keys to allow secure connections to yourinstance.
  • Metadata access: provides a pathway for the instance to access instanceand project metadata.

  You can't disable the core plugin.

  For more information about core functions of the guest agent, seeGuest agent functionality.

• Extensions (Optional plugins): you can provision these extensions to integrate with otherGoogle Cloud services to perform tasks such as:

  • Monitoring and logging: enable the Ops Agent to collect metricsand logs for Cloud Monitoring. For more information, seeInstall and manage the Ops Agent by using VM Extension Manager policies.
  • Workload management: enable the Agent for Compute Workloads togather configuration and runtime information from your workloads foranalysis. For more information, seeAgent for Compute Workloads overview.
  • Workload optimization: enable Agent for SAP to support your SAPworkloads running on Google Cloud. For more information, seeInstall and manage Agent for SAP on a fleet of VMs.

  For more information about installing and managing these extensions, seeVM Extension Manager.

• VM Extension Manager: this managed Google Cloud service runs onGoogle's backend infrastructure. VM Extension Manager manages the lifecycle ofextensions, including their installation, updates, and configuration,by communicating with the guest agent manager on the instance.

• Guest agent manager: this central process starts, stops, andmonitors the status of all plugins. The guest agent manager facilitatescommunication between the core plugin and VM Extension Manager.Lifecycle management for extensions includes the following:

  • Installation and updates: the guest agent manager installs, starts,stops, and configures extensions based on instructions fromVM Extension Manager.
  • Health monitoring: the guest agent manager monitors the health andstatus of extensions, including their CPU and memory usage, andreports this information back to VM Extension Manager.
  • Policy management: use Compute Engine APIs to create policies thatcontrol the installation and versioning of extensions.

Benefits

The plugin-based architecture offers several advantages over the monolithicdesign. These benefits include the following:

• Plugin isolation: each plugin runs in a separate process, so a crash inone doesn't affect the core agent or other plugins.
• Resource protection: the guest agent uses OS-level features to enforceresource limits on plugins, preventing any single plugin from consumingexcessive CPU or memory.
• Automatic crash recovery: the system automatically recovers from aplugin crash by stopping and relaunching the plugin.
• Selective enablement: you can disable extensions that are notneeded, which lets you secure or optimize your instance.
• Reduced overhead for extensions: the guest agent managerautomatically handles the installation and updates of extensions,reducing the manual effort required to keep them up-to-date.

Location of guest agent binaries

The following tables list the file paths for the different guest agent binarieson Linux and Windows instances, depending on the architecture.

Plugin-based agent binaries

This table lists the file paths for the plugin-based guest agent binaries onLinux and Windows instances:

Monolithic agent binaries

The following table lists the file paths for the monolithic guest agentbinaries on Linux and Windows instances:

Guest agent daemon services

The following tables list the guest agent daemon services installed on Linux andWindows instances. These services run assystemd units on Linux and as Windowsservices on Windows.

• For more information about core plugin functions, seeGuest agent functionality