에이전트 정책 사용(베타)

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

에이전트 정책 만들기

이 섹션에서는 Google Cloud SDK를 사용하여 에이전트 정책을 관리하는 방법을 설명합니다. Terraform 사용에 관한 자세한 내용은 Terraform 통합을 참조하세요.

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 스크립트를 참조하세요.

  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라는 프로젝트의 Debian 11 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=debian,version=11 \
    --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에는 OS 구성 에이전트를 수동으로 설치하고 구성해야 할 수 있습니다. OS 구성 에이전트를 수동으로 설치하고 확인하는 방법에 대한 자세한 내용은 VM Manager 확인 체크리스트를 참조하세요.

베타 에이전트 정책 문제 해결

이 섹션에서는 운영 에이전트, 기존 모니터링 에이전트, 기존 로깅 에이전트의 베타 에이전트 정책 문제를 해결하는 데 도움이 되는 정보를 제공합니다.

ops-agents policy 명령어 실패

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

검증 오류 외에도 다음 조건을 나타내는 오류가 표시될 수 있습니다.

다음 섹션에서는 이러한 조건을 자세히 설명합니다.

IAM 권한 부족

gcloud beta compute instances ops-agents policies 권한 오류와 함께 명령어가 실패하면set-permissions.sh 스크립트를 에이전트 정책 만들기에 설명된 대로 실행했는지 확인합니다.

set-permissions.sh 스크립트에 관한 자세한 내용은 set-permissions.sh 스크립트를 참고하세요.

OS Config 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)?

y를 입력하여 API를 사용 설정하거나 에이전트 정책 만들기에 설명된 대로 set-permissions.sh 스크립트를 실행하여 필요한 모든 권한을 부여합니다. 오류 메시지의 프롬프트에서 y를 입력해도 set-permissions.sh 스크립트를 실행하여 필요한 권한을 설정해야 합니다.

프로젝트에 OS Config API가 사용 설정되었는지 확인하려면 다음 명령어를 실행합니다.

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

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

osconfig.googleapis.com    Cloud OS Config API

정책이 이미 존재함

샘플 오류는 다음과 같이 표시됩니다.

ALREADY_EXISTS: Requested entity already exists

이 오류는 동일한 이름, 프로젝트 ID, 리전으로 이 정책이 이미 존재함을 의미합니다. gcloud beta compute instances ops-agents policies describe 명령어를 사용하여 이를 확인할 수 있습니다.

정책이 존재하지 않음

샘플 오류는 다음과 같이 표시됩니다.

NOT_FOUND: Requested entity was not found

이 오류는 정책이 생성되지 않았거나, 정책이 삭제되었거나, 지정된 정책 ID가 잘못되었음을 의미할 수 있습니다. gcloud beta compute instances ops-agents policies describe, update 또는 delete 명령어에 사용된 POLICY_ID가 기존 정책에 해당하는지 확인합니다. 에이전트 정책 목록을 가져오려면 gcloud beta compute instances ops-agents policies list 명령어를 사용하세요.

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

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

OS 구성 에이전트가 설치되어 있지 않다면 VM Manager를 지원하지 않는 운영체제를 사용 중일 수 있습니다. Compute Engine 운영체제 세부정보 문서에 각 Compute Engine 운영체제에서 지원되는 VM Manager 기능이 나와 있습니다.

운영체제에서 VM Manager를 지원하는 경우 OS 구성 에이전트를 수동으로 설치할 수 있습니다.

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

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

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

resource.type="gce_instance"
logId(OSConfigAgent)

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"

Windows

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

  2. 이벤트 뷰어 앱을 열고 Windows 로그 > 애플리케이션을 선택하고 Source가 OSConfigAgent인 로그를 검색합니다.

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

다음 명령어를 실행하면 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'

Observability 에이전트가 설치되었지만 제대로 작동하지 않음

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

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 스크립트

set-permissions.sh 스크립트를 다운로드한 후 사용자가 제공한 인수를 기반으로 스크립트를 사용하여 다음 작업을 수행할 수 있습니다.

다음 예시에서는 스크립트에 대한 몇 가지 일반적인 호출을 보여줍니다. 자세한 내용은 스크립트 자체의 주석을 참고하세요.

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 스크립트

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

  • OS 구성 에이전트 버전
  • 기본 OS 구성 게스트 정책
  • 이 Compute Engine 인스턴스에 적용되는 정책
  • 이 Compute Engine 인스턴스로 가져오는 에이전트 패키지 저장소

스크립트를 호출하려면 다음 명령어를 실행합니다.

bash diagnose.sh --project-id=PROJECT_ID \ 
  --gce-instance-id=INSTANCE_ID \
  --policy-id=POLICY_ID

Terraform 통합

Terraform 구성을 적용하거나 삭제하는 방법은 기본 Terraform 명령어를 참조하세요. Terraform 작동 방식에 대한 자세한 내용은 Terraform 사용하기를 참조하세요.

에이전트 정책에 대한 Terraform 지원은 Google Cloud CLI 명령어를 기반으로 합니다. Terraform을 사용하여 에이전트 정책을 만들려면 Terraform 모듈 agent-policy 안내를 따르세요. examples 디렉터리에서도 정책 예시를 확인할 수 있습니다.