Gérer les agents de transfert

Les agents du service de transfert de stockage sont des applications exécutées dans un conteneur Docker qui se coordonnent avec le service de transfert de stockage pour lire les données des sources du système de fichiers POSIX et/ou écrire des données dans des récepteurs du système de fichiers POSIX.

Si le transfert n'implique pas de système de fichiers POSIX, vous n'avez pas besoin de configurer d'agents.

Ce document explique comment administrer les agents de transfert sur vos serveurs.

Présentation

  • Les processus d'agent sont dynamiques. Lors d'un transfert, vous pouvez ajouter des agents pour améliorer les performances. Les agents nouvellement lancés rejoignent le pool d'agents et effectuent des tâches à partir des transferts existants. Cela vous permet d'ajuster le nombre d'agents en cours d'exécution ou d'adapter les performances de transfert en fonction de la demande.

  • Les processus d'agent constituent une entité collective tolérante aux pannes. Si un agent cesse de s'exécuter, les agents restants continuent leur travail. Si tous vos agents s'arrêtent, le transfert reprend là où ils ont été arrêtés dès que vous les redémarrez. Ainsi, vous n'avez pas besoin d'exploiter des agents de surveillance, de relancer les transferts ni de mettre en œuvre une logique de récupération. Vous pouvez corriger, déplacer et effectuer un scaling dynamique de votre pool d'agents sans que vos transferts ne subissent de temps d'arrêt en coordonnant les agents avec Google Kubernetes Engine.

    Imaginons par exemple que vous lanciez deux transferts pendant que deux agents sont en cours d'exécution. Si l'un des agents s'arrête en raison d'un redémarrage de la machine ou d'un correctif du système d'exploitation, l'agent restant continue de fonctionner. Les deux transferts sont toujours en cours d'exécution, mais à une vitesse réduite, car un seul agent déplace les données. Si l'agent restant s'arrête aussi, tous les transferts cessent de progresser, car aucun agent n'est en cours d'exécution. Lorsque vous redémarrez les processus d'agent, les transferts reprennent là où ils s'étaient arrêtés.

  • Les processus d'agent appartiennent à un pool. Ils déplacent collectivement vos données en parallèle. Pour cette raison, tous les agents d'un pool doivent disposer du même accès à toutes les sources de données que vous souhaitez transférer.

    Par exemple, si vous transférez des données à partir d'un système de fichiers spécifique, vous devez installer le système de fichiers sur chaque machine hébergeant des agents dans votre pool d'agents. Si certains agents de votre pool peuvent accéder à une source de données et que d'autres ne le peuvent pas, les transferts à partir de cette source de données échoueront.

Avant de commencer

Avant de configurer vos transferts, assurez-vous d'avoir configuré l'accès : pour les utilisateurs et les comptes de service.

Si vous prévoyez d'utiliser les commandes gcloud, installez la CLI gcloud.

Installer et exécuter des agents de transfert

Nous vous recommandons d'installer au moins trois agents par pool d'agents, idéalement sur des machines distinctes. Pour savoir comment déterminer le nombre d'agents à exécuter, consultez la page Optimiser les performances de l'agent de transfert.

Pour installer et exécuter des agents de transfert:

Console Google Cloud

  1. Dans la console Google Cloud, accédez à la page Pools d'agents.

    Accéder aux pools d'agents

  2. Sélectionnez le pool d'agents auquel ajouter le nouvel agent.

  3. Cliquez sur Installer l'agent.

  4. Suivez les instructions pour installer et exécuter l'agent.

    Pour en savoir plus sur les options de ligne de commande de l'agent, consultez la section Options de ligne de commande de l'agent.

CLI gcloud

Pour installer un ou plusieurs agents à l'aide de la CLI gcloud, exécutez la commande gcloud transfer agents install:

gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
  --mount-directories=MOUNT_DIRECTORIES

L'outil vous guide tout au long du processus d'installation des agents. Cette commande installe le ou les agents NUM_AGENTS sur votre ordinateur, mappés au nom du pool spécifié en tant que POOL_NAME et authentifie l'agent à l'aide de vos identifiants gcloud. Si le nom du pool n'existe pas, une erreur est renvoyée.

L'option --mount-directories est facultative, mais vivement recommandée. Sa valeur est une liste de répertoires du système de fichiers séparés par des virgules et auxquels l'agent peut accéder. Si vous omettez cet indicateur, l'ensemble du système de fichiers est installé dans le conteneur de l'agent. Pour en savoir plus, consultez la documentation de référence sur gcloud.

Pour exécuter des agents à l'aide d'une clé de compte de service, utilisez l'option --creds-file:

gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
   --creds-file=/relative/path/to/service-account-key.json

Pour obtenir la liste complète des options facultatives, exécutez gcloud transfer agents install --help ou consultez la documentation de référence sur gcloud transfer.

docker run

Avant d'utiliser docker run pour installer des agents, suivez les instructions pour installer Docker.

La commande docker run installe un agent. Pour augmenter le nombre d'agents dans votre pool, exécutez à nouveau cette commande autant de fois que nécessaire.

Lors de l'installation d'agents, vous pouvez choisir de vous authentifier à l'aide de vos identifiants par défaut gcloud ou d'un compte de service.

Identifiants par défaut

Pour permettre au conteneur Docker de s'authentifier avec vos identifiants par défaut gcloud, créez un volume Docker contenant un fichier avec les identifiants par défaut de votre application en exécutant la commande suivante:

sudo docker run -ti --name gcloud-config google/cloud-sdk gcloud auth application-default login

Exécutez ensuite la commande suivante pour installer un agent, en utilisant l'option --volumes-from pour installer le volume d'identifiants gcloud-config:

sudo docker run --ulimit memlock=64000000 -d --rm \
--volumes-from gcloud-config \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--hostname=$(hostname) \
--agent-pool=POOL_NAME

Authentification du compte de service

Pour installer et exécuter les agents de transfert docker run à l'aide des identifiants du compte de service, spécifiez le chemin d'accès à la clé de votre compte de service au format JSON à l'aide de l'option --creds-file.

Le chemin d'accès doit être précédé de la chaîne /transfer_root.

Pour en savoir plus sur les clés de compte de service, consultez la page Créer et gérer les clés de compte de service.

sudo docker run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
-v PATH/TO/KEY.JSON:PATH/TO/KEY.JSON \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/transfer_root/PATH/TO/KEY.JSON
--hostname=$(hostname) \
--agent-pool=POOL_NAME

Options et indicateurs

Remplacez les variables des exemples ci-dessus par les informations suivantes:

  • HOST_DIRECTORY est le répertoire de la machine hôte à partir duquel vous souhaitez effectuer la copie. Vous pouvez utiliser plusieurs options -v pour spécifier des répertoires supplémentaires à partir desquels effectuer la copie.
  • CONTAINER_DIRECTORY est le répertoire mappé dans le conteneur de l'agent. Il doit être identique à HOST_DIRECTORY.
  • PROJECT_ID est l'ID du projet qui héberge le transfert.
  • POOL_NAME est le nom du pool d'agents dans lequel installer cet agent. Si vous omettez cette option, l'agent est installé dans le pool transfer_service_default de votre projet.

La commande docker run est compatible avec des options supplémentaires.

  • --enable-mount-directory installe l'ensemble du système de fichiers dans le répertoire /transfer_root du conteneur. Si --enable-mount-directory est spécifié, les restrictions de répertoire à l'aide de l'option -v ne sont pas appliquées.

  • --enable-s3 indique que cet agent est destiné aux transferts à partir d'un espace de stockage compatible S3. Les agents installés avec cette option ne peuvent pas être utilisés pour les transferts à partir de systèmes de fichiers POSIX.

  • --creds-file=CREDENTIAL_FILE spécifie le chemin d'accès à un fichier d'identifiants de compte de service au format JSON. Sauf si vous utilisez --enable_mount_directory, vous devez:

    1. Installez le fichier d'identifiants à l'aide de l'option -v.
    2. Ajoutez le préfixe /transfer_root au chemin d'accès à --creds-file.

    Exemple :

    -v /tmp/key.json:/tmp/key.json \
--creds-file=/transfer_root/tmp/key.json

  • Si votre transfert provient d'un espace de stockage compatible avec AWS S3 ou S3, transmettez votre ID de clé d'accès et votre clé secrète à l'aide de variables d'environnement:

    -e AWS_ACCESS_KEY_ID=AWS_ACCESS_KEY_ID \
-e AWS_SECRET_ACCESS_KEY=AWS_SECRET_ACCESS_KEY

  • --env HTTPS_PROXY=PROXY spécifie un proxy de transfert sur votre réseau. La valeur de PROXY correspond à l'URL HTTP et au port du serveur proxy. Veillez à spécifier l'URL HTTP, et non une URL HTTPS, pour éviter d'encapsuler les requêtes en double dans le chiffrement TLS. Les requêtes encapsulées en double empêchent le serveur proxy d'envoyer des requêtes sortantes valides.

  • --agent-id-prefix=ID_PREFIX spécifie un préfixe facultatif ajouté à l'ID de l'agent pour aider à identifier cet agent ou sa machine dans Google Cloud Console. Lorsqu'un préfixe est utilisé, l'ID de l'agent est au format prefix + hostname + Docker container ID.

  • --log-dir=LOGS_DIRECTORY modifie le répertoire dans lequel l'agent écrit les journaux. Le répertoire par défaut est /tmp/.

    Si vous n'avez pas spécifié --enable_mount_directory, vous devez ajouter le préfixe /transfer_root à ce chemin. Exemple : /transfer_root/logs.

  • --max-physical-mem=MAX_MEMORY: les agents utilisent par défaut 8 Gio de mémoire système maximum. Si la valeur par défaut ne correspond pas à votre environnement, vous pouvez spécifier une utilisation de mémoire maximale appropriée en utilisant les formats suivants :

    Valeur max-physical-mem Paramètre de mémoire maximale
    6g 6 gigaoctets
    6gb 6 gigaoctets
    6GiB 6 gibioctets

Confirmer les connexions des agents

Après avoir installé vos agents de transfert, vous pouvez vérifier qu'ils sont connectés à votre pool d'agents.

Pour vérifier que vos agents sont bien connectés, procédez comme suit :

  1. Dans la console Google Cloud, accédez à la page Pools d'agents.

    Accéder aux pools d'agents

    Vos pools d'agents s'affichent, avec le nombre d'agents connectés.

  2. Sélectionnez un pool d'agents pour afficher les détails des agents connectés.

Si un nouvel agent n'apparaît pas sur la page du pool d'agents dans les dix minutes suivant sa création, consultez la section Les agents ne sont pas connectés.

Surveiller l'activité des agents

Vous pouvez surveiller l'activité des agents à l'aide des alertes Cloud Monitoring.

La surveillance est disponible avec les dimensions project, agent_pool et agent_id.

À l'aide de ces données de surveillance, vous pouvez configurer des alertes pour vous avertir des problèmes potentiels avec votre transfert. Pour ce faire, créez une alerte sur l'une des métriques Google Cloud suivantes :

Nom de la métrique Description Suggestions d'utilisation
storagetransfer.googleapis.com/agent/transferred_bytes_count Mesure la vitesse à laquelle un agent spécifique déplace des données (parmi toutes les tâches qu'il traite) à un instant donné. Alerte en cas de baisses de performances
storagetransfer.googleapis.com/agent/connected Valeur booléenne correspondant à True si un agent a récemment envoyé un message de pulsation à Google.
  • Alerte en cas d'agents défaillants
  • Chute du nombre d'agents sous un seuil que vous jugez nécessaire pour obtenir des performances raisonnables
  • Signalement d'un problème avec les machines agents

Arrêter un agent

Pour arrêter un agent, exécutez docker stop sur son ID de conteneur Docker. Pour trouver cet ID et arrêter l'agent, procédez comme suit:

  1. Dans la console Google Cloud, accédez à la page Pools d'agents.

    Accéder aux pools d'agents

  2. Sélectionnez le pool d'agents contenant l'agent à arrêter.

  3. Sélectionnez un agent dans la liste. Utilisez le champ Filtre pour rechercher suivant un préfixe, l'état de l'agent, l'âge de l'agent, etc.

  4. Cliquez sur Arrêter l'agent. La commande docker stop s'affiche avec l'ID de conteneur spécifique.

  5. Exécutez la commande sur la machine sur laquelles s'exécute l'agent. Si la commande docker stop réussit, l'ID du conteneur est renvoyé.

Une fois arrêté, l'agent apparaît dans la liste des agents du pool comme étant déconnecté.

Supprimer un agent

Pour supprimer des agents spécifiques, répertoriez ceux qui sont en cours d'exécution sur votre ordinateur :

docker container list --all --filter ancestor=gcr.io/cloud-ingest/tsop-agent

Transmettez ensuite les ID d'agent à transfer agents delete :

gcloud transfer agents delete --ids=id1,id2,…

Pour supprimer tous les agents exécutés sur la machine, utilisez l'option --all ou l'option --uninstall. Les deux options suppriment tous les agents de la machine. L'option --uninstall désinstalle également l'image Docker de l'agent.

gcloud transfer agents delete --all
gcloud transfer agents delete --uninstall

Détails du transfert du système de fichiers

Transferts incrémentiels

Le service de transfert de stockage commence tous les transferts en calculant les données présentes à la source et à la destination afin de déterminer quels fichiers sources sont nouveaux, mis à jour ou supprimés depuis le dernier transfert. Nous procédons ainsi afin de réduire la quantité de données envoyées depuis vos machines, d'utiliser efficacement la bande passante et de réduire les temps de transfert.

Pour détecter si un fichier a changé, nous utilisons un algorithme semblable à gsutil rsync : nous vérifions les date et heure de la dernière modification et la taille du fichier source, et les comparons à celles enregistrées date de la dernière copie du fichier. Lorsque nous détectons un fichier nouveau ou modifié, nous copions l'intégralité de ce fichier vers sa destination. Pour plus d'informations sur la fraîcheur des fichiers, consultez la section Détails sur la cohérence des données.

Par défaut, nous détectons, mais n'agissons pas sur, les fichiers supprimés sur la source. Si vous choisissez l'option de synchronisation Supprimer les fichiers de destination qui n'existent pas également dans la source lors de la création ou de la modification, le transfert supprime l'objet correspondant dans la destination.

Si vous choisissez l'option de synchronisation Supprimer les fichiers de destination qui n'existent pas également dans la source, les fichiers supprimés accidentellement dans la source le sont également dans la destination. Pour éviter toute perte de données due à des suppressions accidentelles, nous vous recommandons d'activer la gestion des versions d'objets dans votre bucket de destination. Par la suite, si vous supprimez accidentellement un fichier, vous pouvez restaurer une ancienne version de vos objets dans Cloud Storage.

Détails sur la cohérence des données

Une opération de transfert réussie transfère tous les fichiers sources existants et n'ayant pas été modifiés pendant toute la durée d'exécution de l'opération. Les fichiers sources qui ont été créés, mis à jour ou supprimés pendant un transfert pourraient ne pas refléter ces modifications dans l'ensemble de données de destination.

Le service de transfert de stockage utilise la date et l'heure de la dernière modification d'un fichier ainsi que sa taille pour déterminer s'il a été modifié. Si un fichier est mis à jour sans modifier sa date ou sa taille de dernière modification, et que vous activez l'option delete-objects-from-source, vous risquez de perdre les données de cette modification.

Lorsque vous utilisez la fonctionnalité delete-objects-from-source, nous vous recommandons vivement de geler les écritures sur la source pendant la durée du transfert afin d'éviter toute perte de données.

Pour geler les écritures sur votre source, effectuez l'une des opérations suivantes :

  • Clonez le répertoire que vous souhaitez transférer, puis utilisez le répertoire cloné en tant que source de transfert.
  • Arrêtez les applications qui écrivent dans le répertoire source.

S'il est important de capturer les modifications survenues lors d'un transfert, vous pouvez relancer le transfert ou définir le système de fichiers source en lecture seule pendant l'exécution de l'opération.

Étant donné que Cloud Storage n'a pas la notion de répertoires, les répertoires sources vides ne sont pas transférés.