Operational how-tos: DNS, storage, auth, lifecycle, observability

[dcmcand]

Part of epic #621.

Goal

Cover the day-2 operational tasks platform admins will actually hit after a cluster is up — the things that currently lack any NKP-aware documentation on the site.

Scope

New or rewritten how-to pages under docs/docs/how-tos/. Each page stands alone but cross-links.

DNS

• Cloudflare DNS provider — CLOUDFLARE_API_TOKEN setup, zone config in nic YAML, what records are created, known limitation around domain changes not cleaning old records

Storage

• Longhorn distributed block storage — when to use Longhorn vs. cloud-native volumes, install/config via NIC, node maintenance (drain/uncordon) procedures

Auth

• Keycloak / authentication — how the Nebari Operator auto-wires Keycloak for packs and the landing page, admin access, realm/role basics, customizing

Cluster lifecycle

• Destroy a cluster — nic destroy behavior, order of teardown, what to check in cloud console afterward
• Update — re-run nic deploy, immutable vs. mutable fields, what triggers drift, how to resolve drift errors
• Upgrade Kubernetes version — version compatibility, rolling node groups, operator/pack considerations

Debugging / observability

• Debug an NKP deployment — where logs live, how to read operator status, common failure modes
• OpenTelemetry configuration — OTEL_EXPORTER, OTEL_ENDPOINT env vars, console vs. OTLP vs. dual export, sending traces to a local collector

All pages should link back to the architecture explainer for conceptual grounding.

Out of scope

• Provider-specific deploy guides (separate sub-issue)
• Pack-level operational guides (packs own their own docs)

Acceptance criteria

• All eight topics above have a dedicated page
• Each page includes concrete commands, not just prose
• Each page notes its NKP-only scope (Classic equivalents stay under /classic/)
• Cross-links are wired

Reference

Repos:

• nic CLI: https://github.com/nebari-dev/nebari-infrastructure-core
• Nebari Operator: https://github.com/nebari-dev/nebari-operator

Source in nebari-infrastructure-core:

• DNS: docs/design-doc/implementation/09-dns-provider-architecture.md
• Cloudflare: docs/plans/2026-02-09-cloudflare-dns-provider-design.md
• Longhorn: docs/plans/2026-02-17-longhorn-storage-design.md, docs/plans/2026-02-17-longhorn-storage-implementation.md, docs/design-doc/operations/longhorn-node-maintenance.md
• Foundational software (Keycloak, cert-manager, ArgoCD, Envoy Gateway): docs/design-doc/implementation/10-foundational-software.md
• State + lifecycle: docs/design-doc/architecture/05-state-management.md
• Telemetry: pkg/telemetry/telemetry.go

Notes for dev rel decomposition

This is the largest issue in the epic. Likely decomposition into ~8 sub-tasks (one per topic above), possibly split into separate tracked issues if parallelization helps.