Skip to content

docs: document sshd configuration and client keepalives - #256

Closed
giuliocalzo wants to merge 1 commit into
SlinkyProject:mainfrom
giuliocalzo:docs/sshd-client-keepalives
Closed

docs: document sshd configuration and client keepalives#256
giuliocalzo wants to merge 1 commit into
SlinkyProject:mainfrom
giuliocalzo:docs/sshd-client-keepalives

Conversation

@giuliocalzo

Copy link
Copy Markdown
Contributor

Documents the generated sshd_config and how to extend it, instead of changing any chart defaults. Supersedes #254, which proposed baking keepalives into values.yaml; the review preference upstream was to keep all extra* fields empty and document the configuration, which is what this does.

Adds docs/usage/ssh-access.md, covering:

  • How sshd_config is 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.
  • Client keepalives. Nothing sets ClientAliveInterval, so it stays at OpenSSH's 0 and 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; TCPKeepAlive does 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.
  • Settings the operator already defines. sshd_config takes the first value per keyword and extraSshdConfig is 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 an Include drop-in for changing them. This is also why ClientAlive* is legitimately an extraSshdConfig setting: it does not collide with anything.

Docs only, no chart or code change. Formatted with the repo's mdformat --wrap=80 pre-commit hook; the page is picked up automatically by the usage/* toctree glob.

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
giuliocalzo force-pushed the docs/sshd-client-keepalives branch from 52807b8 to de0eb06 Compare September 4, 2026 08:02
@SkylerMalinowski

Copy link
Copy Markdown
Contributor

Merged: 334c26f

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants