שימוש בשער Connect

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

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

ודאו שכלי שורת הפקודה הבאים מותקנים:
- הגרסה האחרונה של Google Cloud CLI, כלי שורת הפקודה לאינטראקציה עם Google Cloud.
- kubectl
אם אתם משתמשים ב-Cloud Shell כסביבת המעטפת שלכם לאינטראקציה עם Google Cloud, הכלים האלה מותקנים בשבילכם.
מוודאים שאתחלתם את ה-CLI של gcloud לשימוש בפרויקט.

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

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

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

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

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

gcloud container fleet memberships list

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

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

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

gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

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

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

אם רוצים להשתמש בחשבון שירות ולא בחשבון 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, אפשר לעיין במאמר בנושא התקנת כלים.

למשתמשים ולחשבונות שירות עם תפקיד ה-IAM‏ roles/gkehub.gatewayAdmin והתפקיד cluster-admin ClusterRole יש את ההרשאות הנדרשות להרצת הפקודות attach,‏ cp,‏ exec ו-port-forward. אם למשתמשים ולחשבונות שירות הוקצה תפקיד IAM בהתאמה אישית או תפקיד RBAC בהתאמה אישית, יכול להיות שתצטרכו להעניק הרשאות נוספות. מידע נוסף מופיע בקטעים הבאים.

נותנים הרשאה נוספת אם צריך

כדי להריץ את הפקודות attach, ‏ cp, ‏ exec ו-port-forward דרך שער Connect, נדרשת הרשאת IAM‏ gkehub.gateway.stream. הרשאה זו כלולה ב-roles/gkehub.gatewayAdmin.

למשתמשים שהם לא בעלי הפרויקט, או למשתמשים או לחשבונות שירות שלא קיבלו את ההרשאה roles/gkehub.gatewayAdmin בפרויקט, צריך להעניק את ההרשאה roles/gkehub.gatewayAdmin או ליצור תפקיד בהתאמה אישית שכולל את שאר התפקידים הנדרשים ואת ההרשאה gkehub.gateway.stream. במאמר יצירה וניהול של תפקידים בהתאמה אישית בחומרי העזר של IAM מוסבר איך יוצרים תפקיד בהתאמה אישית.

יצירה והחלה של מדיניות נוספת של RBAC אם צריך

למשתמשים ולחשבונות שירות עם התפקיד cluster-admin ClusterRole יש את ההרשאות הנדרשות להרצת הפקודות attach, ‏cp, ‏exec ו-port-forward.

כדי להריץ את הפקודות, צריך לפחות את הכללים הבאים:

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: User
  name: EMAIL # Specify the user that should have stream access
  namespace: NAMESPACE  # Specify the namespace

פתרון בעיות

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

לשרת אין סוג משאב: יכול להיות שתופיע הודעת השגיאה הזו כשהפקודה kubectl get ns נכשלת. יכולות להיות כמה סיבות לשגיאה הזו. מריצים את הפקודות kubectl במצב מפורט כדי לראות פרטים נוספים, לדוגמה kubectl get ns -v 10.
Cannot find active connections for cluster(project: 12345, membership: my-cluster): השגיאה הזו עשויה להופיע אם סוכן Connect מאבד את הקישוריות או לא מותקן בצורה תקינה (במקרה של אשכולות מחוץ ל- Google Cloud בלבד). כדי לפתור את הבעיה, צריך לוודא שמרחב השמות gke-connect קיים באשכול. אם מרחב השמות gke-connect קיים באשכול, אפשר לעיין בדף פתרון בעיות בחיבור כדי לפתור את בעיות הקישוריות.
כתובת ה-URL המבוקשת לא נמצאה בשרת הזה: יכול להיות שהשגיאה הזו תוצג אם kubeconfig מכיל כתובת שרת שגויה. מוודאים שמשתמשים בגרסה העדכנית ביותר של Google Cloud CLI ומנסים שוב ליצור את שער kubeconfig. אל תערכו את הקובץ kubeconfig באופן ידני, כי זה עלול לגרום לשגיאות לא צפויות.
לזהות המשתמש אין הרשאות מספיקות לשימוש ב-API של השער: כדי להשתמש ב-API, צריך להיות לכם תפקיד roles/gkehub.gatewayAdmin roles/gkehub.gatewayReader או roles/gkehub.gatewayEditor. פרטים נוספים זמינים במאמר הקצאת תפקידי IAM למשתמשים במדריך להגדרת שער.
לסוכן Connect אין הרשאה לשלוח את הבקשות של המשתמש: צריך לאפשר לסוכן Connect להעביר בקשות בשמכם. ההרשאה הזו מוגדרת באמצעות מדיניות התחזות באשכול. במדריך להגדרת שערים מוסבר איך להוסיף משתמש לתפקיד gateway-impersonate.
לזהות המשתמש אין הרשאות RBAC מספיקות לביצוע הפעולה: כדי להריץ את הפעולות שבחרתם, אתם צריכים הרשאות מתאימות באשכול. במדריך להגדרת שערים מוסבר איך להוסיף משתמש ל-ClusterRole המתאים. אפשר לעיין במאמר בנושא הגדרת הרשאות RBAC.
לזהות המשתמש אין מספיק הרשאות לביצוע הפעולה כשמשתמשים ב-קבוצות Google או בתמיכה של צד שלישי: במאמר איסוף יומנים של שירות הזהויות של GKE מוסבר איך לבדוק יומנים שקשורים לפרטי הזהות.
הסוכן 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 שלא ברורה מספיק כדי לנפות את הבעיה. כדי לקבל הודעות שגיאה מפורטות יותר, צריך להשתמש בגרסה 1.32 ואילך של kubectl כדי להריץ את הפקודה עם רמת פירוט של 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

מה השלב הבא?

במדריך שילוב עם Cloud Build יש דוגמה לשימוש בשער Connect כחלק מאוטומציית DevOps.