For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://docs.nvidia.com/dynamo/llms.txt. For full content including API reference and SDK examples, see https://docs.nvidia.com/dynamo/llms-full.txt.

Snapshot

⚠️ Экспериментальная функция: Dynamo Snapshot сейчас находится в preview и может работать только в некоторых конфигурациях кластера. DaemonSet snapshot-agent запускается в privileged mode, чтобы выполнять операции CRIU. Подробности см. в разделе Ограничения.

Dynamo Snapshot - это инфраструктура для быстрого запуска GPU-приложений в Kubernetes с использованием CRIU (Checkpoint/Restore in Userspace) и утилиты NVIDIA cuda-checkpoint. Обычно процесс выглядит так:

1. один раз запустить worker и сохранить checkpoint его инициализированного состояния
2. сохранить этот checkpoint на snapshot volume, локальном для namespace
3. позже восстанавливать worker'ы из этого checkpoint вместо повторного cold start

Тип запуска	Время	Что происходит
Cold Start	~1 min	Скачать модель, загрузить на GPU, инициализировать engine
Warm Start (restore from checkpoint)	~10 sec	Восстановить из готового каталога checkpoint

⚠️ Время восстановления зависит от пропускной способности storage, модели GPU и от того, остаётся ли restore на том же node.

Предварительные требования

• GPU nodes x86_64 (amd64)
• Драйвер NVIDIA 580.xx или новее на целевых GPU nodes (590.xx или новее, если тестируете multi-GPU snapshot)
• На данный момент backend vLLM или SGLang
• Storage для checkpoint. ReadWriteMany - самый безопасный вариант по умолчанию для cross-node или одновременного multi-node доступа, но режим podMount также может использовать подходящий storage ReadWriteOnce для последовательных workflows checkpoint/restore.
• CRI-O / OpenShift: задайте runtime.type=crio в snapshot chart (а на OpenShift - openshift.enabled=true). Значения по умолчанию рассчитаны на containerd; см. README chart для sockets и флагов Helm.

Быстрый старт через CR DynamoCheckpoint

1. Соберите placeholder image
2. Установите snapshot chart
3. Создайте DynamoCheckpoint и дождитесь, пока он станет ready
4. Разверните DynamoGraphDeployment, который восстанавливается из соответствующего checkpointRef

1. Сборка и отправка placeholder image

Worker'ы с поддержкой Snapshot должны использовать placeholder image, который оборачивает обычный runtime image и добавляет tooling для restore. Если такого образа у вас ещё нет, соберите его и отправьте в registry, из которого ваш кластер сможет его скачать:

export RUNTIME_IMAGE=registry.example.com/dynamo/vllm-runtime:1.0.0
export PLACEHOLDER_IMAGE=registry.example.com/dynamo/vllm-placeholder:1.0.0

cd deploy/snapshot

make docker-build-placeholder \
  PLACEHOLDER_BASE_IMG="${RUNTIME_IMAGE}" \
  PLACEHOLDER_IMG="${PLACEHOLDER_IMAGE}"

make docker-push-placeholder \
  PLACEHOLDER_IMG="${PLACEHOLDER_IMAGE}"

Placeholder image сохраняет обычный contract entrypoint/command runtime и добавляет tooling criu, cuda-checkpoint и nsrestore, необходимый для checkpoint и restore.

Чтобы собрать любой snapshot image с использованием собственного форка или ref CRIU, передайте CRIU_REPO и CRIU_REF через make. Если они не заданы, используются значения по умолчанию из Dockerfile.

make docker-build-agent \
  IMG=registry.example.com/dynamo/snapshot-agent:1.0.0 \
  CRIU_REPO="${YOUR_CRIU_REPO}" \
  CRIU_REF="branch-or-sha"

make docker-build-placeholder \
  PLACEHOLDER_BASE_IMG="${RUNTIME_IMAGE}" \
  PLACEHOLDER_IMG="${PLACEHOLDER_IMAGE}" \
  CRIU_REPO="${YOUR_CRIU_REPO}" \
  CRIU_REF="branch-or-sha"

2. Включите checkpointing в platform и проверьте его

Независимо от того, устанавливаете вы dynamo-platform или обновляете её, operator'у нужно только включить checkpointing:

dynamo-operator:
  checkpoint:
    enabled: true

Если platform уже установлена, проверьте, что конфигурация operator'а содержит блок checkpoint:

OPERATOR_CONFIG=$(kubectl get deploy -n "${PLATFORM_NAMESPACE}" \
  -l app.kubernetes.io/name=dynamo-operator,app.kubernetes.io/component=manager \
  -o jsonpath='{.items[0].spec.template.spec.volumes[?(@.name=="operator-config")].configMap.name}')

kubectl get configmap "${OPERATOR_CONFIG}" -n "${PLATFORM_NAMESPACE}" \
  -o jsonpath='{.data.config\.yaml}' | sed -n '/^checkpoint:/,/^[^[:space:]]/p'

Убедитесь, что в сгенерированной конфигурации есть enabled: true.

3. Установите snapshot chart

Для режима namespace-local по умолчанию установите snapshot chart в каждом namespace workload. Chart создаёт PVC и agent в этом namespace:

helm upgrade --install snapshot ./deploy/helm/charts/snapshot \
  --namespace ${NAMESPACE} \
  --create-namespace \
  --set storage.pvc.create=true

В режиме agentMount по умолчанию DaemonSet snapshot-agent монтирует checkpoint PVC напрямую. В multi-node GPU кластере это означает, что agent pods на нескольких node могут монтировать один и тот же PVC, поэтому PVC обычно требуется ReadWriteMany. Chart по умолчанию использует этот режим. Если в кластере нет storage class по умолчанию, также задайте storage.pvc.storageClass.

Если вы используете существующий checkpoint PVC повторно, не задавайте storage.pvc.create=true; установите chart с storage.pvc.create=false и вместо этого задайте storage.pvc.name.

CRI-O или OpenShift: добавьте, например, --set runtime.type=crio, а на OpenShift - --set openshift.enabled=true (см. deploy/helm/charts/snapshot/README.md).

Для кластеров, которые предпочитают один privileged snapshot agent вместо одного DaemonSet на каждый namespace workload, установите chart один раз в infrastructure namespace. В этом режиме chart не создаёт workload PVC; Dynamo operator либо создаёт каждый namespace-local PVC, либо проверяет, что он уже существует:

helm upgrade --install snapshot ./deploy/helm/charts/snapshot \
  --namespace dynamo-system \
  --create-namespace \
  --set storage.accessMode=podMount \
  --set storage.pvc.create=false \
  --set rbac.namespaceRestricted=false

Чтобы разрешить operator'у создавать workload PVC в каждом namespace, где используется checkpoint/restore, настройте operator с create: true:

dynamo-operator:
  checkpoint:
    enabled: true
    storage:
      type: pvc
      pvc:
        pvcName: snapshot-pvc
        basePath: /checkpoints
        create: true
        size: 1Ti
        storageClassName: ""
        accessMode: ReadWriteMany

Здесь chart и operator используют разные поверхности конфигурации: имя PVC в snapshot chart - это storage.pvc.name, а поле конфигурации operator'а - checkpoint.storage.pvc.pvcName.

Это ключевое отличие от agentMount: podMount снимает требование монтировать checkpoint PVC через DaemonSet snapshot-agent на каждом GPU node. Только активный workload pod checkpoint/restore монтирует PVC, а agent доступается к нему через mount namespace этого pod. ReadWriteMany по-прежнему остаётся самым безопасным значением по умолчанию для operator'а, особенно когда несколько pods checkpoint/restore могут одновременно обращаться к одному PVC или когда scheduling restore может охватывать несколько node. Подходящие storage class ReadWriteOnce всё ещё можно использовать для последовательных flows podMount checkpoint/restore, когда backend может подключить volume к node, где работает активный workload pod.

podMount зависит от того, что целевой container остаётся живым, пока agent разрешает /host/proc/<pid>/root/<basePath>. Если container завершится или перезапустится во время настройки checkpoint/restore, если runtime не может предоставить стабильный host PID или если настройки безопасности node запрещают переход по host proc, agent завершает работу с ошибкой или пропускает эту попытку, а reconciliation Kubernetes/operator должен повториться после того, как появится свежий container.

Чтобы использовать уже существующий PVC, опустите create или задайте его в false. Operator завершит reconciliation с понятной ошибкой, если указанный PVC не существует в namespace workload.

Убедитесь, что DaemonSet готов. После того как workload checkpoint или restore будет reconciled, проверьте PVC namespace workload:

kubectl rollout status daemonset/snapshot-agent -n dynamo-system
kubectl get pods -n dynamo-system -l app.kubernetes.io/component=snapshot-agent -o wide
kubectl get pvc snapshot-pvc -n ${NAMESPACE}

4. Создайте DynamoCheckpoint

