הפעלת ESP באופן מקומי או בפלטפורמה אחרת

בדף הזה מוסבר איך להגדיר ולהפעיל מכונה של Extensible Service Proxy‏ (ESP) במחשב מקומי, אצל ספק שירותי ענן אחר כמו Amazon Web Services‏ (AWS) או באשכול Kubernetes שלא נמצא ב- Google Cloud.

אפשר להריץ ESP במחשב או במכונה וירטואלית (VM) עם Linux או macOS. אין תמיכה ב-Microsoft Windows. אפשר לפרוס את האפליקציה ואת ה-ESP באותו מארח או במארחים שונים. אירוח של מופע מקומי של ESP מאפשר לכם:

  • כדאי לנסות את ESP לפני שפורסים אותו בפלטפורמת ייצור.
  • מוודאים שהגדרות האבטחה מוגדרות ופועלות כמו שצריך, ושמדדים ויומנים מופיעים בדף Endpoints > Services כמו שצריך.

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

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

  • אם אתם פורסים את קונטיינר ה-ESP באופן מקומי או במכונה וירטואלית, אתם צריכים להתקין את Docker. מידע נוסף מופיע במאמר בנושא התקנת Docker.

  • פרסתם API באופן מקומי או במארח שאפשר להגיע אליו מהמארח שבו אתם מריצים את ESP.

  • הגדרתם את Cloud Endpoints ופרסתם את ההגדרה כדי ליצור שירות מנוהל עבור ה-API.

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

אופציונלי: שימוש ב-API לדוגמה

בקטע הזה מוסבר איך להגדיר ולפרוס באופן מקומי את הגרסה של Python של getting-started for Endpoints. צריך לבצע את השלבים שבקטע הזה רק אם אין לכם API לבדיקה עם ESP.

הדוגמה של Cloud Endpoints getting-started זמינה בשפות אחרות. בדף דוגמאות ב-GitHub אפשר למצוא את getting-startedהדוגמה בשפה המועדפת עליכם. פועלים לפי ההוראות בקובץ README.md של הדוגמה כדי להריץ את הדוגמה באופן מקומי, ואז פועלים לפי ההוראות שבקטע הזה כדי להגדיר את Endpoints ולפרוס את ההגדרה של Endpoints.

הורדת תוכנה נדרשת

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

קבלת קוד לדוגמה

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

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

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

    cd python-docs-samples/endpoints/getting-started

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

  1. בספריית קוד לדוגמה, פותחים את קובץ ההגדרות openapi.yaml.

    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

  2. בשדה host, מחליפים את YOUR-PROJECT-ID במזהה הפרויקט שלכם Google Cloud .

  3. שומרים את קובץ ה-openapi.yaml.

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

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

  1. מעדכנים את ה-CLI של gcloud:

    gcloud components update

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

    gcloud auth login

    בכרטיסייה החדשה בדפדפן שנפתחת, בוחרים חשבון.

  3. מגדירים את פרויקט ברירת המחדל למזהה הפרויקט:

    gcloud config set project YOUR-PROJECT-ID

    מחליפים את YOUR-PROJECT-ID במזהה הפרויקט של הפרויקטGoogle Cloud שצוין בקובץ openapi.yaml.

  4. פריסת ההגדרה:

    gcloud endpoints services deploy openapi.yaml

‫Service Management משתמש בטקסט שציינתם בשדה host בקובץ openapi.yaml כדי ליצור שירות Endpoints חדש בשם echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog (אם הוא לא קיים), ואז מגדיר את השירות בהתאם לקובץ התצורה של OpenAPI.

במהלך היצירה וההגדרה של השירות, Service Management מציג מידע במסוף. אפשר להתעלם מהאזהרות לגבי הנתיבים בקובץ openapi.yaml שלא דורשים מפתח API. בסיום מוצלח, שורה שדומה לזו שבהמשך מציגה את מזהה הגדרות השירות ואת שם השירות בתוך סוגריים מרובעים:

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

בדוגמה שלמעלה, 2017-02-13r0 הוא מזהה הגדרות השירות ו-echo-api.endpoints.example-project-12345.cloud.goog הוא שם השירות.

