הפעלת סביבת Airflow מקומית באמצעות כלי CLI לפיתוח מקומי של Composer

‫Managed Airflow (דור 3) | Managed Airflow (דור 2) | Managed Airflow (דור 1 מדור קודם)

בקטע הזה מוסבר איך ליצור, להגדיר ולהפעיל סביבת Airflow מקומית באמצעות כלי ה-CLI של Composer Local Development.

מידע על כלי ה-CLI לפיתוח מקומי ב-Composer

כלי ה-CLI לפיתוח מקומי של Composer מייעל את הפיתוח של DAG ב-Apache Airflow ל-Managed Airflow על ידי הפעלת סביבת Airflow באופן מקומי. סביבת Airflow המקומית הזו משתמשת באימג' של Airflow build שמשמש גרסה ספציפית של Managed Airflow.

אפשר ליצור סביבת Airflow מקומית על סמך סביבת Managed Airflow קיימת. במקרה הזה, סביבת Airflow המקומית מקבלת את רשימת חבילות PyPI המותקנות ואת שמות משתני הסביבה מסביבת Managed Airflow.

אתם יכולים להשתמש בסביבת Airflow המקומית הזו למטרות בדיקה ופיתוח, למשל כדי לבדוק קוד DAG חדש, חבילות PyPI או אפשרויות הגדרה של Airflow.

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

  • כלי ה-CLI לפיתוח מקומי של Composer תומך בגרסאות של Airflow 3 החל מ-composer-3-airflow-3.1.0-build.8.

  • כלי ה-CLI של Composer לפיתוח מקומי יוצר סביבות Airflow מקומיות בספרייה שבה מריצים את הפקודה composer-dev create. כדי לגשת לסביבת Airflow המקומית שלכם בהמשך, מריצים את פקודות הכלי בנתיב שבו יצרתם את הסביבה המקומית בהתחלה. כל הנתונים של הסביבה המקומית מאוחסנים בספריית משנה בנתיב שבו יצרתם את הסביבה המקומית: ./composer/<local_environment_name>.

  • במחשב צריך להיות מספיק מקום בדיסק כדי לאחסן תמונות של בניית Airflow. כלי ה-CLI של Composer Local Development מאחסן קובץ אימג' אחד לכל גרסת build של Airflow. לדוגמה, אם יש לכם שתי סביבות מקומיות של Airflow עם גרסאות build שונות של Airflow, כלי ה-CLI של Composer Local Development מאחסן שני קובצי אימג' של גרסאות build של Airflow.

  • כלי ה-CLI לפיתוח מקומי של Composer משתמש בפלט עם צבעים. אפשר להשבית את הפלט הצבעוני באמצעות המשתנה NO_COLOR=1: NO_COLOR=1 composer-dev <other commands>.

  • אם יש לכם רק סביבה מקומית אחת, אתם יכולים להשמיט את שם הסביבה המקומית מכל הפקודות של composer-dev, חוץ מהפקודה run-airflow-cmd.

  • מתקינים את יחסי התלות של כלי ה-CLI לפיתוח מקומי של Composer:

  • מתקינים את Docker. ‫Docker צריך להיות מותקן ופועל במערכת המקומית. כדי לוודא ש-Docker פועל, אפשר להריץ כל פקודה ב-Docker CLI, כמו docker ps.

הגדרת פרטי כניסה

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

gcloud auth application-default login

מתחברים ל-CLI של gcloud באמצעות חשבון Google:

gcloud auth login

כל הקריאות ל-API שמתבצעות על ידי הכלי Composer Local Development CLI ו-DAGs מבוצעות מהחשבון שבו אתם משתמשים ב-CLI של gcloud. לדוגמה, אם DAG בסביבת Airflow המקומית קורא את התוכן של קטגוריה של Cloud Storage, לחשבון הזה צריכות להיות הרשאות גישה לקטגוריה. זה שונה מסביבות Managed Airflow, שבהן חשבון השירות של הסביבה מבצע את הקריאות.

התקנה של כלי ה-CLI לפיתוח מקומי של Composer

