DynamoGraphDeployment (DGD) Reference

Field reference for the DynamoGraphDeployment custom resource — the canonical, live description of a Dynamo inference graph.

View as Markdown

A DynamoGraphDeployment (DGD) is the canonical description of a running Dynamo inference graph. You list the components that make up the graph — frontend, workers, prefill and decode workers, planner, EPP — and the operator reconciles them into DynamoComponentDeployment resources, pods, and Services.

A DGD is the resource that persists and serves traffic. Author one directly when you have a known-good configuration or a tuned recipe; generate one from intent with a DynamoGraphDeploymentRequest (DGDR).

This page documents the nvidia.com/v1beta1 API — the served, current version.

Each entry in spec.components is a DynamoComponentDeploymentSharedSpec — the same fields documented on the DCD Reference. This page covers the graph-level fields; per-component fields live there.

Minimal example

1apiVersion: nvidia.com/v1beta1
2kind: DynamoGraphDeployment
3metadata:
4  name: my-graph
5spec:
6  backendFramework: vllm
7  components:
8    - name: frontend
9      type: frontend
10      replicas: 1
11    - name: worker
12      type: worker
13      replicas: 1
14      podTemplate:
15        spec:
16          containers:
17            - name: main
18              image: nvcr.io/nvidia/ai-dynamo/vllm-runtime:0.6.0

Spec reference

components
[]DynamoComponentDeploymentSharedSpec

Components deployed as part of this graph. Each entry carries its own stable logical name (unique within the list, case-insensitively). Component types are repeatable except type: epp, which may appear at most once. Maximum 25 components. For the full per-component field set, see DCD Reference — Shared component spec.

backendFramework
string

Backend framework for the graph. Sets backend-specific defaults the operator injects into each component’s main container.

Allowed values: sglang vllm trtllm
env
[]core/v1.EnvVar

Environment variables prepended to every component’s environment. A component-specific env entry with the same name takes precedence and may reference values from this list.

core/v1.EnvVar
annotations
map[string]string

Annotations propagated to all child resources (scaling adapters, DCDs, Deployments, and pod templates). Component-level podTemplate values take precedence on conflict.

labels
map[string]string

Labels propagated to all child resources. Same precedence rules as annotations.

priorityClassName
string

Name of the PriorityClass to use for Grove PodCliqueSets. Requires the Grove pathway. See Grove.

restart
Restart

Restart policy for the graph. Change restart.id to trigger a restart.

id
stringRequired

Arbitrary string; any change to it initiates a restart of the graph according to the configured strategy.

strategy
RestartStrategy

How components are restarted.

type
RestartStrategyTypeDefaults to Sequential

Whether components restart one at a time or all at once.

Allowed values: Sequential Parallel
order
[]string

Complete ordered set of component names for a sequential restart. Omit to use the controller’s default order. Must not be set for parallel restarts.

topologyConstraint
SpecTopologyConstraint

Deployment-level topology constraint. Components without their own topologyConstraint inherit this value. See Topology-Aware Scheduling.

clusterTopologyName
stringRequired

Name of the ClusterTopology resource defining the topology hierarchy for this deployment.

packDomain
string

Default topology domain to pack pods within. Optional at this level; omit when only components carry constraints.

experimental
DynamoGraphDeploymentExperimentalSpec

Graph-level opt-in preview features whose API shape may change in breaking ways between v1beta1 releases. Component-level experimental features live under spec.components[*].experimental instead — see DCD Reference — ExperimentalSpec.

kvTransferPolicy
KvTransferPolicy

Topology-aware routing for KV-cache transfers between prefill and decode workers. Set exactly one of labelKey or clusterTopologyName. See Topology-Aware KV Transfer.

clusterTopologyName
string

References a Grove ClusterTopology CR. The operator reads the CR’s topology levels and projects them through Dynamo-owned pod labels for worker topology metadata. Mutually exclusive with labelKey.

labelKey
string

A Kubernetes node label key (for example topology.kubernetes.io/zone) whose value identifies the topology domain for each worker. The operator copies the node label onto worker pods so the runtime can publish it as worker metadata. Should correspond to the topology level named in domain. Mutually exclusive with clusterTopologyName.

domain
TopologyDomain

Logical name for the topology level to enforce (for example zone, rack). The router uses this to match workers that share the same value for the label identified by labelKey. Free-form string matching ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$.

enforcement
KvTransferEnforcementDefaults to required

How the selected prefill worker’s topology is applied to decode routing. required allows only decode workers in the same topology domain as the selected prefill worker; preferred keeps all decode workers eligible but biases selection toward the same domain.

Allowed values: required preferred
preferredWeight
float

Required and used only when enforcement is preferred. Higher values create a stronger same-domain routing preference but do not guarantee same-domain selection; the value is not a probability. 0 disables the topology preference; 1 is the strongest supported preference. Minimum 0, maximum 1.

Status

The operator maintains observed state under status.

status.state
stringDefaults to initializing

High-level textual status of the graph deployment lifecycle.

status.conditions
[]metav1.Condition

Latest observed conditions, merged by type. Includes Available and DynamoComponentReady.

metav1.Condition
status.components
map[string]ComponentReplicaStatus

Per-component replica status, keyed by component name.

See: ComponentReplicaStatus

status.observedGeneration
integer

Most recent metadata.generation observed by the controller.

status.restart
RestartStatus

Status of a graph-level restart in progress.

observedID
string

The restart ID currently being processed. Matches spec.restart.id.

phase
RestartPhase

Phase of the restart.

Allowed values: Pending Restarting Completed Failed Superseded
inProgress
[]string

Names of the components currently being restarted.

status.checkpoints
map[string]ComponentCheckpointStatus

Per-component checkpoint status, keyed by component name. See Snapshot and Restore.

See: ComponentCheckpointStatus

status.rollingUpdate
RollingUpdateStatus

Progress of operator-managed rolling updates. Currently supported only for single-node, non-Grove deployments. See Rolling Update.

phase
RollingUpdatePhase

Current phase of the rolling update.

Allowed values: Pending InProgress Completed Failed
startTime
metav1.Time

When the rolling update began.

metav1.Time
endTime
metav1.Time

When the rolling update completed, successfully or failed.

metav1.Time
updatedComponents
[]string

Components that have completed the rolling update.

Additional Types

Nested struct types referenced by the status fields above, broken out here to keep the field lists shallow. Types prefixed core/v1. or metav1. are standard Kubernetes types and link to their Go package documentation instead of being expanded.

ComponentReplicaStatus

Replica information for a single component, keyed by component name in status.components.

componentKind
ComponentKind

Underlying Kubernetes resource kind backing the component.

Allowed values: PodClique PodCliqueScalingGroup Deployment LeaderWorkerSet
componentNames
[]string

Underlying Kubernetes resource names for this Dynamo component. During normal operation this contains a single name; during rolling updates it contains both the old and new resource names.

replicas
integer

Total number of non-terminated replicas. Minimum 0.

updatedReplicas
integer

Number of replicas at the current/desired revision. Minimum 0.

readyReplicas
integer

Number of ready replicas. Populated for PodClique, Deployment, and LeaderWorkerSet; not available for PodCliqueScalingGroup. Minimum 0.

availableReplicas
integer

Number of available replicas. Populated for Deployment and PodCliqueScalingGroup; not available for PodClique or LeaderWorkerSet. Minimum 0.

ComponentCheckpointStatus

Checkpoint information for a single component, keyed by component name in status.checkpoints.

checkpointName
string

Name of the associated DynamoCheckpoint CR.

checkpointID
string

Artifact ID used by the snapshot protocol.

identityHash
stringDeprecated

Computed hash of the checkpoint identity. Deprecated: automatic checkpoints use checkpointID; this field is retained for older status consumers.

ready
boolean

Whether the checkpoint artifact is ready for future pods to restore.

Inspect a DGD

$# List graph deployments (short name: dgd)
$kubectl get dgd -n $NAMESPACE
$
$# Detailed status, conditions, and events
$kubectl describe dgd my-graph -n $NAMESPACE
$
$# Per-component readiness
$kubectl get dgd my-graph -n $NAMESPACE -o jsonpath='{.status.components}'
DCD Reference

Per-component fields embedded in spec.components.

DGDR Reference

Generate a DGD by intent instead of authoring it by hand.

Deploy with DGD

Task-oriented walkthrough of authoring a graph deployment.

Dynamo Operator

Operator-injected defaults, environment variables, and reconciliation.