Simulate a Kubernetes Deployment with Mocker | NVIDIA Dynamo Documentation

Mocker is a simulated Dynamo backend. It registers workers, publishes KV events, and returns mock responses while exercising the same frontend and routing path as a model-serving deployment.

Use this tutorial to deploy Mocker with a DynamoGraphDeployment (DGD). For local development, see Simulate a Local Deployment. For configuration details, see the Mocker CLI Reference. For implementation details, see Mocker Engine Architecture.

Prerequisites

Before you begin:

Install the Dynamo Kubernetes Platform.
Set NAMESPACE to the namespace where you deploy Dynamo resources.
Set PLANNER_IMAGE to a released or locally built dynamo-planner image.
Configure cluster access with kubectl.

Mocker runs in the planner image and does not request GPU resources.

Deploy an aggregated simulation

Create mocker-agg.yaml:

1 apiVersion: nvidia.com/v1beta1
2 kind: DynamoGraphDeployment
3 metadata:
4   name: mocker-agg
5 spec:
6   components:
7   - name: Frontend
8     type: frontend
9     replicas: 1
10     podTemplate:
11       spec:
12         containers:
13         - name: main
14           image: ${PLANNER_IMAGE}
15   - name: decode
16     type: decode
17     replicas: 1
18     podTemplate:
19       spec:
20         containers:
21         - name: main
22           image: ${PLANNER_IMAGE}
23           workingDir: /workspace
24           command:
25           - python3
26           - -m
27           - dynamo.mocker
28           args:
29           - --model-path
30           - Qwen/Qwen3-0.6B
31           - --speedup-ratio
32           - "1.0"

Replace ${PLANNER_IMAGE} with the image URI, and then apply the DGD:

$ kubectl apply -n "$NAMESPACE" -f mocker-agg.yaml
$ kubectl wait -n "$NAMESPACE" \
>   --for=condition=Ready pod \
>   --selector=nvidia.com/dynamo-graph-deployment-name=mocker-agg \
>   --timeout=300s

The checked-in aggregated Mocker example contains the complete deployment manifest.

Send a request

Forward the frontend service to port 8000:

$ kubectl port-forward -n "$NAMESPACE" svc/mocker-agg-frontend 8000:8000

In another terminal, send an OpenAI-compatible request:

$ curl localhost:8000/v1/chat/completions \
>   -H 'Content-Type: application/json' \
>   -d '{
>     "model": "Qwen/Qwen3-0.6B",
>     "messages": [{"role": "user", "content": "Hello!"}],
>     "max_tokens": 32
>   }'

A successful response confirms that the frontend discovered the Mocker worker and routed the request through the deployment.

Simulate disaggregated serving

Start from the checked-in disaggregated Mocker example. It defines separate prefill and decode components. The prefill worker uses:

1 args:
2 - --model-path
3 - Qwen/Qwen3-0.6B
4 - --disaggregation-mode
5 - prefill
6 - --bootstrap-ports
7 - "50100"

The decode worker uses:

1 args:
2 - --model-path
3 - Qwen/Qwen3-0.6B
4 - --disaggregation-mode
5 - decode

Apply the manifest, repeat the port-forward and request steps, and inspect the worker logs:

$ kubectl logs -n "$NAMESPACE" \
>   --selector=nvidia.com/dynamo-graph-deployment=mocker-disagg \
>   --all-containers --prefix

Use the logs to confirm that both worker stages registered and that requests moved from prefill to decode.

Try another simulation

Change one setting at a time and repeat the request:

Increase replicas to exercise routing across more workers.
Add Mocker scheduling or KV-cache flags from the Mocker CLI Reference.
Enable the Planner to test scaling behavior with simulated workers.
Compare the simulation with a real-GPU deployment by using Benchmarking with AIPerf.

DynoSim helps test control-plane behavior and shortlist configurations. Validate performance conclusions on the target GPU hardware before production use.