פתרון בעיות בהעברות של מערכת קבצים

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

שגיאות

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

הודעת השגיאה סוג השגיאה מה המשמעות של השגיאה איך פותרים את השגיאה
השתנה במהלך ההעברה FILE_MODIFIED_FAILURE קובץ המקור השתנה במהלך ההעברה בכל פעם ש-Storage Transfer Service ניסה להעתיק אותו. מונע כתיבה לקובץ שצוין במהלך הפעולה הבאה של Storage Transfer Service.
ההעברה נכשלה PRECONDITION_FAILURE האובייקט ב-Cloud Storage שמשויך לקובץ המקור עבר שינוי בכל פעם ש-Storage Transfer Service ניסה להעלות את הקובץ. כדי למנוע מכמה משימות העברה לכתוב את אותו קובץ לאותה קטגוריה של Cloud Storage, צריך להשתמש בקידומות ייחודיות של אובייקטים ב-Cloud Storage כשיוצרים משימות העברה.
לא נמצאה ספריית קובצי המקור SOURCE_DIR_NOT_FOUND נתיב המקור שצוין שגוי, או שהנתיב נכון אבל לא לכל הסוכנים יש גישה אליו. בודקים את ההגדרות של משימת ההעברה ומוודאים:
לא הייתה אפשרות למצוא את ספריית המקור או היעד של העבודה ROOT_DIR_NOT_FOUND נתיב המקור או היעד שצוין שגוי, או שהנתיב נכון אבל לא לכל הסוכנים יש גישה אליו. בודקים את ההגדרות של משימת ההעברה ומוודאים:
  • הנתיב של המקור או היעד שמופיע ברשימה נכון
  • לסוכנים הרלוונטיים יש גישה לספרייה
הקובץ לא נמצא FILE_NOT_FOUND_FAILURE קובץ המקור נמצא, אבל הוא נמחק לפני שהועבר אל Cloud Storage. אם הקובץ נמחק בטעות, צריך לשחזר אותו כדי שיועלה בהעברה הבאה.
לא הצלחנו למצוא את קטגוריית היעד BUCKET_NOT_FOUND קטגוריית היעד לא קיימת ב-Cloud Storage. מוודאים שהאיות של שם דלי היעד נכון ושהוא קיים.
לא נמצא אובייקט פנימי של מטא-נתונים METADATA_OBJECT_
NOT_FOUND_FAILURE		 ‫Storage Transfer Service מאחסן מטא-נתונים בקטגוריית היעד עם התחילית storage-transfer. אם קובצי המטא-נתונים נמחקים לפני שפעולות ההעברה התואמות מסתיימות, השגיאה הזו מוצגת. מומלץ להימנע ממחיקת אובייקטים עם הקידומת storage-transfer/ בקטגוריית היעד עד שכל משימות ההעברה יסתיימו.
הפעולה נכשלה בגלל שם קובץ לא תקין INVALID_FILE_NAME הנתיב של קובץ מקור לא תקין. בודקים ומתקנים את נתיב הקובץ שצוין. מוודאים שהנתיב משתמש ב תווים שנתמכים על ידי Cloud Storage.
הפעולה נכשלה בגלל סיווג אחסון לא תקין INVALID_FILE_STORAGE_CLASS הגישה לקריאה לא מותרת בסוג האחסון של המקור שצוין. כדי להבין איך להעביר את הנתונים לסוג אחסון (storage class) שמאפשר להעתיק אותם, צריך לעיין במסמכי התיעוד של ספק שירותי הענן.
הפעולה נכשלה בגלל URI לא תקין של סשן העלאה שניתן להמשיך SESSION_URI_INVALID תוקף מזהה ההעלאה שניתן להמשיך או ה-URI של הסשן פג או שהם בוטלו. הניסיון החוזר לביצוע הפעולה נכשל. עליך לפנות לתמיכה.
הפעולה נכשלה בגלל גודל קובץ לא תקין INVALID_FILE_SIZE גודל הקובץ לא תקין. מוודאים שגודל הקובץ הוא ‎ >= 0 ו-‎ <= 5 TiB (גודל האובייקט המקסימלי ב-Cloud Storage) להעברות אל Cloud Storage.
הפעולה נכשלה בגלל הרשאות PERMISSION_FAILURE ו-UNAUTHENTICATED לסוכן ההעברה לא היו הרשאות מספיקות לביצוע פעולה. יש שתי אפשרויות לשגיאה הזו:
  • לא הייתה לסוכן הרשאה מספקת ב-Google Cloud.
  • סוכן לא הצליח לקרוא קובץ או ספרייה בגלל הרשאות לא מספיקות במערכת הקבצים של המקור.

עליך לוודא את הדברים הבאים:
האובייקט כפוף למדיניות שמירת הנתונים של הקטגוריה ואי אפשר למחוק, לשכתב או להעביר אותו לארכיון PERMISSION_FAILURE לקטגוריה יש מדיניות שמירת נתונים בתוקף, והאובייקט כבר קיים בקטגוריה. אי אפשר להשתמש ב-Storage Transfer Service כדי להחליף אובייקטים קיימים בקטגוריה. השגיאה הזו יכולה להופיע אם הקובץ השתנה במקור, או אם Storage Transfer Service מנסה להעלות את הקובץ פעמיים בגלל תנאי הרשת, וההעלאה הראשונה הצליחה. מוודאים שהנתונים בקטגוריה של Cloud Storage תואמים למה שציפיתם. כדי לוודא שהגודל וזמן השינוי (mtime) של קובצי המקור זהים לאלה של האובייקטים המקבילים ב-Cloud Storage, מריצים מחדש את העבודה ומוודאים שאין שגיאות.
לשירות לא היו הרשאות מספיקות SERVICE_PERMISSION_FAILURE ל-Storage Transfer Service לא היו הרשאות מספיקות כדי לבצע פעולה. ‫Storage Transfer Service משתמש בחשבון שירות בניהול Google, בדרך כלל בפורמט project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com, כדי לגשת למשאבים. כדי לקבוע את PROJECT_NUMBER הספציפי, משתמשים בקריאה ל-API‏ googleserviceaccounts.get. מוודאים שלחשבון השירות יש את התפקידים הבאים:
  • roles/storagetransfer.serviceAgent בפרויקט.
  • ‫roles/storage.admin לכל קטגוריות היעד.
אין תמיכה בסוכן AGENT_UNSUPPORTED_VERSION גרסת הסוכן לא תואמת יותר ל-Storage Transfer Service. זו שגיאה זמנית שקשורה לעדכון סוכן פגום. אם זה קורה, צריך לבצע את הפעולות הבאות:
  1. מפסיקים את כל הסוכנים.
  2. כדי לשלוף את קובץ האימג' העדכני ביותר של Docker, מריצים את הפקודה: sudo docker pull gcr.io/cloud-ingest/tsop-agent
  3. מריצים את הפקודה run של Docker כדי להפעיל את כל מאגרי התגים של הסוכן.
אם הבעיה נמשכת, צריך לפנות לצוות התמיכה.
הפעולה נכשלה בגלל חוסר התאמה בגיבוב HASH_MISMATCH_FAILURE בכל פעם ש-Storage Transfer Service ניסה להעלות את הקובץ הזה, הבייטים שהועלו היו פגומים. כתוצאה מכך, הגיבוב של הקובץ המקומי לא תאם לגיבוב של האובייקט שנוצר ב-Cloud Storage. יכול להיות שהשגיאה הזו נגרמת בגלל כמה בעיות אפשריות. אם אתם רואים אחוז קטן של כשלים בהתאמת הגיבוב (פחות מ-1%) בהעברה גדולה, נסו שוב להעביר את הקבצים שנכשלו. אם אתם רואים אחוז גבוה של כשלים בגלל אי התאמה של הגיבוב (1% או יותר), מומלץ לבדוק אם יש כשלים פוטנציאליים בזיכרון, במעבד או בחומרה אחרת במכונת הסוכן.
הפעולה נכשלה בגלל מצב קובץ שלא נתמך UNSUPPORTED_FILE_MODE Storage Transfer Service נתקל בקובץ עם מצב לא נתמך, כמו מכשיר, שקע, צינור בעל שם או קובץ לא סדיר. מסירים את סוגי הקבצים המיוחדים האלה מספריית קובצי המקור.
הפעולה נכשלה בגלל שגיאה במערכת הקבצים FILESYSTEM_ERROR סוכן נתקל בשגיאה במערכת הקבצים או במערכת ההפעלה במהלך ביצוע פעולה במערכת הקבצים, כמו קריאה, חיפוש או סטטוס. קוראים את תיאור הכשל כדי להבין איזו פעולה במערכת הקבצים נכשלה. מוודאים שיש לסוכן המקומי גישה למערכת הקבצים, ושהוא מגיב לפעולות בסיסיות בקבצים.
הפעולה נכשלה כי לא נשאר מקום במערכת הקבצים FILESYSTEM_NO_SPACE_ON_DEVICE הסוכן לא הצליח לבצע פעולה במערכת הקבצים, כמו פתיחה או כתיבה, כי לא היה לו מספיק נפח אחסון. קוראים את תיאור הכשל כדי להבין איזו פעולה במערכת הקבצים נכשלה. מוודאים שיש מספיק מקום במערכת הקבצים כדי לבצע פעולות על קבצים.
הפעולה נכשלה בגלל שגיאה לא ידועה UNKNOWN_FAILURE אירעה שגיאה בלתי צפויה. קוראים את תיאור הכשל. אם תיאור הכשל לא מכיל מספיק מידע כדי לפתור את הבעיה, צריך לפנות לתמיכה.
הפעולה נכשלה בגלל מפרט לא תקין INVALID_SPEC הנציג קיבל מפרט פנימי פגום. בודקים אם יש נתונים פגומים במארחי הסוכנים, ואם לא מוצאים כאלה, פונים לתמיכה.
הפעולה נכשלה בגלל קובץ מניפסט ריק או לא תקין CONFORMANCE_FAILURE הסוכן לא יכול לקרוא או לקבל בייטים תקינים של CSV בגלל פורמט לא תקין או רשומות CSV לא תקינות. מוודאים שהערכים במניפסט הם נתיבי קבצים תקינים. אם תיאור הכשל לא מכיל מספיק מידע כדי לפתור את הבעיה, צריך לפנות לתמיכה.
החזרה להעלאות שניתן להמשיך במקום להעלאות מרובות חלקים בגלל שגיאת דחייה של הרשאה PERMISSION_FAILURE Multipart uploads have been enabled for this transfer, but the correct permissions have not been set on the bucket. ההרשאות הנדרשות מפורטות בקטע Multipart uploads במאמר הרשאות מערכת קבצים.
הערכים מופיעים בסדר לא נכון INCOMPATIBLE_LIST_ORDER_FAILURE מערכת הקבצים של המקור החזירה רשימה של קבצים בסדר שלא תואם ל-Storage Transfer Service. שירות העברת נתונים (Storage Transfer Service) דורש שמערכת הקבצים של המקור תחזיר קבצים בסדר ממוין לקסיקוגרפית. מוודאים שמערכת הקבצים מחזירה קבצים בסדר ממוין לקסיקוגרפית.

צפייה ביומני הנציגים

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

כברירת מחדל, יומני הסוכנים מאוחסנים ב-/tmp. אפשר לשנות את המיקום באמצעות --log-dir=logs-directory אפשרות שורת הפקודה.

שמות היומנים:

agent.hostname.username.log.log-level.timestamp

אלה הרכיבים של שם היומן:

  • ‫hostname – שם המארח שבו פועל הסוכן.
  • ‫username – שם המשתמש שמריץ את הסוכן.
  • log-level הוא אחד מהערכים הבאים:
    • ‫INFO – הודעות עם מידע חשוב
    • ‫ERROR – שגיאות שנתקלו בהן במהלך ההעברה, אבל לא מנעו את המשך העברת העבודה.
    • ‫FATAL – שגיאות שמונעות את המשך העברת העבודה.
  • ‫timestamp – חותמת זמן בפורמט YYYYMMDD-hhmmss.thread-id

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

  • agent.ERROR
  • agent.FATAL
  • agent.INFO

מהירות העברה איטית

אם העברת הנתונים נמשכת זמן רב, כדאי לבדוק את הדברים הבאים:

  1. קצב העברת הנתונים לקריאה של מערכת הקבצים צריך להיות בערך פי 1.5 מקצב ההעלאה הרצוי. אפשר להשתמש ב-FIO כדי לבדוק את קצב העברת הנתונים של הקריאה במערכת הקבצים.

    מתקינים את fio:

     sudo apt install -y fio

    יוצרים ספרייה חדשה fiotest:

     TEST_DIR=/mnt/mnt_dir/fiotest
 sudo mkdir -p $TEST_DIR

    בדיקת קצב העברת הנתונים לקריאה:

     sudo fio --directory=$TEST_DIR --direct=1
    --rw=randread --randrepeat=0 --ioengine=libaio --bs=1M --iodepth=8
    --time_based=1 --runtime=180 --name=read_test --size=1G

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

  2. משתמשים ב-iPerf3 כדי לבדוק את רוחב הפס הזמין של האינטרנט ב-Storage Transfer Service.

  3. מוודאים שלכל סוכן העברה יש לפחות 4 vCPU ו-8GB של RAM.

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

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

