에이전트 정책 관리

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

지원되는 운영체제

다음 운영체제로 에이전트 정책을 Compute Engine 인스턴스에 적용할 수 있습니다.

Logging agent에이전트 유형 logging의 정책에 매핑됩니다. Monitoring agent에이전트 유형 metrics의 정책에 매핑됩니다. Ops Agent에이전트 유형 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-2-sap-ha, 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

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

에이전트 정책 만들기

Google Cloud CLI를 사용하여 에이전트 정책을 만들려면 다음 단계를 완료하세요.

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

    gcloud CLI에서 에이전트 정책 관리를 위한 명령어 그룹은 beta 출시 버전입니다.

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

    gcloud components install beta
    

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

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

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

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

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

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

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

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

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

다음은 CentOS 7 VM의 단계별 출시 계획의 예시입니다.

1단계: env=testapp=myproduct 라벨로 모든 VM에 기존 Logging 에이전트 및 Monitoring 에이전트를 설치하는 정책을 만듭니다.

gcloud beta compute instances \
    ops-agents policies create ops-agents-policy-safe-rollout \
    --agent-rules="type=logging,version=current-major,package-state=installed,enable-autoupgrade=true;type=metrics,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, 단일 영역만 타겟팅하도록 정책을 업데이트합니다.

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에 OS 구성 에이전트를 설치하려면 다음 단계를 완료하세요.

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

  2. OS 구성 에이전트를 설치할 VM을 결정하고 CSV 파일에 나열합니다.

    Google에서 관리하지 않는(예: Google Kubernetes Engine 또는 Google App Engine에서 관리) 모든 인스턴스의 목록을 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"
    
  1. 스크립트의 안내에 따라 mass-install-osconfig-agent.sh 스크립트를 다운로드하고 실행하여 다음과 같은 명령어를 실행합니다.

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

    이 스크립트는 OS 구성 에이전트 설치 안내를 자동화합니다.

문제 해결

ops-agents 정책 명령어 실패

ops-agents 정책 명령어가 실패하면 해당 유효성 검사 오류가 표시됩니다. 오류 메시지에 제안된 대로 명령어 인수와 플래그를 수정하여 이러한 오류를 수정합니다.

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

  • IAM 권한 부족

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

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

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

    다음 명령어를 실행하면 프로젝트에 OS 구성 게스트 정책 역할이 충분히 설정되어 있는지 확인할 수 있습니다. 이 예시에서 명령어는 사용자에게 roles/osconfig.guestPolicyAdmin 역할이 있는지 확인합니다. GCLOUD_MEMBERuser: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
    
  • Osconfig API가 사용 설정되지 않음

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

    API [osconfig.googleapis.com] not enabled on project [XXX].
    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 구성 에이전트가 정책을 적용할 때 오류가 있는지 확인할 수 있습니다. 이 작업은 개별 Compute Engine 인스턴스로의 SSH / RDP를 통해, 또는 로그 탐색기를 통해 수행할 수 있습니다.

로그 탐색기에서 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에서 SourceOSConfigAgent인 로그를 검색합니다.

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 구성 에이전트의 디버그 수준 로깅을 사용 설정하면 매우 유용합니다.

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.logWriterroles/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 모듈 안내를 따르세요.