משכפלים את מאגר ה-CLI של Composer Local Development:

git clone https://github.com/GoogleCloudPlatform/composer-local-dev.git

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

pip install .

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

יצירת סביבת Airflow מקומית באמצעות תמונת build של Airflow

כדי לראות רשימה של קובצי אימג' זמינים ל-build של Airflow, מריצים את הפקודה:

composer-dev list-available-versions --include-past-releases --limit 10

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

composer-dev create \
  --from-image-version IMAGE_VERSION \
  LOCAL_ENVIRONMENT_NAME

פרמטרים אחרים:

composer-dev create \
  --from-image-version IMAGE_VERSION \
  --project PROJECT_ID \
  --port WEB_SERVER_PORT \
  --dags-path LOCAL_DAGS_PATH \
  LOCAL_ENVIRONMENT_NAME

מחליפים את:

  • IMAGE_VERSION בשם של קובץ האימג' של ה-build של Airflow.
  • ‫PROJECT_ID במזהה הפרויקט (Project ID).
  • ‫WEB_SERVER_PORT עם היציאה שבה שרת האינטרנט של Airflow צריך להאזין.
  • ‫LOCAL_DAGS_PATH עם הנתיב לספרייה מקומית שבה נמצאים קובצי ה-DAG.
  • ‫LOCAL_ENVIRONMENT_NAME בשם של סביבת Airflow המקומית.

דוגמה:

composer-dev create \
  --from-image-version composer-3-airflow-2.11.1-build.9 \
  example-local-environment

יצירת סביבת Airflow מקומית מסביבת Managed Airflow

רק המידע הבא נלקח מסביבת Managed Airflow:

  • גרסה ספציפית של Airflow שמשמשת את הסביבה שלכם.

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

  • רשימה עם הערות של שמות משתני הסביבה שהוגדרו בסביבה שלכם.

מידע אחר ופרמטרים של הגדרות מהסביבה, כמו קובצי DAG, היסטוריית הפעלות של DAG, משתני Airflow וחיבורים, לא מועתקים מסביבת Managed Airflow.

כדי ליצור סביבת Airflow מקומית מסביבת Managed Airflow קיימת:

composer-dev create LOCAL_ENVIRONMENT_NAME \
    --from-source-environment ENVIRONMENT_NAME \
    --location LOCATION \
    --project PROJECT_ID \
    --port WEB_SERVER_PORT \
    --dags-path LOCAL_DAGS_PATH

מחליפים את:

  • ‫LOCAL_ENVIRONMENT_NAME בשם של סביבת Airflow מקומית.
  • ‫ENVIRONMENT_NAME בשם של סביבת Managed Airflow.
  • ‫LOCATION באזור שבו נמצאת סביבת Managed Airflow.
  • ‫PROJECT_ID במזהה הפרויקט (Project ID).
  • ‫WEB_SERVER_PORT עם יציאה לשרת האינטרנט המקומי של Airflow.
  • ‫LOCAL_DAGS_PATH עם נתיב לספרייה מקומית שבה נמצאים קובצי ה-DAG.

דוגמה:

composer-dev create example-local-environment \
  --from-source-environment example-environment \
  --location us-central1 \
  --project example-project \
  --port 8081 \
  --dags-path example_directory/dags

הפעלת סביבת Airflow מקומית

כדי להפעיל סביבת Airflow מקומית, מריצים את הפקודה:

composer-dev start LOCAL_ENVIRONMENT_NAME

מחליפים את:

  • ‫LOCAL_ENVIRONMENT_NAME בשם של סביבת Airflow מקומית.

הפסקה או הפעלה מחדש של סביבת Airflow מקומית

כשמפעילים מחדש סביבת Airflow מקומית, כלי ה-CLI של Composer Local Development מפעיל מחדש את קונטיינר Docker שבו הסביבה פועלת. כל הרכיבים של Airflow נעצרים ומופעלים מחדש. כתוצאה מכך, כל ההרצות של DAG שמתבצעות במהלך הפעלה מחדש מסומנות כנכשלות .

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