הפעלת השרת המקומי

  1. יוצרים virtualenv, מפעילים אותו ומתקינים את יחסי התלות של האפליקציה.

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

  2. מפעילים את השרת:

    python main.py

  3. פותחים חלון טרמינל נוסף ומשתמשים בפקודה curl כדי לשלוח בקשה:

    curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  http://localhost:8080/echo

    ה-API מחזיר את ההודעה ששלחתם לו, ומגיב עם:

    {
"message": "hello world"
}

יצירת חשבון שירות

כדי לספק ניהול של ה-API, גם ESP וגם ESPv2 דורשים את השירותים ב-Service Infrastructure. כדי לקרוא לשירותים האלה, ESP ו-ESPv2 צריכים להשתמש באסימוני גישה. כשפורסים את ESP או ESPv2 בסביבות כמו GKE,‏ Compute Engine או הסביבה הגמישה של App Engine,‏ ESP ו-ESPv2 מקבלים בשבילכם אסימוני גישה דרך שירות המטא-נתונים. Google Cloud Google Cloud

כשפורסים את ESP או ESPv2 בסביבה שאינהGoogle Cloud , כמו שולחן העבודה המקומי, אשכול Kubernetes מקומי או ספק אחר של שירותי ענן, צריך לספק קובץ JSON של חשבון שירות שמכיל מפתח פרטי. ‫ESP ו-ESPv2 משתמשים בחשבון שירות כדי ליצור אסימוני גישה לקריאה לשירותים שהם צריכים כדי לנהל את ה-API שלכם.

אפשר להשתמש במסוף Google Cloud או ב-Google Cloud CLI כדי ליצור את חשבון השירות ואת קובץ המפתח הפרטי:

המסוף

  1. במסוף Google Cloud , פותחים את הדף Service Accounts .

    מעבר לדף 'חשבונות שירות'

  2. לוחצים על Select a project (בחירת פרויקט).
  3. בוחרים את הפרויקט שבו נוצר ה-API ולוחצים על Open.
  4. לוחצים על + יצירת חשבון שירות.
  5. בשדה Service account name, מזינים את השם של חשבון השירות.
  6. לוחצים על יצירה.
  7. לוחצים על Continue.
  8. לוחצים על סיום.
  9. לוחצים על כתובת האימייל של חשבון השירות החדש שנוצר.
  10. לוחצים על Keys.
  11. לוחצים על Add key ואז על Create new key.

  12. לוחצים על יצירה. למחשב שלכם תתבצע הורדה של קובץ JSON עם המפתח.

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

  13. לוחצים על Close.

gcloud

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

    gcloud projects list

  2. מחליפים את PROJECT_ID בפקודה הבאה כדי להגדיר את פרויקט ברירת המחדל לפרויקט שבו נמצא ה-API:

    gcloud config set project PROJECT_ID

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

    gcloud auth login

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

  4. כדי ליצור חשבון שירות, מריצים את הפקודה הבאה ומחליפים את SERVICE_ACCOUNT_NAME ואת My Service Account בשם ובשם התצוגה שרוצים להשתמש בהם:

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
   --display-name "My Service Account"

    הפקודה מקצה כתובת אימייל לחשבון השירות בפורמט הבא:

    SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    כתובת האימייל הזו נדרשת בפקודות הבאות.

  5. יוצרים קובץ מפתח של חשבון שירות:

    gcloud iam service-accounts keys create ~/service-account-creds.json \
   --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

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

מידע נוסף על הפקודות זמין במאמר gcloud iam service-accounts.

הפעלת ESP בקונטיינר

בקטע הזה מוסבר איך פורסים את מאגר התגים של ESP. התהליך שבו משתמשים תלוי במיקום שבו פורסים את מאגר התגים של ESP:

הרצת ESP בקונטיינר Docker באופן מקומי או בפלטפורמה אחרת

  1. משנים את השם של קובץ ה-JSON שמכיל את המפתח הפרטי של חשבון השירות ל-service-account-creds.json ומעתיקים אותו אל $HOME/Downloads/ אם הוא הורד לספרייה אחרת. כך, הנתיב המלא תואם לערך של --service_account_key בפקודה docker run הבאה.

  2. בפקודה docker run הבאה, מחליפים את YOUR_SERVICE_NAME בשם השירות.

Linux

sudo docker run \
  --detach \
  --name="esp" \
  --net="host" \
  --volume=$HOME/Downloads:/esp \
  --publish=8082 \
  gcr.io/endpoints-release/endpoints-runtime:1 \
  --service=YOUR_SERVICE_NAME \
  --rollout_strategy=managed \
  --http_port=8082 \
  --backend=localhost:8080 \
  --service_account_key=/esp/service-account-creds.json

mac OS

האפשרות Docker --net="host" לא פועלת ב-macOS. במקום זאת, צריך לבצע מיפוי יציאות מפורש מהמארח לקונטיינר, ולהחליף את --net="host" ב---publish 8082:8082. צריך גם להחליף את localhost בשם ה-DNS המיוחד שרלוונטי רק ל-macOS‏: docker.for.mac.localhost. מידע נוסף זמין במאמר תרחישי שימוש ופתרונות עקיפים במסמכי העזרה של Docker.

sudo docker run \
  --detach \
  --name="esp" \
  --publish=8082:8082 \
  --volume=$HOME/Downloads:/esp \
  gcr.io/endpoints-release/endpoints-runtime:1 \
  --service=YOUR_SERVICE_NAME \
  --rollout_strategy=managed \
  --http_port=8082 \
  --backend=docker.for.mac.localhost:8080 \
  --service_account_key=/esp/service-account-creds.json

פלטפורמה אחרת

sudo docker run \
  --detach \
  --name="esp" \
  --net="host" \
  --volume=$HOME/Downloads:/esp \
  --publish=8082 \
  gcr.io/endpoints-release/endpoints-runtime:1 \
  --service=YOUR_SERVICE_NAME \
  --rollout_strategy=managed \
  --http_port=8082 \
  --backend=IP_Address:PORT \
  --service_account_key=/esp/service-account-creds.json

בטבלה הבאה מפורטות האפשרויות של Docker שבהן נעשה שימוש בפקודות שלמעלה. מידע על אפשרויות ה-ESP שמשמשות בדוגמה מופיע במאמר אפשרויות הפעלה של ESP.

אפשרות תיאור
--detach אפשרות Docker הזו מפעילה את הקונטיינר במצב מנותק, כך שהוא פועל ברקע.
--name="esp" אפשרות Docker הזו מספקת שם קל לגישה עבור הקונטיינר. לדוגמה, כדי לראות את היומנים מהקונטיינר, אפשר להריץ את הפקודה docker logs esp
--net="host" אפשרות Docker הזו מציינת שקונטיינר Docker משתמש באותה הגדרת רשת כמו המחשב המארח, וכך מאפשרת לו לבצע קריאות ל-localhost במחשב המארח. האפשרות הזו לא פועלת להרצת ESP באופן מקומי ב-macOS.
--publish=8082:8082 ב-macOS, אם רוצים להריץ את ESP באופן מקומי, צריך להשתמש באפשרות הזו של Docker במקום ב---net="host" כדי לבצע מיפוי יציאות מפורש מהמארח לקונטיינר.
--volume=
$HOME/Downloads:/esp 		אפשרות Docker הזו ממפה את הספרייה המקומית $HOME/Downloads לספרייה /esp בקונטיינר. המיפוי הזה משמש לאפשרות --service_account_key ESP.

הפעלת ESP בקונטיינר באשכול Kubernetes

בקטע הזה מוסבר איך פורסים את ESP באשכול Kubernetes שלא נמצא ב- Google Cloud.

