פריסת ה-API backend

בדף הזה מוסבר איך לפרוס את קוד ה-Backend של ה-API ואת Extensible Service Proxy ‏ (ESP) ב-Google Kubernetes Engine, ב-Compute Engine ובסביבה הגמישה של App Engine.

למרות ששלבי הפריסה משתנים בהתאם לפלטפורמה שמארחת את ה-API, תמיד יש שלב שבו מציינים ל-ESP את שם השירות ואפשרות להגדיר את ESP לשימוש בהגדרת השירות העדכנית של Cloud Endpoints שנפרסה. בעזרת המידע הזה, ESP יכול לקבל את הגדרות נקודות הקצה של ה-API, וכך לאפשר ל-ESP לשמש כפרוקסי לבקשות ולתשובות כדי ש-Endpoints יוכל לנהל את ה-API.

דרישות מוקדמות

כנקודת התחלה, בדף הזה מניחים שיש לכם:

הכנות לפריסה

סביבה גמישה של App Engine

הפריסה של ה-API כך שהוא ינוהל על ידי Endpoints זהה לפריסה של כל אפליקציה בסביבה הגמישה של App Engine, וכוללת שלב קטן של הגדרה (כפי שמתואר בשלבים הבאים). פועלים לפי התיעוד של App Engine כדי:

פורסים את ה-API ב-App Engine באמצעות הפקודה gcloud app deploy. הפקודה הזו יוצרת אוטומטית קובץ אימג' של קונטיינר באמצעות שירות Container Builder, ואז פורסת את קובץ האימג' הזה בסביבה הגמישה של App Engine.

לפני שמבצעים פריסה:

Compute Engine

כדי ש-Endpoints ינהל את ה-API, צריך להתקין ולהגדיר את ESP, וגם את קוד השרת של הבק-אנד עבור ה-API. צריך להתקין את Docker במכונת ה-VM של Compute Engine כדי להריץ את קובץ האימג' של Docker של ESP שזמין בחינם ב-Artifact Registry.

לפני שמבצעים פריסה:

בהמשך מפורטים השלבים שצריך לבצע לפני שמפעילים את ה-API ואת ESP ב-Compute Engine. באופן כללי, מבצעים את כל השלבים שנדרשים בדרך כלל כדי להריץ את קוד השרת לקצה העורפי ב-Compute Engine.

  1. יוצרים, מגדירים ומפעילים את המכונה הווירטואלית. ראה את התיעוד של Compute Engine.
  2. מתקינים את Docker Enterprise Edition (EE)‎ או את Docker Community Edition (CE)‎ במופע של מכונה וירטואלית. אפשר לעיין במאמר בנושא התקנת Docker.
  3. יוצרים קונטיינר Docker לקוד של שרת הקצה העורפי. לעיון במאמרי העזרה של Cloud Build
  4. מעבירים את הקונטיינר אל Artifact Registry או אל מאגר אחר.
  5. מוודאים שאפשר לבצע את הפעולות הבאות:

GKE

כשיוצרים אשכול במסוף Google Cloud , כברירת מחדל, היקפי הגישה של OAuth שמוענקים לחשבון השירות של האשכול כוללים את היקפי הגישה שנדרשים ל-Endpoints:

  • Service Control: Enabled
  • Service Management: קריאה בלבד

כשיוצרים אשכול באמצעות הפקודה gcloud container clusters create או באמצעות קובץ הגדרה של צד שלישי, צריך לוודא שמציינים את ההיקפים הבאים:

  • "https://www.googleapis.com/auth/servicecontrol"
  • "https://www.googleapis.com/auth/service.management.readonly"

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

לפני שמבצעים פריסה:

על ידי הוספת קטע קטן לקובץ מניפסט הפריסה, אפשר להפעיל את קובץ האימג' של ESP Docker באשכולות של קונטיינרים יחד עם האפליקציה בקונטיינר. בשלבים הבאים מפורט התהליך הכללי שצריך לבצע לפני שפורסים את ה-API באמצעות ESP ב-GKE. באופן כללי, מבצעים את כל השלבים שנדרשים בדרך כלל כדי להפעיל את קוד השרת העורפי ב-GKE.

  1. פורסים את האפליקציה בקונטיינר לאשכולות של קונטיינרים. השלבים הכלליים שמתוארים במסמכי GKE הם:
    1. אורזים את האפליקציה בקובץ אימג' של Docker.
    2. מעלים את התמונה למאגר.
    3. יוצרים אשכול של קונטיינרים.
    4. פורסים את האפליקציה באשכול.
    5. חשיפת האפליקציה לאינטרנט.
  2. מוודאים שאפשר לבצע את הפעולות הבאות:
    • מפעילים את השרת של ה-API.
    • שליחת בקשות ל-API.

פריסת ה-API וה-ESP

סביבה גמישה של App Engine

כדי לפרוס את ה-API ואת ESP ב-App Engine:

  1. מקבלים את שם השירות של ה-API. זה השם שציינתם בשדה host במסמך OpenAPI.
  2. עורכים את הקובץ app.yaml ומוסיפים קטע בשם endpoints_api_service עם שם השירות. אפשר להשתמש בקובץ app.yaml מ המדריך כדוגמה:
    Java
    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed
    Python
    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed
    Go
    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed
    PHP
    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
  # previously run the deploy command, you can list your existing configuration
  # ids using the 'configs list' command as follows:
  #
  #     gcloud endpoints configs list --service=YOUR-PROJECT-ID.appspot.com
  #
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed
    Ruby
    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed
    NodeJS
    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

    מחליפים את ENDPOINTS-SERVICE-NAME בשם השירות של ה-API.

    מוסיפים את משתני הסביבה וזמן הריצה בקובץ התצורה app.yaml.

    לדוגמה: 

    runtime: nodejs
env: flex
endpoints_api_service:
  name: example-project-12345.appspot.com
  rollout_strategy: managed

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

    אם האפליקציה שלכם מבוססת על מיקרו-שירותים, אתם צריכים לכלול את הקטע endpoints_api_service בכל קובץ app.yaml.

  3. שומרים את קובץ ה-app.yaml (או הקבצים).
  4. פורסים את הקוד של הקצה העורפי ואת ESP ב-App Engine: 
    gcloud app deploy

הפקודה gcloud app deploy פורסת ומגדירה את ESP בקונטיינר נפרד מסביבת App Engine הגמישה, כי הוספתם את הקטע endpoints_api_service לקובץ app.yaml. כל תעבורת הבקשות מנותבת דרך ESP, והוא מעביר בקשות ותשובות אל הקונטיינר שמריץ את קוד שרת הקצה העורפי וממנו.

אם אתם צריכים להגדיר את ESP כך שישתמש במזהה הגדרה ספציפי:

  1. בקטע endpoints_api_service בקובץ app.yaml, מוסיפים את השדה config_id ומגדירים אותו למזהה הגדרה ספציפי.
  2. מסירים את rollout_strategy: managed או מגדירים את rollout_strategy לערך fixed. האפשרות fixed מגדירה את ESP כך שישתמש בהגדרת השירות שציינתם ב-config_id.
  3. פורסים מחדש את ה-API ואת ESP: gcloud app deploy

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

כדי להסיר את מזהה ההגדרה הספציפי:

  1. מסירים את האפשרות config_id מהקובץ app.yaml.
  2. מוסיפים את האפשרות rollout_strategy: managed.
  3. מריצים את הפקודה gcloud app deploy

כשמשתמשים באפשרות rollout_strategy: managed, לא כוללים את config_id: YOUR_SERVICE_CONFIG_ID בקובץ app.yaml. אם כן, gcloud app deploy ייכשל עם השגיאה הבאה:

config_id is forbidden when rollout_strategy is set to "managed".

כשפורסים את ה-API בסביבה הגמישה של App Engine בפעם הראשונה, יכול להיות שיהיה עיכוב בזמן שמגדירים את המכונה הווירטואלית (VM) ואת התשתית האחרת. מידע נוסף זמין במאמר בנושא הבטחת פריסה מוצלחת במסמכי התיעוד של App Engine.

Compute Engine

כדי לפרוס את ה-API באמצעות ESP ב-Compute Engine עם Docker:

  1. מתחברים למופע של מכונת ה-VM. מחליפים את INSTANCE_NAME בשם של מופע המכונה הווירטואלית. 
    gcloud compute ssh INSTANCE_NAME
  2. יוצרים רשת מאגרי מידע משלכם בשם esp_net: 
    sudo docker network create --driver bridge esp_net
  3. מריצים מופע של קובץ האימג' של קוד השרת העורפי ומקשרים אותו לרשת הקונטיינרים esp_net: 
    sudo docker run \
    --detach \
    --name=YOUR_API_CONTAINER_NAME \
    --net=esp_net \
    gcr.io/YOUR_PROJECT_ID/YOUR_IMAGE:1.0
    • מחליפים את YOUR_API_CONTAINER_NAME בשם הקונטיינר.
    • מחליפים את YOUR_PROJECT_ID במזהה הפרויקט שבו השתמשתם כשדחפתם את התמונה. Google Cloud
    • מחליפים את YOUR_IMAGE בשם של קובץ האימג'.
  4. מקבלים את שם השירות של ה-API. זה השם שציינתם בשדה host במסמך OpenAPI.
  5. מריצים מופע של קובץ האימג' של ESP Docker: 
    sudo docker run \
    --name=esp \
    --detach \
    --publish=80:8080 \
    --net=esp_net \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=SERVICE_NAME \
    --rollout_strategy=managed \
    --backend=YOUR_API_CONTAINER_NAME:8080
    • מחליפים את SERVICE_NAME בשם השירות.
    • מחליפים את YOUR_API_CONTAINER_NAME בשם הקונטיינר של ה-API.

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

אם אתם צריכים להגדיר את ESP כך שישתמש במזהה הגדרה ספציפי:

  1. כוללים את האפשרות --version ומגדירים אותה למזהה הגדרה ספציפי.
  2. מסירים את האפשרות --rollout_strategy=managed או מגדירים את --rollout_strategy לערך fixed. האפשרות fixed מגדירה את ESP כך שישתמש בהגדרת השירות שציינתם ב---version.
  3. מריצים שוב את הפקודה docker run.

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

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

כדי להסיר את מזהה ההגדרה הספציפי:

  1. בדגלים של ESP עבור docker run, מסירים את האפשרות --version.
  2. מוסיפים את האפשרות --rollout_strategy=managed.
  3. מריצים את הפקודה docker run כדי להפעיל מחדש את ה-ESP.

רשימת האפשרויות המלאה שאפשר לציין כשמפעילים את ESP מופיעה במאמר אפשרויות להפעלה של ESP.

GKE

כדי לפרוס את ESP ב-GKE:

  1. מקבלים את שם השירות של ה-API (השם שציינתם בשדה host במסמך OpenAPI).
  2. פותחים את קובץ המניפסט של הפריסה (שנקרא קובץ deployment.yaml) ומוסיפים את השורות הבאות לקטע containers: 
    containers:
- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:1
  args: [
    "--http_port=8081",
    "--backend=127.0.0.1:8080",
    "--service=SERVICE_NAME",
    "--rollout_strategy=managed"
  ]

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

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

  3. מפעילים את שירות Kubernetes באמצעות הפקודה kubectl create: 
    kubectl create -f deployment.yaml

אם אתם צריכים להגדיר את ESP כך שישתמש במזהה הגדרה ספציפי:

  1. בקובץ המניפסט של הפריסה, מוסיפים את האפשרות --version ומגדירים אותה למזהה הגדרה ספציפי.
  2. מסירים את --rollout_strategy=managed או מגדירים את --rollout_strategy לערך fixed. האפשרות fixed מגדירה את ESP כך שישתמש בהגדרת השירות שציינתם ב---version.
  3. מפעילים את שירות Kubernetes: ‏ kubectl create -f deployment.yaml

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

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

כדי להסיר את מזהה ההגדרה הספציפי:

  1. מסירים את האפשרות --version מקובץ המניפסט של הפריסה.
  2. להוסיף את ה--rollout_strategy=managed.
  3. מפעילים את שירות Kubernetes: ‏ kubectl create -f deployment.yaml

רשימת האפשרויות המלאה שאפשר לציין כשמפעילים את ESP מופיעה במאמר אפשרויות להפעלה של ESP.

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

אחרי שפורסים את ESP ואת קצה העורפי של ה-API, אפשר להשתמש בכלים כמו curl או Postman כדי לשלוח בקשות ל-API. אם לא מקבלים תגובה תקינה, אפשר להיעזר במאמר פתרון בעיות שקשורות לתגובות.

אחרי ששולחים כמה בקשות, אפשר:

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

    לדף Endpoints Services


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

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

    כניסה לדף Logs Explorer

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