[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["難以理解","hardToUnderstand","thumb-down"],["資訊或程式碼範例有誤","incorrectInformationOrSampleCode","thumb-down"],["缺少我需要的資訊/範例","missingTheInformationSamplesINeed","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-09-09 (世界標準時間)。"],[],[],null,["Linux Windows\n\n*** ** * ** ***\n\nThis document provides an overview of the guest agent architecture. The guest\nagent is a critical component of the guest environment. The guest environment\ncontains scripts, daemons, and binaries that instances need to run on Compute Engine.\nFor more information, see [Guest environment](/compute/docs/images/guest-environment).\n\nThe guest agent sets up services and defines minimum configurations for\nfeatures such as snapshot script execution, Windows failover, OS login, and\nmetadata-based SSH authentication. For more information about core functions of\nthe guest agent, see [Guest agent functionality](/compute/docs/images/guest-agent-functions).\n\nGuest agent architecture\n\nStarting with version `20250901.00`, the guest agent architecture is\nupdated from a monolithic design to a modern, plugin-based system. This\nevolution improves flexibility, reliability, and extensibility.\n\n- *Monolithic architecture* : guest agents earlier than `20250901.00`\n feature a single, unified process centered around the metadata server's\n description of instances. The metadata server is a per-instance HTTP server\n that runs alongside every Compute Engine instance. For more\n information about the metadata server, see [VM metadata](/compute/docs/metadata/overview).\n\n The guest agent long polls the metadata server and takes action\n based on state changes. With this architecture, the agent's state is shared\n across all tasks such as SSH and network setup.\n This monolithic approach lacked interface and component isolation. Changes\n or feature introductions in one area of the agent affect the entire system\n simultaneously. This pattern makes feature additions and testing coverage\n challenging.\n- *Plugin-based architecture* : starting with version `20250901.00`, the\n guest agent is divided into distinct, independent plugins managed by a\n central manager. Each plugin can interact with the metadata server and, as\n directed by a central manager, makes changes as needed. This\n modular approach ensures that a crash in one plugin does not affect the core\n agent or other plugins.\n\nThe plugin-based architecture\n\nThis architecture is built around a central manager that controls various\nplugins, separating core functionalities from optional, service-specific\nplugins.\n\nKey components\n\nThe following diagram shows the key components of the guest agent and their\ninteractions.\n[](../../images/guest-environment/guest-agent-arch.png) Figure 1. Guest agent architecture\n\n- **Core plugin**: this plugin encapsulates the functionality of the original\n guest agent. It performs the essential tasks that your instance needs to run\n on Google Cloud. These include tasks such as the following:\n\n - Network configuration: sets up the primary network interface to enable communication.\n - SSH access: manages user SSH keys to allow secure connections to your instance.\n - Metadata access: provides a pathway for the instance to access instance and project metadata.\n\n You can't disable the core plugin.\n\n For more information about core functions of the guest agent, see\n [Guest agent functionality](/compute/docs/images/guest-agent-functions).\n- **Optional plugins**: you can provision these plugins to integrate with other\n Google Cloud services to perform tasks such as:\n\n - Monitoring and logging: enable the Ops Agent plugin to collect metrics and logs for Cloud Monitoring.\n - Workload management: enable the Workload Manager plugin to gather configuration and runtime information from your workloads for analysis.\n - Workload optimization: enable the SAP Agent plugin to support your SAP workloads running on Google Cloud.\n\n You can enable or disable optional plugins as needed.\n- **Agent control plane**: this managed Google Cloud service runs on\n Google's backend infrastructure. The control plane manages the lifecycle of\n optional plugins, including their installation, updates, and configuration,\n by communicating with the guest agent manager on the instance.\n\n- **Guest agent manager**: this central process starts, stops, and\n monitors the status of all plugins. The guest agent manager facilitates\n communication between the core plugin and the agent control plane.\n Lifecycle management for the optional plugins includes the following:\n\n - Installation and updates: the guest agent manager installs, starts, stops, and configures optional plugins based on instructions from the agent control plane.\n - Health monitoring: the guest agent manager monitors the health and status of optional plugins, including their CPU and memory usage, and reports this information back to the agent control plane.\n - Policy management: use Compute Engine APIs to create policies that control the installation and versioning of optional plugins.\n\nBenefits\n\nThe plugin-based architecture offers several advantages over the monolithic\ndesign. These benefits include the following:\n\n- **Plugin isolation**: each plugin runs in a separate process, so a crash in one doesn't affect the core agent or other plugins.\n- **Resource protection**: the guest agent uses OS-level features to enforce resource limits on plugins, preventing any single plugin from consuming excessive CPU or memory.\n- **Automatic crash recovery**: the system automatically recovers from a plugin crash by stopping and relaunching the plugin.\n- **Selective enablement**: you can disable optional plugins that are not needed, which lets you secure or optimize your instance.\n- **Reduced overhead for optional plugins**: the guest agent manager automatically handles the installation and updates of optional plugins, reducing the manual effort required to keep them up-to-date.\n\nLocation of guest agent binaries\n\nThe following tables list the file paths for the different guest agent binaries\non Linux and Windows instances, depending on the architecture.\n\nPlugin-based agent binaries\n\nThis table lists the file paths for the plugin-based guest agent binaries on\nLinux and Windows instances:\n\n| Component | Path on Linux | Path on Windows |\n|------------------------|-------------------------------------------|----------------------------------------------------------------------------|\n| Guest agent manager | `/usr/bin/google_guest_agent_manager` | `C:\\ProgramData\\Google\\Compute Engine\\google-guest-agent` |\n| Core plugin binary | `/usr/lib/google/guest_agent/core_plugin` | `C:\\Program Files\\Google\\Compute Engine\\agent\\CorePlugin.exe` |\n| Metadata script runner | `/usr/bin/gce_metadata_script_runner` | `C:\\Program Files\\Google\\Compute Engine\\agent\\GCEMetadataScriptRunner.exe` |\n\nMonolithic agent binaries\n\nThe following table lists the file paths for the monolithic guest agent\nbinaries on Linux and Windows instances:\n\n| Component | Path on Linux | Path on Windows |\n|------------------------|------------------------------------------|----------------------------------------------------------------------------------|\n| Guest agent | `/usr/bin/google_guest_agent` | `C:\\Program Files\\Google\\Compute Engine\\google_guest_agent.exe` |\n| Metadata script runner | `/usr/bin/google_metadata_script_runner` | `C:\\Program Files\\Google\\Compute Engine\\metadata_scripts\\GCEMetadataScripts.exe` |\n| Authorized keys | Not applicable | `C:\\Program Files\\Google\\Compute Engine\\agent\\GCEAuthorizedKeys.exe` |\n\nBackward compatibility\n\nTo ensure a smooth transition from the previous, monolithic guest agent to the\nplugin-based system, the guest agent package includes several components\ndesigned for backward compatibility. These components are not part of the\nplugin-based architecture and activate only if you manually choose to revert to\nthe monolithic agent by setting the metadata attribute\n`enable-guest-agent-core-plugin` to `false`.\n\nThe components that support this compatibility include the following:\n\n- Guest agent compatibility manager: this package manages the switch between the plugin-based agent and the monolithic agent.\n- Metadata script runner compatibility manager: this package ensures that the correct script runner is used, depending on whether the monolithic or plugin-based agent is active.\n- Authorized keys compatibility manager (Windows only): this package handles SSH keys, ensuring that the correct keys are used for either the old or new agent.\n\n| Component | Path on Linux | Path on Windows |\n|----------------------------------------------|------------------------------------------|----------------------------------------------------------------------------------------|\n| Guest agent compatibility manager | `/usr/bin/google_guest_compat_manager` | `C:\\Program Files\\Google\\Compute Engine\\agent\\GCEWindowsCompatManager.exe` |\n| Metadata script runner compatibility manager | `/usr/bin/metadata_script_runner_compat` | `C:\\Program Files\\Google\\Compute Engine\\metadata_scripts\\GCECompatMetadataScripts.exe` |\n| Authorized keys compatibility manager | Not applicable | `C:\\Program Files\\Google\\Compute Engine\\agent\\GCEWindowsAuthorizedKeysCompat.exe` |\n\nWhat's next\n\n- For more information about core plugin functions, see [Guest agent functionality](/compute/docs/images/guest-agent-functions)"]]