composer-dev restart LOCAL_ENVIRONMENT_NAME

מחליפים את:

  • ‫LOCAL_ENVIRONMENT_NAME בשם של סביבת Airflow מקומית.

כדי להפסיק סביבת Airflow מקומית, מפעילים:

composer-dev stop LOCAL_ENVIRONMENT_NAME

הוספה ועדכון של DAG

קובצי DAG מאוחסנים בספרייה שציינתם בפרמטר --dags-path כשיצרתם את סביבת Airflow המקומית. כברירת מחדל, הספרייה הזו היא ./composer/<local_environment_name>/dags. אפשר לקבל את הספרייה שבה נעשה שימוש בסביבה באמצעות הפקודה describe.

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

צפייה ביומנים של סביבת Airflow מקומית

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

כדי לראות יומנים מקונטיינר Docker שמריץ את סביבת Airflow המקומית, מריצים את הפקודה:

composer-dev logs LOCAL_ENVIRONMENT_NAME --max-lines 10

כדי לעקוב אחרי זרם היומן, משמיטים את הארגומנט --max-lines:

composer-dev logs LOCAL_ENVIRONMENT_NAME

הרצת פקודה ב-CLI של Airflow

אפשר להריץ פקודות של Airflow CLI בסביבת Airflow המקומית.

כדי להריץ פקודה ב-CLI של Airflow:

composer-dev run-airflow-cmd LOCAL_ENVIRONMENT_NAME \
  SUBCOMMAND SUBCOMMAND_ARGUMENTS

דוגמה:

composer-dev run-airflow-cmd example-local-environment dags list -o table

הגדרת סביבות Airflow מקומיות

כלי ה-CLI של Composer Local Development מאחסן פרמטרים של הגדרות לסביבת Airflow מקומית, כמו משתני סביבה ודרישות של חבילות PyPI בספרייה של הסביבה המקומית (./composer/<local_environment_name>).

ההגדרה מוחלת כשמפעילים סביבת Airflow מקומית. לדוגמה, אם מוסיפים דרישות חבילה סותרות של PyPI, כלי ה-CLI של Composer Local Development מדווח על שגיאות כשמפעילים את הסביבה המקומית.

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

קבלת רשימה וסטטוס של סביבות Airflow מקומיות

כדי להציג רשימה של כל סביבות Airflow המקומיות הזמינות ואת הסטטוס שלהן:

composer-dev list

כדי לתאר סביבה ספציפית ולקבל פרטים כמו גרסת התמונה, נתיב DAG וכתובת URL של שרת אינטרנט של סביבה:

composer-dev describe LOCAL_ENVIRONMENT_NAME

מחליפים את:

  • ‫LOCAL_ENVIRONMENT_NAME בשם של סביבת Airflow המקומית.

רשימת תמונות שמשמשות סביבות Airflow מקומיות

כדי להציג רשימה של כל התמונות שבהן נעשה שימוש בכלי Composer Local Development CLI, מריצים את הפקודה:

docker images --filter=reference='*/cloud-airflow-releaser/*/*'

התקנת תוספים ושינוי נתונים

תוספים ונתונים לסביבת Airflow מקומית נלקחים מהספרייה של הסביבה המקומית: ./composer/<local_environment_name>/data ו-./composer/<local_environment_name>/plugins).

כדי לשנות את התוכן של ספריות /data ו-/plugins, מוסיפים או מסירים קבצים בספריות האלה. ‫Docker מעביר אוטומטית שינויים בקבצים לסביבת Airflow המקומית.

כלי ה-CLI לפיתוח מקומי של Composer לא תומך בהגדרת ספרייה אחרת לנתונים ולתוספים.

הגדרת משתני סביבה

כדי להגדיר משתני סביבה, עורכים את הקובץ variables.env בספריית הסביבה: ./composer/<local_environment_name>/variables.env.

הקובץ variables.env צריך להכיל הגדרות של צמדי מפתח/ערך, שורה אחת לכל משתנה סביבה. כדי לשנות את אפשרויות ההגדרה של Airflow, משתמשים בפורמט AIRFLOW__SECTION__KEY. מידע נוסף על משתני הסביבה הזמינים מופיע במאמר חומר עזר בנושא הגדרות Airflow.

EXAMPLE_VARIABLE=True
ANOTHER_VARIABLE=test
AIRFLOW__WEBSERVER__DAG_DEFAULT_VIEW=graph

כדי להחיל את השינויים, מפעילים מחדש את סביבת Airflow המקומית.

התקנה או הסרה של חבילות PyPI

כדי להתקין או להסיר חבילות PyPI, משנים את הקובץ requirements.txt בספריית הסביבה: ./composer/<local_environment_name>/requirements.txt.

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

כדי להחיל את השינויים, מפעילים מחדש את סביבת Airflow המקומית.

מעבר לתמונת build אחרת של Airflow

אתם יכולים להשתמש בכל קובץ אימג' של Airflow עם כלי ה-CLI של Composer Local Development ולעבור בין קובצי האימג'. הגישה הזו שונה משדרוג סביבת Managed Airflow, כי פרמטרים של הגדרות בסביבת Airflow המקומית מוחלים כשהיא מופעלת.

לדוגמה, אחרי שגרסת build חדשה של Airflow יוצאת, אפשר להעביר את הסביבה שלכם לשימוש בה, ולשמור את ההגדרה הקיימת של סביבת Airflow המקומית.

כדי לשנות את תמונת הסביבה שבה משתמשת סביבת Airflow המקומית:

  1. עורכים את קובץ התצורה של הסביבה המקומית: ./composer/<local_environment_name>/config.json.

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

  3. כדי להחיל את השינויים, מפעילים מחדש את סביבת Airflow המקומית.

מחיקה של סביבת Airflow מקומית

זהירות: חשוב לוודא ששמרתם את כל הנתונים הנדרשים מהסביבה, כמו יומנים והגדרות.

כדי למחוק סביבת Airflow מקומית, מריצים את הפקודה הבאה:

composer-dev remove LOCAL_ENVIRONMENT_NAME

אם הסביבה פועלת, מוסיפים את הדגל --force כדי לכפות את ההסרה שלה.

מחיקת תמונות Docker

כדי למחוק את כל התמונות שהורדו על ידי כלי ה-CLI של Composer Local Development, מריצים את הפקודה:

docker rmi $(docker images --filter=reference='*/cloud-airflow-releaser/*/*' -q)

פתרון בעיות

בקטע הזה מפורטים פתרונות לבעיות נפוצות.

לא ניתן להפעיל סביבה מקומית ב-MacOS

אם התקנתם את חבילת composer-dev בספרייה ש-Docker לא יכול לגשת אליה, יכול להיות שהסביבה המקומית לא תופעל.

לדוגמה, אם Python מותקן בספרייה /opt, כמו במקרה שבו מתקינים אותו עם הגדרת ברירת המחדל של Homebrew ב-MacOS, אז חבילת composer-dev מותקנת גם היא בספרייה /opt. מכיוון ש-Docker עומדת בכללי ארגז החול של Apple, הספרייה /opt לא זמינה כברירת מחדל. בנוסף, אי אפשר להוסיף אותו דרך ממשק המשתמש (הגדרות > משאבים > שיתוף קבצים).

במקרה כזה, כלי ה-CLI של Composer Local Development יוצר הודעת שגיאה שדומה לדוגמה הבאה:

Failed to create container with an error: 400 Client Error for ...
Bad Request ("invalid mount config for type "bind": bind source path does not exist:
/opt/homebrew/lib/python3.9/site-packages/composer_local_dev/docker_files/entrypoint.sh

Possible reason is that composer-dev was installed in the path that is
not available to Docker. See...")

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

  • מתקינים את Python או את חבילת composer-dev בספרייה אחרת, כדי ש-Docker יוכל לגשת לחבילה.
  • עורכים ידנית את הקובץ ~/Library/Group\ Containers/group.com.docker/settings.json ומוסיפים את /opt ל-filesharingDirectories.

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