docs: write the pack documentation - #26
Merged
Merged
Conversation
Fills the Astro + Starlight scaffold with real content, following the
structure apps-pack uses: a Getting Started track, task guides, and a
reference section.
Nine new pages plus a rewritten introduction:
Getting Started
getting-started install, what gets deployed, push endpoints
deployment Argo CD Application, and why each syncOption
is there (managedNamespaceMetadata is what
opts the namespace into nebari-operator;
ServerSideApply avoids the 256KB annotation
limit on dashboard ConfigMaps)
nebari-integration NebariApp, Keycloak OAuth, group-to-role
mapping, landing-page tile, additionalServices
local-development k3d + Tilt, and the two Tiltfile guardrails
Guides
mimir-modes monolithic vs distributed, why filesystem
storage is silently invalid distributed
(issue #22), cloud-bucket config
otel-collector how the override ConfigMap reaches NIC's
collector, why it is a separate ConfigMap
rather than a patch (argo-cd#7478), and the
rollout hook's narrow RBAC
dashboards what ships, and the contract for another pack
to contribute one
Reference
configuration values this chart owns, subchart pass-through
map, and the subchart defaults worth knowing
architecture components, data flow, storage topology, and
the hardening that explains the unusual Mimir
config paths
Content is derived from the chart itself - values.yaml, the templates,
the helpers, and examples/argocd-application.yaml - rather than
restating the README, so version numbers and defaults match what the
chart actually renders.
Also adds an editLink baseUrl so every page carries an "Edit page" link,
matching apps-pack.
|
📄 Docs preview for |
Matches the page name the other pack docs use for the same slot (mlflow-pack, superset-pack, rayserve-pack). The /deployment/ slug is unchanged, so no links move.
Accuracy pass over the pack docs, verified against `helm template` output for both Mimir modes and against NIC's collector values. Resource names: the chart's fullname helper yields `<release>-nebari-lgtm-pack-*`, since the release name `lgtm-pack` does not contain the chart name. Five places assumed `<release>-<suffix>`, so the datasource ConfigMap, NebariApp, OIDC Secret, and rollout Job commands all named resources that do not exist. OTel troubleshooting: `get jobs -l app.kubernetes.io/component=otel-rollout` matched nothing — that label is on the Job's pod template, not the Job. Also note `hook-delete-policy: hook-succeeded` removes the Job on success, so an empty result is the healthy state. Dashboards: the Kubernetes views are not rendered into the release. The grafana subchart emits an empty ConfigMap and a `download-dashboards` init container fetches them from grafana.com at pod startup, so they are absent without egress. Their data also depends on the collector's cAdvisor/kubelet scrape jobs, and this pack ships no scraper at all — spell out that the folder is provisioned but empty on a standalone install. Retention: Loki has none configured, so logs fill the 10Gi PVC — the same unbounded-growth mode as issue #22, previously listed only as "upstream default". Tempo's upstream default is 24h, worth stating outright. Also: caveat that `managedNamespaceMetadata` only labels a namespace its own Application creates (NIC's collector app creates `monitoring`); note `loki-canary` and the other non-release-prefixed subchart resources; note Grafana's persistence is off; drop the claim that an unresolved datasource uid renders empty rather than erroring; fix a heading; and repoint the loki and mimir-distributed values links, which now land on relocation stubs. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RHXnjMGsnSqmgxnx99Pqj6
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 #25 with real content, structured the way apps-pack does it.
Pages
Getting Started
Applicationmanifest and what each part is actually doingNebariApp, Keycloak OAuth, group→role mapping, landing-page tile,additionalServicesGuides
Reference
Notes on the content
Everything is derived from the chart —
values.yaml, the templates,_helpers.tpl, andexamples/argocd-application.yaml— rather than paraphrased from the README, so subchart versions, image tags, PVC sizes, and defaults match what actually renders.Three things the README states in passing are given room to explain themselves, since they are the parts most likely to bite someone:
ignoreDifferencesunreliable on the apply step.enforceAtGatewayis false — Grafana runs its own OIDC flow, so a gatewaySecurityPolicywould double-authenticate and break the callback.Also adds an
editLink.baseUrlso every page gets an "Edit page" link, matching apps-pack.Verification
🤖 Generated with Claude Code