פתרון בעיות בשליפת תמונות

אם קונטיינרים לא מופעלים ב-Google Kubernetes Engine ‏ (GKE), יכול להיות שתראו סטטוסים של Pod כמו ErrImagePull או ImagePullBackOff. הסיבה למצבים האלה היא לרוב בעיה בתהליך משיכת האימג', שבו Kubernetes מנסה לאחזר את קובץ האימג' של הקונטיינר ממאגר. כשל בתהליך הזה עלול למנוע את הפעלת האפליקציות או לגרום לעיכובים בפריסה.

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

  • הגדרות אימות: לאשכול אין את ההרשאות הנדרשות כדי לגשת למאגר קובץ אימג' של קונטיינר.
  • קישוריות לרשת: לא ניתן לחבר את האשכול לרישום בגלל בעיות ב-DNS, כללי חומת אש או חוסר גישה לאינטרנט באשכולות שמשתמשים בבידוד רשת.
  • התמונה לא נמצאה במאגר: שם התמונה או התג שצוינו שגויים, התמונה נמחקה או שהמאגר לא זמין.
  • מגבלות ביצועים: גודל תמונה גדול, קלט/פלט איטי בדיסק או עומס ברשת עלולים לגרום לשליפות איטיות או לפסק זמן.
  • ארכיטקטורת תמונה לא תואמת: התמונה נוצרה לארכיטקטורת CPU שונה ממאגר הצמתים של GKE.
  • גרסאות סכימה לא תואמות: יכול להיות שאתם משתמשים ב-containerd 2.0 ואילך עם סכימת Docker v1, שלא נתמכת.

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

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

הסבר על שליפת תמונות

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

מחזור החיים של תמונה

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

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

אפשרויות לאירוח תמונות

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

  • ‫Artifact Registry: ‏ Artifact Registry הוא כלי לניהול חבילות של Google שמנוהל באופן מלא. ‫Artifact Registry משתלב בצורה הדוקה עם שירותים אחרים של Google Cloud Google Cloud ומציע בקרת גישה פרטנית. מידע נוסף מופיע במאמר עבודה עם תמונות של קונטיינרים במסמכי התיעוד של Artifact Registry.

  • מרשם באירוח עצמי: מרשם באירוח עצמי מאפשר לכם יותר שליטה, אבל אתם גם צריכים לנהל את המרשם. כדאי לשקול את האפשרות הזו אם יש לכם צרכים ספציפיים של תאימות או אבטחה ש-Artifact Registry לא יכול לספק.

אבחון של כשל בשליפת תמונה

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

  1. צפייה בסטטוס ובאירועים של ה-Pod.
  2. הסבר על משמעות הסטטוס.
  3. אפשר להשתמש בהודעות אירועים כדי למצוא את הסיבה לכשל בשליפת התמונה.
  4. צפייה ביומנים של Logs Explorer.

צפייה בסטטוס ובאירועים של ה-Pod

כדי לעזור לכם לוודא שהשליפה של התמונה נכשלה, GKE מתעד את הסטטוסים הבאים של ה-Pods:

  • ImagePullBackOff
  • ErrImagePull
  • ImageInspectError
  • InvalidImageName
  • RegistryUnavailable
  • SignatureValidationFailed

הסטטוסים הכי נפוצים הם ImagePullBackOff ו-ErrImagePull.

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

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

המסוף

כך עושים את זה:

  1. נכנסים לדף Workloads במסוף Google Cloud .

    כניסה לדף Workloads

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

  3. בדף Details של עומס העבודה, מחפשים את הקטע Managed pods ולוחצים על שם ה-Pod עם סטטוס שמציין כשל בשליפת תמונה.

  4. בדף Details של ה-Pod, לוחצים על הכרטיסייה Events.

  5. בודקים את המידע בטבלה. בעמודה Message מפורטים אירועי Kubernetes, שבהם מוצג מידע נוסף על משיכות תמונות שנכשלו. בעמודה סיבה מפורט הסטטוס של ה-Pod.

kubectl

כך עושים את זה:

  1. כדי לראות את הסטטוס של ה-Pods:

    kubectl get pods -n NAMESPACE

    מחליפים את NAMESPACE במרחב השמות שבו פועלים ה-Pods.

    הפלט אמור להיראות כך:

    NAME         READY   STATUS       RESTARTS      AGE
POD_NAME_1   2/2     Running      0             7d5h
POD_NAME_2   0/1     ErrImagePull 0             7d5h

    בעמודה Status מצוין אילו Pods נכשלו בשליפת תמונה.

  2. כדי לראות אירועים של Pods עם שגיאות משיכה של תמונות:

    kubectl describe pod POD_NAME -n NAMESPACE

    מחליפים את POD_NAME בשם של ה-Pod שזיהיתם בשלב הקודם.

    בקטע Events מוצג מידע נוסף על מה שקרה במהלך משיכות תמונה שנכשלו.

    הפלט אמור להיראות כך:

    ...
Events:
  Type    Reason    Age               From           Message
  ----    ------    ----              ----           -------
  Warning  Failed   5m (x4 over 7m)   kubelet, NODE  Failed to pull image "IMAGE_ADDRESS": rpc error: code = Unknown desc = Error response from daemon: repository IMAGE_ADDRESS not found
  Warning  Failed   5m (x4 over 7m)   kubelet, NODE  Error: ErrImagePull
  Normal   BackOff  5m (x6 over 7m)   kubelet, NODE  Back-off pulling image "IMAGE_ADDRESS"
  Warning  Failed   2m (x20 over 7m)  kubelet, NODE  Error: ImagePullBackOff

    בפלט הזה, IMAGE_ADDRESS היא הכתובת המלאה של התמונה. לדוגמה, us-west1-docker.pkg.dev/my-project/my-repo/test:staging.

הסבר על משמעות הסטטוס

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

  • ‫ImagePullBackOff: kubelet לא הצליח למשוך את התמונה, אבל הוא ימשיך לנסות עם השהיה הולכת וגדלה (או השהיה לפני ניסיון חוזר (backoff)) של עד חמש דקות.
  • ‫ErrImagePull: שגיאה כללית שלא ניתן לשחזר במהלך תהליך משיכת התמונה.
  • ‫ImageInspectError: זמן הריצה של הקונטיינר נתקל בבעיה בניסיון לבדוק את קובץ האימג' של הקונטיינר.
  • ‫InvalidImageName: השם של קובץ אימג' של קונטיינר שצוין בהגדרת ה-Pod לא תקין.
  • ‫RegistryUnavailable: אין גישה למאגר. בדרך כלל מדובר בבעיה בחיבור לרשת.
  • ‫SignatureValidationFailed: לא הייתה אפשרות לאמת את החתימה הדיגיטלית של תמונת המאגר.

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

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

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

Failed to pull image "IMAGE_ADDRESS": rpc error: code = CODE = failed to pull and unpack image "IMAGE_ADDRESS": failed to resolve reference "IMAGE_ADDRESS":

ההודעה הזו כוללת את הערכים הבאים:

  • IMAGE_ADDRESS: הכתובת המלאה של התמונה. לדוגמה, us-west1-docker.pkg.dev/my-project/my-repo/test:staging.
  • ‫CODE: קוד שגיאה שמשויך להודעה ביומן. לדוגמה, NotFound או Unknown.

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

הודעה על אירוע פתרון בעיות מפורט
אימות
  • Failed to authorize: failed to fetch oauth token: unexpected status: 403 Forbidden
  • Pulling from host HOST_NAME failed with status code: 403 Forbidden
  • Failed to authorize: failed to fetch oauth token: unexpected status: 401 Unauthorized

  • Unexpected status code [manifests 1.0]: 401 Unauthorized
קישוריות רשת
  • Failed to do request: Head "IMAGE_ADDRESS": dial tcp: lookup gcr.io on REGISTRY_IP_ADDRESS: server misbehaving
  • Failed to start Download and install k8s binaries and configurations
  • Failed to do request: Head "IMAGE_ADDRESS": dial tcp REGISTRY_IP_ADDRESS: i/o timeout
התמונה לא נמצאה
  • "IMAGE_ADDRESS": not found
  • Failed to copy: httpReadSeeker: failed open: could not fetch content descriptor sha256:SHA_HASH (application/vnd.docker.container.image.v1+json) from remote: not found
זמן קצוב לתמונה
  • Unknown desc = context canceled
סכימה לא תואמת
  • Failed to get converter for "IMAGE_ADDRESS": Pulling Schema 1 images have been deprecated and disabled by default since containerd v2.0. As a workaround you may set an environment variable `CONTAINERD_ENABLE_DEPRECATED_PULL_SCHEMA_1_IMAGE=1`, but this will be completely removed in containerd v2.1.

צפייה ביומנים ב-Logs Explorer

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

  1. נכנסים לדף Logs Explorer במסוף Google Cloud .

    כניסה לדף Logs Explorer

  2. בחלונית השאילתה, מזינים את השאילתה הבאה:

    log_id("events")
resource.type="k8s_pod"
resource.labels.cluster_name="CLUSTER_NAME"
jsonPayload.message=~"Failed to pull image"

    מחליפים את CLUSTER_NAME בשם של האשכול שבו פועל ה-Pod עם שגיאות בשליפת האימג'.

  3. לוחצים על הפעלת שאילתה ובודקים את התוצאות.

בדיקת הגדרות האימות

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

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

  1. מוודאים שיש לכם גישה לתמונה.
  2. מאמתים את ההגדרה של imagePullSecret ואת מפרט הפריסה.
  3. בודקים את הסטטוס הפעיל של חשבון השירות של הצומת.
  4. אימות היקף הגישה של הצומת למאגר פרטי ב-Artifact Registry
  5. כדי לגשת אל Artifact Registry, צריך לוודא שההגדרות של VPC Service Controls נכונות.

אימות הגישה לתמונה

אם נתקלתם בשגיאה 403 Forbidden image pull, ודאו שלרכיבים הנדרשים יש גישה לקובץ אימג' של קונטיינר.

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

Artifact Registry

אם משתמשים ב-imagePullSecret, לחשבון השירות שמקושר ל-Secret צריכה להיות הרשאת קריאה למאגר. אחרת, לחשבון השירות של מאגר הצמתים צריכה להיות הרשאה.

  1. פועלים לפי ההוראות במאמרי ה-IAM בנושא הצגת התפקידים שהוקצו לחשבון השירות.

  2. אם לחשבון השירות שלכם אין את תפקיד ה-IAM‏ Artifact Registry Reader‏ (roles/artifactregistry.reader), צריך להקצות אותו:

    gcloud artifacts repositories add-iam-policy-binding REPOSITORY_NAME \
    --location=REPOSITORY_LOCATION \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL \
    --role="roles/artifactregistry.reader"

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

    • ‫REPOSITORY_NAME: השם של מאגר Artifact Registry.
    • ‫REPOSITORY_LOCATION: האזור של מאגר Artifact Registry.
    • SERVICE_ACCOUNT_EMAIL: כתובת האימייל של חשבון השירות הנדרש. אם אתם לא יודעים את הכתובת, אתם יכולים להשתמש בפקודה gcloud iam service-accounts list כדי להציג רשימה של כל כתובות האימייל של חשבונות השירות בפרויקט.

Container Registry

אם משתמשים ב-imagePullSecret, לחשבון השירות שמקושר ל-Secret צריכה להיות הרשאת קריאה למאגר. אחרת, לחשבון השירות של מאגר הצמתים צריכה להיות הרשאה.

  1. פועלים לפי ההוראות במאמרי ה-IAM בנושא הצגת התפקידים שהוקצו לחשבון השירות.

  2. אם לחשבון השירות שלכם אין את תפקיד ה-IAM‏ Storage Object Viewer‏ (roles/storage.objectViewer), צריך להקצות אותו כדי שחשבון השירות יוכל לקרוא מהקטגוריה:

    gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL \
    --role=roles/storage.objectViewer

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

    • SERVICE_ACCOUNT_EMAIL: כתובת האימייל של חשבון השירות הנדרש. אפשר להציג את הרשימה של כל חשבונות השירות בפרויקט באמצעות הפקודה gcloud iam service-accounts list.
    • ‫BUCKET_NAME: השם של קטגוריית Cloud Storage שמכילה את התמונות. כדי לראות את כל הקטגוריות בפרויקט, משתמשים בפקודה gcloud storage ls.

אם האדמין של המאגר הגדיר מאגרי gcr.io ב-Artifact Registry לאחסון תמונות עבור הדומיין gcr.io במקום Container Registry, צריך להעניק גישת קריאה ל-Artifact Registry במקום ל-Container Registry.

מאגר מידע בהארחה עצמית

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

אם אתם משתמשים במפתחות, צריך להשתמש ב-imagePullSecret. ‏imagePullSecrets הן דרך מאובטחת לספק לאשכול את פרטי הכניסה שהוא צריך כדי לגשת למאגר פרטי שמתארח בעצמו. דוגמה להגדרת imagePullSecret מופיעה במאמר Pull an Image from a Private Registry (שליפת תמונה ממאגר פרטי) במסמכי התיעוד של Kubernetes.

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

אימות ההגדרה של imagePullSecret ומפרט הפריסה

אם אתם משתמשים ב-imagePullSecret, ודאו שיצרתם סוד שמכיל את פרטי הכניסה לאימות לצורך משיכת תמונות, ושהגדרתם בכל הפריסות את הסוד שהגדרתם. מידע נוסף זמין במאמר Specifying imagePullSecrets on a Pod (ציון imagePullSecrets ב-Pod) במאמרי העזרה של Kubernetes.

אימות הסטטוס הפעיל של חשבון השירות של הצומת

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

המסוף

  1. מוצאים את השם של חשבון השירות שבו הצמתים משתמשים:

    1. נכנסים לדף Clusters במסוף Google Cloud .

      כניסה לדף Clusters

    2. ברשימת האשכולות, לוחצים על שם האשכול שרוצים לבדוק.

    3. מוצאים את השם של חשבון השירות של הצומת.

      • בקטע Security של אשכולות במצב Autopilot, מוצאים את השדה חשבון שירות.
      • לגבי אשכולות במצב רגיל:
      1. לוחצים על הכרטיסייה Nodes.
      2. בטבלה Node pools (מאגרי צמתים), לוחצים על שם של מאגר צמתים. הדף פרטי מאגר הצמתים נפתח.
      3. בקטע Security, מוצאים את השדה חשבון שירות.

      אם הערך בשדה חשבון שירות הוא default, הצמתים משתמשים בחשבון השירות שמוגדר כברירת מחדל של Compute Engine. אם הערך בשדה הזה לא default, הצמתים משתמשים בחשבון שירות בהתאמה אישית.

  2. בודקים אם חשבון השירות של הצומת מושבת:

    1. נכנסים לדף Service accounts במסוף Google Cloud .

      כניסה לדף Service accounts

    2. בוחרים פרויקט.

    3. מחפשים את השם של חשבון השירות שזיהיתם בשלב הקודם.

    4. בודקים את העמודה סטטוס של החשבון. אם חשבון השירות מושבת, הסטטוס של החשבון הוא Disabled.

gcloud

  1. מוצאים את השם של חשבון השירות שבו הצמתים משתמשים:

    • עבור אשכולות במצב Autopilot, מריצים את הפקודה הבאה:
    gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten=autoscaling.autoprovisioningNodePoolDefaults.serviceAccount
    • לגבי אשכולות במצב רגיל, מריצים את הפקודה הבאה:
    gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --format="table(nodePools.name,nodePools.config.serviceAccount)"

    אם הפלט הוא default, הצמתים משתמשים בחשבון השירות שמוגדר כברירת מחדל של Compute Engine. אם הפלט לא default, הצמתים משתמשים בחשבון שירות בהתאמה אישית.

  2. בודקים אם חשבון השירות של הצומת מושבת:

    gcloud iam service-accounts list --filter="email:SERVICE_ACCOUNT_NAME AND disabled:true" \
--project=PROJECT_ID

    אם הפקודה מחזירה פלט, חשבון השירות מושבת.

אם חשבון השירות מושבת, צריך להפעיל את חשבון השירות של הצומת.

אימות היקף הגישה של הצומת למאגר פרטי ב-Artifact Registry

