יצירת כותרות בהתאמה אישית במפות של כתובות URL

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

כותרות מותאמות אישית של בקשות ותגובות מאפשרות לכם לציין כותרות נוספות שמאזן העומסים יכול להוסיף לבקשות ולתגובות של HTTP(S). בהתאם למידע שמאזן העומסים מזהה, הכותרות האלה יכולות לכלול את המידע הבא:

• זמן האחזור ללקוח

• פרמטרים של חיבור TLS

• המיקום הגיאוגרפי של כתובת ה-IP של הלקוח

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

לפני שמתחילים

אם צריך, מעדכנים לגרסה האחרונה של Google Cloud CLI:

gcloud components update

איך פועלות כותרות מותאמות אישית

כותרות מותאמות אישית פועלות באופן הבא:

• כשמאזן העומסים שולח בקשה לשרת העורפי, הוא מוסיף כותרות לבקשה.

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

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

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

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

• שם הכותרת צריך להיות הגדרה תקינה של שם שדה כותרת HTTP לפי RFC 7230.
• שם הכותרת לא יכול להיות X-User-IP.
• שם הכותרת לא יכול להתחיל ב-X-Google, X-Goog-, X-GFE או X-Amz-.
• אסור להשתמש בכותרות הבאות מסוג hop-by-hop:‏ Keep-Alive,‏ Transfer-Encoding,‏ TE,‏ Connection,‏ Trailer ו-Upgrade. בהתאם ל-RFC 2616, המטמון לא שומר את הכותרות האלה והן לא מועברות על ידי שרתי ה-proxy של היעד.
• שם הכותרת לא יכול להיות Host או authority. גם Host וגם authority הן מילות מפתח מיוחדות ששמורות לשימוש של Google Cloud. אי אפשר לשנות את הכותרות האלה במאזני עומסים שמבוססים על Envoy. במקום זאת, מומלץ ליצור כותרות מותאמות אישית אחרות (לדוגמה, MyHost) כדי לא להפריע לשמות הכותרות השמורים.
• שם של כותרת לא יכול להופיע יותר מפעם אחת ברשימת הכותרות.

השמות של הכותרות הם לא תלויי-רישיות. כששמות של כותרות מועברים לעורף של HTTP/2, פרוטוקול HTTP/2 מקודד את שמות הכותרות באותיות קטנות.

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

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

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

הוספה של כותרות בקשה או תגובה

כדי להוסיף כותרות של בקשות או תגובות, משתמשים ב-CLI של gcloud כדי לערוך את מפת ה-URL באופן הבא:

הערה: אם משתמשים במסוף Google Cloud כדי להוסיף את כותרות הבקשה והתגובה למפת URL, צריך להזין את כתובת המארח בשדה מארחים ואת הקטע של התאמת הנתיב בקובץ ה-YAML הבא בשדה התאמת נתיב.

אזורי

    gcloud compute url-maps edit URL_MAP_NAME \
        --region=REGION
    

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

   defaultService: regions/REGION/backendServices/BACKEND_SERVICE_1
   name: regional-lb-map
   region: region/REGION
   hostRules:
   - hosts:
     - '*'
     pathMatcher: matcher1
   pathMatchers:
   - defaultService: regions/REGION/backendServices/BACKEND_SERVICE_1
     name: matcher1
     routeRules:
       - matchRules:
           - prefixMatch: /PREFIX
         priority: PRIORITY # 0 is highest
         routeAction:
           weightedBackendServices:
             - backendService: regions/REGION/backendServices/BACKEND_SERVICE_1
               weight: 100
               headerAction:
                 requestHeadersToAdd:
                 - headerName: X-header-1-client-region
                   headerValue: "{client_region}"
                 - headerName: X-header-2-client-ip-port
                   headerValue: "{client_ip_address}, {client_port}"
                   replace: True
                 requestHeadersToRemove:
                 - header-3-name
                 responseHeadersToAdd:
                 - headerName: X-header-4-server-ip-port
                   headerValue: "{server_ip_address}, {server_port}"
                   replace: True
                 responseHeadersToRemove:
                 - header-5-name
                 - header-6-name
    

שימו לב להתנהגויות הבאות:

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

משתנים שיכולים להופיע בערך של הכותרת

המשתנים הבאים יכולים להופיע בערכים של כותרות בהתאמה אישית.

משתנה	תיאור
client_region	המדינה (או האזור) שמשויכת לכתובת ה-IP של הלקוח. זהו קוד אזור Unicode CLDR, כמו US או FR. (ברוב המדינות, הקודים האלה תואמים ישירות לקודי ISO-3166-2).
client_rtt_msec	זמן שידור משוער של הלוך ושוב בין מאזן העומסים לבין לקוח HTTP(S), באלפיות השנייה. זהו הפרמטר של זמן הלוך ושוב מוחלק (SRTT) שנמדד על ידי מחסנית ה-TCP של מאזן העומסים, בהתאם ל-RFC 2988. ה-RTT המוחלק הוא אלגוריתם שמטפל בשינויים ובאנומליות שיכולים להתרחש במדידות של ה-RTT.
client_ip_address	כתובת ה-IP של הלקוח. בדרך כלל, זוהי אותה כתובת כמו כתובת ה-IP של הלקוח, שהיא הכתובת הלפני האחרונה בכותרת X-Forwarded-For, אלא אם הלקוח משתמש ב-proxy או אם בוצעו שינויים בכותרת X-Forwarded-For.
client_port	יציאת המקור של הלקוח.
client_encrypted	true אם החיבור בין הלקוח למאזן העומסים מוצפן (באמצעות HTTPS,‏ HTTP/2 או HTTP/3). אחרת, false.
client_protocol	פרוטוקול ה-HTTP שמשמש לתקשורת בין הלקוח לבין מאזן העומסים. אחד מהנכסים הבאים: HTTP/1.0, HTTP/1.1, HTTP/2 או HTTP/3.
origin_request_header	משקף את הערך של הכותרת Origin בבקשה לתרחישי שימוש של שיתוף משאבים בין מקורות (CORS).
server_ip_address	כתובת ה-IP של מאזן העומסים שאליו הלקוח מתחבר. האפשרות הזו שימושית כשכמה מאזני עומסים חולקים את אותם שרתים עורפיים. הערך הזה זהה לכתובת ה-IP האחרונה בכותרת X-Forwarded-For.
server_port	מספר יציאת היעד שהלקוח מתחבר אליה.
tls_sni_hostname	האינדיקציה של שם השרת (כפי שמוגדר ב-RFC 6066), אם הלקוח מספק אותה במהלך לחיצת היד של TLS או QUIC. שם המארח מומר לאותיות קטנות וכל נקודה בסוף השם מוסרת.
tls_version	גרסת TLS שנקבעה במשא ומתן בין הלקוח למאזן העומסים במהלך לחיצת היד בפרוטוקול SSL. הערכים האפשריים כוללים: TLSv1, TLSv1.1,‏ TLSv1.2 ו-TLSv1.3. אם הלקוח מתחבר באמצעות QUIC במקום TLS, הערך הוא QUIC.
tls_cipher_suite	סט אלגוריתמים להצפנה (cipher suite) שנקבע במהלך לחיצת היד בפרוטוקול TLS. הערך הוא ארבע ספרות הקסדצימליות שמוגדרות במאגר של IANA לחבילות הצפנה של TLS, למשל, 009C עבור TLS_RSA_WITH_AES_128_GCM_SHA256. הערך הזה ריק עבור QUIC ועבור חיבורי לקוח לא מוצפנים.
tls_ja3_fingerprint	JA3 TLS/SSL fingerprint אם הלקוח מתחבר באמצעות HTTPS, ‏ HTTP/2 או HTTP/3.
tls_ja4_fingerprint	JA4 TLS/SSL fingerprint אם הלקוח מתחבר באמצעות HTTPS, ‏ HTTP/2 או HTTP/3.

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

• פרמטרים של TLS כשלא נעשה שימוש ב-TLS

• הכותרת {origin_request_header} כשהבקשה לא כוללת כותרת Origin

• משתני מיקום גיאוגרפיים כשהמיקום של כתובת ה-IP לא ידוע

הערכים הגיאוגרפיים הם הערכות שמבוססות על כתובת ה-IP של הלקוח. מעת לעת, Google מעדכנת את הנתונים שמהם נגזרים הערכים האלה כדי לשפר את הדיוק שלהם ולשקף שינויים גיאוגרפיים ופוליטיים. גם אם הכותרת המקורית X-Forwarded-For מכילה פרטי מיקום תקינים, Google מעריכה את מיקומי הלקוחות באמצעות פרטי כתובת ה-IP של המקור שכלולים בחבילות שהתקבלו על ידי מאזן העומסים.

כותרות מותאמות אישית של TLS הדדי

אם מוגדר TLS דו-צדדי (mTLS) ב-TargetHttpsProxy של מאזן העומסים, משתני הכותרת הנוספים הבאים זמינים:

משתנה	תיאור
client_cert_present	true אם הלקוח סיפק אישור במהלך לחיצת היד של TLS, אחרת false.
client_cert_chain_verified	‫true אם שרשרת אישורי הלקוח מאומתת מול TrustStore שהוגדר; אחרת, false.
client_cert_error	מחרוזות מוגדרות מראש שמייצגות את תנאי השגיאה. מידע נוסף על מחרוזות השגיאה זמין במאמר בנושא מצבי אימות של לקוח mTLS.
client_cert_sha256_fingerprint	טביעת אצבע מסוג SHA-256 של אישור הלקוח בקידוד Base64.
client_cert_serial_number	המספר הסידורי של אישור הלקוח. אם המספר הסידורי ארוך מ-50 בייטים, המחרוזת client_cert_serial_number_exceeded_size_limit מתווספת ל- client_cert_error, והמספר הסידורי מוגדר כמחרוזת ריקה.
client_cert_spiffe_id	‫ מזהה SPIFFE מהשדה של שם הנושא החלופי (SAN). אם הערך לא תקין או שהוא גדול מ-2048 בייט, מזהה ה-SPIFFE מוגדר כמחרוזת ריקה. אם מזהה ה-SPIFFE ארוך מ-2,048 בייט, המחרוזת client_cert_spiffe_id_exceeded_size_limit מתווספת ל- client_cert_error.
client_cert_uri_sans	רשימה מופרדת בפסיקים של תוספי SAN מסוג URI בקידוד Base64. תוספי ה-SAN מחולצים מאישור הלקוח. מזהה ה-SPIFFE לא נכלל בשדה client_cert_uri_sans. אם המחרוזת client_cert_uri_sans ארוכה מ-512 בייט, המחרוזת client_cert_uri_sans_exceeded_size_limit מתווספת ל-client_cert_error, והרשימה המופרדת בפסיקים מוגדרת כמחרוזת ריקה.
client_cert_dnsname_sans	רשימה מופרדת בפסיקים בקידוד Base64 של תוספי ה-SAN מסוג DNSName. תוספי ה-SAN מחולצים מאישור הלקוח. אם client_cert_dnsname_sans ארוך מ-512 בייטים, המחרוזת client_cert_dnsname_sans_exceeded_size_limit מתווספת ל-client_cert_error, והרשימה המופרדת בפסיקים מוגדרת כמחרוזת ריקה.
client_cert_valid_not_before	חותמת זמן (בפורמט מחרוזת תאריך RFC 3339) שלפניו אישור הלקוח לא תקף. לדוגמה, 2022-07-01T18:05:09+00:00.
client_cert_valid_not_after	חותמת זמן (בפורמט מחרוזת תאריך RFC 3339) שאחריה אישור הלקוח לא תקף. לדוגמה, 2022-07-01T18:05:09+00:00.
client_cert_issuer_dn	השדה המלא של הרשות המנפיקה מהאישור בקידוד Base64. אם המחרוזת client_cert_issuer_dn ארוכה מ-512 בייטים, המחרוזת client_cert_issuer_dn_exceeded_size_limit מתווספת למחרוזת client_cert_error, והמחרוזת client_cert_issuer_dn מוגדרת כמחרוזת ריקה.
client_cert_subject_dn	השדה 'נושא' המלא מהאישור בקידוד Base64. אם המחרוזת client_cert_subject_dn ארוכה מ-512 בייטים, המחרוזת client_cert_subject_dn_exceeded_size_limit מתווספת ל-client_cert_error, והמחרוזת client_cert_subject_dn מוגדרת כמחרוזת ריקה.
client_cert_leaf	אישור העלה של הלקוח לחיבור mTLS שנוצר כשהאישור עבר אימות. הקידוד של האישור תואם ל-RFC 9440: אישור DER בינארי מקודד באמצעות Base64 (ללא מעברי שורה, רווחים או תווים אחרים מחוץ לאלפבית Base64) ומוגבל באמצעות נקודתיים משני הצדדים. אם הערך של client_cert_leaf חורג מ-16KB ללא קידוד, המחרוזת client_cert_validated_leaf_exceeded_size_limit מתווספת ל-client_cert_error, והערך של client_cert_leaf מוגדר כמחרוזת ריקה.
client_cert_chain	רשימת האישורים המופרדת בפסיקים, בסדר TLS רגיל, של שרשרת אישורי הלקוח לחיבור mTLS שנוצר, שבו אישור הלקוח עבר אימות, לא כולל אישור העלה. קידוד האישור תואם ל-RFC 9440. אם הגודל המשולב של client_cert_leaf ושל client_cert_chain לפני קידוד Base64 חורג מ-16KB, המחרוזת client_cert_validated_chain_exceeded_size_limit מתווספת ל-client_cert_error, והערך של client_cert_chain מוגדר כמחרוזת ריקה.

מגבלות

יש הגבלות:

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

• אין תמיכה במשתני הכותרת המותאמים אישית הבאים במאזני עומסים חיצוניים אזוריים של אפליקציות:

  • cdn_cache_id
  • cdn_cache_status
  • client_region_subdivision
  • client_city
  • client_city_lat_long