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

‫Extensible Service Proxy‏ (ESP) הוא פרוקסי מבוסס NGINX שמאפשר ל-Cloud Endpoints לספק תכונות של ניהול API. כדי להגדיר את ESP, מציינים אפשרויות כשמפעילים את קונטיינר ה-Docker של ESP. כשהקונטיינר של ESP מתחיל, הוא מריץ סקריפט בשם start_esp, שכותב את קובץ ההגדרות של NGINX באמצעות האפשרויות שציינתם ומפעיל את ESP.

מציינים את אפשרויות ההפעלה של ה-ESP בפקודה docker run, לדוגמה:

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

אם פורסים את ESP ב-Kubernetes, מציינים את אפשרויות ההפעלה בקובץ המניפסט של הפריסה בשדה args, לדוגמה:

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

בטבלה הבאה מתוארות אפשרויות ההפעלה של ESP.

אפשרות קצרה אפשרות ארוכה תיאור
-s SERVICE_NAME --service SERVICE_NAME מגדיר את השם של שירות Endpoints.
-R ROLLOUT_STRATEGY --rollout_strategy ROLLOUT_STRATEGY

האפשרות זמינה ב-ESP מגרסה 1.7.0 ואילך. צריך לציין managed או fixed. האפשרות --rollout_strategy=managed מגדירה את ESP כך שישתמש בהגדרת השירות העדכנית ביותר שנפרסה. אם תבחרו באפשרות הזו, עד 5 דקות אחרי שתפרסו הגדרת שירות חדשה, ESP יזהה את השינוי ויתחיל להשתמש בה באופן אוטומטי. אנחנו ממליצים לציין את האפשרות הזו במקום מזהה תצורה ספציפי לשימוש ב-ESP. אין צורך לציין את האפשרות --version כשמגדירים את --rollout_strategy לערך managed.
-v CONFIG_ID --version CONFIG_ID מגדיר את מזהה תצורת השירות שבו ESP ישתמש. במאמר איך מקבלים את שם השירות ואת מזהה ההגדרה מוסבר איך מגדירים את האפשרות הזו. כשמציינים --rollout_strategy=fixed או כשלא כוללים את האפשרות --rollout_strategy, צריך לכלול את האפשרות --version ולציין מזהה הגדרה. במקרה כזה, בכל פעם שמפעילים הגדרה חדשה של Endpoints, צריך להפעיל מחדש את ESP עם מזהה ההגדרה החדש.
-p HTTP1_PORT --http_port HTTP1_PORT הגדרת היציאות ש-ESP חושף לחיבורים מסוג HTTP/1.x.1
-P HTTP2_PORT --http2_port HTTP2_PORT הגדרת היציאות ש-ESP חושף לחיבורי HTTP/2.1
-S SSL_PORT --ssl_port SSL_PORT הגדרת היציאות ש-ESP חושף לחיבורי HTTPS.1
-a BACKEND --backend BACKEND מגדירה את הכתובת של שרת העורף של אפליקציית HTTP/1.x. ערך ברירת המחדל של כתובת הקצה העורפי הוא http://127.0.0.1:8081.
אפשר לציין קידומת פרוטוקול, למשל:
--backend=https://127.0.0.1:8000
אם לא מציינים קידומת פרוטוקול, ברירת המחדל היא http.
אם שרת הקצה העורפי פועל ב-Compute Engine בתוך קונטיינר, אפשר לציין את שם הקונטיינר ואת היציאה, לדוגמה:
--backend=my-api-container:8000
כדי לציין שהקצה העורפי מקבל תנועת gRPC, מוסיפים את התחילית grpc://. לדוגמה:
--backend=grpc://127.0.0.1:8000
אם שרת הקצה העורפי פועל ב-Compute Engine בתוך קונטיינר,
והוא מקבל תנועה מסוג gRPC, אפשר לציין את שם הקונטיינר ואת היציאה, לדוגמה:
--backend=grpc://my-api-container:8000
-N STATUS_PORT --status_port STATUS_PORT הגדרת יציאת הסטטוס (ברירת מחדל: 8090).
ללא --disable_cloud_trace_auto_sampling כברירת מחדל, ESP דוגם בקשה אחת מתוך כל 1,000 בקשות או בקשה אחת מתוך כל 10 שניות, ומופעל עם Cloud Trace. כדי להשבית את הדגימה האוטומטית הזו, מגדירים את הדגל הזה. עדיין אפשר להפעיל את Cloud Trace מכותרות HTTP של בקשות עם הקשר מעקב, ללא קשר לערך של הדגל הזה. מידע נוסף זמין במאמר בנושא מעקב אחר ה-API.
-n NGINX_CONFIG --nginx_config NGINX_CONFIG מגדיר את המיקום של קובץ ההגדרות בהתאמה אישית של NGINX. אם מציינים את האפשרות הזו, ESP מאחזר את קובץ ההגדרות שצוין ואז מפעיל מיד את NGINX עם קובץ ההגדרות המותאם אישית שסופק. מידע נוסף זמין במאמר שימוש בהגדרת nginx מותאמת אישית ב-GKE.
-k SERVICE_ACCOUNT_KEY --service_account_key SERVICE_ACCOUNT_KEY מגדיר את קובץ ה-JSON של פרטי הכניסה לחשבון השירות. אם מסופק חשבון שירות, ESP משתמש בו כדי ליצור אסימון גישה לקריאה ל-Service Infrastructure APIs. צריך לציין את האפשרות הזו רק אם ESP פועל בפלטפורמות אחרות מלבד Google Cloud, כמו מחשב מקומי, Kubernetes או ספק שירותי ענן אחר. מידע נוסף זמין במאמר יצירת חשבון שירות.
-z HEALTHZ_PATH --healthz HEALTHZ_PATH מגדירים נקודת קצה לבדיקת תקינות באותן יציאות כמו ה-backend של האפליקציה. לדוגמה, -z healthz גורם ל-ESP להחזיר קוד 200 למיקום /healthz, במקום להעביר את הבקשה אל ה-backend. ברירת מחדל: לא בשימוש.
ללא --dns DNS_RESOLVER מציינים מקודד DNS. לדוגמה, --dns 169.254.169.254 משתמש בשרת המטא-נתונים של GCP כמפענח DNS. אם לא מציינים ערך, ברירת המחדל היא 8.8.8.8.

1 הפורטים האלה הם אופציונליים וחייבים להיות שונים זה מזה. אם לא מציינים אפשרות יציאה, ESP מקבל חיבורים מסוג HTTP/1.x ביציאה 8080. בחיבורי HTTPS, שרת ה-ESP מצפה שהסודות של TLS יהיו במיקומים /etc/nginx/ssl/nginx.crt ו-/etc/nginx/ssl/nginx.key.

דוגמאות להפעלות משורת הפקודה

בדוגמאות הבאות אפשר לראות איך משתמשים בחלק מארגומנטי שורת הפקודה:

כדי להפעיל את ESP לטיפול בבקשות שמגיעות ביציאת HTTP/1.x‏ 80 וביציאת HTTPS‏ 443 ולשלוח את הבקשות לעורף ה-API בכתובת 127.0.0.1:8000:

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:1
     --service=echo-api.endpoints.example-project-12345.cloud.goog \
        --rollout_strategy=managed \
        --http_port=80 \
        --ssl_port=443 \
        --backend=127.0.0.1:8000

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

sudo docker run \
    --detach \
    --volume=$HOME/Downloads:/esp \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=echo-api.endpoints.example-project-12345.cloud.goog \
    --rollout_strategy=managed \
    --service_account_key=/esp/serviceaccount.json \
    --nginx_config=/esp/nginx.conf

שימו לב: כדי לטעון את קובץ ה-JSON שמכיל את המפתח הפרטי של חשבון השירות ואת קובץ ההגדרות המותאם אישית של NGINX כנפחים בתוך קונטיינר Docker של ESP, צריך להשתמש בדגלי Docker‏ --volume או --mount. בדוגמה שלמעלה, הספרייה $HOME/Downloads במחשב המקומי ממופה לספרייה esp בקונטיינר. כששומרים את קובץ המפתח הפרטי של חשבון השירות, הוא בדרך כלל מורד לספרייה Downloads. אם רוצים, אפשר להעתיק את קובץ המפתח הפרטי לספרייה אחרת. מידע נוסף זמין במאמר בנושא ניהול נתונים ב-Docker.

הוספת תמיכה ב-CORS ל-ESP

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

כדי להפעיל תמיכה ב-CORS ב-ESP, צריך לכלול את האפשרות --cors_preset ולהגדיר אותה ל-basic או ל-cors_with_regex. כשכוללים את --cors_preset=basic או --cors_preset=cors_with_regex, ספק ה-ESP:

  • מניח שלכל נתיבי המיקום יש את אותה מדיניות 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-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.

אחרי שמגדירים את --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

אם אפשרויות ההפעלה של ESP CORS לא מתאימות לצרכים של האפליקציה, אפשר ליצור קובץ nginx.conf בהתאמה אישית עם תמיכת ה-CORS שהאפליקציה דורשת. מידע נוסף זמין במאמר בנושא יצירת nginx.conf בהתאמה אישית לתמיכה ב-CORS.

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

מידע על: