דוגמה ל-Envoy מקורי ל-Apigee ול-Hybrid

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

בדוגמה הזו אנחנו מראים איך להשתמש ב-Apigee Adapter ל-Envoy על ידי התקנה והפעלה של Envoy באופן מקומי, ולא בתוך אוסף Kubernetes. אפשר לפעול לפי הדוגמה במסמך הזה גם בהתקנות של Apigee וגם בהתקנות של Apigee Hybrid.

קריאות ל-proxy ל-API עוברות דרך Envoy שפועל כאפליקציית נייטיב. ‫Apigee מספקת שירותי ניהול API, כמו יצירת מוצר API ואפליקציה למפתחים. ‫Envoy מתקשר עם מישור הניהול של Apigee דרך השירות המרוחק של המתאם. המתאם גם מעביר נתוני ניתוח ל-Apigee, שבה אפשר לראות אותם ב-Apigee Analytics.

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

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

בדיקת ההגדרות האישיות של gcloud

  1. בודקים שההגדרה של gcloud מוגדרת לפרויקט בענן של Google שמשויך לארגון Apigee.

    כדי להציג את ההגדרות הנוכחיות. מידע נוסף זמין במאמר בנושא gcloud config. 

    gcloud config list

    אם צריך, מגדירים את מזהה הפרויקט הנכון ב-Google Cloud באמצעות הפקודה הבאה: 

    gcloud config set project project-id
  2. צריך לאמת את הפרויקט בענן ב-Google Cloud באמצעות Google Cloud SDK‏ (gcloud). ראו גם gcloud auth login. 
    gcloud auth login

הקצאת Apigee

בשלב הזה, תשתמשו ב-CLI של שירות מרוחק כדי להקצות נכסים של Apigee Adapter ל-Envoy ל-Apigee. פקודת ההקצאה פורסת שרתי proxy של API שמשמשים לפעולות של מתאם Apigee, מגדירה אישור ב-Apigee ויוצרת פרטי כניסה שהשירות המרוחק ישתמש בהם כדי להתחבר בצורה מאובטחת מהמערכת שלכם ל-Apigee.

  1. עוברים לספרייה $CLI_HOME: 
    cd $CLI_HOME
  2. (אופציונלי) כברירת מחדל, המתאם מחפש פרטי כניסה של חשבון שירות שמוגדר כברירת מחדל בפרויקט בענן שלכם ב-Google כדי לקבל הרשאה לשלוח נתוני ניתוח ל-Apigee. אם אתם לא רוצים להשתמש בפרטי הכניסה של חשבון השירות שמוגדרים כברירת מחדל, אתם יכולים ליצור חשבון שירות ולהפנות למפתח שלו בפקודת ההקצאה. לחשבון השירות צריך להיות מוקצה התפקיד apigee.analyticsAgent. הוראות מפורטות זמינות במאמר יצירה וניהול של חשבונות שירות.
  3. יוצרים את משתני הסביבה הבאים. המשתנים האלה ישמשו כפרמטרים בסקריפט ההקצאה: 
    export ORG=organization_name
