Skip to content

docs: align production service guide with operator TLS and gRPC behavior #388

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mangelajo wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: align production service guide with operator TLS and gRPC behavior #388

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 4 additions & 20 deletions python/docs/source/getting-started/installation/service/service-production.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,28 +23,12 @@ Jumpstarter uses gRPC for communication, which has specific requirements for pro

### gRPC Requirements

- **HTTP/2 Support**: gRPC requires HTTP/2, ensure your ingress controller or load balancer supports it
- **gRPC Protocol**: Some ingress controllers require specific annotations for gRPC traffic
- **Keep-Alive Settings**: Long-lived gRPC connections may need keep-alive configuration
- **Load Balancing**: Use consistent hashing or session affinity for gRPC connections
- **HTTP/2 Support**: gRPC requires HTTP/2; ensure the path from clients to the service supports it
- **Keep-Alive Settings**: The Jumpstarter service and client configure gRPC keep-alive by default; you usually do not need to tune these separately.

### TLS Termination Options
### TLS for gRPC

Choose one of these TLS termination approaches:

**Option 1: TLS Termination at Ingress/Route (Recommended)**
- Terminate TLS at the ingress controller or OpenShift route
- Simpler certificate management
- Better performance with fewer encryption hops

**Option 2: End-to-End TLS**
- TLS from client to Jumpstarter service
- Higher security but more complex certificate management
- Required for strict compliance environments

```{warning}
gRPC over HTTP/1.1 is not supported. Ensure your ingress controller supports HTTP/2 and is properly configured for gRPC traffic.
```
The [Jumpstarter operator](service-operator.md) installs gRPC with **TLS passthrough** at the ingress or route: encrypted traffic is forwarded to the controller and router pods, which terminate TLS. HTTP login endpoints use edge TLS termination instead.
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Mar 26, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Avoid implying passthrough is the only supported gRPC TLS mode.

Current wording reads as unconditional, but OpenShift route templates also allow grpc.tls.mode: reencrypt (controller/deploy/helm/jumpstarter/charts/jumpstarter-controller/templates/router-route.yaml, Line 1-48). Consider “defaults to passthrough” or “typically passthrough” to prevent operator confusion.

Suggested wording tweak 
-The [Jumpstarter operator](service-operator.md) installs gRPC with **TLS passthrough** at the ingress or route: encrypted traffic is forwarded to the controller and router pods, which terminate TLS. HTTP login endpoints use edge TLS termination instead.
+The [Jumpstarter operator](service-operator.md) configures gRPC to use **TLS passthrough by default** at the ingress or route: encrypted traffic is forwarded to the controller and router pods, which terminate TLS. HTTP login endpoints use edge TLS termination instead.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
The [Jumpstarter operator](service-operator.md) installs gRPC with **TLS passthrough** at the ingress or route: encrypted traffic is forwarded to the controller and router pods, which terminate TLS. HTTP login endpoints use edge TLS termination instead.
The [Jumpstarter operator](service-operator.md) configures gRPC to use **TLS passthrough by default** at the ingress or route: encrypted traffic is forwarded to the controller and router pods, which terminate TLS. HTTP login endpoints use edge TLS termination instead.
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In
`@python/docs/source/getting-started/installation/service/service-production.md`
at line 31, The sentence currently states TLS passthrough unconditionally;
update the wording to avoid implying it's the only supported gRPC TLS mode by
saying the Jumpstarter operator typically or defaults to using TLS passthrough
for gRPC at the ingress/route and explicitly note that routes can also be
configured with grpc.tls.mode: reencrypt (see the router-route.yaml route
template) so operators know re-encrypt is supported; keep the explanation about
edge TLS termination for HTTP login endpoints unchanged.

Copy link
Copy Markdown
Member Author

@mangelajo mangelajo Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good point, but helm support is deprecated

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mangelajo, thanks for the clarification! If Helm support is deprecated, then the reencrypt option in the Helm chart templates is no longer relevant, and the unconditional "TLS passthrough" wording in the docs is accurate for the current supported deployment path. The suggestion can be disregarded — the existing wording is fine.

✏️ Learnings added 
Learnt from: mangelajo
Repo: jumpstarter-dev/jumpstarter PR: 388
File: python/docs/source/getting-started/installation/service/service-production.md:31-31
Timestamp: 2026-03-26T14:31:04.673Z
Learning: In the jumpstarter-dev/jumpstarter repository, Helm-based deployment (charts under `controller/deploy/helm/`) is deprecated. When reviewing documentation or code changes, do not flag Helm chart configurations (such as `grpc.tls.mode: reencrypt` in router-route.yaml) as conflicting with or constraining the current supported deployment approach.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

🧠 Learnings used 
Learnt from: bennyz
Repo: jumpstarter-dev/jumpstarter PR: 320
File: python/packages/jumpstarter-cli/jumpstarter_cli/shell.py:308-341
Timestamp: 2026-03-14T11:11:29.265Z
Learning: In `python/packages/jumpstarter-cli/jumpstarter_cli/shell.py`, the `--tls-grpc` path (`_shell_direct_async`) intentionally does NOT use `ClientConfigV1Alpha1`. It constructs a synthetic config with `allow=[]`, `unsafe=True`, and `use_profiles=False` because this is a direct, controller-free connection mode. Do not flag the absence of a real client config here as an issue.


## Installation

Expand Down
Loading