Skip to content

docs(kvbm): drop the object-storage tier that has no implementation - #14012

Closed
ayaangazali wants to merge 2 commits into
ai-dynamo:mainfrom
ayaangazali:docs/kvbm-drop-unimplemented-object-tier
Closed

ayaangazali wants to merge 2 commits into
ai-dynamo:mainfrom
ayaangazali:docs/kvbm-drop-unimplemented-object-tier

Conversation

@ayaangazali

@ayaangazali ayaangazali commented Aug 29, 2026 •

Copy link
Copy Markdown
Contributor

Summary

The KVBM configuration reference documents an object-storage tier that is not implemented. The section opens with

The G4 tier stores blocks in an S3-compatible object store. Enable it with DYN_KVBM_OBJECT_ENABLED=1 and supply the bucket and credentials.

and then documents seven variables, including a {worker_id} bucket template and access/secret key handling. Nothing in the runtime reads any of them. Across the whole repository the only appearances of DYN_KVBM_OBJECT_* are the constants in environment_names.rs and this page:

$ grep -rn "DYN_KVBM_OBJECT" --exclude-dir=.git --exclude-dir=target .
docs/fern/pages/reference/components/kvbm-configuration.mdx   (7 ParamFields)
lib/runtime/src/config/environment_names.rs                   (7 constants)

There is also no prefix-based loader that could pick them up indirectly. config.rs registers Env::prefixed for DYN_WORKER_, DYN_RUNTIME_, DYN_SYSTEM_, DYN_COMPUTE_, DYN_HEALTH_CHECK_ and DYN_CANARY_, and none for DYN_KVBM_.

The failure mode is quiet, which is what makes it worth fixing. Someone follows the page, puts real S3 credentials in a worker manifest, and gets no offload and no warning, because there is no reader to complain.

Removed the section and the two intro claims that promise the tier, and left a short note in its place so the page does not silently lose the concept.

Two things I deliberately did not do:

  • I left the seven constants in environment_names.rs alone. feat(kvbm-engine): integrate Mooncake Store as G4 object storage backend #9786 is actively building this tier, and it takes a different approach (an ObjectConfig serde struct in the new kvbm-config crate rather than environment variables), so whether an environment surface comes back is that author's call, not mine.
  • I did not mark the section "coming soon" instead of removing it. Happy to switch to that if you would rather keep the shape of the documentation, but as written it reads as a shipped feature.

Validation

Documentation only, no code changes.

  • pre-commit run --files docs/fern/pages/reference/components/kvbm-configuration.mdx passes every applicable hook, including the Fern asset-path check. pytest-marker-report fails identically on an untouched README.md here because vLLM and TensorRT-LLM are not installed.
  • Checked the rest of the docs tree for the same claim: grep -rn "DYN_KVBM_OBJECT" docs/ agent-docs/ is now empty, so no other page contradicts this one.
  • <Note> is used on 54 other Fern pages, so the component is the standard one for this site.

Summary by CodeRabbit

  • Documentation
    • Updated the KVBM reference to describe cache tiers through disk storage (G3).
    • Removed object storage (G4) from the tier overview.
    • Clarified that object storage has no runtime environment variables.
    • Removed the dedicated object-storage configuration section and parameters.

The KVBM configuration reference documents seven DYN_KVBM_OBJECT_* variables
and states that the G4 tier stores blocks in an S3-compatible object store,
down to a {worker_id} bucket template and credential handling. Nothing in the
runtime reads any of them. Their only appearances are the constants in
environment_names.rs and this page.

Someone following the page would supply S3 credentials and expect KV blocks to
offload, and get silence: there is no reader to warn, so the tier just never
does anything.

Remove the section and the two intro claims that promise the tier, and note in
its place that object storage has no environment surface yet, so the page does
not simply lose the concept.

Signed-off-by: ayaangazali <ayaangazali.work@gmail.com>
Copilot AI lite review requested due to automatic review settings August 29, 2026 19:33
@ayaangazali
ayaangazali requested a review from a team as a code owner August 29, 2026 19:33
@copy-pr-bot

copy-pr-bot Bot commented Aug 29, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

@ayaangazali
ayaangazali temporarily deployed to external_collaborator August 29, 2026 19:33 — with GitHub Actions Inactive
@ayaangazali
ayaangazali temporarily deployed to external_collaborator August 29, 2026 19:33 — with GitHub Actions Inactive

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@github-actions

Copy link
Copy Markdown
Contributor

👋 Hi ayaangazali! Thank you for contributing to ai-dynamo/dynamo.

Just a reminder: The NVIDIA Test Github Validation CI runs an essential subset of the testing framework to quickly catch errors.Your PR reviewers may elect to test the changes comprehensively before approving your changes.

🚀

@github-actions github-actions Bot added docs external-contribution Pull request is from an external contributor documentation Improvements or additions to documentation labels Aug 29, 2026
@coderabbitai

coderabbitai Bot commented Aug 29, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 8f81a37d-288d-49e6-b078-d85386fa23cf

📥 Commits

Reviewing files that changed from the base of the PR and between 4c7e981 and 9b02d4e.

📒 Files selected for processing (1)
  • docs/fern/pages/reference/components/kvbm-configuration.mdx

Included review availability: Your plan provides up to 12 included reviews per hour; 10 remain after this review.


Walkthrough

The KVBM reference now documents cache tiers through disk (G3). It states that object storage (G4) is not read from runtime environment variables and removes its configuration section and parameters.

Changes

KVBM configuration documentation

Layer / File(s) Summary
Update runtime tier coverage
docs/fern/pages/reference/components/kvbm-configuration.mdx
The overview removes G4 object storage from runtime-controlled tiers. The page notes that runtime environment variables do not currently read G4 and removes the object-storage configuration details.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Merge Risk: ⚪ Minimal · up to 9b02d

This PR removes documentation for an unimplemented object-storage tier and replaces it with a clarifying note; it does not change runtime behavior or production configuration, so no actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Description check ⚠️ Warning The description provides detailed context, implementation scope, reviewer guidance, and validation results. It does not include the required Related Issues section or confirm that no related issue exi… Add the required Related Issues section. Either link the relevant issue, such as Closes #XXXX``, or include the unchecked-path confirmation: - [ ] Confirmed — no related issue. Also align the description headings with the repository templ…
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely describes the main documentation change: removing the unimplemented KVBM object-storage tier.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Full details: Description check

Explanation

The description provides detailed context, implementation scope, reviewer guidance, and validation results. It does not include the required Related Issues section or confirm that no related issue exists.

Resolution

Add the required Related Issues section. Either link the relevant issue, such as Closes #XXXX``, or include the unchecked-path confirmation: - [ ] Confirmed — no related issue. Also align the description headings with the repository template where practical.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)

  • Fix all pre-merge checks with AI

Comment @coderabbitai help to get the list of available commands.

The reference lists these as unset when the code supplies a real default:

  DYN_KVBM_LEADER_ZMQ_HOST      127.0.0.1  (distributed/utils.rs DEFAULT_LEADER_ZMQ_HOST)
  DYN_KVBM_LEADER_ZMQ_ACK_PORT  56002      (distributed/utils.rs DEFAULT_LEADER_ZMQ_ACK_PORT)
  DYN_KVBM_METRICS_PORT         6880       (vllm/connector/leader.rs fallback)

ACK_PORT was also typed as a string. It is a port, parsed as u16 and range
checked like its PUB_PORT sibling, which the page already documents as an
integer defaulting to 56001.

Folded into this PR rather than opened separately: it is the same page and the
same class of drift, and a third open PR against one reference file would just
conflict with the other two.

Signed-off-by: ayaangazali <ayaangazali.work@gmail.com>
@ayaangazali
ayaangazali temporarily deployed to external_collaborator August 30, 2026 20:10 — with GitHub Actions Inactive
@ayaangazali

Copy link
Copy Markdown
Contributor Author

Added a second commit rather than opening another PR, since it is the same page and the same class of drift.

Three entries list unset where the code supplies a real default:

variable documented actual source
DYN_KVBM_LEADER_ZMQ_HOST unset 127.0.0.1 DEFAULT_LEADER_ZMQ_HOST
DYN_KVBM_LEADER_ZMQ_ACK_PORT unset, string 56002, integer DEFAULT_LEADER_ZMQ_ACK_PORT
DYN_KVBM_METRICS_PORT unset 6880 leader.rs fallback

ACK_PORT was also typed as a string. It is a port: read through the same validated_port_from_env as PUB_PORT, parsed as u16 and range checked. This page already documents PUB_PORT as an integer defaulting to 56001, so the two were describing one mechanism two different ways.

I already have two other PRs open against this file (#14011 and the docs half of this one), so a third would have conflicted with both for no reviewer benefit.

@github-actions

Copy link
Copy Markdown
Contributor

This PR is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 5 days.

@github-actions

Copy link
Copy Markdown
Contributor

This PR has been closed due to inactivity. If you believe this PR is still relevant, please feel free to reopen it with additional context or information.

@github-actions github-actions Bot closed this Nov 15, 2026

This branch was previously deployed

1 inactive deployment
external_collaborator — c210d313 Deployed Aug 30, 2026 by ayaangazali via ok-to-test #13601
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs documentation Improvements or additions to documentation external-contribution Pull request is from an external contributor size/M Stale

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants