Spostare i bucket

Questa pagina descrive la procedura per spostare i bucket da una posizione all'altra. Per informazioni sullo spostamento dei bucket, consulta Spostamento dei bucket.

Prima di iniziare

Prima di avviare la procedura di spostamento del bucket, completa i seguenti passaggi:

  1. Attiva l'hub di gestione.

  2. Attiva l'eliminazione temporanea.

  3. Controlla le quote e i limiti per assicurarti che la nuova posizione disponga di quote sufficienti per contenere i dati del bucket.

  4. Determina il tipo di spostamento del bucket per capire se è necessario un tempo di riposo per le scritture.

  5. Rimuovi eventuali tag bucket esistenti.

  6. Se utilizzi i report sull'inventario, salva le configurazioni.

Ruoli obbligatori

Per ottenere le autorizzazioni per spostare i bucket da una posizione all'altra, chiedi all'amministratore di concederti il ruolo Amministratore archiviazione (roles/storage.admin) per il progetto.

Questo ruolo fornisce un insieme di autorizzazioni che ti consentono di spostare i bucket da una posizione all'altra. Per visualizzare le autorizzazioni esatte richieste, espandi la sezione Autorizzazioni richieste:

Autorizzazioni obbligatorie

Per utilizzare questo metodo, l'utente autenticato deve disporre delle seguenti autorizzazioni IAM sul bucket:

  • storage.buckets.relocate
  • storage.bucketOperations.get
    Questa autorizzazione è necessaria per visualizzare lo stato dell'operazione di spostamento del bucket.
  • storage.bucketOperations.list
    Questa autorizzazione è necessaria per visualizzare l'elenco delle operazioni di spostamento dei bucket.
  • storage.bucketOperations.cancel
    Questa autorizzazione è necessaria per annullare l'operazione di spostamento del bucket.

Per utilizzare questo metodo, l'utente autenticato potrebbe anche aver bisogno delle seguenti autorizzazioni sul bucket:

  • storage.bucket.get
    Questa autorizzazione è necessaria per visualizzare i metadati di un bucket durante il simulacro e la copia incrementale dei dati dell'operazione di spostamento del bucket.
  • storage.objects.list e storage.objects.get
    Queste autorizzazioni sono necessarie per visualizzare l'elenco di oggetti in un bucket che vuoi spostare in un'altra posizione.

Puoi anche ottenere queste autorizzazioni con ruoli personalizzati o potresti riuscire a ottenere queste autorizzazioni con altri ruoli predefiniti. Per sapere quali ruoli sono associati a quali autorizzazioni, consulta la sezione Ruoli IAM per Cloud Storage.

Per istruzioni su come concedere i ruoli per i progetti, consulta Gestire l'accesso ai progetti.

Spostare i bucket

Questa sezione descrive la procedura di spostamento dei bucket Cloud Storage da una posizione all'altra con lo spostamento dei bucket. Quando sposti un bucket, avvii il processo di copia incrementale dei dati, lo monitori e poi avvia il passaggio di sincronizzazione finale. Per ulteriori informazioni su questi passaggi, consulta Informazioni sulla procedura di spostamento dei bucket.

Esegui una prova

Per ridurre al minimo i potenziali problemi durante la procedura di scambio del bucket, ti consigliamo di eseguire un dry run. Un dry run simula il processo di trasferimento dei bucket senza spostare i dati, aiutandoti a rilevare e risolvere i problemi in anticipo. La prova dry run verifica le seguenti incompatibilità:

Sebbene una simulazione non possa identificare tutti i possibili problemi, in quanto alcuni potrebbero verificarsi solo durante la migrazione in produzione a causa di fattori quali la disponibilità delle risorse in tempo reale, riduce il rischio di riscontrare problemi che richiedono molto tempo durante il trasferimento effettivo.

Riga di comando

Simula il dry run dello spostamento del bucket:

gcloud storage buckets relocate gs://BUCKET_NAME --location=LOCATION --dry-run

Dove:

  • BUCKET_NAME è il nome del bucket che vuoi spostare.

  • LOCATION è la posizione di destinazione del separato.

L'avvio di un dry run avvia un'operazione a lunga esecuzione. Riceverai un ID operazione e una descrizione dell'operazione. Per monitorare il completamento della prova, devi monitorarne l'avanzamento. Per informazioni su come monitorare l'avanzamento della simulazione, vedi Ottenere i dettagli di un'operazione che richiede molto tempo.

