VM 확장 프로그램 문제 해결

이 문서에서는 Compute Engine 가상 머신(VM) 인스턴스에서 VM 확장 프로그램 설치를 확인하고, 정책 출시 및 VM 확장 프로그램 상태 문제를 진단하고, 게스트 에이전트 디버그 로그를 보는 방법을 설명합니다. 다음 안내에 따라 예상된 확장 프로그램이 설치되지 않은 이유, 예기치 않은 확장 프로그램이 VM에서 실행되는 이유 또는 확장 프로그램 프로세스가 중지된 이유를 파악합니다.

시작하기 전에

VM에서 VM 확장 프로그램 문제를 해결하기 전에 다음 기본 요건을 완료하세요.

• Google Cloud 리소스 계층 구조에서 확장 프로그램 정책, VM 확장 프로그램 관리자가 지원하는 확장 프로그램의 메타데이터, VM 확장 프로그램 상태를 검사하는 데 필요한 권한이 있는지 확인합니다. 자세한 내용은 VM 확장 프로그램 세부정보 및 상태 보기를 참조하세요.
• 개별 VM에 연결하기 전에 설치 실패, 비정상 종료 또는 롤백을 식별하려면 Cloud Logging에서 이전 확장 프로그램 시행 이벤트를 확인하세요. 자세한 내용은 VM 확장 프로그램 로그 보기를 참조하세요.
• VM에서 직접 실행 중인 확장 프로그램 프로세스와 게스트 에이전트 디버그 로그를 검사하려면 SSH 또는 RDP를 사용하여 VM에 연결할 수 있는지 확인합니다.

확장 프로그램이 설치되었는지 확인

Compute Engine VM에 확장 프로그램이 설치되어 실행 중인지 확인하려면 읽기 전용 메서드를 사용하여 VM 확장 프로그램 상태를 검사합니다. 게스트 OS 프로세스 또는 로그 세부정보가 필요한 경우에만 VM에 연결합니다.

읽기 전용 메서드를 사용하여 VM 확장 프로그램 상태 검사

VM에 연결하지 않고 설치된 확장 프로그램의 런타임 상태와 상태를 확인하려면 gcloud beta compute instances list-vm-extension-states 또는 gcloud beta compute instances get-vm-extension-state 명령어를 실행하거나 해당하는 REST API 메서드를 호출합니다. 응답은 각 확장 프로그램의 활성 버전, 시행 상태(enforcementState), 상태(healthStatus), 진단 메시지(healthMsg), 관리 정책 ID(policyId)를 반환합니다. 자세한 내용은 인스턴스에서 VM 확장 프로그램 상태 보기를 참조하세요.

VM에서 실행 중인 확장 프로그램 프로세스 검사

원격 상태 쿼리가 예상 상태를 반환하지 않으면 VM에 연결하고 게스트 운영체제에서 확장 프로그램 프로세스가 실행 중인지 확인합니다.

다음 표에는 지원되는 각 확장 프로그램의 프로세스 이름이 나와 있습니다.

확장 프로그램 이름	확장 프로그램 프로세스 이름
google-cloud-sap-extension	google_cloud_sap_agent
google-cloud-workload-extension	google_cloud_workload_agent
ops-agent	ops_agent

VM에서 확장 프로그램 프로세스가 실행 중인지 확인하려면 운영체제를 선택합니다.

Linux

실행 중인 확장 프로그램 프로세스를 나열하려면 다음 명령어를 실행합니다.

ps aux | grep 'EXTENSION_PROCESS_NAME'

EXTENSION_PROCESS_NAME을 앞의 표에 있는 확장 프로그램의 프로세스 이름으로 바꿉니다. 예를 들어 ops-agent 확장 프로그램 프로세스를 나열하려면 다음 명령어를 실행합니다.

ps aux | grep 'ops_agent'

Windows

실행 중인 확장 프로그램 프로세스를 나열하려면 다음 명령어를 실행합니다.

tasklist | findstr "EXTENSION_PROCESS_NAME"

EXTENSION_PROCESS_NAME을 앞의 표에 있는 확장 프로그램의 프로세스 이름으로 바꿉니다. 예를 들어 ops-agent 확장 프로그램 프로세스를 나열하려면 다음 명령어를 실행합니다.

tasklist | findstr "ops_agent"

다음 스니펫은 ops-agent 확장 프로그램이 Linux VM에서 실행 중일 때 ps 명령어의 출력 예시를 보여줍니다.

....
/var/lib/google-guest-agent/931374772276853249/plugins/ops-agent_baddabb3dac3
....

게스트 에이전트 설치 항목 검토

게스트 에이전트가 확장 프로그램 플러그인을 다운로드, 추출, 시작한 시점을 확인하려면 게스트 에이전트의 디버그 로그를 사용 설정하고 확인합니다.

