תחילת העבודה עם Cloud Endpoints gRPC עבור קבוצת מופעי מכונה מנוהלים עם ESPv2

במדריך הזה נסביר איך לפרוס דוגמה פשוטה של שירות gRPC באמצעות Extensible Service Proxy V2 ‏(ESPv2) בקבוצת מופעי מכונה מנוהלים.

במדריך הזה נעשה שימוש בגרסת Python של הדוגמה bookstore-grpc. דוגמאות ל-gRPC בשפות אחרות מפורטות בקטע מה השלב הבא.

סקירה כללית של Cloud Endpoints זמינה במאמרים מידע על Endpoints וארכיטקטורת Endpoints.

מטרות

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

  1. מגדירים Google Cloud פרויקט ומורידים את התוכנה הנדרשת. לפני שמתחילים
  2. העתקה והגדרה של קבצים מהדוגמה של bookstore-grpc. איך מגדירים נקודות קצה
  3. פורסים את ההגדרה של Endpoints כדי ליצור שירות Endpoints. איך פורסים את ההגדרה של נקודות הקצה
  4. פורסים את ה-API ואת ESPv2 בחלק האחורי של קבוצת מופעי מכונה מנוהלים. מידע נוסף זמין במאמר בנושא פריסת קצה העורפי של ה-API.
  5. שליחת בקשה ל-API. שליחת בקשה ל-API
  6. כדי להימנע מחיובים בחשבון Google Cloud , מידע נוסף זמין בקטע הסרת המשאבים.

עלויות

במסמך הזה משתמשים ברכיבים הבאים של Google Cloud, והשימוש בהם כרוך בתשלום:

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

משתמשים חדשים של Google Cloud ? יכול להיות שאתם זכאים לתקופת ניסיון בחינם.

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

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

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

  2. 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 the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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 the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. חשוב לרשום את מזהה הפרויקט כי תצטרכו אותו בהמשך.
  7. מתקינים ומפעילים את Google Cloud CLI.
  8. מעדכנים את ה-CLI של gcloud ומתקינים את רכיבי Endpoints: 
    gcloud components update
  9. מוודאים ש-Google Cloud CLI ‏ (gcloud) מורשה לגשת לנתונים ולשירותים שלכם ב- Google Cloud: 
    gcloud auth login
     בכרטיסייה החדשה בדפדפן שנפתחת, בוחרים חשבון.
  10. מגדירים את פרויקט ברירת המחדל למזהה הפרויקט. 
    gcloud config set project YOUR_PROJECT_ID

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

  11. כדי להתקין את gRPC ואת כלי gRPC, פועלים לפי השלבים שמפורטים ב מדריך למתחילים של gRPC Python.

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

הגדרת נקודות קצה

משכפלים את מאגר הדוגמאות bookstore-grpc מ-GitHub.

כדי להגדיר נקודות קצה:

  1. יוצרים קובץ תיאור protobuf עצמאי מקובץ השירות .proto:
    1. שמירת עותק של bookstore.proto ממאגר הדוגמאות. הקובץ הזה מגדיר את ה-API של שירות חנות הספרים.
    2. יוצרים את הספרייה הבאה: mkdir generated_pb2
    3. יוצרים את קובץ התיאור, 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.

  2. יוצרים קובץ YAML של הגדרות gRPC API:
    1. שומרים עותק של קובץ api_config.yaml. בקובץ הזה מוגדר ההגדרה של gRPC API לשירות Bookstore.
    2. מחליפים את 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 Management כדי ליצור שירות מנוהל.

  1. חשוב לוודא שאתם נמצאים בספרייה שבה נמצאים הקבצים api_descriptor.pb ו-api_config.yaml.
  2. מוודאים שפרויקט ברירת המחדל שבו כלי שורת הפקודה gcloud משתמש כרגע הוא הפרויקט Google Cloud שבו רוצים לפרוס את ההגדרה של Endpoints. כדי לוודא שהשירות לא נוצר בפרויקט הלא נכון, מאמתים את מזהה הפרויקט שמוחזר מהפקודה הבאה: 
    gcloud config list project

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

    gcloud config set project YOUR_PROJECT_ID
  3. פורסים את הקובץ 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 backend

עד עכשיו פרסתם את הגדרת ה-API ב-Service Management, אבל עדיין לא פרסתם את הקוד שמשרת את העורף של ה-API. בקטע הזה מוסבר איך להגדיר את Docker בקבוצת מופעי מכונה מנוהלים, ולהריץ את קוד ה-backend של ה-API ואת ESPv2 בקונטיינר Docker.

יצירת תבנית של הגדרות מכונה

יוצרים תבנית שתשמש ליצירת קבוצה של מכונות וירטואליות. כל מופע שנוצר מהתבנית מפעיל ESPv2 ושרת אפליקציות של קצה עורפי.

  1. נכנסים לדף Instance templates במסוף Google Cloud .

    כניסה לדף Instance templates

  2. לוחצים על Create instance template.

  3. בשדה Name (שם), מזינים load-balancing-espv2-template.

  4. בקטע Machine configuration, מגדירים את סוג המכונה לערך e2-micro.

  5. בקטע Boot disk, מגדירים את Image ל-Container Optimized OS stable version.

  6. בקטע Firewall, בוחרים באפשרות Allow HTTP traffic.

  7. לוחצים על Management, security, disks, networking, sole tenancy כדי להציג את ההגדרות המתקדמות.

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

    sudo docker network create --driver bridge esp_net
sudo docker run \
  --detach \
  --name=bookstore \
  --net=esp_net \
  gcr.io/endpointsv2/python-grpc-bookstore-server:1
sudo docker run \
  --detach \
  --name=esp \
  --publish=80:9000 \
  --net=esp_net \
  gcr.io/endpoints-release/endpoints-runtime:2 \
  --service=ENDPOINTS_SERVICE_NAME \
  --rollout_strategy=managed \
  --listener_port=9000 \
  --healthz=/healthz \
  --backend=grpc://bookstore:8000

    הסקריפט מקבל, מתקין ומפעיל את שרת האפליקציה echo ואת שרת ה-proxy של ESPv2 בזמן הפעלת המופע.

  9. לוחצים על יצירה.

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

יצירת קבוצה אזורית של מופעי מכונה מנוהלים

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

  1. נכנסים לדף Instance groups במסוף Google Cloud .

    כניסה לדף Instance groups

  2. לוחצים על יצירת קבוצת מופעים.

  3. בשדה Name (שם), מזינים load-balancing-espv2-group.

  4. בקטע מיקום, בוחרים באפשרות מספר אזורים.

  5. בקטע Region, בוחרים באפשרות us-central1.

  6. לוחצים על התפריט הנפתח Configure zones (הגדרת אזורים) כדי להציג את האפשרות Zones (אזורים). בוחרים את האזורים הבאים:

    • us-central1-b
    • us-central1-c
    • us-central1-f

  7. בקטע Instance template (תבנית של הגדרות מכונה), בוחרים באפשרות load-balancing-espv2-template.

  8. בקטע שינוי גודל אוטומטי, בוחרים באפשרות ללא שינוי גודל אוטומטי.

  9. מגדירים את מספר המופעים ל-3.

  10. בקטע Instance redistribution, בוחרים באפשרות On.

  11. בקטעים תיקון אוטומטי ובדיקת תקינות, בוחרים באפשרות ללא בדיקת תקינות.

  12. לוחצים על יצירה. תועברו בחזרה לדף קבוצות מופעים.

יצירת מאזן עומסים

בקטע הזה מוסבר איך ליצור מאזן עומסים אזורי שמפנה תנועת TCP לקבוצת המכונות שלכם.

  1. נכנסים לדף Create a load balancer במסוף Google Cloud .

    מעבר אל יצירת מאזן עומסים

  2. בקטע TCP Load Balancing (איזון עומסים ב-TCP), לוחצים על Start configuration (תחילת ההגדרה).

  3. בקטע Internet facing or internal only, בוחרים באפשרות From Internet to my VMs.

  4. בקטע אזורים מרובים או אזור יחיד, בוחרים באפשרות אזור יחיד בלבד.

  5. בקטע Backend type (סוג ה-Backend), בוחרים באפשרות Backend Service (שירות Backend).

  6. לוחצים על Continue.

  7. בשדה Name (שם), מזינים espv2-load-balancer.

  8. בקטע Backend configuration, בוחרים באזור us-central1.

  9. בוחרים קבוצת מכונות load-balancing-espv2-group.

  10. בקטע Health check, יוצרים בדיקת תקינות חדשה.

    • בקטע 'שם', מזינים espv2-load-balancer-check.
    • מוודאים שProtocol הוא TCP ו-Port הוא 80.

  11. בקטע Frontend configuration, מזינים את מספר היציאה 80.

  12. בקטע Review and finalize, מוודאים

    • קבוצת המופעים היא load-balancing-espv2-group.
    • הערך בעמודה אזור הוא us-central1.
    • הפרוטוקול הוא TCP.
    • הערך של IP:Port הוא EPHEMERAL:80.

  13. אחרי שיוצרים את מאזן העומסים, מאתרים את כתובת ה-IP בדף Load Balancer.

    כניסה לדף Load Balancer

שליחת בקשה ל-API

אם אתם שולחים את הבקשה מאותו מופע שבו פועלים קונטיינרים של Docker, אתם יכולים להחליף את SERVER_IP ב-localhost. אחרת, מחליפים את SERVER_IP בכתובת ה-IP החיצונית של המכונה.

כדי למצוא את כתובת ה-IP החיצונית, מריצים את הפקודה:

gcloud compute instances list

כדי לשלוח בקשות ל-API לדוגמה, אפשר להשתמש בלקוח gRPC לדוגמה שנכתב ב-Python.

  1. משכפלים את מאגר ה-Git שבו מתארח קוד הלקוח של gRPC:

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

  2. כדי לשנות את ספריית העבודה:

    cd python-docs-samples/endpoints/bookstore-grpc/

  3. יחסי תלות של התקנות: 

    pip install virtualenv
virtualenv env
source env/bin/activate
python -m pip install -r requirements.txt

  4. שליחת בקשה ל-API לדוגמה:

    python bookstore_client.py --host SERVER_IP --port 80

    • מעיינים בתרשימי הפעילות של ה-API בדף Endpoints > Services.

      לדף Endpoints Services

      יכול להיות שיעברו כמה רגעים עד שהבקשה תשתקף בתרשימים.

    • מעיינים ביומני הבקשות של ה-API בדף Logs Explorer.

      כניסה לדף Logs Explorer

אם לא מקבלים תגובה, אפשר להיעזר במאמר בנושא פתרון בעיות שקשורות לתגובות.

הרגע פרסתם ובדקתם API ב-Endpoints!

הסרת המשאבים

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

  1. מוודאים של-CLI של gcloud‏ (gcloud) יש הרשאה לגשת לנתונים ולשירותים שלכם ב- Google Cloud:

    gcloud auth login

  2. מזינים את הפקודה הבאה כדי להציג את מזהי הפרויקטים של Google Cloudהפרויקטים שלכם:

    gcloud projects list

  3. משתמשים במזהה הפרויקט הרלוונטי מהשלב הקודם כדי להגדיר את פרויקט ברירת המחדלGoogle Cloud לפרויקט שבו נמצאת האפליקציה:

    gcloud config set project [YOUR_PROJECT_ID]

  4. כדי לקבל את השם של כל השירותים המנוהלים בפרויקט Google Cloud :

    gcloud endpoints services list

  5. מוחקים את השירות מניהול השירותים. מחליפים את SERVICE_NAME בשם השירות שרוצים להסיר.

    gcloud endpoints services delete SERVICE_NAME

    הפעלת הפקודה gcloud endpoints services delete לא מוחקת באופן מיידי את השירות המנוהל. השירות לניהול שירותים משבית את השירות המנוהל למשך 30 יום, כדי שיהיה לכם זמן לשחזר אותו אם תצטרכו. אחרי 30 יום, כלי ניהול השירותים מוחק את השירות המנוהל באופן סופי.

  6. עוברים לדף Load Balancer.

    כניסה לדף Load Balancer

    מחיקת מאזן העומסים espv2-load-balancer עם בדיקת תקינות espv2-load-balancer-check.

  7. עוברים לדף Instance Groups.

    כניסה לדף Instance Groups

    מחיקת load-balancing-espv2-group

  8. עוברים לדף Instance Template.

    כניסה לדף Instance Templates

    מוחקים את load-balancing-espv2-template.

המאמרים הבאים