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

במדריך הזה מוסבר איך להריץ צינור (pipeline) של dsub ב-Batch. באופן ספציפי, צינור העיבוד dsub שבדוגמה מעבד נתוני ריצוף DNA בקובץ Binary Alignment Map‏ (BAM) כדי ליצור קובץ אינדקס BAM‏ (BAI).

המדריך הזה מיועד למשתמשי Batch שרוצים להשתמש ב-dsub עם Batch. ‫dsub הוא מתזמן משימות בקוד פתוח לתזמור של תהליכי עבודה לעיבוד באצווה ב- Google Cloud. מידע נוסף על השימוש ב-Batch עם dsub זמין במסמכי התיעוד של dsub בנושא Batch.

מטרות

• הפעלת צינור dsub ב-Batch שקורא וכותב קבצים בקטגוריות של Cloud Storage.
• צופים בקובצי הפלט בקטגוריה של Cloud Storage.

עלויות

במסמך הזה משתמשים ברכיבים הבאים של 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. מוודאים שלפרויקט יש לפחות חשבון שירות אחד עם ההרשאות שנדרשות במדריך הזה.

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

   לכל משימה נדרש חשבון שירות שמאפשר לסוכן השירות של Batch ליצור את המשאבים שנדרשים להפעלת המשימה ולגשת אליהם. במדריך הזה, חשבון השירות של העבודה הוא חשבון השירות של Compute Engine שמוגדר כברירת מחדל.

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

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

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

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

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

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

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

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

3. מתקינים את dsub ואת יחסי התלות שלו. מידע נוסף זמין במאמרי העזרה בנושא התקנה של dsub.

   1. מוודאים שמותקנות גרסאות של Python ושל pip שנתמכות על ידי הגרסה העדכנית של dsub. כדי לראות את הגרסאות שמותקנות כרגע, מריצים את הפקודה הבאה:

      pip --version
      

      אם צריך להתקין או לעדכן את pip או את Python, פועלים לפי השלבים להתקנת Python.

   2. מומלץ: כדי למנוע שגיאות של התנגשות בין יחסי תלות במהלך ההתקנה של dsub, צריך ליצור ולהפעיל סביבה וירטואלית של Python:

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

   3. משכפלים את מאגר הנתונים של GitHub‏ dsub באמצעות git ופותחים אותו:

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

   4. מתקינים את dsub ואת יחסי התלות שלו:

      python -m pip install .
      

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

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

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

כדי ליצור קטגוריה של Cloud Storage לאחסון קובצי הפלט מצינור הנתונים לדוגמה dsub באמצעות ה-CLI של gcloud, מריצים את הפקודה gcloud storage buckets create:

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

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

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

• ‫PROJECT_ID: מזהה הפרויקט של פרויקט Google Cloud .

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

Creating gs://BUCKET_NAME/...

הפעלת הפייפליין dsub

בדוגמה dsub מתבצע אינדוקס של קובץ BAM מפרויקט 1,000 הגנומים, והתוצאות מועברות לקטגוריה של Cloud Storage.

כדי להריץ את צינור הנתונים לדוגמה של dsub, מריצים את הפקודה הבאה של dsub:

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

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

• ‫PROJECT_ID: מזהה הפרויקט של פרויקט Google Cloud .

• ‫BUCKET_NAME: השם של קטגוריית Cloud Storage שיצרתם.

• ‫WORK_DIRECTORY: השם של ספרייה חדשה שהצינור יכול להשתמש בה כדי לאחסן יומנים ופלט. לדוגמה, מזינים workDir.

צינור עיבוד הנתונים dsub מריץ משימת Batch שכותבת את קובץ ה-BAI ואת היומנים לספרייה שצוינה בקטגוריה של Cloud Storage. באופן ספציפי, המאגר dsub מכיל תמונת Docker מוכנה מראש שמשתמשת ב-samtools כדי ליצור אינדקס של קובץ ה-BAM שציינתם בדגל --input.

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

בהתחלה, הפקודה עדיין פועלת והפלט דומה לזה:

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.

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

  JOB_NAME: SUCCESS
JOB_NAME

הפלט הזה כולל את הערכים הבאים:

• ‫JOB_NAME: שם המשימה.

• ‫USERNAME: שם המשתמש ב- Google Cloud .

• ‫PROJECT_ID: מזהה הפרויקט של פרויקט Google Cloud .

צפייה בקובצי הפלט

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

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

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

• ‫BUCKET_NAME: השם של קטגוריית Cloud Storage שיצרתם.

• ‫WORK_DIRECTORY: הספרייה שציינתם בפקודה dsub.

• ‫PROJECT_ID: מזהה הפרויקט של פרויקט Google Cloud .

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

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

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

הסרת המשאבים

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

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

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

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

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

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

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

gcloud projects delete PROJECT_ID

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

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

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

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

כדי להפחית את החיובים ב-Cloud Storage בחשבון הנוכחיGoogle Cloud , אפשר:

• אם כבר אין לכם צורך בקטגוריה שבה השתמשתם במדריך הזה, תוכלו להשתמש בפקודה gcloud storage rm עם הדגל --recursive כדי למחוק את הקטגוריה ואת כל התוכן שבה:

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

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

  • ‫BUCKET_NAME: השם של קטגוריית Cloud Storage שיצרתם.

  • ‫PROJECT_ID: מזהה הפרויקט של פרויקט Google Cloud .

• אחרת, אם עדיין צריך את הקטגוריה, משתמשים בפקודה gcloud storage rm עם הדגל --recursive כדי למחוק רק את הספרייה WORK_DIRECTORY ואת כל התוכן שלה:

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

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

  • ‫BUCKET_NAME: השם של קטגוריית Cloud Storage שיצרתם.

  • ‫WORK_DIRECTORY: הספרייה שציינתם בפקודה dsub.

  • ‫PROJECT_ID: מזהה הפרויקט של פרויקט Google Cloud .

מחיקת המשימה

כדי למחוק עבודה באמצעות ה-CLI של gcloud, מריצים את הפקודה gcloud batch jobs delete.

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

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

• ‫JOB_NAME: שם המשימה.
• ‫PROJECT_ID: מזהה הפרויקט של פרויקט Google Cloud .

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

• מידע נוסף על dsub ועל dsub ל-Batch
• מידע נוסף על שימוש בנפחי אחסון עם Batch