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 savoir comment utiliser 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.
  • Affichez 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

Pour obtenir une estimation des coûts en fonction de votre utilisation prévue, utilisez le simulateur de coût.

Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai sans frais.

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, en temps opportun.

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 sans frais pour exécuter, tester et déployer des charges de travail.

  2. Installez la Google Cloud CLI.

  3. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  4. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init

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

    Rôles requis pour sélectionner ou créer un projet

    • Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
    • Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

    • 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 .

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

  7. Activez les API Batch, Cloud Storage, Compute Engine et Logging :

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles. 

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

  8. Installez la Google Cloud CLI.

  9. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  10. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init

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

    Rôles requis pour sélectionner ou créer un projet

    • Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
    • Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

    • 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 .

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

  13. Activez les API Batch, Cloud Storage, Compute Engine et Logging :

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles. 

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

  14. Assurez-vous que votre projet dispose d'au moins un compte de service avec les autorisations requises pour ce tutoriel.

    Chaque job nécessite un compte de service qui permet à l'agent de service Batch de créer et d'accéder aux ressources nécessaires à l'exécution du job. Pour 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 du service Batch de créer des ressources pour les jobs Batch et d'y accéder, demandez à votre administrateur d'accorder les rôles IAM suivants au compte de service Compute Engine par défaut :

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

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

  15. Assurez-vous de disposer des 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 :

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

    1. Assurez-vous d'avoir installé des 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é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 du pipeline dsub exemple à 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 :

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 1000 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 un job 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 que lorsque le pipeline dsub a fini de s'exécuter, ce qui peut varier en fonction de la date de planification du job Batch. Cela prend généralement environ 10 minutes : Batch commence généralement à exécuter le job en quelques minutes, et la durée d'exécution du job est d'environ 8 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.

Une fois le job terminé, la commande se termine et le résultat est semblable à ce qui suit :

  JOB_NAME: SUCCESS
JOB_NAME

Ce résultat inclut les valeurs suivantes :

  • JOB_NAME : nom du job.

  • USERNAME : votre Google Cloud nom d'utilisateur.

  • 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 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'empêcher la facturation est de supprimer le projet actuel.

    Supprimer un projet Google Cloud  :

    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 le pipeline exécuté, 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, effectuez l'une des opérations suivantes :

  • Si vous n'avez plus besoin du bucket utilisé dans ce tutoriel, exécutez la commande gcloud storage rm avec le flag --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 encore besoin du bucket, utilisez la commande gcloud storage rm avec l'option --recursive pour supprimer uniquement 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 un job à 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 du job.
  • PROJECT_ID : ID de projet de votre projet Google Cloud .

Étapes suivantes