Aggiorna i bucket di osservabilità

Puoi aggiornare il nome visualizzato, la descrizione o la chiave di Cloud Key Management Service di un bucket di osservabilità per riflettere le modifiche organizzative o ruotare le chiavi di crittografia.

Se devi risolvere problemi di conformità, esegui nuovamente il provisioning del bucket di osservabilità. Un'operazione di nuovo provisioning consente di eseguire una delle seguenti operazioni:

  • Applica retroattivamente una chiave Cloud KMS a un bucket di osservabilità senza modificare la relativa località di archiviazione.
  • Modifica la località di archiviazione di un bucket di osservabilità e utilizza la crittografia predefinita di Google.
  • Modifica la località di archiviazione di un bucket di osservabilità e utilizza una chiave Cloud KMS per criptare i dati archiviati.

Per informazioni sul nuovo provisioning, consulta Correggi i requisiti di residenza dei dati e CMEK.

Effetti dell'aggiornamento di una chiave Cloud KMS

L'aggiornamento della chiave Cloud KMS per un bucket di osservabilità non influisce sui dati archiviati. In altre parole, prima del completamento dell'aggiornamento, la chiave originale cripta i nuovi dati. Al termine dell'aggiornamento, la chiave aggiornata cripta i nuovi dati.

Puoi continuare ad accedere e visualizzare i dati archiviati, a condizione che la chiave Cloud KMS originale rimanga abilitata e che l'account di servizio Google Cloud Observability mantenga le autorizzazioni di crittografia/decrittografia.

Se disattivi o elimini la chiave Cloud KMS originale, tutti i dati scritti mentre la chiave era attiva diventano immediatamente inaccessibili e illeggibili in modo permanente.

Limitazioni

Si applicano le seguenti limitazioni:

  • Non puoi modificare la località.
  • Non puoi applicare una chiave Cloud KMS a un bucket di osservabilità che utilizza la crittografia predefinita di Google.
  • Il nome visualizzato non deve superare i 100 byte codificati.
  • La descrizione non deve contenere più di 1000 byte codificati.
  • I dati rimangono archiviati per 30 giorni. Puoi omettere il periodo di conservazione o impostarlo su 30.
  • Se aggiorni la chiave Cloud KMS, la località della chiave deve corrispondere esattamente alla località principale del bucket di osservabilità.

Prima di iniziare

Configura il progetto e i ruoli IAM e seleziona l'interfaccia che prevedi di utilizzare.

Configura il progetto e i ruoli

  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, if it is not already enabled.

    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. Per ottenere le autorizzazioni necessarie per aggiornare i bucket di osservabilità, chiedi all'amministratore di concederti il ruolo IAM Observability Editor (roles/observability.editor) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

    Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Configura le interfacce

gcloud

Installa Google Cloud CLI, quindi accedi a gcloud CLI con la tua identità federata. Dopo aver eseguito l'accesso, inizializza Google Cloud CLI eseguendo il comando seguente: 

gcloud init

Terraform

Per utilizzare gli esempi di Terraform in questa pagina in un ambiente di sviluppo locale, installa e inizializza gcloud CLI, quindi configura Credenziali predefinite dell'applicazione con le tue credenziali utente.

  1. Installa Google Cloud CLI.

  2. Configura gcloud CLI per utilizzare la tua identità federata.

    Per saperne di più, consulta Accedi a gcloud CLI con la tua identità federata.

  3. Crea credenziali di autenticazione locali per il tuo account utente: 

    gcloud auth application-default login

    Se viene restituito un errore di autenticazione, verifica di aver eseguito l'accesso a gcloud CLI con la tua identità federata.

Per saperne di più, consulta Configura ADC per un ambiente di sviluppo locale nella documentazione sull'autenticazione di Google Cloud .

REST

Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizzi le credenziali che fornisci a gcloud CLI.

    Installa Google Cloud CLI, quindi accedi a gcloud CLI con la tua identità federata.

Per saperne di più, consulta Autenticati per usare REST nella documentazione sull'autenticazione di Google Cloud .

Configura la chiave Cloud KMS

