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

בדף הזה מוסבר איך להגדיר 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. פריסת דוגמה של שירות Knative serving.

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

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

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

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

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

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

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

  11. ניקוי.

עלויות

במסמך הזה משתמשים ברכיבים הבאים של 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. חשוב לרשום את מזהה הפרויקט כי תצטרכו אותו בהמשך. בהמשך הדף הזה, מזהה הפרויקט הזה יופיע כ-ESPv2_PROJECT_ID.
  7. הורדה והתקנה של Google Cloud SDK
  8. מתקינים את curl אם רוצים לשלוח בקשה לשירות לדוגמה שנפרס.

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

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

  1. מוודאים ש-Google Cloud SDK מורשה לגשת לנתונים ולשירותים שלכם.

    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 serving

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

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

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

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

    למרות שההוראות האלה לא מפעילות התאמה אוטומטית לעומס באשכול כדי לשנות את גודל האשכולות בהתאם לביקוש, 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

פריסת קונטיינר לדוגמה של Knative serving

כדי לפרוס את קונטיינר הדוגמה של Knative serving‏ 'hello' לאשכול שיצרתם:

  1. כניסה ל-Cloud Run

  2. לוחצים על יצירת שירות.

  3. בוחרים באפשרות Knative serving כפלטפורמת הפיתוח.

  4. בתפריט הנפתח של האשכולות הזמינים, בוחרים את האשכול שיצרתם.

  5. משתמשים בשם hello בתור שם השירות. אפשר להשתמש בשם אחר, אבל אם עושים את זה, צריך להשתמש באותו שם בהמשך. בהוראות האלה אנחנו מניחים שאתם משתמשים ב-hello.

  6. בוחרים באפשרות Internal (פנימי) בקטע Connectivity (קישוריות) כדי שהשירות לא יהיה נגיש מבחוץ.

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

  8. מציינים את gcr.io/cloudrun/hello בתור כתובת ה-URL של קובץ אימג' של קונטיינר.

  9. לוחצים על יצירה כדי לפרוס את התמונה ב-Knative serving וממתינים עד שהפריסה תסתיים.

    בסיום, מופיע המסך Revisions (גרסאות). שימו לב שכתובת ה-URL של השירות שנפרס היא:

    http://hello.default.svc.cluster.local

    כשיוצרים שירות פנימי, ‏ GKE יוצר שם DNS שאפשר להשתמש בו רק לבקשות שמקורן בתוך האשכול עצמו, ולא לבקשות חיצוניות. אין לך אפשרות לגשת לקישור הזה מבחוץ לאשכול. מידע נוסף זמין במאמר בנושא שירותי Cloud Run.

  10. כדי לוודא שהשירות פועל בצורה תקינה באמצעות curl, צריך להגדיר מנהרה משולחן העבודה אל האשכול. כדי לראות את ההוראות האלה, לוחצים על הסמל סמל של מידע נוסף משמאל לכתובת ה-URL במסך Revisions:

    מסך הגרסאות.

  11. נפתחת חלונית שבה מוצגות שתי הפקודות שמשמשות לגישה לשירות הפנימי. צריך להריץ את הפקודות האלה בשני חלונות מסוף נפרדים, כי הפקודה הראשונה מגדירה העברת יציאות שמשמשת את הפקודה השנייה.

    כשמריצים את פקודת curl, אמור להופיע פלט מהשירות שלכם בפורמט הבא:

    <!doctype html>
<html lang=en>
<head>
<meta charset=utf-8>
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Congratulations | Cloud Run</title> 
...

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

צריך ליצור מסמך OpenAPI שמבוסס על OpenAPI 2.0 או על OpenAPI 3.x, ומתאר את הסביבה של האפליקציות ואת דרישות האימות. מידע נוסף זמין במאמר גרסאות נתמכות של OpenAPI.

