docs(p2p): kubernetes P2P public exposure guide, document dht_mode off#1074
Merged
Conversation
Contributor
|
🤖 Claude Code Review Status: Complete Current Review: No blocking issues found. This is a well-scoped docs PR with one correct, minimal code fix. Verified against the code:
Minor (already acknowledged in the PR description): the |
Contributor
Benchmark Comparison ReportBaseline: Current: Summary
All benchmark results (sec/op)
Threshold: >10% with p < 0.05 | Generated: 2026-06-11 15:11 UTC |
icellan
approved these changes
Jun 11, 2026
ordishs
approved these changes
Jun 11, 2026
ordishs
left a comment
Collaborator
There was a problem hiding this comment.
Verified every settings claim against the codebase — all accurate: p2p_dht_mode = off shipped default (settings.conf:838), code default "server" (settings/settings.go:501), the bootstrap pool / BSVA claims (settings.conf:801-806), the Hetzner/OVH caveat (settings.conf:826-837), and off is genuinely handled in the code path (services/p2p/Server.go:343-347). The k8s networking advice (L4 requirement, externalTrafficPolicy: Local to avoid kube-proxy SNAT breaking observed-address) is technically correct. All links and the mkdocs nav entry resolve.
Minor comments, none blocking:
- AWS LB Controller inconsistency: the example manifest uses
aws-load-balancer-type: "external"+aws-load-balancer-nlb-target-type, which are AWS Load Balancer Controller annotations (the in-tree provider usesaws-load-balancer-type: nlb). The prose says target typeip"requires the AWS Load Balancer Controller", implyinginstancedoesn't — but the manifest as written already requires it. Either state the controller as a prerequisite or switch the example to the in-tree annotation. - Port wording: "default
9905" is the shipped settings.conf value (P2P_PORT = 9905); the code default is9906(settings/p2p_settings.go:18). Suggest the same "Go default vs settings.conf ships with" phrasing this PR already uses in the settings table. - Operator context:
p2p_dht_mode.operator = server(settings.conf:839) — since this is a Kubernetes guide and operator-managed deployments are the main k8s path, a footnote that the operator context already defaults toserverwould prevent confusion. selector: app: peeris deployment-specific; a one-liner telling readers to adapt it to their pod labels would help.- Agree the struct tag fix (settings/p2p_settings.go:55) belongs in a separate PR — please open a tracking issue so it doesn't get lost.
652a31b to
cb254ad
Compare
…mode off Add howto for exposing the P2P service publicly on Kubernetes/AWS: NLB with externalTrafficPolicy: Local (required to preserve peer source IPs for libp2p's observed-address mechanism and avoid cross-node forwarding), advertise address configuration, DHT mode selection, and how to join the BSVA DNS bootstrap pool. Also fix the P2P settings reference, which omitted dht_mode "off" (the settings.conf default) and the Hetzner/OVH abuse-flagging caveat that previously existed only as a settings.conf comment.
- State AWS Load Balancer Controller as a prerequisite (the example annotations require it) and drop the misleading clause implying only target-type ip needs it - Clarify the P2P port: multiaddrs in listen/advertise addresses are the source of truth; NLB listener must match the advertise multiaddr - Note that operator-managed deployments already default to p2p_dht_mode=server via the .operator settings context - Tell readers to adapt the selector to their pod labels
9906 is the P2P gRPC/HTTP port; the libp2p convention and shipped settings.conf use 9905. The code default colliding with the HTTP port would make a node advertise the wrong port if it ever fell back to it. Also fixes the struct tag longdesc which claimed 9906 was the standard P2P port while every multiaddr example in the same file uses 9905.
- developerSetup.md: kafka settings link had one ../ too many - kafkaMessageFormat.md: wire.go link pointed outside the docs tree; mkdocs cannot resolve source files, keep it as a plain code reference
9d51d95 to
2cace97
Compare
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
New howto: exposing the P2P service publicly on Kubernetes/AWS, plus fixes to the P2P settings reference and the
p2p_portcode default.We ran into this on our own infra: exposing P2P on AWS requires an NLB with
externalTrafficPolicy: Local. With the defaultClusterpolicy, kube-proxy SNATs inbound connections, so peers appear to come from your own node IPs — this breaks libp2p's observed-address mechanism, peer bans, and source-IP diagnostics. None of this was documented.Changes
docs/howto/miners/kubernetes/minersHowToExposeP2P.md(new)externalTrafficPolicy: Localrationale + pod scheduling caveatp2p_advertise_addressespairing (NLB DNS name or EIP); multiaddr port is what peers dial — NLB listener must matchserver/client/off) with resource implications; note that operator-managed deployments already default toservervia the.operatorcontext/dnsaddr/${network}.bootstrap.teranode.bsvb.tech) — requires public dialability +p2p_dht_mode = serverdocs/references/settings/services/p2p_settings.mdp2p_dht_mode = offentirely (the settings.conf default — reference only documented server/client)DHTModeandBootstrapPeerstable rows correctedsettings/settings.go+settings/p2p_settings.go:p2p_portcode default corrected from 9906 to 9905. 9906 is the P2P gRPC/HTTP port; the collision would make a node advertise the HTTP port if it ever fell back to the code default. Struct tag longdesc fixed to match (it claimed 9906 was "the standard P2P port" while every multiaddr example in the same file uses 9905).docs/P2P_NAT_TRAVERSAL.md: cloud/kubernetes best practice now links to the new howtomkdocs.yml: new page registered under Miners → Configurationdocs/howto/developerSetup.md,docs/references/kafkaMessageFormat.md: fixed two pre-existing broken links somkdocs build --strictpasses cleanVerification
mkdocs build --strict: passes with zero warnings (was 2 pre-existing before this PR)go build ./settings/... ./services/p2p/...,go vet ./settings/...: cleango test ./settings/... ./services/asset/httpimpl/: pass (the settings handler test already asserted 9905)Note: the
DHTModestruct tag insettings/p2p_settings.gostill says only "server"/"client" — left for a follow-up PR since it feeds the generated settings reference.