במדריך הזה נסביר איך לפרוס דוגמה פשוטה של שירות gRPC באמצעות Extensible Service Proxy (ESP) לאשכול Kubernetes שלא פועל ב-Google Cloud. במדריך הזה משתמשים בגרסת Python של הדוגמה bookstore-grpc. דוגמאות ל-gRPC בשפות אחרות מפורטות בקטע מה השלב הבא.
במדריך הזה נעשה שימוש בקובצי אימג' של קונטיינרים שנבנו מראש של קוד לדוגמה ושל ESP, שמאוחסנים ב-Artifact Registry. אם אתם לא מכירים את המושג 'מאגרי תגים', תוכלו לקרוא מידע נוסף במאמרים הבאים:
סקירה כללית של Cloud Endpoints זמינה במאמרים מידע על Endpoints וארכיטקטורת Endpoints.
מטרות
במהלך העבודה עם המדריך, תוכלו להשתמש ברשימת המשימות הכללית הבאה. כדי לשלוח בקשות ל-API, צריך לבצע את כל המשימות.
- מגדירים Google Cloud פרויקט ומורידים את התוכנה הנדרשת. לפני שמתחילים
- העתקה והגדרה של קבצים מהדוגמה
bookstore-grpc. איך מגדירים את Cloud Endpoints - פורסים את ההגדרה של Endpoints כדי ליצור שירות Endpoints. איך פורסים את ההגדרה של נקודות הקצה
- יוצרים פרטי כניסה לשירות Endpoints. מידע נוסף זמין במאמר יצירת פרטי כניסה לשירות.
- יוצרים קצה עורפי להצגת ה-API ופורסים את ה-API. מידע נוסף זמין במאמר בנושא פריסת קצה העורפי של ה-API.
- קבלת כתובת ה-IP החיצונית של השירות. איך מקבלים את כתובת ה-IP החיצונית של השירות
- שליחת בקשה ל-API. שליחת בקשה ל-API
- כדי להימנע מחיובים בחשבון Google Cloud , מידע נוסף זמין בקטע הסרת המשאבים.
עלויות
במסמך הזה משתמשים ברכיבים הבאים של Google Cloud, והשימוש בהם כרוך בתשלום:
כדי להעריך את ההוצאות בהתאם לתחזית השימוש שלכם, אתם יכולים להיעזר במחשבון העלויות.
כשמסיימים את המשימות שמתוארות במסמך הזה אפשר למחוק את המשאבים שיצרתם כדי להימנע מחיובים נוספים. מידע נוסף זמין בקטע הסרת המשאבים.
לפני שמתחילים
במדריך הזה אנחנו יוצאים מנקודת הנחה שכבר הגדרתם את Minikube או אשכול Kubernetes. מידע נוסף מופיע במאמרי העזרה בנושא Kubernetes.
- נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
- חשוב לרשום את Google Cloud מזהה הפרויקט כי תצטרכו אותו בהמשך.
- מתקינים ומפעילים את ה-CLI של gcloud.
- מעדכנים את ה-CLI של gcloud ומתקינים את רכיבי Endpoints.
gcloud components update
- מוודאים ש-Google Cloud CLI (
gcloud) מורשה לגשת לנתונים ולשירותים שלכם ב- Google Cloud: בכרטיסייה החדשה שנפתחת, בוחרים חשבון.gcloud auth login
- מגדירים את פרויקט ברירת המחדל למזהה הפרויקט:
gcloud config set project YOUR_PROJECT_IDמחליפים את
YOUR_PROJECT_IDבמזהה הפרויקט ב- Google Cloud .אם יש לכם פרויקטים אחרים ב- Google Cloud ואתם רוצים להשתמש ב-
gcloudכדי לנהל אותם, תוכלו לקרוא את המאמר בנושא ניהול ההגדרות האישיות של ה-CLI של gcloud. - התקנה של
kubectl:gcloud components install kubectl
- קבלת פרטי כניסה חדשים של משתמשים לשימוש ב-Application Default Credentials.
צריך את פרטי הכניסה של המשתמש כדי לתת הרשאה ל-
kubectl.gcloud auth application-default login
- בכרטיסייה החדשה בדפדפן שנפתחת, בוחרים חשבון.
- פועלים לפי השלבים שמפורטים ב מדריך למתחילים של gRPC Python כדי להתקין את gRPC ואת כלי gRPC.
הגדרת נקודות קצה
הדוגמה bookstore-grpc מכילה את הקבצים שצריך להעתיק באופן מקומי ולהגדיר.
- יוצרים קובץ תיאור protobuf עצמאי מקובץ השירות
.proto:- שמירת עותק של
bookstore.protoממאגר הדוגמאות. הקובץ הזה מגדיר את ה-API של שירות חנות הספרים. - יוצרים את הספרייה הבאה:
mkdir generated_pb2 - יוצרים את קובץ התיאור,
api_descriptor.pb, באמצעות קומפיילר מאגרי אחסון לפרוטוקוליםprotoc. מריצים את הפקודה הבאה בספרייה שבה שמרתם אתbookstore.proto:python -m grpc_tools.protoc \ --include_imports \ --include_source_info \ --proto_path=. \ --descriptor_set_out=api_descriptor.pb \ --python_out=generated_pb2 \ --grpc_python_out=generated_pb2 \ bookstore.proto
בפקודה הקודמת,
--proto_pathמוגדר כספריית העבודה הנוכחית. בסביבת ה-build של gRPC, אם אתם משתמשים בספרייה אחרת לקובצי הקלט.proto, אתם צריכים לשנות את--proto_pathכדי שהקומפיילר יחפש בספרייה שבה שמרתם אתbookstore.proto.
- שמירת עותק של
- יוצרים קובץ YAML של הגדרות gRPC API:
- שומרים עותק של
קובץ
api_config.yaml. בקובץ הזה מוגדר ההגדרה של gRPC API לשירות Bookstore. - מחליפים את MY_PROJECT_ID בקובץ
api_config.yamlבמזהה הפרויקט ב- Google Cloud . לדוגמה:# # Name of the service configuration. # name: bookstore.endpoints.example-project-12345.cloud.goog
שימו לב שהערך בשדה
apis.nameבקובץ הזה זהה בדיוק לשם ה-API המלא מקובץ.proto. אחרת, הפריסה לא תפעל. שירות חנות הספרים מוגדר ב-bookstore.protoבחבילהendpoints.examples.bookstore. שם ה-API המלא שלה הואendpoints.examples.bookstore.Bookstore, בדיוק כמו שהוא מופיע בקובץapi_config.yaml.apis: - name: endpoints.examples.bookstore.Bookstore
- שומרים עותק של
קובץ
מידע נוסף מופיע במאמר הגדרת נקודות קצה.
פריסת ההגדרה של נקודות הקצה
כדי לפרוס את ההגדרה של Endpoints, משתמשים בפקודה gcloud endpoints services deploy. הפקודה הזו משתמשת ב-Service Infrastructure, פלטפורמת השירותים הבסיסית של Google, שמשמשת את Endpoints ושירותים אחרים ליצירה ולניהול של ממשקי API ושירותים.
- חשוב לוודא שאתם נמצאים בספרייה שבה נמצאים הקבצים
api_descriptor.pbו-api_config.yaml. - מוודאים שפרויקט ברירת המחדל שבו כלי שורת הפקודה
gcloudמשתמש כרגע הוא הפרויקט Google Cloud שבו רוצים לפרוס את ההגדרה של Endpoints. כדי לוודא שהשירות לא נוצר בפרויקט הלא נכון, מאמתים את מזהה הפרויקט שמוחזר מהפקודה הבאה:gcloud config list project
אם צריך לשנות את פרויקט ברירת המחדל, מריצים את הפקודה הבאה:
gcloud config set project YOUR_PROJECT_ID
- פורסים את הקובץ
proto descriptorואת קובץ ההגדרות באמצעות Google Cloud CLI:gcloud endpoints services deploy api_descriptor.pb api_config.yaml
במהלך היצירה וההגדרה של השירות, Service Management מציג מידע במסוף. בסיום הפריסה, תוצג הודעה שדומה לזו:
Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
CONFIG_ID הוא המזהה הייחודי של הגדרת שירות Endpoints שנוצר על ידי הפריסה. לדוגמה:
Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
בדוגמה הקודמת,
2017-02-13r0הוא מזהה הגדרות השירות ו-bookstore.endpoints.example-project.cloud.googהוא שם השירות. מזהה הגדרות השירות מורכב מחותמת זמן ואחריה מספר הגרסה. אם תפרסו את ההגדרה של Endpoints שוב באותו יום, מספר הגרסה יוגדל במזהה הגדרת השירות.
בדיקת השירותים הנדרשים
לפחות, צריך להפעיל את שירותי Google הבאים כדי להשתמש ב-Endpoints וב-ESP:| שם | כותרת |
|---|---|
servicemanagement.googleapis.com |
Service Management API |
servicecontrol.googleapis.com |
Service Control API |
ברוב המקרים, הפקודה gcloud endpoints services deploy מפעילה את השירותים הנדרשים האלה. עם זאת, הפקודה gcloud מסתיימת בהצלחה אבל לא מפעילה את השירותים הנדרשים בנסיבות הבאות:
אם השתמשתם באפליקציה של צד שלישי כמו Terraform ולא כללתם את השירותים האלה.
הפריסה של הגדרת ה-Endpoints בוצעה בפרויקטGoogle Cloud קיים שבו השירותים האלה הושבתו באופן מפורש.
כדי לוודא שהשירותים הנדרשים מופעלים, משתמשים בפקודה הבאה:
gcloud services list
אם השירותים הנדרשים לא מופיעים ברשימה, צריך להפעיל אותם:
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.comצריך גם להפעיל את שירות Endpoints:
gcloud services enable ENDPOINTS_SERVICE_NAME
כדי לדעת מהו ENDPOINTS_SERVICE_NAME, אפשר:
אחרי פריסת ההגדרה של Endpoints, נכנסים לדף Endpoints במסוף Cloud. רשימת האפשרויות האפשריות של ENDPOINTS_SERVICE_NAME מוצגת בעמודה שם השירות.
ב-OpenAPI, ENDPOINTS_SERVICE_NAME הוא הערך שציינתם בשדה
hostבמפרט OpenAPI. ב-gRPC, ENDPOINTS_SERVICE_NAME הוא הערך שציינתם בשדהnameבהגדרות של נקודות הקצה של gRPC.
מידע נוסף על פקודות gcloud זמין במאמר שירותי gcloud.
אם מופיעה הודעת שגיאה, אפשר להיעזר במאמר בנושא פתרון בעיות בהטמעה של הגדרות Endpoints.
מידע נוסף זמין במאמר פריסת ההגדרה של Endpoints.
יצירת פרטי כניסה לשירות
כדי לספק ניהול של ה-API, גם ESP וגם ESPv2 דורשים את השירותים ב-Service Infrastructure. כדי לקרוא לשירותים האלה, ESP ו-ESPv2 צריכים להשתמש באסימוני גישה. כשפורסים את ESP או ESPv2 בסביבות כמו GKE או Compute Engine, ESP ו-ESPv2 מקבלים בשבילכם טוקנים לגישה דרך שירות המטא-נתונים. Google Cloud Google Cloud
כשפורסים את ESP או ESPv2 בסביבה שאינהGoogle Cloud , כמו שולחן העבודה המקומי, אשכול Kubernetes מקומי או ספק אחר של שירותי ענן, צריך לספק קובץ JSON של חשבון שירות שמכיל מפתח פרטי. ESP ו-ESPv2 משתמשים בחשבון שירות כדי ליצור אסימוני גישה לקריאה לשירותים שהם צריכים כדי לנהל את ה-API שלכם.
אפשר להשתמש במסוף Google Cloud או ב-Google Cloud CLI כדי ליצור את חשבון השירות ואת קובץ המפתח הפרטי:
המסוף
- במסוף Google Cloud , פותחים את הדף Service Accounts .
- לוחצים על Select a project (בחירת פרויקט).
- בוחרים את הפרויקט שבו נוצר ה-API ולוחצים על Open.
- לוחצים על + יצירת חשבון שירות.
- בשדה Service account name, מזינים את השם של חשבון השירות.
- לוחצים על יצירה.
- לוחצים על Continue.
- לוחצים על סיום.
- לוחצים על כתובת האימייל של חשבון השירות החדש שנוצר.
- לוחצים על Keys.
- לוחצים על Add key ואז על Create new key.
לוחצים על יצירה. למחשב שלכם תתבצע הורדה של קובץ JSON עם המפתח.
חשוב לאחסן את קובץ המפתח באופן מאובטח כי הוא יכול לשמש לצורך אימות כחשבון השירות שלכם. אפשר להעביר את הקובץ לאן שרוצים ולשנות את השם שלו למה שרוצים.
לוחצים על Close.
gcloud
מזינים את הפקודה הבאה כדי להציג את מזהי הפרויקטים שלGoogle Cloud הפרויקטים:
gcloud projects list
מחליפים את PROJECT_ID בפקודה הבאה כדי להגדיר את פרויקט ברירת המחדל לפרויקט שבו נמצא ה-API:
gcloud config set project PROJECT_ID
מוודאים ש-Google Cloud CLI (
gcloud) מורשה לגשת לנתונים ולשירותים שלכם ב- Google Cloud:gcloud auth login
אם יש לכם יותר מחשבון אחד, הקפידו לבחור את החשבון שמשויך ל Google Cloud פרויקט שבו ה-API נמצא. אם מריצים את הפקודה
gcloud auth list, החשבון שבחרתם מוצג כחשבון הפעיל של הפרויקט.כדי ליצור חשבון שירות, מריצים את הפקודה הבאה ומחליפים את SERVICE_ACCOUNT_NAME ואת
My Service Accountבשם ובשם התצוגה שרוצים להשתמש בהם:gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \ --display-name "My Service Account"
הפקודה מקצה כתובת אימייל לחשבון השירות בפורמט הבא:
SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.comכתובת האימייל הזו נדרשת בפקודות הבאות.
יוצרים קובץ מפתח של חשבון שירות:
gcloud iam service-accounts keys create ~/service-account-creds.json \ --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
מוסיפים את התפקידים הנדרשים ב-IAM:
בקטע הזה מתוארים משאבי ה-IAM שמשמשים את ESP ו-ESPv2, ותפקידי ה-IAM שנדרשים לחשבון השירות המצורף כדי לגשת למשאבים האלה.
הגדרת שירות נקודות קצה
ESP ו-ESPv2 קוראים ל-Service Control API, שמשתמש בהגדרות השירות של נקודת הקצה. הגדרת שירות נקודת הקצה היא משאב IAM, ו-ESP ו-ESPv2 צריכים את התפקיד Service Controller כדי לגשת אליו.
תפקיד ה-IAM מוגדר בהגדרות של שירות נקודת הקצה, ולא בפרויקט. יכול להיות שלפרויקט יש כמה הגדרות של שירות נקודות קצה.
משתמשים בפקודה הבאה ב-gcloud כדי להוסיף את התפקיד לחשבון השירות המצורף להגדרת שירות נקודת הקצה.
gcloud endpoints services add-iam-policy-binding SERVICE_NAME \ --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \ --role roles/servicemanagement.serviceController
כאשר
* SERVICE_NAME הוא שם שירות נקודת הקצה
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com
הוא חשבון השירות המצורף.
Cloud Trace
ESP ו-ESPv2 קוראים לשירות
Cloud Trace כדי לייצא את הנתונים של Trace לפרויקט. הפרויקט הזה נקרא פרויקט המעקב. ב-ESP, פרויקט המעקב והפרויקט שבבעלותו הגדרות השירות של נקודת הקצה הם אותו פרויקט. ב-ESPv2, אפשר לציין את פרויקט המעקב באמצעות הדגל --tracing_project_id, ופרויקט הפריסה מוגדר כברירת מחדל.
כדי להפעיל את Cloud Trace, צריך להקצות ל-ESP ול-ESPv2 את התפקיד Cloud Trace Agent.
משתמשים בפקודה הבאה ב-gcloud כדי להוסיף את התפקיד לחשבון השירות המצורף:
gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \ --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \ --role roles/cloudtrace.agent
כאשר
* TRACING_PROJECT_ID הוא מזהה פרויקט המעקב
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com
הוא חשבון השירות המצורף.
מידע נוסף זמין במאמר
מהם תפקידים והרשאות?
מידע נוסף על הפקודות זמין במאמר gcloud iam service-accounts.
פריסת ה-API backend
עד עכשיו פרסתם את הגדרת השירות ב-Service Management, אבל עדיין לא פרסתם את הקוד שמשרת את העורף של ה-API. בקטע הזה נסביר איך לפרוס קונטיינרים מוכנים מראש עבור ה-API לדוגמה ו-ESP ל-Kubernetes.
העברת פרטי הכניסה לשירות אל ספק ה-ESP
ל-ESP, שפועל בתוך קונטיינר, נדרשת גישה לפרטי הכניסה שמאוחסנים באופן מקומי בקובץ service-account-creds.json. כדי לתת ל-ESP גישה לפרטי הכניסה, יוצרים סוד של Kubernetes ומטמיעים אותו כנפח של Kubernetes.
כדי ליצור את הסוד של Kubernetes ולצרף את אמצעי האחסון:
אם השתמשתם במסוף Google Cloud כדי ליצור את חשבון השירות, משנים את השם של קובץ ה-JSON ל-
service-account-creds.json. מעבירים אותו לאותה ספרייה שבה נמצאים הקבציםapi_descriptor.pbו-api_config.yaml.יוצרים סוד של Kubernetes עם פרטי הכניסה של חשבון השירות:
kubectl create secret generic service-account-creds --from-file=service-account-creds.jsonאם הפעולה תצליח, תוצג ההודעה
secret "service-account-creds" created.
קובץ המניפסט של הפריסה שבו אתם משתמשים כדי לפרוס את ה-API ואת ה-ESP ב-Kubernetes כבר מכיל את הנפח הסודי, כמו שמוצג בשני הקטעים הבאים של הקובץ:
הגדרת שם השירות והפעלת השירות
ל-ESP צריך להיות ידוע שם השירות כדי למצוא את ההגדרה שפרסתם קודם באמצעות הפקודה gcloud endpoints services deploy.
כדי להגדיר את שם השירות ולהפעיל את השירות:
שומרים עותק של קובץ המניפסט של הפריסה,
k8s-grpc-bookstore.yaml, באותה ספרייה שבה נמצאservice-account-creds.json.פותחים את
k8s-grpc-bookstore.yamlומחליפים את SERVICE_NAME בשם של שירות Endpoints. זהו אותו שם שהגדרתם בשדהnameבקובץapi_config.yaml.האפשרות
--rollout_strategy=managedמגדירה את ESP כך שישתמש בהגדרת השירות העדכנית ביותר שנפרסה. אם תבחרו באפשרות הזו, עד 5 דקות אחרי שתפרסו הגדרת שירות חדשה, ESP יזהה את השינוי ויתחיל להשתמש בה באופן אוטומטי. אנחנו ממליצים לציין את האפשרות הזו במקום מזהה תצורה ספציפי לשימוש ב-ESP. פרטים נוספים על הארגומנטים של ESP זמינים במאמר בנושא אפשרויות הפעלה של ESP.מפעילים את השירות כדי לפרוס אותו ב-Kubernetes:
kubectl create -f k8s-grpc-bookstore.yaml
אם מופיעה הודעת שגיאה דומה להודעה הבאה:
The connection to the server localhost:8080 was refused - did you specify the right host or port?
המשמעות היא ש-
kubectlלא מוגדר בצורה נכונה. מידע נוסף מופיע במאמר הגדרה שלkubectl.
קבלת כתובת ה-IP החיצונית של השירות
כדי לשלוח בקשות ל-API לדוגמה, צריך את כתובת ה-IP החיצונית של השירות. יכול להיות שיעברו כמה דקות אחרי שתפעילו את השירות במאגר עד שכתובת ה-IP החיצונית תהיה מוכנה.
צפייה בכתובת ה-IP החיצונית:
kubectl get service
רושמים את הערך של
EXTERNAL-IPושומרים אותו במשתנה סביבה SERVER_IP, כי משתמשים בו כששולחים בקשות ל-API לדוגמה.export SERVER_IP=YOUR_EXTERNAL_IP
שליחת בקשה ל-API
כדי לשלוח בקשות ל-API לדוגמה, אפשר להשתמש בלקוח gRPC לדוגמה שנכתב ב-Python.
משכפלים את מאגר ה-Git שבו מתארח קוד הלקוח של gRPC:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
כדי לשנות את ספריית העבודה:
cd python-docs-samples/endpoints/bookstore-grpc/
יחסי תלות של התקנות:
pip install virtualenvvirtualenv envsource env/bin/activatepython -m pip install -r requirements.txtשליחת בקשה ל-API לדוגמה:
python bookstore_client.py --host SERVER_IP --port 80
מעיינים בתרשימי הפעילות של ה-API בדף Endpoints > Services.
יכול להיות שיעברו כמה רגעים עד שהבקשה תשתקף בתרשימים.
מעיינים ביומני הבקשות של ה-API בדף Logs Explorer.
אם לא מקבלים תגובה, אפשר להיעזר במאמר בנושא פתרון בעיות שקשורות לתגובות.
הרגע פרסתם ובדקתם API ב-Endpoints!
הסרת המשאבים
כדי להימנע מחיובים בחשבון Google Cloud בגלל השימוש במשאבים שנעשה במסגרת המדריך הזה, אפשר למחוק את הפרויקט שמכיל את המשאבים, או להשאיר את הפרויקט ולמחוק את המשאבים בנפרד.
מחיקת ה-API:
gcloud endpoints services delete SERVICE_NAME
מחליפים את SERVICE_NAME בשם ה-API.
מחיקת אשכול GKE:
gcloud container clusters delete NAME --zone ZONE
המאמרים הבאים
- כאן מוסבר איך מגדירים gRPC API משלכם ל-Endpoints.
- הגדרת DNS:
- כדאי לעיין באפליקציה לדוגמה של חנות הספרים ב-GitHub. הלקוח והשרת זמינים ב-Python וב-Java.
- הדוגמה
getting-started-grpcזמינה ב-GitHub בשפות הבאות: