Guest agent functionality

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

How the guest agent works

Starting with version 20250901.00, the guest agent uses a plugin-based architecture. This design improves reliability and flexibility by 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 instance needs to run on Google Cloud. Its functionality cannot be disabled.
  • Optional plugins: these are plugins that integrate your instance with other Google Cloud services, such as Cloud Monitoring. You can control which of these plugins run on your instance.
  • Agent control plane: this is a managed Google Cloud service that runs on Google's backend infrastructure and manages the lifecycle of optional plugins, including their installation and updates.

For more information about the guest agent architecture, see About guest agent.

Core functionality

The core plugin is responsible for the fundamental services that your instance needs to function on Compute Engine. The following section details the functions that the core plugin provides. You can customize many of these features by using the guest agent configuration file.

Initial instance setup and optimizations

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

Task Frequency
Generate SSH host keys On first boot
Create the boto config for using Cloud Storage On first boot
Optimize for local SSD On every startup
Enable multi-queue on all virtionet devices On every startup

You can control these setup tasks by configuring the InstanceSetup options of the guest agent configuration file. For example, you can disable Local SSD optimization by setting optimize_local_ssd = false.

System telemetry collection

The guest agent records some basic system telemetry information at boot time and then 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 key disable-guest-telemetry to true. To set metadata, see Set and remove custom metadata.

Clock synchronization (Linux only)

To ensure accurate timekeeping, the guest agent uses the clock_skew_daemon component to periodically correct the clock on your instance to match the physical server it runs on. This process prevents a problem called clock skew and generates a system time has changed message in your instance logs, which confirms the time was successfully synchronized.

The agent normally syncs the clock after a stop or start event, or after a migration.

You can disable the clock_skew_daemon component by setting clock_skew_daemon = false in the guest agent configuration file.

Metadata script execution

You can use startup scripts and shutdown scripts to perform automated tasks 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 both startup-script and startup-script-url), the agent runs both.
  • When multiple scripts are provided for the same event, the agent executes the 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 the MetadataScripts options in the guest agent configuration file.

User account and SSH key management

The guest agent uses an accounts_daemon to 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 the Accounts options in the guest agent configuration file.

Linux

OS Login is used to manage SSH access to your instances using IAM without having to create and manage individual SSH keys. For more information about OS Login, see OS Login. On Linux instances if OS Login isn't enabled, the agent creates and manages local user accounts and their SSH keys by using metadata settings.

When you add or remove SSH Keys from instance or project metadata, the guest agent creates or deletes a local user account. The guest agent also performs the following actions to manage these local user accounts:

  • Maintains the authorized_keys file for each user account it manages as follows:
    • When you add SSH keys to metadata, the agent creates an authorized_keys file for the user account.
    • When you remove all SSH keys for a user from metadata, the agent deletes that user account's authorized_keys file.
  • Manages administrator privileges by using the google-sudoers Linux group. Any members of this group receive sudo permissions on the instance.
  • Adds all the user accounts it provisions to the google-sudoers group.
  • Adds user accounts to any additional Linux groups that you specify in the groups option of the guest agent configuration file.

Windows

On Windows instances, the agent automatically creates local user accounts for any SSH user account specified in the metadata SSH keys at the instance or project level. The guest agent also handles creating user accounts and setting or resetting passwords. These local user accounts are needed for connecting to Windows instances using SSH.

You can prevent unintended AD user provisioning by disabling the account manager on the AD controller instance. For more information on setting up AD on Compute Engine, see deploy domain controllers.

OS Login configuration (Linux only)

OS Login is used to manage SSH access to your instances using IAM without having to create and manage individual SSH keys. For more information about OS Login, see the OS Login documentation.

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

The guest agent configures OS Login by completing the following tasks:

  • Adds a Google config block to the SSHD configuration file and restarts SSHD.
  • Adds OS Login entries to the nsswitch.conf file.
  • Adds OS Login entries to the PAM configuration file for SSHD.

If you disable OS Login, the configuration changes are removed. The options under the Accounts section of the SSHD configuration 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 your instance connects to the network correctly and can access other Google Cloud services.

You can control the agent's network management behavior by configuring the NetworkInterfaces options in the guest agent configuration file. For example, you can set the manage_primary_nic = true option to have the agent manage the primary network 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 active network manager on your OS and uses it to enable all secondary network NICs.
  • Configures IP routes: the agent sets up the necessary IP (IPv4 only) routes for features like IP forwarding and alias IP ranges as follows:
    • Sets routes on the primary ethernet interface.
    • Configures Google routes by default, with the routing protocol ID 66. This ID is a namespace for guest agent configured IP addresses. This ID can be changed by using the ethernet_proto_id option in the guest agent configuration file.
  • Creates a route to the metadata server: the agent ensures that your primary NIC can always communicate with the metadata server to get instance information.
  • VLAN configuration: If your instance is configured to connect to a Virtual Local Area Network (VLAN), the guest agent automatically handles the setup. It reads the VLAN configuration from the metadata server and configures the network interface inside the instance to use the correct VLAN tag. This ensures the instance communicates on the intended logical network. Importantly, if the VLAN is attached to the primary NIC, the guest agent configures it even if manage_primary_nic is disabled.

Network manager selection

On Linux, the guest agent automatically detects which network manager is available on the system and uses it to configure the network interfaces. The agent checks for supported managers in order of priority, from netplan to dhclient.

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

Network manager Operating system Configuration location Example path Notes
netplan
  • Debian 12 or later
  • Ubuntu 20.04 or later
 /run/netplan/ /run/netplan/20-google-guest-agent-eth0.yaml The agent may also use a drop-in location at /etc/systemd/network/
wicked
  • SLES
 /etc/sysconfig/network/ /etc/sysconfig/network/ifcfg-eth0 Existing ifcfg files are not overwritten and are skipped instead.
NetworkManager
  • CentOS
  • RHEL
  • Rocky Linux
 /etc/NetworkManager/system-connections/ /etc/NetworkManager/system-connections/google-guest-agent-eth0.nmconnection
systemd-networkd
  • Debian
 /usr/lib/systemd/network/ /usr/lib/systemd/network/20-eth0-google-guest-agent.network
dhclient
  • Debian 11 or earlier
  • Ubuntu 18.04 or earlier
 /run/ /run/dhclient.google-guest-agent.eth0.ipv4.pid If none of the other network managers are detected, the guest agent defaults to using dhclient.

Secure metadata server (MDS) credential management

Shielded VMs now support secure communication with the metadata server by using the HTTPS endpoint https://metadata.google.internal/computeMetadata/v1. This enhancement provides a more secure channel for metadata access.

To enable this secure communication, the guest agent retrieves and stores necessary credentials on the instance's disk. These credentials are saved in a standard location, making them accessible to any client application running on the instance. To review these locations, see Where are certificates stored.

The setup of HTTPS MDS certificates is disabled by default. To have your Shielded VMs automatically set up the HTTPS MDS certificates, set the disable-https-mds-setup metadata key to false on your instance or project. To set metadata, see Set and remove custom metadata.

Credential management by the guest agent includes:

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

For more information on HTTPS metadata server endpoint, see About the HTTPS metadata server endpoint.

By default, the guest agent writes certificates directly to disk. However, you can configure the agent to integrate certificates into the operating system's built-in certificate stores. To enable this integration, set the enable-https-mds-native-cert-store metadata key to true. To set metadata, see Set and remove custom metadata.

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

Linux

The guest agent performs the following steps:

  1. Adds the MDS root certificate to the system's trust store. The specific path depends on the OS distribution. To review these locations, see Root certificate storage in OS trust store.
  2. Updates the local trust store by running the appropriate command for the OS, such as update-ca-certificates or update-ca-trust.

Windows

The agent adds client credentials to Cert:\LocalMachine\My and the root certificate to Cert:\LocalMachine\Root.

Windows failover cluster support (Windows only)

The guest agent monitors the active node in the Windows Server Failover Cluster and coordinate with Google Cloud internal load balancer to forward all cluster traffic to the expected node.

You can control this behavior by using the following fields in instance metadata or in the instance_configs.cfg file:

  • enable-wsfc: when set to true, the agent ignores all IP forwarding information and starts responding to the health check port. The default setting is false.
  • wsfc-agent-port: specifies the port where the agent responds to health checks. The default setting is 59998.
  • wsfc-addrs: a comma-separated list of IP addresses. This advanced setting lets you have both normal forwarding IPs and cluster IPs on the same instance. When you set this, the agent only skips auto-configuration for the IPs in this list. By default, this value is not set.

What's next