הפניה לפעולה ולהגדרה של Edge Microgateway

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

Edge Microgateway גרסה 3.1.5 ואילך

בנושא הזה נסביר איך לנהל ולהגדיר את Edge Microgateway.

יש לך אפשרות לשדרג את Microgateway של Edge אם יש לך חיבור לאינטרנט.

בחלק הזה מוסבר איך לשדרג התקנה קיימת של Edge Microgateway. אם אתה פועל ללא חיבור לאינטרנט, ראה אפשר להתקין את Edge Microgateway בלי חיבור לאינטרנט?

ב-Apigee מומלץ לבדוק את ההגדרות האישיות הקיימות עם גרסה חדשה לפני שתשדרגו את סביבת הייצור.

1. כדי לשדרג לגרסה האחרונה של Edge, מריצים את הפקודה npm הבאה מיקרו-שער:

   npm upgrade edgemicro -g

   כדי לשדרג לגרסה ספציפית של Edge Microgateway, צריך לציין את הגרסה בפקודת השדרוג. אם לא תציינו את מספר הגרסה, הגרסה העדכנית ביותר תותקן. לדוגמה, כדי לשדרג לגרסה 3.1.0, השתמשו הפקודה הבאה:

   npm upgrade edgemicro@3.1.0 -g

2. בודקים את מספר הגרסה. לדוגמה, אם התקנתם את גרסה 3.1.0:

   edgemicro --version
   current nodejs version is v12.5.0
   current edgemicro version is 3.1.0
       

3. לסיום, משדרגים לגרסה האחרונה של שרת ה-proxy edgemicro-auth:

   edgemicro upgradeauth -o $ORG -e $ENV -u $USERNAME

ביצוע שינויים בהגדרות

קובצי התצורה שחשוב להכיר:

• קובץ תצורה של המערכת המוגדר כברירת מחדל
• קובץ תצורה המוגדר כברירת מחדל למכונת Edge Microgateway חדשה שאותחלה
• קובץ תצורה דינמי למכונות פועלות

הקטע הזה עוסק בקבצים האלה ובמה שצריך לדעת כדי לשנות אותם.

הגדרות ברירת המחדל של המערכת קובץ

כשמתקינים את Edge Microgateway, ימוקם כאן קובץ תצורה של המערכת שמוגדר כברירת מחדל:

prefix/lib/node_modules/edgemicro/config/default.yaml

כאשר prefix הוא ספריית התחילית npm. ראו אם הספרייה הזו לא מוצגת, איפה מותקנת Edge Microgateway.

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

edgemicro init
edgemicro configure [params]
edgemicro start [params]

קובץ תצורה המוגדר כברירת מחדל למופעי Edge Microgateway חדשים שאותחלו

כשמריצים את edgemicro init, קובץ התצורה של המערכת (כפי שמתואר שלמעלה), default.yaml, ממוקם בספרייה ~/.edgemicro.

אם משנים את קובץ התצורה ב-~/.edgemicro, צריך להגדיר מחדש ולהפעיל מחדש Microsoft Edge Microgateway:

edgemicro stop
edgemicro configure [params]
edgemicro start [params]

דינמיות קובץ תצורה למכונות פעילות

כשמריצים את edgemicro configure [params], קובץ התצורה נוצר ב-~/.edgemicro. שם הקובץ נקרא כך קו ביטול נעילה: org-env-config.yaml, כאשר org וגם env הם השמות של הארגון והסביבה ב-Apigee Edge. אפשר להשתמש בקובץ הזה כדי להגדיר ולאחר מכן לטעון אותם מחדש ללא זמן השבתה. לדוגמה, אם אתם מוסיפים ומגדירים פלאגין, ניתן לטעון מחדש את התצורה בלי לגרום לזמן השבתה, כפי שמוסבר בהמשך.

אם Edge Microgateway פועל (אפשרות של אפס זמן השבתה):

1. טוענים מחדש את תצורת Edge Microgateway:

   edgemicro reload -o $ORG -e $ENV -k $KEY -s $SECRET

   כאשר:

   • $ORG הוא שם הארגון שלך ב-Edge (השם צריך להיות ארגון) ).
   • $ENV הוא סביבה בארגון שלך (כמו 'בדיקה' או 'מוצר').
   • $KEY הוא המפתח שהוחזר בעבר על ידי פקודת ההגדרה.
   • $SECRET הוא המפתח שהוחזר בעבר על ידי פקודת ההגדרה.

   לדוגמה

   edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \
     -s 05c14356e42ed1...4e34ab0cc824

אם נעצרת עצירה של Microsoft Edge Microgateway:

1. מפעילים מחדש את Edge Microgateway:

   edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET

   כאשר:

   • $ORG הוא שם הארגון שלך ב-Edge (השם צריך להיות ארגון) ).
   • $ENV הוא סביבה בארגון שלך (כמו 'בדיקה' או 'מוצר').
   • $KEY הוא המפתח שהוחזר בעבר על ידי פקודת ההגדרה.
   • $SECRET הוא המפתח שהוחזר בעבר על ידי פקודת ההגדרה.

   לדוגמה:

   edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \
     -s 05c1435...e34ab0cc824

הנה קובץ תצורה לדוגמה. אפשר לקרוא פרטים נוספים על הגדרות של קובצי תצורה בחומר העזר בנושא תצורת Microgateway.

edge_config:
  bootstrap: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test
  jwt_public_key: 'https://docs-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://docs-test.apigee.net/edgemicro-auth/products'
edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
headers:
  x-forwarded-for: true
  x-forwarded-host: true
  x-request-id: true
  x-response-time: true
  via: true
oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  verify_api_key_url: 'https://docs-test.apigee.net/edgemicro-auth/verifyApiKey'
analytics:
  uri: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/axpublisher/organization/docs/environment/test

הגדרה של משתני סביבה

פקודות ממשק שורת הפקודה שדורשות ערכים לארגון שלכם ב-Edge והמפתח והסוד שדרושים להפעלת Edge Microgateway אפשר משתני סביבה:

• EDGEMICRO_ORG
• EDGEMICRO_ENV
• EDGEMICRO_KEY
• EDGEMICRO_SECRET

ההגדרה של המשתנים האלה היא אופציונלית. אם מגדירים אותם, אין צורך לציין את הערכים שלהם כשמשתמשים בממשק שורת הפקודה (CLI) כדי להגדיר ולהפעיל את Edge Microgateway.

הגדרת SSL ב-Ecrogateway של Edge שרת

בסרטונים הבאים מוסבר איך להגדיר TLS ב-Apigee Edge Microgateway:

אפשר להגדיר את שרת ה-Microgateway כך שישתמש ב-SSL. לדוגמה, אם הגדרת SSL, אתה יכול יכולים לקרוא ל-API דרך Edge Microgateway באמצעות ה-"https" למשל:

https://localhost:8000/myapi

כדי להגדיר SSL בשרת Microgateway, מבצעים את השלבים הבאים:

1. יוצרים או משיגים אישור ומפתח SSL באמצעות הכלי openssl או בכל שיטה שרוצים.
2. מוסיפים את המאפיין edgemicro:ssl לקובץ התצורה של Edge Microgateway. לקבלת תמונה מלאה רשימה של אפשרויות, ראה הטבלה למטה. לדוגמה:
   

   edgemicro:
     ssl:
      key: <absolute path to the SSL key file>
      cert: <absolute path to the SSL cert file>
      passphrase: admin123 #option added in v2.2.2
      rejectUnauthorized: true #option added in v2.2.2
      requestCert: true

3. מפעילים מחדש את Edge Microgateway. פועלים לפי השלבים שמפורטים בקטע ביצוע שינויים בהגדרות האישיות בהתאם קובץ התצורה שערכתם: קובץ ברירת המחדל או קובץ התצורה של סביבת זמן הריצה.

הנה דוגמה לקטע edgemicro בקובץ התצורה, עם SSL מוגדר:

edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
  ssl:
    key: /MyHome/SSL/em-ssl-keys/server.key
    cert: /MyHome/SSL/em-ssl-keys/server.crt
    passphrase: admin123 #option added in v2.2.2
    rejectUnauthorized: true #option added in v2.2.2

רשימה של כל אפשרויות השרתים הנתמכים:

שימוש באפשרויות SSL/TLS של לקוח

אפשר להגדיר את Edge Microgateway כלקוח TLS או SSL כשמתחברים ליעד נקודות קצה (endpoints). בקובץ התצורה של Microgateway, משתמשים ברכיב היעדים כדי להגדיר SSL/TLS (אבטחת שכבת התעבורה) אפשרויות.

בדוגמה הזו מפורטות הגדרות שיחולו על כל המארחים:

edgemicro:
...
targets:
  ssl:
    client:
      key: /Users/jdoe/nodecellar/twowayssl/ssl/client.key
      cert: /Users/jdoe/nodecellar/twowayssl/ssl/ca.crt
      passphrase: admin123
      rejectUnauthorized: true

בדוגמה הזו, ההגדרות חלות רק על המארח שצוין:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    ssl:
      client:
        key: /Users/myname/twowayssl/ssl/client.key
        cert: /Users/myname/twowayssl/ssl/ca.crt
        passphrase: admin123
        rejectUnauthorized: true

לפניכם דוגמה ל-TLS:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    tls:
      client:
        pfx: /Users/myname/twowayssl/ssl/client.pfx
        passphrase: admin123
        rejectUnauthorized: true

רשימה של כל האפשרויות הנתמכות ללקוח:

התאמה אישית של שרת ה-proxy ל-Endmicro-auth

כברירת מחדל, דפדפן Edge Microgateway משתמש בשרת proxy שנפרס ב-Apigee Edge לאימות OAuth2. שרת ה-proxy הזה נפרס כשמריצים את edgemicro configure בפעם הראשונה. אפשר לשנות הגדרת ברירת המחדל של שרת ה-proxy הזה כדי להוסיף תמיכה בהצהרות מותאמות אישית לאסימון אינטרנט מסוג JSON (JWT), להגדיר תפוגת תוקף של אסימונים וליצור אסימוני רענון. אפשר לקרוא פרטים נוספים בדף edgemicro-auth ב-GitHub.

שימוש בשירות אימות בהתאמה אישית

כברירת מחדל, דפדפן Edge Microgateway משתמש בשרת proxy שנפרס ב-Apigee Edge לאימות OAuth2. שרת ה-proxy הזה נפרס כשמריצים את edgemicro configure בפעם הראשונה. כברירת מחדל, כתובת ה-URL של שרת ה-proxy מצוינת בקובץ התצורה של Edge Microgateway באופן הבא:

authUri: https://myorg-myenv.apigee.net/edgemicro-auth

אם רוצים להשתמש בשירות מותאם אישית לצורך טיפול באימות, צריך לשנות את ערך של authUri בקובץ התצורה כדי להפנות לשירות שלכם. לדוגמה, ייתכן שיש לך שירות שמשתמש ב-LDAP לאימות זהות.

ניהול קובצי יומן

הפרטים של יומני Edge Microgateway לגבי כל בקשה ותגובה. קובצי יומן מספקים מידע שימושי לניפוי באגים ופתרון בעיות.

איפה נשמרים קובצי היומן

כברירת מחדל, קובצי יומן נשמרים ב-/var/tmp.

איך משנים את יומן ברירת המחדל ספריית קבצים

הספרייה שבה מאוחסנים קובצי היומן מצוינת בהגדרות האישיות של Edge Microgateway חדש. ראו גם ביצוע הגדרות אישיות .

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

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

שליחת יומנים למסוף

אפשר להגדיר רישום ביומן כך שפרטי היומן יישלחו לפלט רגיל במקום קובץ יומן. מגדירים את הדגל to_console כ-TRUE באופן הבא:

edgemicro:
  logging:
    to_console: true

בהגדרה הזו, היומנים יישלחו לכתובת ברירת המחדל. כרגע אי אפשר לשלוח יומנים stdout ולקובץ יומן.

איך להגדיר את רמת הרישום ביומן

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

איך משנים את פרקי הזמן ביומן

אפשר להגדיר את המרווחים האלה בקובץ התצורה של Edge Microgateway. כדאי לעיין גם במאמר ביצוע שינויים בהגדרות אישיות.

המאפיינים שאפשר להגדיר הם:

• stats_log_interval: (ברירת מחדל: 60) מרווח, בשניות, כשהנתונים הסטטיסטיים נכתבת בקובץ היומן של ה-API.
• rotate_interval: (ברירת המחדל: 24) מרווח בשעות, כשקובצי היומן סובבו. לדוגמה:

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

שיטות מומלצות לתחזוקה של קובצי יומן

ככל שנתוני קובץ היומן יצטברו עם הזמן, Apigee ממליצה לאמץ את שיטות:

• מכיוון שקובצי יומן יכולים להיות גדולים למדי, חשוב לוודא שספריית קובצי היומן מספיק מקום. אפשר לעיין בקטעים הבאים: איפה נשמרים קובצי יומן ואיך לשנות את קובץ היומן שמוגדר כברירת מחדל שלנו.
• מומלץ למחוק או להעביר קובצי יומן לספריית ארכיון נפרדת לפחות פעם בשבוע.
• אם המדיניות היא למחוק יומנים, אתם יכולים להשתמש בפקודת ה-CLI edgemicro log -c כדי להסיר (לנקות) יומנים ישנים יותר.

המוסכמה למתן שמות לקובצי יומן

כל מכונה של Edge Microgateway יוצרת שלושה סוגים של קובצי יומן:

• api - רישום כל הבקשות והתשובות שעוברים דרך Edge ביומן מיקרו-שער. בקובץ הזה נרשמים גם מונהים (נתונים סטטיסטיים) ושגיאות של API.
• err – רישום כל מה שנשלח אל stderr.
• out – רישום כל מה שנשלח אל stdout.

זוהי המוסכמה למתן שמות:

edgemicro-<Host Name>-<Instance ID>-<Log Type>.log

לדוגמה:

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log
edgemicro-mymachine-local-MTQzNTg1NDMODAyMQ-err.log
edgemicro-mymachine-local-mtqzntgndmxodaymq-out.log

מידע על תוכן של קובצי יומן

נוסף בגרסה: 2.3.3

כברירת מחדל, שירות הרישום ביומן משמיט את קובץ ה-JSON של שרתי proxy, מוצרים ו-JSON שהורדתם אסימון אינטרנט (JWT). כדי ליצור פלט של האובייקטים לקובצי היומן, צריך להגדיר את DEBUG=* כשמפעילים את Edge Microgateway. לדוגמה:

DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456

התוכן של ה-API קובץ יומן

ממשק ה-API קובץ יומן שמכיל מידע מפורט על רצף הבקשות והתשובות דרך Edge Microgateway. ממשק ה-API קובצי יומן נקראים כך:

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

בכל בקשה שנשלחת ל-Edge Microgateway, מתועדים ארבעה אירועים ב-'api'. יומן file:

• בקשה נכנסת מהלקוח
• בקשה יוצאת אל היעד
• תגובה נכנסת מהיעד
• תגובה יוצאת ללקוח

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

(1) 1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
(2) 1436403888665 info treq m=GET, u=/, h=127.0.0.18080, i=0
(3) 1436403888672 info tres s=200, d=7, i=0
(4) 1436403888676 info res s=200, d=11, i=0

נבחן אותן אחת אחרי השנייה:

1. דוגמה של בקשה נכנסת מהלקוח:

1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0

• 1436403888651 – חותמת תאריך של יוניקס
• info – תלוי בהקשר. יכול להיות מידע, אזהרה או שגיאה, בהתאם לרמת היומן. יכול להיות נתונים סטטיסטיים לרשומת נתונים סטטיסטיים, להצגת אזהרה לגבי אזהרות, או לאיתור שגיאות.
• req – מזהה את האירוע. במקרה כזה, מבקשים הלקוח.
• m – פועל ה-HTTP שנעשה בו שימוש בבקשה.
• u – החלק בכתובת ה-URL שמופיע אחרי הנתיב הבסיסי.
• h – המארח ומספר היציאה שבהם Edge Microgateway הוא בהאזנה.
• r – המארח המרוחק והיציאה שממנה הלקוח מבקש נוצרה.
• i – מזהה הבקשה. כל ארבע רשומות האירועים יחלקו את המזהה הזה. כל אחד לבקשה מוקצה מזהה בקשה ייחודי. קורלציה של רשומות יומן לפי מזהה בקשה יכולה לתת תובנות חשובות לגבי זמן האחזור של היעד.
• d – משך הזמן באלפיות השנייה מאז שהבקשה התקבלה על ידי Microsoft Edge Microgateway. בדוגמה שלמעלה, התקבלה התגובה של היעד לבקשה 0. אחרי 7 אלפיות השנייה (שורה 3), והתגובה נשלחה ללקוח אחרי 4 אלפיות השנייה (שורה 4). במילים אחרות, זמן האחזור הכולל של הבקשה היה 11 אלפיות השנייה, אילו 7 אלפיות השנייה נלקחו על ידי היעד ו-4 אלפיות השנייה על ידי Edge Microgateway עצמו.

2. דוגמה לבקשה יוצאת שנשלחה אל היעד:

1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0

• 1436403888651 – חותמת תאריך של יוניקס
• info – תלוי בהקשר. יכול להיות מידע, אזהרה או שגיאה, בהתאם לרמת היומן. יכול להיות נתונים סטטיסטיים לרשומת נתונים סטטיסטיים, להצגת אזהרה לגבי אזהרות, או לאיתור שגיאות.
• treq – מזהה את האירוע. במקרה הזה, יעד הבקשה.
• m – פועל ה-HTTP שנעשה בו שימוש בבקשת היעד.
• u – החלק בכתובת ה-URL שמופיע אחרי הנתיב הבסיסי.
• h - המארח ומספר היציאה של יעד הקצה העורפי.
• i – המזהה של הרשומה ביומן. כל ארבעת האירועים ישתפו את הקישור הזה ID.

3. דוגמה של תשובה נכנסת מהיעד

1436403888672 info tres s=200, d=7, i=0

1436403888651 – חותמת תאריך של יוניקס

• info – תלוי בהקשר. יכול להיות מידע, אזהרה או שגיאה, בהתאם לרמת היומן. יכול להיות נתונים סטטיסטיים לרשומת נתונים סטטיסטיים, להצגת אזהרה לגבי אזהרות, או לאיתור שגיאות.
• tres – מזהה את האירוע. במקרה הזה, יעד תגובה.
• s – הסטטוס של תגובת ה-HTTP.
• d – משך הזמן באלפיות השנייה. הזמן שלקח לקריאה ל-API על ידי היעד.
• i – המזהה של הרשומה ביומן. כל ארבעת האירועים ישתפו את הקישור הזה ID.

4. דוגמה של תשובה יוצאת ללקוח

1436403888676 info res s=200, d=11, i=0

1436403888651 – חותמת תאריך של יוניקס

• info – תלוי בהקשר. יכול להיות מידע, אזהרה או שגיאה, בהתאם לרמת היומן. יכול להיות נתונים סטטיסטיים לרשומת נתונים סטטיסטיים, להצגת אזהרה לגבי אזהרות, או לאיתור שגיאות.
• res – מזהה את האירוע. במקרה הזה, התגובה הלקוח.
• s – הסטטוס של תגובת ה-HTTP.
• d – משך הזמן באלפיות השנייה. זהו משך הזמן הכולל באמצעות הקריאה ל-API, כולל הזמן שנדרש ל-API המטורגט והזמן שלוקח ל-Edge ה-Microgateway עצמה.
• i – המזהה של הרשומה ביומן. כל ארבעת האירועים ישתפו את הקישור הזה ID.

תזמון קובץ יומן

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

הודעות שגיאה

חלק מרשומות היומן יכילו הודעות שגיאה. כדי לעזור לזהות איפה ולמה מתרחשות השגיאות, להצגת שגיאת קצה Microgateway .

מסמך עזר בנושא תצורת Microgateway

המיקום של קובץ תצורה

מאפייני ההגדרות שמתוארים בקטע הזה נמצאים ב-Edge Microgateway קובץ תצורה. ראו גם ביצוע הגדרות אישיות .

מאפייני dge_config

ההגדרות האלה משמשות לקביעת האינטראקציה בין מכונת Edge Microgateway Apigee Edge.

• shoestrap: (ברירת מחדל: none) כתובת URL שמפנה אל Edge שירות ספציפי ל-Microgateway שפועל ב-Apigee Edge. חברת Edge Microgateway משתמשת בשירות הזה כדי לתקשר עם Apigee Edge. כתובת ה-URL הזו מוחזרת כשמריצים את הפקודה כדי ליצור את זוג מפתחות ציבורי/פרטי: edgemicro genkeys. ראה ההגדרה והגדרת Edge Microgateway לפרטים נוספים.
• jwt_public_key: (ברירת מחדל: ללא) כתובת URL שמפנה אל Edge Microgateway שרת proxy שנפרס ב-Apigee Edge. שרת ה-proxy הזה משמש כנקודת קצה לאימות עבור הנפקת אסימוני גישה חתומים ללקוחות. כתובת ה-URL הזו מוחזרת כשמריצים את הפקודה כדי לפרוס את שרת ה-proxy: edgemicro configuration. ראה ההגדרה והגדרת Edge Microgateway לפרטים נוספים.
• quotaUri: קביעת ההגדרה הזו אם רוצים לנהל את המכסות באמצעות שרת ה-proxy edgemicro-auth נפרסו בארגון שלך. אם המאפיין הזה לא מוגדר, כברירת מחדל, נקודת הקצה במכסה היא נקודת הקצה הפנימית של Edge Microgateway.

  edge_config:
    quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth
  

מאפייני dgemicro

ההגדרות האלה מגדירות את תהליך Microsoft Edge Microgateway.

• port: (ברירת מחדל: 8000) מספר היציאה שבה ה-Edge Microgateway הוא תהליך האזנה.
• max_connections: (ברירת מחדל: 1-) מציין את המספר המקסימלי של חיבורים נכנסים ש-Edge Microgateway יכולים לקבל בו-זמנית. אם המספר הזה הוא חורגת מהסטטוס הזה, מוחזר הסטטוס הבא:
  
  res.statusCode = 429; // Too many requests
  
• max_connections_hard: (ברירת מחדל: 1-) המספר המקסימלי של קישורים בו-זמנית היא בקשות ש-Edge Microgateway יכולה לקבל לפני השבתת החיבור. ההגדרה הזו נועד למנוע התקפות מניעת שירות (DoS). בדרך כלל, מגדירים אותו למספר גדול מ- max_connections.
• רישום ביומן:
  • level: (ברירת המחדל: שגיאה)
    • info - רישום כל הבקשות והתשובות שעוברות דרך מכונת Edge Microgateway.
    • אזהרה – נרשמים ביומן רק הודעות אזהרה.
    • error – רק הודעות שגיאה ביומנים.
  • dir: (ברירת מחדל: /var/tmp) הספרייה שבה קובצי היומן נמצאים .
  • stats_log_interval: (ברירת מחדל: 60) מרווח, בשניות, כשהנתונים הסטטיסטיים נכתבת בקובץ היומן של ממשק ה-API.
  • rotate_interval: (ברירת המחדל: 24) מרווח בשעות, כשקובצי היומן סובבו.

• יישומי פלאגין: יישומי פלאגין מוסיפים פונקציונליות ל-Edge Microgateway. לפרטים בנושא פיתוח יישומי פלאגין, ראו פיתוח יישומי פלאגין מותאמים אישית.

• dir: נתיב יחסי מספריית ה- ./gateway אל או נתיב מוחלט.
• sequence: רשימה של מודולים של יישומי פלאגין להוספה ל-Edge Microgateway. מכונה. המודולים יופעלו לפי הסדר שבו הם צוינו כאן.

• ניפוי באגים: הוספת ניפוי באגים מרחוק לתהליך Microgateway של Edge.
  • port: מספר היציאה להאזנה. לדוגמה, הגדרת כלי לניפוי באגים בסביבת פיתוח משולבת (IDE) כדי להאזין בשקע הזה.
  • args: ארגומנטים לתהליך ניפוי הבאגים. לדוגמה: args --nolazy
    
• config_change_poll_interval: (ברירת מחדל: 600 שניות) Edge Microgateway טוען תצורה חדשה מדי פעם ומבצע טעינה מחדש אם משהו השתנה. הקלפיות אוסף את כל השינויים שבוצעו ב-Edge (שינויים במוצרים, שרתי proxy שתומכים במיקרו-שער וכו') בתור ושינויים שבוצעו בקובץ התצורה המקומי.
  
• disable_config_poll_interval: (ברירת המחדל: false) צריך להגדיר את הערך כ- true כדי להשבית את האפשרות 'עריכת סקרים אוטומטיים'.
• request_timeout: מגדיר זמן קצוב לתפוגה לבקשות יעד. הזמן הקצוב לתפוגה מוגדר ב שניות. אם הזמן שהוקצב פג, Microsoft Edge Microgateway משיב עם קוד סטטוס 504. (נוספה) v2.4.x)
• keep_alive_timeout: הנכס הזה מאפשר להגדיר את ה-Ecrogateway של Edge. זמן קצוב לתפוגה (באלפיות שנייה). (ברירת מחדל: 5 שניות) (נוספה גרסה 3.0.6)
• headers_timeout: המאפיין הזה מגביל את משך הזמן (באלפיות השנייה) המנתח של HTTP ימתין לקבלת להשלים את כותרות ה-HTTP.

  לדוגמה:

  edgemicro:
    keep_alive_timeout: 6000
    headers_timeout: 12000

  באופן פנימי, הפרמטר מגדיר את Node.js Server.headersTimeout בבקשות. (ברירת המחדל: 5 שניות יותר מ- השעה המוגדרת עם edgemicro.keep_alive_timeout. ברירת המחדל הזו מונעת מאזני עומסים או משרתי proxy להפיל את החיבור בטעות). (נוספה גרסה 3.1.1)

• noRuleMatchAction: (מחרוזת) הפעולה שיש לנקוט (אישור או דחייה של גישה) אם כלל ההתאמה שצוין בפלאגין accesscontrol לא נפתר (לא תואם). ערכים חוקיים: ALLOW או DENY ברירת מחדל: ALLOW (נוסף: v3.1.7)
• enableAnalytics: (ברירת מחדל: true) מגדירים את המאפיין ל-false עבור מניעת השימוש בפלאגין של ניתוח נתונים מטעינה. במקרה כזה, לא יבוצעו קריאות לניתוח נתונים של Apigee Edge. אם הערך מוגדר ל-true, או כאשר המאפיין הזה לא זמין, הפלאגין של Analytics יפעל כרגיל. צפייה Edgemicro [מאפייני קצה] כדי להגדיר פרטים. (נוספה גרסה 3.1.8).

  דוגמה:

  edgemicro
    enableAnalytics=false|true

מאפייני כותרות

ההגדרות האלה קובעות איך יטופלו כותרות HTTP מסוימות.

• x-Forwarded-for: (ברירת מחדל: true) יש להגדיר ל-false כדי למנוע העברה באמצעות X לכותרות שיועברו ליעד. שימו לב שאם כותרת מובילה מסוג 'X-קדימה', שבבקשה, הערך שלו יוגדר לערך client-ip ב-Edge Analytics.
• x-Forwarded-host: (ברירת מחדל: true) מוגדר ל-false כדי למנוע כותרות של מארח x להעברה שיועברו ליעד.
• x-request-id: (ברירת מחדל: true) יש להגדיר ל-false כדי למנוע כותרות x-request-id שיועברו ליעד.
• x-response-time: (ברירת המחדל: true) יש להגדיר את הערך false כדי למנוע כותרות x-response-time שיועברו ליעד.
• via: (ברירת מחדל: true) מוגדר ל-false כדי למנוע מהכותרות להיות מועברים ליעד.

מאפייני oauth

ההגדרות האלה קובעות את האופן שבו אימות הלקוח ייאכף על ידי Edge Microgateway.

• allowNoAuthorization: (ברירת המחדל: false) אם המדיניות מוגדרת כ-True, קריאות ל-API מורשים לעבור דרך Edge Microgateway בלי כותרת הרשאה בכלל. הגדרת הערך false כדי לדרוש כותרת הרשאה (ברירת מחדל).
• allowInvalidAuthorization: (ברירת המחדל: false) אם המדיניות מוגדרת כ-True, הקריאות ל-API יהיו מורשה לעבור אם האסימון שהועבר בכותרת ההרשאה לא חוקי או שהתוקף שלו פג. הגדרה ל-false כדי לדרוש אסימונים חוקיים (ברירת מחדל).
• authorization-header: (ברירת המחדל: Authorization: Bearer) הכותרת שבה נעשה שימוש שולחים את אסימון הגישה ל-Edge Microgateway. מומלץ לשנות את ברירת המחדל במקרים שבהם היעד צריך להשתמש בכותרת Authorization למטרות אחרות.
• api-key-header: (ברירת המחדל: x-api-key) שם הכותרת או השאילתה משמש להעברת מפתח API ל-Edge Microgateway. ראו גם שימוש מפתח API.
• keep-authorization-header: (ברירת המחדל: false) אם המדיניות מוגדרת כ-True, הכותרת Authorization הבקשה מועברת ליעד (היא נשמרת).
• allowOAuthOnly – אם המדיניות מוגדרת כ-True, כל API חייב לכלול הרשאה עם אסימון גישה למוביל. מאפשרת להתיר רק את מודל האבטחה OAuth (בזמן שמירה על תאימות לאחור). (נוסף 2.4.x)
• allowAPIKeyOnly – אם המדיניות מוגדרת כ-True, כל API חייב לכלול כותרת x-api-key (או מיקום מותאם אישית) עם מפתח API.מאפשר לך להתיר רק מודל האבטחה של מפתח API (תוך שמירה על תאימות לאחור). (נוסף 2.4.x)
• gracePeriod – הפרמטר הזה עוזר למנוע שגיאות שנגרמות עקב להבדלים בין שעון המערכת לבין זמני 'לא לפני' (nbf) או 'לפי תאריך ההנפקה' (iat) שצוין באסימון ההרשאה של JWT. מגדירים את הפרמטר הזה למספר השניות כדי לאפשר של פערים כאלה. (נוסף 2.5.7)

ספציפי לפלאגין מאפיינים

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

סינון שרתי proxy

אתם יכולים לסנן את שרתי ה-proxy שתומכים ב-microgateway מכונת Edge Microgateway תעבד. כשאפליקציית Edge Microgateway מופעלת, היא מורידה את כל שרתי ה-proxy שתומכים ב-microgateway ב- הארגון שאליו הוא משויך. השתמשו בתצורה הבאה כדי להגביל את שרתי ה-proxy השער המיקרופיין יעבור עיבוד. לדוגמה, התצורה הזו מגבילה את שרתי ה-proxy שנמצאים ב-microgateway יעובד לשלוש ערכים: edgemicro_proxy-1, edgemicro_proxy-2, וגם edgemicro_proxy-3:

edgemicro:
  proxies:
  - edgemicro_proxy-1
  - edgemicro_proxy-2
  - edgemicro_proxy-3

סינון מוצרים לפי שם

משתמשים בהגדרות הבאות כדי להגביל את מספר מוצרי ה-API ש-Edge Microgateway הורדות ותהליכים. כדי לסנן מוצרים שהורדתם, צריך להוסיף את המאפיין productnamefilter פרמטר של שאילתה ל-API /products שרשום ב-Edge Microgateway *.config.yaml חדש. לדוגמה:

edge_config:
  bootstrap: >-
    https://edgemicroservices.apigee.net/edgemicro/bootstrap/organization/willwitman/environment/test
  jwt_public_key: 'https://myorg-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://myorg-test.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24'

שימו לב שיש לציין את הערך של פרמטר השאילתה בפורמט של ביטוי רגולרי להיות מקודדים לכתובות URL. לדוגמה, הביטוי הרגולרי ^[Ee]dgemicro.*$ כולל שמות כמו: "Endmicro-test-1" , "dgemicro_demo" ו-Edgemicro_New_Demo. הערך המקודד בכתובת URL, מתאים עבור בפרמטר השאילתה, הוא: %5E%5BEe%5Ddgemicro.%2A%24.

פלט ניפוי הבאגים הבא מראה שרק המוצרים המסוננים הורדו:

...
2020-05-27T03:13:50.087Z [76060] [microgateway-config network] products download from https://gsc-demo-prod.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24 returned 200 OK
...
....
....
{
   "apiProduct":[
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590549037549,
         "createdBy":"k***@g********m",
         "displayName":"test upper case in name",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590549037549,
         "lastModifiedBy":"k***@g********m",
         "name":"Edgemicro_New_Demo",
         "proxies":[
            "catchall"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590548328998,
         "createdBy":"k***@g********m",
         "displayName":"edgemicro test 1",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590548328998,
         "lastModifiedBy":"k***@g********m",
         "name":"edgemicro-test-1",
         "proxies":[
            "Lets-Encrypt-Validation-DoNotDelete"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[
            "/",
            "/**"
         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1558182193472,
         "createdBy":"m*********@g********m",
         "displayName":"Edge microgateway demo product",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1569077897465,
         "lastModifiedBy":"m*********@g********m",
         "name":"edgemicro_demo",
         "proxies":[
            "edgemicro-auth",
            "edgemicro_hello"
         ],
         "quota":"600",
         "quotaInterval":"1",
         "quotaTimeUnit":"minute",
         "scopes":[

         ]
      }
   ]
}

סינון מוצרים לפי מאפיינים מותאמים אישית

כדי לסנן מוצרים על סמך מאפיינים מותאמים אישית:

1. בממשק המשתמש של Edge, בוחרים את שרת ה-proxy edgemicro_auth בארגון או בסביבה שבו הגדרתם את Edge Microgateway.
2. בהקשה על 'פיתוח', פותחים את מדיניות JavaCallout בעורך.
3. צריך להוסיף מאפיין מותאם אישית עם המפתח products.filter.attributes, ולהפריד ביניהם בפסיקים רשימה של שמות מאפיינים. רק מוצרים שמכילים אחד או יותר מהשמות של המאפיינים המותאמים אישית יוחזר ל-Edge Microgateway.
4. אפשר להשבית את הבדיקה כדי לבדוק אם המוצר מופעל לסביבה הנוכחית באמצעות הגדרה המאפיין המותאם אישית products.filter.env.enable אל false. (ברירת המחדל היא True).
5. (ענן פרטי בלבד) אם אתם משתמשים ב-Edge לענן פרטי, צריך להגדיר את הנכס org.noncps עד true כדי לשלוף מוצרים לסביבות שאינן CPS.

לדוגמה:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
    <DisplayName>JavaCallout</DisplayName>
    <FaultRules/>
    <Properties>
        <Property name="products.filter.attributes">attrib.one, attrib.two</Property>
        <Property name="products.filter.env.enable">false</Property>
        <Property name="org.noncps">true</Property>
    </Properties>
    <ClassName>io.apigee.microgateway.javacallout.Callout</ClassName>
    <ResourceURL>java://micro-gateway-products-javacallout-2.0.0.jar</ResourceURL>
</JavaCallout>

הגדרה של תדירות דחיפה לניתוח נתונים

אפשר להשתמש בפרמטרים של ההגדרות האלה כדי לקבוע את התדירות שבה אפליקציית Edge Microgateway שולחת ניתוח נתונים ל-Apigee:

• bufferSize (אופציונלי): המספר המקסימלי של רשומות ניתוח נתונים יכול להחזיק במאגר נתונים זמני לפני שתתחילו להסיר את הרשומות הישנות ביותר. ברירת מחדל: 10,000
• batchSize (אופציונלי): הגודל המקסימלי של רשומות ב-Analytics נשלחו אל Apigee. ברירת מחדל: 500
• flushInterval (אופציונלי): מספר אלפיות השנייה בין כל ריקון של קבוצה של רשומות ניתוח שנשלחו אל Apigee. ברירת מחדל: 5,000

לדוגמה:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

אנונימיזציה של נתוני ניתוח

ההגדרות הבאות מונעות הצגה של פרטי נתיב הבקשה ב-Edge ב-Analytics. צריך להוסיף את הרכיבים הבאים לתצורת המיקרו-שער כדי לבצע אנונימיזציה של ה-URI של הבקשה ו/או נתיב הבקשה. שימו לב שה-URI מורכב משם המארח ומחלקי הנתיב של הבקשה.

analytics:
  mask_request_uri: 'string_to_mask'
  mask_request_path: 'string_to_mask'

הפרדת קריאות ל-API ב-Edge Analytics

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

edgemicro_proxyname-health

התמונה הבאה מציגה שני שרתי proxy נפרדים במרכז הבקרה של Analytics: edgemicro_hello-health ו edgemicro_mock-health:

שימוש באלה להפרדה בין נתיבים יחסיים ונתיבים מוחלטים במרכז הבקרה של Analytics כשרתי proxy נפרדים:

• relativePath (אופציונלי): מציין נתיב יחסי להפרדה בשדה מרכז הבקרה של Analytics. לדוגמה, אם מציינים את הפרמטר /healthcheck, כל הקריאות ל-API שמכילות את הנתיב /healthcheck יופיע בלוח הבקרה בתור edgemicro_proxyname-health. שימו לב שהדגל הזה מתעלם מהנתיב הבסיסי של שרת ה-proxy. כדי להפריד על סמך נתיב מלא, כולל Basepath, צריך להשתמש בדגל proxyPath.
• proxyPath (אופציונלי): מציין נתיב מלא של שרת proxy ל-API, כולל שרת ה-proxy basepath, להפרדה במרכז הבקרה של Analytics. לדוגמה, אם מציינים /mocktarget/healthcheck, כאשר /mocktarget הוא basepath של שרת ה-proxy, כל הקריאות ל-API שכוללות את הנתיב /mocktarget/healthcheck יופיעו במרכז השליטה בתור edgemicro_proxyname-health.

לדוגמה, בהגדרה הבאה, כל נתיב API שמכיל את /healthcheck יהיו מופרדות באמצעות הפלאגין של Analytics. כלומר, /foo/healthcheck וגם /foo/bar/healthcheck יהיו מופרדים בשרת proxy נפרד שנקרא edgemicro_proxyname-health במרכז הבקרה של ניתוח הנתונים.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  relativePath: /healthcheck

בהגדרה הבאה, כל API עם נתיב שרת ה-proxy /mocktarget/healthcheck יהיה מופרד בתור שרת proxy נפרד בשם edgemicro_proxyname-health במרכז הבקרה של ניתוח הנתונים.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  proxyPath: /mocktarget/healthcheck

הגדרת Edge Microgateway מאחורי חומת האש של החברה

שימוש בשרת proxy ל-HTTP לתקשורת עם Apigee Edge

נוספה בגרסה 3.1.2.

כדי להשתמש בשרת proxy ל-HTTP לתקשורת בין Edge Microgateway ו-Apigee Edge, מבצעים את הפעולות הבאות: הבאים:

1. הגדרה של משתני הסביבה HTTP_PROXY, HTTPS_PROXY וגם NO_PROXY. האלה משתנים שולטים במארחים של כל שרת Proxy של HTTP שרוצים להשתמש בו לתקשורת איתו. Apigee Edge, או המארחים שלא יכולים לטפל בתקשורת עם Apigee Edge. לדוגמה:

   export HTTP_PROXY='http://localhost:3786'
   export HTTPS_PROXY='https://localhost:3786'
   export NO_PROXY='localhost,localhost:8080'

   לתשומת ליבכם: NO_PROXY יכולה להיות רשימת דומיינים מופרדת בפסיקים של Edge Microgateway לא אמור להיות שרת proxy ל-.

   מידע נוסף על המשתנים האלה זמין בכתובת https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables.

2. מפעילים מחדש את Edge Microgateway.

שימוש בשרת proxy ל-HTTP לתקשורת יעד

נוספה בגרסה 3.1.2.

כדי להשתמש בשרת proxy ל-HTTP לתקשורת בין יעדים ב-Edge Microgateway ויעדי קצה עורפי: לבצע את הפעולות הבאות:

1. מוסיפים את התצורה הבאה לקובץ התצורה של microgateway:

   edgemicro:
     proxy:
       tunnel: true | false
       url: proxy_url
       bypass: target_host # target hosts to bypass the proxy.
       enabled: true | false

   כאשר:

   • מנהרה: (אופציונלי) אם הערך הוא True, Edge Microgateway משתמשת בשיטת HTTP CONNECT כדי ליצור מנהור HTTP. בקשות בחיבור TCP יחיד. (הכלל נכון גם אם משתני הסביבה) שמוזכר בהמשך, להגדרת שרת ה-proxy מופעלת TLS). ברירת המחדל: false
   • url: כתובת ה-URL של שרת ה-Proxy ל-HTTP.
   • עקיפה: (אופציונלי) הפרמטר הזה מציין כתובת URL של מארח יעד אחת או יותר שמופרדות בפסיקים, צריך לעקוף את ה-Proxy ל-HTTP. אם המאפיין הזה לא מוגדר, יש להשתמש ב-NO_PROXY משתנה סביבה כדי לציין אילו כתובות URL יעד צריך לעקוף.
   • enabled: אם השדה 'True' ו-proxy.url מוגדר, יש להשתמש בערך proxy.url עבור ה-Proxy ל-HTTP. אם השדה proxy.url לא מוגדר לערך True, יש להשתמש בשרתי proxy שצוינו בשרת ה-proxy של HTTP משתני הסביבה HTTP_PROXY ו-HTTPS_PROXY, כפי שמתואר שימוש בשרת proxy ל-HTTP לתקשורת עם Apigee Edge.

   לדוגמה:

   edgemicro:
     proxy:
       tunnel: true
       url: 'http://localhost:3786'
       bypass: 'localhost','localhost:8080' # target hosts to bypass the proxy.
       enabled: true

2. מפעילים מחדש את Edge Microgateway.

שימוש בתווים כלליים לחיפוש ב-Microgateway שרתי proxy

אפשר להשתמש בסימן "*" אחד או יותר תווים כלליים לחיפוש בנתיב הבסיסי של שרת proxy מסוג edgemicro_* (תומך ב-Microgateway). לדוגמה, נתיב בסיס של השירות /team/*/members מאפשר ללקוחות להתקשר https://[host]/team/blue/members וגם https://[host]/team/green/members בלי ליצור שרתי proxy חדשים ל-API כדי לתמוך בצוותים חדשים. לתשומת ליבכם: /**/ לא נתמך.

חשוב: ב-Apigee אין תמיכה בשימוש בתו כללי לחיפוש "*" בתור המרכיב הראשון של נתיב בסיס. לדוגמה, אין תמיכה בחיפוש /*/.

מפתחות JWT מסתובבים

זמן מה לאחר היצירה הראשונית של JWT, ייתכן שתצטרכו לשנות את זוג מפתחות ציבורי/פרטי שמאוחסן ב-KVM המוצפן ב-Edge. התהליך הזה של יצירת מפתח חדש נקרא רוטציית מפתחות.

איך אפליקציית Edge Microgateway משתמשת באסימוני JWT

אסימון רשת מבוסס JSON (JWT) הוא תקן אסימון המתואר ב-RFC7519. JWT מספק דרך לחתום על קבוצה של הצהרות, שמקבל את ה-JWT יכול לאמת אותו בצורה אמינה.

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

curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"

מידע על יצירת אסימוני JWT באמצעות ה-CLI זמין במאמר יצירת אסימון.

מהי רוטציית מפתחות?

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

כדי ליצור JWT, דפדפן Edge משתמש במידע שמאוחסן ב-KVM המוצפן. א' ה-KVM בשם microgateway נוצר ואכלס במפתחות כשהגדרתם בפעם הראשונה (הוגדרו) Microsoft Edge Microgateway. המפתחות ב-KVM משמשים לחתימה ולהצפנה של אסימון JWT.

מפתחות ה-KVM כוללים:

• private_key – המפתח הפרטי האחרון (העדכני ביותר) של RSA המשמש לחתימה אסימוני JWT.

• public_key – האישור האחרון (העדכני ביותר) המשמש לאימות JWTs חתומה באמצעות private_key.

• private_key_kid – מזהה המפתח הפרטי האחרון (האחרון שנוצר). מזהה המפתח הזה משויך לערך private_key ומשמש לתמיכה ברוטציית מפתחות.

• public_key1_kid – מזהה המפתח הציבורי האחרון (האחרון שנוצר). המפתח הזה הוא המשויך לערך public_key1 ומשמש לתמיכה ברוטציית מפתחות. הערך הזה זהה לילד או לילדה עם המפתח הפרטי.

• public_key1 – המפתח הציבורי האחרון (העדכני ביותר).

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

• public_key2_kid – מזהה המפתח הציבורי הישן. המפתח הזה משויך אל public_key2 ומשמש לתמיכה ברוטציית מפתחות.

• public_key2 – המפתח הציבורי הישן.

אסימוני JWT שמוצגים לאימות יאומתו באמצעות המפתח הציבורי החדש. אם המיקום האימות ייכשל, ולאחר מכן ייעשה שימוש במפתח הציבורי הישן עד שיפוג התוקף של ה-JWT (אחרי פרק הזמן של Token_expiry*, ברירת המחדל היא 30 דקות). לחשבון כך אפשר "לסובב" מפתחות מבלי לשבש באופן מיידי את תנועת ה-API.

איך לבצע רוטציית מפתחות

בקטע הזה נסביר איך לבצע רוטציית מפתחות.

1. כדי לשדרג את ה-KVM, משתמשים בפקודה edgemicro upgradekvm. לפרטים על הרצת הפקודה הזו, ראו שדרוג ה-KVM. צריך לבצע את השלב הזה פעם אחת בלבד.
2. כדי לשדרג את שרת ה-proxy edgemicro-oauth, משתמשים בפקודה edgemicro upgradeauth. לפרטים על הרצת הפקודה הזו: שדרוג של שרת ה-proxy ל-Endmicro-auth. צריך לבצע את השלב הזה פעם אחת בלבד.
3. יש להוסיף את השורה הבאה לקובץ ~/.edgemicro/org-env-config.yaml, שבו צריך כדי לציין את אותו ארגון וסביבה שהגדרתם את השימוש ב-microgateway:

   jwk_public_keys: 'https://$ORG-$ENV.apigee.net/edgemicro-auth/jwkPublicKeys'

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

   edgemicro rotatekey -o $ORG -e $ENV -k $KEY -s $SECRET

   לדוגמה:

   edgemicro rotatekey -o docs -e test \
   -k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
   -s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47
   

לאחר רוטציית המקשים, Edge מחזיר כמה מקשים ל-Edge Microgateway. הערה ב שבדוגמה הבאה, לכל מפתח יש 'ילד' ערך (מזהה מפתח). Microgateway משתמש למפתחות לאימות אסימוני הרשאה. אם אימות האסימון נכשל, המיקרו-שער בודק לבדוק אם יש מפתח ישן בערכת המפתחות ולנסות את המפתח הזה. הפורמט של המפתחות המוחזרים הם מפתח JSON אינטרנט (JWK). אפשר לקרוא על הפורמט הזה ב-RFC 7517.

{
  "keys": [
    {
      "kty": "RSA",
      "n": "nSl7R_0wKLiWi6cO3n8aOJwYGBtinq723Jgg8i7KKWTSTYoszOjgGsJf_MX4JEW1YCScwpE5o4o8ccQN09iHVTlIhk8CNiMZNPipClmRVjaL_8IWvMQp1iN66qy4ldWXzXnHfivUZZogCkBNqCz7VSC5rw2Jf57pdViULVvVDGwTgf46sYveW_6h8CAGaD0KLd3vZffxIkoJubh0yMy0mQP3aDOeIGf_akeZeZ6GzF7ltbKGd954iNTiKmdm8IKhz6Y3gLpC9iwQ-kex_j0CnO_daHl1coYxUSCIdv4ziWIeM3dmjQ5_2dEvUDIGG6_Az9hTpNgPE5J1tvrOHAmunQ",
      "e": "AQAB",
      "kid": "2"
    },
    {
      "kty": "RSA",
      "n": "8BKwzx34BMUcHwTuQtmp8LFRCMxbkKg_zsWD6eOMIUTAsORexTGJsTy7z-4aH0wJ3fT-3luAAUPLBQwGcuHo0P1JnbtPrpuYjaJKSZOeIMOnlryJCspmv-1xG4qAqQ9XaZ9C97oecuj7MMoNwuaZno5MvsY-oi5B_gqED3vIHUjaWCErd4reONyFSWn047dvpE6mwRhZbcOTkAHT8ZyKkHISzopkFg8CD-Mij12unxA3ldcTV7yaviXgxd3eFSD1_Z4L7ZRsDUukCJkJ-8qY2-GWjewzoxl-mAW9D1tLK6qAdc89yFem3JHRW6L1le3YK37-bs6b2a_AqJKsKm5bWw",
      "e": "AQAB",
      "kid": "1"
    }
  ]
}

הגדרת ערך 'לא לפני' עיכוב

בגרסאות 3.1.5 ומטה, המפתח הפרטי החדש שנוצר על ידי הפקודה rotatekey לקח באופן מיידי, ואסימונים חדשים שנוצרו נחתמו באמצעות המפתח הפרטי החדש. אבל, לפעמים המפתח הציבורי החדש היה זמין למכונות של Edge Microgateway רק כל 10 דקות (כברירת מחדל) כשבוצע רענון של תצורת ה-microgateway. בגלל פרק הזמן שחולף מחתימת האסימון ורענון מכונה של microgateway, אסימונים שנחתמו באמצעות המפתח האחרון יידחו עד כל המכונות קיבלו את המפתח הציבורי האחרון.

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

החל מגרסה 3.1.6, דגל חדש בפקודה rotatekey מאפשר לציין עיכוב כדי שהמפתח הפרטי ייכנס לתוקף, ויאפשר זמן רענון של כל מכונות ה-microgateway ולקבל את המפתח הציבורי החדש. הדגל החדש הוא --nbf, שמציין 'לא לפני'. הדגל הזה מקבל ערך של מספר שלם, שהוא מספר הדקות לעיכוב.

בדוגמה הבאה, ההשהיה מוגדרת ל-15 דקות:

edgemicro rotatekey -o docs -e test \
-k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
-s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47 \
--nbf 15

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

סינון שרתי proxy שהורדו

כברירת מחדל, אפליקציית Edge Microgateway מורידה את כל שרתי ה-Proxy בארגון Edge שלך. שמתחיל בקידומת 'dgemicro_'. אפשר לשנות את ברירת המחדל כדי להוריד שרתי proxy שהשמות שלהם תואמים לדפוס.

1. פותחים את קובץ התצורה של Edge Micro: ~/.edgemicro/org-env-config.yaml
2. מוסיפים את הרכיב proxy Template (הדפוס של שרת proxy) בקטע dge_config. לדוגמה, הדפוס הבא הורדת שרתי proxy כמו dgemicro_foo, edgemicro_fast ו-dgemicro_first.

   edge_config:
   …
   proxyPattern: edgemicro_f*

ציון מוצרים ללא שרתי proxy ל-API

ב-Apigee Edge אפשר ליצור מוצר ל-API שלא מכיל שרתי proxy ל-API. הגדרת המוצר הזו מאפשרת למפתח API שמשויך למוצר הזה לפעול עם כל שרת proxy שנפרס בארגון שלך. החל מגרסה 2.5.4, ב-Edge Microgateway יש תמיכה במוצר הזה הגדרה אישית.

ניפוי באגים ופתרון בעיות

מתבצעת התחברות לכלי לניפוי באגים

אפשר להריץ את Edge Microgateway באמצעות כלי לניפוי באגים, כמו node-inspector. האפשרות הזאת שימושית במקרים פתרון בעיות וניפוי באגים ביישומי פלאגין מותאמים אישית.

1. במצב ניפוי באגים צריך להפעיל מחדש את Edge Microgateway. כדי לעשות את זה, צריך להוסיף את DEBUG=* אל תחילת הפקודה start:

   DEBUG=* edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET

   כדי להפנות את הפלט של ניפוי הבאגים לקובץ, אפשר להשתמש בפקודה הבאה:

   export DEBUG=* nohup edgemicro start \
   -o $ORG -e $ENV -k $KEY -s $SECRET 2>&1 | tee /tmp/file.log

2. מפעילים את הכלי לניפוי באגים ומגדירים אותו להאזין למספר היציאה לתהליך ניפוי הבאגים.
3. עכשיו אפשר לעבור דרך הקוד של Edge Microgateway, להגדיר נקודות עצירה, הבעות צפייה, וכן הלאה.

תוכלו לציין דגלים רגילים של Node.js שקשורים למצב ניפוי באגים. לדוגמה, בעזרת --nolazy אפשר לנפות באגים בקוד אסינכרוני.

קובצי היומן בבדיקה

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

שימוש באבטחה של מפתחות API

מפתחות API מספקים מנגנון פשוט לאימות לקוחות ששולחים בקשות ל-Edge מיקרו-שער. כדי לקבל מפתח API אפשר להעתיק את הערך של מפתח הצרכן (שנקרא גם Client ID) ממוצר של Apigee Edge שכולל את שרת ה-proxy לאימות של Edge Microgateway.

שמירה של המפתחות במטמון

מפתחות ה-API מוחלפים באסימונים למוכ"ז, שנשמרים במטמון. אפשר להשבית שמירה במטמון על ידי הגדרה הכותרת Cache-Control: no-cache בבקשות נכנסות ל-Edge מיקרו-שער.

שימוש במפתח API

אפשר להעביר את מפתח ה-API בבקשת API כפרמטר של שאילתה או ככותרת. כברירת מחדל, שם הפרמטר של הכותרת ושל פרמטר השאילתה הם x-api-key.

דוגמה לפרמטר של שאילתה:

curl http://localhost:8000/foobar?x-api-key=JG616Gjz7xs4t0dvpvVsGdI49G34xGsz

דוגמה לכותרת:

curl http://localhost:8000/foobar -H "x-api-key:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

הגדרת השם של מפתח ה-API

כברירת מחדל, x-api-key הוא השם שמשמש גם לכותרת של מפתח ה-API וגם לפרמטר של השאילתה. אפשר לשנות את ברירת המחדל הזו בקובץ התצורה, כמו שמוסבר במאמר ביצוע שינויים בהגדרות האישיות. לדוגמה, כדי לשנות את שם ל-apiKey:

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  api-key-header: apiKey

בדוגמה הזו, גם פרמטר השאילתה וגם שם הכותרת משתנים ל-apiKey. השם x-api-key לא יפעל יותר באף אחד מהמקרים. עוד באותו הקשר ביצוע שינויים בהגדרות האישיות.

לדוגמה:

curl http://localhost:8000/foobar -H "apiKey:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

למידע נוסף על שימוש במפתחות API עם בקשות לשרת proxy, ראו Secure Edge Microgateway.

הפעלת קודי תגובה ב-upstream

כברירת מחדל, הפלאגין oauth מחזיר קודי סטטוס של שגיאה 4xx בלבד אם התשובה היא לא סטטוס 200. אפשר לשנות את ההתנהגות הזו כך שתמיד מחזירה את הקוד בדיוק 4xx או 5xx, בהתאם לשגיאה.

כדי להפעיל את התכונה הזו, צריך להוסיף את oauth.useUpstreamResponse: true להגדרות האישיות של Edge Microgateway. לדוגמה:

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  gracePeriod: 10
  useUpstreamResponse: true

שימוש באבטחת אסימון OAuth2

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

איך מקבלים אסימון גישה

בקטע הזה מוסבר איך להשתמש בשרת ה-proxy של edgemicro-auth כדי לקבל אסימון גישה.

אפשר לקבל אסימון גישה גם באמצעות הפקודה edgemicro token ב-CLI. פרטים נוספים על ה-CLI זמינים במאמר ניהול אסימונים.

API 1: שליחת פרטי כניסה כפרמטרים של גוף ההודעה

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

curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \
-d '{"grant_type": "client_credentials", "client_id": "your_client_id", \
"client_secret": "your_client_secret"}' -H "Content-Type: application/json"

API 2: שליחת פרטי כניסה בכותרת אימות בסיסי

שולחים את פרטי הכניסה של הלקוח ככותרת 'אימות בסיסי', grant_type כפרמטר של טופס. בטופס הפקודה הזה מוסבר גם RFC 6749: מסגרת ההרשאה של OAuth 2.0.

http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \
-d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"

פלט לדוגמה

{
"token": "eyJraWQiOiIxIiwidHlwIjoi",
"access_token": "eyJraWQiOiIxIiwid",
"token_type": "bearer",
"expires_in": "108000"
}

איך מקבלים אסימון רענון

כדי לקבל אסימון רענון, צריך לבצע קריאה ל-API לנקודת הקצה /token של שרת Proxy מסוג edgemicro-auth. חובה לבצע את הקריאה הזו ל-API באמצעות password סוג המענק. השלבים הבאים מפרטים את התהליך.

1. קבלת אסימון גישה ורענון עם ה-API של /token. שימו לב סוג המענק הוא password:

   curl -X POST \
     https://your_organization-your_environment.apigee.net/edgemicro-auth/token \
     -H 'Content-Type: application/json' \
     -d '{
      "client_id":"mpK6l1Bx9oE5zLdifoDbF931TDnDtLq",
      "client_secret":"bUdDcFgv3nXffnU",
      "grant_type":"password",
      "username":"mpK6lBx9RoE5LiffoDbpF931TDnDtLq",
      "password":"bUdD2FvnMsXffnU"
   }'

   ה-API מחזיר אסימון גישה ואסימון רענון. התשובה נראית דומה ל- הזה:

   {
       "token": "your-access-token",
       "access_token": "your-access-token",
       "token_type": "bearer",
       "expires_in": "108000",
       "refresh_token": "your-refresh-token",
       "refresh_token_expires_in": "431999",
       "refresh_token_issued_at": "1562087304302",
       "refresh_token_status": "approved"
   }

2. עכשיו אפשר להשתמש באסימון הרענון כדי לקבל אסימון גישה חדש באמצעות קריאה נקודת הקצה /refresh של אותו API. לדוגמה:

   curl -X POST \
     https://willwitman-test.apigee.net/edgemicro-auth/refresh \
     -H 'Content-Type: application/json' \
     -d '{
      "client_id":"mpK6l1Bx9RoE5zLifoDbpF931TDnDtLq",
      "client_secret":"bUdDc2Fv3nMXffnU",
      "grant_type":"refresh_token",
      "refresh_token":"your-refresh-token"
   }'

   ה-API מחזיר אסימון גישה חדש. התגובה נראית דומה לזו:

   {
       "token": "your-new-access-token"
       }

מעקב תמידי

לתמיד הוא כלי Node.js מפעילה מחדש באופן אוטומטי אפליקציית Node.js במקרה שהתהליך יורד או שיש שגיאה. קצה ב-Microgateway יש קובץ forever.json שאפשר להגדיר כדי לקבוע כמה פעמים פעמים ובאילו מרווחים להפעיל מחדש את Edge Microgateway. הקובץ הזה מגדיר שירות שנקרא לתמיד ניטור, שמנהל את מאז ומתמיד באופן פרוגרמטי.

הקובץ forever.json נמצא בהתקנה ברמה הבסיסית (root) של Edge Microgateway ראו איפה מותקן Edge Microgateway. לפרטים על אפשרויות ההגדרה, עיינו ב מסמכי תיעוד ומעקב תמידי.

הפקודה edgemicro forever כוללת דגלים שמאפשרים לציין את המיקום של את הקובץ forever.json (הדגל -f), ולהתחיל/להפסיק את המעקב ללא הפסקה תהליך (הדגל -a). לדוגמה:

edgemicro forever -f ~/mydir/forever.json -a start

מידע נוסף זמין בקטע מעקב תמידי בחומר העזר בנושא CLI.

ציון נקודת קצה של קובץ תצורה

אם אתם מריצים כמה מכונות של Edge Microgateway, עדיף לנהל את ההגדרות שלהן ממיקום אחד. אפשר לעשות זאת על ידי ציון נקודת קצה (endpoint) מסוג HTTP שבה Edge Micro יכול מורידים את קובץ התצורה שלו. תוכלו לציין את נקודת הקצה כשתפעילו את Edge Micro באמצעות הדגל -u.

לדוגמה:

edgemicro start -o jdoe -e test -u http://mylocalserver/mgconfig -k public_key -s secret_key

שבה נקודת הקצה mgconfig מחזירה את התוכן של קובץ התצורה. זה הקובץ שהוא ממוקם כברירת מחדל ב-~/.edgemicro ומוגדר לו לפי המוסכמה למתן שמות: org-env-config.yaml.

השבתה של אגירת הנתונים של חיבור TCP

אפשר להשתמש במאפיין ההגדרה של nodelay כדי להשבית את אגירת הנתונים עבור חיבורי TCP שמשמשים את Edge Microgateway.

כברירת מחדל בחיבורי TCP משתמשים בשדה Nagle את האלגוריתם למאגר נתונים זמני לפני שליחתם. מגדיר את nodelay ל-true, ההגדרה משביתה את ההתנהגות הזו (הנתונים יפעילו נתונים באופן מיידי בכל פעם השם socket.write() נקרא). מידע נוסף זמין גם ב-Node.js תיעוד לפרטים נוספים.

כדי להפעיל את nodelay, עורכים את קובץ התצורה של Edge Micro באופן הבא:

edgemicro:
  nodelay: true
  port: 8000
  max_connections: 1000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

הרצת Microsoft Edge Microgateway במצב נפרד

אפשר להפעיל את Edge Microgateway במצב מנותק לגמרי מכל תלות ב-Apigee Edge. התרחיש הזה, שנקרא מצב נפרד, מאפשר להריץ ולבדוק את Edge Microgateway ללא חיבור לאינטרנט.

במצב עצמאי, התכונות הבאות לא פועלות כי נדרש להן חיבור ב-Apigee Edge:

• מפתח OAuth ומפתח API
• מכסה
• ניתוח נתונים

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

הגדרת השער והפעלה שלו

כדי להריץ את Edge Microgateway במצב עצמאי:

1. יוצרים קובץ תצורה בשם הבא: $HOME/.edgemicro/$ORG-$ENV-config.yaml

   לדוגמה:

   vi $HOME/.edgemicro/foo-bar-config.yaml

2. מדביקים את הקוד הבא בקובץ:

   edgemicro:
     port: 8000
     max_connections: 1000
     config_change_poll_interval: 600
     logging:
       level: error
       dir: /var/tmp
       stats_log_interval: 60
       rotate_interval: 24
     plugins:
       sequence:
         - extauth
         - spikearrest
   headers:
     x-forwarded-for: true
     x-forwarded-host: true
     x-request-id: true
     x-response-time: true
     via: true
   extauth:
     publickey_url: https://www.googleapis.com/oauth2/v1/certs
   spikearrest:
     timeUnit: second
     allow: 10
     buffersize: 0

3. מייצאים את משתנה הסביבה הבא עם הערך '1':

   export EDGEMICRO_LOCAL=1

4. מריצים את פקודת start הבאה, שבה מספקים ערכים כדי ליצור שרת proxy מקומי:

   edgemicro start -o $ORG -e $ENV -a $LOCAL_PROXY_NAME \
     -v $LOCAL_PROXY_VERSION -t $TARGET_URL -b $BASE_PATH

   כאשר:

   • $ORG הוא ה'ארגון' שבו השתמשתם בשם קובץ התצורה.
   • $ENV הוא ה'סביבה' השם שבו השתמשתם בקובץ התצורה שם.
   • $LOCAL_PROXY_NAME הוא השם של שרת ה-proxy המקומי שייווצר. אפשר להשתמש בכל שם שתרצו.
   • $LOCAL_PROXY_VERSION הוא מספר הגרסה של שרת ה-proxy.
   • $TARGET_URL היא כתובת ה-URL של היעד של שרת ה-proxy. (היעד הוא השירות ששרת ה-Proxy קורא לו.)
   • $BASE_PATH הוא הנתיב הבסיסי של שרת ה-proxy. הערך הזה חייב להתחיל ב- קו נטוי. לנתיב בסיס ברמה הבסיסית, יש לציין רק קו נטוי לפנים; לדוגמה, "/".

   לדוגמה:

   edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /

5. בודקים את ההגדרות האישיות.

   curl http://localhost:8000/echo  { "error" : "missing_authorization" }

   מכיוון שהפלאגין extauth נמצא בקובץ foo-bar-config.yaml, מקבלים את השגיאה 'missing_authorization' שגיאה. הפלאגין הזה מאמת JWT שחייב להיכלל בהרשאה הכותרת של הקריאה ל-API. בקטע הבא תמצאו אסימון JWT שיאפשר לכם לשלוח קריאות ל-API לעבור בלי השגיאה.

דוגמה: קבלת אסימון הרשאה

בדוגמה הבאה אפשר לראות איך מקבלים JWT מנקודת הקצה (endpoint) של JWT ב-Edge Microgateway ב-Apigee Edge (edgemicro-auth/jwkPublicKeys). נקודת הקצה (endpoint) הזו נפרסת כשמבצעים הגדרה והגדרה סטנדרטיות של Edge Microgateway. כדי לקבל את ה-JWT מנקודת הקצה של Apigee, קודם צריך לבצע את ההגדרה הרגילה של Edge Microgateway, להיות מחובר לאינטרנט. כאן אנחנו משתמשים בנקודת הקצה של Apigee למטרות לדוגמה בלבד ולא נדרש. אם רוצים, אפשר להשתמש בנקודת קצה אחרת של אסימון JWT. אם תעשו זאת, תצטרכו לקבל את ה-JWT באמצעות ה-API שסופק לנקודת הקצה הזו.

בשלבים הבאים מוסבר איך לקבל אסימון באמצעות נקודת הקצה edgemicro-auth/jwkPublicKeys:

1. צריך לבצע פעולה רגילה הגדרה והגדרה של Edge Microgateway כדי לפרוס את שרת ה-proxy edgemicro-auth לארגון/לסביבה שלכם ב-Apigee Edge. אם ביצעתם את השלב הזה בעבר, אין צורך לחזור עליו.
2. אם פרסתם את Edge Microgateway ל-Apigee Cloud, אתם צריכים להיות מחוברים לאינטרנט כדי שתוכלו לקבל JWT מנקודת הקצה הזו.
3. Stop Edge Microgateway:

   edgemicro stop

4. בקובץ התצורה שיצרת קודם ($HOME/.edgemicro/org-env-config.yaml), לכוון את extauth:publickey_url לנקודת הקצה edgemicro-auth/jwkPublicKeys בארגון/בסביבה של Apigee Edge. לדוגמה:

   extauth:
     publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'

5. מפעילים מחדש את Edge Microgateway כמו קודם, עם שמות org/env שבהם השתמשתם בשם קובץ התצורה. לדוגמה:

   edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /

6. קבלת אסימון JWT מנקודת הקצה של ההרשאה. בגלל שנעשה שימוש בedgemicro-auth/jwkPublicKeys של נקודת הקצה, תוכלו להשתמש בפקודה הבאה ב-CLI:

אפשר ליצור JWT ל-Edge Microgateway באמצעות הפקודה edgemicro token או API. לדוגמה:

edgemicro token get -o your_org -e your_env \
  -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

כאשר:

• your_org הוא שם הארגון שלך ב-Apigee שעבורו הפעלת בעבר Microsoft Edge Microgateway.
• your_env היא סביבה בארגון.
• האפשרות i מציינת את מפתח הצרכן מאפליקציה למפתחים שכוללת מוצר שכולל את שרת ה-proxy edgemicro-auth.
• האפשרות s מציינת את סוד הצרכן של אפליקציית פיתוח שכוללת מוצר שכולל את שרת ה-proxy edgemicro-auth.

הפקודה הזו מבקשת מ-Apigee Edge ליצור JWT שיכול לשמש לאימות ה-API שיחות.

בדיקת התצורה הנפרדת

כדי לבדוק את ההגדרות, קוראים ל-API עם האסימון שנוסף בכותרת Authorization באופן הבא:

curl http://localhost:8000/echo -H "Authorization: Bearer your_token

דוגמה:

curl http://localhost:8000/echo -H "Authorization: Bearer eyJraWQiOiIxIiwidHlwIjo...iryF3kwcDWNv7OQ"

פלט לדוגמה:

{
   "headers":{
      "user-agent":"curl/7.54.0",
      "accept":"*/*",
      "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
      "client_received_start_timestamp":"1535134472699",
      "x-authorization-claims":"eyJhdDbiO...M1OTE5MTA1NDkifQ==",
      "target_sent_start_timestamp":"1535134472702",
      "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
      "x-forwarded-proto":"http",
      "x-forwarded-host":"localhost:8000",
      "host":"mocktarget.apigee.net",
      "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
      "via":"1.1 localhost, 1.1 google",
      "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
      "connection":"Keep-Alive"
   },
   "method":"GET",
   "url":"/",
   "body":""
}

שימוש במצב שרת proxy מקומי

במצב שרת proxy מקומי, ל-Edge Microgateway לא נדרשת שרת proxy עם בקרת גישה ל-microgateway לפרוס ב-Apigee Edge. במקום זאת, אתם מגדירים 'שרת proxy מקומי' באמצעות אספקת שם של שרת proxy מקומי, basepath וכתובת URL יעד כאשר התחלת המיקרו-שער. לאחר מכן קריאות ל-API אל ה-microgateway נשלחות ליעד כתובת ה-URL של שרת ה-proxy המקומי. בכל שאר הבחינות, מצב שרת proxy מקומי פועל בדיוק כמו הפעלה Microsoft Edge Microgateway במצב הרגיל שלו. האימות פועל באותו אופן, כמו גם עלייה חדה אכיפת מעצר ומכסה, יישומי פלאגין בהתאמה אישית ועוד.

תרחיש לדוגמה ודוגמה

מצב שרת proxy מקומי שימושי כשצריך לשייך רק שרת proxy אחד ל-Edge Microgateway מכונה. לדוגמה, אפשר להחדיר את Edge Microgateway ל-Kubernetes כשרת proxy צדדי, Microgateway ושירות, כל אחד מהם פועל בתאים בודדים, כאשר ה-microgateway מנהל את התנועה אל ומשירות הנלווית שלו. האיור הבא ממחיש את הארכיטקטורה שבה Edge Microgateway פועל כשרת proxy צדדי באשכול Kubernetes. כל מופע של microgateway מדבר רק לנקודת קצה אחת בשירות הנלווה שלו:

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

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

כדי להגדיר את Edge Microgateway לרוץ במצב שרת proxy מקומי, מבצעים את השלבים הבאים:

1. מריצים את הפקודה edgemicro init כדי להגדיר את סביבת ההגדרות המקומית באופן מדויק כמו בהגדרה טיפוסית של Edge Microgateway. עוד באותו הקשר הגדרת Edge Microgateway.
2. מריצים את edgemicro configure, כמו במצב רגיל של Edge Microgateway התהליך. לדוגמה:

   edgemicro configure -o your_org -e your_env -u your_apigee_username

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

3. ב-Apigee Edge, צריך ליצור מוצר API עם ההגדרות הנדרשות הבאות דרישות (ניתן לנהל את כל שאר ההגדרות לפי רצונך):
   • חייבים להוסיף למוצר את שרת ה-proxy Endmicro-auth. שרת ה-proxy הזה נפרסה באופן אוטומטי כשהרצת את edgemicro configure.
   • חייבים לספק נתיב משאב. ההמלצה של Apigee להוסיף את הנתיב הזה המוצר: /**. למידע נוסף, ראו הגדרת ההתנהגות של נתיב המשאב. מידע נוסף זמין בקטע יצירת API מוצרים במסמכי התיעוד של Edge.

4. ב-Apigee Edge, יוצרים מפתח. אם רוצים, אפשר להשתמש במפתח קיים משאלות. למידע נוסף, ראו הוספת מפתחים באמצעות ממשק המשתמש של ניהול Edge.

5. ב-Apigee Edge, יוצרים אפליקציה למפתחים. אתם חייבים להוסיף את מוצר ה-API שאתם שנוצר עכשיו באפליקציה. לקבלת עזרה, אפשר לעיין במאמר רישום אפליקציה ב-Edge ממשק משתמש לניהול.
6. במחשב שבו מותקנת Edge Microgateway, מייצאים את הדברים הבאים עם הערך '1'.

   export EDGEMICRO_LOCAL_PROXY=1

7. מריצים את הפקודה הבאה של start:

   edgemicro start -o your_org -e your_environment -k your_key -s your_secret \
       -a local_proxy_name -v local_proxy_version -t target_url -b base_path

   כאשר:

   • your_org הוא הארגון שלך ב-Apigee.
   • your_environment היא סביבה בארגון שלך.
   • your_key הוא המפתח שהוחזר כשרצת edgemicro configure.
   • your_secret הוא הסוד שהוחזר כשרצת edgemicro configure.
   • local_proxy_name הוא השם של שרת ה-proxy המקומי שייווצר.
   • local_proxy_version הוא מספר הגרסה של שרת ה-proxy.
   • target_url היא כתובת ה-URL של היעד של שרת ה-proxy (השירות ששרת ה-proxy שיחה).
   • base_path הוא הנתיב הבסיסי של שרת ה-proxy. הערך הזה חייב להתחיל ב- קו נטוי. לנתיב בסיס ברמה הבסיסית, יש לציין רק קו נטוי לפנים; לדוגמה, "/".

   לדוגמה:

   edgemicro start -o your_org -e test -k 7eb6aae644cbc09035a...d2eae46a6c095f \
     -s e16e7b1f5d5e24df...ec29d409a2df853163a -a proxy1 -v 1 \
     -t http://mocktarget.apigee.net -b /echo

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

אפשר לבדוק את ההגדרה של שרת ה-proxy המקומי על ידי קריאה לנקודת הקצה של שרת ה-proxy. לדוגמה, אם ציינתם נתיב basepath של /echo, אפשר לקרוא לשרת ה-Proxy באופן הבא:

curl  http://localhost:8000/echo
{
  "error" : "missing_authorization",
  "error_description" : "Missing Authorization header"
}

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

curl  http://localhost:8000/echo -H 'x-api-key:your_api_key'

לדוגמה:

curl  http://localhost:8000/echo -H "x-api-key:DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP"

פלט לדוגמה:

{
  "headers":{
    "user-agent":"curl/7.54.0",
    "accept":"*/*",
    "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
    "client_received_start_timestamp":"1535134472699",
    "x-authorization-claims":"eyJhdWQiOi...TQ0YmUtOWNlOS05YzM1OTE5MTA1NDkifQ==",
    "target_sent_start_timestamp":"1535134472702",
    "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
    "x-forwarded-proto":"http",
    "x-forwarded-host":"localhost:8000",
    "host":"mocktarget.apigee.net",
    "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
    "via":"1.1 localhost, 1.1 google",
    "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
    "connection":"Keep-Alive"
  },
  "method":"GET",
  "url":"/",
  "body":""
}

שימוש בסנכרון

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

בשלב הזה, תכונת הסנכרון נתמכת ב-Redis 5.0.x.

מה זה המסנכרן?

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

כברירת מחדל, צריך לאפשר למכונות של Edge Microgateway לתקשר עם Apigee Edge כדי לאחזר ולרענן את נתוני ההגדרות שלהם, כגון proxy ל-API והגדרות של מוצרי API. אם יש שיבושים בחיבור לאינטרנט דרך Edge, מכונות Microsoftgate ימשיכו לפעול כי נתוני התצורה העדכניים ביותר נשמרים במטמון. עם זאת, מכונות microgate חדשות אי אפשר להפעיל אותו ללא חיבור ברור. בנוסף, ייתכנו מקרים שבהם רשת שיבוש שעלול לגרום למופע אחד או יותר של microgateway לפעול עם הגדרות אישיות שאינו מסונכרן עם מופעים אחרים.

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

המסנכרן הוא מכונה שהוגדרה במיוחד של Edge Microgateway. מטרתה היחידה הוא לדגום את Apigee Edge (ניתן להגדיר את התזמון), לאחזר את נתוני התצורה לכתוב אותו במסד נתונים מקומי של Redis. מכונת הסנכרון עצמה לא יכולה לעבד שרת proxy של API . מופעים אחרים של Edge Microgateway שפועלים בצמתים שונים עלולים להיות מוגדר לאחזור נתוני תצורה ממסד הנתונים של Redis ולא מ-Apigee קצה. כי כל מכונות ה-microgateway שולפות את נתוני ההגדרה שלהן מסד הנתונים יכול להפעיל ולעבד בקשות API גם במקרה של חיבור שיבוש.

הגדרת מופע של סנכרון

מוסיפים את ההגדרות הבאות לקובץ org-env/config.yaml עבור התקנת Edge Microgateway שבה רוצים להשתמש כסנכרון:

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

לדוגמה:

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

בשלב האחרון, שומרים את קובץ התצורה ומפעילים את מכונת Edge Microgateway. השיחה תתחיל ביצוע דגימה של Apigee Edge ואחסון נתוני התצורה שהורדו במסד הנתונים של Redis.

הגדרת מכונות Edge Microgateway רגילות

כשהסנכרון פועל, אפשר להגדיר צמתים נוספים של Edge Microgateway כדי להריץ מופעים קבועים של microgateway שמעבדים תעבורת נתונים בשרת proxy ל-API. עם זאת, מגדירים את המכונות האלה כדי לקבל את נתוני ההגדרות שלהם ממסד הנתונים של Redis Apigee Edge.

צריך להוסיף את ההגדרות הבאות לכל צומת נוסף של Edge Microgateway קובץ org-env/config.yaml. חשוב לשים לב שsynchronizerMode מוגדר ל-0. המאפיין הזה מגדיר את המכונה לפעול כרגיל מכונת Edge Microgateway שמעבדת תעבורת נתונים של שרת proxy ל-API, והמכונה תקבל את נתוני התצורה שלו ממסד הנתונים של Redis.

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

לדוגמה:

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

מאפייני ההגדרות האישיות

מאפייני התצורה הבאים נוספו כדי לתמוך בשימוש בסנכרון:

הגדרה של החרגת כתובות URL מיישומי פלאגין

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

לדוגמה:

...
edgemicro:
  ...
  plugins:
    excludeUrls: '/hello,/proxy_one' # global exclude urls
    sequence:
      - oauth
      - json2xml
      - quota
json2xml:
  excludeUrls: '/hello/xml'  # plugin level exclude urls
...

בדוגמה זו, יישומי פלאגין לא יעבדו קריאות נכנסות לשרת proxy של API עם נתיבים /hello או /proxy_one. בנוסף, json2xml המערכת תדלג על יישומי הפלאגין עבור ממשקי API שהנתיב שלהם כולל /hello/xml.

הגדרת מאפייני תצורה עם ערכים של משתני סביבה

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

בדוגמה זו, המאפיין key מוחלף בערך של משתנה הסביבה TARGETS_SSL_CLIENT_KEY וכן הלאה.

targets:
  - ssl:
      client:
        key: <E>TARGETS_SSL_CLIENT_KEY</E>
        cert: <E>TARGETS_SSL_CLIENT_CERT</E>
        passphrase: <E>TARGETS_SSL_CLIENT_PASSPHRASE</E>

בדוגמה הזו, התג <n> משמש לציון ערך של מספר שלם. רק חיובי יש תמיכה במספרים שלמים.

edgemicro:
  port: <E><n>EMG_PORT</n></E>

בדוגמה זו, התג <b> משמש לציון ערך בוליאני ( כלומר נכון או לא false).

quotas:
  useRedis: <E><b>EMG_USE_REDIS</b></E>