Создание эмулятора игр MS-DOS в Kubernetes

В этой статье мы разберёмся, как можно интегрировать JavaScript-библиотеку js-dos в собственное решение Kubernetes, что позволит нам предоставлять доступ к играм MS-DOS в виде сервисов Kubernetes и запускать их в браузере.

Кроме того, по ходу статьи я дам советы и рекомендации начального, продвинутого и высокого уровней по разработке собственных контроллеров Kubernetes при помощи Golang и Kubebuilder или Operator SDK.

▍ Введение

js-dos — это JavaScript-библиотека, содержащая полнофункциональный DOS-плеер, который можно использовать для загрузки программ MS-DOS и для запуска их в веб-браузере; по сути, это порт знаменитого эмулятора DOSBOX на JavaScript. Библиотека js-dos проста, но очень эффективна, её можно установить и использовать как стандартную JavaScript-библиотеку множеством различных способов: в iframe, в nodeJS, в React или непосредственно на «ванильной» HTML-странице, открываемой в браузере. В нашем решении мы воспользуемся последним вариантом.

js-dos имеет собственный формат файлов дистрибутивов под названием bundle. Bundle — это просто zip-файлы, содержащие кучу файлов, необходимых для настройки и конфигурирования эмулятора и самой игры; всё это удобно упаковано в файл с расширением .jsdos. Для загрузки игры и эмулятора на веб-странице в дополнение к нему понадобится HTML-страница (с очень стандартизированным контентом), которая загружает библиотеку js-dos, её файл CSS, файл игры для js-dos, необходимую для игры конфигурацию DOSBOX и, наконец, сам эмулятор DOSBOX в виде WASM.

▍ Проектирование и реализация

Важное примечание: эта статья не является подробным руководством по созданию собственных контроллеров Kubernetes или по программированию на Golang. Она требует базового понимания языка Go и определённого уровня понимания работы контроллеров и операторов Kubernetes; по сути, это введение в Kubebuilder или Operator SDK.

Основная идея заключается в следующем: нам нужна единая структурная сущность, которая будет указывать на бандл (bundle) игры и позволит Kubernetes заняться обеспечением работы и жизненного цикла всех элементов, необходимых для запуска игры в браузере.

Самое очевидное решение заключается в создании Custom Resource (CR) и собственного контроллера, которые предоставят эти ресурсы Kubernetes, обеспечивающему данную функциональность. Давайте назовём этот CR Game; его определение в самой простой форме будет примерно таким:

type GameSpec struct {   // +kubebuilder:validation:Required  // +kubebuilder:validation:Type=string  GameName string `json:"gameName"`   // +kubebuilder:validation:Required  // +kubebuilder:validation:Pattern:=`^https?:\/\/(?:www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b(?:[-a-zA-Z0-9()@:%_\+.~#?&\/=]*)$`  Url string `json:"url"`   // +kubebuilder:default:=false  // +kubebuilder:validation:Required  // +kubebuilder:validation:Type=boolean  Deploy bool `json:"deploy"`   // +optional  // +kubebuilder:default=80  // +kubebuilder:validation:Type=integer  // +kubebuilder:validation:Minimum=1  // +kubebuilder:validation:Maximum=65535  // +kubebuilder:validation:ExclusiveMinimum=false  // +kubebuilder:validation:ExclusiveMaximum=false  Port int `json:"port,omitempty"` }

Game состоит из трёх обязательных и одного опционального поля: GameName — очевидно, это человекочитаемое название игры, Url — это адрес, с которого будет скачиваться бандл игры, Deploy — это булев переключатель для установки и удаления игры; опциональный Port — это номер порта, в котором будет открыт сервис Kubernetes.

Мы можем использовать маркеры (аннотации) // +kubebuilder:validation для конфигурирования и применения значений, валидации диапазонов или типов, напрямую или косвенно при помощи regex для нашего API. Подробнее об этом можно почитать здесь. Такие маркеры подходят для самой простой валидации; если вам нужно реализовать более сложные сценарии, то стоит задуматься о концепции Admissions Webhooks.

Итак, давайте вернёмся к нашему введению. У нас уже есть структура, хранящая базовую информацию об игре. Чтобы эта игра была играбельной, нужно настроить ещё пару вещей. Нам необходима HTML-страница, которая будет загружать а) бандл б) скрипты и таблицы стилизации в) эмулятор DOSBOX и всё, что будет получать и передавать веб-сервер.

Давайте начнём снизу. В качестве веб-сервера мы воспользуемся простым компонентом; это будет инстанс nginx, считывающий простую HTML-страницу и публикующий её в порт 80. Проще всего это сделать, создав Pod и предоставить в этом Pod контейнер nginx, передающий эту страницу.

Но как мы предоставим эту HTML-страницу (отдельно настраиваемую для каждой игры) Kubernetes и позволим контейнеру nginx получать её? Ответ прост: при помощи ConfigMap, которую мы позже смонтируем в контейнер nginx как Volume:

apiVersion: v1 kind: ConfigMap metadata:   name: {{.Name}}-index-configmap   namespace: {{.Namespace}} data:   index.html: |     <!doctype html>     <html>     <head>         <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>         <style>             html, body, #jsdos {                 width: 100%;                 height: 100%;                 margin: 0;                 padding: 0;             }         </style>         <script src="js-dos.js"></script>         <link href="js-dos.css" rel="stylesheet">     </head>     <body>     <div id="jsdos"/>     <script>         emulators.pathPrefix = "/";         Dos(document.getElementById("jsdos"))             .run("{{.Bundle}}");     </script>     </body>     </html>

В разделе data ConfigMap мы укажем ключ index.html, а его значение будет равно template-версии HTML-страницы, отвечающей за загрузку необходимых артефактов для каждой игры.

Ниже я объясню, почему этот и последующие манифесты являются шаблонами, а также расскажу, как мы ими будем пользоваться.

Но здесь у нас возникает проблема! Как говорилось выше, HTML-страница будет отвечать за загрузку необходимых артефактов для каждой игры (например, js-dos.js, jsdos.css и шаблонизированное значение url бандла {{.Bundle}}).

Где мы будем находить эти файлы? Нам нужно скачать их и поместить в Volume, чтобы они были доступны веб-серверу nginx в первый раз, когда кто-то попытается загрузить страницу. Чтобы добиться этого, мы предоставим в нашем Pod второй контейнер, но он будет иметь существенное отличие от предыдущего: это будет контейнер инициализации.

Контейнеры инициализации (Init Container) — это особые контейнеры, запускаемые до других контейнеров в Pod. Контейнеры инициализации могут содержать утилиты или скрипты настройки, отсутствующие в основном контейнере, и помогут нам скачивать файлы, загружать или перезагружать конфигурацию, и так далее.

Поэтому мы не будем усложнять и воспользуемся в качестве образа контейнера инициализации busybox, настроив его на выполнение команды wget, которая скачает все нужные нам артефакты и сохранит их в ту же папку, в которой будет храниться наша HTML-страница. По сути, это означает, что нам нужно смонтировать в контейнер инициализации volume, который мы смонтировали в контейнер nginx.

wget -P "/mnt/game" --no-check-certificate \  {{.BundleUrl}} \ https://js-dos.com/v7/build/releases/latest/js-dos/js-dos.css \ https://js-dos.com/v7/build/releases/latest/js-dos/js-dos.js \ https://js-dos.com/v7/build/releases/latest/js-dos/wdosbox.js \ https://js-dos.com/v7/build/releases/latest/js-dos/wdosbox.wasm

Но теперь вы вполне справедливо можете задаться вопросом: постойте-ка, а что насчёт Volume, кто и как будет его предоставлять? В случае HTML-контента нашего контейнера nginx ответ прост: ConfigMap можно смонтировать как volume в контейнер, но для артефактов, скачанных контейнером инициализации и используемых контейнером nginx нужно предоставить PersistentVolumeClaim (PVC):

apiVersion: v1 kind: PersistentVolumeClaim metadata:   name: {{.Name}}-pvc   namespace: {{.Namespace}} spec:   accessModes:     - ReadWriteOnce   resources:     requests:       storage: {{.Storage}}Mi

PersistentVolumeClaim (PVC) — это абстрактный запрос хранилища от пользователя. Он схож с Pod. Pod потребляют ресурсы узлов, а PVC потребляют ресурсы Persistent Volume (PV). Pod могут запрашивать конкретные уровни ресурсов (CPU или память). Claim могут запрашивать конкретный размер и режимы доступа (например, их можно смонтировать как ReadWriteOnce, ReadOnlyMany или ReadWriteMany).

PVC — это абстрактный запрос хранилища; когда Pod в первый раз привязывается к PVC (в нашем случае это происходит в контейнере инициализации) драйвер внутреннего хранилища автоматические создаёт PersistentVolume, который затем будет прикреплён к контейнерам без каких-либо действий с нашей стороны.

Вы можете задаться вопросом: всё это становится немного запутанным, можно ли навести немного порядок? Да, и для этого мы создадим Deployment, который будет владеть всеми этими ресурсами и предоставлять их от нашего имени:

apiVersion: apps/v1 kind: Deployment metadata:   name: {{.Name}}   namespace: {{.Namespace}}   labels:     app: {{.Name}} spec:   replicas: 1   selector:     matchLabels:       app: {{.Name}}   template:     metadata:       name: {{.Name}}       labels:         app: {{.Name}}     spec:       volumes:         - name: {{.Name}}-storage           persistentVolumeClaim:             claimName: {{.Name}}-pvc         - name: {{.Name}}-index           configMap:             name: {{.Name}}-index-configmap       containers:         - name: {{.Name}}-engine           image: nginx           imagePullPolicy: IfNotPresent           ports:             - containerPort: 80           volumeMounts:             - mountPath: /usr/share/nginx/html               name: {{.Name}}-storage             - mountPath: /usr/share/nginx/html/index.html               subPath: index.html               name: {{.Name}}-index       initContainers:         - name: {{.Name}}-init           image: busybox:1.28           imagePullPolicy: IfNotPresent           command: [ "sh" ]           args:             - -c             - >-                 wget -P "/mnt/game" --no-check-certificate {{.BundleUrl}} https://js-dos.com/v7/build/releases/latest/js-dos/js-dos.css https://js-dos.com/v7/build/releases/latest/js-dos/js-dos.js https://js-dos.com/v7/build/releases/latest/js-dos/wdosbox.js https://js-dos.com/v7/build/releases/latest/js-dos/wdosbox.wasm;           volumeMounts:             - mountPath: /mnt/game               name: {{.Name}}-storage       restartPolicy: Always

Заглянув в spec.volumes, можно чётко увидеть, что мы приказали создать два volume, один из ConfigMap, второй из PVC. Сделанный из PVC монтируется в оба контейнера (см. volumeMounts в разделе containers и initContainers). В контейнере nginx есть небольшая тонкость, практически благодаря которой всё это работает: оба volume монтируются по одному пути в контейнер nginx, откуда веб-сервер будет брать HTML-страницу index.html.

volumeMounts:             - mountPath: /usr/share/nginx/html               name: {{.Name}}-storage             - mountPath: /usr/share/nginx/html/index.html               subPath: index.html               name: {{.Name}}-index

Разумеется, теперь нужно сделать так, чтобы у нас был доступ к контейнеру nginx вне границ Kubernetes, так мы сможем отрендерить HTML-страницу в браузере и сыграть в игру. Для этого мы предоставим Service:

apiVersion: v1 kind: Service metadata:   name: {{.Name}}   namespace: {{.Namespace}} spec:   selector:     app: {{.Name}}   ports:     - protocol: TCP       port: {{.Port}}       targetPort: 80   type: ClusterIP

▍ Создание контроллера

Основная причина разработки контроллера заключается в создании легковесного контроллера, который не будет генерировать внутри кластера ненужного «шума», так как потенциально мы можем загрузить довольно большое количество Game — сейчас в проекте сообщества js-dos dos.zone есть почти 2000 игр.

Чтобы минимизировать ненужные циклы синхронизации (reconciliation), мы будем играть при помощи так называемых Event Filters, настроив контроллер на фильтрацию того, какие события создания/обновления/удаления и общие события будут вызывать процесс синхронизации. Предикат добавляется к watch-объекту, который регулирует, должен ли он вызывать запрос синхронизации:

var (  gameEventFilters = builder.WithPredicates(predicate.Funcs{   UpdateFunc: func(e event.UpdateEvent) bool {    return e.ObjectOld.GetGeneration() != e.ObjectNew.GetGeneration()   },   DeleteFunc: func(e event.DeleteEvent) bool {    return !e.DeleteStateUnknown   },   CreateFunc: func(e event.CreateEvent) bool {    switch object := e.Object.(type) {    case *operatorv1alpha1.Game:     return object.Spec.Deploy    default:     return false    }   },  }) )  func (r *GameReconciler) SetupWithManager(mgr ctrl.Manager) error {  return ctrl.NewControllerManagedBy(mgr).   For(&operatorv1alpha1.Game{}, gameEventFilters).  Complete(r) }

