DynamoComponentDeployment (DCD) Reference
DynamoComponentDeployment (DCD) Reference
Field reference for the DynamoComponentDeployment custom resource — the single Dynamo component that a DynamoGraphDeployment reconciles into pods.
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.
Minimal example
Spec reference
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.
Shared component spec
These fields are shared between a standalone DCD and each entry of a DGD spec.components list, except where a field is marked DGD-only. In a DGD, prefix them with spec.components[*].
Customizes the primary Grove unit for a component embedded in a DGD. Standalone DCD OpenAPI omits this field. Use apiVersion: grove.io/v1alpha1; the target is PodCliqueTemplateSpec for a component backed by a PodClique or PodCliqueScalingGroupConfig for one backed by a scaling group. The value may set only topologyConstraint. See ProviderOverride.
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. Immutable after it is set. Standalone DCDs cannot use lpx.
The lpx type is experimental, requires the operator’s lpx.enabled setting, and may change incompatibly.
Experimental DGD-only compiled-model and scheduling configuration; requires the operator’s lpx.enabled setting and may change incompatibly. Set buildId; placement comes from the build manifest. Runtime options belong in role pod templates. See LPXConfig.
When the operator’s lpx.modelRegistryURL is configured, buildId must be relative to that registry; absolute paths and URLs require an empty registry URL.
Configures this LPX component’s scheduling attempts. Components may use different deadlines, including when they share a workload.
Best-effort deadline for each of this component’s LPU pipeline requests to leave Pending, including waiting for the scheduler to start. The timer uses a nonzero status.schedulingStartedAt when available; otherwise it uses metadata.creationTimestamp. A scheduler-provided timestamp for a later scheduling cycle takes precedence over the request’s original creation time. Valid values are 1 through 9,223,372,036; omission means unlimited. This field is not a solver budget or an overall deployment readiness timeout.
Current-generation Bound, NoFit, and Unsupported receipts are exempt. Degraded, Releasing, and Released receipts are also exempt when their committed execution was accepted for the current request generation. NoFit can therefore leave the deployment Pending indefinitely, and a Bound request can still wait indefinitely for runtime readiness.
Deadline handling runs after download checks, compiler-registry resolution, and desired-state validation. An outage or invalid desired configuration can delay failure reporting and cleanup indefinitely, even after the deadline has elapsed. The timer does not bound asynchronous cleanup or finalization.
Expiry records LPXSchedulingDeadlineExceeded before cleanup. Cleanup removes complete engine replicas only from a trailing suffix: an expired interior replica blocks deadline cleanup to preserve healthy higher ordinals. Explicit replicas authorizes lowering the Grove replica count to the surviving prefix; externally managed capacity remains unchanged. Grove scaling and owner garbage collection handle pod cleanup; the LPX graph controller does not delete pods directly. A later LPX input revision authorizes republication after cleanup. An existing failure remains cleanup authority for cycles that started before it, so retiring those cycles does not consume the retry edit.
Declares the Dynamo runtime version in the component’s main image, taking precedence over the image tag. Use canonical MAJOR.MINOR.PATCH, for example "1.4.0", with each part between 0 and 9999 and no leading zeros, v prefix, prerelease suffix, or build metadata. This field does not change the image. See Runtime Version Compatibility for admission requirements and rollout behavior.
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 and should not be modified directly.
For a single type: lpx component in a DGD, this counts complete engine replicas, not individual role Pods. Hybrid and LPU-only engines allow up to 2496 replicas; generated Pod hostname limits may lower that maximum. In a speculative pair, draft replicas count model instances (1–8), and target replicas must be 1. LPX does not support scaling adapters or scale-to-zero.
Minimum complete component replicas guaranteed to be gang-scheduled before a shortfall triggers gang termination. Supported only for Grove-backed DGD components, where it defaults to 1; rejected for non-Grove deployments. Minimum 1 and immutable after creation. Positive replicas must be at least this value. Scaling to 0 is allowed and retains minAvailable for the next scale-up.
For LPX components with omitted replicas, minAvailable sets the initial Grove scaling-group size; subsequent capacity is externally managed.
Pod template for the component’s pods. New components must include a container named main with a non-empty image; the operator injects command, environment, port, probe, resource, and volume-mount defaults into that container, merging your overrides by name. Existing components created without a main image may retain that omission on unrelated updates. For DGD components whose image has no parseable semantic-version tag, set runtimeVersionOverride. 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.
For type: lpx, omit this field and use roles[].podTemplate. Every LPX role requires its own template with an explicit main container image.
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.
Number of nodes to deploy. Minimum 2 and immutable after creation. Total GPUs used is nodeCount × container GPU request.
Named Pod-producing parts of a compound component, keyed by name. Multinode components must contain exactly one leader and one worker; omitted role counts default to 1 and multinode.nodeCount - 1, respectively. Omit the field to retain the implicit leader/worker layout.
LPX components use agent for Agent Pods and conductor for the serving runtime. Independent LPX components each declare a conductor role with an explicit template. In a speculative pair, the draft has only an agent role and the target declares both roles. A hybrid engine’s GPU runtime uses the conductor template.
Standalone DCD roles cannot use LPX templates or DGD-only provider overrides. See ComponentRoleSpec.
Semantic role name: leader or worker for ordinary multinode components, conductor or agent for LPX components. Names must be unique within the component.
Logical cardinality of this role in one complete component instance; minimum 1. For ordinary multinode components, admission defaults and persists an omitted value as leader: 1 or worker: multinode.nodeCount - 1; an explicit value must match that fixed shape. For LPX, omitted conductor replicas use 1, subject to runtime-specific limits. Agent replicas are derived from the model build; an explicit count must match the build.
Native Pod template for this role. LPX-only; required for every declared role. Each template requires a main container with an explicit image. Agent and conductor templates are independent.
Provider configuration for the workload unit generated for this role. Available only on ordinary multinode components embedded in a DGD. LPX roles do not support it; standalone DCD OpenAPI omits this field. For Grove multinode leader and worker roles, use target PodCliqueTemplateSpec; only topologyConstraint is allowed in value. Role overrides are not supported for inter-pod GMS components. See ProviderOverride.
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.
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 (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.
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.
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
Runtime Version Compatibility
DGD admission requires runtimeVersionOverride for non-LPX components when the main image has no parseable semantic-version tag. Also set it when a parseable tag does not represent the Dynamo runtime version in the image. The override must describe the Dynamo runtime actually contained in the image.
When updating an image to a different Dynamo runtime version, update any configured runtimeVersionOverride in the same change, or remove it if the new image tag correctly identifies the runtime version. The operator uses the resolved runtime version to select feature gates that control how it renders the component’s PodSpec, including flags, environment variables, and probes. For Dynamo 1.5.0 and later, changing the override alone may change the rendered PodSpec or worker revision and trigger a rollout, even when the image reference is unchanged. Keep the override aligned with the Dynamo runtime actually contained in the image.
For components generated by a DGDR, an explicit component override takes precedence over the DGDR-level default. See Profiler image version compatibility.
Status
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.
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.
Additional Types
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.
ExperimentalSpec
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.
Allowed values: IntraPod InterPodThe 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.
core/v1.PodTemplateSpecConfigures 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.
Number of shadow (standby) engine containers per rank. Reserved for future use; the operator currently creates exactly one shadow. Minimum 1, maximum 1.
Configures experimental Grove workload rendering for a component in a DGD. Requires the Grove pathway.
When true, renders a single-node component as a PodCliqueScalingGroup with one single-pod PodClique per replica. The first minAvailable replicas join the deployment’s base PodGang; each additional replica gets a separate PodGang. false or omission retains automatic selection: multinode and inter-pod GMS components use scaling groups, while other single-node components use a PodClique. Immutable after creation.
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.
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.
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.
Deprecated: omit mode. Use enabled: true without checkpointRef for a DGD-managed automatic checkpoint, or use checkpointRef to restore a named PodSnapshot.
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.
Allowed values: vllm sglang trtllmDynamo platform version.
Tensor parallel configuration. Deprecated: checkpoint launch uses the pod template instead. Minimum 1.
Pipeline parallel configuration. Deprecated: checkpoint launch uses the pod template instead. Minimum 1.
Data type, for example fp16, bf16, or fp8.
Maximum sequence length. Minimum 1.
Additional parameters that affect the checkpoint hash.