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

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.

Install the 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

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Verify that billing is enabled for your Google Cloud project.

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

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

Install the 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

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Verify that billing is enabled for your Google Cloud project.

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

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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 untuk mengizinkan agen layanan Batch 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: Penulis Log (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 mirip dengan berikut ini:

  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 berencana mempelajari beberapa arsitektur, tutorial, atau panduan memulai, Anda dapat menggunakan kembali project untuk membantu Anda agar tidak melampaui batas kuota project.

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