Melakukan orkestrasi tugas dengan menjalankan pipeline dsub di Batch

Tutorial ini menjelaskan cara menjalankan pipeline dsub di Batch. Secara khusus, pipeline dsub contoh memproses data pengurutan DNA dalam file Binary Alignment Map (BAM) untuk membuat file indeks BAM (BAI).

Tutorial ini ditujukan bagi pengguna Batch yang ingin menggunakan dsub dengan Batch. dsub adalah penjadwal tugas open source untuk mengorkestrasi alur kerja batch processing di Google Cloud. Untuk mempelajari lebih lanjut cara menggunakan Batch dengan dsub, lihat dokumentasi dsub untuk Batch.

Tujuan

• Jalankan pipeline dsub di Batch yang membaca dan menulis file di bucket Cloud Storage.
• Lihat file output di bucket Cloud Storage.

Biaya

Dalam dokumen ini, Anda akan menggunakan komponen Google Cloudyang dapat ditagih berikut:

• Batch
• Cloud Storage

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga.

Pengguna Google Cloud baru mungkin memenuhi syarat untuk mendapatkan uji coba gratis.

Resource yang dibuat dalam tutorial ini biasanya berbiaya kurang dari satu dolar, dengan asumsi Anda menyelesaikan semua langkah—termasuk pembersihan—secara tepat waktu.

Sebelum memulai

Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

Instal Google Cloud CLI.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

Buat atau pilih Google Cloud project.

Peran yang diperlukan untuk memilih atau membuat project

• Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
• Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

• Buat Google Cloud project:

  gcloud projects create PROJECT_ID

  Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

• Pilih project Google Cloud yang Anda buat:

  gcloud config set project PROJECT_ID

  Ganti PROJECT_ID dengan nama project Google Cloud Anda.

Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

Aktifkan Batch, Cloud Storage, Compute Engine, dan Logging API:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

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

Instal Google Cloud CLI.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

Buat atau pilih Google Cloud project.

Peran yang diperlukan untuk memilih atau membuat project

• Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
• Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

• Buat Google Cloud project:

  gcloud projects create PROJECT_ID

  Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

• Pilih project Google Cloud yang Anda buat:

  gcloud config set project PROJECT_ID

  Ganti PROJECT_ID dengan nama project Google Cloud Anda.

Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

Aktifkan Batch, Cloud Storage, Compute Engine, dan Logging API:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

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

1. Pastikan project Anda memiliki setidaknya satu akun layanan dengan izin yang diperlukan untuk tutorial ini.

   Catatan: Jika Anda menggunakan project baru, langkah ini tidak diperlukan kecuali organisasi Anda mencegah pemberian peran otomatis untuk akun layanan default. Secara default, akun layanan default Compute Engine secara otomatis diberi peran IAM Editor (roles/editor), yang sudah memiliki semua izin yang diperlukan untuk tutorial ini.

   Setiap tugas memerlukan akun layanan yang memungkinkan agen layanan Batch membuat dan mengakses resource yang diperlukan untuk menjalankan tugas. Untuk tutorial ini, akun layanan tugas adalah akun layanan default Compute Engine.

   Untuk memastikan bahwa akun layanan default Compute Engine memiliki izin yang diperlukan agar agen layanan Batch dapat membuat dan mengakses resource untuk tugas Batch, minta administrator Anda untuk memberikan peran IAM berikut kepada akun layanan default Compute Engine:

   Penting: Anda harus memberikan peran ini ke akun layanan default Compute Engine, bukan ke akun pengguna Anda. Kegagalan memberikan peran ke akun utama yang benar dapat menyebabkan error izin.
   • Batch Agent Reporter (roles/batch.agentReporter) di project
   • Storage Admin (roles/storage.admin) di project
   • (Direkomendasikan) Izinkan tugas membuat log di Cloud Logging: Logs Writer (roles/logging.logWriter) di project

   Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

   Administrator Anda mungkin juga dapat memberikan izin yang diperlukan kepada akun layanan default Compute Engine melalui peran khusus atau peran bawaan lainnya.

2. Pastikan Anda memiliki izin yang diperlukan untuk tutorial ini.

   Catatan: Jika Anda membuat project ini, langkah ini tidak diperlukan. Sebagai pembuat project, Anda otomatis diberi peran IAM Pemilik (roles/owner), yang sudah memiliki semua izin yang diperlukan untuk tutorial ini.

   Untuk mendapatkan izin yang Anda perlukan untuk menyelesaikan tutorial ini, minta administrator Anda untuk memberi Anda peran IAM berikut:

   • Batch Job Editor (roles/batch.jobsEditor) di project
   • Pengguna Akun Layanan (roles/iam.serviceAccountUser) di akun layanan tugas, yang untuk tutorial ini adalah akun layanan default Compute Engine
   • Storage Object Admin (roles/storage.objectAdmin) di project

3. Instal dsub dan dependensinya. Untuk mengetahui informasi selengkapnya, lihat dokumentasi penginstalan dsub.

   1. Pastikan Anda telah menginstal versi Python dan pip yang didukung oleh dsub versi terbaru. Untuk melihat versi yang saat ini diinstal, jalankan perintah berikut:

      pip --version
      

      Jika Anda perlu menginstal atau mengupdate pip atau Python, ikuti langkah-langkah untuk menginstal Python.

   2. Direkomendasikan: Untuk mencegah error konflik dependensi saat menginstal dsub, buat dan aktifkan lingkungan virtual Python:

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

   3. Clone repositori GitHub dsub menggunakan git dan buka:

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

   4. Instal dsub dan dependensinya:

      python -m pip install .
      

      Outputnya mirip dengan hal berikut ini:

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

Membuat bucket Cloud Storage

Untuk membuat bucket Cloud Storage guna menyimpan file output dari pipeline dsub contoh menggunakan gcloud CLI, jalankan perintah gcloud storage buckets create:

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

Ganti kode berikut:

• BUCKET_NAME: nama unik secara global untuk bucket Anda.

• PROJECT_ID: Project ID project Google Cloud Anda.

Outputnya mirip dengan hal berikut ini:

Creating gs://BUCKET_NAME/...

Menjalankan pipeline dsub

Pipeline contoh dsub mengindeks file BAM dari 1.000 Genomes Project dan menampilkan hasilnya ke bucket Cloud Storage.

Untuk menjalankan pipeline dsub contoh, jalankan perintah dsub berikut:

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

Ganti kode berikut:

• PROJECT_ID: Project ID project Google Cloud Anda.

• BUCKET_NAME: nama bucket Cloud Storage yang Anda buat.

• WORK_DIRECTORY: nama untuk direktori baru yang dapat digunakan pipeline untuk menyimpan log dan output. Misalnya, masukkan workDir.

Pipeline dsub menjalankan tugas Batch yang menulis file BAI dan mencatat ke direktori yang ditentukan di bucket Cloud Storage Anda. Secara khusus, repositori dsub berisi image Docker yang telah dibuat sebelumnya yang menggunakan samtools untuk mengindeks file BAM yang Anda tentukan dalam tanda --input.

Perintah tidak akan selesai hingga pipeline dsub selesai berjalan, yang mungkin bervariasi berdasarkan waktu penjadwalan tugas Batch. Biasanya, proses ini memerlukan waktu sekitar 10 menit: Batch biasanya mulai menjalankan tugas dalam beberapa menit, dan runtime tugas sekitar 8 menit.

Pada awalnya, perintah masih berjalan dan outputnya mirip dengan berikut ini:

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.

Kemudian, setelah tugas berhasil diselesaikan, perintah akan berakhir dan outputnya akan terlihat seperti berikut:

  JOB_NAME: SUCCESS
JOB_NAME

Output ini mencakup nilai-nilai berikut:

• JOB_NAME: nama tugas.

• USERNAME: Google Cloud nama pengguna Anda.

• PROJECT_ID: Project ID project Google Cloud Anda.

Melihat file output

Untuk melihat file output yang dibuat oleh pipeline dsub contoh menggunakan gcloud CLI, jalankan perintah gcloud storage ls:

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

Ganti kode berikut:

• BUCKET_NAME: nama bucket Cloud Storage yang Anda buat.

• WORK_DIRECTORY: direktori yang Anda tentukan dalam perintah dsub.

• PROJECT_ID: Project ID project Google Cloud Anda.

Outputnya mirip dengan hal berikut ini:

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

Output ini mencakup file BAI dan direktori yang berisi log tugas.

Pembersihan

Agar tidak perlu membayar biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam tutorial ini, hapus project yang berisi resource tersebut, atau simpan project dan hapus setiap resource.

Menghapus project

Cara termudah untuk menghilangkan penagihan adalah dengan menghapus project saat ini.

Perhatian: Penghapusan project memiliki efek berikut:

• Semua hal dalam project akan dihapus. Jika Anda menggunakan project yang ada untuk mengerjakan tugas di dokumen ini, saat Anda menghapusnya, pekerjaan lain dalam project tersebut juga akan dihapus.
• Project ID kustom akan hilang. Saat membuat project ini, Anda mungkin juga membuat project ID kustom yang masih ingin digunakan pada masa mendatang. Agar tidak kehilangan URL yang menggunakan project ID tersebut, seperti URL appspot.com, hapus resource yang dipilih di dalam project, bukan menghapus seluruh project.

Jika Anda berencana mempelajari beberapa arsitektur, tutorial atau panduan memulai, dengan menggunakan kembali project dapat membantu Anda agar tidak melampaui batas kuota project.

Menghapus Google Cloud project:

gcloud projects delete PROJECT_ID

Menghapus resource satu per satu

Jika Anda ingin terus menggunakan project saat ini, hapus setiap resource yang digunakan dalam tutorial ini.

Menghapus bucket

Setelah pipeline selesai berjalan, pipeline akan membuat dan menyimpan file output di direktori WORK_DIRECTORY bucket Cloud Storage Anda.

Untuk mengurangi biaya Cloud Storage ke akun Google Cloud saat ini, lakukan salah satu hal berikut:

• Jika Anda tidak lagi memerlukan bucket yang digunakan dalam tutorial ini, maka gunakan perintah gcloud storage rm dengan flag --recursive untuk menghapus bucket dan semua isinya:

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

  Ganti kode berikut:

  • BUCKET_NAME: nama bucket Cloud Storage yang Anda buat.

  • PROJECT_ID: Project ID project Google Cloud Anda.

• Jika tidak, jika Anda masih memerlukan bucket, gunakan perintah gcloud storage rm dengan flag --recursive untuk menghapus hanya direktori WORK_DIRECTORY dan semua isinya:

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

  Ganti kode berikut:

  • BUCKET_NAME: nama bucket Cloud Storage yang Anda buat.

  • WORK_DIRECTORY: direktori yang Anda tentukan dalam perintah dsub.

  • PROJECT_ID: Project ID project Google Cloud Anda.

Menghapus tugas

Untuk menghapus tugas menggunakan gcloud CLI, jalankan perintah gcloud batch jobs delete.

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

Ganti kode berikut:

• JOB_NAME: nama tugas.
• PROJECT_ID: Project ID project Google Cloud Anda.

Langkah berikutnya

• Pelajari lebih lanjut dsub dan dsub untuk Batch.
• Pelajari lebih lanjut cara menggunakan volume penyimpanan dengan Batch.