다음 스니펫은 게스트 에이전트가 Linux VM에 ops-agent 확장 프로그램을 설치하고 시작할 때의 게스트 에이전트 로그 항목 예시를 보여줍니다.

my-instance google_guest_agent [14972]: Installing plugin "ops-agent", revision "2dfa648c1892da87"
my-instance google_guest_agent [14972]: (client.go:181) Sent message [[type.googleapis.com/agent_controlplane.PluginEventMessage: (revision_id:"2dfa648c1892da87)]]
my-instance google_guest_agent [14972]: (pluginengine.go:202) Running "DownloadPluginStep" on plugin "ops-agent_2dfa648c1892da87"
my-instance google_guest_agent [14972]: (pluginengine.go:316) Successfully downloaded "https://storage.googleapis.com/acp-gcs-bucket-us-central1-a/ops-agent
my-instance google_guest_agent [14972]: (pluginengine.go:202) Running "UnpackPluginArchiveStep" on plugin "ops-agent_2dfa648c1892da87"
my-instance google_guest_agent [14972]: (pluginengine.go:361) Successfully unpacked "/var/lib/google-guest-agent/ops-agent.tar.gz" to "/google-guest-agent/ops-agent_2dfa648c1892da87
my-instance google_guest_agent [14972]: (pluginengine.go:202) Running "LaunchPluginStep" on plugin "ops-agent_2dfa648c1892da87"
my-instance google_guest_agent [14972]: (run_linux.go:32) Attempting process start: (OutputType:0 Name:/var/lib/google-guest-agent/plugins/ops-agent_2dfa648c1892da87)
my-instance google_guest_agent [14972]: (pluginlauncher.go:132) Launched a plugin process from "/var/lib/google-guest-agent/plugins/ops-agent_2dfa648c1892da87"
my-instance google_guest_agent [14972]: (plugin.go:136) Dialing in on plugin "ops-agent 2dfa648c1892da87"
my-instance google_guest_agent [14972]: (plugin.go:51) Executing start request on plugin "ops-agent_2dfa648c1892da87"

설치 문제 해결하기

VM에 확장 프로그램이 설치되지 않았거나 VM에서 예기치 않은 확장 프로그램이 실행되는 경우 설치를 다시 시도하기 전에 정책 출시, 대상 라벨, 시행 상태를 진단합니다.

VM에 확장 프로그램이 설치되지 않은 이유를 확인하려면 다음 진단 단계를 완료하세요.

1. 정책 시행을 기다립니다. 재시도를 포함한 정책 출시는 대상 VM에서 완료하는 데 최대 1시간이 걸릴 수 있습니다. 출시 진행 상황 검사에 대한 자세한 내용은 확장 프로그램 정책 보기를 참고하세요.
2. 정책에 지정한 포함 라벨이 VM의 라벨과 일치하는지 확인하고 VM 확장 프로그램 관리자가 지원하는 확장 프로그램의 메타데이터를 확인합니다.
   • 조직, 폴더 또는 프로젝트 전체에서 정책 라벨 선택기 및 우선순위 번호를 확인하려면 확장 프로그램 정책 보기를 참고하세요.
   • VM 확장 프로그램 관리자가 모든 영역 또는 특정 영역에서 지원하는 확장 프로그램의 이름, 버전 번호, 지원 수준을 확인하려면 VM 확장 프로그램 및 버전 보기를 참고하세요.
3. 시행 상태, 상태, 진단 메시지, 관리 정책 ID(policyId)를 확인하려면 영향을 받는 VM에서 확장 프로그램 상태를 검사합니다. 일반적인 오류 상태에는 INSTALL_FAILED, INCOMPATIBLE, ROLLED_BACK가 있습니다. 여러 정책이 동일한 VM을 타겟팅하는 경우 policyId 필드에 각 확장 프로그램을 제어하는 정책이 표시됩니다. 자세한 내용은 인스턴스에서 VM 확장 프로그램 상태 보기를 참고하세요.
4. VM에서 게스트 수준 설치 오류를 식별하려면 게스트 에이전트의 디버그 로그를 사용 설정하고 확인합니다.

확장 프로그램 설치 다시 시도

기본 정책 구성 또는 게스트 OS 문제를 해결한 후 게스트 에이전트가 영향을 받는 VM에 설치를 다시 시도하도록 정책 구성을 다시 적용합니다.

확장 프로그램 설치를 다시 시도하려면 다음 옵션 중 하나를 선택합니다.

• 정책 다시 만들기: 정책을 삭제한 후 새 정책을 만듭니다.

• 임시 우선순위가 높은 정책 적용: 대규모 Fleet에 영향을 미치는 정책을 다시 만들지 않고 특정 VM에서 설치를 다시 시도하려면 다음 단계를 완료합니다.

  1. 설치에 실패한 VM에 status=failed와 같은 임시 라벨을 추가합니다.

  2. 임시 라벨을 타겟팅하는 우선순위가 더 높은(정수 값이 더 낮은) 임시 정책을 만듭니다. 예를 들어 원래 정책에서 기본 우선순위 1000를 사용하는 경우 우선순위가 500인 임시 정책을 만들려면 다음 명령어를 실행합니다.

     gcloud compute zone-vm-extension-policies create temp-policy \
         --project=test-project \
         --zone=us-central1-f \
         --extensions=ops-agent \
         --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
         --priority=500 \
         --inclusion-labels=status=failed
     

  3. 게스트 에이전트가 대상 VM에 확장 프로그램을 설치한 후 임시 정책을 삭제합니다.

  4. VM에서 임시 라벨을 삭제합니다. 원래 정책이 해당 VM에 계속 적용되므로 확장 프로그램은 설치된 상태로 유지됩니다.

게스트 에이전트의 디버그 로그 보기

원격 상태 쿼리 및 Logging 이벤트 로그에 확장 프로그램이 다운로드되거나 시작되지 않은 이유가 표시되지 않으면 게스트 에이전트 구성 파일의 Core 섹션에서 상세 디버그 로깅을 사용 설정합니다.

게스트 에이전트의 디버그 로그를 사용 설정하고 보려면 운영체제를 선택합니다.

Linux

Linux VM에서 디버그 로깅을 사용 설정하려면 다음 단계를 완료하세요.

1. /etc/default/instance_configs.cfg에서 게스트 에이전트 구성 파일을 엽니다.

2. /etc/default/instance_configs.cfg에 다음 설정을 추가합니다. [Core] 섹션이 이미 있는 경우 [Core] 아래에 log_level 및 log_verbosity를 추가합니다.

   [Core]
   log_level = 4
   log_verbosity = 4
   

3. 게스트 에이전트 관리자를 다시 시작하려면 다음 명령어를 실행합니다.

   sudo systemctl restart google-guest-agent-manager
   

4. 확장 프로그램 설치 중에 생성된 게스트 에이전트 로그를 보려면 다음 명령어를 실행합니다.

   journalctl -u google-guest-agent-manager
   

Windows

Windows VM에서 디버그 로깅을 사용 설정하려면 다음 단계를 완료합니다.

1. C:\Program Files\Google\Compute Engine\instance_configs.cfg에서 게스트 에이전트 구성 파일을 엽니다.

2. instance_configs.cfg에 다음 설정을 추가합니다. [Core] 섹션이 이미 있는 경우 [Core] 아래에 log_level 및 log_verbosity를 추가합니다.

   [Core]
   log_level = 4
   log_verbosity = 4
   

3. 관리자 권한 명령 프롬프트 또는 PowerShell 창에서 다음 명령어를 실행하여 게스트 에이전트 관리자를 다시 시작합니다.

   net stop GCEAgentManager
   net start GCEAgentManager
   

4. PowerShell에서 확장 프로그램 설치 중에 생성된 게스트 에이전트 로그를 보려면 다음 명령어를 실행합니다.

   Get-Eventlog -Source google_guest_agent_manager -LogName Application
   

일반적인 게스트 에이전트 로그 오류 해결

게스트 에이전트 디버그 로그를 검사할 때 확장 프로그램이 VM에서 추출되거나 실행되지 못하게 하는 리소스 제약 조건 오류가 있는지 확인합니다.

다음 표에는 게스트 에이전트 디버그 로그에 보고되는 일반적인 오류와 해결 방법이 나와 있습니다.

오류 조건	해결 방법
디스크 공간 부족	VM에 확장 프로그램 보관 파일을 다운로드하거나 추출할 디스크 공간이 부족하다고 로그에 보고되면 사용하지 않는 파일을 삭제하거나 부팅 디스크 크기를 조절합니다.
과도한 리소스 사용	로그에 메모리 또는 CPU 사용량이 많아 게스트 에이전트가 확장 프로그램을 중지했다고 표시되면 VM의 머신 유형을 메모리 또는 vCPU가 더 많은 머신 유형으로 변경합니다.

다음 단계

• 출시 진행 상황과 확장 프로그램 상태를 검사하려면 VM 확장 프로그램 세부정보 및 상태 보기를 참조하세요.
• 로깅에서 이전 시정 조치 이벤트 및 감사 설치를 쿼리하려면 VM 확장 프로그램 로그 보기를 참조하세요.
• Cloud Monitoring 대시보드를 빌드하고 에이전트 상태, CPU, 메모리 사용량에 대한 알림을 설정하려면 VM 확장 프로그램 모니터링을 참조하세요.
• 구성 설정을 수정하거나, 고정된 버전을 변경하거나, 배포된 에이전트를 삭제하려면 확장 프로그램 정책을 사용하여 VM 확장 프로그램 관리를 참조하세요.