docs: write the pack documentation - #33
Merged
Merged
Conversation
Fills the Astro + Starlight scaffold with real content, following the
structure apps-pack uses.
Getting Started
getting-started install, why the chart renders its own
Services, first deployment
deployment the two NebariApps, why ignoreDifferences is
needed, and what the broad rayClusterConfig
ignore costs
jupyter ray:// vs HTTP, version matching, the
NetworkPolicy, and what does not survive a
cluster roll
local-development what dev/ builds, and the four things it
cannot exercise
Guides
serve-applications declarative vs notebook deployment, building
the image, proxy_location, checking health
scaling replicas, GPUs end to end (resource, runtime
class, auto-injected toleration, and the
ray_actor_options step people miss), and the
probe overrides behind issue #7
ca-bundle the injection, the four env vars and why
GIT_SSL_CAINFO is separate, the ConfigMap
rationale, the Argo CD footgun (#17), and the
httpx gap
troubleshooting the failures this pack actually produces
Reference
configuration every value, with the asymmetries called out
architecture the mermaid diagram from the README, plus why
serve-svc targets only the head and what that
implies for worker readiness
The through-line is that several of this pack's sharpest edges are
invisible from kubectl: an unset nebariapp.hostname silently skips the
serve NebariApp, `probe: {}` does not suppress a probe because Helm's
deep merge keeps existing keys, and Argo CD's rayClusterConfig ignore
drops the CA injection while reporting fully synced. Each is documented
where someone would hit it, with the command that confirms it.
Adds an editLink baseUrl so every page carries an "Edit page" link.
|
📄 Docs preview for |
Accuracy review findings against the chart and live `helm template` renders. Chart rename (#24) never reached the docs. The fullname helper yields `rayserve-nebari-rayserve-pack`, so all 22 hardcoded names across six pages were wrong — port-forwards, ray.init() addresses, kubectl targets, and NebariApp names. Same bug in dev/Makefile. There is no autoscaler. The chart does not set enableInTreeAutoscaling, so minReplicas/maxReplicas are clamps, not a range something grows within. Rewrote the scaling prose and the configuration table, and dropped the maxReplicas: 8 headroom from the reference values file since nothing would consume it. minReplicas/maxReplicas do not default to replicas. values.yaml pins both to 1, so the template's `default` never fires; KubeRay then clamps desired replicas into [min, max] and `--set worker.replicas=3` yields one worker. Documented as a caution. make up did not deploy both NebariApps. It never set nebariapp.serve.enabled=true, so with the chart default of false only the dashboard rendered — and the `kubectl wait` on the serve NebariApp targeted a resource that was never created, under its pre-rename name. Set the flag and fixed both waits, which makes the page's description true rather than documenting a broken command. Also: - gateway applies to both NebariApps, so the dashboard cannot be internal while the serve endpoint is public; the page claimed otherwise - IgnoreExtraneous skips a resource that is live but not in the desired state; it does not make Argo CD tolerate resources KubeRay creates - route_prefix is optional in Serve's config schema, defaulting to / - image.tag is copied verbatim into rayVersion, so `2.43.0-custom` lands there as a version that does not exist; examples now tag `2.43.0` - notebooks reach Serve over serve-svc, not head-svc (index diagram) - helm template needs `helm dependency update chart` first - canonicalized repo URLs past their rename redirects Verified: npm test 10 passed; build 12 pages; check-links.sh LINKS_OK at BASE=/ and BASE=/rayserve-pack/; every corrected example re-rendered through helm template. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RHXnjMGsnSqmgxnx99Pqj6
Same root cause as the previous commit, outside docs/. The rename in #24 left pre-rename resource names in the CI workflows and the README. test-integration.yaml has failed on main on every run since 94e8fba (2026-07-22): both `kubectl wait --for=condition=Ready nebariapp/...` steps target names the chart no longer produces, so the job dies before it reaches the HTTPRoute and auth assertions. test.yaml port-forwards a head-svc under the old name for the same reason. Also correcting two README facts the docs review surfaced: - nebariapp.serve.enabled documented as `true`; values.yaml sets `false`, and the recommendation elsewhere in the README agrees with `false` - image.tag `2.43.0-custom` lands verbatim in the RayService's rayVersion and canonicalizing repo URLs past their rename redirects. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RHXnjMGsnSqmgxnx99Pqj6
With the rename fixed, nebariapp-integration ran past the NebariApp waits for the first time and exposed a second breakage in a step that had never been reached. The upgrade step repeats the install step's --set flags except the sizing overrides, so it silently reverts head requests to 1 CPU / 2Gi and worker replicas to 1. That is a rayClusterConfig change: KubeRay rolls the cluster into pods a 2-CPU runner cannot schedule, generation 2 is never observed, and `--wait --timeout 5m` fails with RayService generation is 2, but latest observed generation is 1 Auth is meant to be the only delta, so carry the sizing through. Verified by rendering both steps' flags: the RayService is now byte-identical between install and upgrade, so nothing rolls, while auth still renders on both NebariApps for the SecurityPolicy assertion. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RHXnjMGsnSqmgxnx99Pqj6
3 tasks
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.
Fills the docs scaffold from #32 with real content, structured the way apps-pack does it.
Pages
Getting Started
ignoreDifferencesrules costray://vs HTTP, version matching, NetworkPolicy, what doesn't survive a rolldev/builds and the four things it can't exerciseGuides
proxy_location, healthReference
The through-line
Several of this pack's sharpest edges are invisible from
kubectl, so the docs consistently pair each with the command that confirms it:nebariapp.hostnamesilently skips the serveNebariApp. Its template is guarded onserve.enabledand a non-empty hostname, so nothing renders and nothing errors. The dashboard one usesrequiredand fails loudly — that asymmetry is documented in three places.probe: {}does not suppress a probe. Helm's deep merge keeps existing keys, so the chart's raylet-only override stays.null(~) is the answer. Worth spelling out because the wrong answer reintroduces the Worker readiness probe fails on fresh cluster: requires Ray Serve EveryNode proxies + at least one deployed app #7 symptom./spec/rayClusterConfigignore drops the CA injection while reporting fully synced. The README covers this well; it now has a callout on the CA page, a cross-reference from Deploying on Nebari, and a "checkprintenv SSL_CERT_FILE, not the sync status" instruction.Two README details worth a look
nebariapp.serve.enabled— the README's configuration table says the default istrue;values.yamlsetsfalse. The docs followvalues.yaml, and the recommendation elsewhere in the README (keep the serve endpoint internal) agrees withfalse, so the table looks like the stale side. Not changed here.GPU claiming has a fourth step. Requesting
nvidia.com/gpu, settingruntimeClassName, and getting the auto-injected toleration gets a GPU attached to the pod — the Serve deployment still needsray_actor_options.num_gpusor the replica runs on CPU next to an idle GPU. Scaling and GPUs walks all four steps with the verification commands.Verification
🤖 Generated with Claude Code