Configurer des montages de volume Cloud Storage pour les services Cloud Run

Cette page explique comment installer un bucket Cloud Storage en tant que volume de stockage, à l'aide des installations de volume Cloud Run.

L'installation du bucket en tant que volume dans Cloud Run présente le contenu du bucket sous forme de fichiers dans le système de fichiers du conteneur. Après avoir installé le bucket en tant que volume, vous y accédez comme s'il s'agissait d'un répertoire de votre système de fichiers local, en utilisant les opérations et les bibliothèques du système de fichiers de votre langage de programmation au lieu d'utiliser les bibliothèques clientes des API Google.

Vous pouvez installer votre volume en lecture seule et spécifier des options d'installation pour votre volume.

Exigences relatives à la mémoire

• Pour toute la mise en cache de Cloud Storage FUSE, Cloud Run utilise par défaut le paramètre de cache de statistiques avec une valeur TTL (Time To Live) de 60 secondes. La taille maximale par défaut du cache de statistiques est de 32 Mo. La taille maximale par défaut du cache de types est de 4 Mio.

• Lors de la lecture à partir de Cloud Storage, Cloud Storage FUSE effectue des appels d'API pour lire un objet directement, sans télécharger l'intégralité du fichier dans un répertoire local. Cloud Storage FUSE établit une connexion TCP et lit l'intégralité de l'objet Cloud Storage, ou seulement les parties du fichier que vous spécifiez dans votre application ou le système d'exploitation via un décalage. Lors de la lecture, Cloud Storage FUSE consomme également de la mémoire en plus des caches de statistiques et de types, par exemple un tableau de 1 Mio pour chaque fichier qu'il lit et pour goroutines.

• Lors de l'écriture dans Cloud Storage, Cloud Storage FUSE accepte streaming-writes, un chemin d'écriture, par défaut. Cloud Storage FUSE importe les données directement dans Cloud Storage sans effectuer de préproduction complète du fichier. Chaque fichier que vous ouvrez pour des écritures en flux continu consomme environ 64 Mio de mémoire pendant le processus d'importation. Cela réduit à la fois la latence et l'utilisation de l'espace disque, ce qui est particulièrement avantageux pour les écritures séquentielles volumineuses.

Limites

Étant donné que Cloud Run utilise Cloud Storage FUSE pour cette installation de volume, vous devez prendre en compte les éléments suivants lors de l'installation d'un bucket Cloud Storage en tant que volume :

• Cloud Storage FUSE ne permet pas de contrôler la simultanéité pour plusieurs écritures (verrouillage de fichiers) dans un même fichier. Lorsque plusieurs écritures tentent de remplacer un fichier, la dernière écriture l'emporte et toutes les écritures précédentes sont perdues.
• Cloud Storage FUSE n'est pas un système de fichiers entièrement compatible avec POSIX. Pour plus de détails, consultez la documentation de Cloud Storage FUSE.

Chemins d'accès non autorisés

Cloud Run ne vous permet pas d'installer un volume sur /dev, /proc ou /sys, ou dans leurs sous-répertoires.

Avant de commencer

Vous avez besoin d'un bucket Cloud Storage à installer en tant que volume.

Pour optimiser les performances de lecture/écriture dans Cloud Storage, consultez Optimiser les performances de la bande passante réseau de Cloud Storage FUSE.

Rôles requis

Pour obtenir les autorisations nécessaires pour configurer des installations de volume Cloud Storage, demandez à votre administrateur de vous accorder les rôles IAM suivants :

• Développeur Cloud Run (roles/run.developer) sur le service Cloud Run
• Utilisateur du compte de service (roles/iam.serviceAccountUser) sur l'identité du service

Pour obtenir les autorisations nécessaires à votre identité de service pour accéder au fichier et au bucket Cloud Storage, demandez à votre administrateur d'accorder à l'identité du service le rôle Lecteur des objets de l'espace de stockage (roles/storage.objectViewer). Si l'identité de service doit également effectuer des opérations d'écriture dans un bucket, attribuez-lui plutôt le rôle Utilisateur d'objets Storage (roles/storage.objectUser).

Pour en savoir plus sur les rôles et les autorisations Cloud Storage, consultez la page IAM pour Cloud Storage.

Pour obtenir la liste des rôles et des autorisations IAM associés à Cloud Run, consultez les sections Rôles IAM Cloud Run et Autorisations IAM Cloud Run. Si votre service Cloud Run communique avec les APICloud de Confiance , telles que les bibliothèques clientes Cloud, consultez le guide de configuration de l'identité du service. Pour en savoir plus sur l'attribution de rôles, consultez les pages Autorisations de déploiement et Gérer les accès.

Installer un volume Cloud Storage

Si vous utilisez plusieurs conteneurs, spécifiez les volumes, puis spécifiez les installations de volume pour chaque conteneur.

Les installations de volume nécessitent l'environnement d'exécution de deuxième génération. Si aucun environnement d'exécution n'est explicitement configuré, Cloud Run sélectionne automatiquement l'environnement d'exécution de deuxième génération pour votre service.

  resource "google_cloud_run_v2_service" "default" {
    name     = "SERVICE"
    location = "REGION"

    template {
      containers {
        image = "IMAGE_URL"
        volume_mounts {
          name = "VOLUME_NAME"
          mount_path = "MOUNT_PATH"
        }
      }

      volumes {
        name = "VOLUME_NAME"
        gcs {
          bucket = google_storage_bucket.default.name
          read_only = IS_READ_ONLY
        }
      }
    }
  }

  resource "google_storage_bucket" "default" {
    name     = "BUCKET_NAME"
    location = "REGION"
  }

  services:
    web:
      image: IMAGE
      volumes:
        - VOLUME_NAME:MOUNT_PATH
  volumes:
    VOLUME_NAME:

Lire et écrire dans un volume

Si vous utilisez la fonctionnalité d'installation de volume Cloud Run, vous accédez à un volume installé à l'aide des mêmes bibliothèques dans votre langage de programmation que celles que vous utilisez pour lire et écrire des fichiers sur votre système de fichiers local.

Ceci est particulièrement utile si vous utilisez un conteneur existant qui attend que des données soient stockées sur le système de fichiers local et utilise des opérations standards du système de fichiers pour y accéder.

Les extraits suivants supposent une installation de volume avec un mountPath défini sur /mnt/my-volume.

var fs = require('fs');
fs.appendFileSync('/mnt/my-volume/sample-logfile.txt', 'Hello logs!', { flag: 'a+' });

f = open("/mnt/my-volume/sample-logfile.txt", "a")

f, err := os.Create("/mnt/my-volume/sample-logfile.txt")

import java.io.File;
File f = new File("/mnt/my-volume/sample-logfile.txt");

Configuration du volume à l'aide des options d'installation

Vous pouvez éventuellement utiliser des options d'installation pour configurer différentes propriétés de l'installation de votre volume. Les options d'installation disponibles vous permettent de configurer les paramètres de cache, d'installer un répertoire spécifique, d'activer la journalisation de débogage et d'autres comportements.

Spécifier les options d'installation

  gcloud run deploy SERVICE \
      --image IMAGE_URL \
      --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,readonly=READ_ONLY,mount-options="OPTION_1=VALUE_1;OPTION_N=VALUE_N"

  resource "google_cloud_run_v2_service" "default" {
    name     = "SERVICE"
    location = "REGION"

    template {
      containers {
        image = "IMAGE_URL"
        volume_mounts {
          name = "VOLUME_NAME"
          mount_path = "MOUNT_PATH"
        }
      }

      volumes {
        name = "VOLUME_NAME"
        gcs {
            bucket = google_storage_bucket.default.name
            read_only = IS_READ_ONLY
            mount_options = ["OPTION_1=VALUE_1", "OPTION_N=VALUE_N", "OPTION_O"]
        }
      }
    }
  }

Options d'installation couramment utilisées

Les options d'installation sont couramment utilisées pour :

• Configurer les paramètres du cache
• Installer uniquement un répertoire spécifique du bucket Cloud Storage
• Configurez la propriété du volume (uid, gid).
• Désactiver les répertoires implicites
• Spécifiez les niveaux de journalisation de débogage.

Configurer les paramètres de mise en cache

Vous pouvez modifier les paramètres de mise en cache de votre volume en définissant les options d'installation liées à la mise en cache. Le tableau suivant répertorie les paramètres, ainsi que les valeurs Cloud Run par défaut :

La commande Google Cloud CLI suivante définit metadata-cache-ttl-secs sur 120 secondes et augmente la capacité du cache de statistiques et de types à 52 et 7 Mio, respectivement :

gcloud run services update SERVICE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="metadata-cache-ttl-secs=120;stat-cache-max-size-mb=52;type-cache-max-size-mb=7"
    

