MemoriaGCP

tekio.org

gcloud storage : buckets et objets

gcloud storage est la CLI de Cloud Storage. gsutil déconseillé est un outil hérité, à ne pas utiliser : gcloud storage couvre les mêmes commandes et parallélise seul les transferts. Joker * : un niveau de dossier ; ** : tous les niveaux.

Buckets

Objectif Syntaxe Résultat
Créer un bucket privé gcloud storage buckets create gs://BUCKET --project=PROJECT_ID --location=REGION --default-storage-class=STANDARD --uniform-bucket-level-access --public-access-prevention Accès par IAM seulement, jamais public ; nom unique au monde, emplacement définitif (US si --location est omis)
Bucket de travail sans suppression réversible gcloud storage buckets create gs://BUCKET --location=REGION --soft-delete-duration=0 Objets supprimés aussitôt effacés ; 7 jours de rétention par défaut sinon
Lister les buckets gcloud storage buckets list --format="table(name,location,default_storage_class)" Buckets du projet courant ; gcloud storage ls pour les seules URL
Lire la configuration gcloud storage buckets describe gs://BUCKET --format="default(location,soft_delete_policy,versioning_enabled,uniform_bucket_level_access,public_access_prevention)" Seuls les champs demandés ; sans --format, toute la ressource
Taille d'un bucket gcloud storage du -s --readable-sizes gs://BUCKET Total lisible ; -a compte aussi les versions non courantes
Ajouter des libellés gcloud storage buckets update gs://BUCKET --update-labels=equipe=data,env=prod --remove-labels=env en retire
Changer la classe par défaut gcloud storage buckets update gs://BUCKET --default-storage-class=NEARLINE Vaut pour les objets écrits ensuite ; les objets existants gardent leur classe
Supprimer un bucket et tout son contenu gcloud storage rm --recursive gs://BUCKET Objets, versions, puis bucket ; gcloud storage buckets delete ne supprime qu'un bucket vide

Copier, déplacer, synchroniser

Objectif Syntaxe Résultat
Envoyer un fichier gcloud storage cp ./f.csv gs://BUCKET/rep/ Objet rep/f.csv ; somme de contrôle vérifiée
Envoyer un dossier gcloud storage cp --recursive ./dossier gs://BUCKET/rep/ Arborescence recopiée sous rep/dossier/
Télécharger par motif gcloud storage cp 'gs://BUCKET/rep/*.csv' ./local/ Apostrophes pour que le shell ne développe pas le joker
Ne pas écraser gcloud storage cp -n ./f.csv gs://BUCKET/rep/ Objets déjà présents ignorés et signalés
Fixer classe et métadonnées à l'envoi gcloud storage cp --storage-class=NEARLINE --content-type=application/json --cache-control="no-cache" ./f.json gs://BUCKET/rep/ Évite une réécriture après coup
Écrire depuis un flux mysqldump BASE | gzip | gcloud storage cp - gs://BUCKET/dumps/base.sql.gz - lit l'entrée standard, sans fichier local intermédiaire
Copier entre buckets gcloud storage cp --recursive gs://SRC/rep gs://DEST/ Copie côté serveur, sans passer par la machine locale
Renommer un préfixe gcloud storage mv gs://BUCKET/ancien gs://BUCKET/nouveau Copie puis suppression de chaque objet, facturées comme telles : pas de renommage atomique
Synchroniser, à blanc gcloud storage rsync --recursive --dry-run ./site gs://BUCKET/site Liste des copies qui seraient faites, sans rien écrire
Synchroniser en miroir gcloud storage rsync --recursive --delete-unmatched-destination-objects ./site gs://BUCKET/site Destination identique à la source : les objets absents de la source sont supprimés
Exclure des fichiers gcloud storage rsync --recursive --exclude='.*\.tmp$' ./data gs://BUCKET/data Expression régulière Python, relative à la racine synchronisée
Accélérer les gros envois gcloud config set storage/parallel_composite_upload_enabled True Fichiers de plus de 150 Mio découpés, envoyés en parallèle puis recomposés ; objet sans MD5, contrôlé par CRC32C
Lire un objet gcloud storage cat gs://BUCKET/rep/f.csv | head Contenu sur la sortie standard ; -r 0-999 pour une plage d'octets
Supprimer par motif gcloud storage rm 'gs://BUCKET/rep/**' Tous les objets sous rep/, à tous les niveaux

Un envoi composite parallèle laisse des objets temporaires qu'un bucket soumis à une politique de conservation ou à une retenue par défaut ne peut pas effacer. La vérification de compatibilité, active par défaut, l'évite en ne l'appliquant qu'aux objets STANDARD.

Objets et métadonnées

Objectif Syntaxe Résultat
Lister avec tailles et dates gcloud storage ls -l gs://BUCKET/rep/ Taille, date de création, URL ; --recursive pour descendre dans les sous-dossiers
Lister toutes les versions gcloud storage ls -a gs://BUCKET/rep/f.csv URL suffixées de leur génération : gs://BUCKET/rep/f.csv#1767225600123456
Détail d'un objet gcloud storage objects describe gs://BUCKET/rep/f.csv --format="default(size,storage_class,content_type,update_time,custom_fields)" Taille, classe, type, date, métadonnées personnalisées
Ajouter des métadonnées gcloud storage objects update gs://BUCKET/rep/f.csv --update-custom-metadata=source=crm --custom-metadata=... remplace l'ensemble ; --remove-custom-metadata=source retire une clé
Changer la classe d'objets existants gcloud storage objects update 'gs://BUCKET/**/*.jpg' --storage-class=COLDLINE Réécriture des objets ; une règle de cycle de vie fait la même chose en continu
Restaurer un objet supprimé gcloud storage ls --soft-deleted gs://BUCKET/rep/ puis gcloud storage restore gs://BUCKET/rep/f.csv Dernière version supprimée de façon réversible remise en ligne ; #GENERATION pour une version précise
Restaurer en masse gcloud storage restore 'gs://BUCKET/**' --async --deleted-after-time="2026-01-31T00:00:00Z" Opération longue qui restaure tout ce qui a été supprimé depuis cette date

Accès

Objectif Syntaxe Résultat
Donner la lecture à un compte de service gcloud storage buckets add-iam-policy-binding gs://BUCKET --member=serviceAccount:SA@PROJECT_ID.iam.gserviceaccount.com --role=roles/storage.objectViewer Lecture de tous les objets du bucket ; roles/storage.objectCreator pour l'écriture seule, roles/storage.objectUser pour lire, écrire et supprimer
Retirer un rôle gcloud storage buckets remove-iam-policy-binding gs://BUCKET --member=user:EMAIL --role=roles/storage.objectViewer Liaison supprimée
Voir la stratégie IAM gcloud storage buckets get-iam-policy gs://BUCKET Liaisons rôle → membres du bucket
URL signée de téléchargement gcloud storage sign-url gs://BUCKET/rep/f.pdf --duration=10m --impersonate-service-account=SA@PROJECT_ID.iam.gserviceaccount.com Lien valable 10 minutes, sans compte Google ; 7 jours au plus. Demande roles/iam.serviceAccountTokenCreator sur le compte de service, pas de clé
URL signée d'envoi gcloud storage sign-url gs://BUCKET/depot/f.csv --http-verb=PUT --duration=1h --headers=content-type=text/csv --impersonate-service-account=SA@PROJECT_ID.iam.gserviceaccount.com Le client envoie par PUT avec exactement cet en-tête Content-Type
Rendre un bucket public en lecture gcloud storage buckets add-iam-policy-binding gs://BUCKET --member=allUsers --role=roles/storage.objectViewer Refusé tant que la prévention de l'accès public est active ; à réserver à un site statique ou à des données ouvertes

Protection et cycle de vie

Objectif Syntaxe Résultat
Activer le versionnement gcloud storage buckets update gs://BUCKET --versioning Chaque remplacement ou suppression garde l'ancienne version ; --no-versioning pour arrêter
Régler la suppression réversible gcloud storage buckets update gs://BUCKET --soft-delete-duration=30d Rétention de 7 à 90 jours ; 0 la désactive
Appliquer des règles de cycle de vie gcloud storage buckets update gs://BUCKET --lifecycle-file=cycle.json Règles du fichier (voir ci-dessous) ; --clear-lifecycle les retire
Relire les règles gcloud storage buckets describe gs://BUCKET --format="default(lifecycle_config)" Règles actives
Politique de conservation gcloud storage buckets update gs://BUCKET --retention-period=365d Aucun objet supprimable ni remplaçable avant un an ; --clear-retention-period tant qu'elle n'est pas verrouillée
Verrouiller la politique gcloud storage buckets update gs://BUCKET --lock-retention-period Irréversible : la durée ne peut plus qu'augmenter, le bucket ne se supprime qu'une fois tous ses objets arrivés au terme de leur conservation
Retenue temporaire sur un objet gcloud storage objects update gs://BUCKET/rep/f.pdf --temporary-hold Objet non supprimable jusqu'à --no-temporary-hold
Retenue sur événement gcloud storage objects update gs://BUCKET/rep/f.pdf --event-based-hold À la levée (--no-event-based-hold), la durée de conservation du bucket repart de zéro
Conservation propre à un objet gcloud storage objects update gs://BUCKET/rep/f.pdf --retain-until=2031-01-01T00:00:00Z --retention-mode=Unlocked Demande un bucket créé avec --enable-per-object-retention ; Locked rend la date impossible à avancer

Fichier cycle.json : passage en Coldline à 90 jours, suppression à 3 ans, deux versions non courantes au plus.

{
  "rule": [
    {"action": {"type": "SetStorageClass", "storageClass": "COLDLINE"},
     "condition": {"age": 90, "matchesStorageClass": ["STANDARD"]}},
    {"action": {"type": "Delete"}, "condition": {"age": 1095}},
    {"action": {"type": "Delete"}, "condition": {"numNewerVersions": 2, "isLive": false}}
  ]
}

Notifications Pub/Sub

Objectif Syntaxe Résultat
Notifier les nouveaux objets gcloud storage buckets notifications create gs://BUCKET --topic=TOPIC --event-types=OBJECT_FINALIZE --object-prefix=entrant/ Un message par objet écrit sous entrant/ ; sujet créé et droit de publication donné à l'agent de service si besoin
Sujet déjà configuré gcloud storage buckets notifications create gs://BUCKET --topic=projects/PROJECT_ID/topics/TOPIC --skip-topic-setup Ni création de sujet ni modification IAM : l'agent de service doit déjà avoir roles/pubsub.publisher
Lister les notifications gcloud storage buckets notifications list gs://BUCKET ID, sujet, filtres de chaque configuration
Supprimer une notification gcloud storage buckets notifications delete projects/_/buckets/BUCKET/notificationConfigs/NOTIFICATION_ID Configuration supprimée, sujet conservé

Contexte : Cloud Storage, classes et cycle de vie, Pub/Sub, datasets, tables et chargement, configuration de gcloud.