docs(enterprise): private CA trust for Helm deployments - #1804
Open
robsyme wants to merge 4 commits into
Open
Conversation
The only documented Kubernetes recipe for trusting a private CA imports the certificate in place with `keytool -cacerts`. The Helm charts default `containerSecurityContext.readOnlyRootFilesystem: true` for every component except Studios, so that recipe fails at pod start with `FileNotFoundException ... (Read-only file system)` on backend, cron and wave alike. Add a "Use Helm charts" recipe to the SSL/TLS page: copy the trust store to a mounted volume, import into the copy, and point the JVM at it with JAVA_TOOL_OPTIONS. Includes the startup log line that verifies the flag landed, and a note that `JAVA_OPTS` works for backend and cron but is ignored by Wave, which reads `WAVE_JVM_OPTS` and replaces its default heap/GC/Netty options when set. Also correct the Wave limitation, which claimed private-CA container repositories are unsupported outright. That holds only for the hosted wave.seqera.io service, whose trust store cannot be modified; self-hosted Wave works, as verified with a customer running Wave 1.32.4 against a private-CA Harbor registry. Applied to platform-enterprise_docs and version-26.1 through 25.1, the versions that document the Helm install path. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: Rob Syme <rob.syme@gmail.com>
✅ Deploy Preview for seqera-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
christopher-hakkaart
self-requested a review
September 1, 2026 01:35
christopher-hakkaart
approved these changes
Sep 1, 2026
christopher-hakkaart
left a comment
christopher-hakkaart
left a comment
Member
There was a problem hiding this comment.
This looks good to me.
Note, I used this PR to format some of the headings and indentation at the same time. I've also applied our style guide to tidy up the text that was changed.
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
2 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.
Closes EDU-1484
Why
Two problems found while working FD-7878 (Wave 1.32.4 / Platform Enterprise 25.3.6, self-hosted Harbor behind a private CA).
1. The only documented Kubernetes recipe can't work on the Helm install path.
enterprise/configuration/ssl_tls.mdis the sole private-CA page, and both of its Kubernetes recipes import in place:The Helm charts default
containerSecurityContext.readOnlyRootFilesystem: truefor backend, cron, wave, agent-backend, mcp, portal-web and pipeline-optimization (studios is the onlyfalse). So the documented command is guaranteed to fail at pod start withkeytool error: java.io.FileNotFoundException: .../lib/security/cacerts (Read-only file system). This is not Wave-specific: the recipe is broken for backend and cron too, for anyone migrating manifests to charts. The page never mentions Helm, andextraEnvVarsappears nowhere in the docs repo.2.
enterprise/configuration/wave.mdsays the thing is unsupported. Its entire "Limitations" section read:True for the hosted
wave.seqera.ioservice, whose trust store a customer can't modify. False for self-hosted Wave, which is what the same page documents two sections further down. A customer reading it either doesn't file the ticket or files it expecting a no. The customer on FD-7878 is now running exactly this configuration successfully.What changed
ssl_tls.md: new Use Helm charts recipe (copy the trust store to a mounted volume, import into the copy, point the JVM at it withJAVA_TOOL_OPTIONS), plus a caution on the existing in-place recipes. Includes thePicked up JAVA_TOOL_OPTIONSstartup line as the verification signal, and thekubectl get deploy ... -o jsonpathcheck for whenextraEnvVarsis silently dropped.wave.md: limitation scoped to the hosted service, with a link to the recipe.Applied to
platform-enterprise_docs/andversion-26.1throughversion-25.1— every version that documents the Helm install path. Patching the versioned dirs alone would fix the live pages but regress at the next release cut, soplatform-enterprise_docs/is included.A note on
JAVA_OPTSThe page's only JVM-options example is
JAVA_OPTS="-Dmail.smtp.ssl.protocols=TLSv1.2", which is correct for the backend and silently wrong elsewhere.tower-backend/src/main/jib/tower.shpasses a bare${JAVA_OPTS}; Wave'ssrc/main/jib/launch.shreads${WAVE_JVM_OPTS:-<defaults>}and never looks atJAVA_OPTS. Two sibling Java services, two variable names, opposite semantics. The added note recommendsJAVA_TOOL_OPTIONS, which the JVM reads itself and which adds flags without discarding each container's defaults.Verification
The JVM behaviour in the added text was measured, not inferred, with a private CA plus an HTTPS stub and a clone of Wave's
launch.shonamazoncorretto:25 --read-only:trustStorepropertynullJAVA_OPTSnullWAVE_JVM_OPTSJAVA_TOOL_OPTIONSreadOnlyRootFilesystemdefaults were read fromseqeralabs/helm-chartsmaster. The recipe itself matches what the FD-7878 customer confirmed working in production; theinitContainersvariant mentioned in passing is the upgrade-safe alternative and is not what they ran.Follow-ups, not in this PR
docs/install/configure-wave-build.mdinseqeralabs/wavesetsWAVE_JVM_OPTS: "-Xmx3g -Xms1g -XX:+UseG1GC", which silently discardsMaxDirectMemorySizeand the Netty/HTTP-client tuning. Needs a PR in that repo, since product docs are sourced there.caCerts.existingConfigMapvalue would make this recipe unnecessary, and a JSON schema entry onextraEnvVarswould turn the silent drop into ahelm installerror.🤖 Generated with Claude Code