צריך גם להוסיף שדה ספציפי ל-Google שמכיל את כתובת ה-URL של כל אפליקציה, כדי של-ESPv2 יהיה המידע שהוא צריך כדי להפעיל אפליקציה. אם אתם חדשים ב-OpenAPI, תוכלו לקרוא מידע נוסף בסקירה כללית של OpenAPI.

מידע על הגדרת שדה המארח במפרט OpenAPI

במפרט OpenAPI, מציינים את שם שירות Endpoints שמשמש לגישה לשירות Knative serving. השם של שירות Endpoints הוא בפורמט של שם דומיין. השיטה לציון שם השירות תלויה בגרסה של מפרט OpenAPI שבה אתם משתמשים.

OpenAPI 2.0

משתמשים בשדה host כדי לציין את שם השירות:

host: API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog

‫OpenAPI 3.x

משתמשים בשדה url באובייקט servers כדי לציין את שם השירות:

servers:
- url: https://API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog
  x-google-endpoint: {}

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

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

לדוגמה:

hello-api.endpoints.ESPv2_PROJECT_ID.cloud.goog

יצירת מפרט OpenAPI

  1. יוצרים קובץ טקסט בשם openapi-run-anthos.yaml.
  2. שירות הקצה העורפי של Knative serving מוגדר בחלק העליון של הקובץ openapi-run-anthos.yaml. לדוגמה:

    OpenAPI 2.0

    swagger: '2.0'
info:
      title: Cloud Endpoints + Cloud Run
      description: Sample API on Cloud Endpoints with a Cloud Run backend
      version: 1.0.0
host: API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog
x-google-endpoints:
    - name: API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog
      target: "INGRESS-IP"
schemes:
    - https
produces:
    - application/json
x-google-backend:
      address: http://hello.default.svc.cluster.local
      disable_auth: true
paths:
      /hello:
        get:
          summary: Greet a user
          operationId: hello
          responses:
            '200':
              description: A successful response
              schema:
                type: string

    ‫OpenAPI 3.x

    openapi: 3.0.4
info:
  title: Cloud Endpoints + Cloud Run
  description: Sample API on Cloud Endpoints with a Cloud Run backend
  version: 1.0.0
servers:
- url: https://API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog
  x-google-endpoint:
    target: "INGRESS_IP"
x-google-api-management:
  backends:
    cloudrun_anthos_backend:
      address: http://hello.default.svc.cluster.local
      disable_auth: true
      protocol: "http/1.1"
x-google-backend: cloudrun_anthos_backend
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string

    ההזחה חשובה בפורמט YAML. לדוגמה, השדה host (ב-OpenAPI 2.0) או האובייקט servers (ב-OpenAPI 3.x) צריכים להיות באותה רמה כמו info.

  3. בשדה host (ב-OpenAPI 2.0) או בשדה servers של אובייקט url (ב-OpenAPI 3.x), מציינים את שם הדומיין של Endpoints API שמשמש לגישה לשירות Knative serving, בפורמט: 
    API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog

    לדוגמה:

    hello-api.endpoints.my-espv2-project-id.cloud.goog
  4. התוסף x-google-endpoints רושם רשומת DNS לשירות Endpoints בדומיין cloud.goog, בתבנית הבאה:

    OpenAPI 2.0

    x-google-endpoints:
  - name: "API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog"
  target: "IP_ADDRESS"

    ‫OpenAPI 3.x

    servers:
  - url: https://API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog
    x-google-endpoint:
      target: "IP_ADDRESS"

    ‫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 היא 192.0.2.1:15020, לא צריך לציין את :15020. מתעלמים מכתובות ה-IP האחרות שמופיעות ברשימה.
  5. בקטע address, מציינים את שם ה-DNS הפנימי של שירות ה-Backend Knative serving hello ומשביתים את האימות לשירות הזה. הדבר נדרש כי הקריאה מ-ESPv2 לשירות Knative serving מתבצעת כקריאה פנימית מתוך האשכול, ולכן אין צורך באימות.

  6. שימו לב לערך של מאפיין title בקובץ openapi-run-anthos.yaml:

    title: Cloud Endpoints + Cloud Run

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

  7. שומרים את מסמך OpenAPI.

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

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

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

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

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

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

    gcloud endpoints services deploy openapi-run-anthos.yaml \
  --project ESPv2_PROJECT_ID

    כך נוצר שירות Endpoints חדש עם השם שציינתם כשם המארח במסמך OpenAPI. שירות ה-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 [hello-api.endpoints.ESPv2_PROJECT_ID.cloud.goog]

    מזהה הגדרות השירות מורכב מחותמת זמן של התאריך וממספר הגרסה. אם פורסים את openapi-run-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. אחרי שיוצרים את התמונה, אפשר לפרוס אותה באשכול.

כדי ליצור את קובץ ההגדרות של השירות בקובץ אימג' חדש של 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

    הסקריפט משתמש בפקודה 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:ESPv2_VERSION-API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog-CONFIG_ID" \
  --platform gke \
  --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:ESPv2_VERSION-API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
  --platform gke \
  --project ESPv2_PROJECT_ID

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

  3. נותנים ל-ESPv2 הרשאה לבצע קריאה ל-Service Management ול-Service Control.

    • נכנסים לדף Cloud Run במסוף Google Cloud .

      כניסה לדף Cloud Run

    • מוצאים את מופע Cloud Run שפרסתם ואת חשבון השירות שמשויך אליו.

    • מקצים לחשבון השירות את ההרשאות הנדרשות: 

      gcloud projects add-iam-policy-binding PROJECT_NAME 
      
--member "serviceAccount:SERVICE_ACCOUNT" 
      
--role roles/servicemanagement.serviceController

    מידע נוסף זמין במאמר מהם תפקידים והרשאות?

שירות ESPv2 נפרס כשירות חיצוני, כלומר אפשר לגשת אליו באמצעות פקודת curl בצורה הבאה:

curl -H "Host: espv2.default.example.com" http://IP_ADDRESS

כאשר IP_ADDRESS היא כתובת ה-IP של שירות istio-ingress עבור האשכול שלכם.

כדי לראות את פקודת ה-curl הזו, לוחצים על סמל התמונה משמאל לכתובת ה-URL של ESPv2 במסך Revisions של שירות ESPv2 Knative serving שנפרס.

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

curl -H "Host: espv2.default.example.com" http://IP_ADDRESS/hello

עם זאת, לא נוח לציין כותרת host בכל בקשה לשירות Endpoints. בקטע הבא מוגדרת מפת דומיין כדי להקל על ביצוע קריאה לשירות Endpoint באמצעות ESPv2.

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

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

  1. כניסה ל-Cloud Run

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

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

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

  5. בשדה Select a service to map to (בחירת שירות למיפוי) בתיבת הדו-שיח Add mapping (הוספת מיפוי), בוחרים את שירות ESPv2.

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

    API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog

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

    hello-api.endpoints.ESPv2_PROJECT_ID.cloud.goog

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

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

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

משתמשים ב-curl כדי לשלוח בקשת HTTP ל-API:

curl -X GET "http://hello-api.endpoints.ESPv2_PROJECT_ID.cloud.goog/hello"

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

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

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

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

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

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

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

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

OpenAPI 2.0

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

  • מגדירים את השדה host כך שיפנה לדומיין שלכם במקום ל-*.cloud.goog.
  • מסירים את התג x-google-endpoints ואת שני מאפייני הצאצא שלו.

‫OpenAPI 3.x

מוסיפים את הקטע הבא למפרט OpenAPI של Endpoints:

servers:
  - url: YOUR_DOMAIN
    x-google-endpoint: {}

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

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

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

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

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

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

הסרת המשאבים

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

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

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