סקירה כללית על ממשקי API של Google Distributed Cloud במודל Air-gapped

ממשקי תכנות יישומים (API) של Google Distributed Cloud (GDC)‎ עם air gap הם ממשקים פרוגרמטיים לשירותי הפלטפורמה של GDC. ‫Google בונה את ממשקי ה-API של מישור הבקרה על גבי Kubernetes, באמצעות Kubernetes Resource Model ‏(KRM). מישור הבקרה מבצע ניהול משאבים לשירותים, כמו יצירה, מחיקה ועדכונים.

לשירותים ספציפיים יש את ממשקי ה-API האלה וממשקי API משלהם למישור הנתונים, שמבוססים על XML,‏ JSON או gRPC. השירותים האלה מפורטים בחלקים הרלוונטיים בדף הזה.

מידע על ממשקי ה-API של GDC

יש שני סוגים של ממשקי API ב-GDC: כאלה שמבוססים על Kubernetes וכאלה שלא. הרבה ממשקי API של GDC הם תוספים של ממשק ה-API של Kubernetes בקוד פתוח. הם משתמשים במשאבים בהתאמה אישית של Kubernetes ומסתמכים על KRM. ממשקי ה-API האלה, כמו Kubernetes API, הם ממשקי API בארכיטקטורת REST שמבוססים על HTTP, ומקבלים ומחזירים JSON כברירת מחדל, או ב-Protobuf. נקודת הקצה ל-API היא שרת Kubernetes הרלוונטי.

לממשקי API אחרים של GDC שלא מבוססים על Kubernetes, כמו ממשקי ה-AI API שאומנו מראש של Vertex, יש נקודות קצה משלהם. בנוסף לתמיכה ב-HTTP, חלק מממשקי ה-API האלה נגישים גם באמצעות gRPC, מסגרת הקריאה לשירות מרוחק (RPC) בקוד פתוח. למידע נוסף על ממשקי API ספציפיים, עיינו במסמכי התיעוד הייעודיים שלהם בתפריט הניווט האנכי.

כדי לגשת לממשקי ה-API של GDC, צריך להשתמש בכלי ה-CLI של gdcloud או במסוף GDC.

מידע על Kubernetes API ו-KRM

מכיוון שהרבה מממשקי ה-API של GDC הם תוספים של Kubernetes API ומסתמכים על KRM, הבנה של המושגים האלה תעזור לכם לנצל את ממשקי ה-API של GDC בצורה מלאה.

ממשק ה-API של Kubernetes הוא הצהרתי לחלוטין, וכל מה שנמצא בו הוא משאב שתואם ל-KRM. לקוחות API, אנושיים וממוחשבים, פועלים על המשאבים האלה, בדרך כלל באמצעות פעולות של יצירה, קריאה, עדכון ומחיקה (CRUD). מסד הנתונים של Kubernetes מאחסן את המשאב ומייצג את מצב המערכת. ‫Kubernetes עוקב באופן רציף אחרי המשאבים האלה ומתאים את המצב בפועל של המערכת למצב הרצוי. לדוגמה, אם מעדכנים משאב Deployment כדי לציין שרוצים חמישה עותקים של מאגר במקום ארבעה, Kubernetes מזהה את השינוי במספר העותקים הרצוי ויוצר מאגר נוסף.

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

מידע נוסף על Kubernetes API ועל מודל המשאבים ב-Kubernetes זמין במסמכי התיעוד הרשמיים של Kubernetes.

• סקירה כללית של Kubernetes API, בכתובת https://kubernetes.io/docs/reference/using-api/
• מושגים של Kubernetes API, בכתובת https://kubernetes.io/docs/reference/using-api/api-concepts/
• ‫Kubernetes Resource Model ‏(KRM), בכתובת https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md

ממשקי API גלובליים ושל תחום מוגדר

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

ב-GDC עם air gap יש שני סוגים של ממשקי API לניהול משאבים גלובליים ואזוריים: ממשקי API גלובליים וממשקי API אזוריים.

