תזמור משימות על ידי הרצת צינורות Nextflow ב-Batch

במדריך הזה מוסבר איך להריץ צינור עיבוד נתונים של Nextflow ב-Batch. במדריך הזה מריצים את צינור עיבוד הנתונים לדוגמה של מדעי החיים מ-Nextflow, שמבצע כימות של מאפיינים גנומיים מנתוני קריאה קצרים באמצעות RNA-Seq.rnaseq-nf

המדריך הזה מיועד למשתמשי Batch שרוצים להשתמש ב-Nextflow עם Batch.

‫Nextflow היא תוכנה בקוד פתוח לתזמור של תהליכי עבודה בביואינפורמטיקה.

הערה: ההוראות במדריך הזה הן לשימוש באפליקציה הבאה: Nextflow גרסה 23.04.1. יכול להיות שההוראות לא מעודכנות ביחס לגרסאות חדשות יותר של האפליקציה. מידע נוסף זמין במסמכי התיעוד: Nextflow.

מטרות

במדריך הזה תלמדו איך:

• מתקינים את Nextflow ב-Cloud Shell.
• יצירת קטגוריה של Cloud Storage.
• מגדירים צינור עיבוד נתונים של Nextflow.
• מריצים צינור עיבוד נתונים לדוגמה באמצעות Nextflow ב-Batch.
• הצגת הפלט של הפייפליין.
• כדי להימנע מחיובים נוספים, אפשר לבצע אחת מהפעולות הבאות:
  • מחיקת פרויקט.
  • מחיקת משאבים בודדים.

עלויות

במסמך הזה משתמשים ברכיבים הבאים של Google Cloud, והשימוש בהם כרוך בתשלום:

• Batch
• Cloud Storage

כדי להעריך את ההוצאות בהתאם לתחזית השימוש שלכם, אתם יכולים להיעזר במחשבון העלויות.

משתמשים חדשים של Google Cloud ? יכול להיות שאתם זכאים לתקופת ניסיון בחינם.

המשאבים שנוצרים במדריך הזה בדרך כלל עולים פחות מדולר אחד, אם משלימים את כל השלבים – כולל הניקוי – בזמן.

לפני שמתחילים

נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

התקינו את ה-CLI של Google Cloud.

אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:

gcloud init

יוצרים או בוחרים Google Cloud פרויקט.

תפקידים שנדרשים כדי לבחור או ליצור פרויקט

• Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
• יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (יצירת פרויקטים) (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים

הערה: אם אתם לא מתכננים לשמור את המשאבים שתיצרו בתהליך הזה, תוכלו ליצור פרויקט חדש במקום לבחור באחד מהפרויקטים הקיימים. בסיום התהליך תוכלו למחוק את הפרויקט ולהסיר את כל המשאבים שמשויכים אליו.

• יוצרים Google Cloud פרויקט:

  gcloud projects create PROJECT_ID

  מחליפים את PROJECT_ID בשם של פרויקט Google Cloud שיוצרים.

• בוחרים את הפרויקט שיצרתם: Google Cloud

  gcloud config set project PROJECT_ID

  מחליפים את PROJECT_ID בשם הפרויקט ב- Google Cloud .

מוודאים שהחיוב מופעל בפרויקט Google Cloud .

מפעילים את ממשקי ה-API של Batch,‏ Cloud Storage,‏ Compute Engine ו-Logging:

תפקידים שנדרשים להפעלת ממשקי API

כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים

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

התקינו את ה-CLI של Google Cloud.

אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:

gcloud init

יוצרים או בוחרים Google Cloud פרויקט.

תפקידים שנדרשים כדי לבחור או ליצור פרויקט

• Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
• יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (יצירת פרויקטים) (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים

הערה: אם אתם לא מתכננים לשמור את המשאבים שתיצרו בתהליך הזה, תוכלו ליצור פרויקט חדש במקום לבחור באחד מהפרויקטים הקיימים. בסיום התהליך תוכלו למחוק את הפרויקט ולהסיר את כל המשאבים שמשויכים אליו.

• יוצרים Google Cloud פרויקט:

  gcloud projects create PROJECT_ID

  מחליפים את PROJECT_ID בשם של פרויקט Google Cloud שיוצרים.

• בוחרים את הפרויקט שיצרתם: Google Cloud

  gcloud config set project PROJECT_ID

  מחליפים את PROJECT_ID בשם הפרויקט ב- Google Cloud .

מוודאים שהחיוב מופעל בפרויקט Google Cloud .

מפעילים את ממשקי ה-API של Batch,‏ Cloud Storage,‏ Compute Engine ו-Logging:

תפקידים שנדרשים להפעלת ממשקי API

כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים

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

1. מוודאים שבפרויקט יש רשת של ענן וירטואלי פרטי (VPC) עם הגדרת רשת תקינה לצורך המדריך הזה.

   הערה: לא צריך לבצע שום פעולה בשלב הזה אלא אם הארגון שלכם משבית את יצירת הרשתות של default על ידי הפעלת אילוץ המדיניות compute.skipDefaultNetworkCreation או אם בוצע שינוי ברשת default של הפרויקט.

   במדריך הזה אנחנו יוצאים מנקודת הנחה שאתם משתמשים ברשת default. כברירת מחדל,המשאבים משתמשים ברשת default, שמספקת את הגישה לרשת שנדרשת במדריך הזה. Google Cloud

   מטרה: אם רוצים שמשימה באצווה של צינור Nextflow תשתמש ברשת אחרת, אפשר לשנות את הקובץ nextflow.config במדריך הזה כדי להגדיר גם את הרשת ואת רשת המשנה של העבודה באמצעות השדות google.batch.network ו-google.batch.subnetwork של Nextflow. עם זאת, צריך גם לוודא שהרשת ורשת המשנה מוגדרות בצורה נכונה לעומס העבודה. מידע נוסף זמין במאמר סקירה כללית על רשתות של עיבוד באצווה.

2. מוודאים שלפרויקט יש לפחות חשבון שירות אחד עם ההרשאות שנדרשות להפעלת משימה באצווה במדריך הזה.

   כברירת מחדל, המשימות משתמשות בחשבון השירות שמשמש כברירת המחדל של Compute Engine, שמקבל באופן אוטומטי את תפקיד ה-IAM 'עריכה' (roles/editor) וכבר יש לו את כל ההרשאות שנדרשות להדרכה הזו.

   הערה: לא נדרשת פעולה בשלב הזה אלא אם הארגון שלכם השבית את ההרשאות האוטומטיות לחשבונות שירות שמוגדרים כברירת מחדל על ידי הפעלת אילוץ המדיניות iam.automaticIamGrantsForDefaultServiceAccounts, אם בוצעו שינויים בחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine בפרויקט שלכם, או אם אתם רוצים להשתמש בחשבון שירות אחר.

   כדי לוודא שלחשבון השירות של העבודה יש את ההרשאות הנדרשות כדי לאפשר לסוכן השירות של Batch ליצור משאבים ולגשת אליהם עבור עבודות Batch, צריך לבקש מהאדמין להקצות לחשבון השירות של העבודה את תפקידי ה-IAM הבאים:

   חשוב: צריך להקצות את התפקידים האלה לחשבון השירות של העבודה, ולא לחשבון המשתמש שלכם. אם לא תקצו את התפקידים לחשבון המשתמש הנכון, יכול להיות שתקבלו שגיאות הרשאה.
   • ‫Batch Agent Reporter (roles/batch.agentReporter) בפרויקט
   • אדמין לניהול נפח האחסון (roles/storage.admin) בפרויקט
   • (מומלץ) מתן הרשאה למשימות ליצור יומנים ב-Cloud Logging: Logs Writer (roles/logging.logWriter) on the project

   להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

   יכול להיות שהאדמין גם יוכל לתת לחשבון השירות של הג'וב את ההרשאות הנדרשות באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.

3. מוודאים שיש לכם את ההרשאות הנדרשות כדי לבצע את הפעולות שמפורטות במדריך הזה.

   הערה: אם יצרתם את הפרויקט שבו אתם מתכננים להשתמש במדריך הזה, לא צריך לבצע שום פעולה בשלב הזה. כיוצרי הפרויקט, אתם מקבלים באופן אוטומטי את תפקיד ה-IAM 'בעלים' (roles/owner), שכבר כולל את כל ההרשאות שנדרשות במדריך הזה.

   כדי לקבל את ההרשאות שדרושות להשלמת המדריך הזה, אתם צריכים לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים:

   • הכלי לעריכת משימות באצווה (roles/batch.jobsEditor) בפרויקט
   • משתמש בחשבון שירות (roles/iam.serviceAccountUser) בחשבון השירות של המשימה
   • אדמין של אובייקט אחסון (roles/storage.objectAdmin) בפרויקט

4. מתקינים את Nextflow:

   curl -s -L https://github.com/nextflow-io/nextflow/releases/download/v23.04.1/nextflow | bash
   

   הפלט אמור להיראות כך:

   N E X T F L O W
   version 23.04.1 build 5866
   created 15-04-2023 06:51 UTC
   cite doi:10.1038/nbt.3820
   http://nextflow.io
   
   Nextflow installation completed. Please note:
   - the executable file `nextflow` has been created in the folder: ...
   - you may complete the installation by moving it to a directory in your $PATH
   

יצירת קטגוריה של Cloud Storage

כדי ליצור קטגוריה של Cloud Storage לאחסון קבצים זמניים של עבודה ופלט מצינור הנתונים של Nextflow, משתמשים במסוף או בשורת הפקודה. Google Cloud

המסוף

כדי ליצור קטגוריה של Cloud Storage באמצעות Google Cloud המסוף, מבצעים את השלבים הבאים:

1. נכנסים לדף Buckets במסוף Google Cloud .

   כניסה לדף Buckets

2. לוחצים על יצירה.

3. בדף Create a bucket, מזינים שם ייחודי גלובלי לקטגוריה.

4. לוחצים על יצירה.

5. בחלון Public access will be prevented, לוחצים על Confirm.

gcloud

כדי ליצור קטגוריה של Cloud Storage באמצעות Google Cloud CLI, משתמשים בפקודה gcloud storage buckets create.

gcloud storage buckets create gs://BUCKET_NAME

מחליפים את BUCKET_NAME בשם ייחודי גלובלית לקטגוריה.

אם הבקשה תצליח, הפלט ייראה כך:

Creating gs://BUCKET_NAME/...
   ```

הגדרת Nextflow

כדי להגדיר את צינור הנתונים של Nextflow להפעלה ב-Batch, מבצעים את השלבים הבאים בשורת הפקודה:

1. משכפלים את מאגר צינורות עיבוד הנתונים לדוגמה:

   git clone https://github.com/nextflow-io/rnaseq-nf.git
   

2. עוברים לתיקייה rnaseq-nf:

   cd rnaseq-nf
   

3. פותחים את הקובץ nextflow.config:

   nano nextflow.config
   

   הקובץ צריך להכיל את הקטע google-batch הבא:

   'google-batch' {
       params.transcriptome = 'gs://rnaseq-nf/data/ggal/transcript.fa'
       params.reads = 'gs://rnaseq-nf/data/ggal/gut_{1,2}.fq'
       params.multiqc = 'gs://rnaseq-nf/multiqc'
       process.executor = 'google-batch'
       process.container = 'docker.io/nextflow/rnaseq-nf:v1.3.1'
       /*
        * replace with your own bucket!
        */
       workDir = 'gs://BUCKET_NAME/WORK_DIRECTORY'
       google.region  = 'REGION'
   }
   

4. בקטע google-batch, מבצעים את הפעולות הבאות:

   1. מחליפים את BUCKET_NAME בשם של קטגוריית Cloud Storage שיצרתם בשלבים הקודמים.

   2. מחליפים את WORK_DIRECTORY בשם של תיקייה חדשה שצינור הנתונים יכול להשתמש בה כדי לאחסן יומנים ותוצאות.

      לדוגמה, מזינים workDir.

   3. מחליפים את REGION באזור שבו רוצים להשתמש.

      לדוגמה, מזינים us-central1.

   4. אחרי השדה google.region, מוסיפים את השדות הבאים:

      1. מוסיפים את השדה google.project:

         google.project = 'PROJECT_ID'
         

         מחליפים את PROJECT_ID במזהה הפרויקט הנוכחי Google Cloud .

      2. אם אתם לא משתמשים בחשבון השירות שמוגדר כברירת מחדל של Compute Engine כחשבון השירות של העבודה, מוסיפים את השדה google.batch.serviceAccountEmail:

         google.batch.serviceAccountEmail = 'SERVICE_ACCOUNT_EMAIL'
         

         מחליפים את SERVICE_ACCOUNT_EMAIL בכתובת האימייל של חשבון השירות של המשימה שהכנתם למדריך הזה.

      מטרה: כדי לקבל מידע על כל השדות שאפשר לציין כדי להגדיר את משימת Batch עבור צינור Nextflow, אפשר לעיין במסמכי Nextflow בנושא היקף ההגדרה של Batch.

5. כדי לשמור את השינויים:

   1. לוחצים על Control+S.

   2. מזינים Y.

   3. לוחצים על Enter.

הרצת צינור עיבוד הנתונים

מריצים את צינור הנתונים לדוגמה של Nextflow באמצעות שורת הפקודה:

../nextflow run nextflow-io/rnaseq-nf -profile google-batch

צינור הנתונים מריץ מערך נתונים קטן באמצעות ההגדרות שסיפקתם בשלבים הקודמים. יכולות לעבור 10 דקות עד שהפעולה תושלם.

אחרי שהצינור יסיים לפעול, הפלט אמור להיראות כך:

N E X T F L O W  ~  version 23.04.1
Launching `https://github.com/nextflow-io/rnaseq-nf` [crazy_curry] DSL2 - revision: 88b8ef803a [master]
 R N A S E Q - N F   P I P E L I N E
 ===================================
 transcriptome: gs://rnaseq-nf/data/ggal/transcript.fa
 reads        : gs://rnaseq-nf/data/ggal/gut_{1,2}.fq
 outdir       : results

Uploading local `bin` scripts folder to gs://example-bucket/workdir/tmp/53/2847f2b832456a88a8e4cd44eec00a/bin
executor >  google-batch (4)
[67/71b856] process > RNASEQ:INDEX (transcript)     [100%] 1 of 1 ✔
[0c/2c79c6] process > RNASEQ:FASTQC (FASTQC on gut) [100%] 1 of 1 ✔
[a9/571723] process > RNASEQ:QUANT (gut)            [100%] 1 of 1 ✔
[9a/1f0dd4] process > MULTIQC                       [100%] 1 of 1 ✔

Done! Open the following report in your browser --> results/multiqc_report.html

Completed at: 20-Apr-2023 15:44:55
Duration    : 10m 13s
CPU hours   : (a few seconds)
Succeeded   : 4

הצגת הפלט של הצינור

אחרי שהצינור מסיים לפעול, הוא מאחסן קובצי פלט, יומנים, שגיאות או קבצים זמניים בקובץ results/qc_report.html בתיקייה WORK_DIRECTORY של הקטגוריה ב-Cloud Storage.

כדי לבדוק את קובצי הפלט של צינור העיבוד בתיקייה WORK_DIRECTORY בקטגוריית Cloud Storage, אפשר להשתמש במסוף Google Cloud או בשורת הפקודה.

המסוף

כדי לבדוק את קובצי הפלט של צינור העיבוד באמצעות מסוף Google Cloud , פועלים לפי השלבים הבאים:

1. נכנסים לדף Buckets במסוף Google Cloud .

   כניסה לדף Buckets

2. בעמודה Name (שם), לוחצים על שם הקטגוריה שיצרתם בשלבים הקודמים.

3. בדף Bucket details, פותחים את התיקייה WORK_DIRECTORY.

יש תיקייה לכל משימה נפרדת שמופעלת בתהליך העבודה. כל תיקייה מכילה את הפקודות שהופעלו, את קובצי הפלט ואת הקבצים הזמניים שנוצרו על ידי צינור העיבוד.

gcloud

כדי לבדוק את קובצי הפלט של צינור העיבוד באמצעות ה-CLI של gcloud, משתמשים בפקודה gcloud storage ls.

gcloud storage ls gs://BUCKET_NAME/WORK_DIRECTORY

מחליפים את מה שכתוב בשדות הבאים:

• ‫BUCKET_NAME: שם הקטגוריה שיצרתם בשלבים הקודמים.

• ‫WORK_DIRECTORY: הספרייה שציינתם בקובץ nextflow.config.

בפלט מופיעה תיקייה לכל משימה נפרדת שצינור הנתונים מריץ. כל תיקייה מכילה את הפקודות שהופעלו, קובצי פלט וקבצים זמניים שנוצרו על ידי צינור העיבוד.

הסרת המשאבים

כדי להימנע מחיובים בחשבון Google Cloud בגלל השימוש במשאבים שנעשה במסגרת המדריך הזה, אפשר למחוק את הפרויקט שמכיל את המשאבים, או להשאיר את הפרויקט ולמחוק את המשאבים בנפרד.

מחיקת הפרויקט

הדרך הקלה ביותר לבטל את החיוב היא למחוק את הפרויקט הנוכחי.

כדי למחוק את הפרויקט הנוכחי, משתמשים במסוף Google Cloud או ב-CLI של gcloud.

המסוף

זהירות: כשמוחקים פרויקט:

• התוכן של הפרויקט נמחק כולו. אם השתמשתם בפרויקט קיים כדי לתרגל את המשימות במדריך הזה, כשתמחקו אותו תימחק גם כל העבודה שביצעתם באותו פרויקט.
• מאבדים את מזהה הפרויקט בהתאמה אישית. כשיצרתם את הפרויקט, יכולתם לבחור לו מזהה פרויקט בהתאמה אישית כדי להשתמש בו בעתיד. כדי לשמור על כתובות ה-URL שמשתמשות במזהה הפרויקט, כמו appspot.com, צריך למחוק את המשאבים שנבחרו בפרויקט אבל לא את הפרויקט כולו.

אם אתם מתכננים להיעזר בכמה ארכיטקטורות, מדריכים או מדריכים למתחילים, מומלץ להשתמש שוב באותו פרויקט כדי לא לחרוג ממכסות הפרויקטים.

1. במסוף Google Cloud , נכנסים לדף Manage resources.

   כניסה לדף Manage resources

2. ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete.
3. כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

gcloud

זהירות: כשמוחקים פרויקט:

• התוכן של הפרויקט נמחק כולו. אם השתמשתם בפרויקט קיים כדי לתרגל את המשימות במדריך הזה, כשתמחקו אותו תימחק גם כל העבודה שביצעתם באותו פרויקט.
• מאבדים את מזהה הפרויקט בהתאמה אישית. כשיצרתם את הפרויקט, יכולתם לבחור לו מזהה פרויקט בהתאמה אישית כדי להשתמש בו בעתיד. כדי לשמור על כתובות ה-URL שמשתמשות במזהה הפרויקט, כמו appspot.com, צריך למחוק את המשאבים שנבחרו בפרויקט אבל לא את הפרויקט כולו.

אם אתם מתכננים להיעזר בכמה ארכיטקטורות, מדריכים או מדריכים למתחילים, מומלץ להשתמש שוב באותו פרויקט כדי לא לחרוג ממכסות הפרויקטים.

כדי למחוק Google Cloud פרויקט:

gcloud projects delete PROJECT_ID

מחיקת משאבים בודדים

אם רוצים להמשיך להשתמש בפרויקט הנוכחי, צריך למחוק את המשאבים הספציפיים שבהם השתמשתם במדריך הזה.

מחיקת הקטגוריה

אם אתם לא צריכים יותר את ה-bucket שבו השתמשתם במדריך הזה, אתם יכולים למחוק אותו.

מחיקת קובצי הפלט בדלי

אחרי שהצינור מסיים לפעול, הוא יוצר קובצי פלט ומאחסן אותם בתיקייה WORK_DIRECTORY של קטגוריית Cloud Storage.

כדי להפחית את החיובים ב-Cloud Storage בחשבון הנוכחיGoogle Cloud , אפשר למחוק את התיקייה שמכילה את קובצי הפלט של צינור הנתונים באמצעות מסוף Google Cloud או שורת הפקודה.

המסוף

כדי למחוק את התיקייה WORK_DIRECTORY ואת כל קובצי הפלט מקטגוריית Cloud Storage באמצעות מסוףGoogle Cloud , פועלים לפי השלבים הבאים:

1. נכנסים לדף Buckets במסוף Google Cloud .

   כניסה לדף Buckets

2. בעמודה Name (שם), לוחצים על שם הקטגוריה שיצרתם בשלבים הקודמים.

3. בדף Bucket details, בוחרים בשורה שמכילה את התיקייה WORK_DIRECTORY ומבצעים את הפעולות הבאות:

   1. לוחצים על Delete.

   2. כדי לאשר, מזינים DELETE ולוחצים על מחיקה.

gcloud

כדי למחוק את התיקייה WORK_DIRECTORY ואת כל קובצי הפלט מקטגוריה של Cloud Storage באמצעות ה-CLI של gcloud, משתמשים בפקודה gcloud storage rm עם הדגל --recursive.

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

מחליפים את מה שכתוב בשדות הבאים:

• ‫BUCKET_NAME: שם הקטגוריה שציינתם בשלבים הקודמים.

• ‫WORK_DIRECTORY: הספרייה שבה יישמרו קובצי הפלט של צינור העיבוד שציינתם בשלבים הקודמים.

המאמרים הבאים

• מידע נוסף על פריסת תהליכי עבודה של Nextflow זמין במאגר GitHub של Nextflow.

• מידע נוסף על תהליכי Nextflow, על סקריפטים ועל אפשרויות הגדרה זמין במאמרי העזרה בנושא Nextflow.