Se la prova indica la presenza di problemi, risolvili prima di procedere con il passaggio Avvia la copia incrementale dei dati.

API REST

API JSON

  1. Avere installato e inizializzatogcloud CLI, che consente di generare un token di accesso per l'intestazione Authorization.

  2. Crea un file JSON contenente le impostazioni per il bucket, che deve includere i parametri destinationLocation e validateOnly. Consulta la documentazione di Buckets: relocate per un elenco completo delle impostazioni. Di seguito sono riportate le impostazioni comuni da includere:

    {
  "destinationLocation": "DESTINATION_LOCATION",
  "destinationCustomPlacementConfig": {
      "dataLocations": [
        LOCATIONS,
        ...
        ]
    },
  "validateOnly": "true"
}

    Dove:

    • DESTINATION_LOCATION è la posizione di destinazione del bucket.
    • LOCATIONS è un elenco di codici posizione da utilizzare per la regione a due configurabili.
    • validateOnly è impostato su true per eseguire una prova.

  3. Utilizza cURL per chiamare l'API JSON:

    curl -X POST --data-binary @JSON_FILE_NAME \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 "https://storage.googleapis.com/storage/v1/b/bucket=BUCKET_NAME/relocate"

    Dove:

    • JSON_FILE_NAME è il nome del file JSON che hai creato.
    • BUCKET_NAME è il nome del bucket che vuoi spostare.

Avvia la copia incrementale dei dati

Riga di comando

Avvia l'operazione di spostamento del bucket:

gcloud storage buckets relocate gs://BUCKET_NAME --location=LOCATION

Dove:

  • BUCKET_NAME è il nome del bucket che vuoi spostare.

  • LOCATION è la posizione di destinazione del separato.

API REST

API JSON

  1. Avere installato e inizializzatogcloud CLI, che consente di generare un token di accesso per l'intestazione Authorization.

  2. Crea un file JSON contenente le impostazioni per il bucket. Consulta la documentazione di Buckets: relocate per un elenco completo delle impostazioni. Di seguito sono riportate le impostazioni comuni da includere:

    {
  "destinationLocation": "DESTINATION_LOCATION",
  "destinationCustomPlacementConfig": {
      "dataLocations": [
        LOCATIONS,
        ...
        ]
    },
  "validateOnly": "false"
}

    Dove:

    • DESTINATION_LOCATION è la posizione di destinazione del bucket.
    • LOCATIONS è un elenco di codici posizione da utilizzare per la regione a due configurabili.
    • validateOnly è impostato su false per avviare il passaggio di copia dei dati incrementali del trasferimento del bucket.

  3. Utilizza cURL per chiamare l'API JSON:

    curl -X POST --data-binary @JSON_FILE_NAME \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 "https://storage.googleapis.com/storage/v1/b/bucket=BUCKET_NAME/relocate"

    Dove:

    • JSON_FILE_NAME è il nome del file JSON che hai creato.
    • BUCKET_NAME è il nome del bucket che vuoi spostare.

Monitorare la copia incrementale dei dati

Il processo di scambio del bucket è un'operazione di lunga durata che deve essere monitorata per verificarne l'avanzamento. Puoi controllare regolarmente l'elenco delle operazioni che richiedono molto tempo per visualizzare lo stato del passaggio di copia dei dati incrementali. Per informazioni su come visualizzare i dettagli di un'operazione a lunga esecuzione, elencare o annullare le operazioni a lunga esecuzione, consulta Utilizzare le operazioni a lunga esecuzione in Cloud Storage.

L'esempio seguente mostra l'output generato da un'operazione di copia incrementale dei dati:

done: false
kind: storage#operation
metadata:
'@type': type.googleapis.com/google.storage.control.v2.RelocateBucketMetadata
commonMetadata:
  createTime: '2024-10-21T04:26:59.666Z
  endTime: '2024-12-29T23:39:53.340Z'
  progressPercent: 99
  requestedCancellation: false
  type: relocate-bucket
  updateTime: '2024-10-21T04:27:03.2892'
destinationLocation: US-CENTRAL1
finalizationState: 'READY'
progress:
  byteProgressPercent: 100
  discoveredBytes: 200
  remainingBytes: 0
  discoveredObjectCount: 10
  remainingObjectCount: 8
  objectProgressPercent: 100
  discoveredSyncCount: 8
  remainingSyncCount: 0
  syncProgressPercent: 100
relocationState: SYNCING
sourceLocation: US
validateOnly: false
writeDowntimeExpireTime: '2024-12-30T10:34:01.786Z'
name: projects//buckets/my-bucket1/operations/Bar7-1b0khdew@nhenUQRTF_R-Kk4dQ5V1f8fzezkFcPh3XMvlTqJ6xhnqJ1h_QXFIeAirrEqkjgu4zPKSRD6WSSG5UGXil6w
response:
  '@type': type.googleapis.com/google.storage.control.v2.RelocateBucketResponse
  selfLink: https://storage.googleusercontent.com/storage/v1_ds/b/my-bucket1/operations/Bar7-1b0khdew@nhenUQRTF_R-Kk4dQ5V1f8fzezkFcPh3XMvlTqJ6xhnqJ1h_QXFIeAirrEqkjgu4zPKSRD6WSSG5UGXil6w

La seguente tabella fornisce informazioni sui campi chiave nell'output generato dall'operazione di copia dei dati incrementali:

Nome campo Descrizione Valori possibili
done Indica il completamento dell'operazione di spostamento del bucket. true, false
kind Indica che questa risorsa rappresenta un'operazione di archiviazione.
metadata Fornisce informazioni sull'operazione.
metadata.@type Indica il tipo di operazione come spostamento del bucket.
metadata.commonMetadata Metadati comuni a tutte le operazioni.
metadata.commonMetadata.createTime L'ora in cui è stata creata l'operazione a lunga esecuzione.
metadata.commonMetadata.endTime L'ora in cui è terminata l'operazione a lunga esecuzione.
metadata.commonMetadata.progressPercent L'avanzamento stimato dell'operazione a lunga esecuzione, in percentuale. Tra 0 e 100%. Un valore -1 indica che l'avanzamento è sconosciuto o non applicabile.
metadata.commonMetadata.requestedCancellation Indica se l'utente ha richiesto l'annullamento dell'operazione di lunga durata. true, false
metadata.commonMetadata.type Indica il tipo di operazione a lungo termine.
metadata.commonMetadata.updateTime L'ora dell'ultimo aggiornamento dell'operazione a lunga esecuzione.
metadata.destinationLocation La posizione di destinazione del bucket.
metadata.finalizationState Indica l'idoneità per avviare il passaggio di sincronizzazione finale.
  • READY: indica che puoi avviare il passaggio finale della sincronizzazione. Tuttavia, ti consigliamo di attendere fino a quando il valore del campo progressPercent non raggiunge 99.
  • WAITING_ON_SYNC: indica che non puoi avviare il passaggio di sincronizzazione finale.
  • NOT_REQUIRED: indica che il passaggio di sincronizzazione finale non è necessario per questo bucket e puoi saltarlo.
  • BLOCKED_ON_ERRORS: indica che il passaggio di finalizzazione è temporaneamente in pausa a causa di errori. Per continuare con il passaggio, dovrai risolvere gli errori.
  • RUNNING: indica che il passaggio di finalizzazione è in corso.
  • FINALIZED: indica che il passaggio di finalizzazione è stato completato correttamente.
metadata.progress Dettagli sull'avanzamento dell'operazione di trasferimento.
metadata.progress.byteProgressPercent Avanzamento dei byte copiati in percentuale. Tra 0 e 100%. Un valore -1 indica che l'avanzamento è sconosciuto o non applicabile.
metadata.progress.discoveredBytes Numero di byte rilevati nel bucket di origine.
metadata.progress.discoveredObjectCount Numero di oggetti rilevati nel bucket di origine.
metadata.progress.discoveredSyncCount Numero di aggiornamenti dei metadati degli oggetti rilevati nel bucket di origine.
metadata.progress.objectProgressPercent Avanzamento della copia degli oggetti in percentuale. Tra 0 e 100%. Un valore -1 indica che l'avanzamento è sconosciuto o non applicabile.
metadata.progress.remainingBytes Numero di byte rimanenti da copiare dal bucket di origine al bucket di destinazione.
metadata.progress.remainingObjectCount Numero di oggetti rimanenti da copiare dal bucket di origine al bucket di destinazione.
metadata.progress.remainingSyncCount Numero di aggiornamenti dei metadati degli oggetti rimanenti da sincronizzare.
metadata.progress.syncProgressPercent Aggiornamento dei metadati degli oggetti da sincronizzare in percentuale. Tra 0 e 100%. Un valore -1 indica che l'avanzamento è sconosciuto o non applicabile.
metadata.relocationState Stato complessivo dello spostamento del bucket
  • SYNCING: indica che il passaggio di copia dei dati incrementali sta copiando attivamente gli oggetti dal bucket di origine al bucket di destinazione.
  • FINALIZING: indica che è stato avviato il passaggio di finalizzazione.
  • FAILED: indica che il passaggio di copia dei dati incrementali ha rilevato un errore e non è stato completato correttamente.
  • SUCCEEDED: indica che il passaggio di copia dei dati incrementali è stato completato correttamente.
  • CANCELLED: indica che il passaggio di copia dei dati incrementali è stato annullato.
