Re: [devel-distro] Пример файла разметки и описания

[Leonid Krivoshein <klark.devel@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 5292 bytes --]


On 10/10/24 01:08, Leonid Krivoshein wrote:
>> [...]
>>> По результатам обсуждения я сформулировал следующие тезисы:
>>> 1. Графический интерфейс инсталлятора представляет собой конфигуратор,
>>> который создаёт сценарий автоустановки (kickstart-файл)
>> Я не считаю, что у нас возможна совместимость с redhat в этом вопросе.
>> Поэтому я предлагаю придумать этому файлу другой формат и название.
>> Взяв у коллег лучшее, естественно.
>>
>> Формат должен быть документирован, его корректность и наличие
>> всех необходимых полей должны быть проверяемы программно (т.е.
>> нужна схема).
>
> Да. Yaml. СхемЫ тоже на Yaml. Есть возражения? Во множественном, т.к. 
> модульность, схемы будут разделены по пакетам. Важна строгая 
> типизация, давно обсуждали это и кажется Иван Захарящев даже что-то 
> делал для этого с woo.
>

Разметка дисков -- существенная часть установщика. Давно хочу написать 
этот бэкенд и уже примеряюсь к инструментарию, хотя архитектура Volume 
Slicer (vs) созрела окончательно в прошлом году.

Всегда считал, что описание разметки -- весьма непростая сущность, оно 
не обязано быть в том же формате, что и файл ответов, хотя служит тем же 
целям. Если вдруг это совпадёт, будет здорово, можно вложить одно 
Yaml-дерево в другое, но всегда можно использовать просто ссылку на 
отдельный файл.

Для предметного обсуждения приложил пару файлов одной и той же 
развесистой разметки и краткое описание основных разделов. Ключи в 
описаниях блочных сущностный должны просто соответствовать длинным 
опциям, создающим эти блочные сущности. К примеру, "homehost: FIXED" в 
файле разметки превратится в "--homehost FIXED" при вызове mdadm. Такой 
подход позволяет полностью сохранить семантику при работе с внешними 
утилитами.

Для проверки схемы используется pydantic. Выбирал из десятка похожих 
проектов. В результате схема описывается где-то в Yaml-файлах, где-то 
прямо в коде. Пример рабочих сниппетов для лучшего понимания:

def to_kebab(s: str) -> str:
     return s.replace('_', '-')

...

class Filesystem(BaseModel):
     id: int | None = None
     fstype: str | None = None
     label: str | None = None
     uuid: UUID | None = None
     no_discard: bool | None = None

     model_config = ConfigDict(
         alias_generator=AliasGenerator(
             validation_alias=to_snake,
             serialization_alias=to_kebab,
         )
     )

     def model_post_init(self, __context: Any) -> None:
         if self.fstype is None:
             self.fstype = self.__class__.__name__
         self.id = id(self)

     @model_validator(mode='after')
     def check_fstype(self) -> Self:
         print(f'fields of the {self.fstype} filesystem are checked')
         return self
...

class vfat(Filesystem):
     uuid: str | None = Field(
         default=None,
         min_length=9,
         max_lenght=9,
         pattern=r'^[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{4}$'
     )
...

Сама разбивалка должна получиться не очень сложной, т.к. используется 
много внешнего и готового. Например, для чтения используется lsblk с 
выводом в json, pyudev, нативные утилиты, типа dumpe2fs. Ближайшее 
чем-то похожее решение -- blivet, который немного залочен на RedHat и 
построен вокруг libblockdev. При желании его можно использовать, в 
Debian смогли прикрутить. Ещё чем-то очень отдалённо напоминает 
libstorage-ng, которая использует DOM/XML-дерево (XML-файл разметки).


-- 
WBR, Leonid Krivoshein.