ממשקי API גלובליים וגם ממשקי API אזוריים הם ממשקי API דקלרטיביים של Kubernetes שמוצגים בנקודות קצה שונות, ומשאבי GDC מיוצגים כמשאבים בהתאמה אישית של Kubernetes בשרתי ה-API. שרתי ה-API הגלובליים משתפים אשכול etcd יחיד שמופץ בין אזורים כדי לספק מודל עקביות חזק עם עמידות בפני תקלות, על חשבון זמן אחזור גבוה יותר ופחות שאילתות כתיבה לשנייה (QPS) בהשוואה לשרתי ה-API האזוריים. בכל ארגון, שרת API לניהול אזורי מספק את ה-API האזורי לאדמינים ולמפתחים כדי לנהל משאבים אזוריים, ושרת API גלובלי מספק את ה-API הגלובלי לניהול משאבים בכמה אזורים.

גישה לממשקי ה-API של GDC

גם הכלים של gdcloud CLI וגם מסוף GDC משתמשים בממשקי ה-API של GDC. ‫Google ממליצה להשתמש בהם כדי לבדוק את GDC או לבצע פעולות חד-פעמיות. עם זאת, אם אתם משתמשים בגישה אוטומטית או פרוגרמטית ל-GDC, ‏ Google ממליצה להשתמש ישירות בממשקי ה-API של GDC.

תמיכה ב-HTTP וב-gRPC

רוב ממשקי ה-API של GDC מספקים ממשק JSON HTTP שאפשר לקרוא לו ישירות. ממשקי ה-API שמבוססים על Kubernetes משתמשים בספריות הלקוח של Kubernetes. לחלק מממשקי ה-API של GDC שאינם של Kubernetes יש ממשק gRPC, שמספק ביצועים ונוחות שימוש משופרים. ‫Google מספקת גם ספריות לקוח לממשקי API של GDC שלא מבוססים על Kubernetes. מידע נוסף על gRPC זמין בכתובת https://grpc.io/.

הצפנת TLS

כל ממשקי ה-API של GDC מקבלים בקשות באמצעות הצפנת Transport Layer Security‏ (TLS).

• אם אתם משתמשים באחת מספריות הלקוח של Kubernetes או GDC, הספרייה מטפלת בהצפנה במעבר.
• אם אתם משתמשים בלקוח HTTP או gRPC משלכם, אתם צריכים לבצע אימות באמצעות GDC, שדורש TLS. ב-gRPC, פועלים לפי ההוראות במדריך האימות של gRPC בכתובת https://grpc.io/docs/guides/auth/.

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

גישה ל-Kubernetes API ולממשקי API שמבוססים על Kubernetes

ממשק שורת הפקודה (CLI) של kubectl Kubernetes הוא הדרך העיקרית לעבוד ישירות עם ממשק ה-API של Kubernetes ועם כל ממשקי ה-API שמבוססים על Kubernetes.

גישה באמצעות kubectl

כשניגשים ל-Kubernetes API בפעם הראשונה, משתמשים בכלי שורת הפקודה של Kubernetes,‏ kubectl.

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

בודקים את ההגדרות הנוכחיות של kubectl ורואים לאילו אשכולות יש לכם גישה:

kubectl config view

יצירת תיאורים של נקודות קצה ל-API

כדי לראות רשימה של נקודות קצה ל-API שזמינות לכל ממשקי ה-API של השירות ב-GDC עם air gap, אתם יכולים ליצור תיאורי API לפי מפרט OpenAPI בפורמט JSON. אפשר לראות את קובץ ה-JSON שנוצר לנקודות הקצה ל-API בכלים כמו Swagger.

כדי ליצור את התיאורים של נקודות הקצה ל-API של מישור הניהול ומישור הנתונים בפורמט JSON:

1. יוצרים שרת proxy בין הסביבה שלכם לבין שרת ה-API לניהול:

   kubectl proxy --kubeconfig MANAGEMENT_API_SERVER
   

   מחליפים את MANAGEMENT_API_SERVER בנתיב לקובץ kubeconfig של שרת ה-API לניהול. מידע נוסף מופיע במאמר משאבי שרת של Management API ברמת האזור.

