docs(seinode): LLD for sidecar TLS via externally-provisioned Secret

[bdchatham]

Summary

• Lands the LLD for the revised sidecar TLS design as a doc-only PR, so implementation work in Sidecar TLS via externally-provisioned Secret #255 references a merged design rather than a moving target.
• Replaces the in-place-toggle approach explored in closed PR feat(planner): TLS toggle on Running SeiNodes via NodeUpdate plan #254. Cross-review surfaced architectural concerns (brittle plan-task-list classification, cert lifecycle coupled to plan lifecycle, attacker-controllable Issuer trust-anchor) that the revised design eliminates by externalizing cert ownership and making spec.sidecar.tls immutable.

Design at a glance (LLD §0.1)

Three coupled decisions:

• Externalize cert ownership. Operator/platform tooling provisions the kubernetes.io/tls Secret; controller references it by name and gates on presence + cert validity. Mirrors signingKey / nodeKey / operatorKeyring / imported-PVC patterns already in the controller.
• Immutable post-creation. Toggle via delete + recreate with PVC retention. At ~10 nodes manual cycling is fine; each transition gets a clean Pending → Running boundary.
• Machine-readable contract. Controller publishes status.sidecarTLS.{secretName, requiredDNSNames} whenever TLS is enabled. Platform tooling reads this directly — no naming-convention docs the operator must find.

What collapses (vs. PR #254 design)

• The drift detector (sidecarTLSDrift)
• The status mirror (status.currentSidecarTLS)
• Condition reason expansion (TLSToggleStarted, UpdateAndTLSToggleStarted)
• classifyPlan discrimination
• ApplySidecarCert task and GenerateSidecarCertificate generator
• ObserveSidecarTLS task
• Issuer trust-anchor security surface (IssuerName/IssuerKind)

CRD shrinks to spec.sidecar.tls.secretName: string + immutability CEL.

What stays

• noderesource pod/service generation with the existing if SidecarTLSEnabled(node) { ... } branching
• ApplyRBACProxyConfig task (controller-owned, namespace/name-dependent)

Tracking

• Implementation: Sidecar TLS via externally-provisioned Secret #255
• Superseded: closed PR feat(planner): TLS toggle on Running SeiNodes via NodeUpdate plan #254, Sidecar TLS toggle on Running SeiNodes — extend drift detection + reprovision plan #247
• Moot: closed Sidecar TLS disable path on Running SeiNodes #250, Sidecar TLS trust-anchor hardening: pin Issuer + pod-attestation observer #251, Sidecar TLS CA-rotation observability: cert fingerprint in status #252
• Reduced scope: WaitForSidecarTLSSecret: per-task deadline + diagnostic surfacing #253 (preflight gate deadline)

Test plan

This is a doc-only PR; verification of the design happens in #255's implementation tests (LLD §8 lists them). Reviewing here is reviewing the design itself — section by section.

🤖 Generated with Claude Code

[cursor]

You have used all Bugbot PR reviews included in your free trial for your GitHub account on this workspace.

To continue using Bugbot reviews, enable Bugbot for your team in the Cursor dashboard.