Шаблон pod для Job checkpoint должен соответствовать worker container, который вы хотите сохранить в checkpoint. Для flow Snapshot важны identity checkpoint, container с именем main и placeholder image; остальная часть pod template должна повторять обычную конфигурацию worker'а. Дополнительные containers разрешены, но checkpoint создаётся только для main.

apiVersion: nvidia.com/v1alpha1
kind: DynamoCheckpoint
metadata:
  name: qwen3-06b-bf16
spec:
  identity:
    model: Qwen/Qwen3-0.6B
    backendFramework: vllm
    tensorParallelSize: 1
    dtype: bfloat16
    maxModelLen: 2048

  job:
    activeDeadlineSeconds: 3600
    podTemplateSpec:
      spec:
        ...
        containers:
          - name: main
            image: registry.example.com/dynamo/vllm-placeholder:1.0.0
            ...

Поддержка GMS + Snapshot сейчас отключена.

Полный рабочий пример см. в deploy/operator/config/samples/nvidia.com_v1alpha1_dynamocheckpoint.yaml.

Примените его:

kubectl apply -f qwen3-checkpoint.yaml -n ${NAMESPACE}

5. Дождитесь, пока checkpoint станет ready

kubectl get dckpt -n ${NAMESPACE} \
  -o custom-columns=NAME:.metadata.name,HASH:.status.identityHash,PHASE:.status.phase

kubectl wait \
  --for=jsonpath='{.status.phase}'=Ready \
  dynamocheckpoint/qwen3-06b-bf16 \
  -n ${NAMESPACE} \
  --timeout=30m

Полезные поля status:

• status.phase: high-level lifecycle (Pending, Creating, Ready, Failed)
• status.identityHash: детерминированный hash spec.identity
• status.jobName: имя Job checkpoint
• status.createdAt: timestamp, записанный когда checkpoint стал ready
• status.message: подробности прогресса или ошибки, если доступны

6. Разверните DynamoGraphDeployment, который восстанавливается из checkpointRef

Когда checkpoint станет Ready, восстановите worker из него явно:

apiVersion: nvidia.com/v1alpha1
kind: DynamoGraphDeployment
metadata:
  name: vllm-checkpointref-demo
spec:
  services:
    Frontend:
      componentType: frontend
      replicas: 1
      extraPodSpec:
        mainContainer:
          image: registry.example.com/dynamo/vllm-runtime:1.0.0

    VllmDecodeWorker:
      componentType: worker
      replicas: 1
      checkpoint:
        enabled: true
        checkpointRef: qwen3-06b-bf16
      extraPodSpec:
        mainContainer:
          image: registry.example.com/dynamo/vllm-placeholder:1.0.0
          ...
        ...

Примените его:

kubectl apply -f vllm-checkpointref-demo.yaml -n ${NAMESPACE}
kubectl get pods -n ${NAMESPACE} -w

Pod VllmDecodeWorker должен восстановиться из готового checkpoint вместо создания нового.

Автоматический поток DGD

checkpointRef - самый явный путь. mode: Auto - более высокий уровень: operator вычисляет hash identity checkpoint, ищет эквивалентный DynamoCheckpoint и создаёт новый только тогда, когда подходящий checkpoint отсутствует. Если DynamoCheckpoint с той же identity уже существует, Auto mode повторно использует его. Если подходящий checkpoint ещё не существует, первый worker стартует с cold start, а operator создаёт checkpoint в фоне.

checkpoint:
  enabled: true
  mode: Auto
  identity:
    model: Qwen/Qwen3-0.6B
    backendFramework: vllm
    tensorParallelSize: 1
    dtype: bfloat16
    maxModelLen: 2048

Внутри DynamoGraphDeployment это выглядит так:

apiVersion: nvidia.com/v1alpha1
kind: DynamoGraphDeployment
metadata:
  name: vllm-auto-demo
spec:
  services:
    Frontend:
      componentType: frontend
      replicas: 1
      extraPodSpec:
        mainContainer:
          image: registry.example.com/dynamo/vllm-runtime:1.0.0

    VllmDecodeWorker:
      componentType: worker
      replicas: 1
      checkpoint:
        enabled: true
        mode: Auto
        identity:
          model: Qwen/Qwen3-0.6B
          backendFramework: vllm
          tensorParallelSize: 1
          dtype: bfloat16
          maxModelLen: 2048
      extraPodSpec:
        mainContainer:
          image: registry.example.com/dynamo/vllm-placeholder:1.0.0
          ...
        ...

