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.

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.

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

  • Monitoring and logging: enable the Ops Agent plugin to collect metricsand logs for Cloud Monitoring.
  • Workload management: enable the Workload Manager plugin togather configuration and runtime information from your workloads foranalysis.
  • Workload optimization: enable the SAP Agent plugin to support your SAPworkloads running on Google Cloud.

  You can enable or disable optional plugins as needed.

• Agent control plane: this managed Google Cloud service runs onGoogle's backend infrastructure. The control plane manages the lifecycle ofoptional plugins, 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 the agent control plane.Lifecycle management for the optional plugins includes the following:

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

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 optional plugins that are notneeded, which lets you secure or optimize your instance.
• Reduced overhead for optional plugins: the guest agent managerautomatically handles the installation and updates of optional plugins,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:

Backward compatibility

To ensure a smooth transition from the previous, monolithic guest agent to theplugin-based system, the guest agent package includes several componentsdesigned for backward compatibility. These components are not part of theplugin-based architecture and activate only if you manually choose to revert tothe monolithic agent by setting the metadata attributeenable-guest-agent-core-plugin tofalse.

The components that support this compatibility include the following:

• Guest agent compatibility manager: this package manages the switch betweenthe plugin-based agent and the monolithic agent.
• Metadata script runner compatibility manager: this package ensures that thecorrect script runner is used, depending on whether the monolithic orplugin-based agent is active.
• Authorized keys compatibility manager (Windows only): this package handlesSSH keys, ensuring that the correct keys are used for either the old or newagent.

What's next

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