metadata.sourceLocation La posizione di origine del bucket.
metadata.validateOnly Indica se è stato avviato un simulacro del trasferimento del bucket. true, false
metadata.writeDowntimeExpireTime L'ora in cui scade il tempo di riposo per le scritture.
name L'identificatore univoco di questa operazione di trasferimento.
Formato: projects/_/buckets/bucket-name/operations/operation-id
response La risposta dell'operazione.
response.@type Il tipo di risposta.
selfLink Un link a questa operazione.

Potresti riscontrare problemi a causa delle limitazioni quando interagisci con altre funzionalità di Cloud Storage. Per ulteriori informazioni sulle limitazioni, vedi Limitazioni.

Avvia il passaggio di sincronizzazione finale

Il passaggio di sincronizzazione finale prevede un periodo durante il quale non puoi eseguire operazioni di scrittura sul bucket. Ti consigliamo di pianificare il passaggio di sincronizzazione finale in un momento che riduca al minimo l'interruzione delle applicazioni.

Prima di procedere, verifica che il bucket sia completamente preparato controllando il valore finalizationState nell'output del passaggio Monitora la procedura di copia dei dati incrementali. Per procedere con il passaggio di sincronizzazione finale, il valore finalizationState deve essere READY.

Se avvii prematuramente il passaggio di sincronizzazione finale, il comando restituisce un messaggio di errore The relocate bucket operation is not ready to advance to finalization running state, ma il processo di scambio continua.

Ti consigliamo di attendere fino a quando il valore progressPercent non sarà 99 prima di avviare il passaggio di sincronizzazione finale.

Riga di comando

Avvia il passaggio di sincronizzazione finale dell'operazione di trasferimento del bucket quando il valore finalizationState è READY:

gcloud storage buckets relocate --finalize --operation=projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

Dove:

  • BUCKET_NAME è il nome del bucket che vuoi spostare.
  • OPERATION_ID è l'ID dell'operazione a lunga esecuzione, restituito nella risposta dei metodi chiamati. Ad esempio, la seguente risposta viene restituita dall'istruzione gcloud storage operations list e l'ID operazione a lunga esecuzione è AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74.
 `name: projects/_/buckets/my-bucket/operations/AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74`

Imposta il flag ttl per avere un maggiore controllo sulla procedura di trasferimento. Ad esempio:

gcloud storage buckets relocate --finalize --ttl TTL_DURATION --operation=projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

Dove:

TTL_DURATION è la durata (TTL) per la fase di interruzione del servizio di scrittura durante un processo di trasferimento. È espresso come stringa, come 12h per 12 ore. TTL_DURATION determina la durata massima consentita per la fase di interruzione della scrittura. Se il tempo di riposo in scrittura supera questo limite, il processo di scambio torna automaticamente al passaggio di copia incrementale e le operazioni di scrittura nel bucket vengono riattivate. Il valore deve rientrare nell'intervallo da 6h (6 ore) a 48h (48 ore). Se non specificato, il valore predefinito è 12h (12 ore).

API REST

API JSON

  1. Avere installato e inizializzatogcloud CLI, che consente di generare un token di accesso per l'intestazione Authorization.

  2. Crea un file JSON contenente le impostazioni per il trasferimento del bucket. Consulta la documentazione di Buckets: advanceRelocateBucket per un elenco completo delle impostazioni. Di seguito sono riportate le impostazioni comuni da includere:

    {
    "expireTime": "EXPIRE_TIME",
    "ttl": "TTL_DURATION"
}

    Dove:

    • EXPIRE_TIME è l'ora in cui scade il tempo di riposo per le scritture.
    • TTL_DURATION è la durata (TTL) per la fase di interruzione del servizio di scrittura durante un processo di trasferimento. È espresso come stringa, come 12h per 12 ore. TTL_DURATION determina la durata massima consentita per la fase di interruzione della scrittura. Se il tempo di riposo in scrittura supera questo limite, il processo di scambio torna automaticamente al passaggio di copia incrementale e le operazioni di scrittura nel bucket vengono riattivate. Il valore deve rientrare nell'intervallo da 6h (6 ore) a 48h (48 ore). Se non specificato, il valore predefinito è 12h (12 ore).

  3. Utilizza cURL per chiamare l'API JSON:

    curl -X POST --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/bucket/BUCKET_NAME/operations/OPERATION_ID/advanceRelocateBucket"

    Dove:

    • JSON_FILE_NAME è il nome del file JSON che hai creato.
    • BUCKET_NAME è il nome del bucket che vuoi spostare.
    • OPERATION_ID è l'ID dell'operazione a lunga esecuzione, restituito nella risposta dei metodi chiamati. Ad esempio, la seguente risposta viene restituita dall'istruzione Operations: list e l'ID operazione a lunga esecuzione è AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74.

