Gérer les agents de transfert

Les agents du service de transfert de stockage sont des applications exécutées dans un conteneur Open Container Initiative (OCI) qui se coordonnent avec le service de transfert de stockage pour les transferts impliquant des systèmes de fichiers ou un espace de stockage compatible S3.

Par défaut, service de transfert de stockage utilise Docker pour créer et exécuter des conteneurs OCI. Le service de transfert de stockage est également compatible avec Podman pour la gestion des conteneurs. Vous devez installer vos agents à l'aide de la commande podman run pour utiliser Podman.

Si le transfert n'implique pas de système de fichiers ni de stockage compatible S3, 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 section Optimiser les performances de l'agent de transfert.

N'incluez pas d'informations sensibles telles que des informations permettant d'identifier personnellement l'utilisateur ou des données de sécurité dans le préfixe de votre ID d'agent. Les noms de ressources peuvent être propagés aux noms d'autres ressources Google Cloud et peuvent être exposés à des systèmes internes à Google en dehors de votre projet.

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 une virgule, auxquels accorder l'accès à l'agent. Si vous omettez cet indicateur, l'ensemble du système de fichiers est installé sur le conteneur de l'agent. Pour en savoir plus, consultez la documentation de référence sur gcloud.

Sources compatibles S3

Lorsque vous installez des agents à utiliser avec une source compatible avec S3, vous devez fournir les identifiants AWS, qui vont être des variables d'environnement utilisées comme valeurs pour AWS_ACCESS_KEY_ID et AWS_SECRET_ACCESS_KEY, ou bien qui vont être stockés en tant qu'identifiants par défaut dans les fichiers de configuration de votre système.

export AWS_ACCESS_KEY_ID=ID
export AWS_SECRET_ACCESS_KEY=SECRET
gcloud transfer agents install --pool=POOL_NAME \
  --creds-file=/relative/path/to/service-account-key.json

Utiliser une clé de compte de service

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

Plus d'infos

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

Avant d'utiliser Docker 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 cette commande autant de fois que nécessaire.

Lorsque vous installez des agents, vous pouvez choisir de vous authentifier à l'aide de vos identifiants par défaut gcloud ou avec un compte de service.

Identifiants par défaut

Pour que le conteneur Docker puisse s'authentifier avec vos identifiants par défaut gcloud, créez un volume Docker contenant un fichier qui inclut les identifiants par défaut de l'application en exécutant la commande suivante:

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

Utilisez ensuite la commande suivante pour installer un agent, en utilisant l'option --volumes-from pour monter 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 par compte de service

Pour installer et exécuter des agents de transfert docker run à l'aide d'identifiants de compte de service, spécifiez le chemin d'accès à votre clé de compte de service au format JSON à l'aide de l'indicateur --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 des 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 d'autres répertoires à partir desquels effectuer la copie.
  • CONTAINER_DIRECTORY est le répertoire mappé dans le conteneur de l'agent. Elle doit être identique à HOST_DIRECTORY.
  • PROJECT_ID correspond à l'ID du projet qui héberge le transfert.
  • POOL_NAME correspond au nom du pool d'agents dans lequel installer cet agent. Si vous omettez cet indicateur, l'agent est installé dans le pool transfer_service_default de votre projet.

La commande docker run accepte 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 utilisant l'indicateur -v ne sont pas appliquées.

  • --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. Montez le fichier d'identifiants à l'aide de l'indicateur -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

  • --enable-s3 spécifie 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.

  • Si votre transfert provient d'un stockage AWS S3 ou compatible 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 transmission sur votre réseau. La valeur de PROXY correspond à l'URL et au port HTTP du serveur proxy. Veillez à spécifier l'URL HTTP, et non une URL HTTPS, afin d'éviter l'encapsulation en double des requêtes 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 l'agent ou sa machine dans la console Google Cloud. Lorsqu'un préfixe est utilisé, l'ID de l'agent possède le format suivant : 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 d'accès. Exemple : /transfer_root/logs.

  • --max-physical-mem=MAX_MEMORY: les agents utilisent par défaut 8 Gio de mémoire système au 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

Podman

Avant d'utiliser Podman pour installer des agents, installez Podman:

sudo apt-get update
sudo apt-get -y install podman

Lorsque vous installez des agents, vous pouvez choisir de vous authentifier à l'aide de vos identifiants par défaut gcloud ou avec un compte de service.

Identifiants par défaut

Pour autoriser le conteneur de l'agent à s'authentifier avec vos identifiants par défaut Google Cloud CLI, créez un volume contenant un fichier avec les identifiants par défaut de votre application en exécutant la commande suivante:

  gcloud auth print-access-token | podman login -u oauth2accesstoken --password-stdin gcr.io
  sudo podman pull gcr.io/google.com/cloudsdktool/google-cloud-cli:stable
  sudo podman run -ti --replace --name gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud auth application-default login
  ```

Then use the following command to install an agent, using the
`--volumes-from` flag to mount the `gcloud-config` credentials volume.
The command installs one agent. To increase the number of agents in your
pool, re-run this command as many times as required.

```sh
  sudo podman 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 par compte de service

Pour installer et exécuter des agents de transfert à l'aide d'identifiants de compte de service, spécifiez le chemin d'accès à votre clé de compte de service au format JSON à l'aide de l'indicateur --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 des clés de compte de service.

sudo podman 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 d'autres répertoires à partir desquels effectuer la copie.
  • CONTAINER_DIRECTORY est le répertoire mappé dans le conteneur de l'agent. Elle doit être identique à HOST_DIRECTORY.
  • PROJECT_ID correspond à l'ID du projet qui héberge le transfert.
  • POOL_NAME correspond au nom du pool d'agents dans lequel installer cet agent. Si vous omettez cet indicateur, l'agent est installé dans le pool transfer_service_default de votre projet.

La commande podman run accepte 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 utilisant l'indicateur -v ne sont pas appliquées.

  • --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. Montez le fichier d'identifiants à l'aide de l'indicateur -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

  • --enable-s3 spécifie 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.

  • Si votre transfert provient d'un stockage AWS S3 ou compatible 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 transmission sur votre réseau. La valeur de PROXY correspond à l'URL et au port HTTP du serveur proxy. Veillez à spécifier l'URL HTTP, et non une URL HTTPS, afin d'éviter l'encapsulation en double des requêtes 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 l'agent ou sa machine dans la console Google Cloud. Lorsqu'un préfixe est utilisé, l'ID de l'agent possède le format suivant : prefix + hostname + OCI 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 d'accès. Exemple : /transfer_root/logs.

  • --max-physical-mem=MAX_MEMORY: les agents utilisent par défaut 8 Gio de mémoire système au 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

Dépannage

Si votre configuration de SELinux exige que des libellés soient placés sur le contenu du volume installé dans un conteneur, ajoutez l'indicateur :Z au volume:

sudo podman run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY:Z \
-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

Sans libellé, le système de sécurité peut empêcher les processus exécutés dans le conteneur d'utiliser le contenu. Par défaut, Podman ne modifie pas les libellés définis par l'OS.

Confirmer les connexions des 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 de 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 vérifions la date et l'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 en savoir plus 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.