이 문서에서는 게스트 에이전트 서비스를 관리하고 구성 파일을 수정하여 해당 기능을 구성하는 방법을 설명합니다.
게스트 에이전트는 게스트 환경의 핵심 구성요소입니다. 게스트 환경에는 Compute Engine에서 인스턴스가 실행되는 데 필요한 스크립트, 데몬, 바이너리가 포함되어 있습니다. 게스트 환경에 대한 자세한 내용은 게스트 환경을 참조하세요. 게스트 에이전트는 Google 제공 OS 이미지에서 기본 설정으로 자동 실행되지만, 필요에 따라 동작을 맞춤설정할 수도 있습니다. 게스트 에이전트 핵심 기능에 대한 자세한 내용은 게스트 에이전트 기능을 참조하세요.
게스트 에이전트 다시 시작
게스트 에이전트는 Linux 및 Windows 운영체제 모두에서 데몬으로 실행됩니다. Linux에서는 게스트 에이전트가 systemd 서비스로 실행되고 Windows에서는 시스템 서비스로 실행됩니다.
Linux 및 Windows 운영체제에서 다시 시작 단계는 다음과 같이 다릅니다.
Linux
Linux에서 다시 시작하려면 다음 옵션 중 하나를 선택하세요.
게스트 에이전트 버전이
20250901.00이상인 경우 다음 명령어를 실행합니다.ggactl_plugin coreplugin restart
이전 버전의 게스트 에이전트인 경우 다음 명령어를 실행합니다.
systemctl restart google-guest-agent
Windows
Windows에서 다시 시작하려면 다음 옵션 중 하나를 선택합니다.
게스트 에이전트 버전이
20250901.00이상인 경우 다음 명령어를 실행합니다.ggactl_plugin coreplugin restart
이전 버전의 게스트 에이전트인 경우 다음 PowerShell 명령어를 사용합니다.
게스트 에이전트를 중지하려면 다음을 수행합니다.
Stop-Service GCEAgent
게스트 에이전트를 시작하려면 다음을 수행합니다.
Start-Service GCEAgent
또는 게스트 에이전트를 다시 시작하려면 다음을 수행합니다.
Restart-Service GCEAgent
모든 버전의 게스트 에이전트에서 작업 관리자를 사용할 수도 있습니다. GCEGuestAgent 서비스를 찾아 다시 시작하세요.
게스트 에이전트 구성 파일 업데이트
게스트 에이전트의 구성 파일 instance_configs.cfg를 수정하여 동작을 맞춤설정할 수 있습니다. 이 파일을 사용하면 기능을 사용 설정 또는 사용 중지하고 여러 작업의 기본값을 설정할 수 있습니다.
Linux 및 Windows 운영체제에서 instance_configs.cfg 파일을 수정하려면 다음 섹션을 참조하세요.
Linux
Linux VM에서 구성 파일을 수정하려면 다음을 수행하세요.
/etc/default/instance_configs.cfg에 있는 구성 파일을 새로 만들거나 수정하고 필요한 옵션을 설정합니다. 옵션 목록은 구성 옵션을 참조하세요.예를 들어 새 사용자가 생성되는 방식을 맞춤설정하고 생성할 SSH 호스트 키 유형을 지정하려면 파일을 다음 내용으로 만들거나 업데이트하세요.
[Accounts] useradd_cmd = useradd -m -G google-sudoers [InstanceSetup] host_key_types = ecdsa,ed25519
참고: 일부 Linux 배포판에는
/etc/default/instance_configs.cfg.distro에 자체 기본 설정이 포함되어 있을 수 있습니다. 에이전트는 이러한 설정을 먼저 읽지만/etc/default/instance_configs.cfg에 정의한 설정이 배포판 기본값보다 우선 적용됩니다. 이렇게 하면 패키지 업데이트 중에도 커스텀 구성이 손실되지 않습니다.구성 파일을 수정한 후에는 변경사항을 적용하려면 게스트 에이전트를 다시 시작해야 합니다.
Windows
Windows VM의 구성 파일은 C:\Program Files\Google\Compute Engine\instance_configs.cfg에 있습니다. Windows에서 에이전트를 구성하는 방법에 대한 자세한 내용은 Windows 인스턴스 기능 사용 설정 및 사용 중지를 참조하세요.
구성 옵션
다음 표에서는 instance_configs.cfg 파일에 사용할 수 있는 구성 옵션을 보여줍니다.
Accounts
instance_configs.cfg 파일의 Accounts 섹션에 있는 옵션을 사용하여 게스트 에이전트의 사용자 및 그룹 관리를 제어할 수 있습니다.
| 옵션 | 설명 | 운영체제 | 기본값 |
|---|---|---|---|
deprovision_remove |
true로 설정하면 사용자 계정을 삭제할 때 해당 사용자의 홈 디렉터리도 함께 삭제됩니다. 기본적으로는 사용자 계정만 삭제되고 디렉터리는 그대로 유지됩니다. |
Linux | false |
groups |
새 사용자에게 적용할 그룹을 쉼표로 구분하여 나열합니다. | Linux | 비어 있음 |
useradd_cmd |
새 사용자를 만들 때 게스트 에이전트가 실행하는 명령어를 설정합니다. 예를 들어 사용자의 홈 디렉터리를 만들고 google-sudoers 그룹에 추가하려면 값을 useradd -m -G google-sudoers로 설정합니다. |
Linux | 시스템 기본값 |
userdel_cmd |
사용자를 삭제할 때 게스트 에이전트가 실행하는 명령어를 설정합니다.
예를 들어 사용자의 홈 디렉터리와 파일을 모두 삭제하려면 값을 userdel -r로 설정합니다. |
Linux | 시스템 기본값 |
usermod_cmd |
사용자의 그룹을 수정할 때 게스트 에이전트가 실행하는 명령어를 설정합니다. | Linux | 시스템 기본값 |
gpasswd_add_cmd |
사용자를 그룹에 추가할 때 게스트 에이전트가 실행하는 명령어를 설정합니다. | Linux | 시스템 기본값 |
gpasswd_remove_cmd |
사용자를 그룹에서 삭제할 때 게스트 에이전트가 실행하는 명령어를 설정합니다. | Linux | 시스템 기본값 |
groupadd_cmd |
새 그룹을 만들 때 게스트 에이전트가 실행하는 명령어를 설정합니다. | Linux | 시스템 기본값 |
Core
instance_configs.cfg 파일의 Core 섹션에 있는 옵션을 사용하여 게스트 에이전트의 핵심 기능을 제어할 수 있습니다.
| 옵션 | 설명 | 운영체제 | 기본값 |
|---|---|---|---|
cloud_logging_enabled |
false로 설정하면 게스트 에이전트가 활동 로그를 Cloud Logging으로 전송하지 않습니다. |
Linux 및 Windows | true |
log_level |
게스트 에이전트 로그의 로깅 수준을 설정합니다. 이 설정은 Cloud Logging뿐 아니라 게스트 에이전트가 생성하는 모든 로그에 적용됩니다. 설정 및 레벨은 다음과 같습니다.
|
Linux 및 Windows | 3 |
log_verbosity |
DEBUG 로그의 로깅 세부정보 수준을 설정합니다.
허용 가능한 값은 0~4입니다.
값이 높을수록 더 상세한 로그가 출력됩니다.
|
Linux 및 Windows | 0 |
Daemons
instance_configs.cfg 파일의 Daemons 섹션에 있는 옵션을 사용하여 게스트 에이전트가 관리하는 특정 백그라운드 데몬의 실행을 사용 설정하거나 사용 중지할 수 있습니다.
| 옵션 | 설명 | 운영체제 | 기본값 |
|---|---|---|---|
accounts_daemon |
false로 설정하면 게스트 에이전트가 사용자 계정 및 SSH 키 관리를 사용 중지합니다. |
Linux | true |
clock_skew_daemon |
false로 설정하면 게스트 에이전트가 시계 동기화를 사용 중지합니다. |
Linux | true |
network_daemon |
false로 설정하면 게스트 에이전트가 네트워크 관리를 사용 중지합니다. |
Linux | true |
인스턴스 설정
instance_configs.cfg 파일의 InstanceSetup 섹션에 있는 옵션을 사용하여 초기 인스턴스 설정 중에 게스트 에이전트가 수행하는 다양한 작업을 제어할 수 있습니다.
| 옵션 | 설명 | 운영체제 | 기본값 |
|---|---|---|---|
host_key_types |
생성할 호스트 키 유형을 쉼표로 구분한 목록입니다. | Linux | ecdsa,ed25519,rsa |
optimize_local_ssd |
false로 설정하면 게스트가 시작 시 로컬 SSD를 최적화하지 않습니다. |
Linux | true |
network_enabled |
false로 설정하면 게스트 에이전트가 메타데이터 정보가 필요한 인스턴스 설정 기능을 건너뜁니다. 또한 이 옵션을 false로 설정하면 호스트 키 생성이 사용 중지되고 게스트 에이전트가 boto 구성 파일을 구성하지 않도록 방지합니다. |
Linux 및 Windows | true |
set_boto_config |
false로 설정하면 게스트 에이전트가 boto 구성 파일을 만들거나 업데이트하지 않습니다. Boto 라이브러리를 사용하고 Cloud Storage 액세스를 위해 기본 게스트 에이전트의 기본 구성을 사용하는 애플리케이션은 수동으로 boto 구성을 하지 않으면 예상대로 작동하지 않을 수 있습니다. |
Linux 및 Windows | true |
set_host_keys |
false로 설정하면 게스트 에이전트가 첫 번째 부팅 시 호스트 키 생성을 건너뜁니다. |
Linux | true |
set_multiqueue |
false로 설정하면 게스트 에이전트가 네트워크 드라이버의 멀티큐 기능을 사용 설정하여 네트워크 성능을 최적화하지 않습니다. true로 설정하면 에이전트가 네트워크 트래픽에 대해 여러 큐를 사용하도록 시스템을 구성하여 처리량을 높이고 지연 시간을 줄일 수 있습니다. |
Linux | true |
IP 전달
instance_configs.cfg 파일의 IpForwarding 섹션에 있는 옵션을 사용하여 게스트 에이전트가 IP 전달 및 라우팅을 관리하는 방식을 구성할 수 있습니다.
| 옵션 | 설명 | 운영체제 | 기본값 |
|---|---|---|---|
ethernet_proto_id |
데몬 추가 경로에 사용할 프로토콜 ID 문자열입니다. | Linux | 66 |
ip_aliases |
false로 설정하면 게스트 에이전트가 별칭 IP 경로를 설정하지 않습니다. |
Linux | true |
target_instance_ips |
false로 설정하면 게스트 에이전트가 내부 IP 주소 부하 분산을 사용 설정하지 않습니다. |
Linux | true |
메타데이터 스크립트 실행
instance_configs.cfg 파일의 MetadataScripts 섹션에 있는 옵션을 사용하여 시작 및 종료 스크립트 등 메타데이터 스크립트의 실행을 제어할 수 있습니다.
| 옵션 | 설명 | 운영체제 | 기본값 |
|---|---|---|---|
default_shell |
스크립트를 실행할 때 사용할 기본 셸입니다. | Linux | /bin/bash |
run_dir |
메타데이터 스크립트를 실행하기 위한 기본 디렉터리입니다. | Linux | /var/run/google-startup-scripts |
startup |
false로 설정하면 게스트 에이전트가 메타데이터에서 시작 스크립트를 실행하지 않습니다. |
Linux 및 Windows | true |
shutdown |
false로 설정하면 게스트 에이전트가 메타데이터에서 종료 스크립트를 실행하지 않습니다. |
Linux 및 Windows | true |
네트워크 인터페이스
instance_configs.cfg 파일의 NetworkInterfaces 섹션에 있는 옵션을 사용하여 게스트 에이전트가 VM의 네트워크 인터페이스를 관리하는 방식을 제어할 수 있습니다.
| 옵션 | 설명 | 운영체제 | 기본값 |
|---|---|---|---|
setup |
false로 설정하면 게스트 에이전트가 네트워크 인터페이스 설정을 건너뜁니다. |
Linux | true |
ip_forwarding |
false로 설정하면 게스트 에이전트가 IP 전달을 건너뜁니다. |
Linux | true |
manage_primary_nic |
true로 설정하면 게스트 에이전트가 기본 및 보조 NIC를 관리합니다. |
Linux | false |
dhcp_command |
네트워크 인터페이스를 사용 설정하기 위한 대체 DHCP 실행 파일의 경로입니다. | Linux | 비어 있음 |
restore_debian12_netplan_config |
true로 설정하면 게스트 에이전트가 /etc/netplan/90-default.yaml에 있는 Debian 12 기본 netplan 구성을 다시 만듭니다. |
Linux(Debian 12) | true |
OS 로그인
instance_configs.cfg 파일의 OSLogin 섹션에 있는 옵션을 사용하여 게스트 에이전트와 OS 로그인 간의 통합을 구성할 수 있습니다.
| 옵션 | 설명 | 운영체제 | 기본값 |
|---|---|---|---|
cert_authentication |
false로 설정하면 게스트 에이전트가 sshd의 TrustedUserCAKeys, AuthorizedPrincipalsCommand, AuthorizedPrincipalsCommandUser 키를 구성하지 않습니다. |
Linux | true |
다음 단계
- 직렬 포트 출력을 확인하여 게스트 에이전트 로그를 점검하고 문제를 해결합니다.