Orchestrer des jobs en exécutant des pipelines dsub sur Batch

---

Ce tutoriel explique comment exécuter un pipeline dsub sur Batch. Plus précisément, l'exemple de pipeline dsub traite les données de séquençage de l'ADN dans un fichier BAM (Binary Alignment Map) pour créer un fichier d'index BAM (BAI).

Ce tutoriel s'adresse aux utilisateurs de Batch qui souhaitent utiliser dsub avec Batch. dsub est un planificateur de jobs Open Source pour orchestrer des workflows de traitement par lot sur Google Cloud. Pour en savoir plus sur la façon d’utiliser avec dsub, consultez les Documentation dsub pour Batch.

Objectifs

• Exécutez un pipeline dsub sur Batch qui lit et écrit des fichiers dans des buckets Cloud Storage.
• Afficher les fichiers de sortie dans un bucket Cloud Storage

Coûts

Dans ce document, vous utilisez les composants facturables suivants de Google Cloud :

• Batch
• Cloud Storage

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût. Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai gratuit.

Les ressources créées dans ce tutoriel coûtent généralement moins d'un dollar, en supposant que vous effectuiez toutes les étapes, y compris le nettoyage, dans un dans les meilleurs délais.

Avant de commencer

1. Connectez-vous à votre compte Google Cloud. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.
2. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

5. Make sure that billing is enabled for your Google Cloud project.

6. Enable the Batch, Cloud Storage, Compute Engine, and Logging APIs:

   gcloud services enable batch.googleapis.com compute.googleapis.com logging.googleapis.com storage.googleapis.com

7. Install the Google Cloud CLI.

8. To initialize the gcloud CLI, run the following command:

   gcloud init

9. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

10. Make sure that billing is enabled for your Google Cloud project.

11. Enable the Batch, Cloud Storage, Compute Engine, and Logging APIs:

    gcloud services enable batch.googleapis.com compute.googleapis.com logging.googleapis.com storage.googleapis.com

12. Assurez-vous que votre projet comporte au moins un compte de service avec le requises pour ce tutoriel.

    Remarque:Si vous utilisez un nouveau projet, cette étape n'est pas obligatoire. sauf votre organisation empêche l'attribution automatique de rôles pour le service par défaut Google Cloud. Par défaut, le compte de service Compute Engine par défaut se voit attribuer automatiquement le rôle IAM Éditeur (roles/editor), qui dispose déjà de toutes les autorisations requises pour ce tutoriel.

    Chaque job nécessite un compte de service qui autorise Agent de service Batch pour créer les ressources et y accéder nécessaires à l'exécution du job. Dans ce tutoriel, le compte de service du job est le Compte de service Compute Engine par défaut.

    Pour vous assurer que le compte de service Compute Engine par défaut dispose des autorisations nécessaires pour permettre à l'agent de service Batch de créer et d'accéder aux ressources pour les tâches Batch, demandez à votre administrateur d'accorder au compte de service Compute Engine par défaut les rôles IAM suivants :

    • Batch Agent Reporter (roles/batch.agentReporter) sur le projet
    • Administrateur de l'espace de stockage (roles/storage.admin) sur le projet
    • (Recommandé) Autorisez les tâches à générer des journaux dans Cloud Logging : Rédacteur de journaux (roles/logging.logWriter) sur le projet

    Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

    Votre administrateur peut aussi attribuer au compte de service Compute Engine par défaut les autorisations requises à l'aide d'outils personnalisés rôles ou autres prédéfinis rôles.

13. Assurez-vous de disposer des autorisations requises pour ce tutoriel.

    Remarque:Si vous avez créé ce projet, cette étape n'est pas obligatoire. En tant que le rôle de propriétaire du projet, le rôle (roles/owner), qui dispose déjà de toutes les autorisations requises pour ce tutoriel.

    Pour obtenir les autorisations nécessaires pour suivre ce tutoriel, demandez à votre administrateur de vous accorder le rôles IAM suivants:

    • Éditeur de jobs par lot (roles/batch.jobsEditor) sur le projet
    • Utilisateur du compte de service (roles/iam.serviceAccountUser) sur le compte de service de la tâche, qui, pour ce tutoriel, est le compte de service Compute Engine par défaut
    • Administrateur des objets Storage (roles/storage.objectAdmin) sur le projet

14. Installez dsub et ses dépendances. Pour en savoir plus, consultez la documentation d'installation de dsub.

    1. Assurez-vous d'avoir installé les versions de Python et de pip compatibles avec la dernière version de dsub. Pour afficher les versions actuellement installées, exécutez la commande suivante:

       pip --version
       

       Si vous devez installer ou mettre à jour pip ou Python, suivez les étapes d'installation de Python.

    2. Recommandation: Pour éviter les erreurs de conflit de dépendances lors de l'installation de dsub, créer et activer Environnement virtuel Python:

       python -m venv dsub_libs && source dsub_libs/bin/activate
       

    3. Clonez le dépôt GitHub dsub à l'aide de git et ouvrez-le:

       git clone https://github.com/databiosphere/dsub.git && cd dsub
       

    4. Installez dsub et ses dépendances :

       python -m pip install .
       

       Le résultat ressemble à ce qui suit :

       ...
       Successfully installed cachetools-5.3.1 certifi-2023.7.22 charset-normalizer-3.3.1 dsub-0.4.9 funcsigs-1.0.2 google-api-core-2.11.0 google-api-python-client-2.85.0 google-auth-2.17.3 google-auth-httplib2-0.1.0 google-cloud-batch-0.10.0 googleapis-common-protos-1.61.0 grpcio-1.59.0 grpcio-status-1.59.0 httplib2-0.22.0 idna-3.4 mock-4.0.3 parameterized-0.8.1 proto-plus-1.22.3 protobuf-4.24.4 pyasn1-0.4.8 pyasn1-modules-0.2.8 pyparsing-3.1.1 python-dateutil-2.8.2 pytz-2023.3 pyyaml-6.0 requests-2.31.0 rsa-4.9 six-1.16.0 tabulate-0.9.0 tenacity-8.2.2 uritemplate-4.1.1 urllib3-2.0.7
       

Créer un bucket Cloud Storage

Pour créer un bucket Cloud Storage afin de stocker les fichiers de sortie du exemple de pipeline dsub à l'aide de gcloud CLI, exécutez la Commande gcloud storage buckets create:

gcloud storage buckets create gs://BUCKET_NAME \
    --project PROJECT_ID

Remplacez les éléments suivants :

• BUCKET_NAME: a nom unique global pour votre bucket.

• PROJECT_ID: le ID du projet de votre projet Google Cloud.

Le résultat ressemble à ce qui suit :

Creating gs://BUCKET_NAME/...

Exécuter le pipeline dsub

L'exemple de pipeline dsub indexe un fichier BAM du projet 1 000 Génomes et génère les résultats dans un bucket Cloud Storage.

Pour exécuter l'exemple de pipeline dsub, exécutez la commande dsub suivante :

dsub \
    --provider google-batch \
    --project PROJECT_ID \
    --logging gs://BUCKET_NAME/WORK_DIRECTORY/logs \
    --input BAM=gs://genomics-public-data/1000-genomes/bam/HG00114.mapped.ILLUMINA.bwa.GBR.low_coverage.20120522.bam \
    --output BAI=gs://BUCKET_NAME/WORK_DIRECTORY/HG00114.mapped.ILLUMINA.bwa.GBR.low_coverage.20120522.bam.bai \
    --image quay.io/cancercollaboratory/dockstore-tool-samtools-index \
    --command 'samtools index ${BAM} ${BAI}' \
    --wait

Remplacez les éléments suivants :

• PROJECT_ID: le ID du projet de votre projet Google Cloud.

• BUCKET_NAME: nom de l'instance Cloud Storage que vous avez créé.

• WORK_DIRECTORY : nom d'un nouveau répertoire que le pipeline peut utiliser pour stocker les journaux et les sorties. Par exemple, saisissez workDir.

Le pipeline dsub exécute une tâche par lot qui écrit le fichier BAI et les journaux dans le répertoire spécifié de votre bucket Cloud Storage. Plus précisément, le dépôt dsub contient une image Docker prédéfinie qui utilise samtools pour indexer le fichier BAM que vous avez spécifié dans l'indicateur --input.

La commande ne se termine pas tant que le pipeline dsub n'a pas terminé son exécution, ce qui peut varier en fonction de la date et de l'heure de planification de la tâche de traitement par lot. Cela prend généralement 10 minutes: le traitement par lot le job s'exécute en quelques minutes. Son exécution dure environ 8 minutes.

Au début, la commande s'exécute toujours et le résultat ressemble à ce qui suit:

Job properties:
  job-id: JOB_NAME
  job-name: samtools
  user-id: USERNAME
Provider internal-id (operation): projects/PROJECT_ID/locations/us-central1/jobs/JOB_NAME
Launched job-id: JOB_NAME
To check the status, run:
  dstat --provider google-batch --project PROJECT_ID --location us-central1 --jobs 'JOB_NAME' --users 'USERNAME' --status '*'
To cancel the job, run:
  ddel --provider google-batch --project PROJECT_ID --location us-central1 --jobs 'JOB_NAME' --users 'USERNAME'
Waiting for job to complete...
Waiting for: JOB_NAME.

Ensuite, une fois la tâche terminée, la commande s'arrête et la sortie ressemble à ceci:

  JOB_NAME: SUCCESS
JOB_NAME

Ce résultat inclut les valeurs suivantes :

• JOB_NAME: nom de la tâche.

• USERNAME : votre nom d'utilisateur Google Cloud.

• PROJECT_ID : ID de projet de votre projet Google Cloud.

Afficher les fichiers de sortie

Pour afficher les fichiers de sortie créés par l'exemple de pipeline dsub à l'aide de la méthode gcloud CLI, exécutez la Commande gcloud storage ls:

gcloud storage ls gs://BUCKET_NAME/WORK_DIRECTORY \
    --project PROJECT_ID

Remplacez les éléments suivants :

• BUCKET_NAME: nom de l'instance Cloud Storage que vous avez créé.

• WORK_DIRECTORY: répertoire que vous avez spécifié la commande dsub.

• PROJECT_ID : ID de projet de votre projet Google Cloud.

Le résultat ressemble à ce qui suit :

gs://BUCKET_NAME/WORK_DIRECTORY/HG00114.mapped.ILLUMINA.bwa.GBR.low_coverage.20120522.bam.bai
gs://BUCKET_NAME/WORK_DIRECTORY/logs/

Cette sortie inclut le fichier BAI et un répertoire contenant les journaux du job.

Effectuer un nettoyage

Pour éviter que les ressources utilisées lors de ce tutoriel soient facturées sur votre compte Google Cloud, supprimez le projet contenant les ressources, ou conservez le projet et supprimez les ressources individuelles.

Supprimer le projet

Le moyen le plus simple d'éviter la facturation consiste à supprimer le projet en cours.

Attention : La suppression d'un projet entraîne les effets décrits ci-dessous :

• Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour les tâches décrites dans ce document et que vous le supprimez, vous supprimerez également tout autre travail effectué dans le projet.
• Les ID de projets personnalisés sont perdus. Lorsque vous avez créé ce projet, vous avez peut-être créé un ID de projet personnalisé que vous souhaitez utiliser à l'avenir. Pour conserver les URL qui utilisent l'ID de projet, telle qu'une URL appspot.com, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.

Si vous envisagez d'explorer plusieurs architectures, tutoriels et guides de démarrage rapide, réutiliser des projets peut vous aider à ne pas dépasser les limites de quotas des projets.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Supprimer des ressources individuelles

Si vous souhaitez continuer à utiliser le projet actuel, supprimez l'utilisateur les ressources utilisées dans ce tutoriel.

Supprimer le bucket

Une fois l'exécution du pipeline terminée, il crée et stocke des fichiers de sortie dans le répertoire WORK_DIRECTORY de votre bucket Cloud Storage.

Pour réduire les frais Cloud Storage compte Google Cloud, effectuez l'une des opérations suivantes:

• Si vous n'avez plus besoin du bucket que vous avez utilisé dans ce tutoriel, utilisez la Commande gcloud storage rm avec l'option --recursive pour supprimer le bucket et tout son contenu:

  gcloud storage rm gs://BUCKET_NAME \
      --recursive \
      --project PROJECT_ID
  

  Remplacez les éléments suivants :

  • BUCKET_NAME : nom du bucket Cloud Storage que vous avez créé.

  • PROJECT_ID : ID de projet de votre projet Google Cloud.

• Sinon, si vous avez toujours besoin du bucket, utilisez la commande gcloud storage rm avec l'option --recursive pour ne supprimer que le répertoire WORK_DIRECTORY et tout son contenu :

  gcloud storage rm gs://BUCKET_NAME/WORK_DIRECTORY \
      --recursive \
      --project PROJECT_ID
  

  Remplacez les éléments suivants :

  • BUCKET_NAME: nom de l'instance Cloud Storage que vous avez créé.

  • WORK_DIRECTORY : répertoire que vous avez spécifié dans la commande dsub.

  • PROJECT_ID : ID de projet de votre projet Google Cloud.

Supprimer le job

Pour supprimer une tâche à l'aide de gcloud CLI, exécutez la commande gcloud batch jobs delete.

gcloud batch jobs delete JOB_NAME \
    --location us-central1 \
    --project PROJECT_ID

Remplacez les éléments suivants :

• JOB_NAME: nom de la tâche.
• PROJECT_ID: le ID du projet de votre projet Google Cloud.

Étape suivante

• En savoir plus sur dsub et dsub pour Batch.
• En savoir plus sur l'utilisation de volumes de stockage avec Batch