From 0605f8bf09a985cb343b8e6155681ce3047e594d Mon Sep 17 00:00:00 2001
From: Michel Loiseleur <97035654+mloiseleur@users.noreply.github.com>
Date: Wed, 23 Oct 2024 11:10:04 +0200
Subject: [PATCH] Document nativeLBByDefault annotation on Kubernetes Gateway
 provider

---
 docs/content/providers/kubernetes-gateway.md  | 24 +++++++++++++++++
 .../routing/providers/kubernetes-gateway.md   | 27 +++++++++++++++++++
 2 files changed, 51 insertions(+)

diff --git a/docs/content/providers/kubernetes-gateway.md b/docs/content/providers/kubernetes-gateway.md
index a6291db0d..9f2201dee 100644
--- a/docs/content/providers/kubernetes-gateway.md
+++ b/docs/content/providers/kubernetes-gateway.md
@@ -304,6 +304,30 @@ providers:
 --providers.kubernetesgateway.labelselector="app=traefik"
 ```
 
+### `nativeLBByDefault`
+
+_Optional, Default: false_
+
+Defines whether to use Native Kubernetes load-balancing mode by default.
+For more information, please check out the `traefik.io/service.nativelb` [service annotation documentation](../routing/providers/kubernetes-gateway.md#native-load-balancing).
+
+```yaml tab="File (YAML)"
+providers:
+  kubernetesGateway:
+    nativeLBByDefault: true
+    # ...
+```
+
+```toml tab="File (TOML)"
+[providers.kubernetesGateway]
+  nativeLBByDefault = true
+  # ...
+```
+
+```bash tab="CLI"
+--providers.kubernetesgateway.nativeLBByDefault=true
+```
+
 ### `throttleDuration`
 
 _Optional, Default: 0_
diff --git a/docs/content/routing/providers/kubernetes-gateway.md b/docs/content/routing/providers/kubernetes-gateway.md
index 8e97b5c75..c2da4447c 100644
--- a/docs/content/routing/providers/kubernetes-gateway.md
+++ b/docs/content/routing/providers/kubernetes-gateway.md
@@ -723,4 +723,31 @@ X-Forwarded-Server: traefik-6b66d45748-ns8mt
 X-Real-Ip: 10.42.2.1
 ```
 
+## Native Load Balancing
+
+By default, Traefik sends the traffic directly to the pod IPs and reuses the established connections to the backends for performance purposes.
+
+It is possible to override this behavior and configure Traefik to send the traffic to the service IP.
+The Kubernetes service itself does the load balancing to the pods.
+It can be done with the annotation `traefik.io/service.nativelb` on the backend `Service`.
+
+By default, NativeLB is `false`.
+
+!!! info "Default value"
+
+    Note that it is possible to override the default value by using the option [`nativeLBByDefault`](../../providers/kubernetes-gateway.md#nativelbbydefault) at the provider level. 
+
+```yaml
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: myservice
+  namespace: default
+  annotations:
+    traefik.io/service.nativelb: "true"
+spec:
+[...]
+```
+
 {!traefik-for-business-applications.md!}
\ No newline at end of file