Facoltativo. Se prevedi di aggiornare la chiave Cloud KMS utilizzata dal bucket di osservabilità, segui questi passaggi:

  1. Abilita l'API Cloud Key Management Service, se non è già abilitata.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilitare l'API

  2. Crea chiavi automatizzate e una chiave.

    La località del bucket di osservabilità deve corrispondere a quella della chiave.

  3. Sostituisci PROJECT_ID con l'ID del tuo progetto, quindi esegui il seguente comando:

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

    La risposta al comando precedente elenca l'ID del account di servizio di Google Cloud Observability.

  4. Concedi il ruolo Cloud KMS CryptoKey Encrypter/Decrypter al account di servizio Google Cloud Observability.

    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

    Prima di eseguire il comando precedente, effettua le seguenti sostituzioni:

    • KMS_PROJECT_ID Google Cloud e da un numero assegnato in modo casuale, del progetto Google Cloud che esegue Cloud KMS. Per informazioni su come ottenere questo identificatore, consulta Identificazione dei progetti.
    • service-PROJECT_NUMBER: il nome del service account di Google Cloud Observability elencato nel passaggio precedente.
    • KMS_KEY_LOCATION: la regione della chiave Cloud KMS.
    • KMS_KEY_RING: il nome delle chiavi automatizzate Cloud KMS.
    • KMS_KEY_NAME: il nome della chiave Cloud KMS. Il formato è il seguente: projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY.

Aggiorna un bucket di osservabilità

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • BUCKET_ID: l'ID del bucket di osservabilità. Ad esempio, questo ID potrebbe essere _Trace.
  • LOCATION: la località del bucket di osservabilità.
  • DESCRIPTION: una descrizione. Questo campo è facoltativo.
  • DISPLAY_NAME: il nome visualizzato. Questo campo è facoltativo.
  • PROJECT_ID: l'identificatore del progetto.

Il comando gcloud CLI fornisce anche opzioni per aggiornare la chiave Cloud KMS. Per saperne di più, consulta gcloud observability buckets update.

Esegui il comando gcloud observability buckets update:

Linux, macOS o Cloud Shell

gcloud observability buckets update BUCKET_ID \
 --location=LOCATION \
 --description="DESCRIPTION" \
 --display-name="DISPLAY_NAME" \
 --project=PROJECT_ID

Windows (PowerShell)

gcloud observability buckets update BUCKET_ID `
 --location=LOCATION `
 --description="DESCRIPTION" `
 --display-name="DISPLAY_NAME" `
 --project=PROJECT_ID

Windows (cmd.exe)

gcloud observability buckets update BUCKET_ID ^
 --location=LOCATION ^
 --description="DESCRIPTION" ^
 --display-name="DISPLAY_NAME" ^
 --project=PROJECT_ID

Il comando update avvia un'operazione a lunga esecuzione e si blocca fino al completamento dell'operazione. Di seguito è riportato un esempio di risposta quando il comando viene eseguito correttamente: 

Request issued for: [_Trace]
Waiting for operation [projects/my-project/locations/us/operations/operation-1790096940299-65c156c3d730f-5fbc9362-10d93b76] to complete...done.
Updated bucket [_Trace].
createTime: '2026-09-09T21:06:30.590367694Z'
description: Updated bucket for storing trace data
displayName: Updated display name
name: projects/my-project/locations/us/buckets/_Trace
updateTime: '2026-09-22T17:09:00.301850190Z'

Terraform

Per aggiornare il nome visualizzato, la descrizione o la CMEK, utilizza la risorsa Terraform google_observability_bucket e imposta i seguenti campi:

  • project: l'ID del progetto.
  • location: la località del bucket di osservabilità. Per saperne di più, consulta Località.
  • bucket_id: l'ID del bucket di osservabilità. Questo campo deve essere impostato su _Trace.

Puoi aggiornare solo la descrizione, il nome visualizzato e la CMEK. Per saperne di più, consulta la documentazione della risorsa.

REST

Per aggiornare un bucket di osservabilità, invia una richiesta a projects.locations.buckets.patch.

Devi specificare il parametro padre, che identifica il bucket da aggiornare. Questo parametro ha il seguente formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

I campi nell'espressione precedente hanno i seguenti significati:

Il parametro di query deve specificare un campo updateMask, che identifica i campi da modificare. Ad esempio:

  • Per aggiornare la descrizione, utilizza updateMask=description.
  • Per aggiornare la chiave Cloud KMS e la descrizione, utilizza updateMask=description,cmekSettings.kmsKey.

Il corpo della richiesta è un oggetto Bucket. Devi compilare tutti i campi specificati dalla maschera di aggiornamento. Non compilare i campi che non stai aggiornando.

Ad esempio, per aggiornare solo il campo description, puoi utilizzare il seguente oggetto Bucket:

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

La risposta è un oggetto Operation. In genere, questo metodo richiede meno di un minuto.

In genere, per determinare se un metodo che restituisce un oggetto Operation è completo, esegui il polling dell'oggetto chiamando projects.locations.operations.get finché il campo Operation.done non viene impostato su true. Puoi quindi utilizzare altri campi nella struttura Operation per determinare se il metodo è riuscito o meno.

Tuttavia, il metodo patch viene completato rapidamente. Pertanto, un'alternativa è attendere un minuto e poi verificare l'aggiornamento elencando i bucket di osservabilità.

Passaggi successivi