אפשרויות הפעלה של Extensible Service Proxy V2

‫OpenAPI   |  gRPC

‫Extensible Service Proxy V2‏ (ESPv2) הוא פרוקסי מבוסס Envoy שמאפשר ל-Cloud Endpoints לספק תכונות של ניהול API. כדי להגדיר את ESPv2, אפשר לציין דגלי הגדרה כשפורסים את שירות ESPv2.

הגדרת סימוני תצורה

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

מכונה וירטואלית ב-Compute Engine

ההתרעות לגבי התצורה של ESPv2 ב-Compute Engine מפורטות בפקודה docker run. לדוגמה:

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:2 \
    --service=SERVICE_NAME \
    --rollout_strategy=managed \
    --backend=YOUR_API_CONTAINER_NAME:8080

בדוגמה הזו, --service, --rollout_strategy ו---backend הם דגלי ההגדרה של ESPv2.

‫GKE ו-Kubernetes

אפשר לציין דגלי הגדרה ל-GKE ול-Kubernetes בשדה args בקובץ המניפסט של הפריסה. לדוגמה:

containers:
- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:2
  args: [
    "--listener_port=8081",
    "--backend=127.0.0.1:8080",
    "--service=SERVICE_NAME",
    "--rollout_strategy=managed"
  ]

בדוגמה הזו, --listener_port, --backend, --service ו---rollout_strategy הם דגלי התצורה של ESPv2.

Cloud Run לפלטפורמות ללא שרת

כדי לציין אפשרויות הפעלה ל-Cloud Run for serverless, משתמשים במשתנה הסביבה ESPv2_ARGS. אפשר להגדיר את המשתנה בפקודה gcloud run deploy באמצעות האפשרות --set-env-vars.

לדוגמה:

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--enable_debug

בדוגמה הזו, --enable_debug הוא דגל ההגדרה של ESPv2.

מידע נוסף על הפקודה gcloud run deploy זמין במאמרים Cloud Functions for OpenAPI,‏ Cloud Run for OpenAPI או Cloud Run for gRPC.

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

בדוגמה הבאה משתמשים ב-++ כתו מפריד:

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=^++^--cors_preset=basic++--cors_allow_origin=your_host.com

אם הדגל שאתם מגדירים מכיל פסיקים, אתם צריכים להגדיר את משתנה הסביבה ESPv2_ARGS בסקריפט gcloud_build_image.

לדוגמה, כדי להוסיף את הדגל --cors_allow_methods=PUT,POST,GET:

• מורידים את הסקריפט gcloud_build_image.
• עורכים את gcloud_build_image כמו שמוצג בהמשך:

  cat <<EOF > Dockerfile
    FROM BASE_IMAGE
  
    ENV ENDPOINTS_SERVICE_PATH /etc/endpoints/service.json
    COPY service.json \ENDPOINTS_SERVICE_PATH
  
    ENV ESPv2_ARGS ^++^--cors_preset=basic++--cors_allow_method="GET,PUT,POST"++--cors_allow_credentials
  
    ENTRYPOINT ["/env_start_proxy.py"]
    EOF

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

התרעות לגבי הגדרות ESPv2

אפשר לקבץ את דגלי ההגדרה של ESPv2 לקטגוריות הבאות:

• הגדרה ללא שרת
• Logging
• Tracing
• בדיקת אבטחה
• ניפוי באגים
• בדיקות מקומיות
• Non-Google Cloud Deployment
• שליפת כתובת ה-IP של הלקוח
• תמיכה ב-CORS
• תמיכה ב-TLS
• זמן קצוב לתפוגה וניסיונות חוזרים
• gRPC transcoding
• שינוי בקשות ותגובות
• אפשרויות אבטחה
• אימות JWT

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

הגדרה ללא שרת

חובה להשתמש בדגלים האלה כדי להריץ ESPv2 בפלטפורמות שאינן serverless, כמו GKE,‏ Compute Engine ו-Kubernetes. אי אפשר להגדיר אותם כשפורסים ב-Cloud Run לפלטפורמות ללא שרתים.

הערה: משתמשי Kubernetes, אל תקיפו את ערכי השדות במירכאות בקובצי ההגדרות. לדוגמה, --cors_allow_origin="http://example.com" יקצה את ערך המחרוזת \"http://example.com\" לשדה cor_allow_origin במקום ערך המחרוזת המיועד http://example.com.

``

דגל	תיאור
--service	מגדיר את השם של שירות Endpoints.
--version	מגדיר את מזהה תצורת השירות של שירות Endpoints.
--rollout_strategy	מציינים את אסטרטגיית ההשקה של הגדרת השירות, [fixed|managed]. ברירת המחדל היא fixed.
--listener_port	מציין את היציאה שדרכה יתקבלו חיבורים במורד הזרם. הוא תומך בחיבורים מסוג HTTP/1.x,‏ HTTP/2 ו-gRPC. ברירת המחדל היא 8080.
--backend	מציינת את הכתובת של שרת האפליקציות המקומי של העורף. הסכימות התקפות הן http,‏ https,‏ grpc ו-grpcs אם הן כלולות. סכימת ברירת המחדל היא >http.

