הגדרת Cloud Endpoints gRPC ל-Knative serving עם ESPv2

הגדרת Cloud Endpoints gRPC ל-Knative serving עם ESPv2

‫OpenAPI   |  gRPC

בדף הזה מוסבר איך להגדיר Cloud Endpoints ל-Knative serving. ‫Endpoints משתמש ב-Extensible Service Proxy V2 ‏ (ESPv2) כשער API. כדי לספק ניהול API ל-Knative serving, פורסים את קובץ ה-ESPv2 המובנה מראש אל Knative serving שפועל באשכול GKE.

במסגרת ההגדרה הזו, ESPv2 מיירט את כל הבקשות לשירותים שלכם ומבצע את כל הבדיקות הנדרשות (כמו אימות) לפני הפעלת השירות. כשהשירות מגיב, ESPv2 אוסף ומדווח על טלמטריה.

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

רשימת משימות

אפשר להשתמש ברשימת המשימות הבאה במהלך העבודה עם המדריך. חובה להשלים את כל המשימות כדי לסיים את המדריך הזה.

1. יוצרים Google Cloud פרויקט, ואם לא פרסתם שירות משלכם ב-Knative serving, פורסים שירות לדוגמה. לפני שמתחילים

2. יוצרים אשכול GKE עם Knative serving מופעל.

3. פריסת דוגמה של gRPC כשירות Knative serving.

4. יוצרים מסמך הגדרות של gRPC API שמתאר את Endpoints API, ומגדירים את המסלולים לשירות Knative serving. איך מגדירים נקודות קצה

5. פורסים את מסמך ההגדרות של gRPC API כדי ליצור שירות מנוהל. איך פורסים את ההגדרה של נקודות הקצה

6. יוצרים קובץ אימג' חדש של ESPv2 Docker עם הגדרת שירות Endpoints. אפשר לעיין במאמר בנושא יצירת תמונה חדשה של ESPv2.

7. פורסים את תמונת ה-ESPv2 Knative serving החדשה. מידע נוסף זמין במאמר בנושא פריסת אימג' של ESPv2 ב-Cloud Run.

8. יוצרים מיפוי דומיין לשירות ESPv2 Knative serving.

9. כדי לבדוק את ההגדרה, שולחים בקשה אל ה-API.

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

11. ניקוי.

עלויות

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

• Knative serving
• Endpoints

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

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

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

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

נכנסים לחשבון 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 the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

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

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. חשוב לרשום את מזהה הפרויקט כי תצטרכו אותו בהמשך. בהמשך הדף הזה, מזהה הפרויקט הזה יופיע כ-ESPv2_PROJECT_ID.
2. הורדה והתקנה של ה-CLI של gcloud

הגדרה של שורת הפקודה gcloud

כדי להגדיר את ה-CLI של gcloud ל-Knative serving for Anthos:

1. מוודאים של-CLI של gcloud יש הרשאה לגשת לנתונים ולשירותים שלכם.

   1. מתחברים לחשבון.

      gcloud auth login

   2. בכרטיסייה החדשה בדפדפן שנפתחת, בוחרים חשבון עם התפקיד עורך או בעלים בפרויקט Google Cloud שיצרתם כדי לפרוס את ESPv2 ב-Knative serving.

2. עדכון של רכיבי gcloud מותקנים:

   gcloud components update

3. מגדירים את הפלטפורמה ל-gke ומגדירים את הגדרת ברירת המחדל של הפרויקט ל-gcloud לפרויקט שיצרתם:

   gcloud config set run/platform gke 
   gcloud config set project ESPv2_PROJECT_ID

   מחליפים את ESPv2_PROJECT_ID במזהה הפרויקט שיצרתם.

4. מגדירים את האזור הרצוי לאשכול החדש. אפשר להשתמש בכל אזור שבו יש תמיכה ב-GKE, לדוגמה:

   gcloud config set compute/zone ZONE

   מחליפים את ZONE באזור שלכם. לדוגמה, משתמשים ב-us-central1-a. אפשר להשתמש בכל אזור שנתמך על ידי GKE.

5. מפעילים את ממשקי ה-API הבאים בפרויקט, שנדרשים כדי ליצור אשכול, לבנות ולפרסם קונטיינר ב-Artifact Registry:

   gcloud services enable container.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com

יצירת אשכול GKE עם מילוי בקשות מסוג Knative

כדי ליצור אשכול ולהפעיל אותו עבור Knative Serving ב-Google Cloud:

1. יוצרים אשכול חדש באמצעות הפקודה:

   gcloud container clusters create CLUSTER_NAME \ 
     --addons=HttpLoadBalancing,CloudRun \ 
     --machine-type=n1-standard-4 \ 
     --num-nodes=3

   מחליפים את CLUSTER_NAME בשם שרוצים לתת לאשכול.

   הערה: גודל האשכול המינימלי הוא שלושה צמתים, וסוג המכונה המינימלי הוא n1-standard-4 בדוגמה הזו.

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

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

   Creating cluster CLUSTER_NAME...done. 
   Created [https://container.googleapis.com/v1/projects/ESPv2_PROJECT_ID/zones/ZONE/clusters/CLUSTER_NAME].

   בפלט מוצגת גם גרסת האשכול בעמודה NODE_VERSION של הפלט. לדוגמה, 1.15.11-gke.1 או 1.14.10-gke.27. חשוב לשים לב לגרסת האשכול כדי להשתמש בה בהמשך המסמך.

3. כדי שלא תצטרכו לציין את האשכול החדש ואת המיקום שלו כשאתם משתמשים ב-CLI של gcloud, אתם יכולים להגדיר את ברירות המחדל של gcloud כך שישתמשו באשכול החדש ובמיקום שלו:

   gcloud config set run/cluster CLUSTER_NAME
   gcloud config set run/cluster_location ZONE

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

   gcloud container clusters describe CLUSTER_NAME

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

   gcloud container clusters get-credentials CLUSTER_NAME

פריסה של שירות לדוגמה של gRPC Cloud Run

כדי לפרוס את קונטיינר הדוגמה של Cloud Run for Anthos‏ grpc-bookstore לאשכול שיצרתם:

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

2. הדוגמה הזו של שרת gRPC מכילה קובץ אימג' של Docker שנוצר מראש עבור Python 'grpc-bookstore service': gcr.io/endpointsv2/python-grpc-bookstore-server:2. כדי לפרוס את grpc-bookstore לאשכול, משתמשים בפקודה הבאה:

   gcloud run deploy GRPC_SERVICE \
     --image=gcr.io/endpointsv2/python-grpc-bookstore-server:2 \
     --platform=gke \
    --connectivity=internal \
     --use-http2

   חשוב לציין שאתם מגדירים את זה כשירות פנימי, כדי שלא תהיה גישה לשירות מבחוץ.

   מחליפים את GRPC_SERVICE בשם שרוצים לתת לשירות. לדוגמה:

   gcloud run deploy grpc-bookstore \
     --image=gcr.io/endpointsv2/python-grpc-bookstore-server:2 \
     --platform=gke \
     --connectivity=internal \
     --use-http2

   בסיום, תוצג ההודעה הבאה:

   Service [grpc-bookstore] revision [grpc-bookstore-00001-nuk] has been deployed and is serving 100 percent of traffic at http://grpc-bookstore.default.svc.cluster.local

   כשיוצרים שירות פנימי, GKE יוצר שם DNS (grpc-bookstore.default.svc.cluster.local בדוגמה הזו) שאפשר לפתור רק בקשות שמקורן בתוך האשכול עצמו, ולא בקשות חיצוניות. אי אפשר לגשת ל-DNS הזה מבחוץ לאשכול. מידע נוסף זמין במאמר בנושא שירותי Cloud Run.

3. כדי לוודא שהשירות פועל בצורה תקינה, פורסים Pod עם אותו קובץ אימג' של Docker באשכול. התמונה מכילה את קוד הלקוח של gRPC עבור grpc-bookstore שאפשר להשתמש בו כדי לבדוק את השירות הפנימי.

   1. כדי לפרוס את ה-Pod לאותו אשכול שפרסתם קודם, משתמשים בפקודה kubectl הבאה:

      kubectl run grpc --generator=run-pod/v1 \
        --image=gcr.io/endpointsv2/python-grpc-bookstore-server:2

      התמונה הזו מכילה את סקריפט bookstore_client.py שבו אפשר להשתמש כדי לשלוח בקשות מצד הלקוח מתוך האשכול.

      הערה: בגרסאות חדשות יותר של kubectl, יכול להיות שהפקודה תציג את האזהרה הבאה:

      Flag --generator has been deprecated, has no effect and will be removed in the future".

      אפשר להתעלם מהאזהרה הזו.

   2. מקבלים את השם של ה-Pod ‏grpc-bookstore שנוצר באשכול כשפרסתם את קובץ האימג' של Docker בשלב הקודם:

      kubectl get pods

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

      NAME   READY    STATUS    RESTARTS   AGE
      grpc   1/1      Running   0          23h

      כאשר grp הוא השם של הפוד grpc-bookstore. לפני שממשיכים, מוודאים שהסטטוס של ה-pod הוא Running.

   3. כדי לשלוח בקשת לקוח לשירות grpc-bookstore, משתמשים בפקודה הבאה:

      kubectl exec grpc -ti -- python3 bookstore_client.py \
        --host grpc-bookstore.default.svc.cluster.local --port=80

      הפקודה הזו מריצה את הסקריפט bookstore_client.py באופן פנימי באשכול כדי לשלוח בקשת gRPC לשירות grpc-bookstore בשם המארח grpc-bookstore.default.svc.cluster.local.

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

      ListShelves: shelves {
        id: 1
        theme: "Fiction"
      }
      shelves {
        id: 2
        theme: "Fantasy"
      }

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

צריך להיות לכם מפרט של gRPC API שמתאר את הפלטפורמה של השירות לקצה העורפי ואת דרישות האימות.

מידע על הגדרת שדה השם של מפרט gRPC API

בשדה name במפרט של gRPC API, מציינים את שם שירות Endpoints שמשמש לגישה לשירות Knative serving. שם השירות של Endpoints הוא בפורמט של שם דומיין:

API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog

מכיוון ששם השירות של Endpoints תואם לשם דומיין, השם צריך לעמוד בכללים הבאים:

• השם יכול להכיל רק אותיות קטנות, מספרים, נקודות או מקפים.
• השם לא יכול להתחיל במקף.
• אסור להכיל קו תחתון.

לדוגמה:

grpc-boostore-api.endpoints.ESPv2_PROJECT_ID.cloud.goog

יצירת מפרט gRPC API

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

1. יוצרים ספרייה חדשה למפרט gRPC API, למשל my-anthos-grpc. ואז משתמשים בפקודה cd כדי לעבור לספרייה הזו.

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

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

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

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

   שימו לב שהספרייה הזו מכילה את הקובץ bookstore.proto. הקובץ הזה מגדיר את ה-API של שירות חנות הספרים.

4. יוצרים קובץ תיאור protobuf עצמאי מקובץ .proto של השירות:

   1. יוצרים את הספרייה generated_pb2 בספריית העבודה.

   2. יוצרים את קובץ התיאור, api_descriptor.pb, באמצעות קומפיילר מאגרי האחסון לפרוטוקולים protoc. מריצים את הפקודה הבאה בספרייה שמכילה את bookstore.proto:

      python3 -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.

5. משנים את קובץ api_config_anthos.yaml בספריית העבודה הנוכחית (אותה ספרייה שמכילה את bookstore.proto) כדי להוסיף את התוכן הבא לקובץ:

   type: google.api.Service
   config_version: 3
   #
   # Name of the service configuration.
   #
   name: API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog
   #
   # API title to appear in the user interface (Google Cloud console).
   #
   title: Bookstore gRPC API In Cloud Run Anthors
   apis:
   - name: endpoints.examples.bookstore.Bookstore
   #
   # Create a DNS record to map your service name to IP address
   #
   endpoints:
     - name: API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog
       target: IP_ADDRESS
   #
   # Specify the backend address to route to
   #
   backend:
     rules:
       - selector: "*"
         address: grpc://GRPC_SERVICE.default.svc.cluster.local
         disable_auth: true
   #
   # API usage restrictions.
   #
   usage:
     rules:
     # ListShelves methods can be called without an API Key.
     - selector: endpoints.examples.bookstore.Bookstore.ListShelves
       allow_unregistered_calls: true

   הזחה חשובה בפורמט yaml.

6. בשדה name, מציינים את שם הדומיין של Cloud Endpoints API שמשמש לגישה לשירות Knative Serving, בפורמט:

   API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog

   לדוגמה:

   grpc-bookstore-api.endpoints.ESPv2_PROJECT_ID.cloud.goog

7. בקטע endpoints נרשם רשומת DNS לשירות Endpoints בדומיין cloud.goog, בתבנית:

   endpoints:
     - name: API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog
       target: IP_ADDRESS

   הערה: אם הגדרתם מיפוי דומיין משלכם לאשכול, אתם יכולים לדלג על השלב הזה. מידע נוסף זמין במאמר בנושא הגדרת DNS בדומיין cloud.goog.

   ‫IP_ADDRESS היא כתובת ה-IP של שירות istio-ingress באשכול. כדי לזהות את כתובת ה-IP הזו:

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

      מעבר אל Google Kubernetes Engine

   2. בחלונית הניווט שמימין, לוחצים על Services & Ingress (שירותים וכניסה) כדי להציג רשימה של שירותים.

   3. אם גרסת האשכול היא 1.15.3-gke.19 ומעלה, 1.14.3-gke.12 ומעלה או 1.13.10-gke.8 ומעלה, גוללים למטה לשירות istio-ingress. בכל הגרסאות האחרות של האשכול, גוללים למטה אל השירות istio-ingressgateway.

   4. מעתיקים את כתובת ה-IP החיצונית שמוצגת לצד מאזן העומסים, בלי הגדרת היציאה, אם יש כזו. לדוגמה, אם כתובת ה-IP היא XX.XXX.XX.XXX:15020, לא צריך לציין את :15020. מתעלמים מכתובות ה-IP האחרות שמופיעות ברשימה.

8. השדה address בקטע backend מציין את שם ה-DNS הפנימי של שירות Cloud Run ‏grpc-bookstore עם סכמת proto ‏grpc://, ומשבית את האימות לשירות הזה:

   address: grpc://GRPC_SERVICE.default.svc.cluster.local
   disable_auth: true

   לדוגמה:

   address: grpc://grpc-bookstore.default.svc.cluster.local
   disable_auth: true

   הדבר נדרש כי הקריאה מ-ESPv2 לשירות Knative serving מתבצעת כקריאה פנימית מתוך האשכול, ולכן לא נדרש אימות.

9. שימו לב לערך של מאפיין title בקובץ api_config_authos.yaml:

   title: Bookstore gRPC API In Cloud Run Anthos

   הערך של המאפיין title הופך לשם של שירות Endpoints אחרי פריסת ההגדרה.

10. שומרים את מסמך ה-gRPC API.

מידע על השדות במסמך OpenAPI שנדרשים ל-Endpoints זמין במאמר הגדרת Endpoints.

פריסת ההגדרה של נקודות הקצה

כדי לפרוס את ההגדרה של Endpoints, משתמשים בפקודה gcloud endpoints services deploy. הפקודה הזו משתמשת ב-Service Management כדי ליצור שירות מנוהל.

כדי לפרוס את ההגדרה של Endpoints:

1. מוודאים שאתם נמצאים בספרייה שמכילה את מסמך ה-gRPC.

2. מעלים את ההגדרה ויוצרים שירות מנוהל.

   gcloud endpoints services deploy api_descriptor.pb api_config_anthos.yaml \ 
     --project ESPv2_PROJECT_ID

   כך נוצר שירות Endpoints חדש עם השם שציינתם בשדה name בקובץ api_config_anthos.yaml. שירות ה-Endpoints מוגדר בהתאם למסמך ה-OpenAPI שלכם.

   במהלך היצירה וההגדרה של שירות Endpoints, ‏ Service Management מציג מידע במסוף. בסיום הפריסה, תוצג הודעה שדומה להודעה הבאה:

   Service Configuration [CONFIG_ID] uploaded for service [API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog]

   ‫CONFIG_ID הוא מזהה ייחודי של הגדרת שירות Endpoints שנוצר על ידי הפריסה. לדוגמה:

   Service Configuration [2019-02-01r0] uploaded for service [grpc-bookstore-api.endpoints.ESPv2_PROJECT_ID.cloud.goog] 

   מזהה הגדרות השירות מורכב מחותמת זמן של התאריך וממספר הגרסה. אם פורסים את api_config_anthos.yaml שוב באותו יום, מספר הגרסה גדל במזהה הגדרת השירות. אפשר לראות את הגדרות השירות ואת היסטוריית הפריסה בדף Endpoints > Services במסוף Google Cloud .

   אם מופיעה הודעת שגיאה, אפשר להיעזר בפתרון בעיות בהטמעה של הגדרות 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.

יצירת תמונה חדשה של ESPv2 Knative serving

יוצרים קובץ אימג' חדש של ESPv2 Docker מהגדרות השירות של Endpoints. אחרי שיוצרים את התמונה, אפשר לפרוס אותה באשכול.

הערה:

השלב הזה הוא חובה.

צריך ליצור קובץ אימג' חדש של Docker עם הגדרות השירות, כי Cloud Run הוא שירות scale-to-zero. כלומר, כשאין תנועה, כל המופעים נמחקים. כשהתנועה גדלה, נוצרים מופעים חדשים על פי דרישה. יצירה של מופע שירות מהסוג הזה נקראת גם הפעלה במצב התחלתי (cold start). מידע נוסף זמין במאמר בנושא בו-זמניות ב-Cloud Run.

אם קובץ האימג' של Docker לא כולל את הגדרת השירות, Cloud Run יצטרך לבצע שתי קריאות ל-Google ServiceManagement בהפעלה במצב התחלתי (cold start). הקריאות האלה נספרות במכסה של Google ServiceManagement API.

הטמעת הגדרות השירות בתמונת ה-Docker של ESPv2 מאפשרת להסיר את שתי הקריאות ל-API ולמנוע השפעה על ספירת המכסות בשירות Google ServiceManagement. בנוסף, השלב הזה מזרז את יצירת המופע החדש של השירות ומקטין את זמן האחזור של הבקשות שממתינות למופע החדש.

צריך להריץ מחדש את כל השלב הזה ולפרוס מחדש את הקונטיינר החדש:

• בכל פעם שמשנים את הגדרת השירות של Endpoints ומבצעים פריסה מחדש. אחרת, השינויים בהגדרות השירות לא יועברו ל-ESPv2.
• כשמתפרסמת גרסה חדשה של ESPv2. אחרת, הגרסה הישנה יותר של ESPv2 תמשיך להיות בפריסה.

כדי ליצור את קובץ ההגדרות של השירות בקובץ אימג' חדש של ESPv2 Docker:

1. מורידים את הסקריפט הזה למחשב המקומי שבו מותקן ה-CLI של gcloud ומריצים אותו כך:

   chmod +x gcloud_build_image 
   ./gcloud_build_image -s API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog \ 
   -c CONFIG_ID -p ESPv2_PROJECT_ID

   הערה: כדי להשתמש בסקריפט הזה צריך bash. אם אתם לא משתמשים ב-macOS או ב-Linux, אתם יכולים להריץ אותו ב-Cloud Shell, ב-Compute Engine או ב-Windows Subsystem for Linux.

   הסקריפט משתמש בפקודה gcloud כדי להוריד את הגדרות השירות, ליצור את הגדרות השירות בקובץ אימג' חדש של ESPv2 ולהעלות את קובץ האימג' החדש למאגר הקונטיינרים של הפרויקט. הסקריפט משתמש אוטומטית בגרסה האחרונה של ESPv2, שמסומנת ב-ESPv2_VERSION בשם של תמונת הפלט. התמונה שנוצרה מועלית אל:

   gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog-CONFIG_ID

פריסת תמונת ESPv2 Knative serving

פורסים את תמונת השירות של ESPv2 Knative serving באשכול:

1. פורסים את שירות ESPv2 Knative serving עם קובץ האימג' החדש:

   gcloud run deploy ESPv2_SERVICE_NAME \ 
     --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog-CONFIG_ID" \ 
     --platform gke \
     --use-http2 \
     --project=ESPv2_PROJECT_ID

   ב-ESPv2_PROJECT_ID מציינים את השם שרוצים להשתמש בו בשירות ESPv2. בדוגמה הזו, מגדירים את ESPv2_SERVICE_NAME ל-ESPv2.

2. אם רוצים להגדיר את Endpoints כך שישתמש באפשרויות נוספות להפעלה של ESPv2, כמו הפעלת CORS, אפשר להעביר את הארגומנטים במשתנה הסביבה ESPv2_ARGS:

   gcloud run deploy ESPv2_SERVICE_NAME \
     --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog-CONFIG_ID" \ 
     --set-env-vars=ESPv2_ARGS=--cors_preset=basic \ 
     --platform gke --use-http2 \
     --project ESPv2_PROJECT_ID

   למידע נוסף ודוגמאות להגדרת משתנה הסביבה ESPv2_ARGS, כולל רשימת האפשרויות הזמינות ומידע על ציון כמה אפשרויות, אפשר לעיין במאמר Extensible Service Proxy V2 flags.

יצירת מיפוי דומיין לשירות ESPv2 Knative serving

כדי להשמיט את הכותרת host כששולחים בקשה, צריך להוסיף מיפוי דומיין לשירות ESPv2:

1. כניסה ל-Cloud Run

2. בוחרים באפשרות ניהול דומיינים מותאמים אישית.

3. לוחצים על הוספת מיפוי.

4. בתפריט הנפתח, בוחרים באפשרות הוספת מיפוי של דומיין שירות.

5. בשדה בחירת שירות למיפוי בחלון הקופץ הוספת מיפוי, בוחרים את שירות ESPv2.

6. בשדה Enter domain name (הזנת שם הדומיין), מציינים את שם הדומיין שבו רוצים להשתמש כדי לגשת לשירות Knative serving דרך Endpoints. לדוגמה, מציינים:

   API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog

   כאשר API_NAME הוא שם ה-API של Endpoints. בדוגמה הזו, אפשר להשתמש ב-hello-api:

   grpc-bookstore-api.endpoints.ESPv2_PROJECT_ID.cloud.goog

7. לוחצים על Continue. יופיע סיכום של המיפוי.

8. כדי לשמור את המיפוי, לוחצים על סיום.

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

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

1. חשוב לוודא שאתם נמצאים בספרייה שמכילה את מסמכי ה-gRPC, כמו api_config_anthos.yaml.

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

   pip3 install virtualenv
   virtualenv env
   source env/bin/activate
   pip3 install -r requirements.txt

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

   python3 bookstore_client.py --host API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog --port 80

   לדוגמה:

   python3 bookstore_client.py --host grpc-bookstore-api.endpoints.ESPv2_PROJECT_ID.cloud.goog --port 80

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

   ListShelves: shelves {
     id: 1
     theme: "Fiction"
   }
   shelves {
     id: 2
     theme: "Fantasy"
   }

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

     לדף Endpoints Services

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

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

     כניסה לדף Logs Explorer

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

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

הגדרת Endpoints API לשימוש ב-HTTPS

התמיכה האוטומטית ב-TLS מושבתת כברירת מחדל ב-Knative serving ב-Google Cloud. לכן, בדוגמה הזו, כשניגשים ל-Endpoints API דרך ESPv2, הקריאה מתבצעת באמצעות HTTP.

אפשר להגדיר את ESPv2 כך שיתמוך בבקשות באמצעות HTTPS. שימו לב: מגדירים תמיכה ב-HTTPS ב-ESPv2, השירות החיצוני, ולא ב-hello, שירות הקצה העורפי הפנימי.

כדי לתמוך ב-HTTPS באמצעות ESPv2, צריך:

1. להיות בעלים של דומיין. אם אין לכם דומיין, אתם יכולים לקבל אותו מ-Google או מספק דומיינים אחר.

2. יצירת מיפוי דומיין לשירות ESPv2 ועדכון רשומת ה-DNS בהתאם להוראות בדף מיפוי הדומיינים.

   אם קיבלתם את הדומיין מ-Google Domains, השתמשו בו כשרת DNS. אחרת, צריך להשתמש ב-Cloud DNS או בשרת DNS אחר לפי בחירתכם. האפשרות הכי קלה היא להשתמש בדומיין מ-Google Domains.

3. במפרט OpenAPI של נקודות הקצה:

   1. מגדירים את השדה name כך שיפנה לדומיין שלכם במקום ל-*.cloud.goog.

   2. מסירים את התג endpoints ואת שני מאפייני הצאצא שלו.

הוראות מלאות ומדריך זמינים במאמר בנושא הפעלת HTTPS ואישורי TLS אוטומטיים.

הערה: אם אתם רוצים לספר לנו מה אהבתם במדריך הזה, אתם יכולים לשלוח משוב בתחתית הדף. המשוב שלכם עוזר לנו לשפר את המדריכים האלה.
אם קיבלתם שגיאה, הצטרפו לgoogle-cloud-endpointsקבוצת Google וספרו לנו מה השתבש. הקבוצה הזו מקבלת תשובות ממשתמשי Endpoints אחרים ומהמהנדסים של Google שעוקבים אחרי הקבוצה.

מעקב אחר פעילות ב-API

1. אפשר לראות את הגרפים של הפעילות ב-API בדף Endpoints ‏ > Service במסוף Google Cloud .

   הצגת גרפים של פעילות ב-Endpoints

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

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

   הצגת יומני הבקשות של Endpoints

הסרת המשאבים

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

במאמר מחיקת API ומופעי API מוסבר איך להפסיק את השירותים שבהם נעשה שימוש במדריך הזה.

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

• מידע נוסף על Cloud Run
• מידע נוסף על פריסת ההגדרה של Endpoints
• שיתוף ה-API עם מפתח אחר
• מידע על אימות
• מידע על אפשרויות תמיכה קהילתית