סקירה כללית של היתרונות המרכזיים

Service Extensions מאפשרים לכם להשתמש ב-callout משרתי Proxy ברשת. רוב מאזני העומסים של האפליקציות תומכים בנכסי היתרונות המרכזיים. Secure Web Proxy (בגרסת Preview) תומך גם בתוספי יתרונות מרכזיים.

זרימת נתונים של יתרונות מרכזיים

שרת proxy לרשת מתקשר עם callout באמצעות אחד מפרוטוקולי Envoy gRPC הבאים:

• הפרוטוקול External Processing או ext_proc.

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

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

• פרוטוקול ההרשאה החיצונית או ext_authz.

  הפרוטוקול הזה נתמך רק בתוספי הרשאה. התמיכה ב-ext_authz היא בגרסת Preview.

  פרוטוקול ext_authz מעביר החלטות הרשאה לבקשות נכנסות לשירות חיצוני ועצמאי. ה-API הזה מאפשר לשירות התוסף להגיב לאירועים במחזור החיים של בקשת HTTP, כדי לקבל החלטת הרשאה מורכבת על ידי בדיקת הכותרות או המטא-נתונים של הבקשה.

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

אפשר לפרוס את שירותי התוספים האלה במכונות וירטואליות (VM) או ב-GKE, ולהגדיר קבוצת מכונות או קבוצת נקודות קצה ברשת (NEG) שתייצג את נקודות הקצה של השירותים האלה.

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

בתרשים הבא מוצג תרחיש פריסה לדוגמה. אפשר לפרוס את שירות ה-backend של ה-callout עם שרת gRPC במשאב מחשוב שמנוהל על ידי המשתמש – כמו מכונה וירטואלית או אשכול Google Kubernetes Engine ‏ (GKE) – ולהציג אותו למאזן העומסים כשירות לקצה העורפי רגיל.

איך פועלים נכסי היתרונות המרכזיים ב-ext_proc

זוהי גרסה מקוצרת של ext_proc gRPC API.

// The gRPC API to be implemented by the external processing server
service ExternalProcessor {
  rpc Process(stream ProcessingRequest) returns (stream ProcessingResponse) {
  }
}

// Envoy sets one of these fields depending on the processing stage.
message ProcessingRequest {
  oneof request {
    HttpHeaders request_headers = 2;
    HttpHeaders response_headers = 3;
    HttpBody request_body = 4;
    HttpBody response_body = 5;
  }
}

message ProcessingResponse {
  oneof response {
    HeadersResponse request_headers = 1;
    HeadersResponse response_headers = 2;
    BodyResponse request_body = 3;
    BodyResponse response_body = 4;

    ImmediateResponse immediate_response = 7;
  }
}

אחרי קבלת הכותרות של בקשת HTTP, שרתי proxy של מאזן עומסים של אפליקציות ושל Secure Web Proxy שולחים את ההודעה ProcessingRequest לשירות התוסף, כשהשדה request_headers מוגדר לכותרות ה-HTTP מהלקוח.

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

באירועים REQUEST_HEADER ו-RESPONSE_HEADER, שירות התוסף יכול לשנות את כותרות ה-HTTP בבקשה או בתגובה. השירות יכול להוסיף, לשנות או למחוק כותרות על ידי הגדרת השדה request_headers או response_headers בהודעה ProcessingResponse בצורה המתאימה. משתמשים בשדה raw_value לכותרות.

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

תוספי קצה, הרשאה ומסלול תומכים רק בכותרות HTTP. התוספים האלה לא יכולים לבדוק או לשנות את גופי ה-HTTP.

בתוספים של מסלולים ותנועה, אפשר להפעיל נכסי יתרונות מרכזיים באופן אסינכרוני כשערך המאפיין observabilityMode של התוסף מוגדר כ-true ומצב העיבוד של גוף הבקשה הוא STREAMED (ברירת מחדל). השיחות עם ה-backend של התוסף מתבצעות באופן אסינכרוני, בלי להשהות את העיבוד של הבקשה הנוכחית. המערכת מתעלמת מהתשובות, אם יש כאלה.

