From 448785d83058b8866fee9b123c7b1d98e2c2e651 Mon Sep 17 00:00:00 2001
From: Sheddy <shedrack.akintayo@traefik.io>
Date: Wed, 7 May 2025 08:16:04 +0100
Subject: [PATCH] Add multi-tenant TLS guidance to the docs

---
 docs/content/middlewares/http/buffering.md    |  2 +-
 .../{best-practices => }/content-length.md    |  0
 .../tls-certs-in-multi-tenant-kubernetes.md   | 38 +++++++++++++++++++
 docs/mkdocs.yml                               |  4 +-
 4 files changed, 41 insertions(+), 3 deletions(-)
 rename docs/content/security/{best-practices => }/content-length.md (100%)
 create mode 100644 docs/content/security/tls-certs-in-multi-tenant-kubernetes.md

diff --git a/docs/content/middlewares/http/buffering.md b/docs/content/middlewares/http/buffering.md
index 47c7d3022..8a575d566 100644
--- a/docs/content/middlewares/http/buffering.md
+++ b/docs/content/middlewares/http/buffering.md
@@ -334,4 +334,4 @@ The retry expression is defined as a logical combination of the functions below
 
 ### Content-Length
 
-See [Best Practices: Content‑Length](../../security/best-practices/content-length.md)
\ No newline at end of file
+See [Best Practices: Content‑Length](../../security/content-length.md)
diff --git a/docs/content/security/best-practices/content-length.md b/docs/content/security/content-length.md
similarity index 100%
rename from docs/content/security/best-practices/content-length.md
rename to docs/content/security/content-length.md
diff --git a/docs/content/security/tls-certs-in-multi-tenant-kubernetes.md b/docs/content/security/tls-certs-in-multi-tenant-kubernetes.md
new file mode 100644
index 000000000..8fd7ef959
--- /dev/null
+++ b/docs/content/security/tls-certs-in-multi-tenant-kubernetes.md
@@ -0,0 +1,38 @@
+---
+title: "TLS Certificates in Multi‑Tenant Kubernetes"
+description: "Isolate TLS certificates in multi‑tenant clusters by keeping Secrets and routes in the same namespace and disabling cross‑namespace look‑ups in Traefik. Read the technical guidelines."
+---
+
+# TLS Certificates in Multi‑Tenant Kubernetes
+
+In a shared cluster, different teams can create `Ingress` or `IngressRoute` objects that Traefik consumes.
+
+Traefik does not support multi-tenancy when using the Kubernetes `Ingress` or `IngressRoute` specifications due to the way TLS certificate management is handled.
+
+At the core of this limitation is the TLS Store, which holds all the TLS certificates used by Traefik. 
+As this Store is global in Traefik, it is shared across all namespaces, meaning any `Ingress` or `IngressRoute` in the cluster can potentially reference or affect TLS configurations intended for other tenants.
+
+This lack of isolation poses a risk in multi-tenant environments where different teams or applications require strict boundaries between resources, especially around sensitive data like TLS certificates.
+
+In contrast, the [Kubernetes Gateway API](../providers/kubernetes-gateway.md) provides better primitives for secure multi-tenancy. 
+Specifically, the `Listener` resource in the Gateway API allows administrators to explicitly define which Route resources (e.g., `HTTPRoute`) are permitted to bind to which domain names or ports. 
+This capability enforces stricter ownership and isolation, making it a safer choice for multi-tenant use cases.
+
+## Recommended setup
+
+When strict boundaries are required between resources and teams, we recommend using one Traefik instance per tenant.
+
+In Kubernetes one way to isolate a tenant is to restrict it to a namespace.
+In that case, the namespace options from the Kubernetes [CRD](../providers/kubernetes-crd.md#namespaces) and [Ingress](../providers/kubernetes-ingress.md#namespaces) providers can be leveraged.  
+
+!!! tip "Dedicate one Traefik instance per tenant using the Helm Chart" 
+
+    ```yaml
+    providers:
+      kubernetesCRD:
+        namespaces:
+          - tenant
+      kubernetesIngress:
+        namespaces:
+          - tenant
+    ```
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index f6ac2d1d7..e7a270874 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -167,8 +167,8 @@ nav:
           - 'Elastic': 'observability/tracing/elastic.md'
           - 'OpenTelemetry': 'observability/tracing/opentelemetry.md'
   - 'Security':
-    - 'Best Practices': 
-          - 'security/best-practices/content-length.md'
+        - 'Content-Length': 'security/content-length.md'
+        - 'TLS in Multi-Tenant Kubernetes': 'security/tls-certs-in-multi-tenant-kubernetes.md'
   - 'User Guides':
       - 'Kubernetes and Let''s Encrypt': 'user-guides/crd-acme/index.md'
       - 'gRPC Examples': 'user-guides/grpc.md'