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

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

שגיאות

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

הודעת השגיאה סוג השגיאה מה המשמעות של השגיאה איך לפתור את השגיאה
Modified during transfer 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 סוג האחסון של המקור שצוין לא מאפשר קריאה. במסמכי התיעוד של ספק שירותי הענן שלכם מוסבר איך להעביר את הנתונים לסוג אחסון שמאפשר להעתיק אותם.
הפעולה נכשלה בגלל 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 משתמש בסוכן שירות, בדרך כלל בפורמט project-PROJECT_NUMBER@storage-transfer-service.. כדי לקבוע את הערך הספציפי של PROJECT_NUMBER, משתמשים בקריאה ל-API‏ googleserviceaccounts.get. מוודאים שלחשבון השירות יש את התפקידים הבאים:
  • ‫roles/storagetransfer.serviceAgent בפרויקט.
  • ‫roles/storage.objectCreator,‏ roles/storage.objectViewer ו-roles/storage.legacyBucketReader לכל הקטגוריות של היעד או הקטגוריות המתווכות (ראו הגדרת גישה ל-sink: Cloud Storage).
הסוכן לא נתמך AGENT_UNSUPPORTED_VERSION גרסת הסוכן לא תואמת יותר ל-Storage Transfer Service. זו שגיאה זמנית שקשורה לעדכון לא תקין של הסוכן. אם זה קורה, מבצעים את הפעולות הבאות:
  1. עצירת כל הסוכנים.
  2. מריצים את הפקודה הבאה כדי למשוך את קובץ האימג' העדכני של Docker: sudo docker pull gcr.io/cloud-ingest/tsop-agent:latest
  3. מריצים את הפקודה run של Docker כדי להפעיל את כל קונטיינרי הסוכנים.
אם הבעיה נמשכת, פנו לצוות התמיכה.
הפעולה נכשלה בגלל חוסר התאמה בגיבוב (hash) 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 העלאות מרובות חלקים הופעלו להעברה הזו, אבל לא הוגדרו ההרשאות הנכונות בקטגוריה. כדי לדעת מהן ההרשאות הנדרשות, קראו את המאמר הגדרת גישה ל-sink: Cloud Storage.
הפריטים לא מוצגים בסדר הנכון 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. מוודאים שהסוכנים יכולים להתחבר לממשקי ה-API של Cloud Storage:

    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.:443

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

הסוכן לא יכול להתחבר לנקודת קצה מסוג 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.

כדי לפתור את הבעיה, צריך למנוע מהסוכן להשתמש במשא ומתן FAST על ידי הוספת הדגל --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.