모니터링 가능성 버킷 업데이트

모니터링 가능성 버킷의 표시 이름, 설명 또는 Cloud Key Management Service 키를 업데이트하여 조직 변경사항을 반영하거나 암호화 키를 순환할 수 있습니다.

이러한 업데이트 작업은 규정 준수 문제를 해결하는 데 사용할 수 없습니다. 예를 들어 이러한 작업을 사용하여 모니터링 가능성 버킷의 위치를 변경하거나 Google 기본 암호화를 사용하는 버킷에 Cloud KMS 키를 적용할 수 없습니다.

Cloud KMS 키 업데이트의 효과

모니터링 가능성 버킷의 Cloud KMS 키를 업데이트해도 저장된 데이터에는 영향을 미치지 않습니다. 즉, 업데이트가 완료되기 전에 원래 키가 새 데이터를 암호화합니다. 업데이트가 완료되면 업데이트된 키가 새 데이터를 암호화합니다.

원래 Cloud KMS 키가 사용 설정되어 있고 Google Cloud Observability 서비스 계정이 암호화 생성기/복호화 생성기 권한을 유지하는 경우 저장된 데이터에 계속 액세스하고 볼 수 있습니다.

원래 Cloud KMS 키를 사용 중지하거나 폐기하면 해당 키가 활성 상태일 때 작성된 모든 데이터에 즉시 영구적으로 액세스할 수 없으며 읽을 수 없게 됩니다.

제한사항

다음 제한사항이 적용됩니다.

  • 위치를 수정할 수 없습니다.
  • Google 기본 암호화를 사용하는 모니터링 가능성 버킷에 Cloud KMS 키를 적용할 수 없습니다.
  • 표시 이름은 인코딩된 바이트 100자를 초과할 수 없습니다.
  • 설명은 인코딩된 바이트 1,000자를 초과할 수 없습니다.
  • 데이터는 30일 동안 저장됩니다. 보관 기간을 생략하거나 30으로 설정할 수 있습니다.
  • Cloud KMS 키를 업데이트하는 경우 키의 위치가 모니터링 가능성 버킷의 상위 위치와 정확히 일치해야 합니다.

시작하기 전에

프로젝트 및 IAM 역할을 구성하고 사용할 인터페이스를 선택합니다.

프로젝트 및 역할 구성

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. 모니터링 가능성 버킷을 만드는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 모니터링 가능성 편집자 (roles/observability.editor) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

    커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

인터페이스 구성

gcloud

Google Cloud CLI를 설치한 후 제휴 ID로 gcloud CLI에 로그인합니다. 로그인한 후 Google Cloud CLI를 초기화하려면 다음 명령어를 실행합니다. 

gcloud init

REST

로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공한 사용자 인증 정보를 사용합니다.

    Google Cloud CLI를 설치한 후 제휴 ID로 gcloud CLI에 로그인합니다.

자세한 내용은 인증 문서의 REST 사용을 위한 인증 을 참조하세요. Google Cloud

Cloud KMS 키 구성

선택사항입니다. 모니터링 가능성 버킷에서 사용하는 Cloud KMS 키를 업데이트하려는 경우 다음 단계를 따르세요.

  1. Cloud Key Management Service API를 사용 설정합니다.

    API 사용 설정에 필요한 역할

    API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한이 이미 있을 가능성이 높습니다. 그렇지 않으면 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할을 부여하는 방법을 알아보세요.

    API 사용 설정하기

  2. 키링 및 키 만들기.

    모니터링 가능성 버킷의 위치는 키의 위치와 일치해야 합니다.

  3. PROJECT_ID를 프로젝트의 ID로 바꾼 후 다음 명령어를 실행합니다.

    gcloud beta observability settings describe \
--location=global --project=PROJECT_ID

    이전 명령어에 대한 응답에는 Google Cloud Observability 서비스 계정의 ID가 나열됩니다.

  4. Google Cloud Observability 서비스 계정에 Cloud KMS CryptoKey 암호화/복호화 역할을 부여합니다.

    gcloud kms keys add-iam-policy-binding \
--project=KMS_PROJECT_ID \
--member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-observability. \
--role=roles/cloudkms.cryptoKeyEncrypterDecrypter \
--location=KMS_KEY_LOCATION \
--keyring=KMS_KEY_RING \
KMS_KEY_NAME

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

    • KMS_PROJECT_ID: Cloud KMS를 실행하는 프로젝트의 프로젝트 이름과 무작위로 할당된 숫자로 구성된 고유한 영숫자 식별자입니다. Google Cloud Google Cloud 이 식별자를 가져오는 방법에 대한 자세한 내용은 프로젝트 식별을 참조하세요.
    • service-PROJECT_NUMBER: 이전 단계에 나열된 Google Cloud Observability 서비스 계정의 이름입니다.
    • KMS_KEY_LOCATION: Cloud KMS 키 리전입니다.
    • KMS_KEY_RING: Cloud KMS 키링의 이름
    • KMS_KEY_NAME: Cloud KMS 키 이름. 다음과 같이 형식이 지정됩니다. projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY.

모니터링 가능성 버킷 업데이트

REST

모니터링 가능성 버킷을 업데이트하려면 projects.locations.buckets.patch에 요청을 보냅니다.

업데이트할 버킷을 식별하는 상위 매개변수를 지정해야 합니다. 이 매개변수의 형식은 다음과 같습니다.

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

이전 표현식의 필드는 다음과 같은 의미를 갖습니다.

  • PROJECT_ID: 프로젝트 식별자입니다.
  • LOCATION: 모니터링 가능성 버킷의 위치입니다.
  • BUCKET_ID: 모니터링 가능성 버킷의 ID입니다. 예를 들어 이 ID는 _Trace일 수 있습니다.

쿼리 매개변수는 수정할 필드를 식별하는 updateMask 필드를 지정해야 합니다. 예를 들면 다음과 같습니다.

  • 설명을 업데이트하려면 updateMask=description을 사용합니다.
  • Cloud KMS 키와 설명을 업데이트하려면 updateMask=description,cmekSettings.kmsKey를 사용합니다.

요청 본문은 Bucket 객체입니다. 업데이트 마스크로 지정된 모든 필드를 채워야 합니다. 업데이트하지 않는 필드는 채우지 마세요.

예를 들어 description 필드만 업데이트하려면 다음 Bucket 객체를 사용하면 됩니다.

{
    "description": "Updated description for my observability bucket."
}

응답은 Operation 객체입니다. 일반적으로 이 메서드는 완료하는 데 1분 미만이 걸립니다.

일반적으로 Operation 객체를 반환하는 메서드가 완료되었는지 확인하려면 projects.locations.operations.get을 호출하여 객체를 폴링합니다. Operation.done 필드가 true로 설정될 때까지 그런 다음 Operation 구조의 다른 필드를 사용하여 메서드가 성공했는지 실패했는지 확인할 수 있습니다.

하지만 patch 메서드는 빠르게 완료됩니다. 따라서 1분 정도 기다린 후 모니터링 가능성 버킷을 나열하여 업데이트를 확인하는 것이 좋습니다.

gcloud

아래의 명령어 데이터를 사용하기 전에, 다음을 바꿉니다.

  • LOCATION: 모니터링 가능성 버킷의 위치입니다. 위치와 관계없이 모든 모니터링 가능성 버킷을 나열하려면 위치를 하이픈 (-)으로 설정합니다.
  • PROJECT_ID: 프로젝트 식별자입니다.

gcloud beta observability buckets list 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud beta observability buckets list \
 --location=LOCATION --project=PROJECT_ID

Windows(PowerShell)

gcloud beta observability buckets list `
 --location=LOCATION --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets list ^
 --location=LOCATION --project=PROJECT_ID

응답에는 각 모니터링 가능성 버킷의 이름, 설명, 생성 시간이 나열됩니다. 다음은 명령어가 성공했을 때의 응답 예시입니다. 

---
createTime: '2026-01-21T21:39:22.381083860Z'
description: Bucket for storing spans from Cloud Trace.
name: projects/my-project/locations/us/buckets/_Trace

REST

프로젝트 및 특정 위치에 있는 모니터링 가능성 버킷을 나열하려면 projects.locations.buckets.list 엔드포인트에 요청을 보냅니다.

다음 형식의 상위 매개변수를 지정해야 합니다.

projects/PROJECT_ID/locations/LOCATION

이전 표현식의 필드는 다음과 같은 의미를 갖습니다.

  • PROJECT_ID: 프로젝트 식별자입니다.
  • LOCATION: 모니터링 가능성 버킷의 위치입니다. LOCATION을 하이픈 (-)으로 설정하면 프로젝트의 모든 모니터링 가능성 버킷 이 나열됩니다.

응답은 Bucket 객체의 배열입니다. 각 객체의 name 필드 값은 다음 형식을 갖습니다.

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

예를 들어 상위 매개변수가 projects/my-project/locations/us로 설정된 buckets.list 엔드포인트에 명령어가 실행되었을 때 응답은 다음과 같습니다.

{
  "buckets": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace",
      "description": "Trace Bucket",
      "createTime": "2025-01-01T15:42:30.988919645Z",
      "updateTime": "2025-02-04T15:42:30.988919645Z",
      "retentionDays": 30
    }
  ]
}

다른 Observability API 엔드포인트에 명령어를 실행하여 ID가 BUCKET_ID인 버킷에 대한 자세한 정보를 얻을 수 있습니다. 예를 들어 해당 버킷의 데이터 세트와 각 데이터 세트의 뷰 및 링크를 나열할 수 있습니다. Observability API 엔드포인트의 전체 목록은 Observability API 참조 문서를 확인하세요.

다음 단계