Auto mode хэширует только checkpoint.identity. Специфическое поведение checkpoint для GMS пока недоступно.

Полезные команды для проверки:

kubectl get dgd vllm-auto-demo -n ${NAMESPACE} \
  -o jsonpath='{.status.checkpoints.VllmDecodeWorker.checkpointName}{"\n"}{.status.checkpoints.VllmDecodeWorker.identityHash}{"\n"}{.status.checkpoints.VllmDecodeWorker.ready}{"\n"}'

kubectl get dckpt -n ${NAMESPACE}

Если вы хотите принудительно выполнить новый restore после того, как checkpoint станет ready, масштабируйте worker:

kubectl patch dgd vllm-auto-demo -n ${NAMESPACE} --type=merge \
  -p '{"spec":{"services":{"VllmDecodeWorker":{"replicas":2}}}}'

Восстановление при failover

Failover restore пока недоступен. Текущий flow Snapshot не поддерживает GMS + Snapshot, поэтому не используйте failover restore как поддерживаемый путь checkpoint/restore. Актуальные рекомендации по GMS и active/passive failover см. в Shadow Engine Failover.

Низкоуровневое тестирование с snapshotctl

Можно создавать checkpoint и восстанавливать pods без Dynamo operator с помощью низкоуровневой утилиты snapshotctl. Однако должен быть установлен snapshot Helm chart, а в namespace должен работать DaemonSet snapshot-agent с примонтированным checkpoint PVC.

snapshotctl предназначен для низкоуровневой отладки и validation workflows, а не как основной пользовательский интерфейс checkpoint. Подробности команд и требования к manifest см. в deploy/snapshot/cmd/snapshotctl/README.md.

Создание checkpoint из manifest worker pod

snapshotctl checkpoint \
  --manifest ./worker-pod.yaml \
  --container main \
  --namespace ${NAMESPACE}

Manifest checkpoint должен относиться к pod и использовать placeholder image. --container указывает workload container, для которого создаётся checkpoint.

Если не передать --checkpoint-id, snapshotctl сгенерирует его и выведет:

status=completed
namespace=...
name=...
checkpoint_job=...
checkpoint_id=manual-snapshot-...
checkpoint_location=/checkpoints/...

Восстановление из manifest worker pod

snapshotctl restore \
  --manifest ./worker-pod.yaml \
  --namespace ${NAMESPACE} \
  --checkpoint-id manual-snapshot-... \
  --containers main

Это создаёт новый restore pod и завершает работу после отправки запроса. Следите за прогрессом через readiness Kubernetes, events и logs.

Восстановление существующего pod на месте

snapshotctl restore \
  --pod existing-restore-target \
  --namespace ${NAMESPACE} \
  --checkpoint-id manual-snapshot-... \
  --containers main

Это накладывает restore metadata на уже существующий pod, совместимый со Snapshot, и завершается после принятия patch.

Идентичность checkpoint

Checkpoints uniquely identify through 16-символьный SHA256 hash (64 bits) конфигурации, влияющей на состояние runtime:

Поле	Обязательно	Влияет на hash	Пример
model	✓	✓	meta-llama/Llama-3-8B
backendFramework	✓	✓	vllm
dynamoVersion		✓	0.9.0, 1.0.0
tensorParallelSize		✓	1, 2, 4, 8
pipelineParallelSize		✓	1, 2
dtype		✓	float16, bfloat16, fp8
maxModelLen		✓	4096, 8192
extraParameters		✓	custom key-value pairs

Поля, которые не изменяют hash checkpoint:

• количество replicas
• размещение на node (nodeSelector, affinity, tolerations)
• requests/limits ресурсов
• конфигурация logging или observability

CRD DynamoCheckpoint

DynamoCheckpoint (shortname: dckpt) - это ресурс, которым управляет operator для lifecycle checkpoint.

Используйте его, когда вам нужно:

• предварительно прогретые checkpoints до появления любого DynamoGraphDeployment
• явное управление lifecycle независимо от DGD
• стабильное человекочитаемое имя, на которое службы могут ссылаться через checkpointRef

Operator требует:

• spec.identity
• spec.job.podTemplateSpec

spec.job.backoffLimit устарел и игнорируется. Job checkpoint всегда выполняются только с одной попыткой.

Проверяйте status с помощью:

kubectl get dckpt -n ${NAMESPACE}
kubectl describe dckpt qwen3-06b-bf16 -n ${NAMESPACE}
kubectl get dckpt qwen3-06b-bf16 -n ${NAMESPACE} -o yaml

Блок status выглядит так:

