A DynamoComponentDeployment (DCD) describes one component of a Dynamo inference graph — a frontend, a worker, a prefill or decode worker, a planner, or an EPP. The operator reconciles each DCD into a Kubernetes Deployment (or Grove workload) plus its Services, ConfigMaps, and pods.
A DCD is rarely authored on its own. Each entry in a DynamoGraphDeployment spec.components list is a DynamoComponentDeploymentSharedSpec, the same shape documented here under Shared component spec. The operator creates one child DCD per component. Author a standalone DCD only when you want to manage a single component's lifecycle independently; otherwise define components inside a DGD.
This page documents the nvidia.com/v1beta1 API — the served, current version.
This reference covers user-configurable spec fields. For platform installation and operator configuration, see [Install Dynamo](../../kubernetes/installation/install-dynamo.md).
apiVersion: nvidia.com/v1beta1
kind: DynamoComponentDeployment
metadata:
name: my-worker
spec:
backendFramework: vllm
type: worker
replicas: 1
podTemplate:
spec:
containers:
- name: main
image: nvcr.io/nvidia/ai-dynamo/vllm-runtime:1.4.0
The DCD spec is backendFramework plus the shared component spec inlined at the same level.
Inference backend framework for this component. Drives backend-specific defaults the operator injects into the `main` container.
Allowed values: sglang vllm trtllm
These fields are shared between a standalone DCD and each entry of a DGD spec.components list. In a DGD, prefix them with spec.components[*].
Stable logical identifier for the component, unique within its parent DGD's `spec.components` list. Must match `^[A-Za-z0-9]([-A-Za-z0-9]*[A-Za-z0-9])?$`, 1–63 characters. For a standalone DCD the defaulting webhook populates `name` from `metadata.name`, so you rarely set it explicitly. The name is decoupled from the underlying workload name so the operator can rename child workloads (for example, hash-suffixing worker DCDs during a rolling update) without losing the identity that labels, status maps, scaling adapters, planner RBAC, and EPP filters depend on.
Role of the component within the graph. Drives port mapping, frontend detection, planner RBAC, and the pod label `nvidia.com/dynamo-component-type`. `prefill` and `decode` are first-class values for disaggregated serving and can be set directly. At most one component per graph may be `epp`.
Allowed values: frontend worker prefill decode planner epp
Desired number of complete component instances. For a single-node component, each instance is one pod. For a multinode component, each instance contains all of its roles. Minimum `0`. When `scalingAdapter` is set, this field is owned by the [DynamoGraphDeploymentScalingAdapter](full-api-reference.mdx#dynamographdeploymentscalingadapter) and should not be modified directly.
Pod template for the component's pods. The operator injects its defaults (image, command, env, ports, probes, resources, volume mounts) into the container named `main`, merging your overrides by name. If no `main` container is present, the operator generates one. Every other container is treated as a user-managed sidecar and receives no injected defaults — sidecars must specify their own required fields such as `image`. Replaces the ten separate per-component fields (`resources`, `envs`, `livenessProbe`, and so on) that existed in `v1alpha1`.
core/v1.PodTemplateSpec
Configures a `worker`, `prefill`, or `decode` component that spans multiple pods. Other component types reject this field. A pre-existing unsupported combination can remain unchanged during unrelated updates or remove `multinode`, but cannot change or reintroduce it. See [Multinode Orchestration](../../kubernetes/installation/multinode-orchestration.md).
Number of nodes to deploy. Minimum `2` and immutable after creation. Total GPUs used is `nodeCount × container GPU request`.
Optional explicit structure of a compound component. In this release, roles are supported for multinode components and must contain exactly one `leader` and one `worker`. Omit the field to retain the implicit leader/worker layout.
Semantic role name. Multinode components allow `leader` and `worker`.
Logical cardinality of the role in one complete component instance. For multinode, admission defaults and persists an omitted value as `leader: 1` or `worker: multinode.nodeCount - 1`; an explicit value must match that fixed shape.
Provider configuration for the workload unit generated for this role. Available only on components embedded in a DGD; standalone DCD OpenAPI omits this field.
Size of the tmpfs mounted at `/dev/shm`. Omit to use the operator default (`8Gi`); set a positive quantity for a custom size; set `"0"` to disable the shared-memory volume entirely.
resource.Quantity
Places the component in the global Dynamo namespace rather than the per-deployment namespace derived from the DGD name.
References a model served by this component. When set, a headless service is created for endpoint discovery.
Base model identifier, for example `llama-3-70b-instruct-v1`.
Model revision or version.
Opts the component into a [DynamoGraphDeploymentScalingAdapter](full-api-reference.mdx#dynamographdeploymentscalingadapter) (DGDSA). Set it — even as an empty object, `scalingAdapter: {}` — to create a DGDSA that owns `replicas` so external autoscalers (HPA, KEDA, Planner) can drive scaling through the Scale subresource. Omit the field to opt out.
Designates a container in `podTemplate.spec.containers` as the frontend sidecar. The value must match a container `name` in that list; the operator merges its frontend-sidecar defaults (Dynamo env vars, ports, health probes) into that container the same way it merges into `main`. The validation webhook rejects values that match no container.
Configures a PVC-backed compilation cache. The operator handles backend-specific mount paths and environment variables, so you do not hand-wire them into `podTemplate`.
Name of a user-created PVC, which must exist in the same namespace as the deployment.
Overrides the backend-specific default mount path. When empty, the operator selects a default appropriate for the backend framework.
Deprecated: omit `eppConfig` and use the native Rust EPP, which is configured through environment variables and takes no config file. Presence of this field selects the legacy Go EPP pod contract, so existing deployments keep running across an operator upgrade until you clear it.
Only valid when type is epp, and its use is decided by the component's resolved runtime version: required below 1.5.0 (legacy Go EPP image), forbidden at 1.5.0 and later (native Rust EPP image). Migrate by clearing eppConfig and moving to a 1.5.0+ image in the same update. Exactly one of configMapRef or config must be set. See the Gateway API Routing Reference.
References a user-provided ConfigMap key containing EPP configuration. Mutually exclusive with `config`.
<a href="https://pkg.go.dev/k8s.io/api/core/v1#ConfigMapKeySelector" target="_blank">core/v1.ConfigMapKeySelector</a>
EPP `EndpointPickerConfig` supplied inline. The operator marshals it to YAML and creates the ConfigMap for you. Mutually exclusive with `configMapRef`.
Component-level topology placement. See the [SpecTopologyConstraint API](full-api-reference.mdx#spectopologyconstraint).
Topology domain to pack pods within. Must match a domain defined in the referenced `ClusterTopology`. When the parent DGD also sets `spec.topologyConstraint.packDomain`, this value must be narrower than or equal to it.
Opt-in preview features whose API shape may change in breaking ways between `v1beta1` releases. Fields here are **not** covered by the normal `v1beta1` deprecation policy — do not rely on them for production workloads.
See: ExperimentalSpec
The operator maintains observed state under status.
Standard Kubernetes conditions. `Available` reports whether the component is serving traffic; `DynamoComponentReady` reports whether the underlying Dynamo component is ready.
metav1.Condition
Most recent `metadata.generation` the controller has reconciled. A component is up to date when this equals `metadata.generation`.
Replica status for this component: desired, ready, and available counts. Shares the shape documented on the [DGD Reference](dynamo-graph-deployment.mdx#componentreplicastatus).
Nested struct types referenced by the fields above, broken out here to keep the field lists shallow. Types prefixed core/v1., metav1., resource., or runtime. are standard Kubernetes types and link to their Go package documentation instead of being expanded.
Groups opt-in preview features for a component. Referenced by experimental. Nested types (GMSClientPodSpec, ComponentCheckpointJobConfig, DynamoCheckpointIdentity) are expanded inline under the field that references them.
These preview features can change or disappear between `v1beta1` releases without a name-preserving graduation path. They are excluded from the `v1beta1` deprecation policy — do not rely on them for production workloads.
Configures the GPU Memory Service (GMS). When set, GPU access for GMS clients is managed through Dynamic Resource Allocation (DRA), and the operator replaces the `main` container's GPU resources with a DRA `ResourceClaim`.
Selects the GMS deployment topology.
<span className="enum-values"><span className="enum-label">Allowed values:</span> <Badge intent="note" minimal>IntraPod</Badge> <Badge intent="note" minimal>InterPod</Badge></span>
The DRA `DeviceClass` to request GPUs from.
Additional user-declared containers that should be wired as GMS clients in service pods. `SnapshotJob` capture Pod clients are declared under `checkpoint.job.gmsClientContainers` instead. In each rendered pod, only matching container names are wired; absent names are ignored. Each name must match `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`, 1–63 characters.
Additional GMS client pods for inter-pod GMS. Reserved for future use and rejected until inter-pod client orchestration is wired.
Identifies this client pod. Must match `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`, 1–63 characters.
Configures the pod to run as a GMS client.
<a href="https://pkg.go.dev/k8s.io/api/core/v1#PodTemplateSpec" target="_blank">core/v1.PodTemplateSpec</a>
</ParamField>
Configures active-passive GPU failover for a worker component. The `main` container is cloned into two engine containers (active + standby) sharing GPUs via DRA, and the standby acquires the flock when the active engine fails. Requires `gpuMemoryService` to be set, `failover.mode` to match `gpuMemoryService.mode`, and the `nvidia.com/dynamo-kube-discovery-mode: container` annotation on the DGD.
Failover deployment topology. Must match the GMS `mode` on the same component.
<span className="enum-values"><span className="enum-label">Allowed values:</span> <Badge intent="note" minimal>IntraPod</Badge> <Badge intent="note" minimal>InterPod</Badge></span>
Number of shadow (standby) engine containers per rank. Reserved for future use; the operator currently creates exactly one shadow. Minimum `1`, maximum `1`.
Configures container-image snapshotting and restore for the component. Set `checkpoint.enabled: true` to opt in; omit `checkpointRef` for a DGD-managed automatic checkpoint, or set it to restore a `PodSnapshot` in the same namespace.
This release is a hard compatibility boundary for checkpoint resources. Dynamo creates automatic captures through the standalone Snapshot operator's `SnapshotJob` API, and `checkpointRef` names a standalone `PodSnapshot`. Legacy `DynamoCheckpoint` objects and their artifacts cannot be restored.
The upgrade does not delete the legacy DynamoCheckpoint CRD, instances, PodSnapshot objects, PodSnapshotContent objects, PVC data, or stored artifacts. Before upgrading, list retained DynamoCheckpoint objects and legacy PodSnapshot objects labeled nvidia.com/snapshot-owner, recreate any required snapshots through the standalone Snapshot APIs, and delete unneeded legacy checkpoints while the old controller can still run their finalizers. After upgrading, review and remove unsupported resources manually. Do not delete the shared PodSnapshot or PodSnapshotContent CRDs because the standalone Snapshot operator uses them.
Whether checkpointing is enabled for this component. When `true`, omit `checkpointRef` for a DGD-managed automatic checkpoint, or set `checkpointRef` to restore a `PodSnapshot` in the same namespace. Omit the `checkpoint` block, or set `enabled: false`, to disable checkpointing.
When normal worker replicas are started relative to automatic checkpoint readiness. `Immediate` starts workers cold immediately, and later pods restore from the checkpoint once it is Ready. `WaitForCheckpoint` keeps worker replicas at zero until the checkpoint is Ready, then starts them from it.
<span className="enum-values"><span className="enum-label">Allowed values:</span> <Badge intent="note" minimal>Immediate</Badge> <Badge intent="note" minimal>WaitForCheckpoint</Badge></span>
Whether a DGD-managed automatic checkpoint CR and artifact are deleted or retained when the owning DGD is deleted. Explicit `checkpointRef` PodSnapshots are never owned or deleted by the DGD, and retained automatic checkpoints are not valid `checkpointRef` targets.
<span className="enum-values"><span className="enum-label">Allowed values:</span> <Badge intent="note" minimal>Delete</Badge> <Badge intent="note" minimal>Retain</Badge></span>
References an existing `PodSnapshot` in the same namespace by `metadata.name`. When set, this component's `identity` is ignored and the referenced PodSnapshot is used directly. Standalone worker-class (`worker`, `prefill`, or `decode`) `DynamoComponentDeployment` resources cannot set this field; configure `checkpointRef` on the component in the owning `DynamoGraphDeployment`.
The workload container to snapshot and restore. Must match `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`, 1–63 characters.
Customizes the DGD-managed `SnapshotJob` capture Pod.
`SnapshotJob` capture Pod containers that should receive GMS client wiring. Requires `gpuMemoryService` on the component. Each name must match `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`, 1–63 characters.
Customizes the `SnapshotJob` capture Pod. The operator starts from the selected workload container and merges this template, so you can add helper containers such as `gms-saver`.
<a href="https://pkg.go.dev/k8s.io/api/core/v1#PodTemplateSpec" target="_blank">core/v1.PodTemplateSpec</a>
</ParamField>
Deprecated: omit `mode`. Use `enabled: true` without `checkpointRef` for a DGD-managed automatic checkpoint, or use `checkpointRef` to restore a named PodSnapshot.
<span className="enum-values"><span className="enum-label">Allowed values:</span> <Badge intent="note" minimal>Auto</Badge> <Badge intent="note" minimal>Manual</Badge></span>
Deprecated: omit for DGD-managed checkpoints; the operator ignores this field. Use `checkpointRef` to restore an existing `PodSnapshot`.
Model identifier, for example `meta-llama/Llama-3-70B`.
Runtime framework.
<span className="enum-values"><span className="enum-label">Allowed values:</span> <Badge intent="note" minimal>vllm</Badge> <Badge intent="note" minimal>sglang</Badge> <Badge intent="note" minimal>trtllm</Badge></span>
</ParamField>
<ParamField path="dynamoVersion" type="string" deprecated={true}>
Dynamo platform version.
</ParamField>
<ParamField path="tensorParallelSize" type="integer" default="1" deprecated={true}>
Tensor parallel configuration. Deprecated: checkpoint launch uses the pod template instead. Minimum `1`.
</ParamField>
<ParamField path="pipelineParallelSize" type="integer" default="1" deprecated={true}>
Pipeline parallel configuration. Deprecated: checkpoint launch uses the pod template instead. Minimum `1`.
</ParamField>
<ParamField path="dtype" type="string" deprecated={true}>
Data type, for example `fp16`, `bf16`, or `fp8`.
</ParamField>
<ParamField path="maxModelLen" type="integer" deprecated={true}>
Maximum sequence length. Minimum `1`.
</ParamField>
<ParamField path="extraParameters" type="map[string]string" deprecated={true}>
Additional parameters that affect the checkpoint hash.
</ParamField>
# List component deployments (short name: dcd)
kubectl get dcd -n $NAMESPACE
# Detailed status and conditions
kubectl describe dcd my-worker -n $NAMESPACE
# Readiness at a glance
kubectl get dcd my-worker -n $NAMESPACE \
-o jsonpath='{.status.conditions[?(@.type=="Available")].status}'
The graph resource whose `components` embed this spec.
Generate a DGD by intent instead of authoring components.
Task-oriented walkthrough of authoring a graph deployment.
Install and configure the Dynamo platform and operator.