מדריך תפעול

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

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

איך מקבלים מפתח API

בדוגמה הבאה מוסבר איך מקבלים מפתח API שאפשר להשתמש בו כדי לאמת קריאות ל-API של שירות יעד שעוברות דרך Apigee Adapter ל-Envoy.

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

1. התחברות ל-Apigee

1. פותחים את ממשק המשתמש של Apigee בדפדפן.
2. אחרי שנכנסים לממשק המשתמש, בוחרים את אותו ארגון שבו השתמשתם כדי להגדיר את Apigee Adapter ל-Envoy.

2. יצירת מפתח

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

1. בתפריט הניווט הצדדי, בוחרים באפשרות פרסום > מפתחים.
2. לוחצים על + Developer (מפתח).
3. ממלאים את תיבת הדו-שיח כדי ליצור מפתח חדש. אתם יכולים להשתמש בכל שם מפתח או כתובת אימייל שתרצו.

3. יצירת מוצר API

פועלים לפי הדוגמה ליצירת מוצר שמופיעה בהמשך. ראו גם מידע על הגדרת מוצר API.

1. בתפריט הניווט הצדדי, בוחרים באפשרות פרסום > מוצרי API.
2. לוחצים על +יצירה.
3. ממלאים את דף הפרטים של המוצר באופן הבא. אל תלחצו על שמירה עד שתקבלו הוראה לעשות זאת.

   שדה	ערך
   שם	httpbin-product
   שם לתצוגה	httpbin product
   סביבה	your_environment מגדירים את הסביבה שבה השתמשתם כשסיפקתם את Apigee Adapter ל-Envoy באמצעות apigee-remote-service-cli.
   גישה	Private
   Quota	5 בקשות בכל דקה אפשר לקרוא גם על מוצרי API.

4. בקטע 'מאפיינים מותאמים אישית', לוחצים על +הוספת מאפיין מותאם אישית.
5. מזינים את צמד השם/ערך הבא:
   • שם: מזינים את שם המאפיין: apigee-remote-service-targets
   • ערך: מזינים את שם שירות היעד. לדוגמה: httpbin.org
6. לוחצים על OK.
7. לוחצים על Save.

4. יצירת אפליקציית מפתח

1. בתפריט הניווט הצדדי, בוחרים באפשרות פרסום > אפליקציות.
2. לוחצים על + App (הוספת אפליקציה).
3. ממלאים את דף האפליקציה למפתחים באופן הבא. אל תשמרו את הקובץ עד שתקבלו הוראה לעשות זאת.

שם	httpbin-app
שם לתצוגה	httpbin app
מפתח	בוחרים את המפתח שיצרתם קודם או בוחרים מפתח אחר מהרשימה.

4. בקטע Credentials (פרטי כניסה), לוחצים על + Add product (הוספת מוצר) ובוחרים את המוצר שהגדרתם זה עתה: httpbin-product.
5. לוחצים על יצירה.
6. בקטע Credentials (פרטי כניסה), לוחצים על Show (הצגה) לצד Key (מפתח).
7. מעתיקים את הערך של מפתח הצרכן. הערך הזה הוא מפתח ה-API שבו תשתמשו כדי לבצע קריאות ל-API של שירות httpbin.

מידע על מוצרי API

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

הגדרת מוצר API

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

• יעד
• נתיב הבקשה
• מכסה
• היקפי ההרשאות של OAuth

יעדים של שירותים מרוחקים

הגדרת מוצר ה-API תחול על בקשה אם הבקשה תואמת גם לטירגוט (לדוגמה, httpbin.org) וגם לנתיב הבקשה (לדוגמה, /httpbin). רשימה של יעדים פוטנציאליים מאוחסנת כמאפיין במוצר ה-API.

כברירת מחדל, Apigee Remote Service בודק את הכותרת המיוחדת :authority (host) של Envoy מול רשימת היעדים שלו, אבל אפשר להגדיר אותו כך שישתמש בכותרות אחרות.

נתיב משאב ב-API

הנתיב שהוזן תואם לפי הכללים הבאים:

• לוכסן יחיד (/) לבדו תואם לכל נתיב.
• הערך * תקף בכל מקום ומתאים בתוך פלח (בין לוכסנים).
• ההגבלה ** תקינה בסוף, והיא תואמת לכל דבר עד סוף השורה.

מכסה

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

תרחישים לדוגמה לשימוש במכסות

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

המכסה מוגדרת במוצר API

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

>

מפתחות API ממופים למוצרי API, ולכן בכל פעם שמפתח API מאומת, אפשר להפחית את הערך של מונה המכסה המתאים (אם מוגדרת מכסה במוצר המשויך).

בניגוד לזמן הריצה של Apigee, מכסת השימוש שמוזנת בהגדרת המוצר נאכפת באופן אוטומטי על ידי Apigee Remote Service. אם הבקשה תאושר, היא תיספר במסגרת המכסה המותרת.

איפה המכסות מתעדכנות

התהליך Remote Service שומר על המכסות ובודק אותן באופן מקומי, ומעדכן אותן באופן אסינכרוני ב-Apigee Runtime. המשמעות היא שהמכסות לא מדויקות, ויש סיכוי לחריגה אם יש יותר משירות מרוחק אחד ששומר על המכסה. אם החיבור ל-Apigee Runtime מופרע, המכסה המקומית תמשיך לפעול כמכסה עצמאית עד שהחיבור ל-Apigee Runtime יתחדש.

היקפי OAuth

אם אתם משתמשים באסימוני JWT, אתם יכולים להגביל את האסימונים לקבוצות משנה של היקפי ההרשאות המותרים של OAuth. ההיקפים שהוקצו לאסימון JWT שהונפק ייבדקו מול ההיקפים של מוצר ה-API.

מידע על אפליקציות למפתחים

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

שימוש באימות מבוסס-JWT

אתם יכולים להשתמש באסימון JWT כדי לבצע קריאות מאומתות ל-proxy ל-API במקום להשתמש במפתח API. בקטע הזה מוסבר איך להשתמש בפקודה apigee-remote-service-cli token כדי ליצור אסימוני JWT, לבדוק אותם ולבצע רוטציה שלהם. בסביבה היברידית של Apigee, אפשר להשתמש בפקודה הזו כדי ליצור סוד של Kubernetes שיכיל את אסימוני ה-JWT.

סקירה כללית

האימות וההרשאה של JWT מתבצעים על ידי Envoy באמצעות מסנן האימות של JWT.

אחרי האימות, המסנן ext-authz של Envoy שולח את כותרות הבקשה ואת ה-JWT אל apigee-remote-service-envoy. הוא משווה בין טענות ה-JWT‏ api_product_list ו-scope לבין מוצרי ה-API של Apigee כדי לאשר את הגישה ליעד של הבקשה.

יצירת טוקנים מסוג JWT ב-Apigee

אפשר ליצור אסימוני JWT של Apigee באמצעות ה-CLI:

apigee-remote-service-cli token create -c config.yaml --id $KEY --secret $SECRET

או באמצעות נקודת הקצה הסטנדרטית של אסימון OAuth. דוגמה ל-Curl:

‫

curl https://org-env.apigee.net/remote-service/token -d '{"client_id":"myclientid","client_secret":"myclientsecret","grant_type":"client_credentials"}' -H "Content-type: application/json"

הערה: הכותרת Content-type היא חובה.

שימוש בטוקן JWT

אחרי שמקבלים את האסימון, פשוט מעבירים אותו ל-Envoy בכותרת Authorization (הרשאה). דוגמה:

curl localhost:8080/httpbin/headers -i -H "Authorization:Bearer $TOKEN"

כשל בטוקן JWT

דחייה של Envoy

אם Envoy דוחה את האסימון, יכול להיות שתופיע הודעה כמו:

Jwks remote fetch is failed

אם כן, מוודאים שההגדרה של Envoy מכילה URI תקין בקטע remote_jwks, ש-Envoy יכול לגשת אליו ושהגדרתם את האישורים בצורה נכונה כשביצעתם את ההתקנה של שרת ה-Proxy של Apigee. אמורה להיות לכם אפשרות להתקשר ישירות ל-URI באמצעות קריאת GET ולקבל תגובת JSON תקינה.

דוגמה:

curl https://myorg-eval-test.apigee.net/remote-service/certs

הודעות אחרות מ-Envoy עשויות להיראות כך:

