From 44ca9d1562c8606abc82b5d6bcaa01ba743c72ec Mon Sep 17 00:00:00 2001 From: amitmaurya07 Date: Wed, 20 Nov 2024 20:38:15 +0530 Subject: [PATCH 1/6] Add BackendLBPolicyDocs --- site-src/api-types/backendlbpolicy.md | 93 +++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 site-src/api-types/backendlbpolicy.md diff --git a/site-src/api-types/backendlbpolicy.md b/site-src/api-types/backendlbpolicy.md new file mode 100644 index 0000000000..9f07afc52f --- /dev/null +++ b/site-src/api-types/backendlbpolicy.md @@ -0,0 +1,93 @@ +# BackendLBPolicy + +??? example "Experimental Channel since v1.0.0" + + The `BackendLBPolicy` resource is Alpha and has been part of + the Experimental Channel since `v1.0.0`. For more information on release + channels, refer to our [versioning guide](/concepts/versioning). + +`BackendLBPolicy` is a Gateway API type for handling load-balancing configuration +for the traffic between a Gateway and backend Pods through the Service API. + +## Background + +`BackendLBPolicy` specifically addresses the configuration of load balancing for traffic between the Gateway and backend services. This enables the Gateway to manage how traffic is distributed to backend Pods after routing has been completed. + +While other API objects exist for configuring routing and connection behavior, this API object allows users to specifically configure backend load-balancing behavior, such as session persistence and load-balancing algorithms. +For more information on load balancing configuration in the Gateway API, refer to Load Balancing configuration in Gateway API. + +BackendLBPolicy is a Direct [PolicyAttachment](https://gateway-api.sigs.k8s.io/reference/policy-attachment/) +applied to a Service that accesses a backend. It does not include defaults or overrides and resides in the same namespace as the targeted backend. + +In future, BackendLBPolicy enhancements will be there which add additional configurations which includes connection draining, logging that makes central manageable backend traffic policies. + +## Features + +BackendLBPolicy API currently supports Session persistence configuration. + +- Cookie-Based Persistence - Core feture +- Header-Based Persistence - It will be extended feature and optional. + +## Spec + +The specification of a `BackendLBPolicy` consists of: + +- `TargetRefs` - Defines the targeted API object of the policy. Only Service is allowed. +- `SessionPersistence` - Configure the Session Persistence type (Cookie or Header) + +The following chart outlines the object definitions and relationship: +```mermaid +flowchart LR + backendLBPolicy[["backendLBPolicy
BackendLBPolicySpec: spec
PolicyStatus: status"]] + spec[["spec
PolicyTargetReferenceWithSectionName: targetRefs
SessionPersistence: sessionPersistence"]] + status[["status
[ ]PolicyAncestorStatus: ancestors"]] + sessionPersistence[["sessionPersistence
SessionPersistenceType: type
CookieConfig: cookieSettings"]] + ancestorStatus[["ancestors
AncestorRef: parentReference
GatewayController: controllerName
[]Condition: conditions"]] + targetRefs[[targetRefs
]] + service["service"] + backendLBPolicy -->spec + backendLBPolicy -->status + spec -->targetRefs & sessionPersistence + status -->ancestorStatus + targetRefs -->service + note[Future additions:
Load balancing algorithm, timeout, logging] + style note fill:#fff + sessionPersistence -.- note +``` + +The following illustrates a BackendLBPolicy integrates with a Gateway serving a backend: +```mermaid +flowchart LR + client(["Client"]) + gateway["Gateway"] + style gateway fill:#02f,color:#fff + httproute["HTTP
Route"] + style httproute fill:#02f,color:#fff + service["Service"] + style service fill:#02f,color:#fff + pod1["Pod"] + style pod1 fill:#02f,color:#fff + pod2["Pod"] + style pod2 fill:#02f,color:#fff + client -.->|HTTP
request| gateway + gateway --> httproute + httproute -.->|BackendLBPolicy|service + service --> pod1 & pod2 +``` + +### Targeting backends + +A BackendLBPolicy targets a backend Pod (or set of Pods) via one or more TargetRefs to a Service. This TargetRef is a +required object reference that specifies a Service by its Name, Kind (Service), and optionally its Namespace and Group. + +!!! info "Restrictions" + + - Cross-namespace for `BackendLBPolicy` are not allowed. + +### Session Persistence + +This field defined the settings for session between the Gateway and the backend. It supports two types: + + - Cookie-Based Session Persistence - It ensures the client are consistently routed to the same backend using a cookie. + - Header-Based Session Persistence - It uses the custom header for session tracking. + From 66b165a1bf85b0a0f4d8dd735f7d1b6d58262936 Mon Sep 17 00:00:00 2001 From: Amit Maurya <78417464+amitmaurya07@users.noreply.github.com> Date: Thu, 21 Nov 2024 13:50:29 +0530 Subject: [PATCH 2/6] Update site-src/api-types/backendlbpolicy.md Co-authored-by: Nick Young --- site-src/api-types/backendlbpolicy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site-src/api-types/backendlbpolicy.md b/site-src/api-types/backendlbpolicy.md index 9f07afc52f..12d721dc74 100644 --- a/site-src/api-types/backendlbpolicy.md +++ b/site-src/api-types/backendlbpolicy.md @@ -19,7 +19,7 @@ For more information on load balancing configuration in the Gateway API, refer t BackendLBPolicy is a Direct [PolicyAttachment](https://gateway-api.sigs.k8s.io/reference/policy-attachment/) applied to a Service that accesses a backend. It does not include defaults or overrides and resides in the same namespace as the targeted backend. -In future, BackendLBPolicy enhancements will be there which add additional configurations which includes connection draining, logging that makes central manageable backend traffic policies. +In future, BackendLBPolicy enhancements may be added for features like connection draining or logging. ## Features From 0bee96758241e3f20ab7d82001d0d4075ac7e79c Mon Sep 17 00:00:00 2001 From: Amit Maurya <78417464+amitmaurya07@users.noreply.github.com> Date: Thu, 21 Nov 2024 13:50:40 +0530 Subject: [PATCH 3/6] Update site-src/api-types/backendlbpolicy.md Co-authored-by: Nick Young --- site-src/api-types/backendlbpolicy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site-src/api-types/backendlbpolicy.md b/site-src/api-types/backendlbpolicy.md index 12d721dc74..77912a1296 100644 --- a/site-src/api-types/backendlbpolicy.md +++ b/site-src/api-types/backendlbpolicy.md @@ -25,7 +25,7 @@ In future, BackendLBPolicy enhancements may be added for features like connectio BackendLBPolicy API currently supports Session persistence configuration. -- Cookie-Based Persistence - Core feture +- Cookie-Based Persistence - Core feature for the object. Although supporting `BackendLBPolicy` is optional, if the object is supported, then Cookie-Based Persistence must also be supported.; - Header-Based Persistence - It will be extended feature and optional. ## Spec From 5f0cfbceada8cd455b08b5184cbce988c5fa1c25 Mon Sep 17 00:00:00 2001 From: Amit Maurya <78417464+amitmaurya07@users.noreply.github.com> Date: Thu, 21 Nov 2024 13:50:48 +0530 Subject: [PATCH 4/6] Update site-src/api-types/backendlbpolicy.md Co-authored-by: Nick Young --- site-src/api-types/backendlbpolicy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site-src/api-types/backendlbpolicy.md b/site-src/api-types/backendlbpolicy.md index 77912a1296..64ef3c19cd 100644 --- a/site-src/api-types/backendlbpolicy.md +++ b/site-src/api-types/backendlbpolicy.md @@ -26,7 +26,7 @@ In future, BackendLBPolicy enhancements may be added for features like connectio BackendLBPolicy API currently supports Session persistence configuration. - Cookie-Based Persistence - Core feature for the object. Although supporting `BackendLBPolicy` is optional, if the object is supported, then Cookie-Based Persistence must also be supported.; -- Header-Based Persistence - It will be extended feature and optional. +- Header-Based Persistence - Extended feature for the object. Supporting `BackendLBPolicy` is optional, and if it is supported, then supporting Header-Based persistence is also optional. ## Spec From 8399b7818a911a06686930b653252c59244cd1b3 Mon Sep 17 00:00:00 2001 From: Amit Maurya <78417464+amitmaurya07@users.noreply.github.com> Date: Thu, 21 Nov 2024 13:50:57 +0530 Subject: [PATCH 5/6] Update site-src/api-types/backendlbpolicy.md Co-authored-by: Nick Young --- site-src/api-types/backendlbpolicy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site-src/api-types/backendlbpolicy.md b/site-src/api-types/backendlbpolicy.md index 64ef3c19cd..b65dfc8def 100644 --- a/site-src/api-types/backendlbpolicy.md +++ b/site-src/api-types/backendlbpolicy.md @@ -82,7 +82,7 @@ required object reference that specifies a Service by its Name, Kind (Service), !!! info "Restrictions" - - Cross-namespace for `BackendLBPolicy` are not allowed. + - Cross-namespace target references for `BackendLBPolicy` are not allowed. ### Session Persistence From c0d35bc40d3df323710b2a9de1ef3b9ebe870f11 Mon Sep 17 00:00:00 2001 From: Amit Maurya <78417464+amitmaurya07@users.noreply.github.com> Date: Thu, 21 Nov 2024 13:51:07 +0530 Subject: [PATCH 6/6] Update site-src/api-types/backendlbpolicy.md Co-authored-by: Nick Young --- site-src/api-types/backendlbpolicy.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/site-src/api-types/backendlbpolicy.md b/site-src/api-types/backendlbpolicy.md index b65dfc8def..d24b9049c7 100644 --- a/site-src/api-types/backendlbpolicy.md +++ b/site-src/api-types/backendlbpolicy.md @@ -88,6 +88,6 @@ required object reference that specifies a Service by its Name, Kind (Service), This field defined the settings for session between the Gateway and the backend. It supports two types: - - Cookie-Based Session Persistence - It ensures the client are consistently routed to the same backend using a cookie. - - Header-Based Session Persistence - It uses the custom header for session tracking. + - Cookie-Based Session Persistence - Ensures the client are consistently routed to the same backend using a cookie. + - Header-Based Session Persistence - Uses the custom header for session tracking.