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

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

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

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

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

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

כדי לגשת לממשקי GDC API, משתמשים בכלי gdcloud CLI או במסוף GDC.

מידע על Kubernetes API ועל KRM

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

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

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

מידע נוסף על 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 ‏ (KRM), בכתובת https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md

ממשקי API גלובליים ואזוריים

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

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

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

גישה לממשקי GDC APIs

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

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

רוב ממשקי ה-API של GDC מספקים ממשק HTTP בפורמט JSON שאפשר לקרוא לו ישירות. ממשקי ה-API שמבוססים על Kubernetes משתמשים בספריות הלקוח של Kubernetes. חלק מהממשקי GDC API שאינם מבוססים על Kubernetes כוללים ממשק gRPC, שמספק ביצועים ושימושיות משופרים. Google מספקת גם ספריות לקוח לממשקי GDC API שלא מבוססים על 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/.

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

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

kubectl Kubernetes CLI היא הדרך העיקרית לעבוד ישירות עם Kubernetes API ועם כל ממשקי 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 לניהול. מידע נוסף מופיע במאמר משאבי שרת של Zonal 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 במצב שבו היא פועלת כפרוקסי הפוך. הפקודה הזו מתחברת ל-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"
    }
  ]
}

הרצה בלי kubectl proxy

אם אתם לא רוצים להריץ את 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 | grep -E '^token' >/dev/null; do
     echo "waiting for token..." >&2
     sleep 1
   done
   

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

   TOKEN=$(kubectl get secret $(kubectl get secrets | grep default | cut -f1 -d ' ')  \
       -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"
       }
     ]
   }