Convalida la procedura di spostamento del bucket

Dopo aver avviato un trasferimento, verifica che sia stato completato correttamente. Questa sezione fornisce indicazioni per verificare il trasferimento riuscito dei dati.

Verifica l'esito positivo della procedura di trasferimento utilizzando i seguenti metodi:

  • Esegui il polling delle operazioni a lunga esecuzione: il trasferimento dei bucket è un'operazione a lunga esecuzione. Puoi eseguire il polling dell'operazione a tempo lungo utilizzando operation id per monitorarne l'avanzamento e confermarne il completamento verificando lo stato success. Ciò comporta l'esecuzione di query periodiche sullo stato dell'operazione fino a quando non raggiunge uno stato finale. Per informazioni sul monitoraggio delle operazioni a lungo termine, consulta Utilizzare le operazioni a lungo termine in Cloud Storage.

  • Analizza le voci di Cloud Audit Logs: Cloud Audit Logs fornisce un record dettagliato di eventi e operazioni nel tuo Google Cloud ambiente. Puoi analizzare le voci di Cloud Audit Logs associate al trasferimento per verificarne il successo. Analizza i log per rilevare eventuali errori, avvisi o comportamenti imprevisti che potrebbero indicare problemi durante il trasferimento. Per informazioni su come visualizzare gli audit log di Cloud, consulta Visualizzazione degli audit log.

    Le seguenti voci di log ti aiutano a determinare se il trasferimento è riuscito o meno:

    • Spostamento riuscito: Relocate bucket succeeded. All existing objects are now in the new placement configuration.

    • Spostamento non riuscito: Relocate bucket has failed. Bucket location remains unchanged.

    Utilizzando le notifiche Pub/Sub, puoi anche configurare avvisi che ti inviano una notifica quando viene visualizzato l'evento di successo o di errore specifico nei log. Per informazioni sulla configurazione delle notifiche Pub/Sub, consulta Configurare le notifiche Pub/Sub per Cloud Storage.

Completa le attività di spostamento del bucket post

Dopo aver spostato correttamente il bucket, completa i seguenti passaggi:

  1. (Facoltativo) Ripristina eventuali controlli dell'accesso basati su tag nel bucket.
  2. Le configurazioni esistenti dei report sull'inventario non vengono conservate durante la procedura di trasferimento e dovrai ricrearle manualmente. Per informazioni sulla creazione di una configurazione di report dell'inventario, consulta Creare una configurazione di report dell'inventario.
  3. Aggiorna le configurazioni di Infrastructure as Code, come Terraform e il connettore di configurazione di Google Kubernetes Engine, per specificare la nuova posizione del bucket.
  4. Gli endpoint regionali sono legati a località specifiche e dovrai modificare il codice dell'applicazione in modo che rifletta il nuovo endpoint.

Come gestire le operazioni di spostamento del bucket non riuscite

Prima di gestire le operazioni di trasferimento dei bucket non riuscite, considera i seguenti fattori:

  • Se lo spostamento di un bucket non va a buon fine, nella destinazione potrebbero rimanere risorse obsolete, ad esempio file temporanei o copie di dati incomplete. Devi attendere da 7 a 14 giorni prima di avviare un altro trasferimento del bucket nella stessa destinazione. Puoi avviare immediatamente il trasferimento di un bucket in un'altra destinazione.

  • Se la posizione di destinazione non è ottimale per i tuoi dati, potresti eseguire il rollback del trasferimento. Tuttavia, non puoi avviare immediatamente un trasferimento. È necessario un periodo di attesa di massimo 14 giorni prima di poter avviare nuovamente la procedura di trasferimento. Questa limitazione è in vigore per garantire la stabilità e prevenire conflitti di dati.

Passaggi successivi