Перейти к основному содержимому

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.

Оператор Dynamo

Обзор​

Оператор Dynamo — это Kubernetes-оператор, который упрощает развертывание, конфигурацию и управление жизненным циклом DynamoGraphs. Он автоматизирует согласование пользовательских ресурсов, чтобы нужное вам состояние всегда достигалось. Этот оператор хорошо подходит пользователям, которые хотят управлять сложными развертываниями с помощью декларативных YAML-описаний и нативных Kubernetes-инструментов.

Архитектура​

  • Развертывание оператора: Развертывается как Kubernetes Deployment в определенном пространстве имен.

  • Контроллеры:

    • DynamoGraphDeploymentController: следит за CR DynamoGraphDeployment и оркестрирует развертывания графов.
    • DynamoComponentDeploymentController: следит за CR DynamoComponentDeployment и управляет развертываниями отдельных компонентов.
    • DynamoModelController: следит за CR DynamoModel и управляет жизненным циклом модели (например, загрузкой LoRA adapters).

  • Рабочий процесс:

    1. Пользователь или API server создает пользовательский ресурс.
    2. Соответствующий контроллер обнаруживает изменение и запускает reconciliation.
    3. Ресурсы Kubernetes (Deployment, Service и т. д.) создаются или обновляются, чтобы соответствовать спецификации CR.
    4. Поля состояния обновляются, чтобы отражать текущее состояние.

Режимы развертывания​

Оператор Dynamo поддерживает три режима развертывания, чтобы учитывать разные среды кластера и сценарии использования:

1. Общекластерный режим (по умолчанию, рекомендуется)​

Оператор отслеживает и управляет ресурсами DynamoGraph во всех пространствах имен кластера.

Когда использовать:

  • У вас есть полный административный доступ к кластеру
  • Вы хотите централизованно управлять всеми нагрузками Dynamo
  • Стандартное production-развертывание на выделенном кластере

2. Режим с ограничением по namespace (УСТАРЕЛО)​

УСТАРЕЛО: Режим с ограничением по пространству имен (namespaceRestriction.enabled=true) устарел и будет удален в будущем выпуске. Вместо него используйте общекластерный режим. Не применяйте его для новых развертываний.

Оператор отслеживает и управляет ресурсами DynamoGraph только в конкретном пространстве имен. Создается lease-маркер, который сообщает о присутствии оператора любым общекластерным операторам.

Когда использовать:

  • Вы работаете в общем/multi-tenant кластере
  • У вас есть только права на уровне пространства имен
  • Вы хотите изолированно протестировать новую версию оператора
  • Вам нужно избежать конфликтов с другими операторами

Установка:

helm install dynamo-platform dynamo-platform-${RELEASE_VERSION}.tgz \
  --namespace my-namespace \
  --create-namespace \
  --set dynamo-operator.namespaceRestriction.enabled=true

3. Гибридный режим (УСТАРЕЛО)​

УСТАРЕЛО: Гибридный режим опирается на операторы с ограничением по пространству имен, которые устарели и будут удалены в будущем выпуске. Вместо этого используйте один общекластерный оператор.

Общекластерный оператор управляет большинством пространств имен, а один или несколько операторов с ограничением по пространству имен работают в отдельных пространствах имен (например, для тестирования новых версий). Общекластерный оператор автоматически обнаруживает пространства имен с такими операторами и исключает их с помощью lease-маркеров.

Когда использовать:

  • Запуск production-нагрузок со стабильной версией оператора
  • Тестирование новых версий оператора в изолированных пространствах имен без влияния на production
  • Поэтапный rollout обновлений оператора
  • Среды разработки/staging в production-кластерах

Как это работает:

  1. Оператор с ограничением по пространству имен создает lease с именем dynamo-operator-namespace-scope в своем namespace
  2. Общекластерный оператор отслеживает эти lease-маркеры во всех пространствах имен
  3. Общекластерный оператор автоматически исключает любое пространство имен с lease-маркером
  4. Если оператор с ограничением по пространству имен останавливается, его lease истекает (TTL: 30s по умолчанию)
  5. Общекластерный оператор автоматически возобновляет управление этим пространством имен

Пример настройки:

# 1. Install cluster-wide operator (production, v1.0.0)
helm install dynamo-platform dynamo-platform-${RELEASE_VERSION}.tgz \
  --namespace dynamo-system \
  --create-namespace

# 2. Install namespace-scoped operator (testing, v2.0.0-beta)
helm install dynamo-test dynamo-platform-${RELEASE_VERSION}.tgz \
  --namespace test-namespace \
  --create-namespace \
  --set dynamo-operator.namespaceRestriction.enabled=true \
  --set dynamo-operator.controllerManager.manager.image.tag=v2.0.0-beta

Наблюдаемость:

# List all namespaces with local operators
kubectl get lease -A --field-selector metadata.name=dynamo-operator-namespace-scope

# Check which operator version is running in a namespace
kubectl get lease -n my-namespace dynamo-operator-namespace-scope \
  -o jsonpath='{.spec.holderIdentity}'

Определения пользовательских ресурсов (CRD)​

Dynamo предоставляет следующие пользовательские ресурсы:

  • DynamoGraphDeployment (DGD): развертывает полные inference-пайплайны
  • DynamoComponentDeployment (DCD): развертывает отдельные компоненты
  • DynamoModel: управляет жизненным циклом модели (например, загрузкой LoRA adapters)

Полный технический справочник API для Dynamo Custom Resource Definitions см. здесь:

📖 Dynamo CRD API Reference

Руководство, ориентированное на пользователя, по развертыванию и управлению моделями с помощью DynamoModel см. здесь:

📖 Managing Models with DynamoModel Guide

Webhook'и​

Оператор Dynamo использует admission webhooks Kubernetes для проверки и изменения пользовательских ресурсов в реальном времени до того, как они сохраняются в кластере. Webhook'и являются обязательным компонентом оператора и гарантируют, что неверные конфигурации будут немедленно отклонены на уровне API server.

Основные возможности:

  • ✅ Общая инфраструктура сертификатов для всех типов webhook
  • ✅ Автоматическая генерация и ротация сертификатов (по умолчанию, для всех сред)
  • ✅ Интеграция с cert-manager (опционально, для собственного PKI)
  • ✅ Принудительное обеспечение неизменяемости критических полей

Полную документацию по webhook'ам, управлению сертификатами и устранению неполадок см. здесь:

📖 Webhooks Guide

Наблюдаемость​

Оператор Dynamo обеспечивает полную наблюдаемость через метрики Prometheus и дашборды Grafana. Это позволяет отслеживать:

  • Производительность контроллеров: длительность цикла reconciliation, долю успешных операций и долю ошибок по типам ресурсов
  • Активность webhook'ов: производительность проверки, частоту admission и шаблоны отказов
  • Инвентарь ресурсов: текущее количество управляемых ресурсов по состоянию и namespace
  • Операционная готовность: долю успешных операций и индикаторы здоровья контроллеров и webhook'ов

Сбор метрик​

Метрики автоматически публикуются на endpoint /metrics оператора (порт 8443 по умолчанию) и собираются Prometheus через ServiceMonitor. ServiceMonitor автоматически создается при установке оператора через Helm (управляется параметром metricsService.enabled, который по умолчанию равен true).

Дашборд Grafana​

Для визуализации метрик оператора доступен готовый дашборд Grafana. Он включает:

  • Метрики reconciliation: rate, длительность (P95) и ошибки по типам ресурсов
  • Метрики webhook'ов: rate запросов, длительность (P95) и отказы по типам ресурсов и операциям
  • Инвентарь ресурсов: количество DynamoGraphDeployment по состоянию и namespace
  • Операционная готовность: индикаторы доли успешных операций для контроллеров и webhook'ов

Полные инструкции по настройке и справочник метрик см. здесь:

📖 Operator Metrics Guide

Установка​

Быстрая установка через Helm​

# Задать окружение
export NAMESPACE=dynamo-system
export RELEASE_VERSION=0.x.x # any version of Dynamo 0.3.2+ listed at https://github.com/ai-dynamo/dynamo/releases

# Установить Platform (включает operator)
helm fetch https://helm.ngc.nvidia.com/nvidia/ai-dynamo/charts/dynamo-platform-${RELEASE_VERSION}.tgz
helm install dynamo-platform dynamo-platform-${RELEASE_VERSION}.tgz --namespace ${NAMESPACE} --create-namespace

Примечание: Режимы развертывания с ограничением по namespace и гибридный режим устарели. Для всех новых развертываний используйте общекластерный режим. Если вам нужны обратно совместимые конфигурации, см. Режимы развертывания выше.

Сборка из исходников​

# Задать окружение
export NAMESPACE=dynamo-system
export DOCKER_SERVER=your-registry.com/  # your container registry
export IMAGE_TAG=latest

# Собрать образ operator
cd deploy/operator
docker build -t $DOCKER_SERVER/kubernetes-operator:$IMAGE_TAG \
  --build-context snapshot=../snapshot \
  --build-arg DOCKER_PROXY="" \
  .
docker push $DOCKER_SERVER/kubernetes-operator:$IMAGE_TAG
cd -

# Установить platform с пользовательским образом operator (CRD автоматически устанавливаются chart)
cd deploy/helm/charts
helm install dynamo-platform ./platform/ \
  --namespace ${NAMESPACE} \
  --create-namespace \
  --set "dynamo-operator.controllerManager.manager.image.repository=${DOCKER_SERVER}/kubernetes-operator" \
  --set "dynamo-operator.controllerManager.manager.image.tag=${IMAGE_TAG}" \
  --set dynamo-operator.imagePullSecrets[0].name=docker-imagepullsecret

Подробные варианты установки см. в руководстве по установке

Разработка​

  • Структура кода:

Оператор собран с использованием Kubebuilder и operator-sdk и имеет следующую структуру:

  • controllers/: логика reconciliation
  • api/v1alpha1/: типы CRD
  • config/: манифесты и Helm chart'ы

Ссылки​