שימוש בתבניות Flex לאריזת צינור עיבוד נתונים ב-Dataflow לצורך פריסה

בדף הזה מוסבר איך ליצור תבנית Flex לצינור Dataflow. תבניות Flex מאפשרות לארוז את קוד צינור עיבוד הנתונים של Apache Beam כדי להריץ את צינור עיבוד הנתונים בלי להשתמש בסביבת פיתוח. כשיוצרים תבנית Flex, כל מי שיש לו את ההרשאות המתאימות יכול להריץ את צינור הנתונים כמשימת Dataflow.

לקבלת מדריך מקצה לקצה ליצירה ולהרצה של תבנית Flex, ראו פיתוח פתרונות והרצה של תבנית Flex לדוגמה.

סקירה כללית

תבנית גמישה מורכבת מהרכיבים הבאים:

קובץ אימג' של קונטיינר שמאוחסן ב-Artifact Registry. הקונטיינר אחראי להפעלת משימת Dataflow.
קובץ מפרט JSON שמאוחסן ב-Cloud Storage. הקובץ הזה מכיל מצביע לקובץ אימג' של קונטיינר ומטא-נתונים אחרים.

לפני שיוצרים תבנית Flex, צריך להשתמש ב-SDK של Apache Beam כדי לכתוב את קוד צינור הנתונים. מידע נוסף זמין במאמר שימוש ב-Apache Beam לבניית צינורות.

התוכנית שיוצרת את הצינור צריכה לצאת אחרי הקריאה ל-run, כדי שהצינור יתחיל. אל תקראו לפונקציות waitUntilFinish (ב-Java) או wait_until_finish (ב-Python), כי הפונקציות האלה חוסמות ומונעות את ההפעלה של FlexTemplate.

ההרשאות הנדרשות

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

אדמין באחסון (roles/storage.admin)
עריכה ב-Cloud Build (roles/cloudbuild.builds.editor)
בעל הרשאת כתיבה ב-Artifact Registry (roles/artifactregistry.writer)

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

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

מטא-נתונים של תבנית

אפשר גם לספק מטא-נתונים נוספים לתבנית, כולל:

פרמטרים של צינור עיבוד הנתונים: מצהירים על אפשרויות מותאמות אישית של צינור עיבוד הנתונים שבהן צינור עיבוד הנתונים משתמש. מערכת Dataflow מאמתת את הפרמטרים כששולחים את המשימה של תבנית Flex. אם מריצים את התבנית באמצעותGoogle Cloud המסוף, תיבת הדו-שיח Create job from template כוללת את הפרמטרים של צינור עיבוד הנתונים שהוגדרו במטא-נתונים.
תמיכה בסטרימינג: אפשר לציין אם צינור עיבוד הנתונים תומך בסטרימינג, ואם כן, אם הוא תומך במצב 'פעם אחת בדיוק' או במצב 'לפחות פעם אחת'. המטא-נתונים האלה מאפשרים ל Google Cloud מסוף להציג את האפשרויות הרלוונטיות של צינור הנתונים כשמריצים את התבנית.

כדי לכלול מטא-נתונים נוספים, יוצרים קובץ JSON עם פרמטרי המטא-נתונים. מציינים את הקובץ הזה בדגל --metadata-file של הפקודה gcloud dataflow flex-template build. התוכן של קובץ המטא-נתונים משולב בקובץ מפרט התבנית. מידע נוסף זמין במאמר בנושא יצירת תבנית גמישה.

פרמטרים של מטא-נתונים