export ENV=environment_name
export RUNTIME=host_alias_url
export NAMESPACE=hybrid_runtime_namespace  ## Apigee hybrid only
export AX_SERVICE_ACCOUNT=analytics_service_account  ## Optional

    כאשר:

    משתנה תיאור
    organization_name השם של הארגון שלכם ב-Apigee.
    environment_name השם של סביבה בארגון.
    host_alias_url
    • ב-Apigee Hybrid, כתובת URL שכוללת את hostAlias למארח וירטואלי שהוגדר בתצורת ה-Hybrid.
    • ב-Apigee, שם המארח מקבוצת הסביבות שכוללת את הסביבה. אפשר למצוא קבוצות סביבה בממשק המשתמש של Apigee בקטע Admin > Environments > Groups.

      • הערה: כתובת ה-URL חייבת להתחיל ב-https://. לדוגמה: https://apitest.mydomain.net
    hybrid_runtime_namepace (Apigee Hybrid בלבד) מרחב השמות שבו רכיבי זמן הריצה של Hybrid נפרסים.

    הערה: מרחב השמות שמוגדר כברירת מחדל לפריסה היברידית הוא apigee.

    analytics_service_account (אופציונלי) הנתיב לקובץ JSON של מפתח חשבון שירות ב-Google Cloud עם התפקיד Apigee Analytics Agent. תיאור מפורט של הפרמטר הזה מופיע במאמר בנושא פקודת הקצאה.
  4. אם אינכם הבעלים של פרויקט בענן של Google שמשויך לארגון Apigee, ודאו שחשבון המשתמש שלכם ב-Google Cloud כולל את התפקיד אדמין של ארגון Apigee, או את התפקידים יוצר API ופריסה. במאמר הענקה, שינוי וביטול גישה למשאבים מוסבר איך נותנים לחשבונות משתמשים תפקידים, משנים אותם או מבטלים את הגישה אליהם.
  5. מקבלים טוקן גישה: 
    TOKEN=$(gcloud auth print-access-token);echo $TOKEN
  6. הקצאת שרת proxy של שירות מרוחק ל-Apigee. הפלט של הפקודה מועבר לקובץ תצורה שבו תשתמשו בשלב מאוחר יותר.

    אם לא משדרגים, משתמשים בפקודה הזו כדי להקצות את Apigee. אם אתם מקצים הרשאות ל-Apigee hybrid, הקפידו להוסיף את הפרמטר --namespace $NAMESPACE: 

    ./apigee-remote-service-cli provision --organization $ORG --environment $ENV \
     --runtime $RUNTIME --analytics-sa $AX_SERVICE_ACCOUNT --token $TOKEN > config.yaml

    אם אתם משדרגים, משתמשים בפקודה הזו עם הדגל --force-proxy-install כדי להקצות את Apigee. אם אתם מקצים הרשאות ל-Apigee hybrid, הקפידו להוסיף את הפרמטר --namespace $NAMESPACE: 

    ./apigee-remote-service-cli provision --force-proxy-install --organization $ORG --environment $ENV \
     --runtime $RUNTIME --analytics-sa $AX_SERVICE_ACCOUNT --token $TOKEN > config.yaml
  7. בודקים את התוכן של הקובץ config.yaml. הוא אמור להיראות בערך כך: 
    # Configuration for apigee-remote-service-envoy (platform: Google Cloud)
# generated by apigee-remote-service-cli provision on 2020-11-20 02:49:28
apiVersion: v1
kind: ConfigMap
metadata:
  name: apigee-remote-service-envoy
  namespace: apigee
data:
  config.yaml: |
    tenant:
      remote_service_api: https://apitest.mydomain.com/remote-service
      org_name: my-org
      env_name: test
    analytics:
      collection_interval: 10s
    auth:
      jwt_provider_key: https://apitest.mydomain.com/remote-service/token
---
apiVersion: v1
kind: Secret
metadata:
  name: my-org-new-test-policy-secret
  namespace: apigee
type: Opaque
data:
  remote-service.crt: eyJrZXlzIjpbeyJrdHkiOiJSU0EiLCJhbGci...
  remote-service.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURS...
  remote-service.properties: a2lkPTIwMjAtMDctMDZ...
---
apiVersion: v1
kind: Secret
metadata:
  name: my-org-new-test-analytics-secret
  namespace: apigee
type: Opaque
data:
  client_secret.json: ewogICJ0eXBlIjogInNlcnZ...
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: apigee-remote-service-envoy
  namespace: apigee
  8. אם אתם משתמשים ב-Apigee Hybrid, צריך להחיל את הגדרות השירות (הקובץ שנוצר על ידי פקודת ההקצאה) על האשכול שבו הותקן Apigee Hybrid בשלב 1: יצירת אשכול.

מריצים את apigee-remote-service-envoy

אפשר להריץ את השירות המרוחק כקובץ בינארי מקורי או ב-Docker.

הפעלת השירות באופן מקורי

מריצים את קובץ ה-binary של השירות עם קובץ התצורה שהתקבל מהפקודה להקצאת הרשאות: 

$REMOTE_SERVICE_HOME/apigee-remote-service-envoy -c config_file_path/config.yaml

הפעלת השירות ב-Docker

קובצי אימג' של Docker מתפרסמים עם תגי גרסה. לצורך ההתקנה הזו, צריך להשתמש בגרסה העדכנית. יש שלוש גרסאות של התמונה שאפשר לבחור מביניהן:

וריאציה תמונה
Google distroless google/apigee-envoy-adapter:v2.0.3
Ubuntu google/apigee-envoy-adapter:v2.0.3-ubuntu
‫Ubuntu עם Boring Crypto google/apigee-envoy-adapter:v2.0.3-boring

לדוגמה, כדי להריץ את תמונת ה-scratch עם config.yaml המקומי שזמין כ-/config.yaml באמצעות טעינת נפח, משתמשים בפקודה הזו:

docker run -v ./config.yaml:/config.yaml google/apigee-envoy-adapter:v2.0.3

יצירת קובץ תצורה לדוגמה של Envoy

יוצרים קובץ תצורה לדוגמה של Envoy באמצעות ה-CLI:

  1. חשוב לוודא שאתם נמצאים בספרייה $ENVOY_HOME.
  2. כדי להציג את תבניות ההגדרות הזמינות: 
    $CLI_HOME/apigee-remote-service-cli samples templates

  3. מריצים את הפקודה samples. במקום TEMPLATE, מזינים אחת מתבניות Envoy הנתמכות: 

    $CLI_HOME/apigee-remote-service-cli samples create --template TEMPLATE -c ./config.yaml

    הפקודה יוצרת את הקובץ ./samples/envoy-config.yaml.

מידע נוסף זמין במאמר בנושא פקודת דוגמאות.

התקנה והפעלה של שרת Proxy של Envoy

כדי להתקין ולהפעיל את Envoy proxy:

  1. מורידים קובץ בינארי של Envoy או יוצרים אותו.
  2. מריצים את Envoy באמצעות קובץ תצורה לדוגמה שיצרתם קודם לשירות httpbin.org: 
    envoy -c ./samples/envoy-config.yaml

בדיקת ההטמעה

  1. מגדירים מוצר API ומקבלים מפתח API כמו שמוסבר במאמר איך מקבלים מפתח API.
  2. שליחת קריאה לשירות httpbin ללא מפתח API: 
    curl -i http://localhost:8080/headers -H "HOST:httpbin.org"

    השירות מנוהל עכשיו על ידי Apigee, ומכיוון שלא סיפקת מפתח API, הקריאה מחזירה את השגיאה הבאה.

    curl -i http://localhost:8080/headers -H "HOST:httpbin.org"
HTTP/1.1 403 Forbidden
date: Tue, 12 May 2020 17:51:36 GMT
server: envoy
content-length: 0
x-envoy-upstream-service-time: 11
  3. מבצעים קריאה ל-API באמצעות המפתח: 
    export APIKEY=YOUR_API_KEY
curl -i http://localhost:8080/headers -H "HOST:httpbin.org" -H "x-api-key: $APIKEY"

    הקריאה צריכה להצליח עם סטטוס 200 ולהחזיר רשימה של כותרות בתגובה. לדוגמה: 

    curl -i httpbin.default.svc.cluster.local/headers -H "x-api-key: kyOTalNNLMPfOSy6rnVeclmVSL6pA2zS"
HTTP/1.1 200 OK
server: envoy
date: Tue, 12 May 2020 17:55:34 GMT
content-type: application/json
content-length: 828
access-control-allow-origin: *
access-control-allow-credentials: true
x-envoy-upstream-service-time: 301

{
  "headers": {
    "Accept": "*/*",
    "Content-Length": "0",
    "Host": "httpbin.default.svc.cluster.local",
    "User-Agent": "curl/7.70.0-DEV",
    "X-Api-Key": "kyOTalNNLMPfOSy6rneclmVSL6pA2zS",
    "X-Apigee-Accesstoken": "",
    "X-Apigee-Api": "httpbin.default.svc.cluster.local",
    "X-Apigee-Apiproducts": "httpbin",
    "X-Apigee-Application": "httpbin",
    "X-Apigee-Authorized": "true",
    "X-Apigee-Clientid": "kyOTalNNLMPfOSy6rVeclmVSL6pA2zS",
    "X-Apigee-Developeremail": "user@mydomain.com",
    "X-Apigee-Environment": "test",
    "X-Apigee-Organization": "my-org",
    "X-Apigee-Scope": "",
    "X-B3-Parentspanid": "1476f9a2329bbdfa",
    "X-B3-Sampled": "0",
    "X-B3-Spanid": "1ad5c19bfb4bc96f",
    "X-B3-Traceid": "6f329a34e8ca07811476f9a2329bbdfa"
  }
}

הסרת Apigee Envoy adapter

כדי להסיר התקנה של Apigee Envoy Adapter:

  1. בכל מקום שבו בחרתם להפעיל את מתאם Envoy (באופן מקורי או ב-Docker), הסירו אותו.
  2. מוחקים את ה-proxies‏ remote-service ו-remote-token מהסביבות שלכם ב-Apigee. מידע נוסף זמין במאמר בנושא מחיקת proxy ל-API.
  3. מסירים מוצרי API או פעולות שלא נמצאים בשימוש בתרחישי השימוש של מתאם Envoy. מידע נוסף זמין במאמר בנושא מחיקת מוצר API.

השלבים הבאים

תעבורת הנתונים של API לשירות httpbin מנוהלת עכשיו על ידי Apigee. אלה כמה תכונות שכדאי לנסות:

  • ניגשים ל-Apigee Analytics בממשק המשתמש של Edge. עוברים אל Analyze > API Metrics > API Proxy Performance.
  • אפשר לעיין באפשרויות ה-CLI במדריך העזר.