כדי שממשקי ה-API ינוהלו על ידי Endpoints, צריך לפרוס את קונטיינר ה-ESP לאותו פוד של Kubernetes כמו קונטיינר ה-API. קבוצת הפודים שמריצים את ESP ואת ה-API מקובצת תחת שירות Kubernetes באמצעות בורר תוויות, כמו app: my-api. שירות Kubernetes מציין את מדיניות הגישה כדי לבצע איזון עומסים של בקשות הלקוח ליציאת ה-proxy.

  1. משנים את השם של קובץ ה-JSON שמכיל את המפתח הפרטי של חשבון השירות ל-service-account-creds.json ומעתיקים אותו אל $HOME/Downloads/ אם הוא הורד לספרייה אחרת. כך, הנתיב המלא תואם לפקודה בשלב הבא.

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

    kubectl create secret generic service-account-creds \
  --from-file=$HOME/Downloads/service-account-creds.json

    אם הפעולה בוצעה בהצלחה, תוצג ההודעה הבאה: secret "service-account-creds" created

  3. בקובץ התצורה של Kubernetes, מוסיפים את השורות הבאות, ומחליפים את YOUR_APP_NAME בשם ה-API ואת YOUR_SERVICE_NAME בשם השירות.

    spec:
replicas: 1
template:
  metadata:
    labels:
      app: "YOUR_APP_NAME"
  spec:
    volumes:
      - name: service-account-creds
        secret:
          secretName: service-account-creds
          containers:
      - name: esp
        image: gcr.io/endpoints-release/endpoints-runtime:1
        args: [
          "--http_port=8082",
          "--backend=127.0.0.1:8081",
          "--service=YOUR_SERVICE_NAME",
          "--rollout_strategy=managed",
          "--service_account_key=/etc/nginx/creds/service-account-creds.json"
        ]
        ports:
          - containerPort: 8080
        volumeMounts:
          - mountPath: /etc/nginx/creds
            name: service-account-creds
            readOnly: true

    מידע על אפשרויות ה-ESP שמשמשות בדוגמה מופיע במאמר אפשרויות הפעלה של ESP.

  4. פריסת ESP ל-Kubernetes. מחליפים את YOUR_CONFIGURATION_FILE בשם של קובץ התצורה של Kubernetes.

    kubectl apply -f YOUR_CONFIGURATION_FILE

שליחת בקשות

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

sudo docker logs esp

בדוגמאות הבאות מוצגות בקשות שנשלחות ל-API לדוגמה. אם אתם לא משתמשים ב-API לדוגמה, מומלץ להריץ בדיקות דומות.

הגדרתם את קונטיינר ה-ESP לקבלת בקשות ביציאה 8082. אם שולחים בקשה ישירות לשרת בכתובת http://localhost:8080, הבקשה לא עוברת דרך ESP. לדוגמה:

curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  http://localhost:8080/echo

תשובה: 

  {
    "message": "hello world"
  }

כששולחים בקשה ל-http://localhost:8082 שעוברת דרך ESP ולא שולחים מפתח API,‏ ESP דוחה את הבקשה. לדוגמה:

curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  http://localhost:8082/echo

תשובה: 

  {
   "code": 16,
   "message": "Method doesn't allow unregistered callers (callers without
    established identity). Please use API Key or other form of API consumer
    identity to call this API.",
   "details": [
    {
     "@type": "type.googleapis.com/google.rpc.DebugInfo",
     "stackEntries": [],
     "detail": "service_control"
    }
   ]
  }

כדי לבדוק את ה-API באמצעות מפתח API:

  1. יוצרים מפתח API בדף API credentials.

    לדף Credentials

  2. לוחצים על Create credentials ואז על API key.

  3. מעתיקים את המפתח ומדביקים אותו בהצהרה הבאה של משתנה הסביבה:

    export KEY=AIza...

  4. שליחת בקשה עם המפתח:

    curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  http://localhost:8082/echo?key=$KEY

    תראו תגובה שהפעולה בוצעה בהצלחה: 

    {
  "message": "hello world"
}

סידור וארגון

מכבים ומסירים את קונטיינר Docker‏ esp באמצעות הכלי docker:

    sudo docker stop esp
    sudo docker rm esp
 אם רוצים לנקות את הגדרת השירות שפרסתם, אפשר לעיין במאמר בנושא מחיקת API ומופעי API.

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