This document provides an overview of the core functionality of the guest agent,a critical component of the guest environment. The guest environment containsscripts, daemons, and binaries that instances need to run on Compute Engine.For more information, seeGuest environment.

How the guest agent works

Starting with version20250901.00, the guest agent uses aplugin-based architecture. This design improves reliability and flexibilityby separating the agent's functions into distinct components.

The guest agent architecture consists of a few key components:

• Guest agent manager: the central process on your instance that starts,stops, and monitors all plugins.
• Core plugin: this plugin handles the essential services your instanceneeds to run on Google Cloud. Its functionality cannot be disabled.
• Extensions (Optional plugins): these are plugins that integrate your instance withother Google Cloud services, such as Cloud Monitoring. You can controlwhich of these plugins run on your instance by usingVM Extension Manager.
• VM Extension Manager: this is a managed Google Cloud service that runs onGoogle's backend infrastructure and manages the lifecycle of optionalplugins, including their installation and updates.

For more information about the guest agent architecture, seeAbout guest agent.

Startup sequence and dependencies

The guest agent manager follows a specific startup sequence to ensure that theinstance is correctly set up to run on Compute Engine. Immediately after theprocess starts, the agent manager launches the core plugin, a specializedcomponent that handles foundational guest environment tasks.

Best practices for dependent processes

If you have custom services or scripts that depend on guest agent features, such as MDScredential bootstrapping, you must define an explicit startup dependency to ensurethey execute only after the agent is active.

[Unit]After=google-guest-agent-manager.service

sc config "CustomService" depend= "GCEAgentManager"

Core functionality

The core plugin is responsible for the fundamental services that yourinstance needs to function on Compute Engine. The following section detailsthe functions that the core plugin provides. You can customize many of thesefeatures by using theguest agent configuration file.

Initial instance setup and optimizations

The guest agent performs several setup tasks to prepare the instance for runningon Compute Engine. As shown in the following table, some tasks run only on the first boot, while others run on every startup.

You can control these setup tasks by configuring theInstanceSetup optionsof the guest agent configuration file. For example, you can disable Local SSDoptimization by settingoptimize_local_ssd = false.

System telemetry collection

The guest agent records some basic system telemetry information at boot time andthen once every 24 hours. The information recorded includes the following:

• Guest agent version and architecture
• Operating system name and version
• Operating system kernel release and version

You can disable telemetry collection by setting the metadata keydisable-guest-telemetrytotrue. To set metadata, seeSet and remove custom metadata.

Clock synchronization (Linux only)

To ensure accurate timekeeping, the guest agent uses theclock_skew_daemoncomponent to periodically correct the clock on your instance to match thephysical server it runs on. This process prevents a problem calledclock skewand generates asystem time has changed message in your instance logs, whichconfirms the time was successfully synchronized.

If enabled, the agent normally synchronizes the clock after a stop or startevent, or after a migration. However, if the real-time clock (RTC) on your instance isconfigured to use the local timezone instead of UTC, the agent automaticallydetects this configuration and disables clock synchronization to prevent potentialinconsistencies.

The agent performs the re-synchronization by running the following command:/sbin/hwclock --hctosys -u --noadjfile.

You can disable theclock_skew_daemon component by settingclock_skew_daemon = falsein the guest agent configuration file.

Metadata script execution

You can usestartup scripts andshutdown scripts to perform automatedtasks each time your instance starts or stops.

The guest agent helps with the running of these scripts as follows:

• Executes scripts in a shell.
• If you specify multiple scripts (for example, if using bothstartup-scriptandstartup-script-url), the agent runs both.
• When multiple scripts are provided for the same event, the agent executesthe script from the URL first.
• After a script finishes, the agent logs its exit status.

You can configure the execution of metadata scripts by modifying theMetadataScripts optionsin the guest agent configuration file.

User account and SSH key management

The guest agent uses anaccounts_daemonto manage local user accounts and SSH keys, which control access to the instance.The specific behavior varies between Linux and Windows operating systems.

You can modify accounts management options by configuring theAccounts optionsin the guest agent configuration file.

OS Login configuration (Linux only)

OS Login is used to manage SSH access to your instances usingIAM without having to create and manage individual SSH keys.For more information about OS Login, see theOS Logindocumentation.

When youenable OS Login,the guest agent is responsible for configuring the instance to use OS Login.

The guest agent configuresOS Login by completing thefollowing tasks:

• Adds a Google config block to theSSHD configuration file andrestartsSSHD.
• Adds OS Login entries to thensswitch.conf file.
• Adds OS Login entries to thePAM configuration file forSSHD.

If you disable OS Login, the configuration changes areremoved. The options under theAccounts section of theSSHDconfiguration file don't apply to OS Login users.

Network management

The guest agent automatically configures your instance's network interfaces on boot.It reads the network configuration from the metadata server to ensure yourinstance connects to the network correctly and can access other Google Cloudservices.

You can control the agent's network management behavior by configuring theNetworkInterfaces optionsin the guest agent configuration file. For example, you can setthemanage_primary_nic = true option to have the agent manage the primarynetwork interface card (NIC) in addition to secondary NICs.

On every boot, the guest agent performs the following key tasks:

• Enables network interfaces: the agent detects the activenetwork manager on your OS and uses it toenable all secondary network NICs.
• Configures IP routes: the agent sets up the necessary IP (IPv4 only) routesfor features like IP forwarding and alias IP ranges as follows:
  • Sets routes on the primary ethernet interface.
  • Configures Google routes by default, with the routingprotocol ID66. This ID is a namespace for guest agent configured IPaddresses. This ID can be changed by using theethernet_proto_idoption in the guest agent configuration file.
• Creates a route to the metadata server: the agent ensures that yourprimary NIC can always communicate with the metadata server to get instanceinformation.
• VLAN configuration: If your instance is configured to connect to aVirtual Local Area Network (VLAN),the guest agent automatically handles the setup. It reads the VLANconfiguration from the metadata server and configures the network interfaceinside the instance to use the correct VLAN tag. This ensures the instancecommunicates on the intended logical network. Importantly, if the VLAN isattached to the primary NIC, the guest agent configures it even ifmanage_primary_nic is disabled.

Network manager selection

On Linux, the guest agent automatically detects which network manager isavailable on the system and uses it to configure the network interfaces. Theagent checks for supported managers in order of priority, fromnetplan todhclient.

The following table lists the supported network managers, organized by theoperating system they are most commonly associated with by default. Yourspecific instance configuration can differ, but this table reflects the defaultnetwork manager for the listed operating systems.

Shielded VMs now support securecommunication with the metadata server by using the HTTPS endpointhttps://metadata.google.internal/computeMetadata/v1. Thisenhancement provides a more secure channel for metadata access.

To enable this secure communication, the guest agent retrieves and storesnecessary credentials on the instance's disk. These credentials are saved in astandard location, making them accessible to any client application running onthe instance. To review these locations, seeWhere are certificates stored.

The setup of HTTPS MDS certificates is disabled by default. To have yourShielded VMs automatically set up the HTTPS MDS certificates, set thedisable-https-mds-setup metadata key tofalse on your instance or project.To set metadata, seeSet and remove custom metadata.

Credential management by the guest agent includes:

• Initial update: both the root certificate and client credentials areupdated whenever the guest agent process starts.
• Automatic refresh: for enhanced security, the guest agent automaticallyrefreshes client credentials every 48 hours.
• Overlap period: the agent generates and saves new credentials while theold ones remain valid. The overlap period ensures clients have sufficienttime to transition to the new credentials before the old ones expire. Thisoverlap period also allows the agent to retry credential acquisitionin case of failure, ensuring valid credentials are in place before existingones become invalid.
• Composition: the guest agent ensures the client credentials consist of anEC (Elliptic Curve) private key concatenated with the client certificate.
• Uniqueness: the guest agent ensures credentials are unique to an instanceand can't be used elsewhere.

For more information on HTTPS metadata server endpoint, seeAbout the HTTPS metadata server endpoint.

By default, the guest agent writes certificates directly to disk. However, youcan configure the agent to integrate certificates into the operating system'sbuilt-in certificate stores. To enable this integration, set theenable-https-mds-native-cert-store metadata key totrue. To set metadata, seeSet and remove custom metadata.

The agent's behavior for adding certificates to OS trust stores varies by OS asfollows:

Windows failover cluster support (Windows only)

The guest agent monitors the active node in theWindows Server Failover Clusterand coordinate with Google Cloud internal load balancer to forward all clustertraffic to the expected node.

You can control this behavior by using the following fields in instancemetadata or in theinstance_configs.cfgfile:

• enable-wsfc: when set totrue, the agent ignores all IP forwardinginformation and starts responding to the health check port. The defaultsetting isfalse.
• wsfc-agent-port: specifies the port where the agent responds to healthchecks. The default setting is59998.
• wsfc-addrs: a comma-separated list of IP addresses. This advanced settinglets you have both normal forwarding IPs and cluster IPs on the sameinstance. When you set this, the agent only skips auto-configuration forthe IPs in this list. By default, this value is not set.

What's next

• To learn how to manage the guest agent, seeConfigure guest agent