פתרון בעיות שקשורות לסוכנים

בקטעים הבאים מוסבר איך לפתור בעיות שקשורות לסוכן ההעברה:

הנציגים לא מחוברים

אם סוכני ההעברה לא מוצגים כמחוברים במסוף Google Cloud :

  1. מוודאים שהסוכנים יכולים להתחבר לממשקי Cloud Storage API:

    1. מריצים את הפקודה הבאה מאותה מכונה שבה מותקן סוכן ההעברה כדי לבדוק את החיבור של הסוכן לממשקי ה-API של Cloud Storage:

      gcloud storage cp test.txt gs://my-bucket

      מחליפים את:

      ‫my-bucket בשם של הקטגוריה ב-Cloud Storage.

  2. אם בפרויקט שלכם נעשה שימוש ב-VPC Service Controls, כדאי לבדוק את יומני הסוכן כדי לראות אם יש שגיאות. אם ההגדרה של VPC Service Controls שגויה, ביומני הסוכן INFO תופיע השגיאה הבאה:

    Request is prohibited by organization's policy. vpcServiceControlsUniqueIdentifier: id

    בפלט הזה:

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

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

שרת ה-proxy דוחה כתובות IP

אם אתם מפעילים שרת proxy כמו Squid ואתם משתמשים ברשימת היתרים, יכול להיות שתראו בקשות שנדחות בגלל שימוש בכתובות IP במקום בשמות מארחים.

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

--transfer-service-endpoint=storagetransfer.googleapis.com:443

אם אתם משתמשים בנקודת קצה חלופית כדי להגיע אל googleapis.com (לדוגמה, ל-Private Service Connect), מחליפים את googleapis.com בנקודת הקצה החלופית.

הסוכן לא מצליח להתחבר לנקודת קצה (endpoint) של HTTPS באמצעות אישור בחתימה עצמית

אם הסוכן לא מצליח להתחבר לנקודת קצה של HTTPS באמצעות אישור בחתימה עצמית, אפשר להשתמש באפשרות -v נוספת כדי לטעון את חבילת האישורים המותאמת אישית למיקום ברירת המחדל של הקונטיינר (/etc/ssl/certs).

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

-v PATH_TO_LOCAL_CERT:/etc/ssl/certs/ca-certificates.crt

מחליפים את:

  • ‫PATH_TO_LOCAL_CERT מחליפים בנתיב לקובץ האישור בהתאמה אישית.

הסוכן לא מופעל: KDC לא הגיב בצורה מתאימה למשא ומתן של FAST

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

Failed to start the agent, err = failed to create HDFS client: Couldn't find the hdfs client: no available namenodes: SASL handshake: [Root cause: KRBMessage_Handling_Error] KRBMessage_Handling_Error: AS Exchange Error: AS_REP is not valid or client password/keytab incorrect < KRBMessage_Handling_Error: KDC did not respond appropriately to FAST negotiation

השגיאה הזו מתרחשת כשמרכז חלוקת המפתחות (KDC) של Kerberos לא תומך בניהול משא ומתן של FAST, שהסוכן מנסה להשתמש בו כברירת מחדל להעברות של HDFS.

כדי לפתור את הבעיה, צריך למנוע מהסוכן להשתמש במשא ומתן מהיר על ידי הוספת הדגל --kerberos-disable-pa-fx-fast כשמפעילים את הסוכן.

הדגל הזה נתמך רק כשמריצים את הסוכן באמצעות docker או podman. אין תמיכה בשימוש בפקודה gcloud transfer agents install.

מוסיפים את הדגל לפקודה docker run או podman run באופן הבא:

docker run --rm -v /usr/local/transfer_agent:/tmp/transfer_agent \
  gcr.io/cloud-ingest/tsop-agent:latest \
  --project-id=PROJECT_ID \
  --hostname=$(hostname) \
  --kerberos-disable-pa-fx-fast

לפרטים נוספים על פקודות docker ו-podman, אפשר לעיין במאמר בנושא התקנה והפעלה של סוכני העברה.