רישום ביומן

משתמשים בדגלים האלה כדי להגדיר את ESPv2 כך שיכתוב מידע נוסף ליומן Stackdriver.

דגל	תיאור
--log_request_headers	הערכים של כותרות הבקשה שצוינו יתועדו ביומן, כשהם מופרדים בפסיקים ללא רווחים. לדוגמה, מגדירים את הדגל הזה כך: --log_request_headers=foo,bar אם הערכים של הכותרות foo ו-bar זמינים בבקשה, יופיעו ביומן של Endpoints: request_headers: foo=foo_value;bar=bar_value
--log_response_headers	הערכים של כותרות התגובה שצוינו יתועדו ביומן, כשהם מופרדים בפסיקים ללא רווחים. לדוגמה, מגדירים את הדגל הזה כך: --log_response_headers=baz,bing אם הערכים של הכותרות baz ו-bing זמינים בתגובה, היומן של Endpoints יכיל את השורות הבאות: response_headers: baz=baz_value;bing=bing_value
--log_jwt_payloads	הערכים של השדות הפרימיטיביים של מטען ה-JWT הייעודי (payload) שצוינו יתועדו ביומן, כשהם מופרדים בפסיקים ללא רווחים. לדוגמה, מגדירים את הדגל הזה כך: --log_jwt_payloads=sub,project_id,foo.foo_name אם הערכים זמינים במטען הייעודי (payload) של JWT, יומן הרישום של Endpoints יכיל: jwt_payloads: sub=sub_value;project_id=project_id_value; foo.foo_name=foo.foo_name_value הערכים במטען הייעודי (payload) של ה-JWT חייבים להיות שדות פרימיטיביים (מחרוזת, מספר שלם). אובייקטים ומערכים של JSON לא נרשמים ביומן.
--access_log	אם מציינים נתיב, זהו הנתיב לקובץ המקומי שבו ייכתבו הרשומות של יומן הגישה.
--access_log_format	פורמט מחרוזת לציון הפורמט של יומן הגישה. אם לא מגדירים את המדיניות, המערכת משתמשת במחרוזת הפורמט שמוגדרת כברירת מחדל. מידע מפורט על דקדוק הפורמט זמין במאמר בנושא הפניה למחרוזות פורמט.

סקיצה

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

דגל	תיאור
--disable_tracing	משביתים את המעקב. כברירת מחדל, המעקב מופעל. כשההגדרה הזו מופעלת, ESPv2 דוגם מספר קטן של בקשות ל-API שלכם בכל שנייה כדי לקבל עקבות שהוא שולח ל-Stackdriver Trace. כברירת מחדל, מתבצעת דגימה של בקשה אחת מתוך 1,000 בקשות. משתמשים בדגל --tracing_sample_rate כדי לשנות את קצב הדגימה.
--tracing_project_id	מזהה הפרויקט ב-Google עבור Stackdriver tracing. שירות המעקב הוא בתשלום. הפרויקט שצוין יחויב על מעקב. כברירת מחדל, החיוב מתבצע לפי מזהה הפרויקט של שירות ESPv2 שנפרס. מזהה הפרויקט נקבע על ידי קריאה לשרת המטא-נתונים של המופע בהפעלה. Google Cloud אם ESPv2 נפרס מחוץ ל- Google Cloud (באמצעות הדגל --non_gcp ), המעקב יושבת באופן אוטומטי אלא אם הדגל הזה מוגדר באופן מפורש.
--tracing_sample_rate	מגדירים את קצב הדגימה של העקבות לערך בין 0.0 ל-1.0. הערך הזה מציין את החלק היחסי של הבקשות שנדגמות. ערך ברירת המחדל הוא 0.001, ששווה ל-1 מתוך 1,000 בקשות.
--tracing_incoming_context	הדגל הזה מציין אילו כותרות HTTP צריך לבדוק כדי למצוא את הקשר של המעקב. ערכי הדגל מופרדים בפסיקים ללא רווחים. חשוב לזכור שהסדר משנה: הקשר של העקבות ייגזר מהכותרת הראשונה שתואמת. הערכים האפשריים כוללים traceparent, x-cloud-trace-context וגם grpc-trace-bin. אם לא מציינים את הכותרות, המערכת תבדוק את הכותרות traceparent ו-x-cloud-trace-context (לפי הסדר). פרטים נוספים זמינים במאמר מעקב אחר ה-API.
--tracing_outgoing_context	מגדיר את כותרת הקשר של המעקב בבקשה שנשלחת לשירות הקצה העורפי. הדגל הזה מציין איזה כותר HTTP להגדיר, והערכים של הדגל מופרדים בפסיקים ללא רווחים. הערכים האפשריים כוללים traceparent, x-cloud-trace-context וגם grpc-trace-bin. אם לא מציינים את הכותרות האלה, הן יישלחו.traceparentx-cloud-trace-context פרטים נוספים זמינים במאמר מעקב אחר ה-API.

בדיקת תקינות

משתמשים בדגלים האלה כדי להגדיר בדיקות תקינות ל-ESPv2. אפשר להשתמש בדגל הראשון כדי להגדיר handler של תקינות שיגיב לקריאות של בדיקת התקינות. אפשר להשתמש בדגלים האחרים כדי להפעיל בדיקות תקינות ל-backend של gRPC.

/tbody>

דגל	תיאור
-z, --healthz	מגדירים נקודת קצה לבדיקת תקינות. לדוגמה, הפקודה -z healthz גורמת ל-ESPv2 להחזיר קוד 200 עבור הנתיב /healthz.
--health_check_grpc_backend	מפעילים את ESPv2 כדי לבדוק מעת לעת את שירות התקינות של gRPC עבור קצה עורפי שצוין באמצעות הדגל --backend. הקצה העורפי צריך להשתמש בפרוטוקול gRPC ולהטמיע את פרוטוקול בדיקת התקינות של gRPC. נקודת הקצה של בדיקת התקינות שמופעלת על ידי הדגל --healthz תשקף את תוצאת בדיקת התקינות של ה-Backend.
--health_check_grpc_backend_service	מציינים את שם השירות כשקוראים לפרוטוקול בדיקת תקינות של gRPC בשרת העורפי. הערך של הדגל הזה חל רק כשמשתמשים בדגל --health_check_grpc_backend. הפרמטר הזה הוא אופציונלי. אם לא מגדירים אותו, ברירת המחדל היא ריקה. שם שירות ריק משמש לשאילתת סטטוס הבריאות הכולל של שרת gRPC.
--health_check_grpc_backend_interval	כשקוראים לשירות הבריאות של gRPC בקצה העורפי, צריך לציין את מרווח הבדיקה ואת פסק הזמן של הבקשה. הערך של הדגל הזה חל רק כשמשתמשים בדגל --health_check_grpc_backend. ברירת המחדל היא שנייה אחת. הפורמט הקביל הוא רצף של מספרים עשרוניים, שלכל אחד מהם יכול להיות חלק שברירי אופציונלי וסיומת של יחידה, כמו ‎'5s'‎, ‎'100ms'‎ או ‎'2m'‎. יחידות הזמן הקבילות הן m לדקות, s לשניות ו-ms לאלפיות השנייה.

ניפוי באגים

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

דגל	תיאור
--status_port, --admin_port	מפעילים את ESPv2 Envoy admin ביציאה הזו. פרטים נוספים מופיעים במאמר בנושא ממשק הניהול של Envoy. יציאת האדמין מושבתת כברירת מחדל.
--enable_debug	הפעלת יומנים ברמת ניפוי הבאגים והוספת כותרות לניפוי באגים.

פריסה שאינה שלGoogle Cloud

אם ESPv2 נפרס בסביבה שאינה Google Cloud , יכול להיות שיהיה צורך בדגלים הבאים.

דגל	תיאור
--service_account_key	מציינים את קובץ ה-JSON של מפתח חשבון השירות כדי לגשת לשירותי Google. אם האפשרות לא מצוינת, ה-Proxy יוצר קשר עם Google Cloud שרת המטא-נתונים כדי לאחזר אסימון גישה.
--dns_resolver_addresses	הכתובות של שרתי DNS. כל כתובת צריכה להיות בפורמט IP_ADDR או IP_ADDR:PORT, והכתובות צריכות להיות מופרדות בנקודה ופסיק (;). ב-IP_ADDR, ייעשה שימוש ביציאת ה-DNS שמוגדרת כברירת מחדל, 52. לדוגמה: --dns_resolver_addresses=127.0.0.1;127.0.0.2;127.0.0.3:8000) אם לא מוגדר, ESPv2 ישתמש בפתרון ברירת המחדל שהוגדר ב-/etc/resolv.conf
--backend_dns_lookup_family	מגדירים את משפחת חיפושי ה-DNS לכל השרתים העורפיים. האפשרויות הן auto, ‏ v4only, ‏ v6only, ‏ v4preferred ו-all. ברירת המחדל היא v4preferred. שימו לב שהערך auto הוא ערך מדור קודם. הגדרת הדגל ל-auto תגרום להתנהגות שוות ערך ל-v6preferred.
--non_gcp	כברירת מחדל, ה-proxy מנסה להתחבר לשרת המטא-נתוניםGoogle Cloud כדי לקבל את המיקום של מכונת ה-VM בכמה הבקשות הראשונות. כדי לדלג על השלב הזה, מגדירים את הדגל הזה כ-true.

בדיקה מקומית

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

כדי לפרוס ולבדוק בקלות את התכונות באופן מקומי ב<High Priority Term: אינטגרציה רציפה (CI)>, אפשר להשתמש בדגלים האלה יחד עם דגלי הפריסהGoogle Cloud .

דגל	תיאור
--service_json_path	מציינים נתיב לטעינת ההגדרה של שירות נקודת הקצה ב-ESPv2. אם משתמשים בדגל הזה, ESPv2 ישתמש באסטרטגיית השקה 'קבועה' ויתעלם מהדגלים הבאים: --service --version --rollout_strategy הדגל הזה ימנע מ-ESPv2 להשתמש במכסה של Service Management API.
--enable_backend_address_override	אפשר לציין כתובות של קצה עורפי באמצעות הדגל --backend או השדה backend.rule.address בהגדרת השירות. משתמשי OpenAPI צריכים לשים לב שהשדה backend.rule.address מוגדר על ידי השדה address בתוסף x-google-backend. הגדרת השירות לכל פעולה backend.rule.address מצוינת בדרך כלל לניתוב ללא שרת. כברירת מחדל, הפעולה backend.rule.address תקבל עדיפות על פני הסימון --backend לכל פעולה בנפרד. מפעילים את הדגל הזה אם רוצים שהדגל --backend יקבל עדיפות. האפשרות הזו שימושית אם אתם מפתחים בתחנת עבודה מקומית. אחר כך תוכלו להשתמש באותה הגדרת שירות של סביבת הייצור, אבל להחליף את כתובת הבק-אנד באמצעות הדגל --backend לבדיקות מקומיות. הערה: רק הכתובת תוחלף. כל שאר הרכיבים של backend.rule עדיין יחולו (מועדים, אימות בקצה העורפי, תרגום נתיבים וכו').

שליפת כתובת ה-IP של הלקוח

משתמשים בדגלים האלה כדי להגדיר חילוץ של כתובות IP של לקוחות ב-ESPv2.

דגל	תיאור
--envoy_use_remote_address	למידע מפורט על ההגדרה של Envoy HttpConnectionManager, אפשר לעיין בהפניה של Envoy. ברירת המחדל היא מושבת.
--envoy_xff_num_trusted_hops	למידע מפורט על ההגדרה של Envoy HttpConnectionManager, אפשר לעיין בהפניה של Envoy. ערך ברירת המחדל הוא 2.

תמיכה ב-CORS

לתיאור של אפשרויות התמיכה הזמינות ב-CORS, אפשר לעיין במאמר בנושא תמיכה ב-CORS. בקטע הזה מוסבר איך להשתמש בדגלי הפעלה של ESPv2 כדי לתמוך ב-CORS.

כדי להפעיל תמיכה ב-CORS ב-ESPv2, צריך לכלול את האפשרות --cors_preset ולהגדיר אותה לאחד מהדגלים הבאים:

• --cors_preset=basic
• --cors_preset=cors_with_regex

כשכוללים את --cors_preset=basic או --cors_preset=cors_with_regex, ‏ ESPv2:

• מניח שלכל נתיבי המיקום יש את אותה מדיניות CORS.
• הוא מגיב גם לבקשות פשוטות וגם לבקשות קדם-הפעלה HTTP OPTIONS.
• התוצאה של בקשת ה-preflight OPTIONS נשמרת במטמון למשך עד 20 ימים (1,728,000 שניות).

• הכותרות של התגובה מוגדרות לערכים הבאים:

  Access-Control-Allow-Origin: *
  Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
  Access-Control-Allow-Headers: DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization
  Access-Control-Expose-Headers: Content-Length,Content-Range
  Access-Control-Max-Age: 1728000

כדי לשנות את ערך ברירת המחדל של Access-Control-Allow-Origin, צריך לציין אחת מהאפשרויות הבאות:

אפשרות	תיאור
--cors_allow_origin	אפשר להשתמש בתג הזה עם --cors_preset=basic כדי להגדיר את Access-Control-Allow-Origin למוצא ספציפי. דוגמה: --cors_preset=basic --cors_allow_origin=http://example.com
--cors_allow_origin_regex	שימוש עם --cors_preset=cors_with_regex. אפשר להשתמש בביטוי רגולרי כדי להגדיר את Access-Control-Allow-Origin. דוגמה: --cors_preset=cors_with_regex --cors_allow_origin_regex=^https?://.+\.example\.com$ הביטוי הרגולרי בדוגמה שלמעלה מאפשר מקור עם http או https וכל תת-דומיין של example.com. כשמגדירים את האפשרות הזו בקובץ הגדרות של Kubernetes, צריך להוסיף תו נטוי הפוך נוסף כדי לסמן בתו בריחה את שני המקרים של \ במחרוזת, לדוגמה: "--cors_preset","cors_with_regex", "--cors_allow_origin_regex","^https?://.+\\.example\\.com$" כשמגדירים את האפשרות הזו בסקריפט gcloud_build_image ל-Cloud Run, מומלץ להימנע משימוש בתווים עם escape ובקו נטוי הפוך, כי יכול להיות שהם לא יועברו בצורה נכונה מסקריפט ה-bash לשרת ה-proxy בהפעלה. צריך להשתמש במחלקות של תווים במקום ברצפים של תווים מטא. לדוגמה: Original: \d Recommended: [0-9]

אחרי שמגדירים את --cors_preset=basic או את --cors_preset=cors_with_regex כדי להפעיל את CORS, אפשר לשנות את ערכי ברירת המחדל של כותרות התגובה האחרות על ידי ציון אחת או יותר מהאפשרויות הבאות:

אפשרות	תיאור
--cors_allow_methods	מגדירים את Access-Control-Allow-Methods לשיטות ה-HTTP שצוינו. מציינים את ה-HTTP methods כמחרוזת, כשכל HTTP method מופרד בפסיק. דוגמה: --cors_preset=basic --cors_allow_methods=GET,POST,PUT,OPTIONS
--cors_allow_headers	מגדיר את Access-Control-Allow-Headers לכותרות ה-HTTP שצוינו. מציינים את כותרות ה-HTTP כמחרוזת, כשכל כותרת HTTP מופרדת בפסיק. דוגמה: --cors_preset=basic --cors_allow_headers=Origin,Content-Type,Accept
--cors_allow_credentials	כולל את הכותרת Access-Control-Allow-Credentials עם הערך true בתשובות. כברירת מחדל, הכותרת Access-Control-Allow-Credentials לא נכללת בתגובות. דוגמה: --cors_preset=basic --cors_allow_credentials
--cors_expose_headers	מגדיר את Access-Control-Expose-Headers לכותרות שצוינו. מציינים אילו כותרות אפשר לחשוף כחלק מהתגובה כמחרוזת שבה כל כותרת מופרדת בפסיק. דוגמה: --cors_preset=basic --cors_expose_headers=Content-Length
--cors_max_age	מגדיר את Access-Control-Max-Age למשך הזמן שצוין. הפורמט הקביל הוא רצף של מספרים עשרוניים, שלכל אחד מהם יכול להיות ערך חלקי אופציונלי וסיומת של יחידה, כמו '300m',‏ '1.5h' או '2h45m'. יחידות הזמן הקבילות הן m לדקות ו-h לשעות. אם לא מגדירים את הערך, ברירת המחדל היא 480 שעות. דוגמה: --cors_preset=basic --cors_max_age=24h

תמיכה ב-TLS

משתמשים בדגלים האלה כדי להגדיר את ESPv2 לשימוש בחיבורי TLS.

דגל	תיאור
--ssl_server_cert_path	נתיב אישור השרת של ה-Proxy. כשהוא מוגדר, ‏ESPv2 מקבל רק חיבורים מאובטחים של HTTP/1.x ו-HTTP/2 ביציאת listener_port. נדרשים קובצי האישור והמפתח server.crt ו-server.key בנתיב הזה.
--ssl_server_cipher_suites	סטים של אלגוריתמים להצפנה לשימוש בחיבורים במורד הזרם, שצוינו כרשימה מופרדת בפסיקים. אפשר לעיין במאמר הגדרת סט אלגוריתמים להצפנה (cipher suite).
--ssl_backend_client_cert_path	נתיב אישור הלקוח של ה-Proxy. כשמגדירים את ESPv2, הוא מאפשר אימות TLS הדדי לשרתי קצה עורפיים של HTTPS. נדרשים קובצי האישור והמפתח client.crt ו-client.key בנתיב הזה.
--ssl_backend_client_root_certs_file	נתיב הקובץ של אישורים בסיסיים ש-ESPv2 משתמש בהם כדי לאמת את אישור השרת של העורף. אם לא מציינים נתיב, ESPv2 משתמש בנתיב '/etc/ssl/certs/ca-certificates.crt' כברירת מחדל.
--ssl_backend_client_cipher_suites	חבילות הצפנה לשימוש בשרתי קצה עורפיים של HTTPS, שצוינו כרשימה מופרדת בפסיקים. אפשר לעיין במאמר הגדרת סט אלגוריתמים להצפנה (cipher suite).
--ssl_minimum_protocol	גרסה מינימלית של פרוטוקול TLS לחיבור בצד הלקוח. כאן
--ssl_maximum_protocol	גרסת הפרוטוקול המקסימלית של TLS לחיבור בצד הלקוח. כאן
--enable_strict_transport_security	הפעלת HSTS ‏ (HTTP Strict Transport Security). כותרת התגובה Strict-Transport-Security עם הערך max-age=31536000; includeSubdomains;‎ נוספת לכל התגובות.
--generate_self_signed_cert	יצירת אישור ומפתח בחתימה עצמית בהתחלה, ואז שמירתם בנתיבים ‎/tmp/ssl/endpoints/server.crt ו-‎/tmp/ssl/endpoints/server.key. האפשרות הזו שימושית כשצריך רק אישור חתימה עצמית אקראי כדי להציג בקשות HTTPS. האישור שנוצר יכלול את השם הנפוץ localhost ויהיה תקף למשך 10 שנים.

פסק זמן וניסיונות חוזרים

משתמשים בדגלים האלה כדי להגדיר פסק זמן (timeout) וניסיונות חוזרים של קריאות HTTP מרחוק ל-ESPv2.

דגל	תיאור
--http_request_timeout_s	הגדרת פסק זמן בשניות לבקשות שנשלחות לשירותים חיצוניים, למעט Backend ו-Google Service Control. הוא כולל את Google ServiceManagement, שרת מטא-נתונים ושרת Google IAM. הערך חייב להיות > 0, ואם לא מגדירים ערך, ברירת המחדל היא 30 שניות.
--service_control_network_fail_policy	במקרה של כשלים ברשת כשמתחברים לשליטה בשירות Google, הבקשות יאושרו אם הדגל הזה פתוח. ברירת המחדל היא פתוח.
--service_control_check_timeout_ms	מגדירים את הזמן הקצוב לתפוגה (timeout) באלפיות השנייה לבקשת בדיקה של אמצעי הבקרה של השירות. הערך צריך להיות גדול מ-0, ואם לא מגדירים ערך, ברירת המחדל היא 1,000.
--service_control_report_timeout_ms	מגדירים את זמן קצוב לתפוגה באלפיות השנייה לבקשת דוח של Service Control. הערך חייב להיות גדול מ-0, ואם לא מגדירים ערך, ברירת המחדל היא 1,000.
--service_control_quota_timeout_ms	מגדירים את פסק הזמן באלפיות השנייה לבקשת מכסה של Service Control. הערך צריך להיות גדול מ-0. אם לא מגדירים ערך, ברירת המחדל היא 1,000.
--service_control_check_retries	מגדירים את מספר הניסיונות החוזרים לבקשת בדיקה של אמצעי בקרה לשירות. הערך חייב להיות ‎>= 0, ואם לא מגדירים ערך, ברירת המחדל היא 3
--service_control_report_retries	הגדרת מספר הניסיונות החוזרים לבקשת דוח של בקרת שירות. הערך חייב להיות ‎>= 0, ואם לא מגדירים ערך, ברירת המחדל היא 5
--service_control_quota_retries	הגדרת מספר הניסיונות החוזרים לבקשת מכסה של Service Control. הערך חייב להיות ‎>= 0, ואם לא מגדירים ערך, ברירת המחדל היא 1.
--backend_retry_ons	התנאים שבהם ESPv2 מנסה שוב להתחבר לשרתי הקצה העורפיים. אפשר לציין תנאי retryOn אחד או יותר ברשימה שמופרדת בפסיקים. ערך ברירת המחדל הוא reset,connect-failure,refused-stream. כדי להשבית את הניסיון החוזר, מגדירים את הדגל הזה כריק. בקישורים הבאים אפשר לעיין בתנאים המקובלים: x-envoy-retry-on x-envoy-retry-grpc-on
--backend_retry_num	מספר הניסיונות החוזרים המותר. הערך חייב להיות גדול או שווה ל-0, וערך ברירת המחדל הוא 1.

gRPC Transcoding

משתמשים בדגלים האלה כדי להגדיר את ESPv2 ל-HTTP/JSON ל-gRPC transcoding.

דגל	תיאור
--transcoding_always_print_primitive_fields	ההגדרה הזאת קובעת אם להדפיס שדות פרימיטיביים עבור טרנסקוד של grpc-json. כברירת מחדל, שדות פרימיטיביים עם ערכי ברירת מחדל לא ייכללו בפלט JSON. לדוגמה, שדה int32 שהערך שלו הוא 0 יושמט. הגדרת הדגל הזה לערך true תבטל את התנהגות ברירת המחדל ותדפיס שדות פרימיטיביים בלי קשר לערכים שלהם. ברירת המחדל היא false.
--transcoding_always_print_enums_as_ints	ההגדרה הזאת קובעת אם להדפיס סוגי enum כמספרים שלמים עבור grpc-json transcoding. כברירת מחדל, הם מוצגים כמחרוזות. ברירת המחדל היא false.
--transcoding_stream_newline_delimited	אם הערך הוא true, נעשה שימוש בתו מפריד של שורה חדשה כדי להפריד בין הודעות של סטרימינג של תגובות. אם הערך הוא false, כל הודעות הסטרימינג של התגובה עוברות המרה לפורמט JSON כמערך.
--transcoding_case_insensitive_enum_parsing	בדרך כלל, ערכי enum של פרוטו צריכים להיות באותיות רישיות כשמשתמשים בהם ב-JSON. מגדירים את הדגל הזה כ-true אם בקשת ה-JSON משתמשת בערכי enum שאינם באותיות רישיות.
--transcoding_preserve_proto_field_names	ההגדרה הזאת קובעת אם לשמור את שמות השדות של פרוטו עבור טרנסקוד של grpc-json. כברירת מחדל, פרוטוקול protobuf ייצור שמות של שדות JSON באמצעות האפשרות json_name או באמצעות אותיות קטנות בפורמט CamelCase, לפי הסדר הזה. הגדרת הדגל הזה תשמור על השמות המקוריים של השדות. ברירת המחדל היא false.
--transcoding_ignore_query_parameters	רשימה של פרמטרים של שאילתה שמופרדים בפסיקים וצריך להתעלם מהם במיפוי של שיטת הקידוד מחדש בקידוד מחדש של grpc-json. כברירת מחדל, המסנן של הטרנסקודר לא יבצע טרנסקוד לבקשה עם פרמטרים לא ידועים או לא תקינים של שאילתה.
--transcoding_ignore_unknown_query_parameters	ההגדרה הזו קובעת אם להתעלם מפרמטרים של שאילתות שלא ניתן למפות לשדה protobuf תואם בטרנסקודינג של grpc-json. משתמשים באפשרות הזו אם אין לכם שליטה בפרמטרים של השאילתה ואתם לא יודעים אותם מראש. אחרת, משתמשים ב---transcoding_ignore_query_parameters. ברירת המחדל היא false.
--transcoding_query_parameters_disable_unescape_plus	כברירת מחדל, סימני פלוס "+" בפרמטרים של השאילתה לא עוברים ביטול בריחה ומומרים לרווח " " בתעתיק של grpc-json. השינוי הזה נועד לתמוך ב-HTML 2.0. אם לא רוצים להשתמש בתכונה הזו, צריך להגדיר את הדגל הזה כ-True כדי להשבית אותה.

שינוי בקשות ותגובות

אפשר להשתמש בדגלים האלה כדי להגדיר את ESPv2 כך שישנה חלקית בקשות ותגובות.

דגל	תיאור
--add_request_header	מוסיפים כותרת HTTP לבקשה לפני ששולחים אותה לשרת העורפי שלמעלה. אם הכותרת כבר קיימת בבקשה, הערך שלה יוחלף בערך החדש. היא תומכת במשתנים מותאמים אישית של Envoy. אפשר לחזור על הארגומנט הזה כמה פעמים כדי לציין כמה כותרות. לדוגמה: --add_request_header=key1=value1 --add_request_header=key2=value2.
--append_request_header	הוספת כותרת HTTP לבקשה לפני שליחתה לשרת העורפי שלמעלה. אם הכותרת כבר נמצאת בבקשה, הערך החדש יצורף אליה. היא תומכת במשתנים מותאמים אישית של Envoy. אפשר לחזור על הארגומנט הזה כמה פעמים כדי לציין כמה כותרות. לדוגמה: --append_request_header=key1=value1 --append_request_header=key2=value2.
--add_response_header	הוספת כותרת HTTP לתגובה לפני שליחתה ללקוח במורד הזרם. אם הכותרת כבר נמצאת בתשובה, היא תוחלף בכותרת החדשה. היא תומכת במשתנים מותאמים אישית של Envoy. אפשר לחזור על הארגומנט הזה כמה פעמים כדי לציין כמה כותרות. לדוגמה: --add_response_header=key1=value1 --add_response_header=key2=value2.
--append_response_header	הוספת כותרת HTTP לתגובה לפני שליחתה ללקוח במורד הזרם. אם הכותרת כבר נמצאת בתשובה, הכותרת החדשה תצורף אליה. היא תומכת במשתנים מותאמים אישית של Envoy. אפשר לחזור על הארגומנט הזה כמה פעמים כדי לציין כמה כותרות. לדוגמה: --append_response_header=key1=value1 --append_response_header=key2=value2.

אפשרויות אבטחה

אפשר להשתמש בדגלים האלה כדי לחדד עוד יותר את הבקשות שמותרות ב-ESPv2.

דגל	תיאור
--underscores_in_headers	מאפשרים להעביר שמות של כותרות שמכילים קווים תחתונים. ברירת המחדל היא false. התו קו תחתון מותר בשמות של כותרות לפי RFC-7230. עם זאת, ההתנהגות הזו מיושמת כאמצעי אבטחה כי במערכות מסוימות _ ו-- נחשבים לניתנים להחלפה.
--envoy_connection_buffer_limit_bytes	מגדירים את כמות הנתונים המקסימלית שמאוחסנת במאגר הזמני לכל גוף של בקשה או תגובה, בבייטים. אם לא מגדירים את המדיניות, ברירת המחדל נקבעת על ידי Envoy. הגדרת מאזין ב-Envoy
--disable_normalize_path	השבתת הנורמליזציה של כותרת ה-HTTP‏ path בהתאם ל-RFC 3986. מומלץ להשאיר את האפשרות הזו מופעלת אם ה-backend מבצע נורמליזציה של נתיבים כברירת מחדל. בטבלה הבאה מוצגות דוגמאות לבקשה path שהעורף יקבל מ-ESPv2 על סמך ההגדרה של הדגל הזה. ----------------------------------------------------------------- | Request Path | Without Normalization | With Normalization | ----------------------------------------------------------------- | /hello/../world | Rejected | /world | | /%4A | /%4A | /J | | /%4a | /%4a | /J | ----------------------------------------------------------------- כברירת מחדל, ‏ ESPv2 יבצע נורמליזציה של נתיבים. משביתים את התכונה רק אם ההתנהגות שלה משפיעה על התנועה. הערה: בהתאם ל-RFC 3986, האפשרות הזו לא מבטלת את הקידוד של התווים '/' שמקודדים באחוזים. כדי להפעיל את ההתנהגות הזו שלא עומדת בדרישות, צריך להגדיר את הדגל --disallow_escaped_slashes_in_path. הערה: נורמליזציה של אותיות רישיות מ-RFC 3986 לא נתמכת, גם אם האפשרות הזו מופעלת. מידע נוסף זמין במאמר הסבר על יצירת תבניות של נתיבים.
--disable_merge_slashes_in_path	השבתה של מיזוג לוכסנים סמוכים בכותרת ה-HTTP‏ path. מומלץ להשאיר את האפשרות הזו מופעלת אם קצה העורף שלכם מבצע מיזוג כברירת מחדל. בטבלה הבאה מוצגות דוגמאות לבקשה path שהעורף יקבל מ-ESPv2 על סמך ההגדרה של הדגל הזה. ----------------------------------------------------------------- | Request Path | Without Normalization | With Normalization | ----------------------------------------------------------------- | /hello//world | Rejected | /hello/world | | /hello/// | Rejected | /hello | ----------------------------------------------------------------- כברירת מחדל, ESPv2 ימזג את הקווים האלכסוניים. משביתים את התכונה רק אם ההתנהגות שלה משפיעה על התנועה. מידע נוסף זמין במאמר הסבר על יצירת תבניות של נתיבים.
--disallow_escaped_slashes_in_path	הבקשות עם תווים של לוכסן בקידוד של אחוזים עם תו בריחה לא מורשות: ‫%2F או %2f נחשב כ-/ ‫%5C או %5c נחשב ל-\ כשההגדרה הזו מופעלת, ההתנהגות תלויה בפרוטוקול שבו משתמשים: בשרתי קצה של OpenAPI, נתיבי בקשות עם לוכסנים מוצפנים בקידוד אחוזים עם תווי escape יבוטלו אוטומטית באמצעות הפניה אוטומטית. בשרתי קצה של gRPC, נתיבי בקשות עם לוכסנים מוצפנים בקידוד אחוזים עם תווי escape יידחו (gRPC לא תומך בהפניות אוטומטיות). האפשרות הזו לא תואמת ל-RFC 3986, ולכן היא מושבתת כברירת מחדל. אם ה-backend שלכם לא תואם ל-RFC 3986 ומבצע escape ללוכסנים, חובה להפעיל את האפשרות הזו ב-ESPv2. כך נמנעות מתקפות של בלבול נתיבים שגורמות לכך שדרישות האבטחה לא נאכפות. מידע נוסף זמין במאמר הסבר על יצירת תבניות של נתיבים.

אימות JWT

משתמשים בדגלים האלה כדי להגדיר את ESPv2 לאחזור של Jwks מרחוק עם ניסיונות חוזרים.

דגל	תיאור
--jwks_fetch_num_retries	מציינים את מספר הניסיונות החוזרים במדיניות הניסיונות החוזרים לאחזור JWKS מרחוק. ברירת המחדל היא 0, כלומר לא מתבצע ניסיון חוזר.
--jwks_fetch_retry_back_off_base_interval_ms	מציינים את מרווח הזמן הבסיסי של ההשהיה המעריכית לפני ניסיון חוזר של אחזור JWKS, באלפיות השנייה. אם לא מגדירים ערך, ברירת המחדל היא 200ms.
--jwks_fetch_retry_back_off_max_interval_ms	מציינים את המרווח המקסימלי של השהיה מעריכית (exponential backoff) לפני ניסיון חוזר של אחזור JWKS, באלפיות השנייה. אם לא מגדירים ערך, ברירת המחדל היא 32 שניות.
--jwks_cache_duration_in_s	מציינים את משך השהייה במטמון של המפתח הציבורי של JWT בשניות. אם לא מגדירים את התדירות, ברירת המחדל היא 5 דקות.
--jwks_async_fetch_fast_listener	ההגדרה הזו רלוונטית רק כשלא מוגדר הדגל --disable_jwks_async_fetch. הדגל הזה קובע אם ESPv2 ימתין לסיום של jwks השליפה הראשונית לפני קישור יציאת המאזין. אם הערך הוא False, המערכת תמתין. ברירת המחדל היא FALSE.
--jwt_cache_size	מציינים את מספר אסימוני ה-JWT הייחודיים כגודל המקסימלי של מטמון ה-JWT. במטמון מאוחסנים רק אסימונים מאומתים. אם הערך הוא 0, המטמון של JWT מושבת. הדגל הזה מגביל את השימוש בזיכרון למטמון JWT. הזיכרון שמשמש את המטמון הוא בערך (גודל הטוקן + 64 בייט) לכל טוקן. אם לא מציינים ערך, ברירת המחדל היא 100,000.
--disable_jwt_audience_service_name_check	בדרך כלל, השדה aud של JWT נבדק מול קהלים שצוינו בשדה x-google-audiences של OpenAPI. הדגל הזה משנה את ההתנהגות כשלא מציינים את השדה x-google-audiences. אם לא מציינים את השדה x-google-audiences ולא משתמשים בדגל הזה, שם השירות משמש לבדיקת השדה aud של ה-JWT. אם משתמשים בדגל הזה, לא תתבצע בדיקה של השדה aud ב-JWT.

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

מידע על:

• העברה ל-Extensible Service Proxy V2
• תוספים של OpenAPI