docs: add NetworkPolicy examples for HTTP01 challenges to best-practice page#2151
docs: add NetworkPolicy examples for HTTP01 challenges to best-practice page#2151karthikk022 wants to merge 1 commit into
Conversation
cert-manager-prow
Bot
added
the
dco-signoff: no
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
cert-manager-prow
Bot
added
the
size/M
✅ Deploy Preview for cert-manager ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
cert-manager-prow
Bot
added
dco-signoff: yes
Signed-off-by: karthikk022 <karthikchinnaiyan0223@gmail.com>
There was a problem hiding this comment.
Pull request overview
This PR extends the installation best-practices documentation by adding concrete Kubernetes NetworkPolicy examples and corresponding Helm values snippets aimed at supporting ACME HTTP01 challenge solver connectivity in clusters with enforced NetworkPolicies.
Changes:
- Added a new “NetworkPolicy Examples for HTTP01 Challenges” subsection with sample egress/ingress policies and notes about API server access and namespace labeling.
- Added an additional
networkPolicy.egressexample block to the best-practice Helm values file for HTTP01 solver pods.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
| content/docs/installation/best-practice.md | Adds a new documentation subsection with example NetworkPolicies and explanatory notes for HTTP01 solver connectivity. |
| public/docs/installation/best-practice/values.best-practice.yaml | Adds an example egress rule snippet intended to allow controller connectivity to HTTP01 solver pods. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 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 8080. | ||
|
|
| If you have Kubernetes NetworkPolicies enabled, you must configure two things: | ||
|
|
||
| 1. **Allow egress from the cert-manager controller to the solver pods** | ||
| 2. **Allow ingress to the solver pods from the cert-manager controller** |
| # Egress from cert-manager controller to HTTP01 solver pods | ||
| - to: | ||
| - podSelector: | ||
| matchLabels: | ||
| acme.cert-manager.io/http01-solver: "true" | ||
| ports: | ||
| - port: 8080 | ||
| protocol: TCP |
| Ensure your controller egress rules include port 6443 (or port 443) for the API server: | ||
|
|
| - from: | ||
| - namespaceSelector: | ||
| matchLabels: | ||
| kubernetes.io/metadata.name: cert-manager | ||
| ports: | ||
| - port: 8080 | ||
| protocol: TCP |
| # Example: Egress to HTTP01 solver pods (dynamic, created by cert-manager) | ||
| # Only needed if your cluster users use the ACME issuer with HTTP01 | ||
| # The solver pods are labelled with acme.cert-manager.io/http01-solver: "true" | ||
| # and listen on port 8080. | ||
| - to: | ||
| - podSelector: | ||
| matchLabels: | ||
| acme.cert-manager.io/http01-solver: "true" | ||
| ports: | ||
| - port: 8080 | ||
| protocol: TCP |
| Add the following egress rule to the cert-manager controller's NetworkPolicy | ||
| (if you are using the Helm chart, add this to the `networkPolicy.egress` list): | ||
|
|
wallrj-cyberark
left a comment
wallrj-cyberark
left a comment
There was a problem hiding this comment.
Thank you for working on this — concrete NetworkPolicy examples are a genuine gap in the docs, and it is clear you have put thought into the structure. However, there are several technical inaccuracies that need correcting before this can be merged.
I have verified each point below against the cert-manager source code and the existing documentation.
Wrong solver port
The PR uses port 8080 throughout (both in best-practice.md and values.best-practice.yaml), but the cert-manager HTTP01 solver listens on port 8089. See acmeSolverListenPort = 8089. The Copilot review independently flagged this.
Incorrect traffic flow
The PR describes the required policies as "egress from cert-manager controller to solver pods" and "ingress to solver pods from the cert-manager controller". This does not match how HTTP01 validation actually works.
The cert-manager controller's self-check (testReachability) performs an HTTP GET to the challenge URL on port 80, following any redirects — i.e. it connects through the ingress load balancer, the same path the ACME server will use. It does not connect directly to the solver pod on port 8089.
The traffic flow that actually needs NetworkPolicy rules is:
- Ingress controller → solver pod on port 8089 (so both the ACME server's challenge validation and the controller's self-check can reach the solver via the ingress)
- cert-manager controller → port 80/443 outbound (for the self-check) — this is already covered by the existing egress rules in
values.best-practice.yaml
The existing best-practice page already documents this in the "ACME (Let's Encrypt) → cert-manager (acmesolver)" numbered item. The closed PR #2110 by @lohitkolluri had a more accurate treatment of these flows — it may be a useful reference.
podSelector without namespaceSelector
The egress rule in the Helm values and in best-practice.md uses only a podSelector to match solver pods. Since NetworkPolicy pod selectors only match pods in the same namespace as the policy, and HTTP01 solver pods are created in the namespace of the Challenge resource (often not cert-manager), this rule will not match them. A namespaceSelector is needed as well.
Non-existent issue reference
The PR description references cert-manager/cert-manager#8875, which is actually a pull request (not an issue) — a companion PR by yourself that adds inline documentation to the upstream Helm chart's values.yaml. The underlying issue is cert-manager/cert-manager#2334. Note that erikgb and hjoshi123 both commented on #8875 suggesting the documentation belongs on the website rather than in the chart's values file. The useful part of #8875 — the cross-link from the Helm values to the website docs — would be worth keeping if the website content it links to is accurate.
Prior art
Several previous PRs have tackled this area:
- #2110 (closed) — comprehensive FAQ entry by @lohitkolluri. Correctly documented port 8089, the ingress-controller-to-solver flow, controller self-check via port 80, and startupapicheck-to-webhook policy. Had review feedback from erikgb.
- #2041 (merged) — added a "Network Policy Considerations" cross-reference section to the HTTP01 guide, pointing readers to the best-practice page.
- The best-practice page itself was written to address cert-manager/cert-manager#2334 (see the 2023 comment).
I would suggest reviewing the closed #2110 diff and the issue discussion on cert-manager/cert-manager#2334 (particularly the comments from @gramozkrasniqi about ingress controller access to solver pods on port 8089). A revised PR that accurately documents the ingress-controller → solver flow would be a welcome addition.
|
|
||
| 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 8080. |
There was a problem hiding this comment.
The solver pod listens on port 8089, not 8080. See acmeSolverListenPort = 8089.
|
|
||
| Add the following egress rule to the cert-manager controller's NetworkPolicy | ||
| (if you are using the Helm chart, add this to the `networkPolicy.egress` list): | ||
|
|
There was a problem hiding this comment.
This is not accurate. The cert-manager controller does not connect directly to the solver pod. The self-check (testReachability) makes an HTTP GET on port 80 through the ingress, the same path the ACME server uses.
The policy that is actually needed here is to allow your ingress controller to reach the solver pods on port 8089. See the discussion on cert-manager/cert-manager#2334, particularly this comment explaining the ingress controller → solver pod flow.
| acme.cert-manager.io/http01-solver: "true" | ||
| ports: | ||
| - port: 8080 | ||
| protocol: TCP |
There was a problem hiding this comment.
This podSelector will only match pods in the same namespace as the NetworkPolicy (i.e. cert-manager). HTTP01 solver pods are created in the namespace of the Challenge resource, which is typically a workload namespace, not cert-manager. This rule will not match them.
Also, as noted above, the controller's self-check does not connect to the solver pod directly — it goes through port 80 via the ingress. The existing egress rules already permit port 80.
| podSelector: | ||
| matchLabels: | ||
| acme.cert-manager.io/http01-solver: "true" | ||
| ingress: |
There was a problem hiding this comment.
Same port issue: should be 8089, not 8080.
Also, the from source should be the ingress controller, not the cert-manager namespace. The ingress controller is the component that routes external ACME validation traffic to the solver pod. The closed PR #2110 had a more accurate example:
- from:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: ingress-nginx # adjust for your ingress
ports:
- protocol: TCP
port: 8089| - podSelector: | ||
| matchLabels: | ||
| acme.cert-manager.io/http01-solver: "true" | ||
| ports: |
There was a problem hiding this comment.
Port should be 8089, not 8080.
Also, this podSelector-only rule will not match solver pods because they run in the Challenge namespace (a workload namespace), not in the cert-manager namespace where this NetworkPolicy applies. A namespaceSelector is needed.
Note that the existing rule above (lines 63–67) already permits port-80 egress for the controller's HTTP01 self-check, which is the actual egress path the controller uses.
What this PR does
Adds concrete NetworkPolicy examples for HTTP01 challenge solver pods to the best-practice documentation page, as discussed in cert-manager/cert-manager#8875.
Changes
Related