אם מאחסנים את קובץ האימג' של הקונטיינר במאגר פרטי ב-Artifact Registry, יכול להיות שלצומת אין את היקף הגישה הנכון. במקרה כזה, יכול להיות שתופיע שגיאה 401 Unauthorized בשליפת התמונה.

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

  1. מזהים את הצומת שבו פועל ה-Pod:

    kubectl describe pod POD_NAME | grep "Node:"

    מחליפים את POD_NAME בשם של ה-Pod שבו נכשלת משיכת האימג'.

  2. מוודאים שלצומת שזיהיתם בשלב הקודם יש היקף אחסון נכון:

    gcloud compute instances describe NODE_NAME \
    --zone="COMPUTE_ZONE" \
    --format="flattened(serviceAccounts[].scopes)"

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

    • ‫NODE_NAME: השם של הצומת שזיהיתם בשלב הקודם.
    • ‫COMPUTE_ZONE: התחום של Compute Engine שאליו שייך הצומת.

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

    • serviceAccounts[0].scopes[0]: https://www.googleapis.com/auth/devstorage.read_only
    • serviceAccounts[0].scopes[0]: https://www.googleapis.com/auth/cloud-platform

    אם הצומת לא מכיל אחת מההרשאות האלה, משיכת התמונה נכשלת.

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

    מומלץ ליצור את מאגר הצמתים עם ההיקף gke-default. היקף ההרשאות הזה מספק גישה להיקפי ההרשאות הבאים:

    • https://www.googleapis.com/auth/devstorage.read_only
    • https://www.googleapis.com/auth/logging.write
    • https://www.googleapis.com/auth/monitoring
    • https://www.googleapis.com/auth/service.management.readonly
    • https://www.googleapis.com/auth/servicecontrol
    • https://www.googleapis.com/auth/trace.append

    אם היקף ההרשאות gke-default לא מתאים, צריך להעניק למאגר הצמתים את היקף ההרשאות devstorage.read_only, שמאפשר גישה רק לקריאת נתונים.

    gke-default

    יוצרים מאגר צמתים עם ההיקף gke-default:

    gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --scopes="gke-default"

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

    • ‫NODE_POOL_NAME: השם של מאגר הצמתים החדש.
    • ‫CLUSTER_NAME: השם של האשכול הקיים.
    • ‫CONTROL_PLANE_LOCATION: המיקום של מישור הבקרה של האשכול ב-Compute Engine. מציינים אזור לאשכולות אזוריים או אזור זמין לאשכולות אזוריים.

    devstorage.read_only

    יוצרים מאגר צמתים עם ההיקף devstorage.read_only:

    gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --scopes="https://www.googleapis.com/auth/devstorage.read_only"

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

    • ‫NODE_POOL_NAME: השם של מאגר הצמתים החדש.
    • ‫CLUSTER_NAME: השם של האשכול הקיים.
    • ‫CONTROL_PLANE_LOCATION: המיקום של מישור הבקרה של האשכול ב-Compute Engine. מציינים אזור לאשכולות אזוריים או אזור זמין לאשכולות אזוריים.

אימות ההגדרות של VPC Service Controls כדי לגשת ל-Artifact Registry

אם אתם משתמשים ב-VPC Service Controls, אתם צריכים לוודא שגבולות הגזרה של השירות מאפשרים גישה ל-Artifact Registry. מידע נוסף מופיע במאמר הגנה על מאגרי מידע בגבולות גזרה לשירות במסמכי התיעוד של Artifact Registry.

בדיקת החיבור לרשת

במהלך משיכת תמונה, חיבור לרשת יכול למנוע את השלמת התהליך.

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

  1. בודקים את פענוח ה-DNS.
  2. בודקים את הגדרת חומת האש.
  3. בודקים את החיבור לאינטרנט של נקודות קצה של רישום חיצוני.
  4. בודקים אם פג הזמן הקצוב לתפוגה של החיבור לממשקי ה-API של Google.

בדיקת פענוח DNS

אם מופיעה שגיאה בשליפת תמונה server misbehaving, יכול להיות שהבעיה היא בפענוח DNS.

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

  1. פתרון בעיות בשרת המטא-נתונים שרת המטא-נתונים של הצומת פותר את כל שאילתות ה-DNS. בעיות שקשורות לשרת הזה עלולות לשבש את תהליך תרגום השמות, למנוע חיבור למאגר ולגרום לכשל בשליפת התמונה.
  2. אם אתם משתמשים ב-Cloud DNS לפענוח DNS, ודאו שהתחומים הפרטיים המנוהלים, תחומים להעברה, תחומים לפירינג ומדיניות התגובה של Cloud DNS מוגדרים בצורה נכונה. הגדרות שגויות באזורים האלה עלולות לשבש את פענוח ה-DNS. מידע נוסף על Cloud DNS זמין במאמר שימוש ב-Cloud DNS ל-GKE. לקבלת עצות לפתרון בעיות ב-Cloud DNS ב-GKE, אפשר לעיין במאמר פתרון בעיות ב-Cloud DNS ב-GKE.
  3. אם אתם משתמשים ב-kube-dns לפענוח DNS, ודאו שהוא פועל בצורה תקינה. לקבלת עצות לפתרון בעיות ב-kube-dns, אפשר לעיין במאמר בנושא פתרון בעיות ב-kube-dns ב-GKE.
  4. אם לצמתים של האשכול אין כתובות IP חיצוניות (מה שקורה בדרך כלל אם משתמשים בבידוד רשת), צריך להפעיל גישה פרטית ל-Google ברשת המשנה שבה נעשה שימוש באשכול, ולוודא שאתם עומדים בדרישות הרשת. אם משתמשים ב-Cloud NAT,‏Google Cloud מופעלת גישה פרטית ל-Google באופן אוטומטי.

בדיקה של הגדרת חומת האש

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

Failed to start Download and install k8s binaries and configurations

אבחון בעיות בחומת האש

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

  1. משתמשים ב-SSH כדי להתחבר לצומת שבו מתרחשות בעיות:

    gcloud compute ssh NODE_NAME --zone=ZONE_NAME

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

  2. שליחת היומנים האחרונים של השירותים kube-node-installation.service ו-kube-node-configuration.service לקובצי טקסט בשמות kube-node-installation_status.txt ו-kube-node-configuration_status.txt:

    systemctl status kube-node-installation.service > kube-node-installation_status.txt
systemctl status kube-node-configuration.service > kube-node-configuration_status.txt

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

    sudo journalctl -u kube-node-installation.service > kube-node-installation_logs.txt
sudo journalctl -u kube-node-configuration.service > kube-node-configuration_logs.txt

  3. בודקים את התוכן של kube-node-installation_status.txtand kube-node-configuration_status.txt ושל הקבצים. אם אתם רואים i/o timeout בפלט, סביר להניח שהבעיה היא בחומת האש.

פתרון בעיות בהגדרות של חומת האש

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

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

    1. גישה ל-VPC Flow Logs:

      1. נכנסים לדף Logs Explorer במסוף Google Cloud .

        כניסה לדף Logs Explorer

      2. בחלונית השאילתה, מזינים את השאילתה הבאה:

        resource.type="gce_subnetwork"
logName="projects/PROJECT_ID/logs/[compute.googleapis.com%2Fvpc_flows](http://compute.googleapis.com%2Fvpc_flows)"
resource.labels.subnetwork_name="SUBNET_NAME",

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

        • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
        • ‫SUBNET_NAME: השם של רשת המשנה.

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

    2. אם אתם מוצאים כללים לחומת האש שחוסמים תנועה נדרשת, עדכנו אותם.

  2. אם לצמתים של האשכול אין כתובות IP חיצוניות (מה שקורה בדרך כלל אם משתמשים בבידוד רשת), צריך להפעיל גישה פרטית ל-Google ברשת המשנה שבה נעשה שימוש באשכול, ולוודא שאתם עומדים בדרישות הרשת. אם משתמשים ב-Cloud NAT,‏Google Cloud מופעלת גישה פרטית ל-Google באופן אוטומטי.

בדיקת החיבור לאינטרנט של נקודות קצה חיצוניות של מאגרי מידע

אם הגדרת הרשת שלכם מכוונת את התנועה דרך נקודת קצה של רישום חיצוני, יכול להיות שלנקודת הקצה הזו אין חיבור לאינטרנט. אם לנקודת הקצה אין גישה, יכול להיות שהשליפה של התמונה תיכשל ותופיע שגיאת שליפה של התמונה i/o timeout.

כדי לבדוק את החיבור לרשת מנקודת הקצה של המרשם החיצוני למרשם, משתמשים ב-ping או ב-traceroute:

ping REGISTRY_ENDPOINT

או

traceroute REGISTRY_ENDPOINT

מחליפים את REGISTRY_ENDPOINT בנקודת הקצה (endpoint) של המאגר. הערך יכול להיות שם מארח או כתובת IP.

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

  1. במסוף Google Cloud , פותחים את הדף Routes.

    לדף Routes

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

בדיקה אם פג הזמן הקצוב לתפוגה של החיבור ל-Google APIs

אם אתם משתמשים בבידוד רשת, יכול להיות שתיתקלו בשגיאה שבה החיבור ל-Google APIs ולשירותים נכשל בגלל חריגה מזמן קצוב לתפוגה, מה שמוביל לשגיאה בשליפת תמונה i/o timeout.

השגיאה הזו מתרחשת כי הצמתים לא הצליחו לגשת לאחד מהממשקי ה-API הבאים כשניסו לשלוף תמונות מהמאגר:

  • containerregistry.googleapis.com
  • artifactregistry.googleapis.com

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

  1. מפעילים את האפשרות גישה פרטית ל-Google. לצמתים ללא כתובות IP חיצוניות נדרשת גישה פרטית ל-Google כדי להגיע לכתובות ה-IP החיצוניות של Google APIs והשירותים של Google.
  2. להשתמש בדומיין נתמך.

  3. בדיקת מדיניות חומת האש:

    1. נכנסים אל Firewall policies במסוף Google Cloud .

      לדף Firewall policies

    2. בודקים אם יש כללים שחוסמים תעבורת TCP יוצאת ביציאה 443 אל 199.36.153.4/30, אל 199.36.153.8/30 או אל כל טווח כתובות IP שמשמש את הדומיין שבחרתם עבור ממשקי API ושירותים של Google. טווחי כתובות ה-IP‏ 199.36.153.4/30 ו-199.36.153.8/30 משמשים לגישה פרטית ל-Google ולגישה מוגבלת ל-Google, בהתאמה. תנועת TCP ביציאה 443 לטווחים האלה היא לצורך גישה לממשקי API ולשירותים של Google.

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

  4. אם אתם משתמשים ב-Artifact Registry, אתם צריכים לוודא שהסביבה שלכם עומדת בדרישות לשימוש ב-Artifact Registry עם בידוד רשת.

  5. מוודאים שכתובות ה-IP הווירטואליות (VIP) (199.36.153.4/30 או 199.36.153.8/30) מוגדרות עם נתיבי VPC:

    1. נכנסים לרשתות VPC במסוף Google Cloud .

      מעבר לרשתות VPC

    2. בעמודה שם, לוחצים על ברירת מחדל.

    3. בדף הפרטים של רשת ה-VPC, לוחצים על הכרטיסייה Routes.

    4. בודקים את טבלת המסלולים.

      אם רשת ה-VPC מכילה נתיב ברירת מחדל (יעד 0.0.0.0/0 או ::0/0) והקפיצה הבאה בנתיב הזה היא שער האינטרנט שמוגדר כברירת מחדל (Network default), צריך להשתמש בנתיב הזה כדי שכתובות ה-VIP יוכלו לגשת לשירותים ולממשקי Google API.

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

בדיקה למה kubelet לא יכול למצוא את התמונה

אם kubelet לא מצליח למצוא את התמונה, יכול להיות שתופיע image not found שגיאה ופעולות השליפה של התמונה ייכשלו.

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

  1. בודקים את קובץ המניפסט של ה-Pod ומוודאים ששם התמונה ותג התמונה מאויתים בצורה נכונה. שגיאות איות או פורמט יגרמו לכשל בשליפת התמונה.
  2. מוודאים שהתמונה עדיין קיימת במאגר שבו היא אוחסנה. אם לתמונה יש נתיב רישום מלא, מוודאים שהיא קיימת במאגר Docker שבו אתם משתמשים. אם מספקים רק את שם התמונה, צריך לבדוק את רישום Docker Hub.
  3. אם באשכול שלכם נעשה שימוש בבידוד רשת, נסו את הפתרונות הבאים:
    1. הפעלת גישה פרטית ל-Google
    2. מוודאים שגבולות גזרה לשירות מוגדרים כהלכה.

בדיקה למה יש פסק זמן לשליפת תמונות או שליפה איטית של תמונות

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

יכול להיות שתבחינו גם בשליפות תמונות שלא נכשלות, אבל לוקח להן הרבה יותר זמן מהרגיל. כדי לקבל נתון בסיסי של משך הזמן הרגיל של שליפת התמונות, כדאי לעיין ברשומה ביומן Successfully pulled image. לדוגמה, בהודעה ביומן הבאה אפשר לראות ששליפת התמונה נמשכה 30.313387996 שניות:

Successfully pulled image "IMAGE_ADDRESS" in 30.313387996s.

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

  1. בודקים אם יש הפסקות שירות. אם שמתם לב לבעיה רק במהלך פרק זמן מסוים, כדאי לבדוק אם היו הפסקות זמניות בשירות Google Cloud .
  2. בודקים את ביצועי הדיסק. קצב קריאה/כתיבה איטי בדיסק יכול להאריך את הזמן של שליפת התמונות. כדאי לשדרג לדיסקים מתמידים עם SSD‏ (pd-ssd) או להשתמש בדיסקים גדולים יותר כדי לשפר את הביצועים. לקבלת טיפים נוספים, אפשר לעיין במאמר פתרון בעיות שקשורות לביצועי הדיסק.
  3. הקטנת גודל התמונה. לדוגמה, יכול להיות שתוכלו להעביר חלק מהנתונים מתמונות המאגר לנפחים מתמשכים.
  4. כדאי להשתמש בשמירה במטמון של תמונות כדי לקצר את זמני ההפעלה של ה-Pod. מערכת GKE שומרת תמונות במטמון בצמתים. במהלך משיכת תמונה, זמן הריצה של הקונטיינר מוריד רק שכבות שלא קיימות כבר במטמון. כדי למקסם את היעילות של מנגנון השמירה במטמון ולצמצם את הזמן של שליפת התמונות, כדאי לבנות את קובץ ה-Dockerfile כך שהחלקים של התמונה שמשתנים לעיתים קרובות (כמו קוד האפליקציה) יופיעו לקראת סוף הקובץ, ולהשתמש בתמונות בסיס קטנות יותר.
  5. מפעילים סטרימינג של תמונות. התכונה הזו יכולה להאיץ את הפעלת ה-Pod ואת ההורדות של התמונות. מידע נוסף זמין במאמר שימוש בסטרימינג של תמונות כדי לשלוף תמונות של קונטיינרים.
  6. מוודאים שלחשבון השירות שמוגדר כברירת מחדל יש את ההרשאות הנדרשות. שינוי תפקידים שמוקצים לחשבון השירות שמוגדר כברירת מחדל עלול לשבש את עומסי העבודה, כולל משיכת תמונות. לקבלת עצות נוספות, אפשר לעיין במאמר בנושא זיהוי אשכולות עם חשבונות שירות של צמתים שחסרות להם הרשאות קריטיות.
  7. בדיקת הגדרות ה-proxy. אם יש שרת Proxy בין אשכול GKE לבין מאגר שמנוהל על ידי גורם שאינו Google, יכול להיות שיהיו השהיות.
  8. בודקים תוכנות של צד שלישי. תוכנות מסוימות של צד שלישי עלולות לשבש את משיכת התמונות. בודקים אם כלים שהותקנו לאחרונה עלולים לגרום לקונפליקטים.

מוודאים שארכיטקטורת המניפסט של התמונה נכונה

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

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

  1. כדי לבדוק באיזו ארכיטקטורה התמונה שלכם משתמשת, צריך להציג את המניפסט של התמונה. לדוגמה, כדי להציג קובץ אימג' של Docker, מריצים את הפקודה הבאה:

    docker manifest inspect --verbose IMAGE_NAME

    מחליפים את IMAGE_NAME בשם של האימג' שרוצים לראות.

    הפלט אמור להיראות כך:

    ...
"Platform": {
          "architecture": "amd64",
          "os": "linux"
  }
...

    בדוגמה הזו, הארכיטקטורה הנתמכת היא amd64.

  2. בודקים את סוג המכונה שמשמשת את מאגרי הצמתים:

    gcloud container node-pools list --cluster CLUSTER_NAME --location CONTROL_PLANE_LOCATION

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

    • ‫CLUSTER_NAME: השם של האשכול שבו פועל ה-Pod עם שגיאות משיכת התמונה.
    • ‫CONTROL_PLANE_LOCATION: המיקום של מישור הבקרה של האשכול ב-Compute Engine. מציינים אזור לאשכולות אזוריים או אזור זמין לאשכולות אזוריים.

    הפלט אמור להיראות כך:

    NAME: example-node-pool
MACHINE_TYPE: e2-standard-2
DISK_SIZE_GB: 100
NODE_VERSION: 1.30.8-gke.1162000

    בדוגמה הזו, סוג המכונה הוא e2-standard-2.

  3. משווים את הערכים בשדות architecture ו-MACHINE_TYPE ומוודאים שהערכים תואמים. לדוגמה, אם לתמונה יש ארכיטקטורה של amd64, היא תהיה תואמת למאגר צמתים שמשתמש ב-amd64 כסוג המכונה שלו.e2-standard-2 אבל אם נעשה שימוש במאגר הצמתים t2a-standard-1 (סוג מכונה וירטואלית מבוסס-Arm), סוג המכונה הווירטואלית הזה יגרום לכשל.

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

אימות התאימות של גרסת סכימת התמונות

שימוש ב-containerd 2.0 עם קובץ אימג' של סכימת Docker v1 גורם לכשל בשליפת קובץ האימג' כי ב-containerd 2.0 הוסרה התמיכה בשליפת קובצי אימג' של Docker Schema 1 ב-GKE 1.33. אם הבעיה הזו היא הסיבה לכשל בשליפת התמונה, יכול להיות שתוצג הודעת השגיאה הבאה:

Failed to get converter for "IMAGE_ADDRESS": Pulling Schema 1 images have been deprecated and disabled by default since containerd v2.0. As a workaround you may set an environment variable `CONTAINERD_ENABLE_DEPRECATED_PULL_SCHEMA_1_IMAGE=1`, but this will be completely removed in containerd v2.1.

כדי לפתור את הבעיה, צריך לזהות את התמונות האלה ולהעביר אותן לפי ההוראות במאמר העברה מתמונות Docker Schema 1.

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