Orchestrez 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 est destiné 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 de Batch sur dsub.

Objectifs

exécuter un pipeline dsub sur Batch, qui lit et écrit des fichiers dans des buckets Cloud Storage ;
Affichez les fichiers de sortie dans un bucket Cloud Storage.

Coûts

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

Lot
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 les délais impartis.

Avant de commencer

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.

Installez Google Cloud CLI.

Pour initialiser gcloudCLI, exécutez la commande suivante :

gcloud init

Créez ou sélectionnez un projet Google Cloud.

Créez un projet Google Cloud :
```
gcloud projects create PROJECT_ID
```
Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.
Sélectionnez le projet Google Cloud que vous avez créé :
```
gcloud config set project PROJECT_ID
```
Remplacez PROJECT_ID par le nom de votre projet Google Cloud.

Vérifiez que la facturation est activée pour votre projet Google Cloud.

Activer les API Batch, Cloud Storage, Compute Engine, and Logging :

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

Installez Google Cloud CLI.

Pour initialiser gcloudCLI, exécutez la commande suivante :

gcloud init

Créez ou sélectionnez un projet Google Cloud.

Créez un projet Google Cloud :
```
gcloud projects create PROJECT_ID
```
Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.
Sélectionnez le projet Google Cloud que vous avez créé :
```
gcloud config set project PROJECT_ID
```
Remplacez PROJECT_ID par le nom de votre projet Google Cloud.

Vérifiez que la facturation est activée pour votre projet Google Cloud.

Activer les API Batch, Cloud Storage, Compute Engine, and Logging :

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

Assurez-vous que votre projet comporte 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 nécessaire sauf si votre organisation empêche l'attribution automatique de rôles pour les comptes de service par défaut. Par défaut, le compte de service Compute Engine par défaut reçoit 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 permettant à l'agent de service Batch de créer les ressources requises pour exécuter la tâche et d'y accéder. 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 permettre à l'agent de service Batch de créer des ressources pour les jobs Batch et d'y accéder, demandez à votre administrateur d'accorder au compte de service Compute Engine par défaut les rôles IAM suivants:
- Auteur du signalement de l'agent par lot (roles/batch.agentReporter) au niveau du projet
- Administrateur de l'espace de stockage (roles/storage.admin) pour le projet
- (Recommandé) Laissez les jobs 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 section Gérer les accès.

Votre administrateur peut également accorder les autorisations requises au compte de service Compute Engine par défaut via des rôles personnalisés ou d'autres rôles prédéfinis.

Assurez-vous de disposer des autorisations nécessaires pour ce tutoriel.

Remarque:Si vous avez créé ce projet, cette étape n'est pas nécessaire. En tant que créateur du projet, le rôle IAM Propriétaire (roles/owner) vous est automatiquement attribué, 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 attribuer 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

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

Assurez-vous d'avoir installé des versions de Python et 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.
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
```

Clonez le dépôt GitHub dsub à l'aide de git, puis ouvrez-le:

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

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 destiné à stocker les fichiers de sortie de l'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: nom unique pour 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'option --input.

La commande ne se termine qu'à la fin de l'exécution du pipeline dsub, ce qui peut varier en fonction de la date de planification de la tâche par lot. En général, cela prend environ 10 minutes. Batch commence généralement à exécuter la tâche en quelques minutes, et son exécution dure environ huit minutes.

Au début, la commande est toujours en cours d'exécution 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 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 aura les effets suivants :

Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour les tâches de ce document, lorsque vous le supprimez, vous supprimez é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.

Supprimez un projet Google Cloud :

gcloud projects delete PROJECT_ID

Supprimer des ressources individuelles

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

Supprimer le bucket

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

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

Si vous n'avez plus besoin du bucket que vous avez utilisé dans ce tutoriel, exécutez la commande gcloud storage rm avec l'option --recursive pour le supprimer 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, exécutez 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.

Étapes suivantes

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

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

Objectifs

Coûts

Avant de commencer

Créer un bucket Cloud Storage

Exécuter le pipeline dsub

Afficher les fichiers de sortie

Effectuer un nettoyage

Supprimer le projet

Supprimer des ressources individuelles

Supprimer le bucket

Supprimer le job

Étapes suivantes

Exécuter le pipeline `dsub`