Déplacer des buckets

Cette page décrit la procédure à suivre pour déplacer des buckets d'un emplacement à un autre. Pour en savoir plus sur la relocalisation de buckets, consultez Relocalisation de buckets.

Avant de commencer

Avant de pouvoir déplacer des buckets, procédez comme suit :

  1. Configurer Storage Intelligence

  2. Activez la suppression réversible.

  3. Vérifiez les quotas et les limites pour vous assurer que le nouveau lieu dispose de quotas suffisants pour accueillir les données du bucket.

  4. Déterminez le type de relocalisation du bucket pour savoir si un temps d'arrêt en écriture est nécessaire.

  5. Supprimez tous les tags de bucket existants.

  6. Si vous utilisez des rapports d'inventaire, enregistrez vos configurations.

  7. Obtenez les rôles requis, décrits dans la section suivante.

Obtenir les rôles requis

Pour obtenir les autorisations nécessaires pour déplacer des buckets, demandez à votre administrateur de vous accorder le rôle IAM Administrateur de l'espace de stockage (roles/storage.admin) sur le projet. Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient les autorisations requises pour relocaliser des buckets. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour déplacer des buckets :

  • Pour relocaliser un bucket : storage.buckets.relocate
  • Pour afficher l'état d'une opération de déplacement de bucket : storage.bucketOperations.get
  • Pour afficher la liste des opérations de déplacement de buckets pour un projet : storage.bucketOperations.list
  • Pour annuler une opération de déplacement de bucket : storage.bucketOperations.cancel
  • Pour afficher les métadonnées d'un bucket pendant les phases de test et de copie incrémentielle des données de la migration du bucket : storage.buckets.get
  • Pour obtenir un objet dans un bucket que vous souhaitez déplacer : storage.objects.get
  • Pour répertorier les objets d'un bucket que vous souhaitez déplacer : storage.objects.list

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Relocaliser des buckets

Cette section décrit le processus de transfert de buckets Cloud Storage d'un emplacement à un autre. Lorsque vous déplacez un bucket, vous lancez le processus de copie incrémentielle des données, le surveillez, puis lancez l'étape de synchronisation finale. Pour en savoir plus sur ces étapes, consultez Comprendre le processus de relocalisation de buckets.

Effectuer une simulation

Pour minimiser les problèmes potentiels lors du processus de déplacement des buckets, nous vous recommandons d'effectuer un test à blanc. Un dry run simule le processus de migration de bucket sans déplacer les données. Il vous aide à identifier et à résoudre les problèmes en amont. La simulation vérifie les incompatibilités suivantes :

Bien qu'un test à blanc ne puisse pas identifier tous les problèmes potentiels (certains ne pouvant apparaître que lors de la migration à chaud en raison de facteurs tels que la disponibilité des ressources en temps réel), il réduit le risque de rencontrer des problèmes chronophages lors du transfert réel.

Ligne de commande

Simulez le dry run de la relocalisation du bucket :

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

Où :

  • BUCKET_NAME correspond au nom du bucket que vous souhaitez déplacer.

  • LOCATION est l'emplacement de destination du bucket.

Une fois que vous avez lancé une simulation, une opération de longue durée démarre. Vous recevrez un ID d'opération et une description de l'opération. Suivez la progression et l'achèvement du test à blanc en obtenant les détails de l'opération de longue durée.

Si le test à blanc révèle des problèmes, résolvez-les avant de passer à l'étape d'initialisation de la copie incrémentielle des données.

API REST

API JSON

  1. Vous devez installer et initialiser gcloud CLIafin de générer un jeton d'accès pour l'en-tête Authorization.

  2. Créez un fichier JSON contenant les paramètres du bucket, qui doit inclure les paramètres destinationLocation et validateOnly. Consultez la documentation Buckets: relocate pour obtenir la liste complète des paramètres. Les paramètres les plus courants sont les suivants :

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

    Où :

    • DESTINATION_LOCATION est l'emplacement de destination du bucket.
    • LOCATIONS est une liste de codes d'emplacement à utiliser pour l'emplacement birégional configurable.
    • validateOnly est défini sur true pour effectuer une simulation.

  3. Utilisez cURL pour appeler 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"

    Où :

    • JSON_FILE_NAME correspond au nom du fichier JSON que vous avez créé.
    • BUCKET_NAME correspond au nom du bucket que vous souhaitez déplacer.

    Une fois que vous avez lancé une simulation, une opération de longue durée démarre. Le dry run réussit lorsque les conditions suivantes sont remplies :

    • Le dry run ne signale aucune erreur.

    • La ressource operations renvoie une valeur de champ done de true.

      {
"kind": "storage#operation",
"name": "projects/_/buckets/bucket/operations/operation_id",
"metadata": {
  "@type": OperationMetadataType*,
  metadata OperationMetadata*
},
"done": "true",
"response": {
  "@type": ResponseResourceType*,
  response ResponseResource*
}
}

    Si le test à blanc révèle des problèmes, résolvez-les avant de passer à l'étape d'initialisation de la copie incrémentielle des données.

Lancer la copie incrémentielle des données

Ligne de commande

Lancez l'opération de relocalisation du bucket :

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

Où :

  • BUCKET_NAME correspond au nom du bucket que vous souhaitez déplacer.

  • LOCATION est l'emplacement de destination du bucket.

API REST

API JSON

  1. Vous devez installer et initialiser gcloud CLIafin de générer un jeton d'accès pour l'en-tête Authorization.

  2. Créez un fichier JSON contenant les paramètres du bucket. Consultez la documentation Buckets: relocate pour obtenir la liste complète des paramètres. Les paramètres les plus courants sont les suivants :

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

    Où :

    • DESTINATION_LOCATION est l'emplacement de destination du bucket.
    • LOCATIONS est une liste de codes d'emplacement à utiliser pour l'emplacement birégional configurable.
    • validateOnly est défini sur false pour lancer l'étape de copie incrémentielle des données de la relocalisation du bucket.

  3. Utilisez cURL pour appeler 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"

    Où :

    • JSON_FILE_NAME correspond au nom du fichier JSON que vous avez créé.
    • BUCKET_NAME correspond au nom du bucket que vous souhaitez déplacer.

Surveiller la copie incrémentielle des données

Le processus de transfert de bucket est une opération de longue durée qui doit être surveillée pour suivre sa progression. Vous pouvez consulter régulièrement la liste des opérations de longue durée pour connaître l'état de l'étape de copie incrémentielle des données. Pour savoir comment obtenir des informations sur une opération de longue durée, lister ou annuler des opérations de longue durée, consultez Utiliser des opérations de longue durée dans Cloud Storage.

L'exemple suivant montre le résultat généré par une opération de copie de données incrémentielle :

  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
  estimatedWriteDowntimeDuration: '7200s'
  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

Le tableau suivant fournit des informations sur les champs clés de la sortie générée par l'opération de copie incrémentielle des données :

Nom du champ Description Valeurs possibles
done Indique la fin de l'opération de déplacement du bucket. true, false
kind Indique que cette ressource représente une opération de stockage.
metadata Fournit des informations sur l'opération.
metadata.@type Indique le type d'opération en tant que déplacement de bucket.
metadata.commonMetadata Métadonnées communes à toutes les opérations.
metadata.commonMetadata.createTime Heure à laquelle l'opération de longue durée a été créée.
metadata.commonMetadata.endTime Heure de fin de l'opération de longue durée.
metadata.commonMetadata.progressPercent Progression estimée de l'opération de longue durée, en pourcentage. Entre 0 et 100 %. Une valeur de -1 signifie que la progression est inconnue ou non applicable.
metadata.commonMetadata.requestedCancellation Indique si l'utilisateur a demandé l'annulation de l'opération de longue durée. true, false
metadata.commonMetadata.type Indique le type d'opération de longue durée.
metadata.commonMetadata.updateTime Date et heure de la dernière mise à jour de l'opération de longue durée.
metadata.destinationLocation Emplacement de destination du bucket.
metadata.finalizationState Indique si l'étape finale de la synchronisation est prête à être lancée.
  • READY : indique que vous pouvez lancer l'étape de synchronisation finale. Toutefois, nous vous recommandons d'attendre que la valeur du champ progressPercent atteigne 99.
  • WAITING_ON_SYNC : indique que vous ne pouvez pas lancer l'étape de synchronisation finale.
  • NOT_REQUIRED : indique que l'étape de synchronisation finale n'est pas nécessaire pour ce bucket et que vous pouvez l'ignorer.
  • BLOCKED_ON_ERRORS : indique que l'étape de finalisation est temporairement suspendue en raison d'erreurs. Vous devrez résoudre les erreurs pour passer à l'étape suivante.
  • RUNNING : indique que l'étape de finalisation est en cours.
  • FINALIZED : indique que l'étape de finalisation s'est terminée avec succès.
metadata.progress Détails de la progression de l'opération de transfert.
metadata.progress.byteProgressPercent Progression des octets copiés en pourcentage. Entre 0 et 100 %. Une valeur de -1 signifie que la progression est inconnue ou non applicable.
metadata.progress.discoveredBytes Nombre d'octets détectés dans le bucket source.
metadata.progress.discoveredObjectCount Nombre d'objets découverts dans le bucket source.
metadata.progress.discoveredSyncCount Nombre de mises à jour des métadonnées d'objet détectées dans le bucket source.
metadata.progress.objectProgressPercent Progression de la copie des objets en pourcentage. Entre 0 et 100 %. Une valeur de -1 signifie que la progression est inconnue ou non applicable.
metadata.progress.remainingBytes Nombre d'octets restant à copier du bucket source vers le bucket de destination.
metadata.progress.remainingObjectCount Nombre d'objets restant à copier du bucket source vers le bucket de destination.
metadata.progress.remainingSyncCount Nombre de mises à jour des métadonnées d'objet restantes à synchroniser.
metadata.progress.syncProgressPercent Progression des mises à jour des métadonnées d'objet à synchroniser en pourcentage. Entre 0 et 100 %. Une valeur de -1 signifie que la progression est inconnue ou non applicable.
metadata.relocationState État global de l'opération de déplacement du bucket.
  • SYNCING : indique que l'étape de copie incrémentielle des données copie activement les objets du bucket source vers le bucket de destination.
  • FINALIZING : indique que l'étape de finalisation a été lancée.
  • FAILED : indique que l'étape de copie incrémentielle des données a rencontré une erreur et n'a pas abouti.
  • SUCCEEDED : indique que l'étape de copie incrémentielle des données s'est terminée avec succès.
  • CANCELLED : indique que l'étape de copie incrémentielle des données a été annulée.
metadata.sourceLocation Emplacement source du bucket.
metadata.validateOnly Indique si un test à blanc du déplacement du bucket a été lancé. true, false
metadata.estimatedWriteDowntimeDuration Durée estimée de l'indisponibilité en écriture. Cette valeur est renseignée une fois que finalizationState est défini sur READY. La valeur minimale est de 7200s.
metadata.writeDowntimeExpireTime Heure d'expiration de l'indisponibilité en écriture.
name Identifiant unique de cette opération de transfert.
Format : projects/_/buckets/bucket-name/operations/operation-id
response Réponse de l'opération.
response.@type Type de réponse.
selfLink Lien vers cette opération.

Si vous rencontrez des problèmes lorsque vous interagissez avec d'autres fonctionnalités de Cloud Storage, consultez la section Limites.

Lancer l'étape de synchronisation finale

L'étape de synchronisation finale implique une période pendant laquelle vous ne pouvez pas effectuer d'opérations d'écriture sur le bucket. Nous vous recommandons de planifier la dernière étape de synchronisation à un moment qui minimise les perturbations pour vos applications.

Avant de continuer, vérifiez que le bucket est entièrement préparé en consultant la valeur finalizationState dans le résultat de l'étape Copie incrémentielle des données. La valeur finalizationState doit être READY pour continuer.

Si vous lancez l'étape de synchronisation finale de manière prématurée, la commande renvoie un message d'erreur The relocate bucket operation is not ready to advance to finalization running state, mais le processus de relocalisation se poursuit.

Nous vous recommandons d'attendre que la valeur progressPercent soit définie sur 99 avant de lancer l'étape de synchronisation finale.

Ligne de commande

Lancez l'étape de synchronisation finale de l'opération de déplacement du bucket une fois que la valeur finalizationState est READY :

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

Où :

  • BUCKET_NAME correspond au nom du bucket que vous souhaitez déplacer.
  • OPERATION_ID est l'ID de l'opération de longue durée, qui est renvoyé dans la réponse des méthodes que vous appelez. Par exemple, la réponse suivante est renvoyée lors de l'appel de gcloud storage operations list, et l'ID de l'opération de longue durée est AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74.
 `name: projects/_/buckets/my-bucket/operations/AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74`

Définissez l'option ttl pour mieux contrôler le processus de relocalisation. Exemple :

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

Où :

TTL_DURATION correspond à la valeur TTL (Time To Live) de la phase d'indisponibilité en écriture lors d'un processus de relocalisation. Elle est exprimée sous la forme d'une chaîne, par exemple 12h pour 12 heures. TTL_DURATION détermine la durée maximale autorisée pour la phase d'indisponibilité en écriture. Si l'indisponibilité en écriture dépasse cette limite, le processus de relocalisation revient automatiquement à l'étape de copie incrémentielle, et les opérations d'écriture dans le bucket sont réactivées. La valeur doit être comprise entre 6h (6 heures) et 48h (48 heures). Si aucune valeur n'est spécifiée, la valeur par défaut est 12h (12 heures).

API REST

API JSON

  1. Vous devez installer et initialiser gcloud CLIafin de générer un jeton d'accès pour l'en-tête Authorization.

  2. Créez un fichier JSON contenant les paramètres de déplacement du bucket. Consultez la documentation Buckets: advanceRelocateBucket pour obtenir la liste complète des paramètres. Les paramètres les plus courants sont les suivants :

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

    Où :

    • EXPIRE_TIME correspond à l'heure d'expiration de l'indisponibilité en écriture.
    • TTL_DURATION correspond à la valeur TTL (Time To Live) de la phase d'indisponibilité en écriture lors d'un processus de relocalisation. Elle est exprimée sous la forme d'une chaîne, par exemple 12h pour 12 heures. TTL_DURATION détermine la durée maximale autorisée pour la phase d'indisponibilité en écriture. Si l'indisponibilité en écriture dépasse cette limite, le processus de relocalisation revient automatiquement à l'étape de copie incrémentielle, et les opérations d'écriture dans le bucket sont réactivées. La valeur doit être comprise entre 6h (6 heures) et 48h (48 heures). Si aucune valeur n'est spécifiée, la valeur par défaut est 12h (12 heures).

  3. Utilisez cURL pour appeler 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"

    Où :

    • JSON_FILE_NAME correspond au nom du fichier JSON que vous avez créé.
    • BUCKET_NAME correspond au nom du bucket que vous souhaitez déplacer.
    • OPERATION_ID est l'ID de l'opération de longue durée, qui est renvoyé dans la réponse des méthodes que vous appelez. Par exemple, la réponse suivante est renvoyée lors de l'appel de Operations: list, et l'ID de l'opération de longue durée est AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74.

Valider le processus de relocalisation de buckets

Une fois le déplacement lancé, vérifiez qu'il s'est bien déroulé. Cette section fournit des conseils pour confirmer le transfert réussi des données.

Validez la réussite du processus de transfert à l'aide des méthodes suivantes :

  • Interroger les opérations de longue durée : la relocalisation de buckets est une opération de longue durée. Vous pouvez interroger l'opération de longue durée à l'aide de operation id pour surveiller sa progression et confirmer sa réussite en vérifiant l'état success. Cela implique d'interroger régulièrement l'état de l'opération jusqu'à ce qu'elle atteigne un état final. Pour en savoir plus sur la surveillance des opérations de longue durée, consultez Utiliser des opérations de longue durée dans Cloud Storage.

  • Analyser les entrées Cloud Audit Logs : Cloud Audit Logs fournit un enregistrement détaillé des événements et des opérations dans votre environnement Google Cloud . Vous pouvez analyser les entrées Cloud Audit Logs associées au déplacement pour vérifier qu'il a bien été effectué. Analysez les journaux pour détecter les erreurs, les avertissements ou les comportements inattendus qui pourraient indiquer des problèmes lors du transfert. Pour savoir comment afficher les journaux Cloud Audit Logs, consultez Afficher les journaux d'audit.

    Les entrées de journal suivantes vous aident à déterminer si votre migration a réussi ou échoué :

    • Migration réussie : Relocate bucket succeeded. All existing objects are now in the new placement configuration.

    • Échec du transfert : Relocate bucket has failed. Bucket location remains unchanged.

    À l'aide des notifications Pub/Sub, vous pouvez également configurer des alertes qui vous avertissent lorsque l'événement de réussite ou d'échec spécifique apparaît dans les journaux. Pour savoir comment configurer les notifications Pub/Sub, consultez Configurer les notifications Pub/Sub pour Cloud Storage.

Effectuer les tâches post-relocalisation des buckets

Une fois votre bucket déplacé, procédez comme suit :

  1. Facultatif : Restaurez les contrôles d'accès basés sur des tags sur votre bucket.
  2. Les configurations existantes des rapports sur l'inventaire ne sont pas conservées lors du transfert. Vous devrez les recréer manuellement. Pour savoir comment créer une configuration de rapport d'inventaire, consultez Créer une configuration de rapport d'inventaire.
  3. Mettez à jour vos configurations d'infrastructure as code, telles que Terraform et le connecteur de configuration Google Kubernetes Engine, pour spécifier le nouvel emplacement du bucket.
  4. Les points de terminaison régionaux sont liés à des emplacements spécifiques. Vous devrez modifier le code de votre application pour refléter le nouveau point de terminaison.

Gérer les échecs d'opérations de déplacement de buckets

Tenez compte des facteurs suivants avant de gérer les opérations de relocalisation de bucket ayant échoué :

  • Si le déplacement d'un bucket échoue, des ressources obsolètes (telles que des fichiers temporaires ou des copies de données incomplètes) peuvent être laissées à la destination. Vous devez attendre entre 7 et 14 jours avant de pouvoir relocaliser un bucket vers la même destination. Vous pouvez lancer immédiatement le déplacement d'un bucket vers une autre destination.

  • Si l'emplacement de destination n'est pas optimal pour vos données, vous pouvez annuler le déplacement. Toutefois, vous ne pouvez pas lancer immédiatement une relocalisation. Vous devez patienter jusqu'à 14 jours avant de pouvoir relancer le processus de relocalisation. Cette restriction est en place pour assurer la stabilité et éviter les conflits de données.

Étapes suivantes