מפתח הפרמטר		חובה	תיאור הערך
`name`		כן	השם של התבנית.
`description`		לא	פסקה קצרה של טקסט שמתארת את התבנית.
`streaming`		לא	אם הערך הוא `true`, התבנית הזו תומכת בסטרימינג. ערך ברירת המחדל הוא `false`.
`supportsAtLeastOnce`		לא	אם `true`, התבנית הזו תומכת בעיבוד של לפחות פעם אחת. ערך ברירת המחדל הוא `false`. מגדירים את הפרמטר הזה לערך `true` אם התבנית מיועדת לעבודה עם מצב סטרימינג של לפחות פעם אחת.
`supportsExactlyOnce`		לא	אם `true`, התבנית הזו תומכת בזמן עיבוד של פעם אחת בדיוק. ערך ברירת המחדל הוא `true`.
`defaultStreamingMode`		לא	מצב הסטרימינג שמוגדר כברירת מחדל בתבניות שתומכות גם במצב 'לפחות פעם אחת' וגם במצב 'בדיוק פעם אחת'. משתמשים באחד מהערכים הבאים: `"AT_LEAST_ONCE"`, `"EXACTLY_ONCE"`. אם לא מציינים ערך, מצב הסטרימינג שמוגדר כברירת מחדל הוא בדיוק פעם אחת.
`parameters`		לא	מערך של פרמטרים נוספים שהתבנית משתמשת בהם. מערך ריק משמש כברירת מחדל.
	`name`	כן	שם הפרמטר שמשמש בתבנית.
	`label`	כן	מחרוזת שקריאה לאנשים ומשמשת ב Google Cloud מסוף לתווית של הפרמטר.
	`helpText`	כן	פסקת טקסט קצרה שמתארת את הפרמטר.
	`isOptional`	לא	‫`false` אם הפרמטר נדרש ו-`true` אם הפרמטר אופציונלי. אם לא מגדירים ערך, ברירת המחדל של `isOptional` היא `false`. אם לא כוללים את מפתח הפרמטר הזה במטא-נתונים, המטא-נתונים הופכים לפרמטר חובה.
	`regexes`	לא	מערך של ביטויים רגולריים של POSIX-egrep בצורת מחרוזת שמשמש לאימות הערך של הפרמטר. לדוגמה, `["^[a-zA-Z][a-zA-Z0-9]+"]` הוא ביטוי רגולרי יחיד שבודק שהערך מתחיל באות ואחריו יש תו אחד או יותר. מערך ריק משמש כברירת מחדל.

קובץ מטא-נתונים לדוגמה

Java

{
  "name": "Streaming Beam SQL",
  "description": "An Apache Beam streaming pipeline that reads JSON encoded messages from Pub/Sub, uses Beam SQL to transform the message data, and writes the results to a BigQuery",
  "parameters": [
    {
      "name": "inputSubscription",
      "label": "Pub/Sub input subscription.",
      "helpText": "Pub/Sub subscription to read from.",
      "regexes": [
        "[a-zA-Z][-_.~+%a-zA-Z0-9]{2,}"
      ]
    },
    {
      "name": "outputTable",
      "label": "BigQuery output table",
      "helpText": "BigQuery table spec to write to, in the form 'project:dataset.table'.",
      "isOptional": true,
      "regexes": [
        "[^:]+:[^.]+[.].+"
      ]
    }
  ]
}

Python

{
  "name": "Streaming beam Python flex template",
  "description": "Streaming beam example for python flex template.",
  "parameters": [
    {
      "name": "input_subscription",
      "label": "Input PubSub subscription.",
      "helpText": "Name of the input PubSub subscription to consume from.",
      "regexes": [
        "projects/[^/]+/subscriptions/[a-zA-Z][-_.~+%a-zA-Z0-9]{2,}"
      ]
    },
    {
      "name": "output_table",
      "label": "BigQuery output table name.",
      "helpText": "Name of the BigQuery output table name.",
      "isOptional": true,
      "regexes": [
        "([^:]+:)?[^.]+[.].+"
      ]
    }
  ]
}

אפשר להוריד קבצים של מטא-נתונים לתבניות ש-Google מספקת מספריית התבניות של Dataflow.

משתני סביבה

כשיוצרים תבנית Flex, מציינים את משתני הסביבה הבאים בדגל --env של הפקודה gcloud dataflow flex-template build. אם אתם משתמשים באימג' בהתאמה אישית, אתם צריכים להגדיר את משתני הסביבה האלה בקובץ Dockerfile.

Java

ENV	תיאור	חובה
`FLEX_TEMPLATE_JAVA_MAIN_CLASS`	מציינת איזו מחלקת Java להריץ כדי להפעיל את תבנית Flex.	כן
`FLEX_TEMPLATE_JAVA_CLASSPATH`	מציין את המיקום של קובצי המחלקה.	כן
`FLEX_TEMPLATE_JAVA_OPTIONS`	מציינת את האפשרויות של Java שיועברו בזמן ההפעלה של תבנית Flex.	לא

מציינים את FLEX_TEMPLATE_JAVA_MAIN_CLASS ואת FLEX_TEMPLATE_JAVA_CLASSPATH בקובץ Dockerfile.

Python

ENV	תיאור	חובה
`FLEX_TEMPLATE_PYTHON_PY_FILE`	מציין איזה קובץ Python להפעיל כדי להשיק את תבנית Flex.	כן
`FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE`	מציין את קובץ הדרישות עם יחסי התלות של הצינור. מידע נוסף זמין במאמר PyPI dependencies במסמכי התיעוד של Apache Beam.	לא
`FLEX_TEMPLATE_PYTHON_SETUP_FILE`	מציין את הנתיב לקובץ `setup.py` של חבילת צינור הנתונים. מידע נוסף זמין במאמר בנושא תלות במספר קבצים במסמכי התיעוד של Apache Beam.	לא
`FLEX_TEMPLATE_PYTHON_EXTRA_PACKAGES`	מציין את החבילות שלא זמינות לציבור. מידע על שימוש בחבילות נוספות זמין במאמר Local or non-PyPI Dependencies.	לא
`FLEX_TEMPLATE_PYTHON_PY_OPTIONS`	מציינת את אפשרויות Python שיועברו בזמן הפעלת תבנית Flex.	לא

מציינים את FLEX_TEMPLATE_PYTHON_PY_FILE בקובץ Dockerfile.

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

FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE
FLEX_TEMPLATE_PYTHON_PY_OPTIONS
FLEX_TEMPLATE_PYTHON_SETUP_FILE
FLEX_TEMPLATE_PYTHON_EXTRA_PACKAGES

לדוגמה, משתני הסביבה הבאים מוגדרים במדריך בנושא סטרימינג בתבנית Python Flex ב-GitHub:

ENV FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE="${WORKDIR}/requirements.txt"
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="${WORKDIR}/streaming_beam.py"

Go

ENV	תיאור	חובה
`FLEX_TEMPLATE_GO_BINARY`	מציין את קובץ ה-Go הבינארי להפעלה.	כן

מציינים את FLEX_TEMPLATE_GO_BINARY בקובץ Dockerfile.

תמונות בתבניות Flex

תבנית Flex כוללת קובץ אימג' של קונטיינר שמפעיל את צינור הנתונים של Dataflow. כשמריצים משימה של Flex Template, שירות Dataflow מוריד את קובץ האימג' של הקונטיינר מ-Artifact Registry ומתחיל את הקונטיינר. הקונטיינר אחראי להפעלת משימת Dataflow.

‫Google מתחזקת קבוצה של תמונות בסיס של Flex Template שבהן אפשר להשתמש. עם זאת, אם צינור הנתונים שלכם דורש קובץ אימג' של קונטיינר בהתאמה אישית, מומלץ להשתמש באותו קובץ אימג' עבור תבנית Flex. כך, מפעיל FlexTemplate מכיל את אותן תלויות כמו קונטיינר זמן הריצה של צינור הנתונים.

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

כדי ליצור תמונת תבנית Flex מותאמת אישית, צריך לכלול את השלבים הבאים ב-Dockerfile:

מעתינים את הקובץ הבינארי של Flex Template launcher מאחד מתמונות הבסיס ש-Google מספקת לתמונה שלכם. קובץ ההפעלה הבינארי נמצא בנתיב הבא:

Java
/opt/google/dataflow/java_template_launcher

Python
/opt/google/dataflow/python_template_launcher

Go
/opt/google/dataflow/go_template_launcher
מעתיקים את הארטיפקטים שנדרשים להפעלת משימת צינור הנתונים, כמו קובצי Python, קובצי JAR או קבצים בינאריים של Go.
מגדירים את משתני הסביבה שמפורטים בקטע משתני סביבה.

בדוגמה הבאה מוצג קובץ Dockerfile לצינור עיבוד נתונים של Python:

# Flex Template base image. Used here to get the launcher binary.
FROM gcr.io/dataflow-templates-base/IMAGE_NAME:TAG as template_launcher

# Apache Beam SDK image. This is the base image for the pipeline job.
FROM apache/beam_python3.10_sdk:2.69.0

# Customize the image for your pipeline.
# [...]

# Configure the Flex Template.
COPY --from=template_launcher /opt/google/dataflow/python_template_launcher /opt/google/dataflow/python_template_launcher
COPY my_pipeline.py /template/
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="/template/my_pipeline.py"

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

‫IMAGE_NAME: תמונת בסיס שסופקה על ידי Google. לדוגמה: python311-template-launcher-base.
‫TAG: תג גרסה של תמונת הבסיס שמופיעה בתמונות בסיס של תבניות Flex. כדי לשפר את היציבות ולפתור בעיות, מומלץ להימנע משימוש ב-latest. במקום זאת, מצמידים תג גרסה ספציפי.

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

יצירת תבנית Flex

כדי ליצור תבנית Flex, משתמשים בפקודה gcloud dataflow flex-template build. הפקודה הזו יוצרת את הארטיפקטים הבאים:

קובץ המפרט של התבנית, שמאוחסן ב-Cloud Storage
קובץ האימג' של הקונטיינר של מרכז האפליקציות, שמאוחסן ב-Artifact Registry

שימוש בתמונת בסיס ש-Google מספקת

כדי להפעיל Flex Template באמצעות קובץ אימג' בסיסי שסופק על ידי Google, מריצים את הפקודה הבאה:

Java

gcloud dataflow flex-template build gs://BUCKET_NAME/TEMPLATE_FILE_NAME \
  --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG" \
  --sdk-language "JAVA" \
  --flex-template-base-image "BASE_IMAGE" \
  --metadata-file "METADATA_FILE" \
  --jar "JAR_FILE" \
  --env "FLEX_TEMPLATE_JAVA_MAIN_CLASS=JAVA_MAIN_CLASS"

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

‫BUCKET_NAME: השם של קטגוריה ב-Cloud Storage שבה יישמר קובץ מפרט התבנית
‫TEMPLATE_FILE_NAME: השם של קובץ מפרט התבנית שרוצים ליצור. לדוגמה: my_template.json
‫LOCATION: המיקום של מאגר Artifact Registry
‫PROJECT_ID: מזהה הפרויקט Google Cloud
‫REPOSITORY: השם של מאגר Artifact Registry
‫IMAGE: השם של קובץ אימג' של קונטיינר של תבנית Flex
TAG: התג של קובץ אימג' של קונטיינר של תבנית Flex
<pBASE_IMAGE: the base image to use. Specify one of the following: A predefined label, such as "JAVA17". For more information, see the documentation for the --flex-template-base-image flag. The full gcr.io path to a specific container version, in the following format: gcr.io/dataflow-templates-base/IMAGE:TAG.


  
    ‫METADATA_FILE: הנתיב המקומי לקובץ מטא. מידע נוסף זמין במאמר בנושא מטא-נתונים של תבניות.
  

  
    ‫JAR_FILE: הנתיב המקומי לקובץ ה-JAR של קוד צינור הנתונים. אם יש כמה קובצי JAR, צריך לעצב אותם כרשימה מופרדת בפסיקים או לציין אותם בדגלי --jar נפרדים.
  
  
    ‫JAVA_MAIN_CLASS: השם של מחלקת Java להרצה. מידע נוסף זמין במאמר משתני סביבה.


 Python 





  



gcloud dataflow flex-template build gs://BUCKET_NAME/TEMPLATE_FILE_NAME \
  --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG" \
  --sdk-language "PYTHON" \
  --flex-template-base-image "BASE_IMAGE" \
  --metadata-file "METADATA_FILE" \
  --py-path "PYTHON_FILE_PATH" \
  --env "FLEX_TEMPLATE_PYTHON_PY_FILE=PYTHON_FILE"


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

  
    ‫BUCKET_NAME: השם של קטגוריה ב-Cloud Storage שבה יישמר קובץ מפרט התבנית
  
  
    ‫TEMPLATE_FILE_NAME: השם של קובץ מפרט התבנית שרוצים ליצור. לדוגמה: my_template.json
  
  
    ‫LOCATION: המיקום של מאגר Artifact Registry
  
  
    ‫PROJECT_ID: מזהה הפרויקט Google Cloud 
  
  
    ‫REPOSITORY: השם של מאגר Artifact Registry
  
  
    ‫IMAGE: השם של קובץ אימג' של קונטיינר של תבנית Flex
  
  
    TAG: התג של קובץ אימג' של קונטיינר של תבנית Flex
  
  
    <pBASE_IMAGE: the base image to use. Specify one of the following:
    
      
        A predefined label, such as "PYTHON3". For more information, see the documentation
        for the 
        --flex-template-base-image flag.
      
      
        The full gcr.io path to a specific container version, in the following format:
        gcr.io/dataflow-templates-base/IMAGE:TAG.
      
    
  

  
    ‫METADATA_FILE: הנתיב המקומי לקובץ מטא. מידע נוסף זמין במאמר בנושא מטא-נתונים של תבניות.
  

  
    ‫PYTHON_FILE_PATH: הנתיב המקומי לקובצי Python של צינור הנתונים, ולכל קובצי התלות שלהם. אפשר לציין כמה נתיבים כרשימה שמופרדת בפסיקים או כדגלים נפרדים של --py-path.
  
  
    ‫PYTHON_FILE: קובץ Python להרצה. מידע נוסף זמין במאמר משתני סביבה.
  


 Go 





  



gcloud dataflow flex-template build gs://BUCKET_NAME/TEMPLATE_FILE_NAME \
  --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG" \
  --sdk-language "GO" \
  --flex-template-base-image "BASE_IMAGE" \
  --metadata-file "METADATA_FILE" \
  --go-binary-path="GO_FILE_PATH" \
  --env "FLEX_TEMPLATE_GO_BINARY=GO_BINARY"


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

  
    ‫BUCKET_NAME: השם של קטגוריה ב-Cloud Storage שבה יישמר קובץ מפרט התבנית
  
  
    ‫TEMPLATE_FILE_NAME: השם של קובץ מפרט התבנית שרוצים ליצור. לדוגמה: my_template.json
  
  
    ‫LOCATION: המיקום של מאגר Artifact Registry
  
  
    ‫PROJECT_ID: מזהה הפרויקט Google Cloud 
  
  
    ‫REPOSITORY: השם של מאגר Artifact Registry
  
  
    ‫IMAGE: השם של קובץ אימג' של קונטיינר של תבנית Flex
  
  
    TAG: התג של קובץ אימג' של קונטיינר של תבנית Flex
  
  
    <pBASE_IMAGE: the base image to use. Specify one of the following:
    
      
        A predefined label, such as "GO". For more information, see the documentation
        for the 
        --flex-template-base-image flag.
      
      
        The full gcr.io path to a specific container version, in the following format:
        gcr.io/dataflow-templates-base/IMAGE:TAG.
      
    
  

  
    ‫METADATA_FILE: הנתיב המקומי לקובץ מטא. מידע נוסף זמין במאמר בנושא מטא-נתונים של תבניות.
  

  
    ‫GO_FILE_PATH: הנתיב המקומי לקובץ הבינארי של Go שעבר קומפילציה עבור הצינור
  
  
    ‫GO_BINARY: קובץ ה-Go הבינארי להרצה. מידע נוסף זמין במאמר משתני סביבה.


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

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

 Java 
gcloud dataflow flex-template build gs://BUCKET_NAME/TEMPLATE_FILE_NAME \
  --image "CUSTOM_IMAGE" \
  --sdk-language "JAVA" \
  --metadata-file "METADATA_FILE"

 Python 
gcloud dataflow flex-template build gs://BUCKET_NAME/TEMPLATE_FILE_NAME \
  --image "CUSTOM_IMAGE" \
  --sdk-language "PYTHON" \
  --metadata-file "METADATA_FILE"

 Go 
gcloud dataflow flex-template build gs://BUCKET_NAME/TEMPLATE_FILE_NAME \
  --image "CUSTOM_IMAGE" \
  --sdk-language "GO" \
  --metadata-file "METADATA_FILE"


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


‫BUCKET_NAME: השם של קטגוריה ב-Cloud Storage שבה יישמר קובץ מפרט התבנית.
‫TEMPLATE_FILE_NAME: השם של קובץ המפרט של התבנית. לדוגמה: my_template.json.
‫CUSTOM_IMAGE: המיקום של מאגר התמונות של התמונה המותאמת.
‫METADATA_FILE: הנתיב המקומי לקובץ מטא.


יחסי תלות של חבילות ב-Python

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

כשמריצים עבודת Python Dataflow שמשתמשת בתבניות Flex בסביבה שבה הגישה לאינטרנט מוגבלת, צריך לארוז מראש את יחסי התלות כשיוצרים את התבנית.

אפשר להשתמש באחת מהאפשרויות הבאות כדי לארוז מראש תלויות של Python.


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


הוראות לניהול יחסי תלות של צינורות ב-Java וב-Go זמינות במאמר ניהול יחסי תלות של צינורות ב-Dataflow.

שימוש בקובץ דרישות ואריזה מראש של יחסי התלות עם התבנית

אם אתם משתמשים בקובץ Dockerfile משלכם כדי להגדיר את תמונת Flex Template,
פועלים לפי השלבים הבאים:


יוצרים קובץ requirements.txt שמפרט את התלויות של הפייפליין.
COPY requirements.txt /template/
ENV FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE="/template/requirements.txt"

מתקינים את יחסי התלות בתמונת התבנית הגמישה.
RUN pip install --no-cache-dir -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE

מורידים את יחסי התלות למטמון הדרישות המקומי, שמועבר לעובדי Dataflow כשהתבנית מופעלת.
RUN pip download --no-cache-dir --dest /tmp/dataflow-requirements-cache -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE



כשמשתמשים בגישה הזו, יחסי התלות מקובץ requirements.txt מותקנים בעובדי Dataflow בזמן הריצה. תובנה בכרטיסייה 'המלצות' ב Google Cloud מסוף
עשויה לציין את ההתנהגות הזו. כדי להימנע מהתקנת תלות בזמן הריצה, משתמשים בקובץ אימג' מותאם אישית של קונטיינר.

דוגמת הקוד הבאה משתמשת בקובץ דרישות ב-FlexTemplate.








  
  














  





  
    
  
  











  









  




  




  
# Copyright 2020 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

FROM gcr.io/dataflow-templates-base/python3-template-launcher-base

# Configure the Template to launch the pipeline with a --requirements_file option.
# See: https://beam.apache.org/documentation/sdks/python-pipeline-dependencies/#pypi-dependencies
ENV FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE="/template/requirements.txt"
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="/template/streaming_beam.py"

COPY . /template

RUN apt-get update \
    # Install any apt packages if required by your template pipeline.
    && apt-get install -y libffi-dev git \
    && rm -rf /var/lib/apt/lists/* \
    # Upgrade pip and install the requirements.
    && pip install --no-cache-dir --upgrade pip \
    # Install dependencies from requirements file in the launch environment.
    && pip install --no-cache-dir -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE \
    # When FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE  option is used,
    # then during Template launch Beam downloads dependencies
    # into a local requirements cache folder and stages the cache to workers.
    # To speed up Flex Template launch, pre-download the requirements cache
    # when creating the Template.
    && pip download --no-cache-dir --dest /tmp/dataflow-requirements-cache -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE

# Set this if using Beam 2.37.0 or earlier SDK to speed up job submission.
ENV PIP_NO_DEPS=True

ENTRYPOINT ["/opt/google/dataflow/python_template_launcher"]






























מבנה הצינור כחבילה ושימוש בחבילות מקומיות

כשמשתמשים בכמה קבצים או מודולים מקומיים של Python, צריך לבנות את צינור עיבוד הנתונים כחבילה. מבנה הקובץ יכול להיראות כמו בדוגמה הבאה:
main.py
pyproject.toml
setup.py
src/
  my_package/
    __init__.py
    my_custom_dofns_and_transforms.py
    my_pipeline_launcher.py
    other_utils_and_helpers.py

ממקמים את נקודת הכניסה ברמה העליונה, למשל קובץ main.py, בספריית השורש. את שאר הקבצים שומרים בתיקייה נפרדת בתוך התיקייה src, לדוגמה, my_package.
מוסיפים את קובצי ההגדרות של החבילה לספריית השורש עם הפרטים והדרישות של החבילה.

pyproject.toml
[project]
name = "my_package"
version = "package_version"
dependencies = [
  # Add list of packages (and versions) that my_package depends on.
  # Example:
  "apache-beam[gcp]==2.54.0",
]

setup.py
  """An optional setuptools configuration stub for the pipeline package.

  Use pyproject.toml to define the package. Add this file only if you must
  use the --setup_file pipeline option or the
  FLEX_TEMPLATE_PYTHON_SETUP_FILE configuration option.
  """

  import setuptools
  setuptools.setup()


מידע נוסף על הגדרת חבילה מקומית זמין במאמר בנושא אריזת פרויקטים של Python.
כשמייבאים מודולים או קבצים מקומיים לצינור, משתמשים בmy_package שם החבילה כנתיב הייבוא.
from my_package import word_count_transform

מתקינים את חבילת צינור עיבוד הנתונים בתבנית Flex. קובץ ה-Dockerfile של תבנית Flex עשוי לכלול תוכן שדומה לדוגמה הבאה:

קובץ Docker
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="${WORKDIR}/main.py"
ENV FLEX_TEMPLATE_PYTHON_SETUP_FILE="${WORKDIR}/setup.py"

# Copy pipeline, packages and requirements.
WORKDIR ${WORKDIR}
COPY main.py .
COPY pyproject.toml .
COPY setup.py .
COPY src src

# Install local package.
RUN pip install -e .



כשמשתמשים בגישה הזו, יחסי התלות מקובץ requirements.txt מותקנים בעובדי Dataflow בזמן הריצה. תובנה בכרטיסייה 'המלצות' ב Google Cloud מסוף
עשויה לציין את ההתנהגות הזו. כדי להימנע מהתקנת תלות בזמן הריצה, כדאי להשתמש בקובץ אימג' של קונטיינר בהתאמה אישית.

דוגמה לגישה המומלצת מופיעה במדריך Flex Template for a pipeline with dependencies and a custom container image ב-GitHub.

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

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

כדי להשתמש במאגר תגים מותאם אישית:


יוצרים קובץ אימג' של קונטיינר בהתאמה אישית שכולל התקנה מראש של יחסי תלות נדרשים.
מתקינים מראש את אותן תלויות בקובץ Dockerfile של תבנית Flex.

כדי למנוע התקנה של תלות בזמן ריצה, אל תשתמשו באפשרויות FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE או FLEX_TEMPLATE_PYTHON_SETUP_FILE בהגדרות של תבנית Flex.

דוגמה לתבנית Flex שעברה שינוי:Dockerfile
FROM gcr.io/dataflow-templates-base/python3-template-launcher-base
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="/template/main.py"
COPY . /template
# If you use a requirements file, pre-install the requirements.txt.
RUN pip install --no-cache-dir -r /template/requirements.txt
# If you supply the pipeline in a package, pre-install the local package and its dependencies.
RUN pip install -e /template

כשמשתמשים בגישה הזו, מבצעים את הפעולות הבאות:


ליצור את קובץ האימג' של תבנית Flex
ליצור קובץ אימג' מותאם אישית של קונטיינר SDK
להתקין את אותם יחסי תלות בשתי התמונות


לחלופין, כדי לצמצם את מספר התמונות שצריך לתחזק, אפשר להשתמש בקובץ אימג' של קונטיינר בהתאמה אישית כקובץ אימג' בסיסי לתבנית Flex.
אם אתם משתמשים ב-Apache Beam SDK בגרסה 2.49.0 או בגרסה קודמת, צריך להוסיף את האפשרות --sdk_location=container pipeline למפעיל של צינור הנתונים.
האפשרות הזו מציינת לצינור העברת הנתונים להשתמש ב-SDK מהקונטיינר המותאם אישית במקום להוריד את ה-SDK.
options = PipelineOptions(beam_args, save_main_session=True, streaming=True, sdk_location="container")

מגדירים את הפרמטר sdk_container_image בפקודה flex-template run. לדוגמה:
gcloud dataflow flex-template run $JOB_NAME \
   --region=$REGION \
   --template-file-gcs-location=$TEMPLATE_PATH \
   --parameters=sdk_container_image=$CUSTOM_CONTAINER_IMAGE \
   --additional-experiments=use_runner_v2

מידע נוסף מופיע במאמר בנושא שימוש במאגרי תמונות מותאמים אישית ב-Dataflow.


שימוש במאגר פרטי של Docker עם תבניות Flex

אפשר ליצור קובץ אימג' של תבנית Flex שמאוחסן במאגר Docker פרטי, אם המאגר הפרטי משתמש ב-HTTPS ויש לו אישור תקף.

כדי להשתמש בתמונה ממאגר פרטי, צריך לציין את הנתיב לתמונה, שם משתמש וסיסמה למאגר. שם המשתמש והסיסמה צריכים להיות שמורים ב-Secret Manager. אפשר לספק את הסוד באחד מהפורמטים הבאים:


projects/{project}/secrets/{secret}/versions/{secret_version}
projects/{project}/secrets/{secret}


אם משתמשים בפורמט השני, המערכת של Dataflow משתמשת בגרסה האחרונה כי לא מצוינת גרסה.

אם הרישום משתמש באישור בחתימה עצמית, צריך גם לציין את הנתיב לאישור בחתימה עצמית ב-Cloud Storage.

בטבלה הבאה מפורטות האפשרויות של ה-CLI של gcloud שבהן אפשר להשתמש כדי להגדיר מאגר פרטי.


  
    פרמטר
    תיאור
  
  
    
      image
    
    הכתובת של המרשם. לדוגמה:
      gcp.repository.example.com:9082/registry/example/image:latest.
    
  
  
    
      image-repository-username-secret-id
    
    מזהה הסוד ב-Secret Manager של שם המשתמש לאימות
      במאגר הפרטי. לדוגמה:
      projects/example-project/secrets/username-secret.
    
  
  
    
      image-repository-password-secret-id
    
    מזהה הסוד ב-Secret Manager של הסיסמה לאימות
      למאגר הפרטי. לדוגמה:
      projects/example-project/secrets/password-secret/versions/latest.
    
  
  
    
      image-repository-cert-path
    
    כתובת ה-URL המלאה ב-Cloud Storage של אישור בחתימה עצמית עבור רישום פרטי. הערך הזה נדרש רק אם הרישום משתמש באישור בחתימה עצמית. לדוגמה:
      gs://example-bucket/self-signed.crt.
    
  


זו דוגמה לפקודה ב-Google Cloud CLI שיוצרת תבנית Flex באמצעות תמונה במאגר פרטי עם אישור בחתימה עצמית.

gcloud dataflow flex-template build gs://example-bucket/custom-pipeline-private-repo.json
--sdk-language=JAVA
--image="gcp.repository.example.com:9082/registry/example/image:latest"
--image-repository-username-secret-id="projects/example-project/secrets/username-secret"
--image-repository-password-secret-id="projects/example-project/secrets/password-secret/versions/latest"
--image-repository-cert-path="gs://example-bucket/self-signed.crt"
--metadata-file=metadata.json

כדי ליצור תבנית Flex משלכם, צריך להחליף את ערכי הדוגמה, ויכול להיות שתצטרכו לציין אפשרויות שונות או נוספות.

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


איך מריצים תבנית Flex
איך יוצרים ומריצים תבנית Flex לדוגמה
מידע נוסף על תבניות קלאסיות, תבניות Flex ועל תרחישי השימוש שלהן זמין במאמר תבניות Dataflow.
מידע על פתרון בעיות בתבניות Flex זמין במאמר פתרון בעיות שקשורות לפסק זמן בתבניות Flex.


לדוגמאות נוספות של ארכיטקטורות, תרשימים ושיטות מומלצות, עיינו במאמר Cloud Architecture Center.

פרמטר	תיאור
`image`	הכתובת של המרשם. לדוגמה: `gcp.repository.example.com:9082/registry/example/image:latest`.
`image-repository-username-secret-id`	מזהה הסוד ב-Secret Manager של שם המשתמש לאימות במאגר הפרטי. לדוגמה: `projects/example-project/secrets/username-secret`.
`image-repository-password-secret-id`	מזהה הסוד ב-Secret Manager של הסיסמה לאימות למאגר הפרטי. לדוגמה: `projects/example-project/secrets/password-secret/versions/latest`.
`image-repository-cert-path`	כתובת ה-URL המלאה ב-Cloud Storage של אישור בחתימה עצמית עבור רישום פרטי. הערך הזה נדרש רק אם הרישום משתמש באישור בחתימה עצמית. לדוגמה: `gs://example-bucket/self-signed.crt`.

שימוש בתבניות Flex לאריזת צינור עיבוד נתונים ב-Dataflow לצורך פריסה קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

סקירה כללית

ההרשאות הנדרשות

מטא-נתונים של תבנית

פרמטרים של מטא-נתונים

קובץ מטא-נתונים לדוגמה

Java

Python

משתני סביבה

Java

Python

Go

תמונות בתבניות Flex

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

Java

Python

Go

יצירת תבנית Flex

שימוש בתמונת בסיס ש-Google מספקת

Java

Python

Go

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

Java

Python

Go

יחסי תלות של חבילות ב-Python

שימוש בקובץ דרישות ואריזה מראש של יחסי התלות עם התבנית

מבנה הצינור כחבילה ושימוש בחבילות מקומיות

pyproject.toml

setup.py

קובץ Docker

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

שימוש במאגר פרטי של Docker עם תבניות Flex

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

שימוש בתבניות Flex לאריזת צינור עיבוד נתונים ב-Dataflow לצורך פריסה