[-- Attachment #2: condtree.yaml --]
[-- Type: application/x-yaml, Size: 5880 bytes --]

[-- Attachment #3: exp-list.yaml --]
[-- Type: application/x-yaml, Size: 7202 bytes --]

[-- Attachment #4: layout-ru.md --]
[-- Type: text/markdown, Size: 12920 bytes --]

# Формат файла разметки дисков

## VSCT/1.0: Volume Slicer Condensed Tree, Version 1.0

Исходный файл с глубокой иерархией вложенности, позволяющий определить
зависимости одних сущностей от других без необходимости идентификации
каждой блочной сущности. В числе особенностей: поддержка наборов дисков,
автоматическая идентификация узлов дерева устройств, поддержка значений
по умолчанию для блочных сущностей и файловых систем. В этом формате
допускается определение групп дисков под общим идентификатором и групп
операций, выполняемых над ними по одному принципу.

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

* `general`: информация о формате данных и глобальные опции
* `defaults`: значения по умолчанию для других секций этого файла
* `activate`: описания подсистем, задействованных до начала разметки
* `protected`: описания всех исключаемых (защищаемых) дисков
* `targets`: описания всех включаемых целевых дисков
* `layout`: описание проверяемых элементов существующей разметки
* `delete`: список удаляемых элементов существующей разметки
* `change`: описание изменений существующей разметки
* `create`: описание вновь создаваемых элементов будущей разметки
* `volumes`: список форматируемых томов и монтируемых файловых систем

Обязательными являются секции `general` и `targets`. Остальные зависят
от того, что мы хотим сделать при помощи данного файла разметки дисков.

## VSEL/1.0: Volume Slicer Expanded List, Version 1.0

Внутренний формат развёрнутого списка, в котором сохранён только первый
уровень исходного формата. Всем узлам присвоены какие-то идентификаторы,
если их не было в исходном файле. Наборы дисков и операций над ними под
общим идентификатором развёрнуты до индивидуальных дисков и операций,
каждая под своим идентификатором. Каждая блочная сущность перенесена на
второй уровень соответствующего раздела. Каждая файловая система перенесена
из раздела `create` в раздел `volumes`. Все блочные сущности и файловые
системы насыщены дефолтными значениями и информацией о позиционировании
блока в исходном файле. Раздел значений по умолчанию удалён. Добавлены
замыкания блочных устройств, имеющих дочерние устройства.

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

* `general`: информация о формате данных и глобальные опции
* `activate`: описания подсистем, задействованных до начала разметки
* `protected`: описания всех исключаемых (защищаемых) дисков
* `targets`: описания всех включаемых целевых дисков
* `layout`: описание проверяемых элементов существующей разметки
* `delete`: список удаляемых элементов существующей разметки
* `change`: описание изменений существующей разметки
* `create`: описание вновь создаваемых элементов будущей разметки
* `volumes`: список форматируемых томов и монтируемых файловых систем

Обязательными являются секции `general` и `targets`. Остальные зависят
от того, что мы хотим сделать при помощи данного файла разметки дисков.

## Секция general

Определяет по сути две вещи:

* `data-format`: формат данных («VSCT/1.0» либо «VSEL/1.0»), «auto»
  по умолчанию, это поле можно сделать необязательным, если определить
  тип данных окажется возможным автоматически.
* `*`: глобальные флаги и опции, перебивающие дефолтные значения vs,
  но имеющие меньший приоритет, чем опции командной строки.

## Секция defaults

Позволяет определить значения по умолчанию для других секций этого файла
персонально для каждого типа описываемой блочной сущности либо файловой
системы. Например, если мы хотим, чтобы все разделы создавались с типом
RAID, можно указать для блочной сущности `part` дефолтное значение:

```
defaults:
  part:
    parttype: R
```

Секция поддерживается только в исходном файле типа `Condensed Tree`, она
удаляется при развёртывании «сжатого дерева» во внутренний формат списка.

## Секция activate

Может включать описание задействованных в разметке подсистем и файловых
систем, проверяемых и активируемых до начала процедуры разметки. Например,
таких, как: `multipath`, `iscsi`, `fcoe`, `aoe`, `ipoib`, `raid`, `lvm2`,
`ext4`, `swap`, `jfs`, `xfs`, `btrfs`, итд. Описание подсистем необходимо
для определения всех необходимых зависимостей на целевой системе и запуска
команд, служб, загрузки модулей ядра, установки соединений, в том числе,
с использованием аутентификационных данных, что позволит обнаружить или
подключить блочные устройства штатными средсвами Linux ядра и userspace
ещё до того, как будет запущен процесс обнаружения целевых дисков.

Нет необходимости перечислять все задействованные подсистемы в исходном
файле типа `Condensed Tree`, они заново определяются автоматически при
развёртывании «сжатого дерева» во внутренний формат списка.

## Секция protected

Перед поиском целевых дисков выполняется активация подсистем, исключаются
все диски и разделы, которые смонтированы в настоящий момент. Дополнительно
исключаются диски, указанные в командной строке, и диски, описания которых
перечислены в настоящей секции файла разметки.

## Секция targets

Второй обязательный раздел, в котором описывается каждый целевой диск или
набор целевых дисков, соответствующие заданным критериям. Каждая следующая
секция файла описывает блочные сущности, которые строятся поверх целевых
дисков.

## Секция layout

В ней описываются блочные сущности и файловые системы, которые должны быть
проверены до внесения в разметку каких-либо изменений. Например, если мы
собираемся удалить два раздела с порядковыми номерами 5 и 6, создать новый
раздел и отформатировать его, в данной секции мы описываем существующую
таблицу разделов и, по меньшей мере, удаляемые разделы с номерами 5 и 6.

## Секция delete

В ней только перечисляются идентификаторы блочных сущностей и файловых
систем, которые были описаны в секции `layout`, и которые должны быть
рекурсивно удалены. Удаление выполняется всегда в указанном порядке
только после проверки и до внесения каких-либо иных изменений.

## Секция change

Описывает изменения отдельных свойств блочных сущностей и файловых систем
в уже существующей разметке, описанной ранее в секции `layout` и с учётом
уже выполненных к данному моменту удалений, если таковые были указаны в
секции `delete`. Здесь можно переопределить названия томов, их UUID'ы,
выполнить очистку, уменьшить или увеличить размеры разделов и другие
поддерживаемые операции, выполняемые всегда в указанном порядке.

## Секция create

Описывает все вновь создаваемые элементы будущей разметки. Они создаются
либо поверх целых дисков, описанных ранее в секции `targets`, либо поверх
элементов существующей разметки, описанной ранее в секции `layout`, но с
учётом уже выполненных к данному моменту удалений, если таковые были указаны
в секции `delete`, и с учётом уже выполненных к данному моменту изменений,
если таковые были указаны в секции `change`. При конвертировании во внутренний
формат из секции `create` удаляются описания форматируемых файловых систем.

## Секция volumes

Описывает все вновь создаваемые файловые системы, т.е. только то, что
должно быть отформатировано. Их можно описывать и в секции `create` в
исходном файле разметки, но во внутреннем формате они все будут перенесны
в секцию `volumes`. В секции `layout` перечисляются только те файловые
системы, которые будут проверены, которые должны существовать на момент
запуска утилиты, и которые могут быть использованы в процессе каскадного
монтирования томов, но они не участвуют в отдельной операции форматирования.