Orchestrate jobs by running dsub pipelines on 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 tâches Open Source permettant d'orchestrer les workflows de traitement par lot sur Google Cloud. Pour en savoir plus sur l'utilisation de Batch avec dsub, consultez la 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 délai raisonnable.

Avant de commencer

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
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 dispose d'au moins un compte de service disposant des autorisations requises pour ce tutoriel.

    Remarque:Si vous utilisez un nouveau projet, cette étape n'est pas obligatoire sauf si votre organisation empêche les attributions automatiques de rôles aux comptes de service par défaut. 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 tâche nécessite un compte de service qui permet à l'agent de service de lot de créer et d'accéder aux ressources requises pour exécuter la tâche. Pour ce tutoriel, le compte de service de la tâche 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 autoriser l'agent de service Batch à créer et à 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:

    • Responsable du signalement d'agent par lot (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 également attribuer au compte de service par défaut Compute Engine les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

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

    Remarque:Si vous avez créé ce projet, cette étape n'est pas obligatoire. En tant que créateur du projet, vous disposez automatiquement du rôle IAM Propriétaire (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 les rôles IAM suivants:

    • Éditeur de tâches 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) pour 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 la procédure d'installation de Python.

    2. Recommandation: Pour éviter les erreurs de conflit de dépendances lors de l'installation de dsub, créez et activez un 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 de l'exemple de pipeline dsub à l'aide de la 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: nom unique au niveau mondial de votre bucket.

• PROJECT_ID: ID de 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: ID de projet de votre projet Google Cloud .

• BUCKET_NAME: nom du bucket 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 environ 10 minutes: le lot commence généralement à exécuter la tâche en quelques minutes, et la durée d'exécution de la tâche est d'environ huit minutes.

Au début, la commande est toujours en cours d'exécution, et la sortie ressemble à ceci:

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.

Une fois la tâche terminée, la commande se termine et le résultat ressemble à ce qui suit:

  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 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 du bucket 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 .

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 de la tâche.

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 les ressources individuelles 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 sur le compteGoogle Cloud actuel, procédez comme suit:

• 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 du bucket 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: ID de 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