docs: document sshd configuration and client keepalives - #256
Closed
giuliocalzo wants to merge 1 commit into
Closed
Conversation
giuliocalzo
requested review from
SkylerMalinowski,
alanmutsch,
catblade,
vivian-hafener and
wickberg
as code owners
September 4, 2026 07:53
The operator generates the whole `sshd_config` and mounts it over `/etc/ssh/sshd_config`, so the image's own defaults never apply. Nothing documents what that generated file contains, or how `extraSshdConfig` interacts with it. Add a usage guide covering how the file is assembled, which settings the operator already defines, and why `sshd_config`'s first-value-wins rule means `extraSshdConfig` cannot override those. Document client-alive probes as the remedy for long-lived sessions dropped by a load balancer's idle timeout, and for sessions whose client went away while holding a worker's adopted job. Signed-off-by: Giulio Calzolari <gcalzolari@nvidia.com>
giuliocalzo
force-pushed
the
docs/sshd-client-keepalives
branch
from
September 4, 2026 08:02
52807b8 to
de0eb06
Compare
Contributor
|
Merged: 334c26f |
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
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.
Documents the generated
sshd_configand how to extend it, instead of changing any chart defaults. Supersedes #254, which proposed baking keepalives intovalues.yaml; the review preference upstream was to keep allextra*fields empty and document the configuration, which is what this does.Adds
docs/usage/ssh-access.md, covering:sshd_configis assembled. The operator generates the whole file and mounts it over/etc/ssh/sshd_config, so the image's own defaults do not apply — worth stating, since it is invisible from the chart.ClientAliveInterval, so it stays at OpenSSH's0and sshd never probes its clients. Long-lived sessions are then dropped by the idle timeout of whatever sits in front of them (350s AWS NLB, 600s GCP, 4 min Azure;TCPKeepAlivedoes not help, as Linux waits two hours). The reverse case is a vanished client leaving a session that, on a worker, still holds its adopted job. Documented with the reasoning for choosing an interval rather than just a snippet to paste.sshd_configtakes the first value per keyword andextraSshdConfigis appended last, so keywords the operator already emits cannot be overridden there — the added line is silently ignored. The page lists them for login and worker pods and points at anIncludedrop-in for changing them. This is also whyClientAlive*is legitimately anextraSshdConfigsetting: it does not collide with anything.Docs only, no chart or code change. Formatted with the repo's
mdformat --wrap=80pre-commit hook; the page is picked up automatically by theusage/*toctree glob.