מאפייני גישה בהסברים

במקרה של תוספי יתרונות מרכזיים שמשתמשים בפרוטוקול ext_proc, המאפיינים שהוגדרו נשלחים בהודעה ProcessingRequest. המאפיינים מאוחסנים בשדה מיפוי, בדרך כלל תחת מפתח כמו envoy.filters.http.ext_proc.

המפתחות במיפוי תואמים לשמות המאפיינים שציינתם בשדה forwardAttributes בהגדרות התוסף.

בדוגמה הבאה אפשר לראות את המבנה של ProcessingRequest.attributes:

attributes {
  key: "envoy.filters.http.ext_proc"
  value {
    fields {
      key: "request.host"
      value { string_value: "example.com" }
    }
    fields {
      key: "source.client_region"
      value { string_value: "US" }
    }
    // ... other forwarded attributes
  }
}

ההטמעה של שירות gRPC יכולה לגשת לערכים האלה מהמיפוי בהודעות ProcessingRequest שקיבלתם.

איך פועלים נכסי היתרונות המרכזיים ב-ext_authz

‫ext_authz API תומך רק בתוספי יתרונות מרכזיים של הרשאות.

גרסה מקוצרת של ה-API מוצגת בהמשך.

// A generic interface for performing authorization checks on incoming
// requests to a networked service.
service Authorization {
  // Performs an authorization check based on the attributes associated with
  // the incoming request and return status.
  rpc Check(CheckRequest) returns (CheckResponse) {
  }
}

message CheckRequest {
  // The request attributes.
  AttributeContext attributes = 1;
}

message CheckResponse {
  google.rpc.Status status = 1;
  oneof http_response {
    DeniedHttpResponse denied_response = 2;
    OkHttpResponse ok_response = 3;
  }
  google.protobuf.Struct dynamic_metadata = 4;
}

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

שירות התוסף צריך להשיב להודעה CheckRequest בהודעה תואמת CheckResponse שמכילה את הפרטים הבאים:

• ‫status: מציין את הסטטוס. ‫OK מציין שהבקשה מותרת. כל סטטוס אחר מציין שהבקשה נדחתה.

• ‫denied_response או ok_response: מציין אם התשובה מותרת או נדחית. לשדה הזה מצורפים מאפייני תגובת ה-HTTP הרלוונטיים לבדיקת הרשאה.

  • השדה ok_response משמש כשהשירות לאימות הרשאות מאשר את הבקשה. השירות יכול לשנות, להוסיף או להסיר כותרות של בקשות מקוריות ולעדכן כותרות של תגובות HTTP שנשלחות ללקוח. משתמשים בשדה raw_value לכותרות.

  • השדה denied_response משמש כשהבקשה נדחית על ידי שירות ההרשאות. השירות יכול לעדכן כותרות תגובת HTTP שנשלחות ללקוח.

  אם שירות התוסף מחזיר שם או ערך של כותרת שלא מותרים דרך ההודעה CheckResponse, הבקשה נדחית עם קוד הסטטוס 500 Internal Error. מידע על כותרות שאסורות מופיע במאמר בנושא מגבלות על שינוי כותרות.

• ‫dynamic_metadata: כולל מטא-נתונים אופציונליים לשימוש של כל התוספים שמופעלים אחרי תוסף ההרשאה, כמו תוספי תנועה.

מצבי עיבוד של הגוף

בתוספים שתומכים בעיבוד גוף הבקשה, אפשר להגדיר אחד משני מצבי השליחה הבאים לעיבוד גוף הבקשה והתגובה על ידי הגדרת הערך של השדות request_body_send_mode או response_body_send_mode, בהתאמה.

מצב ברירת המחדל הוא STREAMED, והוא מומלץ לרוב תרחישי השימוש.

קצה עורפי נתמך לשירותי קצה עורפי של הערות קריאה בניהול המשתמשים

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

• כל קצוות העורף של קבוצות מופעי מכונה מנוהלים ולא מנוהלים
• כל ה-NEGs האזוריים
• כל קבוצות ה-NEG של קישוריות היברידית
• קבוצות של נקודות קצה ברשת (NEGs) של Private Service Connect שמפנות לשירותי VPC
• קבוצות של נקודות קצה ברשת בלי שרת (serverless) שמפנות לשירותי Cloud Run

המלצות לאופטימיזציה של יתרונות מרכזיים

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

כדי לצמצם את זמן האחזור, כדאי לבצע את האופטימיזציות הבאות:

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

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

• כשמשתמשים במאזן עומסים גלובלי חיצוני של אפליקציות (ALB), צריך למקם את ה-backends של שירותי ה-callout באזורים הגיאוגרפיים שבהם נמצאות המכונות הווירטואליות של מאזן העומסים הרגיל, עומסי העבודה של GKE ופונקציות Cloud Run.

• אם אפשר, כדאי להגדיר את התוסף כך שיעבד רק את הנתונים שאתם צריכים. לדוגמה, כדי לשנות רק את כותרות הבקשה לתוספי ניתוב ותנועה, מגדירים את השדה supported_events בתוסף ל-REQUEST_HEADERS.

המגבלות של רכיבי ה-Callout

בקטע הזה מפורטות כמה מגבלות שקשורות ליתרונות המרכזיים.

מגבלות על שינוי כותרות

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

• אין תמיכה בשינוי של הכותרות הבאות:

  • X-user-IP
  • CDN-Loop
  • כותרות שמתחילות ב-X-Forwarded, ב-X-Google, ב-X-GFE או ב-X-Amz-
  • connection
  • keep-alive
  • transfer-encoding, te
  • upgrade
  • proxy-connection, proxy-authenticate, proxy-authorization
  • trailers

  בתוספים של תעבורת נתונים והרשאות, גם לא אפשרי מניפולציה של כותרות עבור אלה: :method,‏ :authority,‏ :scheme או כותרות של מארחים.

• כששרת gRPC מציין ערכי כותרת ב-HeaderMutation, המערכת מתעלמת מהשדה value.

מגבלות בעיבוד של נתוני גוף

אלה המגבלות שחלות על לקוחות ושרתים עורפיים של HTTP/1.1 בהקשר של גוף ההודעה, שרלוונטיות ל-ext_proc אבל לא ל-ext_authz.

• כשמגדירים REQUEST_BODY או RESPONSE_BODY לתוסף, אם ה-proxy מקבל בקשה תואמת, הוא מסיר את הכותרת Content-Length מהתשובה ועובר לקידוד של גוף התשובה במקטעים.

• במהלך סטרימינג של גוף ההודעה לשרת ext_proc, בסוף, יכול להיות שהפרוקסי ישלח הודעת ProcessingRequest עם גוף ריק שבו הערך של end_stream הוא true, כדי לציין שהסטרימינג הסתיים.

מגבלות אחרות

אלה ההגבלות על הודעות תגובה של gRPC:

• הגודל המקסימלי של הודעת תגובה הוא 128 kB. אם הודעה שמתקבלת חורגת מהמגבלה הזו, הזרם נסגר עם שגיאה RESOURCE_EXHAUSTED.

• שירות ה-backend של שיחות יוצאות לא יכול להשתמש במדיניות של Cloud Armor,‏ IAP או Cloud CDN.

• שירות לקצה העורפי של ה-callout חייב להשתמש ב-HTTP/2 כפרוטוקול.

• בתוספים של הרשאות, מאזן העומסים לא מעביר גוף בקשה לשירות הקצה העורפי של ה-callout.

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

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

• הגדרת שירות קצה עורפי של התקשרות (callout) שמנוהל על ידי משתמש

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

• הגדרת תוסף הרשאה

• הגדרת תוסף ל-Secure Web Proxy

• הגדרת תוסף תנועה

• הגדרת תוסף להתקשרות עם שירות של Google