• ‫"Audiences in Jwt are not allowed" (אסור להשתמש בקהלים ב-JWT)
• ‫"Jwt issuer is not configured" (לא הוגדר מנפיק JWT)

ההודעות האלה נובעות מדרישות בהגדרות של Envoy, שאולי תצטרכו לשנות.

בדיקת טוקן

אפשר להשתמש ב-CLI כדי לבדוק את האסימון. דוגמה

apigee-remote-service-cli -c config.yaml token inspect -f path/to/file

או

apigee-remote-service-cli -c config.yaml token inspect <<< $TOKEN

ניפוי באגים

מפתח API תקין נכשל

רישום ביומן

אפשר לשנות את רמת הרישום ביומן בשירות $REMOTE_SERVICE_HOME/apigee-remote-service-envoy. כל הרישום ביומן נשלח אל stderr.

רכיב	חובה	תיאור
‫‎-l, --log-level	הדרגות האפשריות: debug, info, warn, error.	שינוי רמת הרישום ביומן. ברירת מחדל: info
‫‎-j, --json-log		פלט היומן מופק כרשומות JSON.

‫Envoy מספק רישום ביומן. מידע נוסף זמין בקישורים הבאים למסמכי התיעוד של Envoy:

• רישום ביומן של אפליקציות
• יומני גישה
• Stackdriver logging with GKE

שינוי השם של סוד המדיניות

סוד (Secret) של Kubernetes שנפרס באשכול מכיל פרטי כניסה שהמתאם צריך כדי לאמת את התקשורת עם שרת ה-proxy של השירות המרוחק. הסוד הזה דורש נקודת טעינה של נפח, שאפשר להגדיר אותה. כברירת מחדל, נקודת הטעינה היא /policy-secret. כדי לשנות את נקודת הטעינה, פועלים לפי השלבים הבאים:

1. מריצים את הפקודה הבאה:

   $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/new-mount_point_name

   לדוגמה:

   $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/my-mount-point

2. פותחים את $CLI_HOME/samples/apigee-envoy-adapter.yaml בעורך.
3. משנים את השם של נקודת הטעינה לשם החדש:

   volumeMounts:
     - mountPath: /config
       name: apigee-remote-service-envoy
       readOnly: true
     - mountPath: /opt/apigee/tls
       name: tls-volume
       readOnly: true
     - mountPath: /my-mount-point
       name: policy-secret
       readOnly: true

4. שומרים את הקובץ ומחילים אותו על Service mesh:

   kubectl apply -f $REMOTE_SERVICE_HOME/samples/apigee-envoy-adapter.yaml

שימוש בשרת proxy של רשת

אפשר להוסיף שרת proxy מסוג HTTP באמצעות משתני הסביבה HTTP_PROXY ו-HTTPS_PROXY בסביבה של הקובץ הבינארי apigee-remote-service-envoy. כשמשתמשים בהם, אפשר להשתמש גם במשתנה הסביבה NO_PROXY כדי להחריג מארחים ספציפיים משליחה דרך ה-proxy.

HTTP_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
HTTPS_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
NO_PROXY=127.0.0.1,localhost

חשוב לזכור שצריך להיות אפשר להגיע לשרת ה-proxy מ-apigee-remote-service-envoy.

מידע על מדדים וניתוח נתונים

נקודת קצה של מדדי Prometheus זמינה בכתובת :5001/metrics. אפשר להגדיר את מספר היציאה הזה. מידע על קובץ התצורה

ניתוח נתונים של Envoy

בקישורים הבאים תוכלו לקרוא מידע על השגת נתונים של ניתוח Envoy proxy:

• ממשק האדמין
• נתונים סטטיסטיים
• נתונים סטטיסטיים של אשכול

ניתוח נתונים ב-Istio

בקישורים הבאים תוכלו לקרוא מידע על השגת נתונים של ניתוח Envoy proxy:

• משימות שקשורות ליכולת התבוננות
• הגדרת טלמטריה

ניתוח נתונים של Apigee

‫Apigee Remote Service for Envoy שולח נתונים סטטיסטיים של בקשות ל-Apigee לעיבוד לצורך ניתוח. מערכת Apigee מדווחת על הבקשות האלה תחת השם של מוצר ה-API המשויך.

מידע על ניתוח נתונים ב-Apigee זמין במאמר סקירה כללית של שירותי ניתוח נתונים.