Мы имеем возможность выполнять контроль через четыре предикативные функции с соответствующими событиями: GenericFunc (здесь не используется), CreateFunc, UpdateFunc и DeleteFunc. Обратите внимание, что во время события Update синхронизация происходит только тогда, когда возникают реальные изменения в specs Game, а не когда происходит обновление status при сравнении на семантическое равенство значений ObjectOld и ObjectNew:

UpdateFunc: func(e event.UpdateEvent) bool {    return e.ObjectOld.GetGeneration() != e.ObjectNew.GetGeneration()   }

Мы полностью заглушаем события Delete. После удаления Game нам не нужно ничего обновлять в кластере. DeleteStateUnknown равно false, только если объект подтверждён API-сервером как удалённый:

DeleteFunc: func(e event.DeleteEvent) bool {    return !e.DeleteStateUnknown   }

Наконец, в процессе события Create мы позволяем запустить синхронизацию, только если вызвавший срабатывание событий CR — это Game и только если значение его поля Spec.deploy равно true.

CreateFunc: func(e event.CreateEvent) bool {    switch object := e.Object.(type) {    case *operatorv1alpha1.Game:     return object.Spec.Deploy    default:     return false    }   }

На то есть две причины: а) Game владеет ресурсами, которые мы рассмотрели в предыдущем параграфе (Deployment; а Deployment, в свою очередь, владеет ресурсами Pod, ConfigMap, PVC, PV и Service. Если мы удалим Game, то хотим, чтобы все эти ресурсы удалялись автоматически). Если в будущем мы хотим наблюдать за другими такими ресурсами, то у нас должна быть возможность определить источник событий. б) как говорилось ранее, потенциально может существовать огромное количество Game, которые создаются в больших масштабах. Если они одновременно вызовут процесс синхронизации, то мы подвергнем кластер чрезмерной нагрузке, поэтому нужно гарантировать, что только новые создаваемые Game, у которых Spec.Deploy имеет значение true, вызывали синхронизацию во время события Create.

А теперь давайте рассмотрим функциональность цикла синхронизации:

func (r *GameReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {  logger = log.FromContext(ctx).WithName("controller")   game := &operatorv1alpha1.Game{}  if err := r.Get(ctx, req.NamespacedName, game); err != nil {   if apierrors.IsNotFound(err) {    return ctrl.Result{}, nil   }    logger.V(5).Error(err, "unable to fetch game")   return ctrl.Result{}, err  }   if !game.Spec.Deploy {   err := r.DeleteDeployment(ctx, req, game)   if err != nil {    return ctrl.Result{}, err   }    _ = r.SetStatus(ctx, req, game, false)   return ctrl.Result{}, nil  }   deployment, err := r.CreateOrUpdateDeployment(ctx, req, game)  if err != nil {   return ctrl.Result{}, err  }   _, err = r.CreateOrUpdateConfigMap(ctx, req, game, deployment)  if err != nil {   return ctrl.Result{}, err  }   _, err = r.CreateOrUpdatePersistentVolumeClaim(ctx, req, game, deployment)  if err != nil {   return ctrl.Result{}, err  }   _, err = r.CreateOrUpdateService(ctx, req, game, deployment)  if err != nil {   return ctrl.Result{}, err  }   return r.RefreshStatus(ctx, req, game, deployment.Labels["app"]) }

Задача функции Reconcile заключается в управлении ресурсом Game. Если Spec.Deploy имеет значение false, то все предоставленные им ресурсы должны быть удалены (если ранее были установлены), а затем Spec.Deploy должно быть присвоено значение true, чтобы все необходимые артефакты были предоставлены идемпотентным образом.

Каждая функция CreateOrUpdateXXX выполняет две простые взаимосвязанные задачи:

а) Создаёт конкретный манифест для соответствующего ресурса:

На самом деле, мы можем создать все эти ресурсы Kubernetes и при помощи одного Golang, без шаблонов манифестов, но на мой взгляд, это обычно сложнее читать, сложнее поддерживать и менять; к тому же в долговременной перспективе повышается возможность ошибок.

Альтернативным решением было бы создание генерации манифестов в формате шаблонов, которые бы мы могли парсить в идиоматическом для Golang стиле при помощи пакета text/template. Для этих целей я сохранил все эти шаблоны YAML в отдельную папку, которую назвал manifests. Я создал пакет assets, использующий пакет embed для получения ссылки на содержимое манифестов.

//go:embed manifests/*  manifests embed.FS

Содержимое каждого шаблона считывается из функции getTemplate при помощи manifests.ReadFile, которая из подвергнутого парсингу контента возвращает вызывающей стороне шаблон:

func getTemplate(name string) (*template.Template, error) {  manifestBytes, err := manifests.ReadFile(fmt.Sprintf("manifests/%s.yaml", name))  if err != nil {   return nil, err  }   tmp := template.New(name)  parse, err := tmp.Parse(string(manifestBytes))  if err != nil {   return nil, err  }   return parse, nil }

Затем вызывающая сторона создаёт анонимную struct metadata со значениями, которые должны быть заменены в шаблоне (например, для PVC):

metadata := struct {   Namespace string   Name      string   Storage   uint64  }{   Namespace: namespace,   Name:      name,   Storage:   storage,  }

Вызывающая сторона вызывает функцию getObject, которая заменяет заполнители шаблона значениями анонимной struct, а после передаёт созданный манифест объекту Golang, который узнает API-сервер.

func getObject(name string, gv schema.GroupVersion, metadata any) (runtime.Object, error) {  parse, err := getTemplate(name)  if err != nil {   return nil, err  }   var buffer bytes.Buffer  err = parse.Execute(&buffer, metadata)  if err != nil {   return nil, err  }   object, err := runtime.Decode(   appsCodecs.UniversalDecoder(gv),   buffer.Bytes(),  )   return object, nil }

б) Развёртывает этот ресурс:

После получения нужного ресурса каждая функция CreateOrUpdateXXX теперь может создать ресурс в Kubernetes (и задать соответствующего владельца этого ресурса при помощи SetControllerReference):

deployment, err = assets.GetDeployment(game.Namespace, game.Name, game.Spec.Port, game.Spec.Url)   if err != nil {    logger.Error(err, "unable to parse deployment template")    return nil, err   }    err = ctrl.SetControllerReference(game, deployment, r.Scheme)   if err != nil {    logger.Error(err, "unable to set controller reference")    return nil, err   }    err = r.Create(ctx, deployment)   if err != nil {    logger.Error(err, "unable to create deployment")    return nil, err   }

Ожидая развёртывания ресурсов и завершения работы контейнера инициализации, контроллер периодически проверяет его статус (каждые 15 секунд). Когда статус Pod становится ready, выполняется выход из цикла синхронизации и ожидаются только внешние события (Create, Update или Delete), которые могут запустить его в будущем.

func (r *GameReconciler) RefreshStatus(  ctx context.Context,  req ctrl.Request,  game *operatorv1alpha1.Game,  appLabel string, ) (ctrl.Result, error) {  ready, err := r.GetStatus(ctx, req, appLabel)  if err != nil {   logger.V(5).Error(err, "unable to fetch pod status")    _ = r.SetStatus(ctx, req, game, false)    return ctrl.Result{    Requeue:      true,    RequeueAfter: 15 * time.Second,   }, err  }   if !ready {   logger.Info("pod not ready, requeue in 15sec")    _ = r.SetStatus(ctx, req, game, ready)    return ctrl.Result{    Requeue:      true,    RequeueAfter: 15 * time.Second,   }, nil  }   err = r.SetStatus(ctx, req, game, ready)  if err != nil {   return ctrl.Result{    Requeue:      true,    RequeueAfter: 15 * time.Second,   }, nil  }   return ctrl.Result{}, nil }

После подготовки Deployment и Pod контейнер инициализации скачивает все файлы и сохраняет их в PV.

Давайте протестируем систему и развернём манифест, который установит в наш кластер Prince of Persia:

apiVersion: operator.contrib.dosbox.com/v1alpha1 kind: Game metadata:   name: prince-of-persia spec:   gameName: "Prince of Persia"   url: "https://cdn.dos.zone/original/2X/1/1179a7c9e05b1679333ed6db08e7884f6e86c155.jsdos"   deploy: true

После завершения развёртывания мы готовы к переадресации порта Service и проверке в браузере (я выбрал порт 8080; на самом деле, не важно, на какой порт вы решите выполнять переадресацию):

▍ Работа на будущее

Этот мини-проект далёк от завершения. В нём отсутствует даже базовая функциональность, например, сохранение прогресса в PV, публикация метрик в Prometheus, публикация событий в Kubernetes, обновление Conditions статуса для CR, установка лимитов ресурсов для контейнеров, и многое другое. Тем не менее, его стоит попробовать, вы получите много удовольствия от этих ретроигр; также можно форкнуть репозиторий и двигаться в собственном направлении: GitHub — akyriako/kube-dosbox.

Скидки, итоги розыгрышей и новости о спутнике RUVDS — в нашем Telegram-канале ?