에이전트 정책 관리

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

에이전트 정책을 사용하면 사용자가 지정한 기준과 일치하는 Compute Engine VM Fleet에서 Google Cloud Observability 에이전트를 자동으로 설치하고 유지보수할 수 있습니다. 하나의 명령어로 해당 Google Cloud 프로젝트와 연관된 기존 VM 및 신규 VM을 제어하는 Google Cloud 프로젝트에 대한 정책을 만들어 이러한 VM에서 모든 Google Cloud Observability 에이전트에 대해 적절한 설치 및 선택적인 자동 업그레이드를 보장할 수 있습니다.

에이전트 정책을 만들고 관리하려면 Google Cloud CLI에서 gcloud beta compute instances ops-agents policies 명령어 그룹을 사용합니다. 이 그룹의 명령어는 Compute Engine의 VM Manager 도구 모음을 사용하여 OS 정책을 관리합니다. 이를 통해 운영 에이전트, 기존 Monitoring 에이전트, 기존 Logging 에이전트 등 Google Cloud Observability 에이전트와 같은 소프트웨어 구성의 배포 및 유지보수를 자동화할 수 있습니다.

지원되는 운영체제

다음 표에 표시된 운영체제를 실행하는 Compute Engine VM 인스턴스에 에이전트 정책을 적용할 수 있습니다. 표에서 에이전트 열은 gcloud beta compute instances ops-agents policies create 호출에 지정된 에이전트 유형에 매핑됩니다.

• Logging 에이전트는 에이전트 유형이 logging인 정책에 매핑됩니다.
• Monitoring 에이전트는 에이전트 유형이 metrics인 정책에 매핑됩니다.
• 운영 에이전트는 에이전트 유형이 ops-agent인 정책에 매핑됩니다.

운영체제	Logging 에이전트	Monitoring 에이전트	운영 에이전트
CentOS 7
CentOS 8
Rocky Linux 8
RHEL 6
RHEL 7: rhel-7, rhel-7-6-sap-ha, rhel-7-7-sap-ha, rhel-7-9-sap-ha		^1
RHEL 8: rhel-8, rhel-8-4-sap-ha, rhel-8-6-sap-ha, rhel-8-8-sap-ha		^1
Debian 9(Stretch)
Debian 10(Buster)
Debian 11(Bullseye)
Ubuntu LTS 18.04(Bionic Beaver): ubuntu-1804-lts, ubuntu-minimal-1804-lts
Ubuntu LTS 20.04(Focal Fossa): ubuntu-2004-lts, ubuntu-minimal-2004-lts
Ubuntu LTS 22.04(Jammy Jellyfish): ubuntu-2204-lts, ubuntu-minimal-2204-lts
SLES 12: sles-12, sles-12-sp5-sap
SLES 15: sles-15, sles-15-sp2-sap, sles-15-sp3-sap, sles-15-sp4-sap, sles-15-sp5-sap
OpenSUSE Leap 15: opensuse-leap(opensuse-leap-15-3-*, opensuse-leap-15-4-*)
Windows Server: 2016, 2019, 2022, Core 2016, Core 2019, Core 2022

¹ Monitoring 에이전트는 rhel-7-9-sap-ha, rhel-8-2-sap-ha, rhel-8-4-sap-ha에서 지원되지 않습니다.

에이전트 정책 만들기

Google Cloud CLI를 사용하여 에이전트 정책을 만들려면 다음 단계를 수행합니다.

1. 아직 Google Cloud CLI를 설치하지 않았다면 설치합니다.

   이 문서에서는 에이전트 정책 관리를 위한 beta 명령어 그룹에 대해 설명합니다.

2. 아직 수행하지 않았으면 gcloud CLI의 beta 구성요소를 설치합니다.

   gcloud components install beta
   

   설치된 beta 구성요소가 있는지 확인하려면 다음을 실행합니다.

   gcloud components list
   

   이전에 beta 구성요소를 설치했으면 최신 버전인지 확인합니다.

   gcloud components update
   

3. 다음 스크립트를 사용하여 API를 사용 설정하고 Google Cloud CLI를 사용하기 위한 적절한 권한을 설정합니다. set-permissions.sh

   스크립트에 대한 자세한 내용은 set-permissions.sh 스크립트는 어떤 기능을 하나요?를 참조하세요.

   참고: set-permissions.sh 스크립트는 Linux에서 실행하도록 설계되었습니다. 다른 운영체제에서 머신을 사용하는 경우 Cloud Shell에서 스크립트를 실행하세요.

