From 8c0fc2cc444eb0f41f0924f6fdd92f07d30096ec Mon Sep 17 00:00:00 2001
From: Lohit Kolluri <lohitkolluri@gmail.com>
Date: Tue, 16 Jun 2026 23:07:01 +0530
Subject: [PATCH] docs(best-practice): fix HTTP01 NetworkPolicy examples -
 correct port, traffic flow, and selectors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Address all review comments on PR #2151:

- Fix solver port 8080 → 8089 to match cert-manager's
  acmeSolverListenPort (pkg/issuer/acme/http/http.go:49)
- Correct the traffic flow documentation: the controller does NOT
  connect directly to solver pods. The self-check (testReachability)
  goes through port 80 via the ingress/load balancer, the same path
  the ACME server uses.
- Replace the ingress rule source from cert-manager namespace to the
  ingress controller namespace (namespaceSelector-based), since the
  ingress controller is the component that routes traffic to solver
  pods on port 8089.
- Remove the incorrect egress-from-controller-to-solver-pods example
  (wrong port, wrong selector, wrong flow - already covered by the
  existing port-80 egress rule for self-checks).
- Remove the redundant API server port example (already documented
  in the Network Requirements list and covered by default egress rules).
- Update the values.yaml comment on the port-80 self-check rule to
  accurately describe the traffic flow.

Closes #2151
Signed-off-by: Lohit Kolluri <lohitkolluri@gmail.com>
---
 content/docs/installation/best-practice.md    | 44 +++++++++++++++++++
 .../best-practice/values.best-practice.yaml   |  5 ++-
 2 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/content/docs/installation/best-practice.md b/content/docs/installation/best-practice.md
index 13ea97fc34b..6ceff6b6f70 100644
--- a/content/docs/installation/best-practice.md
+++ b/content/docs/installation/best-practice.md
@@ -155,6 +155,50 @@ Here is an overview of the network requirements:
    The cert-manager controller, webhook, and cainjector have metrics servers which listen for HTTP connections on TCP port 9402.
    Create a network policy which allows access to these services from your chosen metrics collector.
 
+### NetworkPolicy Examples for HTTP01 Challenges
+
+If you use an ACME Issuer configured for HTTP01,
+cert-manager dynamically creates solver pods in the namespace of the Challenge resource.
+These pods are labelled with `acme.cert-manager.io/http01-solver: "true"` and listen on TCP port 8089.
+
+The traffic flow for HTTP01 validation is:
+
+1. **ACME server (e.g. Let's Encrypt) → Your ingress/load balancer → Ingress controller → solver pod** (port 8089)
+2. **cert-manager controller → ingress/load balancer** (port 80) for the self-check — this follows the same path as the ACME server.
+
+The cert-manager controller does **not** connect directly to the solver pod.
+The controller's self-check ([`testReachability`](https://github.com/cert-manager/cert-manager/blob/main/pkg/issuer/acme/http/http.go#L215))
+sends an HTTP GET to the challenge URL on port 80 through your ingress,
+the same path the ACME server will use.
+The default egress rules in the Helm chart and the example rules below already permit port 80 outbound traffic for this purpose.
+
+The NetworkPolicy you need is an **ingress rule** in the solver pod's namespace
+that allows traffic from your **ingress controller** to the solver pods on TCP port 8089:
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: allow-acmesolver-from-ingress-controller
+spec:
+  podSelector:
+    matchLabels:
+      acme.cert-manager.io/http01-solver: "true"
+  ingress:
+  - from:
+    - namespaceSelector:
+        matchLabels:
+          kubernetes.io/metadata.name: ingress-nginx  # adjust for your ingress controller
+    ports:
+    - port: 8089
+      protocol: TCP
+```
+
+> ℹ️ Replace `ingress-nginx` with the namespace of your ingress controller
+> (e.g., `istio-system` for Istio, `projectcontour` for Contour, `traefik` for Traefik, etc.).
+> The `namespaceSelector` above uses `kubernetes.io/metadata.name`, which is automatically added by Kubernetes 1.21+.
+> If you are on an older cluster, ensure the ingress controller's namespace has a matching label.
+
 ## Isolate cert-manager on dedicated node pools
 
 cert-manager is a cluster scoped operator and you should treat it as part of your platform's control plane.
diff --git a/public/docs/installation/best-practice/values.best-practice.yaml b/public/docs/installation/best-practice/values.best-practice.yaml
index 15ab33bf4a1..c8eb1679bab 100644
--- a/public/docs/installation/best-practice/values.best-practice.yaml
+++ b/public/docs/installation/best-practice/values.best-practice.yaml
@@ -60,8 +60,9 @@ networkPolicy:
   # with Network policies enabled. In production you should edit or remove these
   # to match your requirements.
 
-  # Example: Allow access to the HTTP01 solver pod for ACME HTTP01 self-checks
-  # Only needed if your cluster users use the ACME issuer with HTTP01
+  # Example: Allow the controller to reach the challenge URL for ACME HTTP01 self-checks.
+  # The controller performs the self-check via the ingress (port 80), not directly to the solver pod.
+  # Only needed if your cluster users use the ACME issuer with HTTP01.
   - ports:
     - port: 80
       protocol: TCP