2. מורידים את רשימת התיאורים של נקודות הקצה ל-API בפורמט JSON:

   curl -s http://127.0.0.1:8001/openapi/v2 | jq 'if .paths then .paths = (.paths
       | with_entries(select(.key | contains(".private") | not))) else . end' > k8s_swagger.json
   

3. פותחים את קובץ ה-k8s_swagger.json שנוצר בכלי כמו Swagger כדי לראות את התיאורים של נקודות הקצה ל-API.

גישה ישירה ל-API באמצעות צד הלקוח ב-HTTP

אפשר לגשת ישירות ל-API בארכיטקטורת REST באמצעות צד הלקוח ב-HTTP, כמו curl,‏ wget או דפדפן:

• להסתמך על kubectl כדי לטפל באימות באמצעות שימוש בו במצב שרת proxy.
• לטפל באימות בעצמכם.

מריצים את kubectl proxy

הפקודה kubectl proxy מריצה את kubectl במצב שבו הוא פועל כשרת proxy הפוך. הפקודה הזו מתחברת אל apiserver ומנהלת את האימות.

כשמריצים את kubectl במצב שרת proxy, נעשה שימוש במיקום של שרת ה-API ששמור, והזהות של שרת ה-API מאומתת באמצעות אישור. השיטה הזו מגינה מפני התקפות אדם בתווך (MITM).

בדוגמה הבאה אפשר לראות איך משתמשים בפקודה kubectl proxy:

kubectl proxy --port=8080 &

אחרי שה-proxy של kubectl פועל, אפשר לבדוק את ה-API באמצעות curl,‏ wget או דפדפן, כמו שמוצג בדוגמאות הבאות:

$ curl http://localhost:8080/api/
{
  "versions": [
    "v1"
  ],
  "serverAddressByClientCIDRs": [
    {
      "clientCIDR": "0.0.0.0/0",
      "serverAddress": "10.0.1.149:443"
    }
  ]
}

הפעלה בלי שרת proxy של kubectl

אם אתם לא רוצים להריץ את kubectl במצב שרת proxy, אתם יכולים להעביר אסימון אימות ישירות לשרת ה-API.

1. מציגים את כל אשכולות Kubernetes שיש לכם גישה אליהם, כי יכול להיות שלקובץ kubeconfig יש כמה הקשרים:

   kubectl config view \
       -o jsonpath='{"Cluster name\tServer\n"}{range.clusters[*]}{.name}{"\t"}{.cluster.server}{"\n"}{end}'
   

2. מייצאים את השם של אשכול Kubernetes שרוצים להשתמש בו מהפלט הקודם:

   export CLUSTER_NAME="CLUSTER_NAME"
   

3. מגדירים את שרת ה-API שמפנה לשם של אשכול Kubernetes:

   APISERVER=$(kubectl config view -o jsonpath="{.clusters[?(@.name==\"$CLUSTER_NAME\")].cluster.server}")
   

4. יוצרים סוד שיכיל אסימון לחשבון השירות שמוגדר כברירת מחדל:

   kubectl apply -n NAMESPACE -f - <<EOF
   apiVersion: v1
   kind: Secret
   metadata:
     name: default-token
     annotations:
       kubernetes.io/service-account.name: default
   type: kubernetes.io/service-account-token
   EOF
   

5. מחכים שבקר הטוקנים יאכלס את הסוד בטוקן:

   while ! kubectl describe secret default-token -n NAMESPACE | grep -E '^token' >/dev/null; do
     echo "waiting for token..." >&2
     sleep 1
   done
   

6. מגדירים את ערך הטוקן:

   TOKEN=$(kubectl get secret default-token -n NAMESPACE \
       -o jsonpath='{.data.token}' | base64 --decode)
   

7. כדי לגשת ל-API, משתמשים באסימון עם כלי כמו curl על ידי הוספת כותרת ה-HTTP‏ Authorization: Bearer $TOKEN, כמו בדוגמה הבאה:

   curl -k $APISERVER/api --header "Authorization: Bearer $TOKEN"
   

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

   {
     "kind": "APIVersions",
     "versions": [
       "v1"
     ],
     "serverAddressByClientCIDRs": [
       {
         "clientCIDR": "0.0.0.0/0",
         "serverAddress": "10.0.1.149:443"
       }
     ]
   }