תחילת העבודה עם Endpoints for GKE עם ESP

במדריך הזה נסביר איך לפרוס דוגמה פשוטה של שירות gRPC באמצעות Extensible Service Proxy‏ (ESP) ב-Google Kubernetes Engine‏ (GKE). במדריך הזה נעשה שימוש בגרסת Python של הדוגמה bookstore-grpc. דוגמאות ל-gRPC בשפות אחרות מופיעות בקטע מה השלב הבא.

במדריך הזה נעשה שימוש בקובצי אימג' של קונטיינרים שנבנו מראש של קוד לדוגמה ושל ESP, שמאוחסנים ב-Artifact Registry. אם אתם לא מכירים את המושג 'מאגרי תגים', תוכלו לקרוא מידע נוסף במאמרים הבאים:

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

מטרות

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

  1. מגדירים Google Cloud פרויקט ומורידים את התוכנה הנדרשת. לפני שמתחילים
  2. העתקה והגדרה של קבצים מהדוגמה bookstore-grpc. איך מגדירים נקודות קצה
  3. פורסים את ההגדרה של Endpoints כדי ליצור שירות Endpoints. איך פורסים את ההגדרה של נקודות הקצה
  4. יוצרים קצה עורפי להצגת ה-API ופורסים את ה-API. מידע נוסף זמין במאמר בנושא פריסת קצה העורפי של ה-API.
  5. קבלת כתובת ה-IP החיצונית של השירות. איך מקבלים את כתובת ה-IP החיצונית של השירות
  6. שליחת בקשה ל-API. שליחת בקשה ל-API
  7. כדי להימנע מחיובים בחשבון 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. חשוב לרשום את Google Cloud מזהה הפרויקט כי תצטרכו אותו בהמשך.
  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. התקנה של kubectl: 
    gcloud components install kubectl
  12. קבלת פרטי כניסה חדשים של משתמשים לשימוש כפרטי הכניסה שמוגדרים כברירת מחדל באפליקציה. צריך את פרטי הכניסה של המשתמש כדי לתת הרשאה ל-kubectl. 
    gcloud auth application-default login
     בכרטיסייה החדשה בדפדפן שנפתחת, בוחרים חשבון.
  13. כדי להתקין את gRPC ואת כלי gRPC, פועלים לפי השלבים שמפורטים ב מדריך למתחילים של gRPC Python.

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

הדוגמה bookstore-grpc כוללת את הקבצים שצריך להעתיק באופן מקומי ולהגדיר.

  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

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

יצירת אשכול של מאגרי תגים

כדי ליצור אשכול מאגרי תגים לדוגמה:

  1. נכנסים לדף Kubernetes clusters במסוף Google Cloud .

    כניסה לדף Kubernetes clusters

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

אימות kubectl לאשכול המכילים

כדי להשתמש ב-kubectl כדי ליצור ולנהל משאבי אשכול, צריך לקבל פרטי כניסה לאשכול ולהפוך אותם לזמינים ל-kubectl. כדי לעשות את זה, מריצים את הפקודה הבאה ומחליפים את NAME בשם החדש של האשכול ואת ZONE באזור של האשכול.

gcloud container clusters get-credentials NAME --zone ZONE

בדיקת ההרשאות הנדרשות

‫ESP ו-ESPv2 קוראים לשירותי Google שמשתמשים ב-IAM כדי לוודא שלזהות שקוראת יש מספיק הרשאות לגשת למשאבי ה-IAM שנעשה בהם שימוש. הזהות של הקריאה היא חשבון השירות המצורף שפורסו בו ESP ו-ESPv2.

כשפורסים את האפליקציה בתרמיל GKE, חשבון השירות המצורף הוא חשבון השירות של הצומת. בדרך כלל זה חשבון השירות שמוגדר כברירת מחדל ב-Compute Engine. כדי לבחור חשבון שירות מתאים לצומת, צריך לפעול לפי ההמלצה בנושא הרשאות.

אם נעשה שימוש ב- Workload Identity, אפשר להשתמש בחשבון שירות נפרד, שאינו חשבון השירות של הצומת, כדי לתקשר עם שירותי Google. אפשר ליצור חשבון שירות של Kubernetes בשביל הפוד כדי להריץ את ESP ו-ESPv2, ליצור חשבון שירות של Google ולקשר את חשבון השירות של Kubernetes לחשבון השירות של Google.

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

אם חשבון השירות המצורף הוא חשבון השירות שמוגדר כברירת מחדל ב-Compute Engine של הפרויקט, וההגדרה של שירות נקודת הקצה נפרסת באותו הפרויקט, לחשבון השירות אמורות להיות מספיק הרשאות כדי לגשת למשאבי IAM, ולכן אפשר לדלג על שלב ההגדרה של תפקידי IAM. אחרת, צריך להוסיף את התפקידים הבאים ב-IAM לחשבון השירות המצורף.

מוסיפים את התפקידים הנדרשים ב-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 הוא חשבון השירות המצורף. מידע נוסף זמין במאמר מהם תפקידים והרשאות?

פריסת ה-API לדוגמה ו-ESP באשכול

כדי לפרוס את שירות ה-gRPC לדוגמה באשכול כדי שהלקוחות יוכלו להשתמש בו:

  1. שומרים ופותחים לעריכה עותק של קובץ המניפסט של הפריסה grpc-bookstore.yaml.
  2. מחליפים את SERVICE_NAME בשם של שירות Endpoints. זהו אותו שם שהגדרתם בשדה name בקובץ api_config.yaml. 
    spec:
  containers:
  - name: esp
    image: gcr.io/endpoints-release/endpoints-runtime:1
    args: [
      "--http2_port=9000",
      "--service=SERVICE_NAME",
      "--rollout_strategy=managed",
      "--backend=grpc://127.0.0.1:8000"
    ]
    ports:
      - containerPort: 9000
  - name: bookstore
    image: gcr.io/endpointsv2/python-grpc-bookstore-server:1
    ports:
      - containerPort: 8000

    האפשרות --rollout_strategy=managed מגדירה את ESP כך שישתמש בהגדרת השירות העדכנית ביותר שנפרסה. אם תבחרו באפשרות הזו, עד 5 דקות אחרי שתפרסו הגדרת שירות חדשה, ESP יזהה את השינוי ויתחיל להשתמש בה באופן אוטומטי. אנחנו ממליצים לציין את האפשרות הזו במקום מזהה תצורה ספציפי לשימוש ב-ESP. פרטים נוספים על הארגומנטים של ESP זמינים במאמר בנושא אפשרויות הפעלה של ESP.

    לדוגמה:

        spec:
      containers:
      - name: esp
        image: gcr.io/endpoints-release/endpoints-runtime:1
        args: [
          "--http2_port=9000",
          "--service=bookstore.endpoints.example-project-12345.cloud.goog",
          "--rollout_strategy=managed",
          "--backend=grpc://127.0.0.1:8000"
        ]
  3. מפעילים את השירות: 
    kubectl create -f grpc-bookstore.yaml

אם מופיעה הודעת שגיאה, אפשר לעיין במאמר בנושא פתרון בעיות בנקודות קצה ב-GKE.

קבלת כתובת ה-IP החיצונית של השירות

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

  1. צפייה בכתובת ה-IP החיצונית:

    kubectl get service

  2. רושמים את הערך של EXTERNAL-IP ושומרים אותו במשתנה סביבה SERVER_IP. כתובת ה-IP החיצונית משמשת לשליחת בקשות ל-API לדוגמה.

    export SERVER_IP=YOUR_EXTERNAL_IP

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

כדי לשלוח בקשות ל-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. מחיקת ה-API:

    gcloud endpoints services delete SERVICE_NAME

    מחליפים את SERVICE_NAME בשם ה-API.

  2. מחיקת אשכול GKE:

    gcloud container clusters delete NAME --zone ZONE

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