diff --git a/site-src/api-types/backendlbpolicy.md b/site-src/api-types/backendlbpolicy.md new file mode 100644 index 0000000000..d24b9049c7 --- /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 may be added for features like connection draining or logging. + +## Features + +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 - Extended feature for the object. Supporting `BackendLBPolicy` is optional, and if it is supported, then supporting Header-Based persistence is also 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 target references 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 - Ensures the client are consistently routed to the same backend using a cookie. + - Header-Based Session Persistence - Uses the custom header for session tracking. +