מדריך תפעול

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

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

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

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

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

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

2. יצירת מפתח

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

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

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

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

  1. בתפריט הניווט הצדדי, בוחרים באפשרות פרסום > מוצרי API.
  2. לוחצים על +יצירה.
  3. ממלאים את הקטע פרטי המוצר באופן הבא. בטבלה הבאה מפורטים רק שדות החובה:
    שדה ערך תיאור
    שם httpbin-product השם הייחודי של מוצר ה-API.
    שם לתצוגה httpbin product השם התיאורי שרוצים לראות בממשק המשתמש או בהקשרים אחרים של תצוגה.
    גישה Public לצורך הדוגמה הזו, האפשרות גלוי לכולם היא בחירה טובה.
  4. בקטע 'פעולות', לוחצים על +הוספת פעולה.
  5. בקטע מקור, בוחרים באפשרות שירות מרוחק.
  6. מעבירים את המתג מקור כדי לאפשר הקלדה ידנית של שם שירות מרוחק בשדה 'שירות מרוחק'.
  7. בשדה Remote Service, מזינים את השם של שירות מרוחק. זהו שירות היעד שאליו המתאם מעביר בקשות HTTP נכנסות. למטרות בדיקה, אפשר להשתמש ב-httpbin.org או ב-httpbin.default.svc.cluster.local עם Kubernetes.

    לחצן הבחירה 'שירות מרוחק' נבחר, המתג להפעלת הזנת טקסט ידנית מופעל, והשירות המרוחק httpbin.org מוזן בשדה 'שירות מרוחק'.

  8. בקטע Operation, מזינים / בשדה של הנתיב. מידע על אפשרויות הנתיב זמין במאמר הגדרת נתיבי משאבים.
  9. לוחצים על שמירה כדי לשמור את הפעולה.
  10. לוחצים על שמירה כדי לשמור את מוצר ה-API.

מידע נוסף מופיע במאמר ניהול מוצרי API.

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

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

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

שימוש באימות מבוסס-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-token/token -d '{"client_id":"myclientid","client_secret":"myclientsecret","grant_type":"client_credentials"}' -H "Content-type: application/json"

שימוש בטוקן JWT

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

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

כשל בטוקן JWT

דחייה של Envoy

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

Jwks remote fetch has failed

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

דוגמה:

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

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

  • "אסור להשתמש בקהלים ב-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 תקין נכשל

שימוש בספק זהויות משלכם

כברירת מחדל, Apigee Adapter ל-Envoy משתמש ב-remote-token proxy ל-API כספק שירותי זהויות לאימות אפליקציות לקוח ולמסירת אסימוני JWT על סמך סוג ההרשאה של פרטי לקוח ב-OAuth 2.0. אבל במקרים מסוימים, יכול להיות שלא תוכלו להשתמש בשרת ה-proxy של remote-token. אם אתם חייבים להשתמש בספק זהויות שאינו הספק שמסופק על ידי Apigee, אתם יכולים להגדיר את המתאם כך שישתמש בספק זהויות אחר. לפרטים על תרחיש השימוש הזה של ספק זהויות שאינו Apigee ועל ההגדרה הנדרשת, אפשר לעיין במאמר הזה בקהילת Apigee: Using your own Identity Provider with the Apigee Envoy Adapter (שימוש בספק זהויות משלכם עם Apigee Envoy Adapter).

רישום ביומן

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

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

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

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

סוד (Secret) של Kubernetes שנפרס באשכול מכיל פרטי כניסה שהמתאם צריך כדי לאמת את התקשורת עם שרת ה-proxy של השירות המרוחק. כדי להשתמש ב-Secret הזה צריך נקודת טעינה של נפח, שאפשר להגדיר. כברירת מחדל, נקודת הטעינה היא /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. שומרים את הקובץ ומחילים אותו על רשת השירותים: 
    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 זמין במאמר סקירה כללית של שירותי ניתוח נתונים.

תמיכה בסביבת Multi-tenant

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

כדי להגדיר תמיכה במספר סביבות, משנים את הערך של tenant:env_name ל-"*" בקובץ config.yaml. לדוגמה:

  1. פותחים את הקובץ config.yaml בכלי לעריכה.
  2. משנים את הערך של tenant.env_name ל-"*". לדוגמה: 
    apiVersion: v1
kind: ConfigMap
metadata:
  name: apigee-remote-service-envoy
  namespace: apigee
data:
  config.yaml: |
    tenant:
      remote_service_api: https://apitest.mydomain.net/remote-service
      org_name: my-org
      env_name: "*""
      allow_unverified_ssl_cert: true
    analytics:
      collection_interval: 10s
    auth:
      jwt_provider_key: https://apitest.mydomain.net/remote-token/token
  3. שומרים את הקובץ.
  4. החלת הקובץ: 
    kubectl apply -f $CLI_HOME/config.yaml

כשמגדירים מצב ריבוי סביבות, צריך גם להגדיר את Envoy כך שישלח ערך סביבה מתאים למתאם. לשם כך, מוסיפים את המטא-נתונים הבאים לקטע virtual_hosts:routes בקובץ envoy-config.yaml. לדוגמה:

  1. יוצרים את קובץ envoy-config.yaml באמצעות ה-CLI. לדוגמה: 
    $CLI_HOME/apigee-remote-service-cli samples create \
  -t envoy-1.16 -c ./config.yaml --out myconfigs
  2. פותחים את הקובץ שנוצר (השם שלו הוא envoy-config.yaml).
  3. מוסיפים את המטא-נתונים הבאים בקטע virtual_host או בקטע routes של הקובץ: 
    typed_per_filter_config:
  envoy.filters.http.ext_authz:
    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
    check_settings:
      context_extensions:
        apigee_environment: test

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

    filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          stat_prefix: ingress_http
          route_config:
            virtual_hosts:
            - name: default
              domains: "*"
              routes:
              - match: { prefix: /test }
                route:
                  cluster: httpbin
                typed_per_filter_config:
                  envoy.filters.http.ext_authz:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                    check_settings:
                      context_extensions:
                         apigee_environment: test
              - match: { prefix: /prod }
                route:
                  cluster: httpbin
                typed_per_filter_config:
                  envoy.filters.http.ext_authz:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                    check_settings:
                      context_extensions:
                         apigee_environment: prod
  4. חוזרים על השלב האחרון כדי להוסיף סביבות נוספות לפי הצורך.
  5. שומרים את הקובץ ומחילים אותו.

איסוף נתונים לדוחות בהתאמה אישית

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

כדי להשתמש בתכונה הזו:

  1. יוצרים משאב REST של כלי לאיסוף נתונים.
  2. הגדרת משתנים של איסוף נתונים באמצעות Apigee datacollectors API.
  3. אם עדיין לא עשיתם זאת, צרו את קובץ envoy-config.yaml באמצעות ה-CLI. לדוגמה: 
    $CLI_HOME/apigee-remote-service-cli samples create \
  -t envoy-1.16 -c ./config.yaml --out myconfigs
  4. פותחים את הקובץ שנוצר (השם שלו הוא envoy-config.yaml).
  5. משתמשים במסנן Envoy כדי להגדיר ערכים למשתנים המותאמים אישית במרחב השמות envoy.filters.http.apigee.datacapture. לדוגמה, אפשר להשתמש במסנן Header to Metadata או במסנן Lua. מידע נוסף על המסננים האלה זמין במאמרים בנושא Header-To-Metadata ו-Lua.

    השמות של המשתנים המותאמים אישית צריכים להיות בפורמט dc.XXXXX.

    דוגמה למסנן של כותרת למטא-נתונים: 

     - name: envoy.filters.http.header_to_metadata
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.http.header_to_metadata.v3.Config
    request_rules:
      - header: "Host"
        on_header_present:
          metadata_namespace: envoy.filters.http.apigee.datacapture
          key: dc.host  # host (without the prefix) also works
          type: STRING
        remove: false

    דוגמה לפילטר Lua: 

    - name: envoy.filters.http.lua
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
    inline_code: |
      function envoy_on_request(request_handle)
        metadata = request_handle:streamInfo():dynamicMetadata()
        metadata:set("envoy.filters.http.apigee.datacapture", "dc.test", "A test string.")
      end
  6. מוסיפים את המסנן הרצוי לקובץ. בהמשך מפורטות דוגמאות.
  7. שומרים את הקובץ ומחילים אותו.

הגדרת mTLS בין המתאם לבין זמן הריצה של Apigee

אתם יכולים לספק אישורי TLS בצד הלקוח בקטע tenant בקובץ config.yaml של המתאם כדי להשתמש ב-mTLS בין המתאם לבין זמן הריצה של Apigee. השינוי הזה חל על כל פלטפורמות Apigee הנתמכות. הוא גם מאפשר mTLS לניתוח נתונים בפלטפורמת Apigee Edge for Private Cloud. לדוגמה: 

tenant:
  tls:
    ca_file: path/ca.pem
    cert_file: path/cert.pem
    key_file: path/key.pem
    allow_unverified_ssl_cert: false