Aggiorna i bucket di osservabilità

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

Non puoi utilizzare queste operazioni di aggiornamento per risolvere i problemi di conformità. Ad esempio, non puoi utilizzare queste operazioni per modificare la posizione di un bucket di osservabilità o applicare una chiave Cloud KMS a un bucket che utilizza la crittografia predefinita di Google.

Effetti dell'aggiornamento di una chiave Cloud KMS

L'aggiornamento della chiave Cloud KMS per un bucket di osservabilità non influisce sui dati archiviati. ovvero, 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 ai dati archiviati e visualizzarli a condizione che la chiave Cloud KMS originale rimanga abilitata e che il account di servizio Google Cloud Observability mantenga le autorizzazioni di crittografia/decrittografia.

Se disabiliti 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 posizione.
  • 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 superare i 1000 byte codificati.
  • I dati vengono archiviati per 30 giorni. Puoi omettere il periodo di conservazione o impostarlo su 30.
  • Se aggiorni la chiave Cloud KMS, la posizione della chiave deve corrispondere esattamente alla posizione 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. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.

  2. 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

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

  4. 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

  5. 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

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

  7. 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

    8.

  8. Per ottenere le autorizzazioni necessarie per aggiornare i bucket di osservabilità, chiedi all'amministratore di concederti il ruolo IAM Editor osservabilità (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 interfacce

gcloud

Nella console Google Cloud , attiva Cloud Shell.

Attiva Cloud Shell

Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

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. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  3. Se utilizzi una shell locale, crea le credenziali di autenticazione locali per il tuo account utente: 

    gcloud auth application-default login

    Non è necessario eseguire questa operazione se utilizzi Cloud Shell.

    Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver acceduto 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.

    Se utilizzi un provider di identità (IdP) esterno, devi prima accedere 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.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo dei servizi (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 comando seguente:

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

    La risposta al comando precedente elenca l'ID del account di servizio 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.iam.gserviceaccount.com \
--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: l'identificatore alfanumerico univoco, composto dal nome del tuo progetto 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 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. È formattato nel seguente modo: projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY.

Aggiorna un bucket di osservabilità

gcloud

Non supportati.

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 posizione del bucket di osservabilità. Per saperne di più, vedi 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 ogni campo specificato 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, il completamento di 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 è 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à.

Questa sezione descrive come elencare i bucket di osservabilità. Un bucket di osservabilità è l'entità di gestione per i set di dati, che archiviano i dati.

gcloud

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

  • LOCATION: la posizione dei bucket di osservabilità. Per elencare tutti i bucket osservabilità, indipendentemente dalla località, imposta la località su un trattino (-).
  • PROJECT_ID: L'identificatore del progetto.

Esegui il comando gcloud beta observability buckets list:

Linux, macOS o 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

La risposta elenca il nome, la descrizione e l'ora di creazione di ogni bucket di osservabilità. Di seguito è riportato un esempio di risposta quando il comando ha esito positivo: 

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

Terraform

Non puoi utilizzare Terraform per elencare i bucket di osservabilità.

REST

Per elencare i bucket di osservabilità presenti nel tuo progetto e in una località specifica, utilizza il metodo projects.locations.buckets.list.

Devi specificare il parametro padre, che ha il seguente formato:

projects/PROJECT_ID/locations/LOCATION

I campi nell'espressione precedente hanno i seguenti significati:

  • PROJECT_ID: l'identificatore del progetto.
  • LOCATION: la posizione del bucket di osservabilità. Se imposti LOCATION su un trattino (-), vengono elencati tutti i bucket osservabilità nel tuo progetto.

La risposta è un array di oggetti Bucket. Per ogni oggetto, il valore del campo name ha il seguente formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

Di seguito è riportato un esempio di risposta:

{
  "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
    }
  ]
}

Puoi utilizzare l'API Observability per ottenere maggiori informazioni sul bucket il cui ID è BUCKET_ID. Ad esempio, puoi elencare i set di dati nel bucket e le visualizzazioni e i link di ogni set di dati. Per saperne di più, consulta la documentazione di riferimento dell'API Observability.

Passaggi successivi