יצירת קובצי אימג' מותאמים אישית של קונטיינרים ל-Dataflow

במסמך הזה מוסבר איך ליצור קובץ אימג' בקונטיינר בהתאמה אישית לעבודות Dataflow.

דרישות

קובץ אימג' מותאם אישית של קונטיינר ל-Dataflow צריך לעמוד בדרישות הבאות:

  • מערכת Apache Beam SDK והרכיבים התלויים הנדרשים מותקנים. מומלץ להתחיל עם תמונה של Apache Beam SDK שמוגדרת כברירת מחדל. מידע נוסף זמין במאמר הזה בקטע בחירת תמונת בסיס.
  • הסקריפט /opt/apache/beam/boot צריך לפעול כשלב האחרון במהלך הפעלת מאגר התגים. הסקריפט הזה מאתחל את סביבת העובד ומתחיל את תהליך העובד של ה-SDK. הסקריפט הזה הוא ENTRYPOINT שמוגדר כברירת מחדל בתמונות של Apache Beam SDK. עם זאת, אם משתמשים בתמונת בסיס אחרת או אם מבטלים את ברירת המחדל ENTRYPOINT, צריך להריץ את הסקריפט באופן מפורש. מידע נוסף זמין בקטע שינוי נקודת הכניסה של מאגר התמונות במסמך הזה.
  • קובץ האימג' של הקונטיינר צריך לתמוך בארכיטקטורה של מכונות ה-VM של העובדים עבור משימת Dataflow. אם אתם מתכננים להשתמש בקונטיינר בהתאמה אישית במכונות וירטואליות (VM) של ARM, מומלץ ליצור אימג' מרובה ארכיטקטורות. מידע נוסף זמין במאמר בנושא יצירת תמונת קונטיינר מרובת-ארכיטקטורות.

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

  1. מוודאים שהגרסה של Apache Beam SDK שהתקנתם תומכת ב-Portable Runner ובגרסת השפה שלכם. מידע נוסף זמין במאמר בנושא התקנת Apache Beam SDK.

  2. כדי לבדוק את קובץ האימג' של הקונטיינר באופן מקומי, צריך להתקין את Docker. מידע נוסף זמין במאמר קבלת Docker.

  3. יוצרים מאגר Artifact Registry. מציינים את פורמט קובץ האימג' של Docker. צריכה להיות לכם לפחות הרשאת כתיבה ב-Artifact Registry למאגר.

    כדי ליצור מאגר חדש, מריצים את הפקודה gcloud artifacts repositories create:

    gcloud artifacts repositories create REPOSITORY \
  --repository-format=docker \
  --location=REGION \
  --async

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

    • ‫REPOSITORY: שם למאגר. שמות המאגרים צריכים להיות ייחודיים לכל מיקום בפרויקט.
    • ‫REGION: האזור שבו רוצים לפרוס את משימת Dataflow. בוחרים אזור Dataflow שקרוב למקום שבו מריצים את הפקודות. הערך חייב להיות שם אזור תקין. מידע נוסף על אזורים ומיקומים זמין במאמר מיקומים של Dataflow.

    בדוגמה הזו נשתמש בדגל --async. הפקודה מוחזרת באופן מיידי, בלי להמתין לסיום הפעולה.

  4. כדי להגדיר את Docker לאימות בקשות ל-Artifact Registry, מריצים את הפקודה gcloud auth configure-docker:

    gcloud auth configure-docker REGION-docker.pkg.dev

    הפקודה מעדכנת את ההגדרה של Docker. מעכשיו אפשר להתחבר אל Artifact Registry בפרויקט Google Cloud כדי להעלות תמונות.

בחירת תמונת בסיס

מומלץ להתחיל עם תמונת Apache Beam SDK כתמונת הבסיס של הקונטיינר. התמונות האלה מופצות כחלק מגרסאות של Apache Beam ב-Docker Hub.

שימוש בתמונת בסיס של Apache Beam

כדי להשתמש בתמונה של Apache Beam SDK כתמונת הבסיס, מציינים את תמונת הקונטיינר בהוראה FROM ואז מוסיפים את ההתאמות האישיות שלכם.

Java

בדוגמה הזו נעשה שימוש ב-Java 8 עם Apache Beam SDK בגרסה 2.75.0.

FROM apache/beam_java8_sdk:2.75.0

# Make your customizations here, for example:
ENV FOO=/bar
COPY path/to/myfile ./

גרסת זמן הריצה של הקונטיינר המותאם אישית צריכה להיות זהה לזמן הריצה שבו תשתמשו כדי להפעיל את צינור עיבוד הנתונים. לדוגמה, אם תפעילו את צינור עיבוד הנתונים מסביבת Java 11 מקומית, בשורה FROM צריך לציין סביבת Java 11: apache/beam_java11_sdk:....

Python

בדוגמה הזו נעשה שימוש ב-Python 3.10 עם Apache Beam SDK גרסה 2.75.0.

FROM apache/beam_python3.10_sdk:2.75.0

# Make your customizations here, for example:
ENV FOO=/bar
COPY path/to/myfile ./

גרסת זמן הריצה של הקונטיינר המותאם אישית צריכה להיות זהה לזמן הריצה שבו תשתמשו כדי להפעיל את צינור עיבוד הנתונים. לדוגמה, אם מפעילים את צינור העיבוד מסביבת Python 3.10 מקומית, בשורה FROM צריך לציין סביבת Python 3.10: apache/beam_python3.10_sdk:....

המשך

בדוגמה הזו נעשה שימוש ב-Go עם Apache Beam SDK בגרסה 2.75.0.

FROM apache/beam_go_sdk:2.75.0

# Make your customizations here, for example:
ENV FOO=/bar
COPY path/to/myfile ./

שימוש בתמונת בסיס מותאמת אישית

אם רוצים להשתמש בתמונה בסיסית אחרת, או אם צריך לשנות היבט מסוים בתמונות ברירת המחדל של Apache Beam (למשל גרסת מערכת ההפעלה או תיקוני אבטחה), צריך להשתמש בתהליך בנייה רב-שלבית. מעתיקים את הארטיפקטים הנדרשים מקובץ בסיס ברירת מחדל של Apache Beam.

מגדירים את ENTRYPOINT להפעלת הסקריפט /opt/apache/beam/boot, שמאותחל את סביבת העובד ומתחיל את תהליך העובד של ה-SDK. אם לא מגדירים את נקודת הכניסה הזו, תהליכי העבודה של Dataflow לא מתחילים בצורה תקינה.

בדוגמה הבאה מוצג קובץ Dockerfile שמעתיק קבצים מ-Apache Beam SDK:

Java

FROM openjdk:8

# Copy files from official SDK image, including script/dependencies.
COPY --from=apache/beam_java8_sdk:2.75.0 /opt/apache/beam /opt/apache/beam

# Set the entrypoint to Apache Beam SDK launcher.
ENTRYPOINT ["/opt/apache/beam/boot"]

Python

FROM python:3.10-slim

# Install SDK.
RUN pip install --no-cache-dir apache-beam[gcp]==2.75.0

# Verify that the image does not have conflicting dependencies.
RUN pip check

# Copy files from official SDK image, including script/dependencies.
COPY --from=apache/beam_python3.10_sdk:2.75.0 /opt/apache/beam /opt/apache/beam

# Set the entrypoint to Apache Beam SDK launcher.
ENTRYPOINT ["/opt/apache/beam/boot"]

בדוגמה הזו מניחים שהרכיבים התלויים הנדרשים (במקרה הזה, Python 3.10 ו-pip) הותקנו בתמונת הבסיס הקיימת. התקנת Apache Beam SDK בתמונה מבטיחה שהתמונה כוללת את יחסי התלות הנדרשים של SDK ומקצרת את זמן ההפעלה של העובד.

חשוב: גרסת ה-SDK שצוינה בהוראות של RUN ו-COPY צריכה להיות זהה לגרסה ששימשה להפעלת צינור העיבוד.

המשך

FROM golang:latest

# Copy files from official SDK image, including script/dependencies.
COPY --from=apache/beam_go_sdk:2.75.0 /opt/apache/beam /opt/apache/beam

# Set the entrypoint to Apache Beam SDK launcher.
ENTRYPOINT ["/opt/apache/beam/boot"]

שינוי נקודת הכניסה של מאגר התגים

אם במאגר מופעל סקריפט בהתאמה אישית במהלך הפעלת המאגר, הסקריפט חייב להסתיים בהפעלת /opt/apache/beam/boot. ארגומנטים שמועברים על ידי Dataflow במהלך הפעלת מאגר התגים צריכים להיות מועברים לסקריפט ברירת המחדל של האתחול. בדוגמה הבאה מוצג סקריפט הפעלה בהתאמה אישית שקורא לסקריפט האתחול שמוגדר כברירת מחדל:

#!/bin/bash

echo "This is my custom script"
# ...

# Pass command arguments to the default boot script.
/opt/apache/beam/boot "$@"

ב-Dockerfile, מגדירים את ENTRYPOINT לקריאה לסקריפט:

Java

FROM apache/beam_java8_sdk:2.75.0

COPY script.sh path/to/my/script.sh
ENTRYPOINT [ "path/to/my/script.sh" ]

Python

FROM apache/beam_python3.10_sdk:2.75.0

COPY script.sh path/to/my/script.sh
ENTRYPOINT [ "path/to/my/script.sh" ]

המשך

FROM apache/beam_go_sdk:2.75.0

COPY script.sh path/to/my/script.sh
ENTRYPOINT [ "path/to/my/script.sh" ]

יצירה של קובץ האימג' והעלאה שלו

אתם יכולים להשתמש ב-Cloud Build או ב-Docker כדי ליצור את קובץ האימג' בקונטיינר ולהעביר אותו בדחיפה למאגר ב-Artifact Registry.

Cloud Build

כדי ליצור את הקובץ ולהעביר אותו בדחיפה למאגר Artifact Registry, מריצים את הפקודה gcloud builds submit:

  gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/IMAGE:TAG .

Docker 

docker build . --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/IMAGE:TAG
docker push REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/IMAGE:TAG

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

  • ‫REGION: האזור שבו רוצים לפרוס את משימת Dataflow. הערך של המשתנה REGION חייב להיות שם אזור תקין.
  • ‫PROJECT_ID: שם הפרויקט או שם המשתמש.
  • ‫REPOSITORY: שם מאגר התמונות.
  • ‫IMAGE: השם של התמונה.
  • ‫TAG: תג התמונה. תמיד צריך לציין תג או SHA של מאגר תגים עם גרסה. אל תשתמשו בתג :latest או בתג שניתן לשינוי.

התקנה מראש של יחסי תלות ב-Python

הקטע הזה רלוונטי לצינורות Python.

כשמריצים עבודת Python Dataflow, אפשר לציין תלות נוספת באמצעות האפשרות --requirements_file או --extra_packages בזמן הריצה. מידע נוסף מופיע במאמר ניהול תלויות של צינורות Python. תלויות נוספות מותקנות בכל קונטיינר של עובד Dataflow. כשהעבודה מתחילה לראשונה ובמהלך התאמה אוטומטית לעומס, התקנת התלות מובילה לעיתים קרובות לשימוש גבוה במעבד ולתקופת אתחול ארוכה בכל עובדי Dataflow החדשים שהופעלו.

כדי להימנע מהתקנות חוזרות של תלות, אפשר ליצור מראש קובץ אימג' מותאם אישית של קונטיינר Python SDK עם התלות שכבר מותקנת. אפשר לבצע את השלב הזה בזמן הבנייה באמצעות Dockerfile, או בזמן הריצה כששולחים את העבודה.

תהליך העבודה יוצר סביבת Python וירטואלית חדשה כשהוא מתחיל את הקונטיינר. לכן, כדאי להתקין את התלות בסביבת Python שמוגדרת כברירת מחדל (גלובלית) במקום ליצור סביבה וירטואלית. אם מפעילים סביבה וירטואלית בקובץ האימג' בקונטיינר, יכול להיות שהסביבה הזו לא תופעל כשהעבודה תתחיל. מידע נוסף זמין במאמר בנושא בעיות נפוצות.

התקנה מראש באמצעות קובץ Dockerfile

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

FROM apache/beam_python3.10_sdk:2.75.0

COPY requirements.txt .

# Pre-install Python dependencies. For reproducibile builds,
# supply all of the dependencies and their versions in a requirements.txt file.
RUN pip install -r requirements.txt

# You can also install individual dependencies.
RUN pip install lxml
# Pre-install other dependencies.
RUN apt-get update \
  && apt-get dist-upgrade \
  && apt-get install -y --no-install-recommends ffmpeg

שולחים את העבודה עם האפשרויות של צינור הנתונים --sdk_container_image ו---sdk_location. האפשרות --sdk_location מונעת את ההורדה של ה-SDK כשמפעילים את העבודה. ערכת ה-SDK מאוחזרת ישירות מתמונת הקונטיינר.

בדוגמה הבאה מריצים את צינור העיבוד לדוגמה wordcount:

python -m apache_beam.examples.wordcount \
  --input=INPUT_FILE \
  --output=OUTPUT_FILE \
  --project=PROJECT_ID \
  --region=REGION \
  --temp_location=TEMP_LOCATION \
  --runner=DataflowRunner \
  --experiments=use_runner_v2 \
  --sdk_container_image=IMAGE_URI
  --sdk_location=container

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

  • INPUT_FILE: קובץ קלט לפייפליין
  • ‫OUTPUT_FILE: נתיב לכתיבת הפלט
  • ‫PROJECT_ID: מזהה הפרויקט Google Cloud
  • ‫REGION: האזור שבו תפרסו את משימת Dataflow.
  • ‫TEMP_LOCATION: הנתיב ב-Cloud Storage שבו Dataflow מאחסן באופן זמני קבצים של משימות
  • ‫IMAGE_URI: ה-URI של קובץ האימג' המותאם אישית של הקונטיינר

ביצוע build מראש של קובץ אימג' בקונטיינר כששולחים את העבודה

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

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

  • ‫--prebuild_sdk_container_engine=[cloud_build | local_docker]. כשהדגל הזה מוגדר, Apache Beam יוצר מאגר מותאם אישית ומתקין את כל התלות שצוינו באפשרויות --requirements_file ו---extra_packages. הדגל הזה תומך בערכים הבאים:

    • ‫cloud_build. משתמשים ב-Cloud Build כדי ליצור את הקונטיינר. צריך להפעיל את Cloud Build API בפרויקט.
    • ‫local_docker. משתמשים בהתקנה המקומית של Docker כדי ליצור את הקונטיינר.

  • ‫--docker_registry_push_url=IMAGE_PATH. מחליפים את IMAGE_PATH בתיקייה ב-Artifact Registry.

  • ‫--sdk_location=container. האפשרות הזו מונעת מהעובדים להוריד את ה-SDK כשהעבודה מתחילה. במקום זאת, ה-SDK מאוחזר ישירות מקובץ האימג' בקונטיינר.

בדוגמה הבאה נעשה שימוש ב-Cloud Build כדי ליצור מראש את קובץ האימג':

