이 문서에서는 게스트 에이전트 서비스를 관리하고 구성 파일을 수정하여 기능을 구성하는 방법을 설명합니다.
게스트 에이전트는 게스트 환경의 중요한 구성요소입니다. 게스트 환경에는 인스턴스가 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 파일에 사용할 수 있는 구성 옵션이 나와 있습니다.
계정
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 |
데몬
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 |
다음 단계
- 직렬 포트 출력을 확인하여 게스트 에이전트 로그를 확인하고 문제를 해결합니다.