שימוש בשער Connect

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

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

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

    • הגרסה העדכנית של Google Cloud CLI, כלי שורת הפקודה לאינטראקציה עם Google Cloud.
    • kubectl

    אם אתם משתמשים ב-Cloud Shell כסביבת המעטפת שלכם לאינטראקציה עם Google Cloud, הכלים האלה מותקנים אצלכם.

  • מוודאים שהפעלתם את ה-CLI של gcloud לשימוש בפרויקט.

התפקידים הנדרשים

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

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

התפקיד Connect Gateway Admin (roles/gkehub.gatewayAdmin) הוא התפקיד המוגדר מראש היחיד שכולל את ההרשאה gkehub.gateway.stream, שנדרשת להפעלת פקודות CLI של kubectl כמו attach,‏ exec,‏ port-forward ו-cp.

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

כניסה לחשבון Google Cloud

אתם יכולים להשתמש ב Google Cloud חשבון שלכם או ב Google Cloud חשבון שירות כדי לקיים אינטראקציה עם אשכולות מחוברים באמצעות Gateway API.

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

בחירת אשכול רשום

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

gcloud container fleet memberships list

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

קבלת השער של האשכול kubeconfig

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

gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

מחליפים את MEMBERSHIP_NAME בשם החברות בצי של האשכול.

הפקודה הזו מחזירה שער חיבור ספציפי kubeconfig שמאפשר להתחבר לאשכול דרך שער החיבור.

אם רוצים להשתמש בחשבון שירות ולא בחשבון Google Cloud שלכם, משתמשים ב-gcloud config כדי להגדיר את auth/impersonate_service_account לכתובת האימייל בחשבון השירות.

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

  • קלאסטרים של Google Distributed Cloud (תוכנה בלבד) בשרת פיזי וב-VMware: שם החברות זהה לשם הקלאסטר.

  • ‫GKE ב-AWS: משתמשים ב-gcloud container aws clusters get-credentials.

  • ‫GKE ב-Azure: שימוש ב-gcloud container azure clusters get-credentials.

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

gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

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

הרצת פקודות באשכול

אחרי שמקבלים את פרטי הכניסה הנדרשים, אפשר להריץ פקודות באמצעות kubectl או go-client, כמו בכל אשכול Kubernetes. הפלט אמור להיראות כך:

# Get namespaces in the Cluster.
kubectl get namespaces
NAME              STATUS   AGE
default           Active   59d
gke-connect       Active   4d

פקודות kubectl exec/cp/attach/port-forward

הפקודות הבאות של kubectl הן פקודות סטרימינג ויש להן דרישות נוספות:

  • attach
  • cp
  • exec
  • port-forward

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

  • הגרסה של האשכולות צריכה להיות 1.30 ואילך כדי להשתמש בפקודות attach,‏ cp ו-exec, וגרסה 1.31 ואילך כדי להשתמש בפקודה port-forward.

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

  • למשתמשים ולחשבונות שירות צריכה להיות גישה נוספת ל-Kubernetes API דרך IAM או RBAC:

    • ‫IAM: צריך להקצות תפקיד שכולל את ההרשאה gkehub.gateway.stream. ההרשאה הזו כלולה בתפקיד המוגדר מראש roles/gkehub.gatewayAdmin. אפשר גם להקצות את ההרשאה הזו לתפקיד בהתאמה אישית.

    • ‫RBAC: מעניקים תפקיד או ClusterRole שכולל גישה ל-get למשאבי המשנה של ממשקי ה-API ‏pods/exec, ‏pods/portforward ו-pods/attach, כמו בדוגמה הבאה של תפקיד ו-RoleBinding:

      apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: stream-role
  namespace: NAMESPACE # Specify the namespace
rules:
- apiGroups: ["*"]
  resources: ["pods/exec", "pods/attach", "pods/portforward"]
  verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: stream-rolebinding
  namespace: NAMESPACE # Specify the namespace
roleRef:
  apiGroup: "rbac.authorization.k8s.io"
  kind: Role
  name: stream-role
subjects:
- kind: Group
  name: EMAIL # Specify the group that should have stream access

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

      • ‫NAMESPACE: מרחב השמות של Role ו-RoleBinding.
      • ‫EMAIL: כתובת האימייל של הקבוצה שאליה צריך לתת גישה לזרם, אם האשכול תומך בRBAC עם קבוצות.

      ההרשאות האלה כלולות גם ב-ClusterRole cluster-admin כברירת מחדל.

פתרון בעיות

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

  • לשרת אין סוג משאב: יכול להיות שתראו את הודעת השגיאה הזו אם הפקודה kubectl get ns תיכשל. יש כמה סיבות אפשריות לשגיאה הזו. מריצים את הפקודות kubectl במצב מפורט כדי לראות פרטים נוספים, לדוגמה kubectl get ns -v 10.
  • לא נמצאו חיבורים פעילים לאשכול(פרויקט: 12345, חברות: my-cluster): השגיאה הזו עשויה להופיע אם סוכן Connect מאבד את הקישוריות או לא מותקן בצורה תקינה (אשכולות מחוץ ל- Google Cloud בלבד). כדי לפתור את הבעיה, צריך לוודא שמרחב השמות gke-connect קיים באשכול. אם מרחב השמות gke-connect קיים באשכול, אפשר לעיין בדף פתרון בעיות בחיבור כדי לפתור את בעיות הקישוריות.
  • כתובת ה-URL המבוקשת לא נמצאה בשרת הזה: יכול להיות שתראו את השגיאה הזו אם kubeconfig מכיל כתובת שרת שגויה. מוודאים שמשתמשים בגרסה העדכנית ביותר של Google Cloud CLI ומנסים שוב ליצור את שער kubeconfig. אל תערכו ידנית את הקובץ kubeconfig, כי זה עלול לגרום לשגיאות לא צפויות.
  • לזהות המשתמש אין הרשאות מספיקות לשימוש ב-API של השער: צריך את התפקיד roles/gkehub.gatewayAdmin roles/gkehub.gatewayReader או roles/gkehub.gatewayEditor כדי להשתמש ב-API. פרטים נוספים זמינים במאמר הענקת תפקידי IAM למשתמשים במדריך להגדרת השער.
  • לסוכן Connect אין הרשאה לשלוח את הבקשות של המשתמש: צריך לאפשר לסוכן Connect להעביר בקשות בשמכם. ההרשאה הזו מוגדרת באמצעות מדיניות התחזות באשכול. במדריך להגדרת שער, אפשר לעיין במאמר בנושא הגדרת הרשאה של RBAC כדי לראות דוגמה להוספת משתמש לתפקיד gateway-impersonate.
  • לזהות המשתמש אין הרשאות RBAC מספיקות לביצוע הפעולה: כדי להריץ את הפעולות שבחרתם, צריכות להיות לכם הרשאות מתאימות באשכול. במדריך להגדרת שער, בקטע הגדרת הרשאות RBAC, יש דוגמה להוספת משתמש ל-ClusterRole המתאים.
  • לזהות המשתמש אין מספיק הרשאות לביצוע הפעולה כשמשתמשים ב-קבוצות Google או בתמיכה של צד שלישי: במאמר איסוף יומנים של GKE Identity Service מוסבר איך לבדוק יומנים שקשורים לפרטי הזהות.
  • הסוכן Connect לא תקין: כדאי לעיין בדף פתרון הבעיות של Connect כדי לוודא שהאשכול מחובר.
  • לא נמצא קובץ הפעלה gke-gcloud-auth-plugin או לא נמצא ספק אימות בשם gcp: יכול להיות שהשגיאה הזו תוצג בגרסאות 1.26 ואילך של kubectl בגלל שינויים באימות kubectl החל מגרסה 1.26 של GKE. מתקינים את gke-gcloud-auth-plugin ומריצים מחדש את gcloud container fleet memberships get-credentials MEMBERSHIP_NAME עם הגרסה האחרונה של Google Cloud CLI.
  • החיבורים לשער נכשלים בגרסאות ישנות יותר של Google Cloud CLI: באשכולות GKE, סוכן Connect כבר לא נדרש כדי שהשער יפעל, ולכן הוא לא מותקן כברירת מחדל במהלך רישום החברות. בגרסאות קודמות של Google Cloud CLI (גרסה 399.0.0 ומטה), קיימת הנחה לגבי קיומו של סוכן Connect באשכול. ניסיון להשתמש בשער עם הגרסאות הקודמות האלה עלול להיכשל באשכולות שרשומים בגרסה חדשה יותר של Google Cloud CLI. כדי לפתור את הבעיה, אפשר לשדרג את לקוח Google Cloud CLI לגרסה חדשה יותר או להריץ מחדש את פקודת הרישום לחברות עם הדגל --install-connect-agent.
  • הגודל של הקבוצות שמוחזרות בקבוצה gke-security-groups חורג ממגבלת הגודל של כותרת HTTP‏ (8KB). לארגן מחדש את ההיררכיה של הקבוצות ולנסות שוב: אין הגבלה קשיחה על מספר הקבוצות, אבל שמות ארוכים של קבוצות עלולים לגרום לכך שהבקשה תחרוג מהגודל המקסימלי של כותרת ה-HTTP (8 KB) ולגרום לשגיאות. במקרה כזה, יכול להיות שתצטרכו לשנות את המבנה של ההיררכיה של הקבוצות.