Remplacez les éléments suivants :

• SERVICE : nom de votre service.
• BUCKET_NAME : nom du bucket Cloud Storage.
• MOUNT_PATH : chemin relatif où vous installez le volume, par exemple /cache.

Activer la journalisation du débogage

Par défaut, Cloud Storage FUSE consigne les événements de niveau Info ou supérieur. Vous pouvez modifier les paramètres de journalisation en utilisant l'un des niveaux de gravité de journal suivants, classés du plus bas au plus élevé :

• trace
• debug
• info
• warning
• error
• Pour désactiver toute journalisation, spécifiez la valeur off.

Lorsque vous spécifiez un niveau de gravité, Cloud Storage FUSE génère des journaux pour les événements dont le niveau de gravité est supérieur ou égal à la gravité spécifiée. Par exemple, lorsque vous spécifiez le niveau warning, Cloud Storage FUSE génère des journaux pour les avertissements et les erreurs.

Définir la gravité des journaux sur des niveaux supérieurs à info peut avoir un impact sur les performances et générer une grande quantité de données de journalisation. Nous vous recommandons donc de ne le faire qu'en cas de besoin. Pour assurer la compatibilité avec Cloud Logging, le format de journal est text. Le format json n'est pas accepté.

La ligne de commande suivante active la journalisation du débogage :

gcloud run services update SERVICE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="log-severity=debug"

Remplacez les éléments suivants :

• SERVICE : nom de votre service.
• BUCKET_NAME : nom du bucket Cloud Storage.
• MOUNT_PATH : chemin relatif où vous installez le volume, par exemple /cache.

Désactiver les répertoires implicites

Pour que Cloud Storage ressemble davantage à un système de fichiers standard, Cloud Run active les répertoires implicites par défaut lors de l'installation d'un bucket Cloud Storage. Vous pouvez désactiver les répertoires implicites à l'aide de l'option d'installation implicit-dirs. La désactivation des répertoires implicites peut améliorer les performances et réduire les coûts, mais elle présente des inconvénients en termes de compatibilité.

La fonctionnalité de répertoires implicites permet à Cloud Run de reconnaître les fichiers Cloud Storage préexistants dont les noms imitent une structure de répertoires, comme /mydir/myfile.txt. Si vous désactivez les répertoires implicites, Cloud Run ne pourra pas lister ni lire ces fichiers.

La désactivation des répertoires implicites réduit le nombre de requêtes adressées à Cloud Storage, ce qui peut améliorer les performances et le coût de votre application. Pour en savoir plus, consultez la documentation sur les fichiers et répertoires Cloud Storage FUSE.

La ligne de commande suivante désactive les répertoires implicites :

gcloud run services update SERVICE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="implicit-dirs=false"

Remplacez les éléments suivants :

• SERVICE : nom de votre service.
• BUCKET_NAME : nom du bucket Cloud Storage.
• MOUNT_PATH : chemin relatif où vous installez le volume, par exemple /cache.

Installer un répertoire spécifique dans votre bucket Cloud Storage

Par défaut, Cloud Run installe l'intégralité du bucket Cloud Storage, ce qui permet aux services Cloud Run d'accéder à l'ensemble de son contenu. Dans certains cas, vous pouvez n'installer qu'un répertoire spécifique. Par exemple, si le bucket contient un grand nombre de fichiers, l'installation d'un répertoire spécifique peut améliorer les performances.

Vous pouvez également l'implémenter à des fins d'isolation lorsque vous avez besoin que différents services aient accès à différents répertoires du bucket de stockage.

La ligne de commande suivante spécifie le répertoire à installer :

gcloud run services update SERVICE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="only-dir=images"

Remplacez les éléments suivants :

• SERVICE : nom de votre service.
• BUCKET_NAME : nom du bucket Cloud Storage.
• MOUNT_PATH : chemin relatif où vous installez le volume, par exemple /cache.

Régler le volume UID et GID

Utilisez les options d'installation uid et gid pour modifier l'identifiant utilisateur et l'identifiant de groupe du volume. Cela est utile si vous souhaitez définir la propriété du fichier sur un utilisateur ou un groupe spécifique correspondant à l'identité d'un ou de plusieurs conteneurs en cours d'exécution. Par défaut, les volumes appartiennent à la racine.

La ligne de commande suivante définit uid et gid :

gcloud run services update SERVICE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="uid=UID;gid=GID"

Remplacez les éléments suivants :

• SERVICE : nom de votre service.
• MOUNT_PATH : chemin relatif où vous installez le volume, par exemple /cache.
• BUCKET_NAME : nom du bucket Cloud Storage.
• UID : ID utilisateur à utiliser pour installer le volume.
• GID : ID de groupe à utiliser pour installer le volume.

Afficher les paramètres des installations de volumes

Optimiser les performances de la bande passante réseau de Cloud Storage FUSE

Pour de meilleures performances de lecture et d'écriture, connectez votre service Cloud Run à un réseau VPC à l'aide du VPC direct et acheminez tout le trafic sortant via votre réseau VPC. Pour ce faire, utilisez l'une des options suivantes:

• Activez l'accès privé à Google en veillant à définir le paramètre vpc-egress sur all-traffic.
• Utilisez l'une des options décrites sur la page des bonnes pratiques de mise en réseau, dans la section Trafic interne vers une API Google.

Délai de démarrage du conteneur et installations Cloud Storage FUSE

L'utilisation de Cloud Storage FUSE peut légèrement augmenter le temps de démarrage à froid de votre conteneur Cloud Run, car Cloud Run démarre l'installation de volumes avant le démarrage du ou des conteneurs. Votre conteneur ne démarrera que si Cloud Storage FUSE est installé correctement.

Notez que Cloud Storage FUSE n'installe un volume qu'après avoir établi une connexion à Cloud Storage. Tout retard de mise en réseau peut avoir un impact sur le temps de démarrage du conteneur. De même, si la tentative de connexion échoue, Cloud Storage FUSE ne pourra pas être installé et le service Cloud Run ne démarrera pas. En outre, si l'installation de Cloud Storage FUSE prend plus de 30 secondes, le service Cloud Run ne démarre pas, car Cloud Run a un délai total de 30 secondes pour effectuer toutes les installations.

Caractéristiques des performances de Cloud Storage FUSE

Si vous définissez deux volumes, chacun pointant vers un bucket différent, deux processus Cloud Storage FUSE seront lancés. Les montages et les processus se produisent en parallèle.

Les opérations utilisant Cloud Storage FUSE sont affectées par la bande passante réseau, car Cloud Storage FUSE communique avec Cloud Storage à l'aide de l'API Cloud Storage. Certaines opérations, telles que la liste du contenu d'un bucket, peuvent être lentes si la bande passante réseau est faible. De même, la lecture d'un fichier volumineux peut prendre du temps, car cette opération est également limitée par la bande passante du réseau.

Lorsque vous écrivez dans un bucket, Cloud Storage FUSE prépare entièrement l'objet en mémoire. Cela signifie que l'écriture de fichiers volumineux est limitée par la quantité de mémoire disponible pour l'instance de conteneur (la limite de mémoire maximale du conteneur est de 32 Gio).

L'écriture n'est effacée dans le bucket que lorsque vous effectuez une opération close ou fsync : l'objet complet est alors importé dans le bucket. La seule exception à un objet en cours de réimportation dans le bucket concerne un fichier avec du contenu ajouté lorsque sa taille est supérieure ou égale à 2 Mio.

Pour en savoir plus, consultez les ressources suivantes :

• Documentation Cloud Storage FUSE
• Performances de Cloud Storage FUSE
• Sémantique de Cloud Storage FUSE

Effacer et supprimer des volumes et des installations de volume

Vous pouvez effacer tous les volumes et installations, ou supprimer des volumes et des installations de volume individuels.

Effacer tous les volumes et installations de volume

Pour effacer tous les volumes et installations de volume de votre service à conteneur unique, exécutez la commande suivante :

gcloud run services update SERVICE \
    --clear-volumes \
    --clear-volume-mounts

gcloud run services update SERVICE \
    --container=container1 \
    --clear-volumes \
    --clear-volume-mounts \
    --container=container2 \
    --clear-volumes \
    --clear-volume-mounts

Supprimer des volumes et des installations de volume individuels

Pour supprimer un volume, vous devez également supprimer tous les montages de volume qui l'utilisent.

Pour supprimer des volumes ou des installations de volume individuels, utilisez les options remove-volume et remove-volume-mount :

gcloud run services update SERVICE \
    --remove-volume VOLUME_NAME \
    --container=container1 \
    --remove-volume-mount MOUNT_PATH \
    --container=container2 \
    --remove-volume-mount MOUNT_PATH