docs: add a Mooncake CacheRuntime sample for client-less cache systems - #6163
Conversation
|
Hi @btxu-db. Thanks for your PR. I'm waiting for a fluid-cloudnative member to verify that this patch is reasonable to test. If it is, they should reply with Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
Mooncake is a distributed KVCache store with no POSIX mount semantics: applications talk to the cache service through its own client library instead of a mount point. Its CacheRuntimeClass therefore declares only master and worker, and omits the client component. Add an end-to-end sample walking through that minimal setup, and document the client-less topology in the generic cache runtime integration guide, including the fact that Fluid still creates a Bound PVC/PV that application pods must not mount. Requires fluid-cloudnative#6157, without which the controller panics when a topology omits the client component. Signed-off-by: btxu-db <btxu-db@outlook.com>
938a186 to
cb28224
Compare
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #6163 +/- ##
==========================================
+ Coverage 65.13% 65.19% +0.05%
==========================================
Files 485 486 +1
Lines 34039 34150 +111
==========================================
+ Hits 22171 22263 +92
- Misses 10127 10136 +9
- Partials 1741 1751 +10 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
Documents Mooncake as a client-less CacheRuntime, building on #6157.
Changes:
- Adds bilingual end-to-end Mooncake samples.
- Documents client-less cache-system integration behavior.
- Adds English and Chinese navigation entries.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
docs/en/TOC.md |
Adds the English sample link. |
docs/zh/TOC.md |
Adds the Chinese sample link. |
docs/en/samples/cacheruntime/mooncake_cache_runtime.md |
Adds the English Mooncake walkthrough. |
docs/zh/samples/cacheruntime/mooncake_cache_runtime.md |
Adds the Chinese Mooncake walkthrough. |
docs/en/dev/generic_cache_runtime_integration.md |
Documents client-less integration requirements. |
docs/zh/dev/generic_cache_runtime_integration.md |
Adds the corresponding Chinese guidance. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| print("match:", hashlib.md5(payload).hexdigest() == hashlib.md5(got).hexdigest()) | ||
| ``` | ||
|
|
||
| > The connection address is the master pod's DNS name `mooncake-demo-master-0.svc-mooncake-demo-master`, not the Service name. The CacheRuntimeClass declares a headless Service, which does not expose ports itself, so you must reach the pod through its DNS record. |
| 本示例使用的 Mooncake 镜像： | ||
|
|
||
| ``` | ||
| btxu/mooncake:v3 |
| print("match:", hashlib.md5(payload).hexdigest() == hashlib.md5(got).hexdigest()) | ||
| ``` | ||
|
|
||
| > 连接地址使用的是 master Pod 的 DNS 名 `mooncake-demo-master-0.svc-mooncake-demo-master`，而不是 Service 名。CacheRuntimeClass 中声明的是 headless Service，其本身不暴露端口，需要通过 Pod 的 DNS 记录访问。 |
| The Mooncake image used in this example: | ||
|
|
||
| ``` | ||
| btxu/mooncake:v3 |
| mooncake-client-2 1/1 Running 0 79s 10.244.2.15 fluid-mooncake-worker <none> <none> | ||
| ``` | ||
|
|
||
| In the second pod, only read and verify (the `setup` parameters are the same as above): |
| mooncake-client-2 1/1 Running 0 79s 10.244.2.15 fluid-mooncake-worker <none> <none> | ||
| ``` | ||
|
|
||
| 在第二个 Pod 中只做读取和校验（`setup` 参数与上文相同）： |
Check the demo image's build context into samples/mooncake/docker so the sample can be rebuilt from the repository instead of depending on an opaque image in a personal registry. Pin both the Docker Hub image and its Alibaba Cloud mirror to an immutable digest, note that the two registries are personal accounts with no availability guarantee, and recommend building and substituting your own image. Correct the note on addressing the master: Fluid creates the component Service as headless with no ports, but that only affects SRV records, so the Service name resolves to the backing pod IPs just as the per-pod name does. The per-pod name is preferred only because it stays pinned to a single replica. Show the second client pod opening its own Python session and repeating the MooncakeDistributedStore initialization, which the reader previously had to infer; following the sample literally hit a NameError on store. Also add the trailing newline missing from the Chinese sample. Signed-off-by: btxu-db <btxu-db@outlook.com>
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
| exec mooncake_client \ | ||
| --host="$WORKER_HOST" \ | ||
| --port=50052 \ | ||
| --global_segment_size="$SEGMENT_SIZE" \ | ||
| --master_server_address="$MASTER_ADDR" \ | ||
| --metadata_server="$METADATA_ADDR" \ |
Install Python wheels only so no setup script runs at install time, pin nvidia-cuda-runtime-cu12, and run the components as an unprivileged user. Document why the worker's metadata and transfer connections stay clear-text. Signed-off-by: btxu-db <btxu-db@outlook.com>
a7c6163 to
fcf7a53
Compare
|
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: cheyang The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
Ⅰ. Describe what this PR does
Mooncake is a distributed KVCache store with no POSIX mount semantics: applications talk to the cache service through its own client library instead of reading and writing files through a mount point. Its
CacheRuntimeClasstherefore declares onlymasterandworkerundertopology, and omits theclientcomponent.This PR documents that client-less setup:
docs/{en,zh}/samples/cacheruntime/mooncake_cache_runtime.md— a new end-to-end sample: create theCacheRuntimeClass/Dataset/CacheRuntime, write and read data across pods and nodes through the Mooncake Python client, inspect the reported cache status, plus an FAQ entry.docs/{en,zh}/dev/generic_cache_runtime_integration.md— a new "cache systems without a client component" section describing when theclientcomponent may be omitted, and noting that Fluid still creates a Bound PVC/PV that application pods must not mount.docs/{en,zh}/TOC.md— table of contents entries.Docs only; no code changes.
Ⅱ. Does this pull request fix one issue?
NONE
Ⅲ. List the added test cases (unit test/integration test) if any, please explain if no tests are needed.
No tests — this PR only adds documentation.
Ⅳ. Describe how to verify it
The sample was run end to end on a kind cluster: the
DatasetreachesBoundwith onlymasterandworkerdeclared, data written from one client pod is readable from a second client pod on a different node after the writer has exited, andreportSummary.shpopulatesstatus.cacheStates(cached: 4.00MiB,fileNum: 1). All command output shown in the document is copied from that run.Rendering: all relative links in the touched documents resolve to existing files, and the en/zh versions have identical heading structures.
Ⅴ. Special notes for reviews
topologyomits the client component, so the sample cannot be followed on current master. Please merge fix: avoid nil pointer dereference in CacheRuntime configmap builder #6157 first. The version note in the sample currently points readers at that PR; happy to replace it with a concrete release version once fix: avoid nil pointer dereference in CacheRuntime configmap builder #6157 lands.btxu/mooncake:v3, plus an Alibaba Cloud mirror for mainland China) that adds two scripts on top of the official Mooncake image:/custom-entrypoint.shand/reportSummary.sh. The document explains what both scripts do so readers can build an equivalent image themselves. If you would prefer the build context to live in this repository, I can follow up with a PR adding it (I have a Dockerfile alongside an e2e case for this client-less topology, which I intended to send separately).