Observability Analytics를 사용하도록 버킷 업그레이드 문제 해결

Observability Analytics를 사용하도록 로그 버킷을 업그레이드하면 SQL 쿼리를 실행하여 해당 버킷에 저장된 로그 데이터를 분석할 수 있습니다. 로그 버킷 업그레이드가 실패하거나 중단되면 이 문서를 사용하여 동기식 검증 오류, 비동기식 프로비저닝 오류, 차단된 작업을 진단하고 해결할 수 있습니다. 로그 버킷을 업그레이드하는 방법에 대한 자세한 내용은 Observability Analytics를 사용하도록 버킷 업그레이드를 참조하세요.

업그레이드 프로세스 정보

Cloud Logging은 Observability Analytics를 사용하도록 로그 버킷을 업그레이드하는 명령어를 실행할 때 2단계 프로세스를 사용합니다.

  1. 동기 검증: Logging은 명령어 매개변수를 검증합니다. 검증이 실패하면 명령어가 즉시 오류를 반환합니다.
  2. 비동기 프로비저닝: 검증에 성공하면 Logging은 일반적으로 10분 이내에 완료되는 장기 실행 작업을 시작합니다.

로그 버킷 업그레이드는 감사 대상 작업입니다. 장기 실행 작업의 상태를 확인하거나 오류 세부정보를 찾으려면 Operations.GetOperation 메서드를 사용하여 작업을 폴링하거나 감사 로그를 쿼리하면 됩니다.

업그레이드 중 로그 버킷 상태

업그레이드 요청의 동기 검증이 성공하면 Logging은 로그 버킷의 상태를 ACTIVE에서 UPDATING로 변경하고 장기 실행 작업을 시작합니다. 작업이 완료되면 로그 버킷 상태가 ACTIVE로 돌아갑니다.

gcloud logging buckets describe 명령어를 실행하여 로그 버킷의 현재 상태를 확인할 수 있습니다.

gcloud logging buckets describe LOG_BUCKET_ID \
  --location=LOCATION_ID \
  --project=PROJECT_ID

명령어를 실행하기 전에 다음을 바꿉니다.

  • PROJECT_ID: 프로젝트의 ID입니다.
  • LOCATION_ID: 버킷의 위치입니다.
  • LOG_BUCKET_ID: 버킷의 ID입니다.

응답의 lifecycleState 필드에 버킷 상태가 표시됩니다.

description: Default bucket
lifecycleState: ACTIVE
name: projects/PROJECT_ID/locations/LOCATION_ID/buckets/LOG_BUCKET_ID
retentionDays: 30

Google Cloud 콘솔에서 로그 버킷이 UPDATING 상태인 동안 다음을 수행합니다.

  • 로그 스토리지 페이지에서 장기 실행 작업이 활성 상태인 동안 Observability Analytics 사용 가능 열에 업그레이드 중…이 표시됩니다 (또는 콘솔에서 작업 상태를 검색할 수 없는 경우 업그레이드할 수 없음).
  • 버킷 수정 패널과 로그 버킷 업그레이드 패널에서 버킷을 업그레이드하는 옵션이 사용 중지되고 도움말에 충족되지 않은 요구사항으로 대기 중인 업데이트가 없음이 표시됩니다.

VPC 서비스 제어 경계 고려사항

VPC 서비스 제어 경계 내의 로그 버킷 업그레이드는 경계에 의해 API가 차단되거나 프로젝트 간 구성으로 인해 실패할 수 있습니다.

경계에서 허용해야 하는 API

VPC 서비스 제어 경계 내에 있는 로그 버킷을 업그레이드하려면 경계가 다음 서비스를 제한하지 않아야 합니다.

  • logging.googleapis.com
  • cloudkms.googleapis.com: 고객 관리 암호화 키 (CMEK)를 사용하는 로그 버킷을 업그레이드하는 데 필요합니다.

이러한 서비스를 제한하면 다음과 같은 동작이 발생합니다.

  • logging.googleapis.com 제한됨: 업그레이드 명령어가 PERMISSION_DENIED 오류와 함께 즉시 실패하고 로그 버킷이 ACTIVE 상태로 유지됩니다.

    해결 방법: 이 섹션의 시작 부분에 나열된 API를 허용하도록 경계를 업데이트한 후 명령어를 다시 시도합니다.

  • cloudkms.googleapis.com 제한됨: CMEK로 보호되는 로그 버킷의 경우 장기 실행 작업이 INTERNAL 오류와 함께 실패하고 로그 버킷이 ACTIVE 상태로 돌아갑니다.

    해결 방법: 이 섹션의 시작 부분에 나열된 API를 허용하도록 경계를 업데이트한 후 명령어를 다시 시도합니다.

경계 간 CMEK 구성

로그 버킷과 Cloud KMS 키가 서로 다른 VPC 서비스 제어 경계에 있는 경우 ID 기반 인그레스 또는 이그레스 규칙을 사용하여 Cloud Key Management Service 키에 대한 경계 간 액세스 권한을 부여할 수 없습니다.

이 구성의 경우 인그레스 규칙에서 Logging 서비스 계정 ID만 지정하면 다음이 발생합니다.

  • 비동기 프로비저닝이 INTERNAL 오류와 함께 실패하고 로그 버킷이 ACTIVE 상태로 돌아갑니다.
  • Cloud KMS 프로젝트의 정책 감사 로그에 실패가 기록됩니다. 이 감사 로그는 google.cloud.kms.v1.KeyManagementService.Encrypt 메서드가 NO_MATCHING_ACCESS_LEVEL 인그레스 위반으로 실패했으며 BigQuery 암호화 서비스 계정에 대한 것임을 보여줍니다.

해결 방법: Cloud KMS 경계에 대한 액세스를 허용하는 인그레스 규칙에서 identityType를 ANY_IDENTITY로 설정하고 로그 버킷이 포함된 프로젝트를 소스 리소스로 지정합니다.

- ingressFrom:
    identityType: ANY_IDENTITY
    sources:
    - resource: projects/PROJECT_NUMBER
  ingressTo:
    operations:
    - serviceName: cloudkms.googleapis.com
      methodSelectors:
      - method: '*'
    resources:
    - projects/KMS_PROJECT_NUMBER

앞의 예시에서 다음 변수를 바꿉니다.

  • PROJECT_NUMBER: 로그 버킷이 포함된 프로젝트의 프로젝트 번호입니다.
  • KMS_PROJECT_NUMBER: Cloud KMS 키가 포함된 프로젝트의 프로젝트 번호입니다.

이그레스 규칙도 지정하는 경우 identityType: ANY_IDENTITY도 설정해야 합니다.

감사 로그에서 실패 정보 쿼리

이 섹션의 쿼리를 사용하면 로그 버킷을 업데이트하거나 업그레이드할 때 실패를 보고하는 로그 항목을 찾을 수 있습니다. 이러한 쿼리는 로그 탐색기에서 사용됩니다.

Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.

로그 탐색기로 이동

검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.

프로젝트에서 실패한 모든 버킷 업데이트 또는 업그레이드 쿼리

log_id("cloudaudit.googleapis.com/activity")
protoPayload.serviceName="logging.googleapis.com"
(protoPayload.methodName="google.logging.v2.ConfigServiceV2.UpdateBucket" OR
 protoPayload.methodName="google.logging.v2.ConfigServiceV2.UpdateBucketAsync")
severity=ERROR

Google Cloud 콘솔을 사용하여 Observability Analytics를 사용하도록 로그 버킷을 업그레이드하고 연결된 BigQuery 데이터 세트를 만드는 경우 다음 쿼리를 사용합니다.

log_id("cloudaudit.googleapis.com/activity")
(protoPayload.serviceName="logging.googleapis.com" OR
 protoPayload.serviceName="bigquery.googleapis.com")
(protoPayload.methodName="google.logging.v2.ConfigServiceV2.UpdateBucket" OR
 protoPayload.methodName="google.logging.v2.ConfigServiceV2.UpdateBucketAsync" OR
 protoPayload.methodName="google.cloud.bigquery.v2.DatasetService.InsertDataset")
severity=ERROR

이전 쿼리 결과에는 연결된 BigQuery 데이터 세트 생성이 실패했음을 나타내는 로그 항목이 포함됩니다. 오류 메시지는 실패 원인을 해결하는 데 도움이 될 수 있습니다.

특정 버킷의 실패한 버킷 업데이트 또는 업그레이드 쿼리

다음 쿼리를 사용하기 전에 다음을 바꿉니다.

  • PROJECT_ID: 프로젝트의 ID입니다.
  • LOCATION_ID: 버킷의 위치입니다.
  • LOG_BUCKET_ID: 버킷의 ID입니다.
log_id("cloudaudit.googleapis.com/activity")
protoPayload.serviceName="logging.googleapis.com"
(protoPayload.methodName="google.logging.v2.ConfigServiceV2.UpdateBucket" OR
 protoPayload.methodName="google.logging.v2.ConfigServiceV2.UpdateBucketAsync")
protoPayload.resourceName="projects/PROJECT_ID/locations/LOCATION_ID/buckets/LOG_BUCKET_ID"
severity=ERROR

장기 실행 작업 실패 쿼리

log_id("cloudaudit.googleapis.com/activity")
protoPayload.serviceName="logging.googleapis.com"
protoPayload.methodName="google.logging.v2.ConfigServiceV2.UpdateBucketAsync"
operation.last=true
severity=ERROR

INVALID_ARGUMENT (3)

INVALID_ARGUMENT (3) 오류 코드와 함께 제공되는 오류 메시지에는 오류를 해결하는 데 충분한 정보가 포함되어 있습니다. 따라서 이 섹션에서는 가능한 모든 오류 메시지를 열거하지 않습니다.

리소스 이름 문제

리소스 이름 문제를 해결하려면 projects/PROJECT_ID/locations/LOCATION_ID/buckets/LOG_BUCKET_ID 형식의 유효한 버킷 리소스 이름을 전달합니다.

리소스 이름 길이가 길이 제한 내에 있는지 확인합니다.

업데이트 마스크 문제

update_mask 또는 Update mask 텍스트가 포함된 오류 메시지는 값이 누락되었거나 잘못된 형식임을 나타냅니다.

이 문제를 해결하려면 API 명령어에서 update_mask를 지정하고 값을 "analytics_enabled"로 설정합니다.

로그 버킷 자격 요건 문제

  • 잠긴 _Default 로그 버킷 또는 잠긴 커스텀 버킷은 업그레이드할 수 없습니다. _Required 버킷이 잠겨 있는 동안 업그레이드할 수 있습니다.

    로그 버킷이 잠겨 있으면 오류 메시지는 "Bucket is not eligible for an upgrade to enable analytics"입니다.

    이 오류를 해결하려면 분석이 사용 설정된 새 버킷을 만들고 로그를 이 버킷으로 라우팅합니다.

  • 버킷을 다른 방식으로 변경하는 동시에 로그 버킷을 업그레이드할 수 없습니다. 예를 들어 로그 버킷을 업그레이드하고 버킷 설명을 업데이트할 수 없습니다.

    이 오류를 해결하려면 update_mask에 analytics_enabled만 포함된 별도의 UpdateBucket 또는 UpdateBucketAsync 요청을 전송하고 별도의 요청으로 다른 로그 버킷 필드를 업데이트합니다.

  • 조직, 폴더 또는 결제 계정의 로그 버킷은 업그레이드할 수 없습니다. 상위 요소가 Google Cloud 프로젝트인 로그 버킷만 업그레이드할 수 있습니다.

  • 이미 업그레이드되었거나 업그레이드 중인 로그 버킷은 업그레이드할 수 없습니다.

    GetBucket 또는 ListOperations를 사용하여 업그레이드가 이미 완료되었는지 또는 진행 중인지 확인합니다.

Cloud KMS 키 문제

오류 메시지:

  • "Not a valid key reference (wrong type): 'KMS_KEY_NAME'"
  • "Name "KMS_KEY_NAME" is missing the COMPONENT component. Expected the form projects/[PROJECT_ID]/locations/[ID]/keyRings/[ID]/cryptoKeys/[ID]"

해결 방법: 버킷을 업그레이드하기 전에 로그 버킷의 cmek_settings.kms_key_name를 유효한 Cloud KMS CryptoKey 리소스 이름으로 업데이트합니다. 키 버전 CryptoKeyVersion이 아닌 리소스 이름을 업데이트해야 합니다.

잘못된 인수 메시지

"Request contains an invalid argument." 메시지가 표시되면 CMEK 사용 설정 로그 버킷에 대해 다음을 시도합니다.

  • 버킷의 CMEK 구성과 연결된 Logging 서비스 계정이 초기화되었는지 확인합니다.
  • 버킷에 양수 보관 기간이 있는지 확인합니다.

서비스 계정 이름을 찾으려면 로그 버킷, 위치, 프로젝트 ID를 업데이트한 후 다음 명령어를 실행합니다.

gcloud logging buckets describe LOG_BUCKET_ID --location=LOCATION_ID --project=PROJECT_ID

서비스 계정은 프로젝트, 폴더 또는 조직에 있을 수 있습니다.

DEADLINE_EXCEEDED (4)

UpdateBucketAsync를 사용하고 Operations.GetOperation 메서드를 사용하여 반환된 장기 실행 작업을 폴링하거나 백그라운드 업그레이드가 완료된 후 GetBucket를 호출합니다.

NOT_FOUND (5)

이러한 오류를 해결하려면 다음을 시도합니다.

  • 프로젝트 ID 또는 프로젝트 번호가 올바르고 프로젝트가 활성 상태인지 확인합니다. 프로젝트가 삭제 대기 중인 경우 먼저 프로젝트를 복원합니다.
  • 지정된 위치가 Logging에서 지원되는지 확인합니다.
  • 로그 버킷 ID와 위치가 프로젝트에 있고 대상 버킷이 _CloudTrace가 아닌지 확인합니다.

PERMISSION_DENIED (7)

권한 거부 오류는 요청된 작업이 허용되지 않음을 나타냅니다.

사용자 권한 누락

로그 버킷을 업그레이드하려면 호출자에게 logging.buckets.update 권한 (예: roles/logging.configWriter 또는 roles/logging.admin)이 포함된 Identity and Access Management (IAM) 역할이 있는지 확인하고 커스텀 조직 정책이 업데이트를 차단하지 않는지 확인합니다.

조직 정책 제한사항

"Request is prohibited by organization's policy. vpcServiceControlsUniqueIdentifier: [ID]" 오류 메시지를 해결하려면 VPC 서비스 제어 경계가 logging.googleapis.com 서비스를 제한하지 않는지 확인합니다. 자세한 내용은 VPC 서비스 제어 경계 고려사항을 참조하세요.

리전 엔드포인트 문제

리전 엔드포인트가 지정된 경우 권한 거부 오류를 해결하려면 전역 엔드포인트 (logging.googleapis.com) 또는 로그 버킷의 위치와 일치하는 리전 엔드포인트로 요청을 전송합니다.

RESOURCE_EXHAUSTED (8)

이 오류를 해결하려면 진행 중인 프로비저닝 작업이 완료될 때까지 기다린 후 지수 백오프로 다시 시도합니다.

FAILED_PRECONDITION (9)

이러한 오류를 해결하려면 다음을 시도합니다.

  • 로그 버킷이 ACTIVE 상태인지 확인합니다. 삭제 중이거나 업데이트 또는 프로비저닝 작업이 진행 중인 로그 버킷은 업그레이드할 수 없습니다.

    로그 버킷 상태를 확인하는 방법은 업그레이드 중 로그 버킷 상태를 참조하세요.

  • 잠긴 로그 버킷은 업그레이드할 수 없습니다.

  • 일반 메시지 "Precondition check failed."은 버킷 상태가 ACTIVE가 아님을 나타냅니다. 진행 중인 작업이 완료될 때까지 기다린 후 업그레이드를 다시 시도합니다.

INTERNAL (13)

오류 메시지:

  • 장기 실행 작업 (Operations.GetOperation): "Failed to create analytics enabled bucket."
  • Cloud 감사 로그 및 동기식 UpdateBucket: "Internal error encountered."

해결 방법: 다음을 시도해 보세요.

  • CMEK 사용 설정 로그 버킷의 경우 Cloud KMS 키가 사용 설정되어 있고, 버킷의 CMEK 구성과 연결된 Logging 서비스 계정에 키에 대한 roles/cloudkms.cryptoKeyEncrypterDecrypter 역할이 있고, BigQuery에서 키에 액세스할 수 있고, 조직 정책 또는 VPC 서비스 제어 경계가 Cloud KMS 액세스를 차단하지 않는지 확인합니다.

    서비스 계정 이름을 찾으려면 다음 명령어를 실행합니다.

    gcloud logging buckets describe LOG_BUCKET_ID --location=LOCATION_ID --project=PROJECT_ID

    서비스 계정은 프로젝트, 폴더 또는 조직에 있을 수 있습니다.

  • 버킷 (logging.views.list)의 기존 로그 뷰를 검사하여 필터가 유효한지 확인하고 버킷 업그레이드를 다시 시도하세요.

  • 로그 버킷이 삭제되지 않았는지 (DELETE_REQUESTED), 버킷에서 충돌하는 관리 작업이 발생하지 않는지 확인한 후 업그레이드를 다시 시도합니다.

  • 일시적인 BigQuery 스토리지 데이터 세트 또는 검색 색인 생성 오류가 해결되거나 다운스트림 BigQuery, Cloud KMS 또는 프로비저닝 서비스 가용성이 복원된 후 로그 버킷 업그레이드를 다시 시도하세요. 실패가 지속되면 Cloud Customer Care에 문의하세요.

UNAVAILABLE (14)

"The service is currently unavailable." 메시지가 표시되면 지수 백오프로 UpdateBucketAsync 요청을 다시 시도합니다.