Configurer des installations de volume Cloud Storage pour les jobs

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.

Exigences relatives à la mémoire

Les installations de volume Cloud Storage utilisent la mémoire du conteneur Cloud Run pour les activités suivantes :

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 Mo.
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 Mo pour chaque fichier en cours de lecture et pour les goroutines.
Lors de l'écriture dans Cloud Storage, l'ensemble du fichier est stocké dans la mémoire Cloud Run avant son écriture dans Cloud Storage.

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 et /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 en lecture/écriture dans Cloud Storage, consultez Optimiser les performances de 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 job 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 IAM suivant:

Administrateur de l'espace de stockage (roles/storage.admin)

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 pages Rôles IAM Cloud Run et Autorisations IAM Cloud Run. Si votre job Cloud Run communique avec des API Google Cloud, telles que des 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

Vous pouvez installer plusieurs buckets sur différents chemins d'installation. Vous pouvez également installer un volume sur plusieurs conteneurs à l'aide de chemins d'installation identiques ou différents sur l'ensemble des conteneurs.

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

Console

Dans la console Google Cloud, accédez à la page des jobs Cloud Run :

Accédez à Cloud Run
Cliquez sur Déployer un conteneur, puis sélectionnez Job pour remplir la page initiale des paramètres du job. Si vous configurez un job existant, cliquez sur celui-ci, puis sur Modifier.
Cliquez sur Conteneur, variables et secrets, connexions, sécurité pour développer la page des propriétés du job.
Cliquez sur l'onglet Volumes.
- Sous Volumes :
  - Cliquez sur Ajouter un volume.
  - Dans la liste déroulante Type de volume, sélectionnez "Bucket Cloud Storage" comme type de volume.
  - Dans le champ Nom du volume, saisissez le nom du volume que vous souhaitez utiliser.
  - Parcourez les buckets et sélectionnez-en un pour le volume.
  - Si vous le souhaitez, cochez la case Lecture seule pour passer le bucket en lecture seule.
  - Cliquez sur OK.
- Cliquez sur l'onglet "Conteneur", puis développez le conteneur sur lequel vous installez le volume pour modifier le conteneur.
- Cliquez sur l'onglet Montages de volume.
- Cliquez sur Monter le volume.
Cliquez sur Créer ou Mettre à jour.

gcloud

Pour ajouter un volume et l'installer, procédez comme suit :
```
gcloud run jobs update JOB \
--add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME \
--add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH
```
Remplacez :
- JOB par le nom de votre tâche.
- MOUNT_PATH par le chemin relatif où vous installez le volume, par exemple, /mnt/my-volume.
- VOLUME_NAME par le nom que vous souhaitez pour votre volume. La valeur VOLUME_NAME permet de mapper le volume à l'installation du volume.
- BUCKET_NAME par le nom de votre bucket Cloud Storage.
Pour installer votre volume en tant que volume en lecture seule, procédez comme suit :
```
--add-volume=name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,readonly=true
```

Si vous utilisez plusieurs conteneurs, spécifiez d'abord vos volumes, puis les installations de volumes pour chaque conteneur :

gcloud run jobs update JOB \
--add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME \
--container CONTAINER_1 \
--add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH \
--container CONTAINER_2 \
--add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH2

YAML

Si vous créez un job, ignorez cette étape. Si vous mettez à jour un job existant, téléchargez sa configuration YAML :
```
gcloud run jobs describe JOB_NAME --format export > job.yaml
```

Mettez à jour les attributs MOUNT_PATH, VOLUME_NAME, BUCKET_NAME et IS_READ_ONLY si nécessaire.

apiVersion: run.googleapis.com/v1
kind: Job
metadata:
  name: JOB_NAME
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/execution-environment: gen2
    spec:
      template:
        spec:
          containers:
          - image: IMAGE_URL
            volumeMounts:
            - mountPath: MOUNT_PATH
              name: VOLUME_NAME
          volumes:
          - name: VOLUME_NAME
            csi:
              driver: gcsfuse.run.googleapis.com
              readOnly: IS_READ_ONLY
              volumeAttributes:
                bucketName: BUCKET_NAME

Remplacer

IMAGE_URL par une référence à l'image de conteneur, par exemple us-docker.pkg.dev/cloudrun/container/hello:latest. Si vous utilisez Artifact Registry, le dépôt REPO_NAME doit déjà être créé. L'URL se présente sous la forme suivante : LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
MOUNT_PATH par le chemin relatif où vous installez le volume, par exemple, /mnt/my-volume.
VOLUME_NAME par le nom que vous souhaitez pour votre volume. La valeur VOLUME_NAME permet de mapper le volume à l'installation du volume.
IS_READ_ONLY par True pour passer le volume en lecture seule ou False pour autoriser les écritures.
BUCKET_NAME par le nom du bucket Cloud Storage

Créez ou mettez à jour le job à l'aide de la commande suivante :
```
gcloud run jobs replace job.yaml
```

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.

Nodejs

Utilisez le module File System pour créer un fichier ou ajouter des données à un fichier existant dans le volume /mnt/my-volume :

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

Python

Écrivez les données dans un fichier conservé dans le volume /mnt/my-volume :

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

Go

Utilisez le package os pour créer un fichier conservé dans le volume /mnt/my-volume.

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

Java

Utilisez la classe Java.io.File pour créer un fichier journal dans le volume /mnt/my-volume :

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

Afficher les paramètres des installations de volumes

Console

Dans la console Google Cloud, accédez à la page des jobs Cloud Run :

Accéder aux jobs Cloud Run
Cliquez sur la tâche qui vous intéresse pour ouvrir la page Informations sur la tâche.
Cliquez sur l'onglet Volumes.
Recherchez le paramètre des installations de volumes dans la page d'informations sur les volumes.

gcloud

Exécutez la commande suivante :
```
gcloud run jobs describe JOB_NAME
```
Recherchez le paramètre des installations de volumes dans la configuration renvoyée.

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

Pour de meilleures performances de lecture et d'écriture, connectez votre tâche 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 dans la page "Bonnes pratiques de mise en réseau" dans l'exemple 2, 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 l'installation de volumes est effectuée avant le démarrage du ou des conteneurs. Votre conteneur ne démarre que si Cloud Storage FUSE est correctement installé.

Notez que Cloud Storage FUSE ne peut installer un volume qu'après avoir établi une connexion à Cloud Storage. Tout retard 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 peut pas être monté et la tâche Cloud Run ne peut pas démarrer. En outre, si l'installation de Cloud Storage FUSE prend plus de 30 secondes, le job 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 démarré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 du réseau, car Cloud Storage FUSE communique avec Cloud Storage à l'aide de l'API Cloud Storage. Certaines opérations, comme la liste du contenu d'un bucket, peuvent être lentes si la bande passante du 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 met entièrement en cache 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é/ré-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 :