פתרון בעיות בפקודות kubectl exec,‏ cp,‏ attach ו-port-forward

השגיאה שמוחזרת מהפעלת הפקודה היא לרוב שגיאה כללית 400 Bad Request שלא ברורה מספיק כדי לנפות את הבעיה. כדי לקבל הודעות שגיאה מפורטות יותר, צריך להשתמש בkubectl בגרסה 1.32 ואילך כדי להריץ את הפקודה עם רמת פירוט של 4 ומעלה, לדוגמה: kubectl exec -v 4 ....

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

  • לפקודה kubectl exec/cp/attach: RemoteCommand fallback:
  • לפקודה kubectl port-forward: fallback to secondary dialer from primary dialer err:

בקטע הבא מוסבר איך לפתור בעיות שקשורות להודעות שגיאה נפוצות שאולי תקבלו מהפקודה kubectl exec -v 4 ....

חסרות הרשאות IAM

אם הודעת השגיאה מכילה את generic::permission_denied: Permission'gkehub.gateway.stream' denied on resource, יכול להיות שלא קיבלתם את הרשאות ה-IAM הנדרשות להרצת הפקודה. כדי להשתמש בתכונה הזו, למשתמשים צריכה להיות הרשאת ה-IAM‏ gkehub.gateway.stream, שכלולה כברירת מחדל בתפקיד roles/gkehub.gatewayAdmin. הוראות מפורטות זמינות בקטע הרשאות IAM.

חסרות הרשאות RBAC נדרשות

אם הודעת השגיאה מכילה את הערך ...generic::failed_precondition: failed to connect to the cluster's API Server with response (status=403 Forbidden..., זה מצביע על כך שחסרות לכם הרשאות RBAC. כדי להריץ את הפקודות האלה של kubectl, צריך להגדיר ב-cluster קבוצה של הרשאות RBAC. מידע נוסף על הגדרת הרשאות RBAC נדרשות זמין במאמר יצירה והחלה של מדיניות RBAC נוספת אם יש צורך.

הודעת השגיאה generic::resource_exhausted: Gateway's active_streams quota exhausted

יש מכסת שידורים פעילים של 10 לכל פרויקט מארח של Fleet. המספר הזה מוגדר במסגרת המכסה של connectgateway.googleapis.com/active_streams. הוראות לניהול המכסות זמינות במאמר הצגה וניהול של מכסות.

הודעת השגיאה generic::failed_precondition: error encountered within the cluster

אם מופיעה השגיאה generic::failed_precondition: error encountered within the cluster, צריך לבדוק את היומנים של Connect Agent באשכול כדי לזהות את הסיבה הבסיסית:

kubectl logs -n gke-connect -l app=gke-connect-agent --tail -1

היומן שצריך לחפש ב-Connect Agent הוא failed to create the websocket connection....

הודעת השגיאה generic::failed_precondition: connection to Agent failed/terminated

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

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

kubectl --raw פתרון בעיות

שימוש בנקודת קצה מקוצרת (כמו kubectl get --raw /version) עלול לגרום לשגיאה הבאה: Error from server (NotFound): the server could not find the requested resource. חובה לציין את הכתובת המלאה של השרת.

מאחזרים את נקודת הקצה מ-kubeconfig:

# e.g. https://connectgateway.googleapis.com/v1/projects/1234567/locations/global/gkeMemberships/my-membership
FULL_GATEWAY_ENDPOINT=$(kubectl config view --minify -o jsonpath='{.clusters[*].cluster.server}')
echo $FULL_GATEWAY_ENDPOINT

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

kubectl get --raw $FULL_GATEWAY_ENDPOINT/version

מה השלב הבא?