יצירת קובצי אימג' מותאמים אישית של קונטיינרים ל-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 שהתקנתם תומכת ב-Runner v2 ובגרסת השפה שלכם. מידע נוסף זמין במאמר בנושא התקנת 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.69.0.

FROM apache/beam_java8_sdk:2.69.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.69.0.

FROM apache/beam_python3.10_sdk:2.69.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

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

FROM apache/beam_go_sdk:2.69.0

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

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

אם רוצים להשתמש בתמונה בסיסית אחרת, או אם צריך לשנות היבט מסוים בתמונות ברירת המחדל של Apache Beam (למשל גרסת מערכת ההפעלה או תיקוני אבטחה), צריך להשתמש בתהליך multistage build. מעתיקים את הארטיפקטים הנדרשים מקובץ בסיס ברירת המחדל של 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.69.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.69.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.69.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 צריכה להיות זהה לגרסה ששימשה להפעלת צינור העיבוד.

Go

FROM golang:latest

# Copy files from official SDK image, including script/dependencies.
COPY --from=apache/beam_go_sdk:2.69.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.69.0

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

Python

FROM apache/beam_python3.10_sdk:2.69.0

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

Go

FROM apache/beam_go_sdk:2.69.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 worker. כשהעבודה מתחילה לראשונה ובמהלך התאמה אוטומטית לעומס, התקנת התלות מובילה לעיתים קרובות לשימוש גבוה במעבד ולתקופת אתחול ארוכה בכל העובדים החדשים של Dataflow שהופעלו.

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

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

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

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

FROM apache/beam_python3.10_sdk:2.69.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 Platform
  • ‫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 pipeline. מסירים את אפשרויות התלות --requirements_file, --extra_packages ו---setup_file.

אם אתם לא מתכננים להשתמש בתמונה שוב, מומלץ למחוק אותה אחרי שהעבודה מסתיימת. אפשר למחוק את התמונה באמצעות ה-CLI של gcloud או בדפי 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, יכול להיות שהמשימה לא הצליחה לפעול בגלל גודל יתר של התלות שמותקנת. משתמשים בסוג מכונה גדול יותר של Cloud Build worker על ידי העברת --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

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