status:
  phase: Ready
  identityHash: 3bff874d069f0ed5
  jobName: checkpoint-job-3bff874d069f0ed5-1
  createdAt: "2026-01-29T10:05:00Z"
  message: ""

Ограничения

• Поддержка backend ограничена: checkpoint/restore сейчас поддерживают только worker'ы vLLM, и эта поддержка всё ещё находится в ограниченном preview.
• Покрытие worker'ов узкое: специализированные worker'ы, такие как multimodal, embedding и diffusion, не поддерживаются.
• Multi-GPU остаётся preview: конфигурации vLLM с tensor-parallel имеют ограниченную валидацию и пока не являются широко поддерживаемым путём в кластерах.
• Restore GMS остаётся экспериментальным: GMS + Snapshot сейчас отключён.
• Сетевое состояние чувствительно: restore чувствителен к живому состоянию TCP socket. Самый надёжный путь сегодня - loopback bootstrap/control sockets.
• Требуется privileged DaemonSet: snapshot-agent должен работать в privileged mode, чтобы выполнять CRIU и cuda-checkpoint. Workload pods не обязаны быть privileged.

Устранение неполадок

Job checkpoint завершается, но checkpoint так и не становится Ready

Snapshot становится Ready только после того, как snapshot-agent подтвердит содержимое checkpoint. Одного завершившегося Job недостаточно.

kubectl get dckpt <checkpoint-name> -n ${NAMESPACE} \
  -o custom-columns=NAME:.metadata.name,PHASE:.status.phase,MESSAGE:.status.message,JOB:.status.jobName

JOB_NAME=$(kubectl get dckpt <checkpoint-name> -n ${NAMESPACE} -o jsonpath='{.status.jobName}')
if [ -n "${JOB_NAME}" ]; then
  kubectl logs job/"${JOB_NAME}" -n ${NAMESPACE}
fi

kubectl logs daemonset/snapshot-agent -n ${NAMESPACE} --all-containers

Если шаблон worker'а неверный, самые частые причины - использование обычного runtime image вместо placeholder image или отсутствие обычных mounts и secrets, которые нужны worker'у для запуска.

Restore не может найти или смонтировать checkpoint storage

Для установки agentMount по умолчанию restore обнаруживает checkpoint storage через DaemonSet snapshot-agent в namespace workload. Этот DaemonSet должен быть ready и должен монтировать checkpoint PVC.

kubectl rollout status daemonset/snapshot-agent -n ${NAMESPACE}
kubectl get daemonset -n ${NAMESPACE} -l app.kubernetes.io/component=snapshot-agent -o wide
kubectl get pvc -n ${NAMESPACE}

Для shared-agent установки podMount DaemonSet snapshot-agent может работать в infrastructure namespace вместо этого. Проверьте там pods shared-agent, а затем убедитесь, что в namespace workload есть checkpoint PVC, который operator создал или проверил:

kubectl rollout status daemonset/snapshot-agent -n dynamo-system
kubectl get pods -n dynamo-system -l app.kubernetes.io/component=snapshot-agent -o wide
kubectl get pvc snapshot-pvc -n ${NAMESPACE}

В режиме podMount agent обращается к checkpoint через mount namespace workload pod, а не монтирует сам PVC. Проверьте аннотации storage checkpoint у workload pod и журналы snapshot-agent, чтобы увидеть фактический разрешённый путь checkpoint. snapshotctl использует путь разрешения storage из chart, поэтому для низкоуровневой отладки snapshotctl убедитесь, что конфигурация snapshot chart соответствует режиму доступа, который вы тестируете.

snapshotctl отклоняет manifest или целевой объект restore неверный

snapshotctl требует manifest Pod и список target-container. Multi-container manifest'ы поддерживаются, если каждое имя, переданное через --container или --containers, существует в pod spec.

snapshotctl checkpoint --manifest ./worker-pod.yaml --container main --namespace ${NAMESPACE}
snapshotctl restore  --manifest ./worker-pod.yaml --containers main --namespace ${NAMESPACE} --checkpoint-id <checkpoint-id>

Если manifest уже содержит метаданные target Snapshot, они должны совпадать с флагом CLI; snapshotctl отклоняет несовпадения вместо того, чтобы молча выбирать один из вариантов.

Запланированные возможности

• Стабилизировать поддержку multi-GPU
• Добавить поддержку дополнительных backend'ов
• Добавить альтернативные backend'ы storage

Связанная документация

• Installation Guide
• Shadow Engine Failover
• API Reference