4. gcloud beta compute instances ops-agents policies create 명령어를 사용하여 정책을 만듭니다. 명령어 구문은 gcloud beta compute instances ops-agents policies create 문서를 참조하세요.

   명령어 형식을 지정하는 방법을 보여주는 예시는 Google Cloud CLI 문서에서 예시 섹션을 참조하세요.

   명령어 그룹에서 다른 명령어 및 사용 가능한 옵션에 대한 자세한 내용은 gcloud beta compute instances ops-agents policies 문서를 참조하세요.

에이전트 정책 사용 권장사항

출시 중에 프로덕션 시스템에 미치는 영향을 제어하려면 인스턴스 라벨과 영역을 사용하여 정책이 적용되는 인스턴스를 필터링하는 것이 좋습니다.

운영 에이전트의 정책을 만드는 경우 VM에 기존 Logging 에이전트나 Monitoring 에이전트가 설치되어 있지 않은지 확인합니다. 같은 VM에서 운영 에이전트와 기존 에이전트가 실행되면 중복 로그가 수집되거나 측정항목 수집 시 충돌이 발생할 수 있습니다. 필요한 경우 운영 에이전트를 설치하는 정책을 만들기 전에 Monitoring 에이전트를 제거하고 Logging 에이전트를 제거합니다.

다음은 my_project라는 프로젝트에서 CentOS 7 VM에 대한 단계별 출시 계획 예시입니다.

1단계: env=test 및 app=myproduct 라벨을 사용해서 모든 VM에 운영 에이전트를 설치하는 ops-agents-policy-safe-rollout이라는 정책을 만듭니다.

gcloud beta compute instances \
    ops-agents policies create ops-agents-policy-safe-rollout \
    --agent-rules="type=ops-agent,version=current-major,package-state=installed,enable-autoupgrade=true" \
    --os-types=short-name=centos,version=7 \
    --group-labels=env=test,app=myproduct \
    --project=my_project

운영체제 지정에 대한 자세한 내용은 gcloud beta compute instances ops-agents policies create를 참조하세요.

2단계: 단일 영역에서 env=prod 및 app=myproduct 라벨이 있는 VM을 대상으로 지정하도록 정책을 업데이트합니다.

gcloud beta compute instances \
    ops-agents policies update ops-agents-policy-safe-rollout \
    --group-labels=env=prod,app=myproduct \
    --zones=us-central1-c \

3단계: 정책 업데이트를 통해 영역 필터를 삭제하여 전 세계적으로 출시되도록 합니다.

gcloud beta compute instances \
    ops-agents policies update ops-agents-policy-safe-rollout \
    --clear-zones

제한사항

OS 구성보다 먼저 VM에 정책을 적용하려면 정책이 신뢰하는 OS 구성 에이전트가 VM에 설치되도록 추가 설정을 해야 합니다. VM Fleet에 OS 구성 에이전트를 설치하려면 다음 단계를 완료하세요.

1. 에이전트 정책 만들기 섹션에서 set-permissions.sh 스크립트를 실행했는지 확인합니다.

2. OS 구성 에이전트를 설치하려는 VM을 식별하고 이를 CSV 파일로 나열합니다. 예를 들어 Google Kubernetes Engine, App Engine, 기타 Google Cloud 서비스에서 관리되지 않는 VM 목록을 가져와서 instances.csv라는 파일에 저장하려면 다음 명령어를 실행합니다.

     gcloud compute instances list \
         --filter="-labels.list(show="keys"):goog-" \
         --format="csv(name,zone)" \
         | grep -v -x -F -f  <(gcloud compute instances os-inventory list-instances \
             --format="csv(name,zone)") \
         | sed 's/$/,update/' > instances.csv
   

   grep 섹션은 이미 OS 구성 에이전트가 설치되고 사용 설정된 VM을 필터링합니다. goog-을 기반으로 하는 VM 라벨 제외는 GKE, App Engine, 기타 서비스에서 관리되는 Compute Engine VM을 필터링하여 제외합니다.

   영역 또는 라벨별로 인스턴스를 더 자세히 필터링하려면 --filter 플래그의 값을 다음과 비슷한 항목으로 변경합니다.

     "-labels.list(show="keys"):goog- AND zone:(ZONE_1,ZONE_2) AND labels.KEY_1:VALUE_1 AND labels.KEY_2=VALUE_2"
   

3. Linux VM에 OS 구성 에이전트를 설치하려면 mass-install-osconfig-agent.sh 스크립트를 실행합니다.

   참고: OS 구성 에이전트 설치 명령을 자동화하는 mass-install-osconfig-agent.sh 스크립트는 Linux VM에만 OS 구성 에이전트를 설치할 수 있습니다. Windows VM을 사용하는 경우에는 설치 명령을 수동으로 실행합니다.

   다음 명령어는 지정된 프로젝트에서 instances.csv 파일에 지정된 VM에 OS 구성 에이전트를 설치합니다.

      bash mass-install-osconfig-agent.sh --project PROJECT_ID --input-file instances.csv
   

   스크립트 사용에 대한 자세한 내용은 해당 스크립트의 주석을 참조하세요.

문제 해결

ops-agents policy 명령어 실패

gcloud beta compute instances ops-agents policies 명령어가 실패하면 응답에 검증 오류가 표시됩니다. 오류 메시지에 제안된 대로 명령어 인수와 플래그를 수정하여 이러한 오류를 수정합니다.

검증 오류 외에도 다음과 같은 오류가 표시될 수 있습니다.

• IAM 권한 부족

  샘플 오류는 다음과 같습니다.

  ERROR: (gcloud.beta.compute.instances.ops-agents.policies.command) PERMISSION_DENIED: Caller does not have required permission to command
  

  에이전트 정책 만들기 섹션에서 set-permissions.sh 스크립트를 실행하여 osconfig.guestPolicy 관련 IAM 역할을 설정합니다.

  다음 명령어를 실행하면 프로젝트에 OS 구성 게스트 정책 역할이 충분히 설정되어 있는지 확인할 수 있습니다. 이 예시에서 명령어는 사용자에게 roles/osconfig.guestPolicyAdmin 역할이 있는지 확인합니다. GCLOUD_MEMBER 값은 user:USER_EMAIL 또는 serviceaccount:SERVICE_ACCOUNT_EMAIL 형식이어야 합니다.

  gcloud projects get-iam-policy PROJECT_ID \
      --filter=--member=GCLOUD_MEMBER \
      | grep "roles/osconfig.guestPolicyAdmin" -B 2
  

  예상되는 출력은 다음과 같습니다.

  - members:
    - GCLOUD_MEMBER
    role: roles/osconfig.guestPolicyAdmin
  

• OS 구성 API가 사용 설정되지 않음

  샘플 오류는 다음과 같습니다.

  API [osconfig.googleapis.com] not enabled on project PROJECT_ID.
  Would you like to enable and retry (this will take a few minutes)?
  (y/N)?
  

  에이전트 정책 만들기 섹션에서 set-permissions.sh 스크립트를 실행하여 필요한 모든 권한을 부여해야 합니다.

  다음 명령어를 실행하여 OS Config API가 프로젝트에 사용 설정되었는지 확인할 수 있습니다.

  gcloud services list --project PROJECT_ID \
      | grep osconfig.googleapis.com
  

  예상되는 출력은 다음과 같습니다.

  osconfig.googleapis.com    Cloud OS Config API
  

• 정책이 존재하지 않음

  샘플 오류는 다음과 같습니다.

  NOT_FOUND: Requested entity was not found
  

  이는 정책이 이미 삭제되었음을 나타냅니다. describe, update 또는 delete 명령어의 정책 ID가 기존 정책에 매핑되는지 확인합니다.

정책이 생성되었으나 효과가 없음

OS 구성 에이전트는 각 Compute Engine 인스턴스에 배포되어 Logging 및 Monitoring 에이전트의 패키지를 관리합니다. 기본 OS 구성 에이전트가 설치되지 않은 경우 정책이 아무런 효과가 없는 것처럼 보일 수 있습니다.

LINUX

OS 구성 에이전트가 설치되었는지 확인하려면 다음 명령어를 실행합니다.

gcloud compute ssh instance-id \
    --project project-id \
    -- sudo systemctl status google-osconfig-agent

샘플 출력은 다음과 같습니다.

    google-osconfig-agent.service - Google OSConfig Agent
    Loaded: loaded (/lib/systemd/system/google-osconfig-agent.service; enabled; vendor preset:
    Active: active (running) since Wed 2020-01-15 00:14:22 UTC; 6min ago
    Main PID: 369 (google_osconfig)
     Tasks: 8 (limit: 4374)
    Memory: 102.7M
    CGroup: /system.slice/google-osconfig-agent.service
            └─369 /usr/bin/google_osconfig_agent

WINDOWS

OS 구성 에이전트가 설치되었는지 확인하려면 다음 단계를 실행합니다.

1. RDP 또는 유사한 도구를 사용하여 인스턴스에 연결하고 Windows에 로그인합니다.

2. PowerShell 터미널을 열고 다음 PowerShell 명령어를 실행하세요. 관리자 권한은 필요하지 않습니다.

   Get-Service google_osconfig_agent
   

샘플 출력은 다음과 같습니다.

    Status   Name               DisplayName
    ------   ----               -----------
    Running  google_osconfig_a… Google OSConfig Agent

SUSE 및 Ubuntu Compute Engine 인스턴스에는 OS 구성 에이전트가 사전 설치되어 있지 않으므로 OS 구성 에이전트 설치 안내에 따라 OS 구성 에이전트를 해당 Compute Engine 인스턴스에 설치해야 합니다.

OS 구성 에이전트가 설치되어 있지만 운영 에이전트는 설치되지 않음

OS 구성 에이전트의 로그를 확인하여 OS 구성 에이전트가 정책을 적용할 때 오류가 있는지 확인할 수 있습니다. 로그 탐색기나 SSH 또는 RDP를 사용해서 이 작업을 수행하여 개별 Compute Engine 인스턴스를 확인할 수 있습니다.

로그 탐색기에서 OS 구성 에이전트 로그를 보려면 다음 필터를 사용하세요.

resource.type="gce_instance"
logName="projects/PROJECT_ID/logs/OSConfigAgent"

개별 Compute Engine Linux 인스턴스에 대해 SSH를 사용해서 OS 구성 에이전트 로그를 보려면 다음 명령어를 실행합니다.

• CentOS / RHEL / SLES / SUSE

  gcloud compute ssh INSTANCE_ID \
      --project PROJECT_ID \
      -- sudo cat /var/log/messages \
         | grep "OSConfigAgent\|google-fluentd\|stackdriver-agent"
  

• Debian / Ubuntu

  gcloud compute ssh INSTANCE_ID \
      --project PROJECT_ID \
      -- sudo cat /var/log/syslog \
         | grep "OSConfigAgent\|google-fluentd\|stackdriver-agent"
  

개별 Compute Engine Windows 인스턴스에 대한 RDP를 사용하여 OS 구성 에이전트 로그를 보려면 다음 단계를 실행합니다.

1. RDP 또는 유사한 도구를 사용하여 인스턴스에 연결하고 Windows에 로그인합니다.

2. Event Viewer 앱을 열고 Windows Logs => Application에서 Source가 OSConfigAgent인 로그를 검색합니다.

OS 구성 서비스에 연결하는 데 오류가 발생하면 에이전트 정책 만들기 섹션에서 set-permissions.sh 스크립트를 실행하여 메타데이터를 설정해야 합니다.

다음 명령어를 실행하면 OS 구성 메타데이터가 사용 설정되었는지 확인할 수 있습니다.

gcloud compute project-info describe \
    --project PROJECT_ID \
    | grep "enable-osconfig\|enable-guest-attributes" -A 1

예상되는 출력은 다음과 같습니다.

- key: enable-guest-attributes
  value: 'TRUE'
- key: enable-osconfig
  value: 'TRUE'

관측 가능성 에이전트가 설치되었지만 제대로 작동하지 않음

특정 에이전트 디버깅에 대한 자세한 내용은 다음 문서를 참조하세요.

• 운영 에이전트 문제 해결
• 기존 Logging 에이전트 문제 해결
• 기존 Monitoring 에이전트 문제 해결

OS 구성 에이전트에 대한 디버그 수준 로그 사용 설정

문제를 보고할 때는 OS 구성 에이전트에서 디버그 수준 로깅을 사용 설정하는 것이 유용할 수 있습니다.

osconfig-log-level: debug 메타데이터를 설정하여 OS 구성 에이전트에 디버그 수준 로깅을 사용 설정할 수 있습니다. 수집된 로그에는 조사에 도움이 되는 추가 정보가 있습니다.

전체 프로젝트에 디버그 수준 로깅을 사용 설정하려면 다음 명령어를 실행합니다.

gcloud compute project-info add-metadata \
    --project PROJECT_ID \
    --metadata osconfig-log-level=debug

VM 하나의 디버그 수준 로깅을 사용 설정하려면 다음 명령어를 실행합니다.

gcloud compute instances add-metadata INSTANCE_ID \
    --project PROJECT_ID \
    --metadata osconfig-log-level=debug

set-permissions.sh 스크립트는 어떤 기능을 하나요?

프로젝트 ID, Identity and Access Management(IAM) 역할, 이메일 또는 서비스 계정이 주어지면 set-permissions.sh 스크립트는 다음 작업을 수행합니다.

• 프로젝트의 Cloud Logging API, Cloud Monitoring API, OS Config API가 사용 설정됩니다.

• Compute Engine 기본 서비스 계정에 roles/logging.logWriter 및 roles/monitoring.metricWriter 역할을 부여하여 에이전트가 Logging 및 Cloud Monitoring API에 로그와 측정항목을 작성할 수 있도록 합니다.

• OS 구성 에이전트가 VM에서 활성화되도록 프로젝트의 OS 구성 메타데이터를 사용 설정합니다.

• 지정된 IAM 역할을 gcloud 사용자 또는 서비스 계정에 부여합니다. 프로젝트 소유자에게는 정책을 만들고 관리할 수 있는 전체 액세스 권한이 있습니다. 다른 모든 사용자 또는 서비스 계정의 경우 프로젝트 소유자가 다음 역할 중 하나를 부여해야 합니다.

  • roles/osconfig.guestPolicyAdmin: 정책에 대한 전체 액세스 권한을 제공합니다.

  • roles/osconfig.guestPolicyEditor: 사용자가 정책을 가져오고 업데이트하고 나열할 수 있도록 합니다.

  • roles/osconfig.guestPolicyViewer: 정책을 가져오고 나열할 수 있는 읽기 전용 액세스 권한을 제공합니다.

  스크립트를 실행할 때 역할 이름의 guestPolicy* 부분만 지정하면 됩니다. 스크립트가 이름의 roles/osconfig. 부분을 제공합니다.

다음 스크립트 호출은 API를 사용 설정하고, 기본 서비스 계정에 필요한 역할을 부여하고, OS 구성 메타데이터를 사용 설정합니다.

bash set-permissions.sh --project=PROJECT_ID

스크립트를 사용하여 프로젝트에 대한 roles/owner(소유자) 역할이 없는 사용자에게 OS 구성 역할 중 하나를 부여하려면 다음과 같이 스크립트를 실행합니다.

bash set-permissions.sh --project=PROJECT_ID \
  --iam-user=USER_EMAIL \
  --iam-permission-role=guestPolicy[Admin|Editor|Viewer]

스크립트를 사용하여 OS 구성 역할 중 하나를 기본이 아닌 서비스 계정에 부여하려면 다음과 같이 스크립트를 실행합니다.

bash set-permissions.sh --project=PROJECT_ID \
  --iam-service-account=SERVICE_ACCT_EMAIL \
  --iam-permission-role=guestPolicy[Admin|Editor|Viewer]

자세한 내용은 스크립트 내용을 참조하세요.

diagnose.sh 스크립트는 어떤 기능을 하나요?

프로젝트, Compute Engine 인스턴스 ID, 운영 에이전트 정책 ID가 주어지면 diagnose.sh 스크립트는 정책의 문제를 진단하는 데 필요한 정보를 자동으로 수집합니다.

• OS 구성 에이전트 버전

• 기본 OS 구성 게스트 정책

• 이 Compute Engine 인스턴스에 적용되는 정책

• Compute Engine 인스턴스로 가져오는 에이전트 패키지 저장소

Terraform 통합

Terraform 지원은 Google Cloud CLI 명령어를 기반으로 합니다. Terraform을 사용하여 에이전트 정책을 만들려면 Terraform 모듈 안내를 따르세요.