이 문서에서는 게스트 에이전트 아키텍처를 간략하게 설명합니다. 게스트 에이전트는 게스트 환경의 중요한 구성요소입니다. 게스트 환경에는 인스턴스가 Compute Engine에서 실행하는 데 필요한 스크립트, 데몬, 바이너리가 포함되어 있습니다.
자세한 내용은 게스트 환경을 참고하세요.
게스트 에이전트는 스냅샷 스크립트 실행, Windows 장애 조치, OS 로그인, 메타데이터 기반 SSH 인증과 같은 기능의 서비스를 설정하고 최소 구성을 정의합니다. 게스트 에이전트의 핵심 기능에 대한 자세한 내용은 게스트 에이전트 기능을 참고하세요.
게스트 에이전트 아키텍처
버전 20250901.00부터 게스트 에이전트 아키텍처가 모놀리식 설계에서 최신 플러그인 기반 시스템으로 업데이트됩니다. 이러한 발전으로 유연성, 안정성, 확장성이 향상됩니다.
모놀리식 아키텍처: 20250901.00 이전 게스트 에이전트는 인스턴스에 관한 메타데이터 서버의 설명을 중심으로 하는 단일 통합 프로세스를 특징으로 합니다. 메타데이터 서버는 모든 Compute Engine 인스턴스와 함께 실행되는 인스턴스별 HTTP 서버입니다. 메타데이터 서버에 대한 자세한 내용은 VM 메타데이터를 참고하세요.
게스트 에이전트는 메타데이터 서버를 길게 폴링하고 상태 변경에 따라 작업을 실행합니다. 이 아키텍처를 사용하면 에이전트의 상태가 SSH, 네트워크 설정과 같은 모든 작업에서 공유됩니다.
이 모놀리식 접근 방식에는 인터페이스와 구성요소 격리가 부족했습니다. 에이전트의 한 영역에서 변경사항이나 기능이 도입되면 전체 시스템에 동시에 영향을 미칩니다. 이 패턴은 기능 추가와 테스트 범위에 어려움을 줍니다.
플러그인 기반 아키텍처: 버전 20250901.00부터 게스트 에이전트는 중앙 관리자가 관리하는 별도의 독립적인 플러그인으로 나뉩니다. 각 플러그인은 메타데이터 서버와 상호작용할 수 있으며 중앙 관리자의 지시에 따라 필요에 따라 변경합니다. 이 모듈식 접근 방식을 사용하면 하나의 플러그인에서 비정상 종료가 발생해도 핵심 에이전트나 다른 플러그인에는 영향을 미치지 않습니다.
플러그인 기반 아키텍처
이 아키텍처는 다양한 플러그인을 제어하는 중앙 관리자를 중심으로 구축되어 핵심 기능을 선택적 서비스별 플러그인과 분리합니다.
주요 구성요소
다음 다이어그램은 게스트 에이전트의 주요 구성요소와 상호작용을 보여줍니다.
그림 1. 게스트 에이전트 아키텍처
핵심 플러그인: 이 플러그인은 원래 게스트 에이전트의 기능을 캡슐화합니다. Google Cloud에서 인스턴스를 실행하는 데 필요한 필수 작업을 실행합니다. 여기에는 다음과 같은 작업이 포함됩니다.
네트워크 구성: 통신을 지원하도록 기본 네트워크 인터페이스를 설정합니다.
SSH 액세스: 인스턴스에 대한 보안 연결을 허용하도록 사용자 SSH 키를 관리합니다.
메타데이터 액세스: 인스턴스가 인스턴스 및 프로젝트 메타데이터에 액세스할 수 있는 경로를 제공합니다.
이전의 모놀리식 게스트 에이전트에서 플러그인 기반 시스템으로 원활하게 전환할 수 있도록 게스트 에이전트 패키지에는 하위 호환성을 위해 설계된 여러 구성요소가 포함되어 있습니다. 이러한 구성요소는 플러그인 기반 아키텍처의 일부가 아니며 메타데이터 속성 enable-guest-agent-core-plugin를 false로 설정하여 모놀리식 에이전트로 되돌리도록 수동으로 선택한 경우에만 활성화됩니다.
이 호환성을 지원하는 구성요소는 다음과 같습니다.
게스트 에이전트 호환성 관리자: 이 패키지는 플러그인 기반 에이전트와 모놀리식 에이전트 간 전환을 관리합니다.
메타데이터 스크립트 러너 호환성 관리자: 이 패키지는 모놀리식 또는 플러그인 기반 에이전트가 활성 상태인지에 따라 올바른 스크립트 러너가 사용되도록 합니다.
승인된 키 호환성 관리자 (Windows만 해당): 이 패키지는 SSH 키를 처리하여 이전 또는 새 에이전트에 올바른 키가 사용되도록 합니다.
[[["이해하기 쉬움","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(UTC)"],[],[],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)"]]