python -m apache_beam.examples.wordcount \
  --input=INPUT_FILE \
  --output=OUTPUT_FILE \
  --project=PROJECT_ID \
  --region=REGION \
  --temp_location=TEMP_LOCATION \
  --runner=DataflowRunner \
  --disk_size_gb=DISK_SIZE_GB \
  --experiments=use_runner_v2 \
  --requirements_file=./requirements.txt \
  --prebuild_sdk_container_engine=cloud_build \
  --docker_registry_push_url=IMAGE_PATH \
  --sdk_location=container

כדי להשתמש בתכונת הטרום-בנייה, צריך להשתמש ב-Apache Beam SDK ל-Python בגרסה 2.25.0 ואילך.

בתהליך העבודה של טרום-בנייה של קובץ אימג' של SDK, קובץ האימג' שמועבר באמצעות אפשרות הצינור --sdk_container_image משמש כקובץ האימג' הבסיסי. אם האפשרות לא מוגדרת, ברירת המחדל היא שימוש בתמונה של Apache Beam כתמונת הבסיס.

אפשר לעשות שימוש חוזר בתמונת קונטיינר של Python SDK שנבנתה מראש בעבודה אחרת עם אותן תלות וגרסת SDK. כדי לעשות שימוש חוזר בתמונה, מעבירים את כתובת ה-URL של קובץ האימג' בקונטיינר שנבנה מראש למשימה השנייה באמצעות האפשרות --sdk_container_image של צינור העברת הנתונים. מסירים את אפשרויות התלות --requirements_file, --extra_packages ו---setup_file.

אם אתם לא מתכננים לעשות שימוש חוזר בתמונה, מומלץ למחוק אותה אחרי שהעבודה מסתיימת. אפשר למחוק את התמונה באמצעות gcloud CLI או בדפי Artifact Registry במסוף Google Cloud .

אם התמונה מאוחסנת ב-Artifact Registry, משתמשים בפקודה artifacts docker images delete:

   gcloud artifacts docker images delete IMAGE --delete-tags

בעיות נפוצות

  • אם למשימה שלכם יש יחסי תלות נוספים ב-Python ממראה פרטית של PyPi, ולא ניתן למשוך אותם על ידי משימת Cloud Build מרחוק, נסו להשתמש באפשרות Docker המקומית או ליצור את הקונטיינר באמצעות Dockerfile.

  • אם המשימה ב-Cloud Build נכשלת עם השגיאה docker exit code 137, פירוש הדבר הוא שנגמר הזיכרון של משימת ה-Build, יכול להיות בגלל הגודל של התלות שמותקנת. משתמשים בסוג מכונת עובד גדול יותר של Cloud Build על ידי העברת --cloud_build_machine_type=machine_type, כאשר machine_type היא אחת מהאפשרויות הבאות:

    • n1-highcpu-8
    • n1-highcpu-32
    • e2-highcpu-8
    • e2-highcpu-32

    כברירת מחדל, Cloud Build משתמש בסוג המכונה e2-medium.

  • ב-Apache Beam מגרסה 2.44.0 ואילך, תהליכי worker יוצרים סביבה וירטואלית כשמתחילים קונטיינר בהתאמה אישית. אם מאגר התגים יוצר סביבה וירטואלית משלו כדי להתקין יחסי תלות, יחסי התלות האלה נמחקים. התנהגות כזו עלולה לגרום לשגיאות כמו:

    ModuleNotFoundError: No module named '<dependency name>'

    כדי להימנע מהבעיה הזו, צריך להתקין את התלות בסביבת ברירת המחדל (הגלובלית) של Python. כפתרון עקיף, אפשר להשבית את ההתנהגות הזו ב-Beam 2.48.0 ובגרסאות מתקדמות יותר על ידי הגדרת משתנה הסביבה הבא בקובץ האימג' בקונטיינר:

    ENV RUN_PYTHON_SDK_IN_DEFAULT_ENVIRONMENT=1

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