From 5d47bbe04cda6f9a4ed1aadd22669bda82ad4af3 Mon Sep 17 00:00:00 2001 From: Vitaliy Filippov Date: Sat, 29 Jan 2022 23:43:22 +0300 Subject: [PATCH] Add documentation --- README-ru.md | 718 ++---------------- README.md | 681 ++--------------- docs/config.en.md | 38 + docs/config.ru.md | 39 + docs/config/common.en.md | 46 ++ docs/config/common.ru.md | 45 ++ docs/config/inode.en.md | 32 + docs/config/inode.ru.md | 34 + docs/config/layout-cluster.en.md | 124 +++ docs/config/layout-cluster.ru.md | 134 ++++ docs/config/layout-osd.en.md | 176 +++++ docs/config/layout-osd.ru.md | 185 +++++ docs/config/monitor.en.md | 79 ++ docs/config/monitor.ru.md | 80 ++ docs/config/network.en.md | 214 ++++++ docs/config/network.ru.md | 224 ++++++ docs/config/osd.en.md | 297 ++++++++ docs/config/osd.ru.md | 310 ++++++++ docs/config/pool.en.md | 197 +++++ docs/config/pool.ru.md | 195 +++++ docs/config/src/common.en.md | 3 + docs/config/src/common.ru.md | 3 + docs/{params => config/src}/common.yml | 0 docs/config/src/layout-cluster.en.md | 4 + docs/config/src/layout-cluster.ru.md | 4 + .../{params => config/src}/layout-cluster.yml | 0 docs/config/src/layout-osd.en.md | 4 + docs/config/src/layout-osd.ru.md | 5 + docs/{params => config/src}/layout-osd.yml | 19 +- docs/config/src/make.js | 120 +++ docs/config/src/monitor.en.md | 3 + docs/config/src/monitor.ru.md | 3 + docs/{params => config/src}/monitor.yml | 0 docs/config/src/network.en.md | 4 + docs/config/src/network.ru.md | 4 + docs/{params => config/src}/network.yml | 12 +- docs/config/src/osd.en.md | 4 + docs/config/src/osd.ru.md | 5 + docs/{params => config/src}/osd.yml | 4 + docs/installation/kubernetes.en.md | 20 + docs/installation/kubernetes.ru.md | 20 + docs/installation/openstack.en.md | 40 + docs/installation/openstack.ru.md | 40 + docs/installation/packages.en.md | 44 ++ docs/installation/packages.ru.md | 43 ++ docs/installation/proxmox.en.md | 39 + docs/installation/proxmox.ru.md | 39 + docs/installation/source.en.md | 65 ++ docs/installation/source.ru.md | 68 ++ docs/intro/architecture.en.md | 91 +++ docs/intro/architecture.ru.md | 208 +++++ docs/intro/author.en.md | 37 + docs/intro/author.ru.md | 37 + docs/intro/features.en.md | 62 ++ docs/intro/features.ru.md | 62 ++ docs/intro/quickstart.en.md | 95 +++ docs/intro/quickstart.ru.md | 103 +++ docs/performance/comparison1.en.md | 108 +++ docs/performance/comparison1.ru.md | 113 +++ docs/performance/theoretical.en.md | 49 ++ docs/performance/theoretical.ru.md | 41 + docs/performance/understanding.en.md | 57 ++ docs/performance/understanding.ru.md | 65 ++ docs/usage/cli.en.md | 206 +++++ docs/usage/cli.ru.md | 197 +++++ docs/usage/fio.en.md | 23 + docs/usage/fio.ru.md | 23 + docs/usage/nbd.en.md | 34 + docs/usage/nbd.ru.md | 39 + docs/usage/nfs.en.md | 45 ++ docs/usage/nfs.ru.md | 44 ++ docs/usage/qemu.en.md | 48 ++ docs/usage/qemu.ru.md | 52 ++ src/cli.cpp | 2 +- 74 files changed, 5012 insertions(+), 1296 deletions(-) create mode 100644 docs/config.en.md create mode 100644 docs/config.ru.md create mode 100644 docs/config/common.en.md create mode 100644 docs/config/common.ru.md create mode 100644 docs/config/inode.en.md create mode 100644 docs/config/inode.ru.md create mode 100644 docs/config/layout-cluster.en.md create mode 100644 docs/config/layout-cluster.ru.md create mode 100644 docs/config/layout-osd.en.md create mode 100644 docs/config/layout-osd.ru.md create mode 100644 docs/config/monitor.en.md create mode 100644 docs/config/monitor.ru.md create mode 100644 docs/config/network.en.md create mode 100644 docs/config/network.ru.md create mode 100644 docs/config/osd.en.md create mode 100644 docs/config/osd.ru.md create mode 100644 docs/config/pool.en.md create mode 100644 docs/config/pool.ru.md create mode 100644 docs/config/src/common.en.md create mode 100644 docs/config/src/common.ru.md rename docs/{params => config/src}/common.yml (100%) create mode 100644 docs/config/src/layout-cluster.en.md create mode 100644 docs/config/src/layout-cluster.ru.md rename docs/{params => config/src}/layout-cluster.yml (100%) create mode 100644 docs/config/src/layout-osd.en.md create mode 100644 docs/config/src/layout-osd.ru.md rename docs/{params => config/src}/layout-osd.yml (92%) create mode 100755 docs/config/src/make.js create mode 100644 docs/config/src/monitor.en.md create mode 100644 docs/config/src/monitor.ru.md rename docs/{params => config/src}/monitor.yml (100%) create mode 100644 docs/config/src/network.en.md create mode 100644 docs/config/src/network.ru.md rename docs/{params => config/src}/network.yml (95%) create mode 100644 docs/config/src/osd.en.md create mode 100644 docs/config/src/osd.ru.md rename docs/{params => config/src}/osd.yml (99%) create mode 100644 docs/installation/kubernetes.en.md create mode 100644 docs/installation/kubernetes.ru.md create mode 100644 docs/installation/openstack.en.md create mode 100644 docs/installation/openstack.ru.md create mode 100644 docs/installation/packages.en.md create mode 100644 docs/installation/packages.ru.md create mode 100644 docs/installation/proxmox.en.md create mode 100644 docs/installation/proxmox.ru.md create mode 100644 docs/installation/source.en.md create mode 100644 docs/installation/source.ru.md create mode 100644 docs/intro/architecture.en.md create mode 100644 docs/intro/architecture.ru.md create mode 100644 docs/intro/author.en.md create mode 100644 docs/intro/author.ru.md create mode 100644 docs/intro/features.en.md create mode 100644 docs/intro/features.ru.md create mode 100644 docs/intro/quickstart.en.md create mode 100644 docs/intro/quickstart.ru.md create mode 100644 docs/performance/comparison1.en.md create mode 100644 docs/performance/comparison1.ru.md create mode 100644 docs/performance/theoretical.en.md create mode 100644 docs/performance/theoretical.ru.md create mode 100644 docs/performance/understanding.en.md create mode 100644 docs/performance/understanding.ru.md create mode 100644 docs/usage/cli.en.md create mode 100644 docs/usage/cli.ru.md create mode 100644 docs/usage/fio.en.md create mode 100644 docs/usage/fio.ru.md create mode 100644 docs/usage/nbd.en.md create mode 100644 docs/usage/nbd.ru.md create mode 100644 docs/usage/nfs.en.md create mode 100644 docs/usage/nfs.ru.md create mode 100644 docs/usage/qemu.en.md create mode 100644 docs/usage/qemu.ru.md diff --git a/README-ru.md b/README-ru.md index 622091f6..0409a618 100644 --- a/README-ru.md +++ b/README-ru.md @@ -4,674 +4,68 @@ ## Идея -Я всего лишь хочу сделать качественную блочную SDS! +Вернём былую скорость кластерному блочному хранилищу! -Vitastor - распределённая блочная SDS, прямой аналог Ceph RBD и внутренних СХД популярных -облачных провайдеров. Однако, в отличие от них, Vitastor быстрый и при этом простой. -Только пока маленький :-). +Vitastor - распределённая блочная SDS (программная СХД), прямой аналог Ceph RBD и +внутренних СХД популярных облачных провайдеров. Однако, в отличие от них, Vitastor +быстрый и при этом простой. Только пока маленький :-). -Архитектурная схожесть с Ceph означает заложенную на уровне алгоритмов записи строгую консистентность, +Vitastor архитектурно похож на Ceph, что означает атомарность и строгую консистентность, репликацию через первичный OSD, симметричную кластеризацию без единой точки отказа и автоматическое распределение данных по любому числу дисков любого размера с настраиваемыми схемами избыточности - репликацией или с произвольными кодами коррекции ошибок. -## Возможности - -Vitastor на данный момент находится в статусе предварительного выпуска, расширенные -возможности пока отсутствуют, а в будущих версиях вероятны "ломающие" изменения. - -Однако следующее уже реализовано: - -- Базовая часть - надёжное кластерное блочное хранилище без единой точки отказа -- Производительность ;-D -- Несколько схем отказоустойчивости: репликация, XOR n+1 (1 диск чётности), коды коррекции ошибок - Рида-Соломона на основе библиотеки jerasure с любым числом дисков данных и чётности в группе -- Конфигурация через простые человекочитаемые JSON-структуры в etcd -- Автоматическое распределение данных по OSD, с поддержкой: - - Математической оптимизации для лучшей равномерности распределения и минимизации перемещений данных - - Нескольких пулов с разными схемами избыточности - - Дерева распределения, выбора OSD по тегам / классам устройств (только SSD, только HDD) и по поддереву - - Настраиваемых доменов отказа (диск/сервер/стойка и т.п.) -- Восстановление деградированных блоков -- Ребаланс, то есть перемещение данных между OSD (дисками) -- Поддержка "ленивого" fsync (fsync не на каждую операцию) -- Сбор статистики ввода/вывода в etcd -- Клиентская библиотека режима пользователя для ввода/вывода -- Драйвер диска для QEMU (собирается вне дерева исходников QEMU) -- Драйвер диска для утилиты тестирования производительности fio (также собирается вне дерева исходников fio) -- NBD-прокси для монтирования образов ядром ("блочное устройство в режиме пользователя") -- Утилита для удаления образов/инодов (vitastor-cli rm-data) -- Пакеты для Debian и CentOS -- Статистика операций ввода/вывода и занятого места в разрезе инодов -- Именование инодов через хранение их метаданных в etcd -- Снапшоты и copy-on-write клоны -- Сглаживание производительности случайной записи в SSD+HDD конфигурациях -- Поддержка RDMA/RoCEv2 через libibverbs -- CSI-плагин для Kubernetes -- Базовая поддержка OpenStack: драйвер Cinder, патчи для Nova и libvirt -- Слияние снапшотов (vitastor-cli {snap-rm,flatten,merge}) -- Консольный интерфейс для управления образами (vitastor-cli {ls,create,modify}) -- Плагин для Proxmox -- Упрощённая NFS-прокси для эмуляции файлового доступа к образам (подходит для VMWare) - -## Планы развития - -- Более корректные скрипты разметки дисков и автоматического запуска OSD -- Другие инструменты администрирования -- Плагины для OpenNebula и других облачных систем -- iSCSI-прокси -- Более быстрое переключение при отказах -- Фоновая проверка целостности без контрольных сумм (сверка реплик) -- Контрольные суммы -- Поддержка SSD-кэширования (tiered storage) -- Поддержка NVDIMM -- Web-интерфейс -- Возможно, сжатие -- Возможно, поддержка кэширования данных через системный page cache - -## Архитектура - -Так же, как и в Ceph, в Vitastor: - -- Есть пулы (pools), PG, OSD, мониторы, домены отказа, дерево распределения (аналог crush-дерева). -- Образы делятся на блоки фиксированного размера (объекты), и эти объекты распределяются по OSD. -- У OSD есть журнал и метаданные и они тоже могут размещаться на отдельных быстрых дисках. -- Все операции записи тоже транзакционны. В Vitastor, правда, есть режим отложенного/ленивого fsync - (коммита), в котором fsync не вызывается на каждую операцию записи, что делает его более - пригодным для использования на "плохих" (десктопных) SSD. Однако все операции записи - в любом случае атомарны. -- Клиентская библиотека тоже старается ждать восстановления после любого отказа кластера, то есть, - вы тоже можете перезагрузить хоть весь кластер разом, и клиенты только на время зависнут, - но не отключатся. - -Некоторые базовые термины для тех, кто не знаком с Ceph: - -- OSD (Object Storage Daemon) - процесс, который хранит данные на одном диске и обрабатывает - запросы чтения/записи от клиентов. -- Пул (Pool) - контейнер для данных, имеющих одну и ту же схему избыточности и правила распределения по OSD. -- PG (Placement Group) - группа объектов, хранимых на одном и том же наборе реплик (OSD). - Несколько PG могут храниться на одном и том же наборе реплик, но объекты одной PG - в норме не хранятся на разных наборах OSD. -- Монитор - демон, хранящий состояние кластера. -- Домен отказа (Failure Domain) - группа OSD, которым вы разрешаете "упасть" всем вместе. - Иными словами, это группа OSD, в которые СХД не помещает разные копии одного и того же - блока данных. Например, если домен отказа - сервер, то на двух дисках одного сервера - никогда не окажется 2 и более копий одного и того же блока данных, а значит, даже - если в этом сервере откажут все диски, это будет равносильно потере только 1 копии - любого блока данных. -- Дерево распределения (Placement Tree / CRUSH Tree) - иерархическая группировка OSD - в узлы, которые далее можно использовать как домены отказа. То есть, диск (OSD) входит в - сервер, сервер входит в стойку, стойка входит в ряд, ряд в датацентр и т.п. - -Чем Vitastor отличается от Ceph: - -- Vitastor в первую очередь сфокусирован на SSD. Также Vitastor, вероятно, должен неплохо работать - с комбинацией SSD и HDD через bcache, а в будущем, возможно, будут добавлены и нативные способы - оптимизации под SSD+HDD. Однако хранилище на основе одних лишь жёстких дисков, вообще без SSD, - не в приоритете, поэтому оптимизации под этот кейс могут вообще не состояться. -- OSD Vitastor однопоточный и всегда таким останется, так как это самый оптимальный способ работы. - Если вам не хватает 1 ядра на 1 диск, просто делите диск на разделы и запускайте на нём несколько OSD. - Но, скорее всего, вам хватит и 1 ядра - Vitastor не так прожорлив к ресурсам CPU, как Ceph. -- Журнал и метаданные всегда размещаются в памяти, благодаря чему никогда не тратится лишнее время - на чтение метаданных с диска. Размер метаданных линейно зависит от размера диска и блока данных, - который задаётся в конфигурации кластера и по умолчанию составляет 128 КБ. С блоком 128 КБ метаданные - занимают примерно 512 МБ памяти на 1 ТБ дискового пространства (и это всё равно меньше, чем нужно Ceph-у). - Журнал вообще не должен быть большим, например, тесты производительности в данном документе проводились - с журналом размером всего 16 МБ. Большой журнал, вероятно, даже вреден, т.к. "грязные" записи (записи, - не сброшенные из журнала) тоже занимают память и могут немного замедлять работу. -- В Vitastor нет внутреннего copy-on-write. Я считаю, что реализация CoW-хранилища гораздо сложнее, - поэтому сложнее добиться устойчиво хороших результатов. Возможно, в один прекрасный день - я придумаю красивый алгоритм для CoW-хранилища, но пока нет - внутреннего CoW в Vitastor не будет. - Всё это не относится к "внешнему" CoW (снапшотам и клонам). -- Базовый слой Vitastor - простое блочное хранилище с блоками фиксированного размера, а не сложное - объектное хранилище с расширенными возможностями, как в Ceph (RADOS). -- В Vitastor есть режим "ленивых fsync", в котором OSD группирует запросы записи перед сбросом их - на диск, что позволяет получить лучшую производительность с дешёвыми настольными SSD без конденсаторов - ("Advanced Power Loss Protection" / "Capacitor-Based Power Loss Protection"). - Тем не менее, такой режим всё равно медленнее использования нормальных серверных SSD и мгновенного - fsync, так как приводит к дополнительным операциям передачи данных по сети, поэтому рекомендуется - всё-таки использовать хорошие серверные диски, тем более, стоят они почти так же, как десктопные. -- PG эфемерны. Это означает, что они не хранятся на дисках и существуют только в памяти работающих OSD. -- Процессы восстановления оперируют отдельными объектами, а не целыми PG. -- PGLOG-ов нет. -- "Мониторы" не хранят данные. Конфигурация и состояние кластера хранятся в etcd в простых человекочитаемых - JSON-структурах. Мониторы Vitastor только следят за состоянием кластера и управляют перемещением данных. - В этом смысле монитор Vitastor не является критичным компонентом системы и больше похож на Ceph-овский - менеджер (MGR). Монитор Vitastor написан на node.js. -- Распределение PG не основано на консистентных хешах. Вместо этого все маппинги PG хранятся прямо в etcd - (ибо нет никакой проблемы сохранить несколько сотен-тысяч записей в памяти, а не считать каждый раз хеши). - Перераспределение PG по OSD выполняется через математическую оптимизацию, - а конкретно, сведение задачи к ЛП (задаче линейного программирования) и решение оной с помощью утилиты - lp_solve. Такой подход позволяет обычно выравнивать распределение места почти идеально - равномерность - обычно составляет 96-99%, в отличие от Ceph, где на голом CRUSH-е без балансировщика обычно выходит 80-90%. - Также это позволяет минимизировать объём перемещения данных и случайность связей между OSD, а также менять - распределение вручную, не боясь сломать логику перебалансировки. В таком подходе есть и потенциальный - недостаток - есть предположение, что в очень большом кластере он может сломаться - однако вплоть до - нескольких сотен OSD подход точно работает нормально. Ну и, собственно, при необходимости легко - реализовать и консистентные хеши. -- Отдельный слой, подобный слою "CRUSH-правил", отсутствует. Вы настраиваете схемы отказоустойчивости, - домены отказа и правила выбора OSD напрямую в конфигурации пулов. - -## Понимание сути производительности систем хранения - -Вкратце: для быстрой хранилки задержки важнее, чем пиковые iops-ы. - -Лучшая возможная задержка достигается при тестировании в 1 поток с глубиной очереди 1, -что приблизительно означает минимально нагруженное состояние кластера. В данном случае -IOPS = 1/задержка. Ни числом серверов, ни дисков, ни серверных процессов/потоков -задержка не масштабируется... Она зависит только от того, насколько быстро один -серверный процесс (и клиент) обрабатывают одну операцию. - -Почему задержки важны? Потому, что некоторые приложения *не могут* использовать глубину -очереди больше 1, ибо их задача не параллелизуется. Важный пример - это все СУБД -с поддержкой консистентности (ACID), потому что все они обеспечивают её через -журналирование, а журналы пишутся последовательно и с fsync() после каждой операции. - -fsync, кстати - это ещё одна очень важная вещь, про которую почти всегда забывают в тестах. -Смысл в том, что все современные диски имеют кэши/буферы записи и не гарантируют, что -данные реально физически записываются на носитель до того, как вы делаете fsync(), -который транслируется в команду сброса кэша операционной системой. - -Дешёвые SSD для настольных ПК и ноутбуков очень быстрые без fsync - NVMe диски, например, -могут обработать порядка 80000 операций записи в секунду с глубиной очереди 1 без fsync. -Однако с fsync, когда они реально вынуждены писать каждый блок данных во флеш-память, -они выжимают лишь 1000-2000 операций записи в секунду (число практически постоянное -для всех моделей SSD). - -Серверные SSD часто имеют суперконденсаторы, работающие как встроенный источник -бесперебойного питания и дающие дискам успеть сбросить их DRAM-кэш в постоянную -флеш-память при отключении питания. Благодаря этому диски с чистой совестью -*игнорируют fsync*, так как точно знают, что данные из кэша доедут до постоянной -памяти. - -Все наиболее известные программные СХД, например, Ceph и внутренние СХД, используемые -такими облачными провайдерами, как Amazon, Google, Яндекс, медленные в смысле задержки. -В лучшем случае они дают задержки от 0.3мс на чтение и 0.6мс на запись 4 КБ блоками -даже при условии использования наилучшего возможного железа. - -И это в эпоху SSD, когда вы можете пойти на рынок и купить там SSD, задержка которого -на чтение будет 0.1мс, а на запись - 0.04мс, за 100$ или даже дешевле. - -Когда мне нужно быстро протестировать производительность дисковой подсистемы, я -использую следующие 6 команд, с небольшими вариациями: - -- Линейная запись: - `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4M -iodepth=32 -rw=write -runtime=60 -filename=/dev/sdX` -- Линейное чтение: - `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4M -iodepth=32 -rw=read -runtime=60 -filename=/dev/sdX` -- Запись в 1 поток (T1Q1): - `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=1 -fsync=1 -rw=randwrite -runtime=60 -filename=/dev/sdX` -- Чтение в 1 поток (T1Q1): - `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=1 -rw=randread -runtime=60 -filename=/dev/sdX` -- Параллельная запись (numjobs используется, когда 1 ядро CPU не может насытить диск): - `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=128 [-numjobs=4 -group_reporting] -rw=randwrite -runtime=60 -filename=/dev/sdX` -- Параллельное чтение (numjobs - аналогично): - `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=128 [-numjobs=4 -group_reporting] -rw=randread -runtime=60 -filename=/dev/sdX` - -## Теоретическая максимальная производительность Vitastor - -При использовании репликации: -- Задержка чтения в 1 поток (T1Q1): 1 сетевой RTT + 1 чтение с диска. -- Запись+fsync в 1 поток: - - С мгновенным сбросом: 2 RTT + 1 запись. - - С отложенным ("ленивым") сбросом: 4 RTT + 1 запись + 1 fsync. -- Параллельное чтение: сумма IOPS всех дисков либо производительность сети, если в сеть упрётся раньше. -- Параллельная запись: сумма IOPS всех дисков / число реплик / WA либо производительность сети, если в сеть упрётся раньше. - -При использовании кодов коррекции ошибок (EC): -- Задержка чтения в 1 поток (T1Q1): 1.5 RTT + 1 чтение. -- Запись+fsync в 1 поток: - - С мгновенным сбросом: 3.5 RTT + 1 чтение + 2 записи. - - С отложенным ("ленивым") сбросом: 5.5 RTT + 1 чтение + 2 записи + 2 fsync. -- Под 0.5 на самом деле подразумевается (k-1)/k, где k - число дисков данных, - что означает, что дополнительное обращение по сети не нужно, когда операция - чтения обслуживается локально. -- Параллельное чтение: сумма IOPS всех дисков либо производительность сети, если в сеть упрётся раньше. -- Параллельная запись: сумма IOPS всех дисков / общее число дисков данных и чётности / WA либо производительность сети, если в сеть упрётся раньше. - Примечание: IOPS дисков в данном случае надо брать в смешанном режиме чтения/записи в пропорции, аналогичной формулам выше. - -WA (мультипликатор записи) для 4 КБ блоков в Vitastor обычно составляет 3-5: -1. Запись метаданных в журнал -2. Запись блока данных в журнал -3. Запись метаданных в БД -4. Ещё одна запись метаданных в журнал при использовании EC -5. Запись блока данных на диск данных - -Если вы найдёте SSD, хорошо работающий с 512-байтными блоками данных (Optane?), -то 1, 3 и 4 можно снизить до 512 байт (1/8 от размера данных) и получить WA всего 2.375. - -Кроме того, WA снижается при использовании отложенного/ленивого сброса при параллельной -нагрузке, т.к. блоки журнала записываются на диск только когда они заполняются или явным -образом запрашивается fsync. - -## Пример сравнения с Ceph - -Железо - 4 сервера, в каждом: -- 6x SATA SSD Intel D3-4510 3.84 TB -- 2x Xeon Gold 6242 (16 cores @ 2.8 GHz) -- 384 GB RAM -- 1x 25 GbE сетевая карта (Mellanox ConnectX-4 LX), подключённая к свитчу Juniper QFX5200 - -Экономия энергии CPU отключена. В тестах и Vitastor, и Ceph развёрнуто по 2 OSD на 1 SSD. - -Все результаты ниже относятся к случайной нагрузке 4 КБ блоками (если явно не указано обратное). - -Производительность голых дисков: -- T1Q1 запись ~27000 iops (задержка ~0.037ms) -- T1Q1 чтение ~9800 iops (задержка ~0.101ms) -- T1Q32 запись ~60000 iops -- T1Q32 чтение ~81700 iops - -Ceph 15.2.4 (Bluestore): -- T1Q1 запись ~1000 iops (задержка ~1ms) -- T1Q1 чтение ~1750 iops (задержка ~0.57ms) -- T8Q64 запись ~100000 iops, потребление CPU процессами OSD около 40 ядер на каждом сервере -- T8Q64 чтение ~480000 iops, потребление CPU процессами OSD около 40 ядер на каждом сервере - -Тесты в 8 потоков проводились на 8 400GB RBD образах со всех хостов (с каждого хоста запускалось 2 процесса fio). -Это нужно потому, что в Ceph несколько RBD-клиентов, пишущих в 1 образ, очень сильно замедляются. - -Настройки RocksDB и Bluestore в Ceph не менялись, единственным изменением было отключение cephx_sign_messages. - -На самом деле, результаты теста не такие уж и плохие для Ceph (могло быть хуже). -Собственно говоря, эти серверы как раз хорошо сбалансированы для Ceph - 6 SATA SSD как раз -утилизируют 25-гигабитную сеть, а без 2 мощных процессоров Ceph-у бы не хватило ядер, -чтобы выдать пристойный результат. Собственно, что и показывает жор 40 ядер в процессе -параллельного теста. - -Vitastor: -- T1Q1 запись: 7087 iops (задержка 0.14ms) -- T1Q1 чтение: 6838 iops (задержка 0.145ms) -- T2Q64 запись: 162000 iops, потребление CPU - 3 ядра на каждом сервере -- T8Q64 чтение: 895000 iops, потребление CPU - 4 ядра на каждом сервере -- Линейная запись (4M T1Q32): 2800 МБ/с -- Линейное чтение (4M T1Q32): 1500 МБ/с - -Тест на чтение в 8 потоков проводился на 1 большом образе (3.2 ТБ) со всех хостов (опять же, по 2 fio с каждого). -В Vitastor никакой разницы между 1 образом и 8-ю нет. Естественно, примерно 1/4 запросов чтения -в такой конфигурации, как и в тестах Ceph выше, обслуживалась с локальной машины. Если проводить -тест так, чтобы все операции всегда обращались к первичным OSD по сети - тест сильнее упирался -в сеть и результат составлял примерно 689000 iops. - -Настройки Vitastor: `--disable_data_fsync true --immediate_commit all --flusher_count 8 - --disk_alignment 4096 --journal_block_size 4096 --meta_block_size 4096 - --journal_no_same_sector_overwrites true --journal_sector_buffer_count 1024 - --journal_size 16777216`. - -### EC/XOR 2+1 - -Vitastor: -- T1Q1 запись: 2808 iops (задержка ~0.355ms) -- T1Q1 чтение: 6190 iops (задержка ~0.16ms) -- T2Q64 запись: 85500 iops, потребление CPU - 3.4 ядра на каждом сервере -- T8Q64 чтение: 812000 iops, потребление CPU - 4.7 ядра на каждом сервере -- Линейная запись (4M T1Q32): 3200 МБ/с -- Линейное чтение (4M T1Q32): 1800 МБ/с - -Ceph: -- T1Q1 запись: 730 iops (задержка ~1.37ms latency) -- T1Q1 чтение: 1500 iops с холодным кэшем метаданных (задержка ~0.66ms), 2300 iops через 2 минуты прогрева (задержка ~0.435ms) -- T4Q128 запись (4 RBD images): 45300 iops, потребление CPU - 30 ядер на каждом сервере -- T8Q64 чтение (4 RBD images): 278600 iops, потребление CPU - 40 ядер на каждом сервере -- Линейная запись (4M T1Q32): 1950 МБ/с в пустой образ, 2500 МБ/с в заполненный образ -- Линейное чтение (4M T1Q32): 2400 МБ/с - -### NBD - -NBD расшифровывается как "сетевое блочное устройство", но на самом деле оно также -работает просто как аналог FUSE для блочных устройств, то есть, представляет собой -"блочное устройство в пространстве пользователя". - -NBD - на данный момент единственный способ монтировать Vitastor ядром Linux. -NBD немного снижает производительность, так как приводит к дополнительным копированиям -данных между ядром и пространством пользователя. Тем не менее, способ достаточно оптимален, -а производительность случайного доступа вообще затрагивается слабо. - -Vitastor с однопоточной NBD прокси на том же стенде: -- T1Q1 запись: 6000 iops (задержка 0.166ms) -- T1Q1 чтение: 5518 iops (задержка 0.18ms) -- T1Q128 запись: 94400 iops -- T1Q128 чтение: 103000 iops -- Линейная запись (4M T1Q128): 1266 МБ/с (в сравнении с 2800 МБ/с через fio) -- Линейное чтение (4M T1Q128): 975 МБ/с (в сравнении с 1500 МБ/с через fio) - -## Установка - -### Debian - -- Добавьте ключ репозитория Vitastor: - `wget -q -O - https://vitastor.io/debian/pubkey | sudo apt-key add -` -- Добавьте репозиторий Vitastor в /etc/apt/sources.list: - - Debian 11 (Bullseye/Sid): `deb https://vitastor.io/debian bullseye main` - - Debian 10 (Buster): `deb https://vitastor.io/debian buster main` -- Для Debian 10 (Buster) также включите репозиторий backports: - `deb http://deb.debian.org/debian buster-backports main` -- Установите пакеты: `apt update; apt install vitastor lp-solve etcd linux-image-amd64 qemu` - -### CentOS - -- Добавьте в систему репозиторий Vitastor: - - CentOS 7: `yum install https://vitastor.io/rpms/centos/7/vitastor-release-1.0-1.el7.noarch.rpm` - - CentOS 8: `dnf install https://vitastor.io/rpms/centos/8/vitastor-release-1.0-1.el8.noarch.rpm` -- Включите EPEL: `yum/dnf install epel-release` -- Включите дополнительные репозитории CentOS: - - CentOS 7: `yum install centos-release-scl` - - CentOS 8: `dnf install centos-release-advanced-virtualization` -- Включите elrepo-kernel: - - CentOS 7: `yum install https://www.elrepo.org/elrepo-release-7.el7.elrepo.noarch.rpm` - - CentOS 8: `dnf install https://www.elrepo.org/elrepo-release-8.el8.elrepo.noarch.rpm` -- Установите пакеты: `yum/dnf install vitastor lpsolve etcd kernel-ml qemu-kvm` - -### Установка из исходников - -- Установите ядро 5.4 или более новое, для поддержки io_uring. Желательно 5.8 или даже новее, - так как в 5.4 есть как минимум 1 известный баг, ведущий к зависанию с io_uring и контроллером HP SmartArray. -- Установите liburing 0.4 или более новый и его заголовки. -- Установите lp_solve. -- Установите etcd, версии не ниже 3.4.15. Более ранние версии работать не будут из-за различных багов, - например [#12402](https://github.com/etcd-io/etcd/pull/12402). Также вы можете взять версию 3.4.13 с - этим конкретным исправлением из ветки release-3.4 репозитория https://github.com/vitalif/etcd/. -- Установите node.js 10 или новее. -- Установите gcc и g++ 8.x или новее. -- Склонируйте данный репозиторий с подмодулями: `git clone https://yourcmc.ru/git/vitalif/vitastor/`. -- Желательно пересобрать QEMU с патчем, который делает необязательным запуск через LD_PRELOAD. - См `patches/qemu-*.*-vitastor.patch` - выберите версию, наиболее близкую вашей версии QEMU. -- Установите QEMU 3.0 или новее, возьмите исходные коды установленного пакета, начните его пересборку, - через некоторое время остановите её и скопируйте следующие заголовки: - - `/include` → `/qemu/include` - - Debian: - * Берите qemu из основного репозитория - * `/b/qemu/config-host.h` → `/qemu/b/qemu/config-host.h` - * `/b/qemu/qapi` → `/qemu/b/qemu/qapi` - - CentOS 8: - * Берите qemu из репозитория Advanced-Virtualization. Чтобы включить его, запустите - `yum install centos-release-advanced-virtualization.noarch` и далее `yum install qemu` - * `/config-host.h` → `/qemu/b/qemu/config-host.h` - * Для QEMU 3.0+: `/qapi` → `/qemu/b/qemu/qapi` - * Для QEMU 2.0+: `/qapi-types.h` → `/qemu/b/qemu/qapi-types.h` - - `config-host.h` и `qapi` нужны, т.к. в них содержатся автогенерируемые заголовки -- Установите fio 3.7 или новее, возьмите исходники пакета и сделайте на них симлинк с `/fio`. -- Соберите и установите Vitastor командой `mkdir build && cd build && cmake .. && make -j8 && make install`. - Обратите внимание на переменную cmake `QEMU_PLUGINDIR` - под RHEL её нужно установить равной `qemu-kvm`. - -## Запуск - -Внимание: процедура пока что достаточно нетривиальная, задавать конфигурацию и смещения -на диске нужно почти вручную. Это будет исправлено в ближайшем будущем. - -- Желательны SATA SSD или NVMe диски с конденсаторами (серверные SSD). Можно использовать и - десктопные SSD, включив режим отложенного fsync, но производительность однопоточной записи - в этом случае пострадает. -- Быстрая сеть, минимум 10 гбит/с -- Для наилучшей производительности нужно отключить энергосбережение CPU: `cpupower idle-set -D 0 && cpupower frequency-set -g performance`. -- На хостах мониторов: - - Пропишите нужные вам значения в файле `/usr/lib/vitastor/mon/make-units.sh` - - Создайте юниты systemd для etcd и мониторов: `/usr/lib/vitastor/mon/make-units.sh` -- Запустите etcd и мониторы: `systemctl start etcd vitastor-mon` -- Пропишите etcd_address и osd_network в `/etc/vitastor/vitastor.conf`. Например: - ``` - { - "etcd_address": ["10.200.1.10:2379","10.200.1.11:2379","10.200.1.12:2379"], - "osd_network": "10.200.1.0/24" - } - ``` -- Инициализуйте OSD: - - SSD: `/usr/lib/vitastor/make-osd.sh /dev/disk/by-partuuid/XXX [/dev/disk/by-partuuid/YYY ...]` - - Гибридные, HDD+SSD: `/usr/lib/vitastor/mon/make-osd-hybrid.js /dev/sda /dev/sdb ...` - передайте - все ваши SSD и HDD скрипту в командной строке подряд, скрипт автоматически выделит разделы под - журналы на SSD и данные на HDD. Скрипт пропускает HDD, на которых уже есть разделы - или вообще какие-то данные, поэтому если диски непустые, сначала очистите их с помощью - `wipefs -a`. SSD с таблицей разделов не пропускаются, но так как скрипт создаёт новые разделы - для журналов, на SSD должно быть доступно свободное нераспределённое место. -- Вы можете менять параметры OSD в юнитах systemd или в `vitastor.conf`. Смысл некоторых параметров: - - `disable_data_fsync 1` - отключает fsync, используется с SSD с конденсаторами. - - `immediate_commit all` - используется с SSD с конденсаторами. - Внимание: если установлено, также нужно установить его в то же значение в etcd в /vitastor/config/global - - `disable_device_lock 1` - отключает блокировку файла устройства, нужно, только если вы запускаете - несколько OSD на одном блочном устройстве. - - `flusher_count 256` - "flusher" - микропоток, удаляющий старые данные из журнала. - Не волнуйтесь об этой настройке, 256 теперь достаточно практически всегда. - - `disk_alignment`, `journal_block_size`, `meta_block_size` следует установить равными размеру - внутреннего блока SSD. Это почти всегда 4096. - - `journal_no_same_sector_overwrites true` запрещает перезапись одного и того же сектора журнала подряд - много раз в процессе записи. Большинство (99%) SSD не нуждаются в данной опции. Однако выяснилось, что - диски, используемые на одном из тестовых стендов - Intel D3-S4510 - очень сильно не любят такую - перезапись, и для них была добавлена эта опция. Когда данный режим включён, также нужно поднимать - значение `journal_sector_buffer_count`, так как иначе Vitastor не хватит буферов для записи в журнал. -- Создайте глобальную конфигурацию в etcd: `etcdctl --endpoints=... put /vitastor/config/global '{"immediate_commit":"all"}'` - (если все ваши диски - серверные с конденсаторами). -- Создайте пулы: `etcdctl --endpoints=... put /vitastor/config/pools '{"1":{"name":"testpool","scheme":"replicated","pg_size":2,"pg_minsize":1,"pg_count":256,"failure_domain":"host"}}'`. - Для jerasure EC-пулов конфигурация должна выглядеть так: `2:{"name":"ecpool","scheme":"jerasure","pg_size":4,"parity_chunks":2,"pg_minsize":2,"pg_count":256,"failure_domain":"host"}`. -- Запустите все OSD: `systemctl start vitastor.target` -- Ваш кластер должен быть готов - один из мониторов должен уже сконфигурировать PG, а OSD должны запустить их. -- Вы можете проверить состояние PG прямо в etcd: `etcdctl --endpoints=... get --prefix /vitastor/pg/state`. Все PG должны быть 'active'. - -### Задать имя образу - -``` -etcdctl --endpoints= put /vitastor/config/inode// '{"name":"","size":[,"parent_id":][,"readonly":true]}' -``` - -Например: - -``` -etcdctl --endpoints=http://10.115.0.10:2379/v3 put /vitastor/config/inode/1/1 '{"name":"testimg","size":2147483648}' -``` - -Если вы зададите parent_id, то образ станет CoW-клоном, т.е. все новые запросы записи пойдут в новый инод, а запросы -чтения будут проверять сначала его, а потом родительские слои по цепочке вверх. Чтобы случайно не перезаписать данные -в родительском слое, вы можете переключить его в режим "только чтение", добавив флаг `"readonly":true` в его запись -метаданных. В таком случае родительский образ становится просто снапшотом. - -Таким образом, для создания снапшота вам нужно просто переименовать предыдущий inode (например, из testimg в testimg@0), -сделать его readonly и создать новый слой с исходным именем образа (testimg), ссылающийся на только что переименованный -в качестве родительского. - -### Запуск тестов с fio - -Пример команды для запуска тестов: - -``` -fio -thread -ioengine=libfio_vitastor.so -name=test -bs=4M -direct=1 -iodepth=16 -rw=write -etcd=10.115.0.10:2379/v3 -image=testimg -``` - -Если вы не хотите обращаться к образу по имени, вместо `-image=testimg` можно указать номер пула, номер инода и размер: -`-pool=1 -inode=1 -size=400G`. - -### Загрузить образ диска ВМ в/из Vitastor - -Используйте qemu-img и строку `vitastor:etcd_host=:image=` в качестве имени файла диска. Например: - -``` -qemu-img convert -f qcow2 debian10.qcow2 -p -O raw 'vitastor:etcd_host=10.115.0.10\:2379/v3:image=testimg' -``` - -Обратите внимание, что если вы используете немодифицированный QEMU, потребуется установить переменную окружения -`LD_PRELOAD=/usr/lib/x86_64-linux-gnu/qemu/block-vitastor.so`. - -Если вы не хотите обращаться к образу по имени, вместо `:image=` можно указать номер пула, номер инода и размер: -`:pool=:inode=:size=`. - -### Запустить ВМ - -Для запуска QEMU используйте опцию `-drive file=vitastor:etcd_host=:image=` (аналогично qemu-img) -и физический размер блока 4 KB. - -Например: - -``` -qemu-system-x86_64 -enable-kvm -m 1024 - -drive 'file=vitastor:etcd_host=10.115.0.10\:2379/v3:image=testimg',format=raw,if=none,id=drive-virtio-disk0,cache=none - -device virtio-blk-pci,scsi=off,bus=pci.0,addr=0x5,drive=drive-virtio-disk0,id=virtio-disk0,bootindex=1,write-cache=off,physical_block_size=4096,logical_block_size=512 - -vnc 0.0.0.0:0 -``` - -Обращение по номерам (`:pool=:inode=:size=` вместо `:image=`) работает аналогично qemu-img. - -### Удалить образ - -Используйте утилиту vitastor-cli rm-data. Например: - -``` -vitastor-cli rm-data --etcd_address 10.115.0.10:2379/v3 --pool 1 --inode 1 --parallel_osds 16 --iodepth 32 -``` - -### NBD - -Чтобы создать локальное блочное устройство, используйте NBD. Например: - -``` -vitastor-nbd map --etcd_address 10.115.0.10:2379/v3 --image testimg -``` - -Команда напечатает название устройства вида /dev/nbd0, которое потом можно будет форматировать -и использовать как обычное блочное устройство. - -Для обращения по номеру инода, аналогично другим командам, можно использовать опции -`--pool --inode --size ` вместо `--image testimg`. - -### NFS - -В Vitastor реализована упрощённая NFS 3.0 прокси для эмуляции файлового доступа к образам. -Это не полноценная файловая система, т.к. метаданные всех файлов (образов) сохраняются -в etcd и всё время хранятся в оперативной памяти - то есть, положить туда много файлов -не получится. - -Однако в качестве способа доступа к образам виртуальных машин NFS прокси прекрасно подходит -и позволяет подключить Vitastor, например, к VMWare. - -При этом, если вы используете режим immediate_commit=all (для SSD с конденсаторами или HDD -с отключённым кэшем), то NFS-сервер не имеет состояния и вы можете свободно поднять -его в нескольких экземплярах и использовать поверх них сетевой балансировщик нагрузки или -схему с отказоустойчивостью. - -Использование vitastor-nfs: - -``` -vitastor-nfs [--etcd_address ADDR] [ДРУГИЕ ОПЦИИ] - ---subdir экспортировать "поддиректорию" - образы с префиксом имени / (по умолчанию пусто - экспортировать все образы) ---portmap 0 отключить сервис portmap/rpcbind на порту 111 (по умолчанию включён и требует root привилегий) ---bind принимать соединения по адресу (по умолчанию 0.0.0.0 - на всех) ---nfspath установить путь NFS-экспорта в (по умолчанию /) ---port использовать порт для NFS-сервисов (по умолчанию 2049) ---pool исползовать пул для новых образов (обязательно, если пул в кластере не один) ---foreground 1 не уходить в фон после запуска -``` - -Пример монтирования Vitastor через NFS: - -``` -vitastor-nfs --etcd_address 192.168.5.10:2379 --portmap 0 --port 2050 --pool testpool -``` - -``` -mount localhost:/ /mnt/ -o port=2050,mountport=2050,nfsvers=3,soft,nolock,tcp -``` - -### Kubernetes - -У Vitastor есть CSI-плагин для Kubernetes, поддерживающий RWO, а также блочные RWX, тома. - -Для установки возьмите манифесты из директории [csi/deploy/](csi/deploy/), поместите -вашу конфигурацию подключения к Vitastor в [csi/deploy/001-csi-config-map.yaml](001-csi-config-map.yaml), -настройте StorageClass в [csi/deploy/009-storage-class.yaml](009-storage-class.yaml) -и примените все `NNN-*.yaml` к вашей инсталляции Kubernetes. - -``` -for i in ./???-*.yaml; do kubectl apply -f $i; done -``` - -После этого вы сможете создавать PersistentVolume. Пример смотрите в файле [csi/deploy/example-pvc.yaml](csi/deploy/example-pvc.yaml). - -### OpenStack - -Чтобы подключить Vitastor к OpenStack: - -- Установите пакеты vitastor-client, libvirt и QEMU из DEB или RPM репозитория Vitastor -- Примените патч `patches/nova-21.diff` или `patches/nova-23.diff` к вашей инсталляции Nova. - nova-21.diff подходит для Nova 21-22, nova-23.diff подходит для Nova 23-24. -- Скопируйте `patches/cinder-vitastor.py` в инсталляцию Cinder как `cinder/volume/drivers/vitastor.py` -- Создайте тип томов в cinder.conf (см. ниже) -- Обязательно заблокируйте доступ от виртуальных машин к сети Vitastor (OSD и etcd), т.к. Vitastor (пока) не поддерживает аутентификацию -- Перезапустите Cinder и Nova - -Пример конфигурации Cinder: - -``` -[DEFAULT] -enabled_backends = lvmdriver-1, vitastor-testcluster -# ... - -[vitastor-testcluster] -volume_driver = cinder.volume.drivers.vitastor.VitastorDriver -volume_backend_name = vitastor-testcluster -image_volume_cache_enabled = True -volume_clear = none -vitastor_etcd_address = 192.168.7.2:2379 -vitastor_etcd_prefix = -vitastor_config_path = /etc/vitastor/vitastor.conf -vitastor_pool_id = 1 -image_upload_use_cinder_backend = True -``` - -Чтобы помещать в Vitastor Glance-образы, нужно использовать -[https://docs.openstack.org/cinder/pike/admin/blockstorage-volume-backed-image.html](образы на основе томов Cinder), -однако, поддержка этой функции ещё не проверялась. - -### Proxmox - -Чтобы подключить Vitastor к Proxmox Virtual Environment (поддерживаются версии 6.4 и 7.1): - -- Добавьте соответствующий Debian-репозиторий Vitastor в sources.list на хостах Proxmox - (buster для 6.4, bullseye для 7.1) -- Установите пакеты vitastor-client, pve-qemu-kvm, pve-storage-vitastor (* или см. сноску) из репозитория Vitastor -- Определите тип хранилища в `/etc/pve/storage.cfg` (см. ниже) -- Обязательно заблокируйте доступ от виртуальных машин к сети Vitastor (OSD и etcd), т.к. Vitastor (пока) не поддерживает аутентификацию -- Перезапустите демон Proxmox: `systemctl restart pvedaemon` - -Пример `/etc/pve/storage.cfg` (единственная обязательная опция - vitastor_pool, все остальные -перечислены внизу для понимания значений по умолчанию): - -``` -vitastor: vitastor - # Пул, в который будут помещаться образы дисков - vitastor_pool testpool - # Путь к файлу конфигурации - vitastor_config_path /etc/vitastor/vitastor.conf - # Адрес(а) etcd, нужны, только если не указаны в vitastor.conf - vitastor_etcd_address 192.168.7.2:2379/v3 - # Префикс ключей метаданных в etcd - vitastor_etcd_prefix /vitastor - # Префикс имён образов - vitastor_prefix pve/ - # Монтировать образы через NBD прокси, через ядро (нужно только для контейнеров) - vitastor_nbd 0 -``` - -\* Примечание: вместо установки пакета pve-storage-vitastor вы можете вручную скопировать файл -[patches/PVE_VitastorPlugin.pm](patches/PVE_VitastorPlugin.pm) на хосты Proxmox как -`/usr/share/perl5/PVE/Storage/Custom/VitastorPlugin.pm`. - -## Известные проблемы - -- Запросы удаления объектов могут в данный момент приводить к "неполным" объектам в EC-пулах, - если в процессе удаления произойдут отказы OSD или серверов, потому что правильная обработка - запросов удаления в кластере должна быть "трёхфазной", а это пока не реализовано. Если вы - столкнётесь с такой ситуацией, просто повторите запрос удаления. - -## Принципы реализации - -- Я люблю архитектурно простые решения. Vitastor проектируется именно так и я намерен - и далее следовать данному принципу. -- Если вы пришли сюда за идеальным кодом на C++, вы, вероятно, не по адресу. "Общепринятые" - практики написания C++ кода меня не очень волнуют, так как зачастую, опять-таки, ведут к - излишним усложнениям и код получается красивый... но медленный. -- По той же причине в коде иногда можно встретить велосипеды типа собственного упрощённого - HTTP-клиента для работы с etcd. Зато эти велосипеды маленькие и компактные и не требуют - использования десятка внешних библиотек. -- node.js для монитора - не случайный выбор. Он очень быстрый, имеет встроенную событийную - машину, приятный нейтральный C-подобный язык программирования и развитую инфраструктуру. +Vitastor нацелен на SSD и SSD+HDD кластеры с как минимум 10 Гбит/с сетью, поддерживает +TCP и RDMA и на хорошем железе может достигать задержки 4 КБ чтения и записи на уровне ~0.1 мс, +что примерно в 10 раз быстрее, чем Ceph и другие популярные программные СХД. + +Vitastor поддерживает QEMU-драйвер, протоколы NBD и NFS, драйверы OpenStack, Proxmox, Kubernetes. +Другие драйверы могут также быть легко реализованы. + +Подробности смотрите в документации по ссылкам ниже. + +## Презентации и записи докладов + +- DevOpsConf'2021: презентация ([на русском](https://vitastor.io/presentation/devopsconf/devopsconf.html), + [на английском](https://vitastor.io/presentation/devopsconf/devopsconf_en.html)), + [видео](https://vitastor.io/presentation/devopsconf/talk.webm) +- Highload'2022: презентация ([на русском](https://vitastor.io/presentation/highload/highload.html)), + [видео](https://vitastor.io/presentation/highload/talk.webm) + +## Документация + +- Введение + - [Быстрый старт](docs/intro/quickstart.ru.md) + - [Возможности](docs/intro/features.ru.md) + - [Архитектура](docs/intro/architecture.ru.md) + - [Автор и лицензия](docs/intro/author.ru.md) +- Установка + - [Пакеты](docs/installation/packages.ru.md) + - [Proxmox](docs/installation/proxmox.ru.md) + - [OpenStack](docs/installation/openstack.ru.md) + - [Kubernetes CSI](docs/installation/kubernetes.ru.md) + - [Сборка из исходных кодов](docs/installation/source.ru.md) +- Конфигурация + - [Обзор](docs/config.ru.md) + - Параметры + - [Общие](docs/config/common.ru.md) + - [Сетевые](docs/config/network.ru.md) + - [Глобальные дисковые параметры](docs/config/layout-cluster.ru.md) + - [Дисковые параметры OSD](docs/config/layout-osd.ru.md) + - [Прочие параметры OSD](docs/config/osd.ru.md) + - [Параметры мониторов](docs/config/monitor.ru.md) + - [Настройки пулов](docs/config/pool.ru.md) + - [Метаданные образов в etcd](docs/config/inode.ru.md) +- Использование + - [vitastor-cli](docs/usage/cli.ru.md) (консольный интерфейс) + - [fio](docs/usage/fio.ru.md) для тестов производительности + - [NBD](docs/usage/nbd.ru.md) для монтирования ядром + - [QEMU и qemu-img](docs/usage/qemu.ru.md) + - [NFS](docs/usage/nfs.ru.md)-прокси для VMWare и подобных +- Производительность + - [Понимание сути производительности](docs/performance/understanding.ru.md) + - [Теоретический максимум](docs/performance/theoretical.ru.md) + - [Пример сравнения с Ceph](docs/performance/comparison1.ru.md) ## Автор и лицензия diff --git a/README.md b/README.md index f5f84228..d4cf6b13 100644 --- a/README.md +++ b/README.md @@ -1,626 +1,71 @@ -## Vitastor +# Vitastor [Читать на русском](README-ru.md) ## The Idea -Make Software-Defined Block Storage Great Again. - -Vitastor is a small, simple and fast clustered block storage (storage for VM drives), -architecturally similar to Ceph which means strong consistency, primary-replication, symmetric -clustering and automatic data distribution over any number of drives of any size -with configurable redundancy (replication or erasure codes/XOR). - -## Features - -Vitastor is currently a pre-release, a lot of features are missing and you can still expect -breaking changes in the future. However, the following is implemented: - -- Basic part: highly-available block storage with symmetric clustering and no SPOF -- Performance ;-D -- Multiple redundancy schemes: Replication, XOR n+1, Reed-Solomon erasure codes - based on jerasure library with any number of data and parity drives in a group -- Configuration via simple JSON data structures in etcd -- Automatic data distribution over OSDs, with support for: - - Mathematical optimization for better uniformity and less data movement - - Multiple pools - - Placement tree, OSD selection by tags (device classes) and placement root - - Configurable failure domains -- Recovery of degraded blocks -- Rebalancing (data movement between OSDs) -- Lazy fsync support -- I/O statistics reporting to etcd -- Generic user-space client library -- QEMU driver (built out-of-tree) -- Loadable fio engine for benchmarks (also built out-of-tree) -- NBD proxy for kernel mounts -- Inode removal tool (vitastor-cli rm-data) -- Packaging for Debian and CentOS -- Per-inode I/O and space usage statistics -- Inode metadata storage in etcd -- Snapshots and copy-on-write image clones -- Write throttling to smooth random write workloads in SSD+HDD configurations -- RDMA/RoCEv2 support via libibverbs -- CSI plugin for Kubernetes -- Basic OpenStack support: Cinder driver, Nova and libvirt patches -- Snapshot merge tool (vitastor-cli {snap-rm,flatten,merge}) -- Image management CLI (vitastor-cli {ls,create,modify}) -- Proxmox storage plugin -- Simplified NFS proxy for file-based image access emulation (suitable for VMWare) - -## Roadmap - -- Better OSD creation and auto-start tools -- Other administrative tools -- Plugins for OpenNebula and other cloud systems -- iSCSI proxy -- Faster failover -- Scrubbing without checksums (verification of replicas) -- Checksums -- Tiered storage -- NVDIMM support -- Web GUI -- Compression (possibly) -- Read caching using system page cache (possibly) - -## Architecture - -Similarities: - -- Just like Ceph, Vitastor has Pools, PGs, OSDs, Monitors, Failure Domains, Placement Tree. -- Just like Ceph, Vitastor is transactional (even though there's a "lazy fsync mode" which - doesn't implicitly flush every operation to disks). -- OSDs also have journal and metadata and they can also be put on separate drives. -- Just like in Ceph, client library attempts to recover from any cluster failure so - you can basically reboot the whole cluster and only pause, but not crash, your clients - (I consider this a bug if the client crashes in that case). - -Some basic terms for people not familiar with Ceph: - -- OSD (Object Storage Daemon) is a process that stores data and serves read/write requests. -- PG (Placement Group) is a container for data that (normally) shares the same replicas. -- Pool is a container for data that has the same redundancy scheme and placement rules. -- Monitor is a separate daemon that watches cluster state and handles failures. -- Failure Domain is a group of OSDs that you allow to fail. It's "host" by default. -- Placement Tree groups OSDs in a hierarchy to later split them into Failure Domains. - -Architectural differences from Ceph: - -- Vitastor's primary focus is on SSDs. Proper SSD+HDD optimizations may be added in the future, though. -- Vitastor OSD is (and will always be) single-threaded. If you want to dedicate more than 1 core - per drive you should run multiple OSDs each on a different partition of the drive. - Vitastor isn't CPU-hungry though (as opposed to Ceph), so 1 core is sufficient in a lot of cases. -- Metadata and journal are always kept in memory. Metadata size depends linearly on drive capacity - and data store block size which is 128 KB by default. With 128 KB blocks metadata should occupy - around 512 MB per 1 TB (which is still less than Ceph wants). Journal doesn't have to be big, - the example test below was conducted with only 16 MB journal. A big journal is probably even - harmful as dirty write metadata also take some memory. -- Vitastor storage layer doesn't have internal copy-on-write or redirect-write. I know that maybe - it's possible to create a good copy-on-write storage, but it's much harder and makes performance - less deterministic, so CoW isn't used in Vitastor. -- The basic layer of Vitastor is block storage with fixed-size blocks, not object storage with - rich semantics like in Ceph (RADOS). -- There's a "lazy fsync" mode which allows to batch writes before flushing them to the disk. - This allows to use Vitastor with desktop SSDs, but still lowers performance due to additional - network roundtrips, so use server SSDs with capacitor-based power loss protection - ("Advanced Power Loss Protection") for best performance. -- PGs are ephemeral. This means that they aren't stored on data disks and only exist in memory - while OSDs are running. -- Recovery process is per-object (per-block), not per-PG. Also there are no PGLOGs. -- Monitors don't store data. Cluster configuration and state is stored in etcd in simple human-readable - JSON structures. Monitors only watch cluster state and handle data movement. - Thus Vitastor's Monitor isn't a critical component of the system and is more similar to Ceph's Manager. - Vitastor's Monitor is implemented in node.js. -- PG distribution isn't based on consistent hashes. All PG mappings are stored in etcd. - Rebalancing PGs between OSDs is done by mathematical optimization - data distribution problem - is reduced to a linear programming problem and solved by lp_solve. This allows for almost - perfect (96-99% uniformity compared to Ceph's 80-90%) data distribution in most cases, ability - to map PGs by hand without breaking rebalancing logic, reduced OSD peer-to-peer communication - (on average, OSDs have fewer peers) and less data movement. It also probably has a drawback - - this method may fail in very large clusters, but up to several hundreds of OSDs it's perfectly fine. - It's also easy to add consistent hashes in the future if something proves their necessity. -- There's no separate CRUSH layer. You select pool redundancy scheme, placement root, failure domain - and so on directly in pool configuration. - -## Understanding Storage Performance - -The most important thing for fast storage is latency, not parallel iops. - -The best possible latency is achieved with one thread and queue depth of 1 which basically means -"client load as low as possible". In this case IOPS = 1/latency, and this number doesn't -scale with number of servers, drives, server processes or threads and so on. -Single-threaded IOPS and latency numbers only depend on *how fast a single daemon is*. - -Why is it important? It's important because some of the applications *can't* use -queue depth greater than 1 because their task isn't parallelizable. A notable example -is any ACID DBMS because all of them write their WALs sequentially with fsync()s. - -fsync, by the way, is another important thing often missing in benchmarks. The point is -that drives have cache buffers and don't guarantee that your data is actually persisted -until you call fsync() which is translated to a FLUSH CACHE command by the OS. - -Desktop SSDs are very fast without fsync - NVMes, for example, can process ~80000 write -operations per second with queue depth of 1 without fsync - but they're really slow with -fsync because they have to actually write data to flash chips when you call fsync. Typical -number is around 1000-2000 iops with fsync. - -Server SSDs often have supercapacitors that act as a built-in UPS and allow the drive -to flush its DRAM cache to the persistent flash storage when a power loss occurs. -This makes them perform equally well with and without fsync. This feature is called -"Advanced Power Loss Protection" by Intel; other vendors either call it similarly -or directly as "Full Capacitor-Based Power Loss Protection". - -All software-defined storages that I currently know are slow in terms of latency. -Notable examples are Ceph and internal SDSes used by cloud providers like Amazon, Google, -Yandex and so on. They're all slow and can only reach ~0.3ms read and ~0.6ms 4 KB write latency -with best-in-slot hardware. - -And that's in the SSD era when you can buy an SSD that has ~0.04ms latency for 100 $. - -I use the following 6 commands with small variations to benchmark any storage: - -- Linear write: - `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4M -iodepth=32 -rw=write -runtime=60 -filename=/dev/sdX` -- Linear read: - `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4M -iodepth=32 -rw=read -runtime=60 -filename=/dev/sdX` -- Random write latency (T1Q1, this hurts storages the most): - `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=1 -fsync=1 -rw=randwrite -runtime=60 -filename=/dev/sdX` -- Random read latency (T1Q1): - `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=1 -rw=randread -runtime=60 -filename=/dev/sdX` -- Parallel write iops (use numjobs if a single CPU core is insufficient to saturate the load): - `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=128 [-numjobs=4 -group_reporting] -rw=randwrite -runtime=60 -filename=/dev/sdX` -- Parallel read iops (use numjobs if a single CPU core is insufficient to saturate the load): - `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=128 [-numjobs=4 -group_reporting] -rw=randread -runtime=60 -filename=/dev/sdX` - -## Vitastor's Theoretical Maximum Random Access Performance - -Replicated setups: -- Single-threaded (T1Q1) read latency: 1 network roundtrip + 1 disk read. -- Single-threaded write+fsync latency: - - With immediate commit: 2 network roundtrips + 1 disk write. - - With lazy commit: 4 network roundtrips + 1 disk write + 1 disk flush. -- Saturated parallel read iops: min(network bandwidth, sum(disk read iops)). -- Saturated parallel write iops: min(network bandwidth, sum(disk write iops / number of replicas / write amplification)). - -EC/XOR setups: -- Single-threaded (T1Q1) read latency: 1.5 network roundtrips + 1 disk read. -- Single-threaded write+fsync latency: - - With immediate commit: 3.5 network roundtrips + 1 disk read + 2 disk writes. - - With lazy commit: 5.5 network roundtrips + 1 disk read + 2 disk writes + 2 disk fsyncs. - - 0.5 in actually (k-1)/k which means that an additional roundtrip doesn't happen when - the read sub-operation can be served locally. -- Saturated parallel read iops: min(network bandwidth, sum(disk read iops)). -- Saturated parallel write iops: min(network bandwidth, sum(disk write iops * number of data drives / (number of data + parity drives) / write amplification)). - In fact, you should put disk write iops under the condition of ~10% reads / ~90% writes in this formula. - -Write amplification for 4 KB blocks is usually 3-5 in Vitastor: -1. Journal block write -2. Journal data write -3. Metadata block write -4. Another journal block write for EC/XOR setups -5. Data block write - -If you manage to get an SSD which handles 512 byte blocks well (Optane?) you may -lower 1, 3 and 4 to 512 bytes (1/8 of data size) and get WA as low as 2.375. - -Lazy fsync also reduces WA for parallel workloads because journal blocks are only -written when they fill up or fsync is requested. - -## Example Comparison with Ceph - -Hardware configuration: 4 nodes, each with: -- 6x SATA SSD Intel D3-4510 3.84 TB -- 2x Xeon Gold 6242 (16 cores @ 2.8 GHz) -- 384 GB RAM -- 1x 25 GbE network interface (Mellanox ConnectX-4 LX), connected to a Juniper QFX5200 switch - -CPU powersaving was disabled. Both Vitastor and Ceph were configured with 2 OSDs per 1 SSD. - -All of the results below apply to 4 KB blocks and random access (unless indicated otherwise). - -Raw drive performance: -- T1Q1 write ~27000 iops (~0.037ms latency) -- T1Q1 read ~9800 iops (~0.101ms latency) -- T1Q32 write ~60000 iops -- T1Q32 read ~81700 iops - -Ceph 15.2.4 (Bluestore): -- T1Q1 write ~1000 iops (~1ms latency) -- T1Q1 read ~1750 iops (~0.57ms latency) -- T8Q64 write ~100000 iops, total CPU usage by OSDs about 40 virtual cores on each node -- T8Q64 read ~480000 iops, total CPU usage by OSDs about 40 virtual cores on each node - -T8Q64 tests were conducted over 8 400GB RBD images from all hosts (every host was running 2 instances of fio). -This is because Ceph has performance penalties related to running multiple clients over a single RBD image. - -cephx_sign_messages was set to false during tests, RocksDB and Bluestore settings were left at defaults. - -In fact, not that bad for Ceph. These servers are an example of well-balanced Ceph nodes. -However, CPU usage and I/O latency were through the roof, as usual. - -Vitastor: -- T1Q1 write: 7087 iops (0.14ms latency) -- T1Q1 read: 6838 iops (0.145ms latency) -- T2Q64 write: 162000 iops, total CPU usage by OSDs about 3 virtual cores on each node -- T8Q64 read: 895000 iops, total CPU usage by OSDs about 4 virtual cores on each node -- Linear write (4M T1Q32): 2800 MB/s -- Linear read (4M T1Q32): 1500 MB/s - -T8Q64 read test was conducted over 1 larger inode (3.2T) from all hosts (every host was running 2 instances of fio). -Vitastor has no performance penalties related to running multiple clients over a single inode. -If conducted from one node with all primary OSDs moved to other nodes the result was slightly lower (689000 iops), -this is because all operations resulted in network roundtrips between the client and the primary OSD. -When fio was colocated with OSDs (like in Ceph benchmarks above), 1/4 of the read workload actually -used the loopback network. - -Vitastor was configured with: `--disable_data_fsync true --immediate_commit all --flusher_count 8 - --disk_alignment 4096 --journal_block_size 4096 --meta_block_size 4096 - --journal_no_same_sector_overwrites true --journal_sector_buffer_count 1024 - --journal_size 16777216`. - -### EC/XOR 2+1 - -Vitastor: -- T1Q1 write: 2808 iops (~0.355ms latency) -- T1Q1 read: 6190 iops (~0.16ms latency) -- T2Q64 write: 85500 iops, total CPU usage by OSDs about 3.4 virtual cores on each node -- T8Q64 read: 812000 iops, total CPU usage by OSDs about 4.7 virtual cores on each node -- Linear write (4M T1Q32): 3200 MB/s -- Linear read (4M T1Q32): 1800 MB/s - -Ceph: -- T1Q1 write: 730 iops (~1.37ms latency) -- T1Q1 read: 1500 iops with cold cache (~0.66ms latency), 2300 iops after 2 minute metadata cache warmup (~0.435ms latency) -- T4Q128 write (4 RBD images): 45300 iops, total CPU usage by OSDs about 30 virtual cores on each node -- T8Q64 read (4 RBD images): 278600 iops, total CPU usage by OSDs about 40 virtual cores on each node -- Linear write (4M T1Q32): 1950 MB/s before preallocation, 2500 MB/s after preallocation -- Linear read (4M T1Q32): 2400 MB/s - -### NBD - -NBD is currently required to mount Vitastor via kernel, but it imposes additional overhead -due to additional copying between the kernel and userspace. This mostly hurts linear -bandwidth, not iops. - -Vitastor with single-thread NBD on the same hardware: -- T1Q1 write: 6000 iops (0.166ms latency) -- T1Q1 read: 5518 iops (0.18ms latency) -- T1Q128 write: 94400 iops -- T1Q128 read: 103000 iops -- Linear write (4M T1Q128): 1266 MB/s (compared to 2800 MB/s via fio) -- Linear read (4M T1Q128): 975 MB/s (compared to 1500 MB/s via fio) - -## Installation - -### Debian - -- Trust Vitastor package signing key: - `wget -q -O - https://vitastor.io/debian/pubkey | sudo apt-key add -` -- Add Vitastor package repository to your /etc/apt/sources.list: - - Debian 11 (Bullseye/Sid): `deb https://vitastor.io/debian bullseye main` - - Debian 10 (Buster): `deb https://vitastor.io/debian buster main` -- For Debian 10 (Buster) also enable backports repository: - `deb http://deb.debian.org/debian buster-backports main` -- Install packages: `apt update; apt install vitastor lp-solve etcd linux-image-amd64 qemu` - -### CentOS - -- Add Vitastor package repository: - - CentOS 7: `yum install https://vitastor.io/rpms/centos/7/vitastor-release-1.0-1.el7.noarch.rpm` - - CentOS 8: `dnf install https://vitastor.io/rpms/centos/8/vitastor-release-1.0-1.el8.noarch.rpm` -- Enable EPEL: `yum/dnf install epel-release` -- Enable additional CentOS repositories: - - CentOS 7: `yum install centos-release-scl` - - CentOS 8: `dnf install centos-release-advanced-virtualization` -- Enable elrepo-kernel: - - CentOS 7: `yum install https://www.elrepo.org/elrepo-release-7.el7.elrepo.noarch.rpm` - - CentOS 8: `dnf install https://www.elrepo.org/elrepo-release-8.el8.elrepo.noarch.rpm` -- Install packages: `yum/dnf install vitastor lpsolve etcd kernel-ml qemu-kvm` - -### Building from Source - -- Install Linux kernel 5.4 or newer, for io_uring support. 5.8 or later is highly recommended because - there is at least one known io_uring hang with 5.4 and an HP SmartArray controller. -- Install liburing 0.4 or newer and its headers. -- Install lp_solve. -- Install etcd, at least version 3.4.15. Earlier versions won't work because of various bugs, - for example [#12402](https://github.com/etcd-io/etcd/pull/12402). You can also take 3.4.13 - with this specific fix from here: https://github.com/vitalif/etcd/, branch release-3.4. -- Install node.js 10 or newer. -- Install gcc and g++ 8.x or newer. -- Clone https://yourcmc.ru/git/vitalif/vitastor/ with submodules. -- Install QEMU 3.0+, get its source, begin to build it, stop the build and copy headers: - - `/include` → `/qemu/include` - - Debian: - * Use qemu packages from the main repository - * `/b/qemu/config-host.h` → `/qemu/b/qemu/config-host.h` - * `/b/qemu/qapi` → `/qemu/b/qemu/qapi` - - CentOS 8: - * Use qemu packages from the Advanced-Virtualization repository. To enable it, run - `yum install centos-release-advanced-virtualization.noarch` and then `yum install qemu` - * `/config-host.h` → `/qemu/b/qemu/config-host.h` - * For QEMU 3.0+: `/qapi` → `/qemu/b/qemu/qapi` - * For QEMU 2.0+: `/qapi-types.h` → `/qemu/b/qemu/qapi-types.h` - - `config-host.h` and `qapi` are required because they contain generated headers -- You can also rebuild QEMU with a patch that makes LD_PRELOAD unnecessary to load vitastor driver. - See `patches/qemu-*.*-vitastor.patch`. -- Install fio 3.7 or later, get its source and symlink it into `/fio`. -- Build & install Vitastor with `mkdir build && cd build && cmake .. && make -j8 && make install`. - Pay attention to the `QEMU_PLUGINDIR` cmake option - it must be set to `qemu-kvm` on RHEL. - -## Running - -Please note that startup procedure isn't currently simple - you specify configuration -and calculate disk offsets almost by hand. This will be fixed in near future. - -- Get some SATA or NVMe SSDs with capacitors (server-grade drives). You can use desktop SSDs - with lazy fsync, but prepare for inferior single-thread latency. -- Get a fast network (at least 10 Gbit/s). -- Disable CPU powersaving: `cpupower idle-set -D 0 && cpupower frequency-set -g performance`. -- On the monitor hosts: - - Edit variables at the top of `/usr/lib/vitastor/mon/make-units.sh` to desired values. - - Create systemd units for the monitor and etcd: `/usr/lib/vitastor/mon/make-units.sh` -- Start etcd and monitors: `systemctl start etcd vitastor-mon` -- Put etcd_address and osd_network into `/etc/vitastor/vitastor.conf`. Example: - ``` - { - "etcd_address": ["10.200.1.10:2379","10.200.1.11:2379","10.200.1.12:2379"], - "osd_network": "10.200.1.0/24" - } - ``` -- Initialize OSDs: - - Simplest, SSD-only: `/usr/lib/vitastor/mon/make-osd.sh /dev/disk/by-partuuid/XXX [/dev/disk/by-partuuid/YYY ...]` - - Hybrid, HDD+SSD: `/usr/lib/vitastor/mon/make-osd-hybrid.js /dev/sda /dev/sdb ...` - pass all your - devices (HDD and SSD) to this script - it will partition disks and initialize journals on its own. - This script skips HDDs which are already partitioned so if you want to use non-empty disks for - Vitastor you should first wipe them with `wipefs -a`. SSDs with GPT partition table are not skipped, - but some free unpartitioned space must be available because the script creates new partitions for journals. -- You can change OSD configuration in units or in `vitastor.conf`. Notable configuration variables: - - `disable_data_fsync 1` - only safe with server-grade drives with capacitors. - - `immediate_commit all` - use this if all your drives are server-grade. - If all OSDs have it set to all then you should also put the same value in etcd into /vitastor/config/global - - `disable_device_lock 1` - only required if you run multiple OSDs on one block device. - - `flusher_count 256` - flusher is a micro-thread that removes old data from the journal. - You don't have to worry about this parameter anymore, 256 is enough. - - `disk_alignment`, `journal_block_size`, `meta_block_size` should be set to the internal - block size of your SSDs which is 4096 on most drives. - - `journal_no_same_sector_overwrites true` prevents multiple overwrites of the same journal sector. - Most (99%) SSDs don't need this option. But Intel D3-4510 does because it doesn't like when you - overwrite the same sector twice in a short period of time. The setting forces Vitastor to never - overwrite the same journal sector twice in a row which makes D3-4510 almost happy. Not totally - happy, because overwrites of the same block can still happen in the metadata area... When this - setting is set, it is also required to raise `journal_sector_buffer_count` setting, which is the - number of dirty journal sectors that may be written to at the same time. -- `systemctl start vitastor.target` everywhere. -- Create global configuration in etcd: `etcdctl --endpoints=... put /vitastor/config/global '{"immediate_commit":"all"}'` - (if all your drives have capacitors). -- Create pool configuration in etcd: `etcdctl --endpoints=... put /vitastor/config/pools '{"1":{"name":"testpool","scheme":"replicated","pg_size":2,"pg_minsize":1,"pg_count":256,"failure_domain":"host"}}'`. - For jerasure pools the configuration should look like the following: `2:{"name":"ecpool","scheme":"jerasure","pg_size":4,"parity_chunks":2,"pg_minsize":2,"pg_count":256,"failure_domain":"host"}`. -- At this point, one of the monitors will configure PGs and OSDs will start them. -- You can check PG states with `etcdctl --endpoints=... get --prefix /vitastor/pg/state`. All PGs should become 'active'. - -### Name an image - -``` -etcdctl --endpoints= put /vitastor/config/inode// '{"name":"","size":[,"parent_id":][,"readonly":true]}' -``` - -For example: - -``` -etcdctl --endpoints=http://10.115.0.10:2379/v3 put /vitastor/config/inode/1/1 '{"name":"testimg","size":2147483648}' -``` - -If you specify parent_id the image becomes a CoW clone. I.e. all writes go to the new inode and reads first check it -and then upper layers. You can then make parent readonly by updating its entry with `"readonly":true` for safety and -basically treat it as a snapshot. - -So to create a snapshot you basically rename the previous upper layer (for example from testimg to testimg@0), make it readonly -and create a new top layer with the original name (testimg) and the previous one as a parent. - -### Run fio benchmarks - -fio command example: - -``` -fio -thread -ioengine=libfio_vitastor.so -name=test -bs=4M -direct=1 -iodepth=16 -rw=write -etcd=10.115.0.10:2379/v3 -image=testimg -``` - -If you don't want to access your image by name, you can specify pool number, inode number and size -(`-pool=1 -inode=1 -size=400G`) instead of the image name (`-image=testimg`). - -### Upload VM image - -Use qemu-img and `vitastor:etcd_host=:image=` disk filename. For example: - -``` -qemu-img convert -f qcow2 debian10.qcow2 -p -O raw 'vitastor:etcd_host=10.115.0.10\:2379/v3:image=testimg' -``` - -Note that the command requires to be run with `LD_PRELOAD=/usr/lib/x86_64-linux-gnu/qemu/block-vitastor.so qemu-img ...` -if you use unmodified QEMU. - -You can also specify `:pool=:inode=:size=` instead of `:image=` -if you don't want to use inode metadata. - -### Start a VM - -Run QEMU with `-drive file=vitastor:etcd_host=:image=` and use 4 KB physical block size. - -For example: - -``` -qemu-system-x86_64 -enable-kvm -m 1024 - -drive 'file=vitastor:etcd_host=10.115.0.10\:2379/v3:image=testimg',format=raw,if=none,id=drive-virtio-disk0,cache=none - -device virtio-blk-pci,scsi=off,bus=pci.0,addr=0x5,drive=drive-virtio-disk0,id=virtio-disk0,bootindex=1,write-cache=off,physical_block_size=4096,logical_block_size=512 - -vnc 0.0.0.0:0 -``` - -You can also specify `:pool=:inode=:size=` instead of `:image=`, -just like in qemu-img. - -### Remove inode - -Use vitastor-rm / vitastor-cli rm-data. For example: - -``` -vitastor-cli rm-data --etcd_address 10.115.0.10:2379/v3 --pool 1 --inode 1 --parallel_osds 16 --iodepth 32 -``` - -### NBD - -To create a local block device for a Vitastor image, use NBD. For example: - -``` -vitastor-nbd map --etcd_address 10.115.0.10:2379/v3 --image testimg -``` - -It will output the device name, like /dev/nbd0 which you can then format and mount as a normal block device. - -Again, you can use `--pool --inode --size ` insteaf of `--image ` if you want. - -### NFS - -Vitastor has a simplified NFS 3.0 proxy for file-based image access emulation. It's not -suitable as a full-featured file system, at least because all file/image metadata is stored -in etcd and kept in memory all the time - thus you can't put a lot of files in it. - -However, NFS proxy is totally fine as a method to provide VM image access and allows to -plug Vitastor into, for example, VMWare. It's important to note that for VMWare it's a much -better access method than iSCSI, because with iSCSI we'd have to put all VM images into one -Vitastor image exported as a LUN to VMWare and formatted with VMFS. VMWare doesn't use VMFS -over NFS. - -NFS proxy is stateless if you use immediate_commit=all mode (for SSD with capacitors or -HDDs with disabled cache), so you can run multiple NFS proxies and use a network load -balancer or any failover method you want to in that case. - -vitastor-nfs usage: - -``` -vitastor-nfs [--etcd_address ADDR] [OTHER OPTIONS] - ---subdir export images prefixed / (default empty - export all images) ---portmap 0 do not listen on port 111 (portmap/rpcbind, requires root) ---bind bind service to address (default 0.0.0.0) ---nfspath set NFS export path to (default is /) ---port use port for NFS services (default is 2049) ---pool use as default pool for new files (images) ---foreground 1 stay in foreground, do not daemonize -``` - -Example start and mount commands: - -``` -vitastor-nfs --etcd_address 192.168.5.10:2379 --portmap 0 --port 2050 --pool testpool -``` - -``` -mount localhost:/ /mnt/ -o port=2050,mountport=2050,nfsvers=3,soft,nolock,tcp -``` - -### Kubernetes - -Vitastor has a CSI plugin for Kubernetes which supports RWO (and block RWX) volumes. - -To deploy it, take manifests from [csi/deploy/](csi/deploy/) directory, put your -Vitastor configuration in [csi/deploy/001-csi-config-map.yaml](001-csi-config-map.yaml), -configure storage class in [csi/deploy/009-storage-class.yaml](009-storage-class.yaml) -and apply all `NNN-*.yaml` manifests to your Kubernetes installation: - -``` -for i in ./???-*.yaml; do kubectl apply -f $i; done -``` - -After that you'll be able to create PersistentVolumes. See example in [csi/deploy/example-pvc.yaml](csi/deploy/example-pvc.yaml). - -### OpenStack - -To enable Vitastor support in an OpenStack installation: - -- Install vitastor-client, patched QEMU and libvirt packages from Vitastor DEB or RPM repository -- Use `patches/nova-21.diff` or `patches/nova-23.diff` to patch your Nova installation. - Patch 21 fits Nova 21-22, patch 23 fits Nova 23-24. -- Install `patches/cinder-vitastor.py` as `..../cinder/volume/drivers/vitastor.py` -- Define a volume type in cinder.conf (see below) -- Block network access from VMs to Vitastor network (to OSDs and etcd), because Vitastor doesn't support authentication (yet) -- Restart Cinder and Nova - -Cinder volume type configuration example: - -``` -[DEFAULT] -enabled_backends = lvmdriver-1, vitastor-testcluster -# ... - -[vitastor-testcluster] -volume_driver = cinder.volume.drivers.vitastor.VitastorDriver -volume_backend_name = vitastor-testcluster -image_volume_cache_enabled = True -volume_clear = none -vitastor_etcd_address = 192.168.7.2:2379 -vitastor_etcd_prefix = -vitastor_config_path = /etc/vitastor/vitastor.conf -vitastor_pool_id = 1 -image_upload_use_cinder_backend = True -``` - -To put Glance images in Vitastor, use [https://docs.openstack.org/cinder/pike/admin/blockstorage-volume-backed-image.html](volume-backed images), -although the support has not been verified yet. - -### Proxmox - -To enable Vitastor support in Proxmox Virtual Environment (6.4 and 7.1 are supported): - -- Add the corresponding Vitastor Debian repository into sources.list on Proxmox hosts - (buster for 6.4, bullseye for 7.1) -- Install vitastor-client, pve-qemu-kvm, pve-storage-vitastor (* or see note) packages from Vitastor repository -- Define storage in `/etc/pve/storage.cfg` (see below) -- Block network access from VMs to Vitastor network (to OSDs and etcd), because Vitastor doesn't support authentication (yet) -- Restart pvedaemon: `systemctl restart pvedaemon` - -`/etc/pve/storage.cfg` example (the only required option is vitastor_pool, all others -are listed below with their default values): - -``` -vitastor: vitastor - # pool to put new images into - vitastor_pool testpool - # path to the configuration file - vitastor_config_path /etc/vitastor/vitastor.conf - # etcd address(es), required only if missing in the configuration file - vitastor_etcd_address 192.168.7.2:2379/v3 - # prefix for keys in etcd - vitastor_etcd_prefix /vitastor - # prefix for images - vitastor_prefix pve/ - # use NBD mounter (only required for containers) - vitastor_nbd 0 -``` - -\* Note: you can also manually copy [patches/PVE_VitastorPlugin.pm](patches/PVE_VitastorPlugin.pm) to Proxmox hosts -as `/usr/share/perl5/PVE/Storage/Custom/VitastorPlugin.pm` instead of installing pve-storage-vitastor. - -## Known Problems - -- Object deletion requests may currently lead to 'incomplete' objects in EC pools - if your OSDs crash during deletion because proper handling of object cleanup - in a cluster should be "three-phase" and it's currently not implemented. - Just repeat the removal request again in this case. - -## Implementation Principles - -- I like architecturally simple solutions. Vitastor is and will always be designed - exactly like that. -- I also like reinventing the wheel to some extent, like writing my own HTTP client - for etcd interaction instead of using prebuilt libraries, because in this case - I'm confident about what my code does and what it doesn't do. -- I don't care about C++ "best practices" like RAII or proper inheritance or usage of - smart pointers or whatever and I don't intend to change my mind, so if you're here - looking for ideal reference C++ code, this probably isn't the right place. -- I like node.js better than any other dynamically-typed language interpreter - because it's faster than any other interpreter in the world, has neutral C-like - syntax and built-in event loop. That's why Monitor is implemented in node.js. +Make Clustered Block Storage Fast Again. + +Vitastor is a distributed block SDS, direct replacement of Ceph RBD and internal SDS's +of public clouds. However, in contrast to them, Vitastor is fast and simple at the same time. +The only thing is it's slightly young :-). + +Vitastor is architecturally similar to Ceph which means strong consistency, +primary-replication, symmetric clustering and automatic data distribution over any +number of drives of any size with configurable redundancy (replication or erasure codes/XOR). + +Vitastor targets SSD and SSD+HDD clusters with at least 10 Gbit/s network, supports +TCP and RDMA and may achieve 4 KB read and write latency as low as ~0.1 ms +with proper hardware which is ~10 times faster than other popular SDS's like Ceph +or internal systems of public clouds. + +Vitastor supports QEMU, NBD, NFS protocols, OpenStack, Proxmox, Kubernetes drivers. +More drivers may be created easily. + +Read more details below in the documentation. + +## Talks and presentations + +- DevOpsConf'2021: presentation ([in Russian](https://vitastor.io/presentation/devopsconf/devopsconf.html), + [in English](https://vitastor.io/presentation/devopsconf/devopsconf_en.html)), + [video](https://vitastor.io/presentation/devopsconf/talk.webm) +- Highload'2022: presentation ([in Russian](https://vitastor.io/presentation/highload/highload.html)), + [video](https://vitastor.io/presentation/highload/talk.webm) + +## Documentation + +- Introduction + - [Quick Start](docs/intro/quickstart.en.md) + - [Features](docs/intro/features.en.md) + - [Architecture](docs/intro/architecture.en.md) + - [Author and license](docs/intro/author.en.md) +- Installation + - [Packages](docs/installation/packages.en.md) + - [Proxmox](docs/installation/proxmox.en.md) + - [OpenStack](docs/installation/openstack.en.md) + - [Kubernetes CSI](docs/installation/kubernetes.en.md) + - [Building from Source](docs/installation/source.en.md) +- Configuration + - [Overview](docs/config.en.md) + - Parameter Reference + - [Common](docs/config/common.en.md) + - [Network](docs/config/network.en.md) + - [Global Disk Layout](docs/config/layout-cluster.en.md) + - [OSD Disk Layout](docs/config/layout-osd.en.md) + - [OSD Runtime Parameters](docs/config/osd.en.md) + - [Monitor](docs/config/monitor.en.md) + - [Pool configuration](docs/config/pool.en.md) + - [Image metadata in etcd](docs/config/inode.en.md) +- Usage + - [vitastor-cli](docs/usage/cli.en.md) (command-line interface) + - [fio](docs/usage/fio.en.md) for benchmarks + - [NBD](docs/usage/nbd.en.md) for kernel mounts + - [QEMU and qemu-img](docs/usage/qemu.en.md) + - [NFS](docs/usage/nfs.en.md) emulator for VMWare and similar +- Performance + - [Understanding storage performance](docs/performance/understanding.en.md) + - [Theoretical performance](docs/performance/theoretical.en.md) + - [Example comparison with Ceph](docs/performance/comparison1.en.md) ## Author and License diff --git a/docs/config.en.md b/docs/config.en.md new file mode 100644 index 00000000..3a1e1a52 --- /dev/null +++ b/docs/config.en.md @@ -0,0 +1,38 @@ +[Documentation](../README.md#documentation) → Configuration Reference + +----- + +[Читать на русском](config.ru.md) + +# Configuration Reference + +Vitastor configuration consists of: +- Configuration parameters (key-value), described here +- [Pool configuration](config/pool.en.md) +- OSD placement tree configuration +- [Inode configuration](config/inode.en.md) i.e. image metadata like name, size and parent reference + +Configuration parameters can be set in 3 places: +- Configuration file (`/etc/vitastor/vitastor.conf` or other path) +- etcd key `/vitastor/config/global`. Most variables can be set there, but etcd + connection parameters should obviously be set in the configuration file. +- Command line of Vitastor components: OSD, mon, fio and QEMU options, + OpenStack/Proxmox/etc configuration. The latter doesn't allow to set all + variables directly, but it allows to override the configuration file and + set everything you need inside it. + +In the future, additional configuration methods may be added: +- OSD superblock which will, by design, contain parameters related to the disk + layout and to one specific OSD. +- OSD-specific keys in etcd like `/vitastor/config/osd/`. + +## Parameter Reference + +- [Common](config/common.en.md) +- [Network](config/network.en.md) +- [Global Disk Layout](config/layout-cluster.en.md) +- [OSD Disk Layout](config/layout-osd.en.md) +- [OSD Runtime Parameters](config/osd.en.md) +- [Monitor](config/monitor.en.md) +- [Pool configuration](config/pool.en.md) +- [Inode metadata in etcd](docs/config/inode.en.md) diff --git a/docs/config.ru.md b/docs/config.ru.md new file mode 100644 index 00000000..270023b4 --- /dev/null +++ b/docs/config.ru.md @@ -0,0 +1,39 @@ +[Документация](../README-ru.md#документация) → Конфигурация Vitastor + +----- + +[Read in English](config.en.md) + +# Конфигурация Vitastor + +Конфигурация Vitastor состоит из: +- Параметров (ключ-значение), описанных на данной странице +- [Настроек пулов](config/pool.ru.md) +- Настроек дерева OSD +- [Настроек инодов](config/inode.ru.md), т.е. метаданных образов, таких, как имя, размер и ссылки на + родительский образ + +Параметры конфигурации могут задаваться в 3 местах: +- Файле конфигурации (`/etc/vitastor/vitastor.conf` или по другому пути) +- Ключе в etcd `/vitastor/config/global`. Большая часть параметров может + задаваться там, кроме, естественно, самих параметров соединения с etcd, + которые должны задаваться в файле конфигурации +- В командной строке компонентов Vitastor: OSD, монитора, опциях fio и QEMU, + настроек OpenStack, Proxmox и т.п. Последние, как правило, не включают полный + набор параметров напрямую, но разрешают определить путь к файлу конфигурации + и задать любые параметры в нём. + +В будущем также могут быть добавлены другие способы конфигурации: +- Суперблок OSD, в котором будут храниться параметры OSD, связанные с дисковым + форматом и с этим конкретным OSD. +- OSD-специфичные ключи в etcd типа `/vitastor/config/osd/<номер>`. + +## Список параметров + +- [Общие](config/common.ru.md) +- [Сеть](config/network.ru.md) +- [Глобальные дисковые параметры](config/layout-cluster.ru.md) +- [Дисковые параметры OSD](config/layout-osd.ru.md) +- [Прочие параметры OSD](config/osd.ru.md) +- [Параметры мониторов](config/monitor.ru.md) +- [Настройки пулов](config/pool.ru.md) diff --git a/docs/config/common.en.md b/docs/config/common.en.md new file mode 100644 index 00000000..eaba93b3 --- /dev/null +++ b/docs/config/common.en.md @@ -0,0 +1,46 @@ +[Documentation](../../README.md#documentation) → [Configuration](../config.en.md) → Common Parameters + +----- + +[Читать на русском](common.ru.md) + +# Common Parameters + +These are the most common parameters which apply to all components of Vitastor. + +- [config_path](#config_path) +- [etcd_address](#etcd_address) +- [etcd_prefix](#etcd_prefix) +- [log_level](#log_level) + +## config_path + +- Type: string +- Default: /etc/vitastor/vitastor.conf + +Path to the JSON configuration file. Configuration file is optional, +a non-existing configuration file does not prevent Vitastor from +running if required parameters are specified. + +## etcd_address + +- Type: string or array of strings + +etcd connection endpoint(s). Multiple endpoints may be delimited by "," or +specified in a JSON array `["10.0.115.10:2379/v3","10.0.115.11:2379/v3"]`. +Note that https is not supported for etcd connections yet. + +## etcd_prefix + +- Type: string +- Default: /vitastor + +Prefix for all keys in etcd used by Vitastor. You can change prefix and, for +example, use a single etcd cluster for multiple Vitastor clusters. + +## log_level + +- Type: integer +- Default: 0 + +Log level. Raise if you want more verbose output. diff --git a/docs/config/common.ru.md b/docs/config/common.ru.md new file mode 100644 index 00000000..15aff53e --- /dev/null +++ b/docs/config/common.ru.md @@ -0,0 +1,45 @@ +[Документация](../../README-ru.md#документация) → [Конфигурация](../config.ru.md) → Общие параметры + +----- + +[Read in English](common.en.md) + +# Общие параметры + +Это наиболее общие параметры, используемые всеми компонентами Vitastor. + +- [config_path](#config_path) +- [etcd_address](#etcd_address) +- [etcd_prefix](#etcd_prefix) +- [log_level](#log_level) + +## config_path + +- Тип: строка +- Значение по умолчанию: /etc/vitastor/vitastor.conf + +Путь к файлу конфигурации в формате JSON. Файл конфигурации необязателен, +без него Vitastor тоже будет работать, если переданы необходимые параметры. + +## etcd_address + +- Тип: строка или массив строк + +Адрес(а) подключения к etcd. Несколько адресов могут разделяться запятой +или указываться в виде JSON-массива `["10.0.115.10:2379/v3","10.0.115.11:2379/v3"]`. + +## etcd_prefix + +- Тип: строка +- Значение по умолчанию: /vitastor + +Префикс для ключей etcd, которые использует Vitastor. Вы можете задать другой +префикс, например, чтобы запустить несколько кластеров Vitastor с одним +кластером etcd. + +## log_level + +- Тип: целое число +- Значение по умолчанию: 0 + +Уровень логгирования. Повысьте, если хотите более подробный вывод. diff --git a/docs/config/inode.en.md b/docs/config/inode.en.md new file mode 100644 index 00000000..28720e76 --- /dev/null +++ b/docs/config/inode.en.md @@ -0,0 +1,32 @@ +[Documentation](../../README.md#documentation) → [Configuration](../config.en.md) → Image metadata in etcd + +----- + +[Читать на русском](inode.ru.md) + +# Image metadata in etcd + +Image list is stored in etcd in `/vitastor/config/inode//` keys. + +You can even create images manually: + +``` +etcdctl --endpoints= put /vitastor/config/inode// '{"name":"","size":[,"parent_id":][,"readonly":true]}' +``` + +For example: + +``` +etcdctl --endpoints=http://10.115.0.10:2379/v3 put /vitastor/config/inode/1/1 '{"name":"testimg","size":2147483648}' +``` + +If you specify parent_id the image becomes a CoW clone. I.e. all writes go to the new inode and reads first check it +and then upper layers. You can then make parent readonly by updating its entry with `"readonly":true` for safety and +basically treat it as a snapshot. + +So to create a snapshot you basically rename the previous upper layer (for example from testimg to testimg@0), make it readonly +and create a new top layer with the original name (testimg) and the previous one as a parent. + +vitastor-cli, K8s, OpenStack and other drivers also store the reverse mapping in `/vitastor/index/image/` keys +in JSON format: `{"id":,"pool_id":}` and ID counters in `/vitastor/index/maxid/` as numbers +to simplify ID generation. diff --git a/docs/config/inode.ru.md b/docs/config/inode.ru.md new file mode 100644 index 00000000..49018fc8 --- /dev/null +++ b/docs/config/inode.ru.md @@ -0,0 +1,34 @@ +[Документация](../../README-ru.md#документация) → [Конфигурация](../config.ru.md) → Метаданные образов в etcd + +----- + +[Read in English](inode.en.md) + +# Метаданные образов в etcd + +Список образов хранится в etcd в ключах `/vitastor/config/inode//`. + +Вы можете даже создавать образы вручную: + +``` +etcdctl --endpoints= put /vitastor/config/inode// '{"name":"","size":[,"parent_id":][,"readonly":true]}' +``` + +Например: + +``` +etcdctl --endpoints=http://10.115.0.10:2379/v3 put /vitastor/config/inode/1/1 '{"name":"testimg","size":2147483648}' +``` + +Если вы зададите parent_id, то образ станет CoW-клоном, т.е. все новые запросы записи пойдут в новый инод, а запросы +чтения будут проверять сначала его, а потом родительские слои по цепочке вверх. Чтобы случайно не перезаписать данные +в родительском слое, вы можете переключить его в режим "только чтение", добавив флаг `"readonly":true` в его запись +метаданных. В таком случае родительский образ становится просто снапшотом. + +Таким образом, для создания снапшота вам нужно просто переименовать предыдущий inode (например, из testimg в testimg@0), +сделать его readonly и создать новый слой с исходным именем образа (testimg), ссылающийся на только что переименованный +в качестве родительского. + +vitastor-cli и драйвера K8s, OpenStack и т.п. также хранят обратный маппинг в ключах `/vitastor/index/image/` +в JSON-формате: `{"id":,"pool_id":}` и счётчики ID `/vitastor/index/maxid/` в виде просто чисел +для упрощения генерации ID новых образов. diff --git a/docs/config/layout-cluster.en.md b/docs/config/layout-cluster.en.md new file mode 100644 index 00000000..60354b04 --- /dev/null +++ b/docs/config/layout-cluster.en.md @@ -0,0 +1,124 @@ +[Documentation](../../README.md#documentation) → [Configuration](../config.en.md) → Cluster-Wide Disk Layout Parameters + +----- + +[Читать на русском](layout-cluster.ru.md) + +# Cluster-Wide Disk Layout Parameters + +These parameters apply to clients and OSDs, are fixed at the moment of OSD drive +initialization and can't be changed after it without losing data. + +- [block_size](#block_size) +- [bitmap_granularity](#bitmap_granularity) +- [immediate_commit](#immediate_commit) +- [client_dirty_limit](#client_dirty_limit) + +## block_size + +- Type: integer +- Default: 131072 + +Size of objects (data blocks) into which all physical and virtual drives are +subdivided in Vitastor. One of current main settings in Vitastor, affects +memory usage, write amplification and I/O load distribution effectiveness. + +Recommended default block size is 128 KB for SSD and 4 MB for HDD. In fact, +it's possible to use 4 MB for SSD too - it will lower memory usage, but +may increase average WA and reduce linear performance. + +OSDs with different block sizes (for example, SSD and SSD+HDD OSDs) can +currently coexist in one etcd instance only within separate Vitastor +clusters with different etcd_prefix'es. + +Also block size can't be changed after OSD initialization without losing +data. + +You must always specify block_size in etcd in /vitastor/config/global if +you change it so all clients can know about it. + +OSD memory usage is roughly (SIZE / BLOCK * 68 bytes) which is roughly +544 MB per 1 TB of used disk space with the default 128 KB block size. + +## bitmap_granularity + +- Type: integer +- Default: 4096 + +Required virtual disk write alignment ("sector size"). Must be a multiple +of disk_alignment. It's called bitmap granularity because Vitastor tracks +an allocation bitmap for each object containing 2 bits per each +(bitmap_granularity) bytes. + +This parameter can't be changed after OSD initialization without losing +data. Also it's fixed for the whole Vitastor cluster i.e. two different +values can't be used in a single Vitastor cluster. + +Clients MUST be aware of this parameter value, so put it into etcd key +/vitastor/config/global if you change it for any reason. + +## immediate_commit + +- Type: string +- Default: false + +Another parameter which is really important for performance. + +Desktop SSDs are very fast (100000+ iops) for simple random writes +without cache flush. However, they are really slow (only around 1000 iops) +if you try to fsync() each write, that is, when you want to guarantee that +each change gets immediately persisted to the physical media. + +Server-grade SSDs with "Advanced/Enhanced Power Loss Protection" or with +"Supercapacitor-based Power Loss Protection", on the other hand, are equally +fast with and without fsync because their cache is protected from sudden +power loss by a built-in supercapacitor-based "UPS". + +Some software-defined storage systems always fsync each write and thus are +really slow when used with desktop SSDs. Vitastor, however, can also +efficiently utilize desktop SSDs by postponing fsync until the client calls +it explicitly. + +This is what this parameter regulates. When it's set to "all" the whole +Vitastor cluster commits each change to disks immediately and clients just +ignore fsyncs because they know for sure that they're unneeded. This reduces +the amount of network roundtrips performed by clients and improves +performance. So it's always better to use server grade SSDs with +supercapacitors even with Vitastor, especially given that they cost only +a bit more than desktop models. + +There is also a common SATA SSD (and HDD too!) firmware bug (or feature) +that makes server SSDs which have supercapacitors slow with fsync. To check +if your SSDs are affected, compare benchmark results from `fio -name=test +-ioengine=libaio -direct=1 -bs=4k -rw=randwrite -iodepth=1` with and without +`-fsync=1`. Results should be the same. If fsync=1 result is worse you can +try to work around this bug by "disabling" drive write-back cache by running +`hdparm -W 0 /dev/sdXX` or `echo write through > /sys/block/sdXX/device/scsi_disk/*/cache_type` +(IMPORTANT: don't mistake it with `/sys/block/sdXX/queue/write_cache` - it's +unsafe to change by hand). The same may apply to newer HDDs with internal +SSD cache or "media-cache" - for example, a lot of Seagate EXOS drives have +it (they have internal SSD cache even though it's not stated in datasheets). + +This parameter must be set both in etcd in /vitastor/config/global and in +OSD command line or configuration. Setting it to "all" or "small" requires +enabling disable_journal_fsync and disable_meta_fsync, setting it to "all" +also requires enabling disable_data_fsync. + +TLDR: For optimal performance, set immediate_commit to "all" if you only use +SSDs with supercapacitor-based power loss protection (nonvolatile +write-through cache) for both data and journals in the whole Vitastor +cluster. Set it to "small" if you only use such SSDs for journals. Leave +empty if your drives have write-back cache. + +## client_dirty_limit + +- Type: integer +- Default: 33554432 + +Without immediate_commit=all this parameter sets the limit of "dirty" +(not committed by fsync) data allowed by the client before forcing an +additional fsync and committing the data. Also note that the client always +holds a copy of uncommitted data in memory so this setting also affects +RAM usage of clients. + +This parameter doesn't affect OSDs themselves. diff --git a/docs/config/layout-cluster.ru.md b/docs/config/layout-cluster.ru.md new file mode 100644 index 00000000..20b57141 --- /dev/null +++ b/docs/config/layout-cluster.ru.md @@ -0,0 +1,134 @@ +[Документация](../../README-ru.md#документация) → [Конфигурация](../config.ru.md) → Дисковые параметры уровня кластера + +----- + +[Read in English](layout-cluster.en.md) + +# Дисковые параметры уровня кластера + +Данные параметры используются клиентами и OSD, задаются в момент инициализации +диска OSD и не могут быть изменены после этого без потери данных. + +- [block_size](#block_size) +- [bitmap_granularity](#bitmap_granularity) +- [immediate_commit](#immediate_commit) +- [client_dirty_limit](#client_dirty_limit) + +## block_size + +- Тип: целое число +- Значение по умолчанию: 131072 + +Размер объектов (блоков данных), на которые делятся физические и виртуальные +диски в Vitastor. Одна из ключевых на данный момент настроек, влияет на +потребление памяти, объём избыточной записи (write amplification) и +эффективность распределения нагрузки по OSD. + +Рекомендуемые по умолчанию размеры блока - 128 килобайт для SSD и 4 +мегабайта для HDD. В принципе, для SSD можно тоже использовать 4 мегабайта, +это понизит использование памяти, но ухудшит распределение нагрузки и в +среднем увеличит WA. + +OSD с разными размерами блока (например, SSD и SSD+HDD OSD) на данный +момент могут сосуществовать в рамках одного etcd только в виде двух независимых +кластеров Vitastor с разными etcd_prefix. + +Также размер блока нельзя менять после инициализации OSD без потери данных. + +Если вы меняете размер блока, обязательно прописывайте его в etcd в +/vitastor/config/global, дабы все клиенты его знали. + +Потребление памяти OSD составляет примерно (РАЗМЕР / БЛОК * 68 байт), +т.е. примерно 544 МБ памяти на 1 ТБ занятого места на диске при +стандартном 128 КБ блоке. + +## bitmap_granularity + +- Тип: целое число +- Значение по умолчанию: 4096 + +Требуемое выравнивание записи на виртуальные диски (размер их "сектора"). +Должен быть кратен disk_alignment. Называется гранулярностью битовой карты +потому, что Vitastor хранит битовую карту для каждого объекта, содержащую +по 2 бита на каждые (bitmap_granularity) байт. + +Данный параметр нельзя менять после инициализации OSD без потери данных. +Также он фиксирован для всего кластера Vitastor, т.е. разные значения +не могут сосуществовать в одном кластере. + +Клиенты ДОЛЖНЫ знать правильное значение этого параметра, так что если вы +его меняете, обязательно прописывайте изменённое значение в etcd в ключ +/vitastor/config/global. + +## immediate_commit + +- Тип: строка +- Значение по умолчанию: false + +Ещё один важный для производительности параметр. + +Модели SSD для настольных компьютеров очень быстрые (100000+ операций в +секунду) при простой случайной записи без сбросов кэша. Однако они очень +медленные (всего порядка 1000 iops), если вы пытаетесь сбрасывать кэш после +каждой записи, то есть, если вы пытаетесь гарантировать, что каждое +изменение физически записывается в энергонезависимую память. + +С другой стороны, серверные SSD с конденсаторами - функцией, называемой +"Advanced/Enhanced Power Loss Protection" или просто "Supercapacitor-based +Power Loss Protection" - одинаково быстрые и со сбросом кэша, и без +него, потому что их кэш защищён от потери питания встроенным "источником +бесперебойного питания" на основе суперконденсаторов и на самом деле они +его никогда не сбрасывают. + +Некоторые программные СХД всегда сбрасывают кэши дисков при каждой записи +и поэтому работают очень медленно с настольными SSD. Vitastor, однако, может +откладывать fsync до явного его вызова со стороны клиента и таким образом +эффективно утилизировать настольные SSD. + +Данный параметр влияет как раз на это. Когда он установлен в значение "all", +весь кластер Vitastor мгновенно фиксирует каждое изменение на физические +носители и клиенты могут просто игнорировать запросы fsync, т.к. они точно +знают, что fsync-и не нужны. Это уменьшает число необходимых обращений к OSD +по сети и улучшает производительность. Поэтому даже с Vitastor лучше всегда +использовать только серверные модели SSD с суперконденсаторами, особенно +учитывая то, что стоят они ненамного дороже настольных. + +Также в прошивках SATA SSD (и даже HDD!) очень часто встречается либо баг, +либо просто особенность логики, из-за которой серверные SSD, имеющие +конденсаторы и защиту от потери питания, всё равно медленно работают с +fsync. Чтобы понять, подвержены ли этой проблеме ваши SSD, сравните +результаты тестов `fio -name=test -ioengine=libaio -direct=1 -bs=4k +-rw=randwrite -iodepth=1` без и с опцией `-fsync=1`. Результаты должны +быть одинаковые. Если результат с `fsync=1` хуже, вы можете попробовать +обойти проблему, "отключив" кэш записи диска командой `hdparm -W 0 /dev/sdXX` +либо `echo write through > /sys/block/sdXX/device/scsi_disk/*/cache_type` +(ВАЖНО: не перепутайте с `/sys/block/sdXX/queue/write_cache` - этот параметр +менять руками небезопасно). Такая же проблема может встречаться и в новых +HDD-дисках с внутренним SSD или "медиа" кэшем - например, она встречается во +многих дисках Seagate EXOS (у них есть внутренний SSD-кэш, хотя это и не +указано в спецификациях). + +Данный параметр нужно указывать и в etcd в /vitastor/config/global, и в +командной строке или конфигурации OSD. Значения "all" и "small" требуют +включения disable_journal_fsync и disable_meta_fsync, значение "all" также +требует включения disable_data_fsync. + +Итого, вкратце: для оптимальной производительности установите +immediate_commit в значение "all", если вы используете в кластере только SSD +с суперконденсаторами и для данных, и для журналов. Если вы используете +такие SSD для всех журналов, но не для данных - можете установить параметр +в "small". Если и какие-то из дисков журналов имеют волатильный кэш записи - +оставьте параметр пустым. + +## client_dirty_limit + +- Тип: целое число +- Значение по умолчанию: 33554432 + +При работе без immediate_commit=all - это лимит объёма "грязных" (не +зафиксированных fsync-ом) данных, при достижении которого клиент будет +принудительно вызывать fsync и фиксировать данные. Также стоит иметь в виду, +что в этом случае до момента fsync клиент хранит копию незафиксированных +данных в памяти, то есть, настройка влияет на потребление памяти клиентами. + +Параметр не влияет на сами OSD. diff --git a/docs/config/layout-osd.en.md b/docs/config/layout-osd.en.md new file mode 100644 index 00000000..932cb434 --- /dev/null +++ b/docs/config/layout-osd.en.md @@ -0,0 +1,176 @@ +[Documentation](../../README.md#documentation) → [Configuration](../config.en.md) → OSD Disk Layout Parameters + +----- + +[Читать на русском](layout-osd.ru.md) + +# OSD Disk Layout Parameters + +These parameters apply to OSDs, are fixed at the moment of OSD drive +initialization and can't be changed after it without losing data. + +- [data_device](#data_device) +- [meta_device](#meta_device) +- [journal_device](#journal_device) +- [journal_offset](#journal_offset) +- [journal_size](#journal_size) +- [meta_offset](#meta_offset) +- [data_offset](#data_offset) +- [data_size](#data_size) +- [meta_block_size](#meta_block_size) +- [journal_block_size](#journal_block_size) +- [disable_data_fsync](#disable_data_fsync) +- [disable_meta_fsync](#disable_meta_fsync) +- [disable_journal_fsync](#disable_journal_fsync) +- [disable_device_lock](#disable_device_lock) +- [disk_alignment](#disk_alignment) + +## data_device + +- Type: string + +Path to the block device to use for data. It's highly recommendded to use +stable paths for all device names: `/dev/disk/by-partuuid/xxx...` instead +of just `/dev/sda` or `/dev/nvme0n1` to not mess up after server restart. +Files can also be used instead of block devices, but this is implemented +only for testing purposes and not for production. + +## meta_device + +- Type: string + +Path to the block device to use for the metadata. Metadata must be on a fast +SSD or performance will suffer. If this option is skipped, `data_device` is +used for the metadata. + +## journal_device + +- Type: string + +Path to the block device to use for the journal. Journal must be on a fast +SSD or performance will suffer. If this option is skipped, `meta_device` is +used for the journal, and if it's also empty, journal is put on +`data_device`. It's almost always fine to put metadata and journal on the +same device, in this case you only need to set `meta_device`. + +## journal_offset + +- Type: integer +- Default: 0 + +Offset on the device in bytes where the journal is stored. + +## journal_size + +- Type: integer + +Journal size in bytes. By default, all available space between journal_offset +and data_offset, meta_offset or the end of the journal device is used. +Large journals aren't needed in SSD-only setups, 32 MB is always enough. +In SSD+HDD setups it is beneficial to use larger journals (for example, 1 GB) +and enable [throttle_small_writes](osd.en.md#throttle_small_writes). + +## meta_offset + +- Type: integer +- Default: 0 + +Offset on the device in bytes where the metadata area is stored. +Again, set it to something if you colocate metadata with journal or data. + +## data_offset + +- Type: integer +- Default: 0 + +Offset on the device in bytes where the data area is stored. +Again, set it to something if you colocate data with journal or metadata. + +## data_size + +- Type: integer + +Data area size in bytes. By default, the whole data device up to the end +will be used for the data area, but you can restrict it if you want to use +a smaller part. Note that there is no option to set metadata area size - +it's derived from the data area size. + +## meta_block_size + +- Type: integer +- Default: 4096 + +Physical block size of the metadata device. 4096 for most current +HDDs and SSDs. + +## journal_block_size + +- Type: integer +- Default: 4096 + +Physical block size of the journal device. Must be a multiple of +`disk_alignment`. 4096 for most current HDDs and SSDs. + +## disable_data_fsync + +- Type: boolean +- Default: false + +Do not issue fsyncs to the data device, i.e. do not flush its cache. +Safe ONLY if your data device has write-through cache. If you disable +the cache yourself using `hdparm` or `scsi_disk/cache_type` then make sure +that the cache disable command is run every time before starting Vitastor +OSD, for example, in the systemd unit. See also `immediate_commit` option +for the instructions to disable cache and how to benefit from it. + +## disable_meta_fsync + +- Type: boolean +- Default: false + +Same as disable_data_fsync, but for the metadata device. If the metadata +device is not set or if the data device is used for the metadata the option +is ignored and disable_data_fsync value is used instead of it. + +## disable_journal_fsync + +- Type: boolean +- Default: false + +Same as disable_data_fsync, but for the journal device. If the journal +device is not set or if the metadata device is used for the journal the +option is ignored and disable_meta_fsync value is used instead of it. If +the same device is used for data, metadata and journal the option is also +ignored and disable_data_fsync value is used instead of it. + +## disable_device_lock + +- Type: boolean +- Default: false + +Do not lock data, metadata and journal block devices exclusively with +flock(). Though it's not recommended, but you can use it you want to run +multiple OSD with a single device and different offsets, without using +partitions. + +## disk_alignment + +- Type: integer +- Default: 4096 + +Required physical disk write alignment. Most current SSD and HDD drives +use 4 KB physical sectors even if they report 512 byte logical sector +size, so 4 KB is a good default setting. + +Note, however, that physical sector size also affects WA, because with block +devices it's impossible to write anything smaller than a block. So, when +Vitastor has to write a single metadata entry that's only about 32 bytes in +size, it actually has to write the whole 4 KB sector. + +Because of this it can actually be beneficial to use SSDs which work well +with 512 byte sectors and use 512 byte disk_alignment, journal_block_size +and meta_block_size. But the only SSD that may fit into this category is +Intel Optane (probably, not tested yet). + +Clients don't need to be aware of disk_alignment, so it's not required to +put a modified value into etcd key /vitastor/config/global. diff --git a/docs/config/layout-osd.ru.md b/docs/config/layout-osd.ru.md new file mode 100644 index 00000000..f6652e94 --- /dev/null +++ b/docs/config/layout-osd.ru.md @@ -0,0 +1,185 @@ +[Документация](../../README-ru.md#документация) → [Конфигурация](../config.ru.md) → Дисковые параметры OSD + +----- + +[Read in English](layout-osd.en.md) + +# Дисковые параметры OSD + +Данные параметры используются только OSD и, также как и общекластерные +дисковые параметры, задаются в момент инициализации дисков OSD и не могут быть +изменены после этого без потери данных. + +- [data_device](#data_device) +- [meta_device](#meta_device) +- [journal_device](#journal_device) +- [journal_offset](#journal_offset) +- [journal_size](#journal_size) +- [meta_offset](#meta_offset) +- [data_offset](#data_offset) +- [data_size](#data_size) +- [meta_block_size](#meta_block_size) +- [journal_block_size](#journal_block_size) +- [disable_data_fsync](#disable_data_fsync) +- [disable_meta_fsync](#disable_meta_fsync) +- [disable_journal_fsync](#disable_journal_fsync) +- [disable_device_lock](#disable_device_lock) +- [disk_alignment](#disk_alignment) + +## data_device + +- Тип: строка + +Путь к диску (блочному устройству) для хранения данных. Крайне рекомендуется +использовать стабильные пути: `/dev/disk/by-partuuid/xxx...` вместо простых +`/dev/sda` или `/dev/nvme0n1`, чтобы пути не могли спутаться после +перезагрузки сервера. Также вместо блочных устройств можно указывать файлы, +но это реализовано только для тестирования, а не для боевой среды. + +## meta_device + +- Тип: строка + +Путь к диску метаданных. Метаданные должны располагаться на быстром +SSD-диске, иначе производительность пострадает. Если эта опция не указана, +для метаданных используется `data_device`. + +## journal_device + +- Тип: строка + +Путь к диску журнала. Журнал должен располагаться на быстром SSD-диске, +иначе производительность пострадает. Если эта опция не указана, +для журнала используется `meta_device`, если же пуста и она, журнал +располагается на `data_device`. Нормально располагать журнал и метаданные +на одном устройстве, в этом случае достаточно указать только `meta_device`. + +## journal_offset + +- Тип: целое число +- Значение по умолчанию: 0 + +Смещение на устройстве в байтах, по которому располагается журнал. + +## journal_size + +- Тип: целое число + +Размер журнала в байтах. По умолчанию для журнала используется всё доступное +место между journal_offset и data_offset, meta_offset или концом диска. +В SSD-кластерах большие журналы не нужны, достаточно 32 МБ. В гибридных +(SSD+HDD) кластерах осмысленно использовать больший размер журнал (например, 1 ГБ) +и включить [throttle_small_writes](osd.ru.md#throttle_small_writes). + +## meta_offset + +- Тип: целое число +- Значение по умолчанию: 0 + +Смещение на устройстве в байтах, по которому располагаются метаданные. +Эту опцию нужно задать, если метаданные у вас хранятся на том же +устройстве, что данные или журнал. + +## data_offset + +- Тип: целое число +- Значение по умолчанию: 0 + +Смещение на устройстве в байтах, по которому располагаются данные. +Эту опцию нужно задать, если данные у вас хранятся на том же +устройстве, что метаданные или журнал. + +## data_size + +- Тип: целое число + +Размер области данных в байтах. По умолчанию под данные будет использована +вся доступная область устройства данных до конца устройства, но вы можете +использовать эту опцию, чтобы ограничить её меньшим размером. Заметьте, что +опции размера области метаданных нет - она вычисляется из размера области +данных автоматически. + +## meta_block_size + +- Тип: целое число +- Значение по умолчанию: 4096 + +Размер физического блока устройства метаданных. 4096 для большинства +современных SSD и HDD. + +## journal_block_size + +- Тип: целое число +- Значение по умолчанию: 4096 + +Размер физического блока устройства журнала. Должен быть кратен +`disk_alignment`. 4096 для большинства современных SSD и HDD. + +## disable_data_fsync + +- Тип: булево (да/нет) +- Значение по умолчанию: false + +Не отправлять fsync-и устройству данных, т.е. не сбрасывать его кэш. +Безопасно, ТОЛЬКО если ваше устройство данных имеет кэш со сквозной +записью (write-through). Если вы отключаете кэш через `hdparm` или +`scsi_disk/cache_type`, то удостоверьтесь, что команда отключения кэша +выполняется перед каждым запуском Vitastor OSD, например, в systemd unit-е. +Смотрите также опцию `immediate_commit` для инструкций по отключению кэша +и о том, как из этого извлечь выгоду. + +## disable_meta_fsync + +- Тип: булево (да/нет) +- Значение по умолчанию: false + +То же, что disable_data_fsync, но для устройства метаданных. Если устройство +метаданных не задано или если оно равно устройству данных, значение опции +игнорируется и вместо него используется значение опции disable_data_fsync. + +## disable_journal_fsync + +- Тип: булево (да/нет) +- Значение по умолчанию: false + +То же, что disable_data_fsync, но для устройства журнала. Если устройство +журнала не задано или если оно равно устройству метаданных, значение опции +игнорируется и вместо него используется значение опции disable_meta_fsync. +Если одно и то же устройство используется и под данные, и под журнал, и под +метаданные - значение опции также игнорируется и вместо него используется +значение опции disable_data_fsync. + +## disable_device_lock + +- Тип: булево (да/нет) +- Значение по умолчанию: false + +Не блокировать устройства данных, метаданных и журнала от открытия их +другими OSD с помощью flock(). Так делать не рекомендуется, но теоретически +вы можете это использовать, чтобы запускать несколько OSD на одном +устройстве с разными смещениями и без использования разделов. + +## disk_alignment + +- Тип: целое число +- Значение по умолчанию: 4096 + +Требуемое выравнивание записи на физические диски. Почти все современные +SSD и HDD диски используют 4 КБ физические секторы, даже если показывают +логический размер сектора 512 байт, поэтому 4 КБ - хорошее значение по +умолчанию. + +Однако стоит понимать, что физический размер сектора тоже влияет на +избыточную запись (WA), потому что ничего меньше блока (сектора) на блочное +устройство записать невозможно. Таким образом, когда Vitastor-у нужно +записать на диск всего лишь одну 32-байтную запись метаданных, фактически +приходится перезаписывать 4 КБ сектор целиком. + +Поэтому, на самом деле, может быть выгодно найти SSD, хорошо работающие с +меньшими, 512-байтными, блоками и использовать 512-байтные disk_alignment, +journal_block_size и meta_block_size. Однако единственные SSD, которые +теоретически могут попасть в эту категорию - это Intel Optane (но и это +пока не проверялось автором). + +Клиентам не обязательно знать про disk_alignment, так что помещать значение +этого параметра в etcd в /vitastor/config/global не нужно. diff --git a/docs/config/monitor.en.md b/docs/config/monitor.en.md new file mode 100644 index 00000000..9bf3f7cc --- /dev/null +++ b/docs/config/monitor.en.md @@ -0,0 +1,79 @@ +[Documentation](../../README.md#documentation) → [Configuration](../config.en.md) → Monitor Parameters + +----- + +[Читать на русском](monitor.ru.md) + +# Monitor Parameters + +These parameters only apply to Monitors. + +- [etcd_mon_ttl](#etcd_mon_ttl) +- [etcd_mon_timeout](#etcd_mon_timeout) +- [etcd_mon_retries](#etcd_mon_retries) +- [mon_change_timeout](#mon_change_timeout) +- [mon_stats_timeout](#mon_stats_timeout) +- [osd_out_time](#osd_out_time) +- [placement_levels](#placement_levels) + +## etcd_mon_ttl + +- Type: seconds +- Default: 30 +- Minimum: 10 + +Monitor etcd lease refresh interval in seconds + +## etcd_mon_timeout + +- Type: milliseconds +- Default: 1000 + +etcd request timeout used by monitor + +## etcd_mon_retries + +- Type: integer +- Default: 5 + +Maximum number of attempts for one monitor etcd request + +## mon_change_timeout + +- Type: milliseconds +- Default: 1000 +- Minimum: 100 + +Optimistic retry interval for monitor etcd modification requests + +## mon_stats_timeout + +- Type: milliseconds +- Default: 1000 +- Minimum: 100 + +Interval for monitor to wait before updating aggregated statistics in +etcd after receiving OSD statistics updates + +## osd_out_time + +- Type: seconds +- Default: 600 + +Time after which a failed OSD is removed from the data distribution. +I.e. time which the monitor waits before attempting to restore data +redundancy using other OSDs. + +## placement_levels + +- Type: json +- Default: `{"host":100,"osd":101}` + +Levels for the placement tree. You can define arbitrary tree levels by +defining them in this parameter. The configuration parameter value should +contain a JSON object with level names as keys and integer priorities as +values. Smaller priority means higher level in tree. For example, +"datacenter" should have smaller priority than "osd". "host" and "osd" +levels are always predefined and can't be removed. If one of them is not +present in the configuration, then it is defined with the default priority +(100 for "host", 101 for "osd"). diff --git a/docs/config/monitor.ru.md b/docs/config/monitor.ru.md new file mode 100644 index 00000000..12cca10a --- /dev/null +++ b/docs/config/monitor.ru.md @@ -0,0 +1,80 @@ +[Документация](../../README-ru.md#документация) → [Конфигурация](../config.ru.md) → Параметры мониторов + +----- + +[Read in English](monitor.en.md) + +# Параметры мониторов + +Данные параметры используются только мониторами Vitastor. + +- [etcd_mon_ttl](#etcd_mon_ttl) +- [etcd_mon_timeout](#etcd_mon_timeout) +- [etcd_mon_retries](#etcd_mon_retries) +- [mon_change_timeout](#mon_change_timeout) +- [mon_stats_timeout](#mon_stats_timeout) +- [osd_out_time](#osd_out_time) +- [placement_levels](#placement_levels) + +## etcd_mon_ttl + +- Тип: секунды +- Значение по умолчанию: 30 +- Минимальное значение: 10 + +Интервал обновления etcd резервации (lease) монитором + +## etcd_mon_timeout + +- Тип: миллисекунды +- Значение по умолчанию: 1000 + +Таймаут выполнения запросов к etcd от монитора + +## etcd_mon_retries + +- Тип: целое число +- Значение по умолчанию: 5 + +Максимальное число попыток выполнения запросов к etcd монитором + +## mon_change_timeout + +- Тип: миллисекунды +- Значение по умолчанию: 1000 +- Минимальное значение: 100 + +Время повтора при коллизиях при запросах модификации в etcd, производимых монитором + +## mon_stats_timeout + +- Тип: миллисекунды +- Значение по умолчанию: 1000 +- Минимальное значение: 100 + +Интервал, который монитор ожидает при изменении статистики по отдельным +OSD перед обновлением агрегированной статистики в etcd + +## osd_out_time + +- Тип: секунды +- Значение по умолчанию: 600 + +Время, через которое отключенный OSD исключается из распределения данных. +То есть, время, которое монитор ожидает перед попыткой переместить данные +на другие OSD и таким образом восстановить избыточность хранения. + +## placement_levels + +- Тип: json +- Значение по умолчанию: `{"host":100,"osd":101}` + +Определения уровней для дерева размещения OSD. Вы можете определять +произвольные уровни, помещая их в данный параметр конфигурации. Значение +параметра должно содержать JSON-объект, ключи которого будут являться +названиями уровней, а значения - целочисленными приоритетами. Меньшие +приоритеты соответствуют верхним уровням дерева. Например, уровень +"датацентр" должен иметь меньший приоритет, чем "OSD". Уровни с названиями +"host" и "osd" являются предопределёнными и не могут быть удалены. Если +один из них отсутствует в конфигурации, он доопределяется с приоритетом по +умолчанию (100 для уровня "host", 101 для "osd"). diff --git a/docs/config/network.en.md b/docs/config/network.en.md new file mode 100644 index 00000000..3fe55bf2 --- /dev/null +++ b/docs/config/network.en.md @@ -0,0 +1,214 @@ +[Documentation](../../README.md#documentation) → [Configuration](../config.en.md) → Network Protocol Parameters + +----- + +[Читать на русском](network.ru.md) + +# Network Protocol Parameters + +These parameters apply to clients and OSDs and affect network connection logic +between clients, OSDs and etcd. + +- [tcp_header_buffer_size](#tcp_header_buffer_size) +- [use_sync_send_recv](#use_sync_send_recv) +- [use_rdma](#use_rdma) +- [rdma_device](#rdma_device) +- [rdma_port_num](#rdma_port_num) +- [rdma_gid_index](#rdma_gid_index) +- [rdma_mtu](#rdma_mtu) +- [rdma_max_sge](#rdma_max_sge) +- [rdma_max_msg](#rdma_max_msg) +- [rdma_max_recv](#rdma_max_recv) +- [peer_connect_interval](#peer_connect_interval) +- [peer_connect_timeout](#peer_connect_timeout) +- [osd_idle_timeout](#osd_idle_timeout) +- [osd_ping_timeout](#osd_ping_timeout) +- [up_wait_retry_interval](#up_wait_retry_interval) +- [max_etcd_attempts](#max_etcd_attempts) +- [etcd_quick_timeout](#etcd_quick_timeout) +- [etcd_slow_timeout](#etcd_slow_timeout) +- [etcd_keepalive_timeout](#etcd_keepalive_timeout) +- [etcd_ws_keepalive_timeout](#etcd_ws_keepalive_timeout) + +## tcp_header_buffer_size + +- Type: integer +- Default: 65536 + +Size of the buffer used to read data using an additional copy. Vitastor +packet headers are 128 bytes, payload is always at least 4 KB, so it is +usually beneficial to try to read multiple packets at once even though +it requires to copy the data an additional time. The rest of each packet +is received without an additional copy. You can try to play with this +parameter and see how it affects random iops and linear bandwidth if you +want. + +## use_sync_send_recv + +- Type: boolean +- Default: false + +If true, synchronous send/recv syscalls are used instead of io_uring for +socket communication. Useless for OSDs because they require io_uring anyway, +but may be required for clients with old kernel versions. + +## use_rdma + +- Type: boolean +- Default: true + +Try to use RDMA for communication if it's available. Disable if you don't +want Vitastor to use RDMA. TCP-only clients can also talk to an RDMA-enabled +cluster, so disabling RDMA may be needed if clients have RDMA devices, +but they are not connected to the cluster. + +## rdma_device + +- Type: string + +RDMA device name to use for Vitastor OSD communications (for example, +"rocep5s0f0"). Please note that Vitastor RDMA requires Implicit On-Demand +Paging (Implicit ODP) and Scatter/Gather (SG) support from the RDMA device +to work. For example, Mellanox ConnectX-3 and older adapters don't have +Implicit ODP, so they're unsupported by Vitastor. Run `ibv_devinfo -v` as +root to list available RDMA devices and their features. + +## rdma_port_num + +- Type: integer +- Default: 1 + +RDMA device port number to use. Only for devices that have more than 1 port. +See `phys_port_cnt` in `ibv_devinfo -v` output to determine how many ports +your device has. + +## rdma_gid_index + +- Type: integer +- Default: 0 + +Global address identifier index of the RDMA device to use. Different GID +indexes may correspond to different protocols like RoCEv1, RoCEv2 and iWARP. +Search for "GID" in `ibv_devinfo -v` output to determine which GID index +you need. + +**IMPORTANT:** If you want to use RoCEv2 (as recommended) then the correct +rdma_gid_index is usually 1 (IPv6) or 3 (IPv4). + +## rdma_mtu + +- Type: integer +- Default: 4096 + +RDMA Path MTU to use. Must be 1024, 2048 or 4096. There is usually no +sense to change it from the default 4096. + +## rdma_max_sge + +- Type: integer +- Default: 128 + +Maximum number of scatter/gather entries to use for RDMA. OSDs negotiate +the actual value when establishing connection anyway, so it's usually not +required to change this parameter. + +## rdma_max_msg + +- Type: integer +- Default: 1048576 + +Maximum size of a single RDMA send or receive operation in bytes. + +## rdma_max_recv + +- Type: integer +- Default: 8 + +Maximum number of parallel RDMA receive operations. Note that this number +of receive buffers `rdma_max_msg` in size are allocated for each client, +so this setting actually affects memory usage. This is because RDMA receive +operations are (sadly) still not zero-copy in Vitastor. It may be fixed in +later versions. + +## peer_connect_interval + +- Type: seconds +- Default: 5 +- Minimum: 1 + +Interval before attempting to reconnect to an unavailable OSD. + +## peer_connect_timeout + +- Type: seconds +- Default: 5 +- Minimum: 1 + +Timeout for OSD connection attempts. + +## osd_idle_timeout + +- Type: seconds +- Default: 5 +- Minimum: 1 + +OSD connection inactivity time after which clients and other OSDs send +keepalive requests to check state of the connection. + +## osd_ping_timeout + +- Type: seconds +- Default: 5 +- Minimum: 1 + +Maximum time to wait for OSD keepalive responses. If an OSD doesn't respond +within this time, the connection to it is dropped and a reconnection attempt +is scheduled. + +## up_wait_retry_interval + +- Type: milliseconds +- Default: 500 +- Minimum: 50 + +OSDs respond to clients with a special error code when they receive I/O +requests for a PG that's not synchronized and started. This parameter sets +the time for the clients to wait before re-attempting such I/O requests. + +## max_etcd_attempts + +- Type: integer +- Default: 5 + +Maximum number of attempts for etcd requests which can't be retried +indefinitely. + +## etcd_quick_timeout + +- Type: milliseconds +- Default: 1000 + +Timeout for etcd requests which should complete quickly, like lease refresh. + +## etcd_slow_timeout + +- Type: milliseconds +- Default: 5000 + +Timeout for etcd requests which are allowed to wait for some time. + +## etcd_keepalive_timeout + +- Type: seconds +- Default: max(30, etcd_report_interval*2) + +Timeout for etcd connection HTTP Keep-Alive. Should be higher than +etcd_report_interval to guarantee that keepalive actually works. + +## etcd_ws_keepalive_timeout + +- Type: seconds +- Default: 30 + +etcd websocket ping interval required to keep the connection alive and +detect disconnections quickly. diff --git a/docs/config/network.ru.md b/docs/config/network.ru.md new file mode 100644 index 00000000..454eeb44 --- /dev/null +++ b/docs/config/network.ru.md @@ -0,0 +1,224 @@ +[Документация](../../README-ru.md#документация) → [Конфигурация](../config.ru.md) → Параметры сетевого протокола + +----- + +[Read in English](network.en.md) + +# Параметры сетевого протокола + +Данные параметры используются клиентами и OSD и влияют на логику сетевого +взаимодействия между клиентами, OSD, а также etcd. + +- [tcp_header_buffer_size](#tcp_header_buffer_size) +- [use_sync_send_recv](#use_sync_send_recv) +- [use_rdma](#use_rdma) +- [rdma_device](#rdma_device) +- [rdma_port_num](#rdma_port_num) +- [rdma_gid_index](#rdma_gid_index) +- [rdma_mtu](#rdma_mtu) +- [rdma_max_sge](#rdma_max_sge) +- [rdma_max_msg](#rdma_max_msg) +- [rdma_max_recv](#rdma_max_recv) +- [peer_connect_interval](#peer_connect_interval) +- [peer_connect_timeout](#peer_connect_timeout) +- [osd_idle_timeout](#osd_idle_timeout) +- [osd_ping_timeout](#osd_ping_timeout) +- [up_wait_retry_interval](#up_wait_retry_interval) +- [max_etcd_attempts](#max_etcd_attempts) +- [etcd_quick_timeout](#etcd_quick_timeout) +- [etcd_slow_timeout](#etcd_slow_timeout) +- [etcd_keepalive_timeout](#etcd_keepalive_timeout) +- [etcd_ws_keepalive_timeout](#etcd_ws_keepalive_timeout) + +## tcp_header_buffer_size + +- Тип: целое число +- Значение по умолчанию: 65536 + +Размер буфера для чтения данных с дополнительным копированием. Пакеты +Vitastor содержат 128-байтные заголовки, за которыми следуют данные размером +от 4 КБ и для мелких операций ввода-вывода обычно выгодно за 1 вызов читать +сразу несколько пакетов, даже не смотря на то, что это требует лишний раз +скопировать данные. Часть каждого пакета за пределами значения данного +параметра читается без дополнительного копирования. Вы можете попробовать +поменять этот параметр и посмотреть, как он влияет на производительность +случайного и линейного доступа. + +## use_sync_send_recv + +- Тип: булево (да/нет) +- Значение по умолчанию: false + +Если установлено в истину, то вместо io_uring для передачи данных по сети +будут использоваться обычные синхронные системные вызовы send/recv. Для OSD +это бессмысленно, так как OSD в любом случае нуждается в io_uring, но, в +принципе, это может применяться для клиентов со старыми версиями ядра. + +## use_rdma + +- Тип: булево (да/нет) +- Значение по умолчанию: true + +Пытаться использовать RDMA для связи при наличии доступных устройств. +Отключите, если вы не хотите, чтобы Vitastor использовал RDMA. +TCP-клиенты также могут работать с RDMA-кластером, так что отключать +RDMA может быть нужно только если у клиентов есть RDMA-устройства, +но они не имеют соединения с кластером Vitastor. + +## rdma_device + +- Тип: строка + +Название RDMA-устройства для связи с Vitastor OSD (например, "rocep5s0f0"). +Имейте в виду, что поддержка RDMA в Vitastor требует функций устройства +Implicit On-Demand Paging (Implicit ODP) и Scatter/Gather (SG). Например, +адаптеры Mellanox ConnectX-3 и более старые не поддерживают Implicit ODP и +потому не поддерживаются в Vitastor. Запустите `ibv_devinfo -v` от имени +суперпользователя, чтобы посмотреть список доступных RDMA-устройств, их +параметры и возможности. + +## rdma_port_num + +- Тип: целое число +- Значение по умолчанию: 1 + +Номер порта RDMA-устройства, который следует использовать. Имеет смысл +только для устройств, у которых более 1 порта. Чтобы узнать, сколько портов +у вашего адаптера, посмотрите `phys_port_cnt` в выводе команды +`ibv_devinfo -v`. + +## rdma_gid_index + +- Тип: целое число +- Значение по умолчанию: 0 + +Номер глобального идентификатора адреса RDMA-устройства, который следует +использовать. Разным gid_index могут соответствовать разные протоколы связи: +RoCEv1, RoCEv2, iWARP. Чтобы понять, какой нужен вам - смотрите строчки со +словом "GID" в выводе команды `ibv_devinfo -v`. + +**ВАЖНО:** Если вы хотите использовать RoCEv2 (как мы и рекомендуем), то +правильный rdma_gid_index, как правило, 1 (IPv6) или 3 (IPv4). + +## rdma_mtu + +- Тип: целое число +- Значение по умолчанию: 4096 + +Максимальная единица передачи (Path MTU) для RDMA. Должно быть равно 1024, +2048 или 4096. Обычно нет смысла менять значение по умолчанию, равное 4096. + +## rdma_max_sge + +- Тип: целое число +- Значение по умолчанию: 128 + +Максимальное число записей разделения/сборки (scatter/gather) для RDMA. +OSD в любом случае согласовывают реальное значение при установке соединения, +так что менять этот параметр обычно не нужно. + +## rdma_max_msg + +- Тип: целое число +- Значение по умолчанию: 1048576 + +Максимальный размер одной RDMA-операции отправки или приёма. + +## rdma_max_recv + +- Тип: целое число +- Значение по умолчанию: 8 + +Максимальное число параллельных RDMA-операций получения данных. Следует +иметь в виду, что данное число буферов размером `rdma_max_msg` выделяется +для каждого подключённого клиентского соединения, так что данная настройка +влияет на потребление памяти. Это так потому, что RDMA-приём данных в +Vitastor, увы, всё равно не является zero-copy, т.е. всё равно 1 раз +копирует данные в памяти. Данная особенность, возможно, будет исправлена в +более новых версиях Vitastor. + +## peer_connect_interval + +- Тип: секунды +- Значение по умолчанию: 5 +- Минимальное значение: 1 + +Время ожидания перед повторной попыткой соединиться с недоступным OSD. + +## peer_connect_timeout + +- Тип: секунды +- Значение по умолчанию: 5 +- Минимальное значение: 1 + +Максимальное время ожидания попытки соединения с OSD. + +## osd_idle_timeout + +- Тип: секунды +- Значение по умолчанию: 5 +- Минимальное значение: 1 + +Время неактивности соединения с OSD, после которого клиенты или другие OSD +посылают запрос проверки состояния соединения. + +## osd_ping_timeout + +- Тип: секунды +- Значение по умолчанию: 5 +- Минимальное значение: 1 + +Максимальное время ожидания ответа на запрос проверки состояния соединения. +Если OSD не отвечает за это время, соединение отключается и производится +повторная попытка соединения. + +## up_wait_retry_interval + +- Тип: миллисекунды +- Значение по умолчанию: 500 +- Минимальное значение: 50 + +Когда OSD получают от клиентов запросы ввода-вывода, относящиеся к не +поднятым на данный момент на них PG, либо к PG в процессе синхронизации, +они отвечают клиентам специальным кодом ошибки, означающим, что клиент +должен некоторое время подождать перед повторением запроса. Именно это время +ожидания задаёт данный параметр. + +## max_etcd_attempts + +- Тип: целое число +- Значение по умолчанию: 5 + +Максимальное число попыток выполнения запросов к etcd для тех запросов, +которые нельзя повторять бесконечно. + +## etcd_quick_timeout + +- Тип: миллисекунды +- Значение по умолчанию: 1000 + +Максимальное время выполнения запросов к etcd, которые должны завершаться +быстро, таких, как обновление резервации (lease). + +## etcd_slow_timeout + +- Тип: миллисекунды +- Значение по умолчанию: 5000 + +Максимальное время выполнения запросов к etcd, для которых не обязательно +гарантировать быстрое выполнение. + +## etcd_keepalive_timeout + +- Тип: секунды +- Значение по умолчанию: max(30, etcd_report_interval*2) + +Таймаут для HTTP Keep-Alive в соединениях к etcd. Должен быть больше, чем +etcd_report_interval, чтобы keepalive гарантированно работал. + +## etcd_ws_keepalive_timeout + +- Тип: секунды +- Значение по умолчанию: 30 + +Интервал проверки живости вебсокет-подключений к etcd. diff --git a/docs/config/osd.en.md b/docs/config/osd.en.md new file mode 100644 index 00000000..fc9f0d06 --- /dev/null +++ b/docs/config/osd.en.md @@ -0,0 +1,297 @@ +[Documentation](../../README.md#documentation) → [Configuration](../config.en.md) → Runtime OSD Parameters + +----- + +[Читать на русском](osd.ru.md) + +# Runtime OSD Parameters + +These parameters only apply to OSDs, are not fixed at the moment of OSD drive +initialization and can be changed with an OSD restart. + +- [etcd_report_interval](#etcd_report_interval) +- [run_primary](#run_primary) +- [osd_network](#osd_network) +- [bind_address](#bind_address) +- [bind_port](#bind_port) +- [autosync_interval](#autosync_interval) +- [autosync_writes](#autosync_writes) +- [recovery_queue_depth](#recovery_queue_depth) +- [recovery_sync_batch](#recovery_sync_batch) +- [readonly](#readonly) +- [no_recovery](#no_recovery) +- [no_rebalance](#no_rebalance) +- [print_stats_interval](#print_stats_interval) +- [slow_log_interval](#slow_log_interval) +- [max_write_iodepth](#max_write_iodepth) +- [min_flusher_count](#min_flusher_count) +- [max_flusher_count](#max_flusher_count) +- [inmemory_metadata](#inmemory_metadata) +- [inmemory_journal](#inmemory_journal) +- [journal_sector_buffer_count](#journal_sector_buffer_count) +- [journal_no_same_sector_overwrites](#journal_no_same_sector_overwrites) +- [throttle_small_writes](#throttle_small_writes) +- [throttle_target_iops](#throttle_target_iops) +- [throttle_target_mbs](#throttle_target_mbs) +- [throttle_target_parallelism](#throttle_target_parallelism) +- [throttle_threshold_us](#throttle_threshold_us) +- [osd_memlock](#osd_memlock) + +## etcd_report_interval + +- Type: seconds +- Default: 5 + +Interval at which OSDs report their state to etcd. Affects OSD lease time +and thus the failover speed. Lease time is equal to this parameter value +plus max_etcd_attempts * etcd_quick_timeout because it should be guaranteed +that every OSD always refreshes its lease in time. + +## run_primary + +- Type: boolean +- Default: true + +Start primary OSD logic on this OSD. As of now, can be turned off only for +debugging purposes. It's possible to implement additional feature for the +monitor which may allow to separate primary and secondary OSDs, but it's +unclear why anyone could need it, so it's not implemented. + +## osd_network + +- Type: string or array of strings + +Network mask of the network (IPv4 or IPv6) to use for OSDs. Note that +although it's possible to specify multiple networks here, this does not +mean that OSDs will create multiple listening sockets - they'll only +pick the first matching address of an UP + RUNNING interface. Separate +networks for cluster and client connections are also not implemented, but +they are mostly useless anyway, so it's not a big deal. + +## bind_address + +- Type: string +- Default: 0.0.0.0 + +Instead of the network mask, you can also set OSD listen address explicitly +using this parameter. May be useful if you want to start OSDs on interfaces +that are not UP + RUNNING. + +## bind_port + +- Type: integer + +By default, OSDs pick random ports to use for incoming connections +automatically. With this option you can set a specific port for a specific +OSD by hand. + +## autosync_interval + +- Type: seconds +- Default: 5 + +Time interval at which automatic fsyncs/flushes are issued by each OSD when +the immediate_commit mode if disabled. fsyncs are required because without +them OSDs quickly fill their journals, become unable to clear them and +stall. Also this option limits the amount of recent uncommitted changes +which OSDs may lose in case of a power outage in case when clients don't +issue fsyncs at all. + +## autosync_writes + +- Type: integer +- Default: 128 + +Same as autosync_interval, but sets the maximum number of uncommitted write +operations before issuing an fsync operation internally. + +## recovery_queue_depth + +- Type: integer +- Default: 4 + +Maximum recovery operations per one primary OSD at any given moment of time. +Currently it's the only parameter available to tune the speed or recovery +and rebalancing, but it's planned to implement more. + +## recovery_sync_batch + +- Type: integer +- Default: 16 + +Maximum number of recovery operations before issuing an additional fsync. + +## readonly + +- Type: boolean +- Default: false + +Read-only mode. If this is enabled, an OSD will never issue any writes to +the underlying device. This may be useful for recovery purposes. + +## no_recovery + +- Type: boolean +- Default: false + +Disable automatic background recovery of objects. Note that it doesn't +affect implicit recovery of objects happening during writes - a write is +always made to a full set of at least pg_minsize OSDs. + +## no_rebalance + +- Type: boolean +- Default: false + +Disable background movement of data between different OSDs. Disabling it +means that PGs in the `has_misplaced` state will be left in it indefinitely. + +## print_stats_interval + +- Type: seconds +- Default: 3 + +Time interval at which OSDs print simple human-readable operation +statistics on stdout. + +## slow_log_interval + +- Type: seconds +- Default: 10 + +Time interval at which OSDs dump slow or stuck operations on stdout, if +they're any. Also it's the time after which an operation is considered +"slow". + +## max_write_iodepth + +- Type: integer +- Default: 128 + +Parallel client write operation limit per one OSD. Operations that exceed +this limit are pushed to a temporary queue instead of being executed +immediately. + +## min_flusher_count + +- Type: integer +- Default: 1 + +Flusher is a micro-thread that moves data from the journal to the data +area of the device. Their number is auto-tuned between minimum and maximum. +Minimum number is set by this parameter. + +## max_flusher_count + +- Type: integer +- Default: 256 + +Maximum number of journal flushers (see above min_flusher_count). + +## inmemory_metadata + +- Type: boolean +- Default: true + +This parameter makes Vitastor always keep metadata area of the block device +in memory. It's required for good performance because it allows to avoid +additional read-modify-write cycles during metadata modifications. Metadata +area size is currently roughly 224 MB per 1 TB of data. You can turn it off +to reduce memory usage by this value, but it will hurt performance. This +restriction is likely to be removed in the future along with the upgrade +of the metadata storage scheme. + +## inmemory_journal + +- Type: boolean +- Default: true + +This parameter make Vitastor always keep journal area of the block +device in memory. Turning it off will, again, reduce memory usage, but +hurt performance because flusher coroutines will have to read data from +the disk back before copying it into the main area. The memory usage benefit +is typically very small because it's sufficient to have 16-32 MB journal +for SSD OSDs. However, in theory it's possible that you'll want to turn it +off for hybrid (HDD+SSD) OSDs with large journals on quick devices. + +## journal_sector_buffer_count + +- Type: integer +- Default: 32 + +Maximum number of buffers that can be used for writing journal metadata +blocks. The only situation when you should increase it to a larger value +is when you enable journal_no_same_sector_overwrites. In this case set +it to, for example, 1024. + +## journal_no_same_sector_overwrites + +- Type: boolean +- Default: false + +Enable this option for SSDs like Intel D3-S4510 and D3-S4610 which REALLY +don't like when a program overwrites the same sector multiple times in a +row and slow down significantly (from 25000+ iops to ~3000 iops). When +this option is set, Vitastor will always move to the next sector of the +journal after writing it instead of possibly overwriting it the second time. + +Most (99%) other SSDs don't need this option. + +## throttle_small_writes + +- Type: boolean +- Default: false + +Enable soft throttling of small journaled writes. Useful for hybrid OSDs +with fast journal/metadata devices and slow data devices. The idea is that +small writes complete very quickly because they're first written to the +journal device, but moving them to the main device is slow. So if an OSD +allows clients to issue a lot of small writes it will perform very good +for several seconds and then the journal will fill up and the performance +will drop to almost zero. Throttling is meant to prevent this problem by +artifically slowing quick writes down based on the amount of free space in +the journal. When throttling is used, the performance of small writes will +decrease smoothly instead of abrupt drop at the moment when the journal +fills up. + +## throttle_target_iops + +- Type: integer +- Default: 100 + +Target maximum number of throttled operations per second under the condition +of full journal. Set it to approximate random write iops of your data devices +(HDDs). + +## throttle_target_mbs + +- Type: integer +- Default: 100 + +Target maximum bandwidth in MB/s of throttled operations per second under +the condition of full journal. Set it to approximate linear write +performance of your data devices (HDDs). + +## throttle_target_parallelism + +- Type: integer +- Default: 1 + +Target maximum parallelism of throttled operations under the condition of +full journal. Set it to approximate internal parallelism of your data +devices (1 for HDDs, 4-8 for SSDs). + +## throttle_threshold_us + +- Type: microseconds +- Default: 50 + +Minimal computed delay to be applied to throttled operations. Usually +doesn't need to be changed. + +## osd_memlock + +- Type: boolean +- Default: false + +Lock all OSD memory to prevent it from being unloaded into swap with mlockall(). Requires sufficient ulimit -l (max locked memory). diff --git a/docs/config/osd.ru.md b/docs/config/osd.ru.md new file mode 100644 index 00000000..86b2d79f --- /dev/null +++ b/docs/config/osd.ru.md @@ -0,0 +1,310 @@ +[Документация](../../README-ru.md#документация) → [Конфигурация](../config.ru.md) → Изменяемые параметры OSD + +----- + +[Read in English](osd.en.md) + +# Изменяемые параметры OSD + +Данные параметры используются только OSD, но, в отличие от дисковых параметров, +не фиксируются в момент инициализации дисков OSD и могут быть изменены в любой +момент с перезапуском OSD. + +- [etcd_report_interval](#etcd_report_interval) +- [run_primary](#run_primary) +- [osd_network](#osd_network) +- [bind_address](#bind_address) +- [bind_port](#bind_port) +- [autosync_interval](#autosync_interval) +- [autosync_writes](#autosync_writes) +- [recovery_queue_depth](#recovery_queue_depth) +- [recovery_sync_batch](#recovery_sync_batch) +- [readonly](#readonly) +- [no_recovery](#no_recovery) +- [no_rebalance](#no_rebalance) +- [print_stats_interval](#print_stats_interval) +- [slow_log_interval](#slow_log_interval) +- [max_write_iodepth](#max_write_iodepth) +- [min_flusher_count](#min_flusher_count) +- [max_flusher_count](#max_flusher_count) +- [inmemory_metadata](#inmemory_metadata) +- [inmemory_journal](#inmemory_journal) +- [journal_sector_buffer_count](#journal_sector_buffer_count) +- [journal_no_same_sector_overwrites](#journal_no_same_sector_overwrites) +- [throttle_small_writes](#throttle_small_writes) +- [throttle_target_iops](#throttle_target_iops) +- [throttle_target_mbs](#throttle_target_mbs) +- [throttle_target_parallelism](#throttle_target_parallelism) +- [throttle_threshold_us](#throttle_threshold_us) +- [osd_memlock](#osd_memlock) + +## etcd_report_interval + +- Тип: секунды +- Значение по умолчанию: 5 + +Интервал, с которым OSD обновляет своё состояние в etcd. Значение параметра +влияет на время резервации (lease) OSD и поэтому на скорость переключения +при падении OSD. Время lease равняется значению этого параметра плюс +max_etcd_attempts * etcd_quick_timeout. + +## run_primary + +- Тип: булево (да/нет) +- Значение по умолчанию: true + +Запускать логику первичного OSD на данном OSD. На данный момент отключать +эту опцию может иметь смысл только в целях отладки. В теории, можно +реализовать дополнительный режим для монитора, который позволит отделять +первичные OSD от вторичных, но пока не понятно, зачем это может кому-то +понадобиться, поэтому это не реализовано. + +## osd_network + +- Тип: строка или массив строк + +Маска подсети (IPv4 или IPv6) для использования для соединений с OSD. +Имейте в виду, что хотя сейчас и можно передать в этот параметр несколько +подсетей, это не означает, что OSD будут создавать несколько слушающих +сокетов - они лишь будут выбирать адрес первого поднятого (состояние UP + +RUNNING), подходящий под заданную маску. Также не реализовано разделение +кластерной и публичной сетей OSD. Правда, от него обычно всё равно довольно +мало толку, так что особенной проблемы в этом нет. + +## bind_address + +- Тип: строка +- Значение по умолчанию: 0.0.0.0 + +Этим параметром можно явным образом задать адрес, на котором будет ожидать +соединений OSD (вместо использования маски подсети). Может быть полезно, +например, чтобы запускать OSD на неподнятых интерфейсах (не UP + RUNNING). + +## bind_port + +- Тип: целое число + +По умолчанию OSD сами выбирают случайные порты для входящих подключений. +С помощью данной опции вы можете задать порт для отдельного OSD вручную. + +## autosync_interval + +- Тип: секунды +- Значение по умолчанию: 5 + +Временной интервал отправки автоматических fsync-ов (операций очистки кэша) +каждым OSD для случая, когда режим immediate_commit отключён. fsync-и нужны +OSD, чтобы успевать очищать журнал - без них OSD быстро заполняют журналы и +перестают обрабатывать операции записи. Также эта опция ограничивает объём +недавних незафиксированных изменений, которые OSD могут терять при +отключении питания, если клиенты вообще не отправляют fsync. + +## autosync_writes + +- Тип: целое число +- Значение по умолчанию: 128 + +Аналогично autosync_interval, но задаёт не временной интервал, а +максимальное количество незафиксированных операций записи перед +принудительной отправкой fsync-а. + +## recovery_queue_depth + +- Тип: целое число +- Значение по умолчанию: 4 + +Максимальное число операций восстановления на одном первичном OSD в любой +момент времени. На данный момент единственный параметр, который можно менять +для ускорения или замедления восстановления и перебалансировки данных, но +в планах реализация других параметров. + +## recovery_sync_batch + +- Тип: целое число +- Значение по умолчанию: 16 + +Максимальное число операций восстановления перед дополнительным fsync. + +## readonly + +- Тип: булево (да/нет) +- Значение по умолчанию: false + +Режим "только чтение". Если включить этот режим, OSD не будет писать ничего +на диск. Может быть полезно в целях восстановления. + +## no_recovery + +- Тип: булево (да/нет) +- Значение по умолчанию: false + +Отключить автоматическое фоновое восстановление объектов. Обратите внимание, +что эта опция не отключает восстановление объектов, происходящее при +записи - запись всегда производится в полный набор из как минимум pg_minsize +OSD. + +## no_rebalance + +- Тип: булево (да/нет) +- Значение по умолчанию: false + +Отключить фоновое перемещение объектов между разными OSD. Отключение +означает, что PG, находящиеся в состоянии `has_misplaced`, будут оставлены +в нём на неопределённый срок. + +## print_stats_interval + +- Тип: секунды +- Значение по умолчанию: 3 + +Временной интервал, с которым OSD печатают простую человекочитаемую +статистику выполнения операций в стандартный вывод. + +## slow_log_interval + +- Тип: секунды +- Значение по умолчанию: 10 + +Временной интервал, с которым OSD выводят в стандартный вывод список +медленных или зависших операций, если таковые имеются. Также время, при +превышении которого операция считается "медленной". + +## max_write_iodepth + +- Тип: целое число +- Значение по умолчанию: 128 + +Максимальное число одновременных клиентских операций записи на один OSD. +Операции, превышающие этот лимит, не исполняются сразу, а сохраняются во +временной очереди. + +## min_flusher_count + +- Тип: целое число +- Значение по умолчанию: 1 + +Flusher - это микро-поток (корутина), которая копирует данные из журнала в +основную область устройства данных. Их число настраивается динамически между +минимальным и максимальным значением. Этот параметр задаёт минимальное число. + +## max_flusher_count + +- Тип: целое число +- Значение по умолчанию: 256 + +Максимальное число микро-потоков очистки журнала (см. выше min_flusher_count). + +## inmemory_metadata + +- Тип: булево (да/нет) +- Значение по умолчанию: true + +Данный параметр заставляет Vitastor всегда держать область метаданных диска +в памяти. Это нужно, чтобы избегать дополнительных операций чтения с диска +при записи. Размер области метаданных на данный момент составляет примерно +224 МБ на 1 ТБ данных. При включении потребление памяти снизится примерно +на эту величину, но при этом также снизится и производительность. В будущем, +после обновления схемы хранения метаданных, это ограничение, скорее всего, +будет ликвидировано. + +## inmemory_journal + +- Тип: булево (да/нет) +- Значение по умолчанию: true + +Данный параметр заставляет Vitastor всегда держать в памяти журналы OSD. +Отключение параметра, опять же, снижает потребление памяти, но ухудшает +производительность, так как для копирования данных из журнала в основную +область устройства OSD будут вынуждены читать их обратно с диска. Выигрыш +по памяти при этом обычно крайне низкий, так как для SSD OSD обычно +достаточно 16- или 32-мегабайтного журнала. Однако в теории отключение +параметра может оказаться полезным для гибридных OSD (HDD+SSD) с большими +журналами, расположенными на быстром по сравнению с HDD устройстве. + +## journal_sector_buffer_count + +- Тип: целое число +- Значение по умолчанию: 32 + +Максимальное число буферов, разрешённых для использования под записываемые +в журнал блоки метаданных. Единственная ситуация, в которой этот параметр +нужно менять - это если вы включаете journal_no_same_sector_overwrites. В +этом случае установите данный параметр, например, в 1024. + +## journal_no_same_sector_overwrites + +- Тип: булево (да/нет) +- Значение по умолчанию: false + +Включайте данную опцию для SSD вроде Intel D3-S4510 и D3-S4610, которые +ОЧЕНЬ не любят, когда ПО перезаписывает один и тот же сектор несколько раз +подряд. Такие SSD при многократной перезаписи одного и того же сектора +сильно замедляются - условно, с 25000 и более iops до 3000 iops. Когда +данная опция установлена, Vitastor всегда переходит к следующему сектору +журнала после записи вместо потенциально повторной перезаписи того же +самого сектора. + +Почти все другие SSD (99% моделей) не требуют данной опции. + +## throttle_small_writes + +- Тип: булево (да/нет) +- Значение по умолчанию: false + +Разрешить мягкое ограничение скорости журналируемой записи. Полезно для +гибридных OSD с быстрыми устройствами метаданных и медленными устройствами +данных. Идея заключается в том, что мелкие записи в этой ситуации могут +завершаться очень быстро, так как они изначально записываются на быстрое +журнальное устройство (SSD). Но перемещать их потом на основное медленное +устройство долго. Поэтому если OSD быстро примет от клиентов очень много +мелких операций записи, он быстро заполнит свой журнал, после чего +производительность записи резко упадёт практически до нуля. Ограничение +скорости записи призвано решить эту проблему с помощью искусственного +замедления операций записи на основании объёма свободного места в журнале. +Когда эта опция включена, производительность мелких операций записи будет +снижаться плавно, а не резко в момент окончательного заполнения журнала. + +## throttle_target_iops + +- Тип: целое число +- Значение по умолчанию: 100 + +Расчётное максимальное число ограничиваемых операций в секунду при условии +отсутствия свободного места в журнале. Устанавливайте приблизительно равным +максимальной производительности случайной записи ваших устройств данных +(HDD) в операциях в секунду. + +## throttle_target_mbs + +- Тип: целое число +- Значение по умолчанию: 100 + +Расчётный максимальный размер в МБ/с ограничиваемых операций в секунду при +условии отсутствия свободного места в журнале. Устанавливайте приблизительно +равным максимальной производительности линейной записи ваших устройств +данных (HDD). + +## throttle_target_parallelism + +- Тип: целое число +- Значение по умолчанию: 1 + +Расчётный максимальный параллелизм ограничиваемых операций в секунду при +условии отсутствия свободного места в журнале. Устанавливайте приблизительно +равным внутреннему параллелизму ваших устройств данных (1 для HDD, 4-8 +для SSD). + +## throttle_threshold_us + +- Тип: микросекунды +- Значение по умолчанию: 50 + +Минимальная применимая к ограничиваемым операциям задержка. Обычно не +требует изменений. + +## osd_memlock + +- Тип: булево (да/нет) +- Значение по умолчанию: false + +Блокировать всю память OSD с помощью mlockall, чтобы запретить её выгрузку в пространство подкачки. Требует достаточного значения ulimit -l (лимита заблокированной памяти). diff --git a/docs/config/pool.en.md b/docs/config/pool.en.md new file mode 100644 index 00000000..89f3294f --- /dev/null +++ b/docs/config/pool.en.md @@ -0,0 +1,197 @@ +[Documentation](../../README.md#documentation) → [Configuration](../config.en.md) → Pool configuration + +----- + +[Читать на русском](pool.ru.md) + +# Pool configuration + +Pool configuration is set in etcd key `/vitastor/config/pools` in the following +JSON format: + +``` +{ + "": { + "name": "", + ...other parameters... + } +} +``` + +- [name](#name) +- [scheme](#scheme) +- [pg_size](#pg_size) +- [parity_chunks](#parity_chunks) +- [pg_minsize](#pg_minsize) +- [pg_count](#pg_count) +- [failure_domain](#failure_domain) +- [max_osd_combinations](#max_osd_combinations) +- [pg_stripe_size](#pg_stripe_size) +- [root_node](#root_node) +- [osd_tags](#osd_tags) +- [primary_affinity_tags](#primary_affinity_tags) + +Examples: + +- [Replicated Pool](#replicated-pool) +- [Erasure-coded Pool](#erasure-coded-pool) + +# Parameters + +## name + +- Type: string +- Required + +Pool name. + +## scheme + +- Type: string +- Required +- One of: "replicated", "xor" or "jerasure" + +Redundancy scheme used for data in this pool. + +## pg_size + +- Type: integer +- Required + +Total number of disks for PGs of this pool - i.e., number of replicas for +replicated pools and number of data plus parity disks for EC/XOR pools. + +## parity_chunks + +- Type: integer + +Number of parity chunks for EC/XOR pools. For such pools, data will be lost +if you lose more than parity_chunks disks at once, so this parameter can be +equally described as FTT (number of failures to tolerate). + +Required for EC/XOR pools, ignored for replicated pools. + +## pg_minsize + +- Type: integer +- Required + +Number of available live disks for PGs of this pool to remain active. +That is, if it becomes impossible to place PG data on at least (pg_minsize) +OSDs, PG is deactivated for both read and write. So you know that a fresh +write always goes to at least (pg_minsize) OSDs (disks). + +FIXME: pg_minsize behaviour may be changed in the future to only make PGs +read-only instead of deactivating them. + +## pg_count + +- Type: integer +- Required + +Number of PGs for this pool. The value should be big enough for the monitor / +LP solver to be able to optimize data placement. + +"Enough" is usually around 64-128 PGs per OSD, i.e. you set pg_count for pool +to (total OSD count * 100 / pg_size). You can round it to the closest power of 2, +because it makes it easier to reduce or increase PG count later by dividing or +multiplying it by 2. + +In Vitastor, PGs are ephemeral, so you can change pool PG count anytime just +by overwriting pool configuration in etcd. Amount of the data affected by +rebalance will be smaller if the new PG count is a multiple of the old PG count +or vice versa. + +## failure_domain + +- Type: string +- Default: host + +Failure domain specification. Must be "host" or "osd" or refer to one of the +placement tree levels, defined in [placement_levels](monitor.en.md#placement_levels). + +Two replicas, or two parts in case of EC/XOR, of the same block of data are +never put on OSDs in the same failure domain (for example, on the same host). +So failure domain specifies the unit which failure you are protecting yourself +from. + +## max_osd_combinations + +- Type: integer +- Default: 10000 + +Vitastor data placement algorithm is based on the LP solver and OSD combinations +which are fed to it are generated ramdonly. This parameter specifies the maximum +number of combinations to generate when optimising PG placement. + +This parameter usually doesn't require to be changed. + +## pg_stripe_size + +- Type: integer +- Default: 0 + +Specifies the stripe size for this pool according to which images are split into +different PGs. Stripe size can't be smaller than [block_size](layout-cluster.en.md#block_size) +multiplied by (pg_size - parity_chunks) for EC/XOR pools, or 1 for replicated pools, +and the same value is used by default. + +This means first `pg_stripe_size = (block_size * (pg_size-parity_chunks))` bytes +of an image go to one PG, next `pg_stripe_size` bytes go to another PG and so on. + +Usually doesn't require to be changed separately from the block size. + +## root_node + +- Type: string + +Specifies the root node of the OSD tree to restrict this pool OSDs to. +Referenced root node must exist in /vitastor/config/node_placement. + +## osd_tags + +- Type: string or array of strings + +Specifies OSD tags to restrict this pool to. If multiple tags are specified, +only OSDs having all of these tags will be used for this pool. + +## primary_affinity_tags + +- Type: string or array of strings + +Specifies OSD tags to prefer putting primary OSDs in this pool to. +Note that for EC/XOR pools Vitastor always prefers to put primary OSD on one +of the OSDs containing a data chunk for a PG. + +# Examples + +## Replicated pool + +``` +{ + "1": { + "name":"testpool", + "scheme":"replicated", + "pg_size":2, + "pg_minsize":1, + "pg_count":256, + "failure_domain":"host" + } +} +``` + +## Erasure-coded pool + +``` +{ + "2": { + "name":"ecpool", + "scheme":"jerasure", + "pg_size":3, + "parity_chunks":1, + "pg_minsize":2, + "pg_count":256, + "failure_domain":"host" + } +} +``` diff --git a/docs/config/pool.ru.md b/docs/config/pool.ru.md new file mode 100644 index 00000000..e2359640 --- /dev/null +++ b/docs/config/pool.ru.md @@ -0,0 +1,195 @@ +[Документация](../../README-ru.md#документация) → [Конфигурация](../config.ru.md) → Конфигурация пулов + +----- + +[Read in English](pool.en.md) + +# Конфигурация пулов + +Настройки пулов задаются в ключе etcd `/vitastor/config/pools` в JSON-формате: + +``` +{ + "<Численный ID>": { + "name": "<имя>", + ...остальные параметры... + } +} +``` + +- [name](#name) +- [scheme](#scheme) +- [pg_size](#pg_size) +- [parity_chunks](#parity_chunks) +- [pg_minsize](#pg_minsize) +- [pg_count](#pg_count) +- [failure_domain](#failure_domain) +- [max_osd_combinations](#max_osd_combinations) +- [pg_stripe_size](#pg_stripe_size) +- [root_node](#root_node) +- [osd_tags](#osd_tags) +- [primary_affinity_tags](#primary_affinity_tags) + +Примеры: + +- [Реплицированный пул](#реплицированный-пул) +- [Пул с кодами коррекции ошибок 2+1](#пул-с-кодами-коррекции-ошибок) + +# Параметры + +## name + +- Тип: строка +- Обязательный + +Название пула. + +## scheme + +- Тип: строка +- Обязательный +- Возможные значения: "replicated", "xor" или "jerasure" + +Схема избыточности, используемая в данном пуле. + +## pg_size + +- Тип: целое число +- Обязательный + +Размер PG данного пула, т.е. число реплик для реплицированных пулов или +число дисков данных плюс дисков чётности для пулов EC/XOR. + +## parity_chunks + +- Тип: целое число + +Число дисков чётности для EC/XOR пулов. Иными словами, число дисков, при +одновременной потере которых данные будут потеряны. + +Игнорируется для реплицированных пулов, обязательно для EC/XOR. + +## pg_minsize + +- Тип: целое число +- Обязательный + +Число доступных дисков для PG данного пула, при котором PG остаются активны. +Если становится невозможно размещать новые данные в PG как минимум на pg_minsize +OSD, PG деактивируется на чтение и запись. Иными словами, всегда известно, +что новые блоки данных всегда записываются как минимум на pg_minsize дисков. + +FIXME: Поведение pg_minsize может быть изменено в будущем с полной деактивации +PG на перевод их в режим только для чтения. + +## pg_count + +- Тип: целое число +- Обязательный + +Число PG для данного пула. Число должно быть достаточно большим, чтобы монитор +мог равномерно распределить по ним данные. + +Обычно это означает примерно 64-128 PG на 1 OSD, т.е. pg_count можно устанавливать +равным (общему числу OSD * 100 / pg_size). Значение можно округлить до ближайшей +степени 2, чтобы потом было легче уменьшать или увеличивать число PG, умножая +или деля его на 2. + +PG в Vitastor эферемерны, то есть вы можете менять их число в любой момент, +просто перезаписывая конфигурацию пулов в etcd. Однако объём перемещения данных +при этом будет минимален, если новое число PG кратно старому (или наоборот). + +## failure_domain + +- Тип: строка +- По умолчанию: host + +Домен отказа для пула. Может быть равен "host" или "osd" или любому другому +уровню дерева OSD, задаваемому в настройке [placement_levels](monitor.ru.md#placement_levels). + +Смысл домена отказа в том, что 2 копии, или 2 части одного блока данных в случае +кодов коррекции ошибок, никогда не помещаются на OSD, принадлежащие одному домену отказа. +Иными словами, домен отказа - это то, от отказа чего вы защищаете себя избыточным +хранением. + +## max_osd_combinations + +- Тип: целое число +- По умолчанию: 10000 + +Алгоритм распределения данных Vitastor основан на решателе задачи линейного +программирования. При этом для снижения сложности задачи возможные комбинации OSD +генерируются случайно и ограничиваются количеством, равным значению этого параметра. + +Обычно данный параметр не требует изменений. + +## pg_stripe_size + +- Тип: целое число +- По умолчанию: 0 + +Данный параметр задаёт размер полосы "нарезки" образов на PG. Размер полосы не может +быть меньше, чем [block_size](layout-cluster.ru.md#block_size), умноженный на +(pg_size - parity_chunks) для EC-пулов или 1 для реплицированных пулов. То же +значение используется по умолчанию. + +Это означает, что по умолчанию первые `pg_stripe_size = (block_size * (pg_size-parity_chunks))` байт +образа помещаются в одну PG, следующие `pg_stripe_size` байт помещаются в другую +и т.п. + +Данный параметр обычно тоже не требует изменений. + +## root_node + +- Тип: строка + +Корневой узел дерева OSD для ограничения OSD, выбираемых для пула. Задаваемый +узел должен быть предварительно задан в /vitastor/config/node_placement. + +## osd_tags + +- Тип: строка или массив строк + +Теги OSD для ограничения OSD, выбираемых для пула. Если задаётся несколько тегов +массивом, то выбираются только OSD, у которых есть все эти теги. + +## primary_affinity_tags + +- Тип: строка или массив строк + +Теги OSD, по которым должны выбираться OSD, предпочитаемые в качестве первичных +для PG этого пула. Имейте в виду, что для EC-пулов Vitastor также всегда +предпочитает помещать первичный OSD на один из OSD с данными, а не с чётностью. + +# Примеры + +## Реплицированный пул + +``` +{ + "1": { + "name":"testpool", + "scheme":"replicated", + "pg_size":2, + "pg_minsize":1, + "pg_count":256, + "failure_domain":"host" + } +} +``` + +## Пул с кодами коррекции ошибок + +``` +{ + "2": { + "name":"ecpool", + "scheme":"jerasure", + "pg_size":3, + "parity_chunks":1, + "pg_minsize":2, + "pg_count":256, + "failure_domain":"host" + } +} +``` diff --git a/docs/config/src/common.en.md b/docs/config/src/common.en.md new file mode 100644 index 00000000..b39f28c5 --- /dev/null +++ b/docs/config/src/common.en.md @@ -0,0 +1,3 @@ +# Common Parameters + +These are the most common parameters which apply to all components of Vitastor. diff --git a/docs/config/src/common.ru.md b/docs/config/src/common.ru.md new file mode 100644 index 00000000..6d6d4987 --- /dev/null +++ b/docs/config/src/common.ru.md @@ -0,0 +1,3 @@ +# Общие параметры + +Это наиболее общие параметры, используемые всеми компонентами Vitastor. diff --git a/docs/params/common.yml b/docs/config/src/common.yml similarity index 100% rename from docs/params/common.yml rename to docs/config/src/common.yml diff --git a/docs/config/src/layout-cluster.en.md b/docs/config/src/layout-cluster.en.md new file mode 100644 index 00000000..527ff8d8 --- /dev/null +++ b/docs/config/src/layout-cluster.en.md @@ -0,0 +1,4 @@ +# Cluster-Wide Disk Layout Parameters + +These parameters apply to clients and OSDs, are fixed at the moment of OSD drive +initialization and can't be changed after it without losing data. diff --git a/docs/config/src/layout-cluster.ru.md b/docs/config/src/layout-cluster.ru.md new file mode 100644 index 00000000..2f02765b --- /dev/null +++ b/docs/config/src/layout-cluster.ru.md @@ -0,0 +1,4 @@ +# Дисковые параметры уровня кластера + +Данные параметры используются клиентами и OSD, задаются в момент инициализации +диска OSD и не могут быть изменены после этого без потери данных. diff --git a/docs/params/layout-cluster.yml b/docs/config/src/layout-cluster.yml similarity index 100% rename from docs/params/layout-cluster.yml rename to docs/config/src/layout-cluster.yml diff --git a/docs/config/src/layout-osd.en.md b/docs/config/src/layout-osd.en.md new file mode 100644 index 00000000..a6f897ef --- /dev/null +++ b/docs/config/src/layout-osd.en.md @@ -0,0 +1,4 @@ +# OSD Disk Layout Parameters + +These parameters apply to OSDs, are fixed at the moment of OSD drive +initialization and can't be changed after it without losing data. diff --git a/docs/config/src/layout-osd.ru.md b/docs/config/src/layout-osd.ru.md new file mode 100644 index 00000000..01a26828 --- /dev/null +++ b/docs/config/src/layout-osd.ru.md @@ -0,0 +1,5 @@ +# Дисковые параметры OSD + +Данные параметры используются только OSD и, также как и общекластерные +дисковые параметры, задаются в момент инициализации дисков OSD и не могут быть +изменены после этого без потери данных. diff --git a/docs/params/layout-osd.yml b/docs/config/src/layout-osd.yml similarity index 92% rename from docs/params/layout-osd.yml rename to docs/config/src/layout-osd.yml index 57a63e07..6f94ff6d 100644 --- a/docs/params/layout-osd.yml +++ b/docs/config/src/layout-osd.yml @@ -44,16 +44,17 @@ - name: journal_size type: int info: | - Journal size in bytes. Doesn't have to be large, 16-32 MB is usually fine. - By default, the whole journal device will be used for the journal. You must - set it to some value manually (or use make-osd.sh) if you colocate the - journal with data or metadata. + Journal size in bytes. By default, all available space between journal_offset + and data_offset, meta_offset or the end of the journal device is used. + Large journals aren't needed in SSD-only setups, 32 MB is always enough. + In SSD+HDD setups it is beneficial to use larger journals (for example, 1 GB) + and enable [throttle_small_writes](osd.en.md#throttle_small_writes). info_ru: | - Размер журнала в байтах. Большим быть не обязан, 16-32 МБ обычно достаточно. - По умолчанию для журнала используется всё устройство журнала. Если же вы - размещаете журнал на устройстве данных или метаданных, то вы должны - установить эту опцию в какое-то значение сами (или использовать скрипт - make-osd.sh). + Размер журнала в байтах. По умолчанию для журнала используется всё доступное + место между journal_offset и data_offset, meta_offset или концом диска. + В SSD-кластерах большие журналы не нужны, достаточно 32 МБ. В гибридных + (SSD+HDD) кластерах осмысленно использовать больший размер журнал (например, 1 ГБ) + и включить [throttle_small_writes](osd.ru.md#throttle_small_writes). - name: meta_offset type: int default: 0 diff --git a/docs/config/src/make.js b/docs/config/src/make.js new file mode 100755 index 00000000..d0db1104 --- /dev/null +++ b/docs/config/src/make.js @@ -0,0 +1,120 @@ +#!/usr/bin/nodejs + +const fs = require('fs'); +const yaml = require('yaml'); + +const L = { + en: { + Documentation: 'Documentation', + Configuration: 'Configuration', + Crossref: 'Read in English', + toc_root: '[Documentation](../README.md#documentation)', + toc_intro: 'Introduction', + toc_installation: 'Installation', + toc_config: '[Configuration](../config.en.md)', + toc_usage: 'Usage', + toc_performance: 'Performance', + }, + ru: { + Documentation: 'Документация', + Configuration: 'Конфигурация', + Type: 'Тип', + Default: 'Значение по умолчанию', + Minimum: 'Минимальное значение', + Crossref: 'Читать на русском', + toc_root: '[Документация](../README-ru.md#документация)', + toc_intro: 'Введение', + toc_installation: 'Установка', + toc_config: '[Конфигурация](../config.ru.md)', + toc_usage: 'Использование', + toc_performance: 'Производительность', + }, +}; +const types = { + en: { + string: 'string', + bool: 'boolean', + int: 'integer', + sec: 'seconds', + ms: 'milliseconds', + us: 'microseconds', + }, + ru: { + string: 'строка', + bool: 'булево (да/нет)', + int: 'целое число', + sec: 'секунды', + ms: 'миллисекунды', + us: 'микросекунды', + }, +}; +const params_files = fs.readdirSync(__dirname) + .filter(f => f.substr(-4) == '.yml') + .map(f => f.substr(0, f.length-4)); + +for (const file of params_files) +{ + const cfg = yaml.parse(fs.readFileSync(__dirname+'/'+file+'.yml', { encoding: 'utf-8' })); + for (const lang in types) + { + let out = '\n'; + for (const c of cfg) + { + out += `\n- [${c.name}](#${c.name})`; + } + for (const c of cfg) + { + out += `\n\n## ${c.name}\n\n`; + out += `- ${L[lang]['Type'] || 'Type'}: ${c["type_"+lang] || types[lang][c.type] || c.type}\n`; + if (c.default !== undefined) + out += `- ${L[lang]['Default'] || 'Default'}: ${c.default}\n`; + if (c.min !== undefined) + out += `- ${L[lang]['Minimum'] || 'Minimum'}: ${c.min}\n`; + out += `\n`+(c["info_"+lang] || c["info"]).replace(/\s+$/, ''); + } + const head = fs.readFileSync(__dirname+'/'+file+'.'+lang+'.md', { encoding: 'utf-8' }); + out = head.replace(/\s+$/, '')+out+"\n"; + fs.writeFileSync(__dirname+'/../'+file+'.'+lang+'.md', out); + } +} + +// Add "Read in..." to all other documentation files + +for (const file of find_files(__dirname+'/../..', name => name.substr(-3) == '.md' && !/config\/src\//.exec(name))) +{ + const m = /^(?:(.*?)\/)?([^\/]+)\.([^\.]+)\.[^\.]+$/.exec(file); + if (!m) + continue; + const [ , subdir, filename, lang ] = m; + if (!L[lang]) + continue; + let text = fs.readFileSync(__dirname+'/../../'+file, { encoding: 'utf-8' }); + const title = /(^|\n)# ([^\n]+)/.exec(text)[2]; + let read_in = Object.keys(L).filter(other => other != lang) + .map(other => `[${L[other].Crossref}](${filename}.${other}.md)`) + .join(' ')+'\n\n'; + read_in = L[lang]['toc_root'].replace(/\.\.\//, subdir ? '../../' : '../')+' → '+ + (subdir ? L[lang]['toc_'+subdir]+' → ' : '')+ + title+'\n\n-----\n\n'+ + read_in; + if (text.substr(0, read_in.length) != read_in) + { + fs.writeFileSync(__dirname+'/../../'+file, read_in + (text[0] == '#' ? text : text.replace(/^([\s\S]*?\n)?#/, '#'))); + } +} + +function find_files(dir, fn, subdir = '', res = []) +{ + for (const ent of fs.readdirSync(dir+'/'+subdir, { withFileTypes: true })) + { + if (ent.isDirectory()) + { + find_files(dir, fn, subdir ? subdir+'/'+ent.name : ent.name, res); + } + else if (fn(subdir ? subdir+'/'+ent.name : ent.name, ent)) + { + res.push(subdir ? subdir+'/'+ent.name : ent.name); + } + } + return res; +} diff --git a/docs/config/src/monitor.en.md b/docs/config/src/monitor.en.md new file mode 100644 index 00000000..8ed97a31 --- /dev/null +++ b/docs/config/src/monitor.en.md @@ -0,0 +1,3 @@ +# Monitor Parameters + +These parameters only apply to Monitors. diff --git a/docs/config/src/monitor.ru.md b/docs/config/src/monitor.ru.md new file mode 100644 index 00000000..a9976eef --- /dev/null +++ b/docs/config/src/monitor.ru.md @@ -0,0 +1,3 @@ +# Параметры мониторов + +Данные параметры используются только мониторами Vitastor. diff --git a/docs/params/monitor.yml b/docs/config/src/monitor.yml similarity index 100% rename from docs/params/monitor.yml rename to docs/config/src/monitor.yml diff --git a/docs/config/src/network.en.md b/docs/config/src/network.en.md new file mode 100644 index 00000000..44fc2d11 --- /dev/null +++ b/docs/config/src/network.en.md @@ -0,0 +1,4 @@ +# Network Protocol Parameters + +These parameters apply to clients and OSDs and affect network connection logic +between clients, OSDs and etcd. diff --git a/docs/config/src/network.ru.md b/docs/config/src/network.ru.md new file mode 100644 index 00000000..37826a86 --- /dev/null +++ b/docs/config/src/network.ru.md @@ -0,0 +1,4 @@ +# Параметры сетевого протокола + +Данные параметры используются клиентами и OSD и влияют на логику сетевого +взаимодействия между клиентами, OSD, а также etcd. diff --git a/docs/params/network.yml b/docs/config/src/network.yml similarity index 95% rename from docs/params/network.yml rename to docs/config/src/network.yml index 8ccf1818..009c9d96 100644 --- a/docs/params/network.yml +++ b/docs/config/src/network.yml @@ -35,15 +35,15 @@ default: true info: | Try to use RDMA for communication if it's available. Disable if you don't - want Vitastor to use RDMA. RDMA increases the performance, but TCP-only - clients can still talk to an RDMA-enabled cluster, so you don't need to - make sure that all clients support RDMA when enabling it. + want Vitastor to use RDMA. TCP-only clients can also talk to an RDMA-enabled + cluster, so disabling RDMA may be needed if clients have RDMA devices, + but they are not connected to the cluster. info_ru: | Пытаться использовать RDMA для связи при наличии доступных устройств. Отключите, если вы не хотите, чтобы Vitastor использовал RDMA. - RDMA улучшает производительность, но - Клиенты и клиентов and TCP-only clients in the cluster at the - same time - TCP-only clients are still able to use an RDMA-enabled cluster. + TCP-клиенты также могут работать с RDMA-кластером, так что отключать + RDMA может быть нужно только если у клиентов есть RDMA-устройства, + но они не имеют соединения с кластером Vitastor. - name: rdma_device type: string info: | diff --git a/docs/config/src/osd.en.md b/docs/config/src/osd.en.md new file mode 100644 index 00000000..a5c12355 --- /dev/null +++ b/docs/config/src/osd.en.md @@ -0,0 +1,4 @@ +# Runtime OSD Parameters + +These parameters only apply to OSDs, are not fixed at the moment of OSD drive +initialization and can be changed with an OSD restart. diff --git a/docs/config/src/osd.ru.md b/docs/config/src/osd.ru.md new file mode 100644 index 00000000..4ca2ca04 --- /dev/null +++ b/docs/config/src/osd.ru.md @@ -0,0 +1,5 @@ +# Изменяемые параметры OSD + +Данные параметры используются только OSD, но, в отличие от дисковых параметров, +не фиксируются в момент инициализации дисков OSD и могут быть изменены в любой +момент с перезапуском OSD. diff --git a/docs/params/osd.yml b/docs/config/src/osd.yml similarity index 99% rename from docs/params/osd.yml rename to docs/config/src/osd.yml index 60a9c5bc..bfa656b8 100644 --- a/docs/params/osd.yml +++ b/docs/config/src/osd.yml @@ -248,6 +248,8 @@ row and slow down significantly (from 25000+ iops to ~3000 iops). When this option is set, Vitastor will always move to the next sector of the journal after writing it instead of possibly overwriting it the second time. + + Most (99%) other SSDs don't need this option. info_ru: | Включайте данную опцию для SSD вроде Intel D3-S4510 и D3-S4610, которые ОЧЕНЬ не любят, когда ПО перезаписывает один и тот же сектор несколько раз @@ -256,6 +258,8 @@ данная опция установлена, Vitastor всегда переходит к следующему сектору журнала после записи вместо потенциально повторной перезаписи того же самого сектора. + + Почти все другие SSD (99% моделей) не требуют данной опции. - name: throttle_small_writes type: bool default: false diff --git a/docs/installation/kubernetes.en.md b/docs/installation/kubernetes.en.md new file mode 100644 index 00000000..3641ee0b --- /dev/null +++ b/docs/installation/kubernetes.en.md @@ -0,0 +1,20 @@ +[Documentation](../../README.md#documentation) → Installation → Kubernetes CSI + +----- + +[Читать на русском](kubernetes.ru.md) + +# Kubernetes CSI + +Vitastor has a CSI plugin for Kubernetes which supports RWO (and block RWX) volumes. + +To deploy it, take manifests from [csi/deploy/](../../csi/deploy/) directory, put your +Vitastor configuration in [001-csi-config-map.yaml](../../csi/deploy/001-csi-config-map.yaml), +configure storage class in [009-storage-class.yaml](../../csi/deploy/009-storage-class.yaml) +and apply all `NNN-*.yaml` manifests to your Kubernetes installation: + +``` +for i in ./???-*.yaml; do kubectl apply -f $i; done +``` + +After that you'll be able to create PersistentVolumes. See example in [csi/deploy/example-pvc.yaml](../../csi/deploy/example-pvc.yaml). diff --git a/docs/installation/kubernetes.ru.md b/docs/installation/kubernetes.ru.md new file mode 100644 index 00000000..51fa67fd --- /dev/null +++ b/docs/installation/kubernetes.ru.md @@ -0,0 +1,20 @@ +[Документация](../../README-ru.md#документация) → Установка → Kubernetes CSI + +----- + +[Read in English](kubernetes.en.md) + +# Kubernetes CSI + +У Vitastor есть CSI-плагин для Kubernetes, поддерживающий RWO, а также блочные RWX, тома. + +Для установки возьмите манифесты из директории [csi/deploy/](../csi/deploy/), поместите +вашу конфигурацию подключения к Vitastor в [csi/deploy/001-csi-config-map.yaml](../csi/deploy/001-csi-config-map.yaml), +настройте StorageClass в [csi/deploy/009-storage-class.yaml](../csi/deploy/009-storage-class.yaml) +и примените все `NNN-*.yaml` к вашей инсталляции Kubernetes. + +``` +for i in ./???-*.yaml; do kubectl apply -f $i; done +``` + +После этого вы сможете создавать PersistentVolume. Пример смотрите в файле [csi/deploy/example-pvc.yaml](../csi/deploy/example-pvc.yaml). diff --git a/docs/installation/openstack.en.md b/docs/installation/openstack.en.md new file mode 100644 index 00000000..d707bf09 --- /dev/null +++ b/docs/installation/openstack.en.md @@ -0,0 +1,40 @@ +[Documentation](../../README.md#documentation) → Installation → OpenStack + +----- + +[Читать на русском](openstack.ru.md) + +# OpenStack + +To enable Vitastor support in an OpenStack installation: + +- Install vitastor-client, patched QEMU and libvirt packages from Vitastor DEB or RPM repository +- Use `patches/nova-21.diff` or `patches/nova-23.diff` to patch your Nova installation. + Patch 21 fits Nova 21-22, patch 23 fits Nova 23-24. +- Install `patches/cinder-vitastor.py` as `..../cinder/volume/drivers/vitastor.py` +- Define a volume type in cinder.conf (see below) +- Block network access from VMs to Vitastor network (to OSDs and etcd), + because Vitastor doesn't support authentication +- Restart Cinder and Nova + +Cinder volume type configuration example: + +``` +[DEFAULT] +enabled_backends = lvmdriver-1, vitastor-testcluster +# ... + +[vitastor-testcluster] +volume_driver = cinder.volume.drivers.vitastor.VitastorDriver +volume_backend_name = vitastor-testcluster +image_volume_cache_enabled = True +volume_clear = none +vitastor_etcd_address = 192.168.7.2:2379 +vitastor_etcd_prefix = +vitastor_config_path = /etc/vitastor/vitastor.conf +vitastor_pool_id = 1 +image_upload_use_cinder_backend = True +``` + +To put Glance images in Vitastor, use [https://docs.openstack.org/cinder/pike/admin/blockstorage-volume-backed-image.html](volume-backed images), +although the support has not been verified yet. diff --git a/docs/installation/openstack.ru.md b/docs/installation/openstack.ru.md new file mode 100644 index 00000000..292f2a9f --- /dev/null +++ b/docs/installation/openstack.ru.md @@ -0,0 +1,40 @@ +[Документация](../../README-ru.md#документация) → Установка → OpenStack + +----- + +[Read in English](openstack.en.md) + +# OpenStack + +Чтобы подключить Vitastor к OpenStack: + +- Установите пакеты vitastor-client, libvirt и QEMU из DEB или RPM репозитория Vitastor +- Примените патч `patches/nova-21.diff` или `patches/nova-23.diff` к вашей инсталляции Nova. + nova-21.diff подходит для Nova 21-22, nova-23.diff подходит для Nova 23-24. +- Скопируйте `patches/cinder-vitastor.py` в инсталляцию Cinder как `cinder/volume/drivers/vitastor.py` +- Создайте тип томов в cinder.conf (см. ниже) +- Обязательно заблокируйте доступ от виртуальных машин к сети Vitastor (OSD и etcd), т.к. Vitastor (пока) не поддерживает аутентификацию +- Перезапустите Cinder и Nova + +Пример конфигурации Cinder: + +``` +[DEFAULT] +enabled_backends = lvmdriver-1, vitastor-testcluster +# ... + +[vitastor-testcluster] +volume_driver = cinder.volume.drivers.vitastor.VitastorDriver +volume_backend_name = vitastor-testcluster +image_volume_cache_enabled = True +volume_clear = none +vitastor_etcd_address = 192.168.7.2:2379 +vitastor_etcd_prefix = +vitastor_config_path = /etc/vitastor/vitastor.conf +vitastor_pool_id = 1 +image_upload_use_cinder_backend = True +``` + +Чтобы помещать в Vitastor Glance-образы, нужно использовать +[https://docs.openstack.org/cinder/pike/admin/blockstorage-volume-backed-image.html](образы на основе томов Cinder), +однако, поддержка этой функции ещё не проверялась. diff --git a/docs/installation/packages.en.md b/docs/installation/packages.en.md new file mode 100644 index 00000000..ad85f40d --- /dev/null +++ b/docs/installation/packages.en.md @@ -0,0 +1,44 @@ +[Documentation](../../README.md#documentation) → Installation → Packages + +----- + +[Читать на русском](packages.ru.md) + +# Packages + +## Debian + +- Trust Vitastor package signing key: + `wget -q -O - https://vitastor.io/debian/pubkey | sudo apt-key add -` +- Add Vitastor package repository to your /etc/apt/sources.list: + - Debian 11 (Bullseye/Sid): `deb https://vitastor.io/debian bullseye main` + - Debian 10 (Buster): `deb https://vitastor.io/debian buster main` +- For Debian 10 (Buster) also enable backports repository: + `deb http://deb.debian.org/debian buster-backports main` +- Install packages: `apt update; apt install vitastor lp-solve etcd linux-image-amd64 qemu` + +## CentOS + +- Add Vitastor package repository: + - CentOS 7: `yum install https://vitastor.io/rpms/centos/7/vitastor-release-1.0-1.el7.noarch.rpm` + - CentOS 8: `dnf install https://vitastor.io/rpms/centos/8/vitastor-release-1.0-1.el8.noarch.rpm` +- Enable EPEL: `yum/dnf install epel-release` +- Enable additional CentOS repositories: + - CentOS 7: `yum install centos-release-scl` + - CentOS 8: `dnf install centos-release-advanced-virtualization` +- Enable elrepo-kernel: + - CentOS 7: `yum install https://www.elrepo.org/elrepo-release-7.el7.elrepo.noarch.rpm` + - CentOS 8: `dnf install https://www.elrepo.org/elrepo-release-8.el8.elrepo.noarch.rpm` +- Install packages: `yum/dnf install vitastor lpsolve etcd kernel-ml qemu-kvm` + +## Installation requirements + +- Linux kernel 5.4 or newer, for io_uring support. 5.8 or later is highly + recommended because io_uring is a relatively new technology and there is + at least one bug which reproduces with io_uring and HP SmartArray + controllers in 5.4 +- liburing 0.4 or newer +- lp_solve +- etcd 3.4.15 or newer. Earlier versions won't work because of various bugs, + for example [#12402](https://github.com/etcd-io/etcd/pull/12402). +- node.js 10 or newer diff --git a/docs/installation/packages.ru.md b/docs/installation/packages.ru.md new file mode 100644 index 00000000..8ee46d35 --- /dev/null +++ b/docs/installation/packages.ru.md @@ -0,0 +1,43 @@ +[Документация](../../README-ru.md#документация) → Установка → Установка из пакетов + +----- + +[Read in English](packages.en.md) + +# Установка из пакетов + +## Debian + +- Добавьте ключ репозитория Vitastor: + `wget -q -O - https://vitastor.io/debian/pubkey | sudo apt-key add -` +- Добавьте репозиторий Vitastor в /etc/apt/sources.list: + - Debian 11 (Bullseye/Sid): `deb https://vitastor.io/debian bullseye main` + - Debian 10 (Buster): `deb https://vitastor.io/debian buster main` +- Для Debian 10 (Buster) также включите репозиторий backports: + `deb http://deb.debian.org/debian buster-backports main` +- Установите пакеты: `apt update; apt install vitastor lp-solve etcd linux-image-amd64 qemu` + +## CentOS + +- Добавьте в систему репозиторий Vitastor: + - CentOS 7: `yum install https://vitastor.io/rpms/centos/7/vitastor-release-1.0-1.el7.noarch.rpm` + - CentOS 8: `dnf install https://vitastor.io/rpms/centos/8/vitastor-release-1.0-1.el8.noarch.rpm` +- Включите EPEL: `yum/dnf install epel-release` +- Включите дополнительные репозитории CentOS: + - CentOS 7: `yum install centos-release-scl` + - CentOS 8: `dnf install centos-release-advanced-virtualization` +- Включите elrepo-kernel: + - CentOS 7: `yum install https://www.elrepo.org/elrepo-release-7.el7.elrepo.noarch.rpm` + - CentOS 8: `dnf install https://www.elrepo.org/elrepo-release-8.el8.elrepo.noarch.rpm` +- Установите пакеты: `yum/dnf install vitastor lpsolve etcd kernel-ml qemu-kvm` + +## Установочные требования + +- Ядро Linux 5.4 или новее, для поддержки io_uring. Рекомендуется даже 5.8, + так как io_uring - относительно новый интерфейс и в версиях до 5.8 встречались + некоторые баги, например, зависание с io_uring и контроллером HP SmartArray +- liburing 0.4 или новее +- lp_solve +- etcd 3.4.15 или новее. Более старые версии не будут работать из-за разных багов, + например, [#12402](https://github.com/etcd-io/etcd/pull/12402). +- node.js 10 или новее diff --git a/docs/installation/proxmox.en.md b/docs/installation/proxmox.en.md new file mode 100644 index 00000000..c9e3363b --- /dev/null +++ b/docs/installation/proxmox.en.md @@ -0,0 +1,39 @@ +[Documentation](../../README.md#documentation) → Installation → Proxmox VE + +----- + +[Читать на русском](proxmox.ru.md) + +# Proxmox VE + +To enable Vitastor support in Proxmox Virtual Environment (6.4 and 7.1 are supported): + +- Add the corresponding Vitastor Debian repository into sources.list on Proxmox hosts + (buster for 6.4, bullseye for 7.1) +- Install vitastor-client, pve-qemu-kvm, pve-storage-vitastor (* or see note) packages from Vitastor repository +- Define storage in `/etc/pve/storage.cfg` (see below) +- Block network access from VMs to Vitastor network (to OSDs and etcd), + because Vitastor doesn't support authentication +- Restart pvedaemon: `systemctl restart pvedaemon` + +`/etc/pve/storage.cfg` example (the only required option is vitastor_pool, all others +are listed below with their default values): + +``` +vitastor: vitastor + # pool to put new images into + vitastor_pool testpool + # path to the configuration file + vitastor_config_path /etc/vitastor/vitastor.conf + # etcd address(es), required only if missing in the configuration file + vitastor_etcd_address 192.168.7.2:2379/v3 + # prefix for keys in etcd + vitastor_etcd_prefix /vitastor + # prefix for images + vitastor_prefix pve/ + # use NBD mounter (only required for containers) + vitastor_nbd 0 +``` + +\* Note: you can also manually copy [patches/PVE_VitastorPlugin.pm](patches/PVE_VitastorPlugin.pm) to Proxmox hosts +as `/usr/share/perl5/PVE/Storage/Custom/VitastorPlugin.pm` instead of installing pve-storage-vitastor. diff --git a/docs/installation/proxmox.ru.md b/docs/installation/proxmox.ru.md new file mode 100644 index 00000000..58cf4c80 --- /dev/null +++ b/docs/installation/proxmox.ru.md @@ -0,0 +1,39 @@ +[Документация](../../README-ru.md#документация) → Установка → Proxmox + +----- + +[Read in English](proxmox.en.md) + +# Proxmox + +Чтобы подключить Vitastor к Proxmox Virtual Environment (поддерживаются версии 6.4 и 7.1): + +- Добавьте соответствующий Debian-репозиторий Vitastor в sources.list на хостах Proxmox + (buster для 6.4, bullseye для 7.1) +- Установите пакеты vitastor-client, pve-qemu-kvm, pve-storage-vitastor (* или см. сноску) из репозитория Vitastor +- Определите тип хранилища в `/etc/pve/storage.cfg` (см. ниже) +- Обязательно заблокируйте доступ от виртуальных машин к сети Vitastor (OSD и etcd), т.к. Vitastor (пока) не поддерживает аутентификацию +- Перезапустите демон Proxmox: `systemctl restart pvedaemon` + +Пример `/etc/pve/storage.cfg` (единственная обязательная опция - vitastor_pool, все остальные +перечислены внизу для понимания значений по умолчанию): + +``` +vitastor: vitastor + # Пул, в который будут помещаться образы дисков + vitastor_pool testpool + # Путь к файлу конфигурации + vitastor_config_path /etc/vitastor/vitastor.conf + # Адрес(а) etcd, нужны, только если не указаны в vitastor.conf + vitastor_etcd_address 192.168.7.2:2379/v3 + # Префикс ключей метаданных в etcd + vitastor_etcd_prefix /vitastor + # Префикс имён образов + vitastor_prefix pve/ + # Монтировать образы через NBD прокси, через ядро (нужно только для контейнеров) + vitastor_nbd 0 +``` + +\* Примечание: вместо установки пакета pve-storage-vitastor вы можете вручную скопировать файл +[patches/PVE_VitastorPlugin.pm](patches/PVE_VitastorPlugin.pm) на хосты Proxmox как +`/usr/share/perl5/PVE/Storage/Custom/VitastorPlugin.pm`. diff --git a/docs/installation/source.en.md b/docs/installation/source.en.md new file mode 100644 index 00000000..f6445beb --- /dev/null +++ b/docs/installation/source.en.md @@ -0,0 +1,65 @@ +[Documentation](../../README.md#documentation) → Installation → Building from Source + +----- + +[Читать на русском](source.ru.md) + +# Building from Source + +- [Requirements](#requirements) +- [Basic instructions](#basic-instructions) +- [QEMU Driver](#qemu-driver) + +## Requirements + +- gcc and g++ 8 or newer, clang 10 or newer, or other compiler with C++11 plus + designated initializers support from C++20 +- CMake +- liburing, jerasure headers +- tcmalloc (google-perftools-dev) + +## Basic instructions + +Download source, for example using git: `git clone --recurse-submodules https://yourcmc.ru/git/vitalif/vitastor/` + +Get `fio` source and symlink it into `/fio`. If you don't want to build fio engine, +you can disable it by passing `-DWITH_FIO=no` to cmake. + +Build and install Vitastor: + +``` +cd vitastor +mkdir build +cd build +cmake .. && make -j8 install +``` + +## QEMU Driver + +It's recommended to build the QEMU driver (qemu_driver.c) in-tree, as a part of +QEMU build process. To do that: +- Install vitastor client library headers (from source or from vitastor-client-dev package) +- Take a corresponding patch from `patches/qemu-*-vitastor.patch` and apply it to QEMU source +- Copy `src/qemu_driver.c` to QEMU source directory as `block/block-vitastor.c` +- Build QEMU as usual + +But it is also possible to build it out-of-tree. To do that: +- Get QEMU source, begin to build it, stop the build and copy headers: + - `/include` → `/qemu/include` + - Debian: + * Use qemu packages from the main repository + * `/b/qemu/config-host.h` → `/qemu/b/qemu/config-host.h` + * `/b/qemu/qapi` → `/qemu/b/qemu/qapi` + - CentOS 8: + * Use qemu packages from the Advanced-Virtualization repository. To enable it, run + `yum install centos-release-advanced-virtualization.noarch` and then `yum install qemu` + * `/config-host.h` → `/qemu/b/qemu/config-host.h` + * For QEMU 3.0+: `/qapi` → `/qemu/b/qemu/qapi` + * For QEMU 2.0+: `/qapi-types.h` → `/qemu/b/qemu/qapi-types.h` + - `config-host.h` and `qapi` are required because they contain generated headers +- Configure Vitastor with `WITH_QEMU=yes` and, if you're on RHEL, also with `QEMU_PLUGINDIR=qemu-kvm`: + `cmake .. -DWITH_QEMU=yes`. +- After that, Vitastor will build `block-vitastor.so` during its build process. +- This way you can use the driver even with unmodified QEMU, but you'll need to set + environment variable `LD_PRELOAD=/usr/lib/x86_64-linux-gnu/qemu/block-vitastor.so` + and Vitastor disks won't work in QAPI and in "new" JSON syntax `-blockdev` in this case. diff --git a/docs/installation/source.ru.md b/docs/installation/source.ru.md new file mode 100644 index 00000000..4ebc4316 --- /dev/null +++ b/docs/installation/source.ru.md @@ -0,0 +1,68 @@ +[Документация](../../README-ru.md#документация) → Установка → Сборка из исходных кодов + +----- + +[Read in English](source.en.md) + +# Сборка из исходных кодов + +- [Требования](#требования) +- [Базовая инструкция](#базовая-инструкция) +- [Драйвер QEMU](#драйвер-qemu) + +## Требования + +- gcc и g++ >= 8, либо clang >= 10, либо другой компилятор с поддержкой C++11 плюс + назначенных инициализаторов (designated initializers) из C++20 +- CMake +- Заголовки liburing, jerasure +- tcmalloc (google-perftools-dev) + +## Базовая инструкция + +Скачайте исходные коды, например, из git: `git clone --recurse-submodules https://yourcmc.ru/git/vitalif/vitastor/` + +Скачайте исходные коды пакета `fio`, распакуйте их и создайте символическую ссылку на них +в директории исходников Vitastor: `/fio`. Либо, если вы не хотите собирать плагин fio, +его можно исключить из сборки путём передачи `-DWITH_FIO=no` в cmake. + +Собрать и установить Vitastor: + +``` +cd vitastor +mkdir build +cd build +cmake .. && make -j8 install +``` + +## Драйвер QEMU + +Драйвер QEMU (qemu_driver.c) рекомендуется собирать вместе с самим QEMU. Для этого: +- Установите заголовки клиентской библиотеки Vitastor (из исходников или из пакета vitastor-client-dev) +- Возьмите соответствующий патч из `patches/qemu-*-vitastor.patch` и примените его к исходникам QEMU +- Скопируйте [src/qemu_driver.c](../../src/qemu_driver.c) в директорию исходников QEMU как `block/block-vitastor.c` +- Соберите QEMU как обычно + +Однако в целях отладки драйвер также можно собирать отдельно от QEMU. Для этого: +- Установите QEMU, возьмите исходные коды установленного пакета, начните его пересборку, + через некоторое время остановите её и скопируйте следующие заголовки: + - `/include` → `/qemu/include` + - Debian: + * Берите qemu из основного репозитория + * `/b/qemu/config-host.h` → `/qemu/b/qemu/config-host.h` + * `/b/qemu/qapi` → `/qemu/b/qemu/qapi` + - CentOS 8: + * Берите qemu из репозитория Advanced-Virtualization. Чтобы включить его, запустите + `yum install centos-release-advanced-virtualization.noarch` и далее `yum install qemu` + * `/config-host.h` → `/qemu/b/qemu/config-host.h` + * Для QEMU 3.0+: `/qapi` → `/qemu/b/qemu/qapi` + * Для QEMU 2.0+: `/qapi-types.h` → `/qemu/b/qemu/qapi-types.h` + - `config-host.h` и `qapi` нужны, т.к. в них содержатся автогенерируемые заголовки +- Сконфигурируйте cmake Vitastor с `WITH_QEMU=yes` (`cmake .. -DWITH_QEMU=yes`) и, если вы + используете RHEL-подобый дистрибутив, также с `QEMU_PLUGINDIR=qemu-kvm`. +- После этого в процессе сборки Vitastor также будет собираться подходящий для вашей + версии QEMU `block-vitastor.so`. +- Таким образом можно использовать драйвер даже с немодифицированным QEMU, но в этом случае + диски Vitastor не будут работать через QAPI и через JSON-синтаксис `-blockdev`, а также + потребуется устанавливать переменную окружения + `LD_PRELOAD=/usr/lib/x86_64-linux-gnu/qemu/block-vitastor.so`. diff --git a/docs/intro/architecture.en.md b/docs/intro/architecture.en.md new file mode 100644 index 00000000..147536a6 --- /dev/null +++ b/docs/intro/architecture.en.md @@ -0,0 +1,91 @@ +[Documentation](../../README.md#documentation) → Introduction → Architecture + +----- + +[Читать на русском](architecture.ru.md) + +# Architecture + +- [Basic concepts](#basic-concepts) +- [Similarities to Ceph](#similarities-to-ceph) +- [Differences from Ceph](#differences-from-ceph) +- [Implementation Principles](#implementation-principles) + +## Basic concepts + +- OSD (Object Storage Daemon) is a process that stores data and serves read/write requests. +- PG (Placement Group) is a "shard" of the cluster, group of data stored on one set of replicas. +- Pool is a container for data that has equal redundancy scheme and placement rules. +- Monitor is a separate daemon that watches cluster state and handles failures. +- Failure Domain is a group of OSDs that you allow to fail. It's "host" by default. +- Placement Tree groups OSDs in a hierarchy to later split them into Failure Domains. + +## Similarities to Ceph + +- Vitastor also has Pools, PGs, OSDs, Monitors, Failure Domains, Placement Tree: +- Vitastor also distributes every image data across the whole cluster. +- Vitastor is also transactional. Even though there's a "lazy fsync mode" which + doesn't implicitly flush every operation to disks, every write to the cluster is atomic. +- OSDs also have journal and metadata and they can also be put on separate drives. +- Just like in Ceph, client library attempts to recover from any cluster failure so + you can basically reboot the whole cluster and only pause, but not crash, your clients. + +## Differences from Ceph + +- Vitastor's primary focus is on SSDs: SSD-only and SSD+HDD clusters. +- The basic layer of Vitastor is block storage with fixed-size blocks, not object storage with + rich semantics like in Ceph (RADOS). +- PGs are ephemeral in Vitastor. This means that they aren't stored on data disks and only exist + in memory while OSDs are running. +- Vitastor OSD is (and will always be) single-threaded. If you want to dedicate more than 1 core + per drive you should run multiple OSDs each on a different partition of the drive. + Vitastor isn't CPU-hungry though (as opposed to Ceph), so 1 core is sufficient in a lot of cases. +- Metadata is always kept in memory which removes the need for extra disk reads. Metadata size + depends linearly on drive capacity and data store block size which is 128 KB by default. + With 128 KB blocks metadata takes around 512 MB per 1 TB (which is still less than Ceph wants). + Journal is also kept in memory by default, but in SSD-only clusters it's only 32 MB, and in SSD+HDD + clusters, where it's beneficial to increase it, [inmemory_journal](docs/config/osd.en.md#inmemory_journal) can be disabled. +- Vitastor storage layer doesn't have internal copy-on-write or redirect-write. I know that maybe + it's possible to create a good copy-on-write storage, but it's much harder and makes performance + less deterministic, so CoW isn't used in Vitastor. +- There's a "lazy fsync" mode which allows to batch writes before flushing them to the disk. + This allows to use Vitastor with desktop SSDs, but still lowers performance due to additional + network roundtrips, so use server SSDs with capacitor-based power loss protection + ("Advanced Power Loss Protection") for best performance. +- Recovery process is per-object (per-block), not per-PG. Also there are no PGLOGs. +- Monitors don't store data. Cluster configuration and state is stored in etcd in simple human-readable + JSON structures. Monitors only watch cluster state and handle data movement. + Thus Vitastor's Monitor isn't a critical component of the system and is more similar to Ceph's Manager. + Vitastor's Monitor is implemented in node.js. +- PG distribution isn't based on consistent hashes. All PG mappings are stored in etcd. + Rebalancing PGs between OSDs is done by mathematical optimization - data distribution problem + is reduced to a linear programming problem and solved by lp_solve. This allows for almost + perfect (96-99% uniformity compared to Ceph's 80-90%) data distribution in most cases, ability + to map PGs by hand without breaking rebalancing logic, reduced OSD peer-to-peer communication + (on average, OSDs have fewer peers) and less data movement. It also probably has a drawback - + this method may fail in very large clusters, but up to several hundreds of OSDs it's perfectly fine. + It's also easy to add consistent hashes in the future if something proves their necessity. +- There's no separate CRUSH layer. You select pool redundancy scheme, placement root, failure domain + and so on directly in pool configuration. + +## Implementation Principles + +- I like architecturally simple solutions. Vitastor is and will always be designed + exactly like that. +- I also like reinventing the wheel to some extent, like writing my own HTTP client + for etcd interaction instead of using prebuilt libraries, because in this case + I'm confident about what my code does and what it doesn't do. +- I don't care about C++ "best practices" like RAII or proper inheritance or usage of + smart pointers or whatever and I don't intend to change my mind, so if you're here + looking for ideal reference C++ code, this probably isn't the right place. +- I like node.js better than any other dynamically-typed language interpreter + because it's faster than any other interpreter in the world, has neutral C-like + syntax and built-in event loop. That's why Monitor is implemented in node.js. + +## Known Problems + +- Deleting images in a degraded cluster may currently lead to objects reappearing + after dead OSDs come back, and in case of erasure-coded pools, they may even + reappear as incomplete. Just repeat the removal request again in this case. + This problem will be fixed in the nearest future, the fix is already implemented + in the "epoch-deletions" branch. diff --git a/docs/intro/architecture.ru.md b/docs/intro/architecture.ru.md new file mode 100644 index 00000000..e94e247a --- /dev/null +++ b/docs/intro/architecture.ru.md @@ -0,0 +1,208 @@ +[Документация](../../README-ru.md#документация) → Введение → Архитектура + +----- + +[Read in English](architecture.en.md) + +# Архитектура + +Краткое описание архитектуры Vitastor. + +- [Серверные компоненты](#серверные-компоненты) +- [Базовые понятия](#базовые-понятия) +- [Клиентские компоненты](#клиентские-компоненты) +- [Общий процесс записи и чтения](#общий-процесс-записи-и-чтения) + - [Особенности обработки запросов](#особенности-обработки-запросов) +- [Схожесть с Ceph](#схожесть-с-ceph) +- [Отличия от Ceph](#отличия-от-ceph) +- [Принципы разработки](#принципы-разработки) + +## Серверные компоненты + +- **OSD** (Object Storage Daemon) — процесс, который непосредственно работает с диском, пишет и читает данные. + Один OSD управляет одним диском (или разделом). OSD общаются с etcd и друг с другом — от etcd они + получают состояние кластера, а друг другу передают запросы записи и чтения вторичных копий данных. +- **etcd** — кластерная key/value база данных, используется для хранения настроек и верхнеуровневого + состояния кластера, а также предотвращения разделения сознания. Блоки данных в etcd не хранятся, + в обработке клиентских запросов чтения и записи etcd не участвует. +- **Монитор** — отдельный демон на node.js, рассчитывающий необходимые изменения в конфигурацию + кластера, сохраняющий эту информацию в etcd и таким образом командующий OSD применить эти изменения. + Также агрегирует статистику. Контактирует только с etcd, OSD с монитором не общаются. + +## Базовые понятия + +- **Пул (Pool)** — контейнер для данных, имеющих одну и ту же схему избыточности и правила распределения по OSD. +- **PG (Placement Group)** — "шард", единица деления пулов в кластере, которой назначается свой набор + OSD для хранения данных (копий или частей объектов). +- **Домен отказа (Failure Domain)** — группа OSD, одновременное падение которых рассматривается + как вероятное. По умолчанию это "host" (сервер). +- **Дерево распределения** (Placement Tree, в Ceph CRUSH Tree) — иерархическая группировка OSD + в узлы, которые далее можно использовать как домены отказа. + +## Клиентские компоненты + +- **Клиентская библиотека** — инкапсулирует логику на стороне клиента. Соединяются с etcd и со всеми OSD, + от etcd получают состояние кластера, команды чтения и записи отправляют на все OSD напрямую. + В силу архитектуры все отдельные блоки данных (по умолчанию по 128 КБ) располагается на разных + OSD, но клиент устроен так, что всегда точно знает, к какому OSD обращаться, и подключается + к нему напрямую. + +На базе клиентской библиотеки реализованы все остальные клиенты: + +- **vitastor-cli** — утилита командной строки для управления кластером. В данный момент позволяет + просматривать общее состояние кластера и управлять образами — т.е. создавать, менять и удалять + виртуальные диски, их снимки и клоны. +- **Драйвер QEMU** — подключаемый модуль QEMU, позволяющий QEMU/KVM виртуальным машинам работать + с виртуальными дисками Vitastor напрямую из пространства пользователя с помощью клиентской + библиотеки, без необходимости отображения дисков в виде блочных устройств. +- **vitastor-nbd** — утилита, позволяющая монтировать образы Vitastor в виде блочных устройств + с помощью NBD (Network Block Device), на самом деле скорее работающего как "BUSE" + (Block Device In Userspace). Модуля ядра Linux для выполнения той же задачи в Vitastor нет + (по крайней мере, пока). +- **CSI драйвер** — драйвер для подключения Vitastor-образов в виде персистентных томов (PV) Kubernetes. + Работает через vitastor-nbd — образы отражаются в виде блочных устройств и монтируются + в контейнеры. +- **Драйвера Proxmox, OpenStack и т.п.** — подключаемые модули для соответствующих систем, + позволяющие использовать Vitastor как хранилище в оных. +- **vitastor-nfs** — утилита, предоставляющая файловый доступ к образам в кластере Vitastor + по протоколу NFS 3.0. Предназначена для гипервизоров, не основанных на QEMU и Linux, но при + этом поддерживающих NFS. + +## Общий процесс записи и чтения + +- В Vitastor хранятся виртуальные диски, также называемые "образы" или "иноды". +- Каждый образ хранится в определённом пуле. Пул определяет параметры хранения образов в нём, + такие, как схему избыточности (репликация или EC — коды коррекции ошибок), домен отказа + и ограничения по выбору OSD для размещения данных образов. См. [Конфигурация пулов](../config/pool.ru.md). +- Каждый образ разбивается на объекты фиксированного размера, равного [block_size](../config/layout-cluster.ru.md#block_size) + (по умолчанию 128 КБ), умноженному на число частей данных для EC или на 1 для реплик. + То есть, например, если в пуле используется схема кодирования 4+2 (4 части данных + 2 чётности), + то при стандартном block_size образы разбиваются на части по 512 КБ. +- Клиентские запросы чтения/записи разделяются на части, соответствующие этим объектам. +- Для каждого объекта определяется номер PG, которой он принадлежит, путём простого взятия + остатка от деления ID образа и смещения на число PG в пуле, которому принадлежит образ. +- Клиент читает информацию о первичном OSD всех PG из etcd. Первичный OSD каждой PG назначается + монитором в процессе работы кластера, вместе с текущим целевым набором OSD этой PG. +- Клиент соединяется (если ещё не соединён) с первичными OSD всех PG, объекты которых участвуют + в запросе и одновременно отправляет им запросы чтения/записи частей. +- Если какие-то из первичных OSD недоступны, клиент повторяет попытки соединения бесконечно до + тех пор, пока они не станут доступны или пока PG не будут назначены другие первичные OSD. +- Клиент также повторяет запросы, если первичные OSD отвечают кодом ошибки EPIPE, означающим, + что запрос не может быть обработан в данный момент. Это происходит, если PG либо не активна + вообще, либо не активна на данном OSD в данный момент (например, если в этот момент меняется + её первичный OSD) или если в процессе обработки запроса сам первичный OSD теряет подключение + к репликам. +- Первичный OSD определяет, на каких OSD находятся части объекта. По умолчанию все объекты + считаются находящимися на текущем целевом наборе OSD соответствующей PG, но какие-то могут + находиться на других OSD, если эти объекты деградированы или перемещены, или идёт процесс + ребаланса. Запросы для проверки по сети не отправляются, информация о местоположении всех + объектов рассчитывается первичным OSD при активации PG и хранится в памяти. +- Первичный OSD соединяется (если ещё не соединён) с вторичными OSD, на которых располагаются + части объекта, и отправляет им запросы чтения/записи, а также читает/пишет из/в своё локальное + хранилище, если сам входит в набор. +- После завершения всех вторичных операций чтения/записи первичный OSD отправляет ответ клиенту. + +### Особенности обработки запросов + +- Если в пуле используются коды коррекции ошибок и при этом часть OSD недоступна, первичный + OSD при чтении восстанавливает данные из оставшихся частей. +- Каждый объект имеет номер версии. При записи объекта первичный OSD сначала читает из номер + версии объекта. Так как первичный OSD обычно сам хранит копию или часть объекта, номер + версии обычно читается из памяти самого OSD. Однако, если ни одна часть обновляемого объекта + не находится на первичном OSD, для получения номера версии он обращается к одному из вторичных + OSD, на которых копия объекта есть. Обращения к диску при этом всё равно не происходит, + так как метаданные объектов, включая номер версии, все OSD хранят в памяти. +- Если в пуле используются коды коррекции ошибок, перед частичной записью объекта для вычисления + чётности зачастую требуется чтение частей объекта с вторичных OSD или с локального диска + самого первичного OSD. +- Также, если в пуле используются коды коррекции ошибок, для закрытия Write Hole применяется + двухфазный алгоритм записи: сначала на все вторичные OSD записывается новая версия частей + объекта, но при этом старая версия не удаляется, а потом, после получения подтверждения + успешной записи от всех вторичных OSD, новая версия фиксируется и разрешается удаление старой. +- Если в кластере не включён режим immediate_commit, то запросы записи, отправляемые клиентами, + не считаются зафиксированными на физических накопителях сразу. Для фиксации данных клиенты + должны отдельно отправлять запросы SYNC (отдельный от чтения и записи вид запроса), + а пока такой запрос не отправлен, считается, что записанные данные могут исчезнуть, + если соответствующий OSD упадёт. Поэтому, когда режим immediate_commit отключён, все + запросы записи клиенты копируют в памяти и при потере соединения и повторном соединении + с OSD повторяют из памяти. Скопированные в память данные удаляются при успешном fsync, + а чтобы хранение этих данных не приводило к чрезмерному потреблению памяти, клиенты + автоматически выполняют fsync каждые [client_dirty_limit](../config/layout-cluster.ru.md#client_dirty_limit) + записанных байт. + +## Схожесть с Ceph + +- В Vitastor тоже есть пулы (pools), PG, OSD, мониторы, домены отказы, дерево распределения (аналог crush-дерева). +- Vitastor тоже равномерно распределяет данные каждого образа по всем PG пула. +- Vitastor тоже транзакционный, то есть, каждая запись в кластер атомарна. +- У Vitastor OSD тоже есть журнал и метаданные и их тоже можно размещать на отдельном диске. +- Как и в Ceph, клиентская библиотека пытается дождаться восстановления работы + при любом полном или частичном отказе кластера, то есть, вы можете перезагрузить + хоть весь кластер разом, и клиенты не отключатся, только на время зависнут. + +## Отличия от Ceph + +- Vitastor в первую очередь сфокусирован на использовании с SSD: либо в кластерах на основе + только SSD, либо гибридных (HDD с журналами на SSD). +- Базовый слой Vitastor — простое блочное хранилище с блоками фиксированного размера, а не + объектное со сложной семантикой, как в Ceph (RADOS). +- PG в Vitastor эфемерны. Это означает, что они не хранятся на дисках и существуют только в + памяти работающих OSD. +- Vitastor OSD однопоточные и всегда такими останутся. Если вам нужно выделить больше 1 ядра + на 1 диск — создайте несколько OSD на разделах этого диска. Нужно это в основном для NVMe, + так как Vitastor не потребляет много ресурсов CPU. +- Метаданные всегда размещаются в памяти, благодаря чему никогда не тратится лишнее время + на чтение метаданных с диска. Объём метаданных линейно зависит от ёмкости диска и размера + блока хранилища (block_size, по умолчанию 128 КБ). С 128 КБ блоком потребление памяти + составляет примерно 512 МБ на 1 ТБ данных. Журналы по умолчанию тоже хранятся в памяти, + но в SSD-кластерах нужный размер журнала составляет всего 32 МБ, а в гибридных (SSD+HDD) + кластерах, в которых есть смысл делать журналы больше, можно отключить [inmemory_journal](../docs/config/osd.ru.md#inmemory_journal). +- В Vitastor нет внутреннего copy-on-write. Я считаю, что реализация CoW-хранилища гораздо сложнее, + поэтому сложнее добиться устойчиво хороших результатов. Возможно, в один прекрасный день + я придумаю красивый алгоритм для CoW-хранилища, но пока нет — внутреннего CoW в Vitastor не будет. + Всё это не относится к "внешнему" CoW (снапшотам и клонам). +- В Vitastor есть режим "ленивых fsync", в котором OSD группирует запросы записи перед сбросом их + на диск, что позволяет получить лучшую производительность с дешёвыми настольными SSD без конденсаторов + ("Advanced Power Loss Protection" / "Capacitor-Based Power Loss Protection"). + Тем не менее, такой режим всё равно медленнее использования нормальных серверных SSD и мгновенного + fsync, так как приводит к дополнительным операциям передачи данных по сети, поэтому рекомендуется + всё-таки использовать хорошие серверные диски, тем более, стоят они почти так же, как десктопные. +- Процессы восстановления оперируют отдельными объектами, а не целыми PG. +- "Мониторы" не хранят данные. Конфигурация и состояние кластера хранятся в etcd в простых человекочитаемых + JSON-структурах. Мониторы Vitastor только следят за состоянием кластера и управляют перемещением данных. + В этом смысле монитор Vitastor не является критичным компонентом системы и больше похож на Ceph-овский + менеджер (MGR). Монитор Vitastor написан на node.js. +- Распределение PG не основано на консистентных хешах. Вместо этого все маппинги PG хранятся прямо в etcd + (ибо нет никакой проблемы сохранить несколько сотен-тысяч записей в памяти, а не считать каждый раз хеши). + Перераспределение PG по OSD выполняется через математическую оптимизацию, + а конкретно, сведение задачи к ЛП (задаче линейного программирования) и решение оной с помощью утилиты + lp_solve. Такой подход позволяет обычно выравнивать распределение места почти идеально — равномерность + обычно составляет 96-99%, в отличие от Ceph, где на голом CRUSH-е без балансировщика обычно выходит 80-90%. + Также это позволяет минимизировать объём перемещения данных и случайность связей между OSD, а также менять + распределение вручную, не боясь сломать логику перебалансировки. В таком подходе есть и потенциальный + недостаток — есть предположение, что в очень большом кластере он может сломаться — однако вплоть до + нескольких сотен OSD подход точно работает нормально. Ну и, собственно, при необходимости легко + реализовать и консистентные хеши. +- Отдельный слой, подобный слою "CRUSH-правил", отсутствует. Вы настраиваете схемы отказоустойчивости, + домены отказа и правила выбора OSD напрямую в конфигурации пулов. + +## Принципы разработки + +- Я люблю простые решения. Поэтому Vitastor простой и быстрый и всегда будет таковым. +- Я не против иногда изобрести велосипед, например, собственный простенький HTTP-клиент + для работы с etcd, вместо того, чтобы взять тяжёлую готовую библиотеку, ибо в данном + случае я точно уверен в том, что знаю, что делает код. +- Общепринятые практики написания C++ кода с RAII, наследованием, умными указателями + и так далее меня также не волнуют, поэтому если вы хотели увидеть здесь красивый + идиоматичный C++ код, вы, вероятно, пришли не по адресу. +- Из всех интерпретаторов скриптоты больше всех я люблю node.js, это самый быстрый в мире + интерпретатор, у него есть встроенная событийная машина, развитая инфраструктура и + приятный нейтральный C-подобный язык программирования. Поэтому Монитор реализован на node.js. + +## Известные проблемы + +- Удаление образов в деградированном кластере может в данный момент приводить к повторному + "появлению" удалённых объектов после поднятия отключённых OSD, причём в случае EC-пулов, + объекты могут появиться в виде "неполных". Если вы столкнётесь с такой ситуацией, просто + повторите запрос удаления. Исправление этой проблемы уже реализовано в ветке "epoch-deletions" + и вскоре будет включено в релиз. diff --git a/docs/intro/author.en.md b/docs/intro/author.en.md new file mode 100644 index 00000000..3d75f27b --- /dev/null +++ b/docs/intro/author.en.md @@ -0,0 +1,37 @@ +[Documentation](../../README.md#documentation) → Introduction → Author and License + +----- + +[Читать на русском](author.ru.md) + +# Author and License + +Copyright (c) Vitaliy Filippov (vitalif [at] yourcmc.ru), 2019+ + +Join Vitastor Telegram Chat: https://t.me/vitastor + +All server-side code (OSD, Monitor and so on) is licensed under the terms of +Vitastor Network Public License 1.1 (VNPL 1.1), a copyleft license based on +GNU GPLv3.0 with the additional "Network Interaction" clause which requires +opensourcing all programs directly or indirectly interacting with Vitastor +through a computer network and expressly designed to be used in conjunction +with it ("Proxy Programs"). Proxy Programs may be made public not only under +the terms of the same license, but also under the terms of any GPL-Compatible +Free Software License, as listed by the Free Software Foundation. +This is a stricter copyleft license than the Affero GPL. + +Please note that VNPL doesn't require you to open the code of proprietary +software running inside a VM if it's not specially designed to be used with +Vitastor. + +Basically, you can't use the software in a proprietary environment to provide +its functionality to users without opensourcing all intermediary components +standing between the user and Vitastor or purchasing a commercial license +from the author 😀. + +Client libraries (cluster_client and so on) are dual-licensed under the same +VNPL 1.1 and also GNU GPL 2.0 or later to allow for compatibility with GPLed +software like QEMU and fio. + +You can find the full text of VNPL-1.1 in the file [VNPL-1.1.txt](../../VNPL-1.1.txt). +GPL 2.0 is also included in this repository as [GPL-2.0.txt](../../GPL-2.0.txt). diff --git a/docs/intro/author.ru.md b/docs/intro/author.ru.md new file mode 100644 index 00000000..d950d9b3 --- /dev/null +++ b/docs/intro/author.ru.md @@ -0,0 +1,37 @@ +[Документация](../../README-ru.md#документация) → Введение → Автор и лицензия + +----- + +[Read in English](author.en.md) + +# Автор и лицензия + +Автор: Виталий Филиппов (vitalif [at] yourcmc.ru), 2019+ + +Заходите в Telegram-чат Vitastor: https://t.me/vitastor + +Лицензия: VNPL 1.1 на серверный код и двойная VNPL 1.1 + GPL 2.0+ на клиентский. + +VNPL - "сетевой копилефт", собственная свободная копилефт-лицензия +Vitastor Network Public License 1.1, основанная на GNU GPL 3.0 с дополнительным +условием "Сетевого взаимодействия", требующим распространять все программы, +специально разработанные для использования вместе с Vitastor и взаимодействующие +с ним по сети, под лицензией VNPL или под любой другой свободной лицензией. + +Идея VNPL - расширение действия копилефта не только на модули, явным образом +связываемые с кодом Vitastor, но также на модули, оформленные в виде микросервисов +и взаимодействующие с ним по сети. + +Таким образом, если вы хотите построить на основе Vitastor сервис, содержаший +компоненты с закрытым кодом, взаимодействующие с Vitastor, вам нужна коммерческая +лицензия от автора 😀. + +На Windows и любое другое ПО, не разработанное *специально* для использования +вместе с Vitastor, никакие ограничения не накладываются. + +Клиентские библиотеки распространяются на условиях двойной лицензии VNPL 1.0 +и также на условиях GNU GPL 2.0 или более поздней версии. Так сделано в целях +совместимости с таким ПО, как QEMU и fio. + +Вы можете найти полный текст VNPL 1.1 в файле [VNPL-1.1.txt](../../VNPL-1.1.txt), +а GPL 2.0 в файле [GPL-2.0.txt](../../GPL-2.0.txt). diff --git a/docs/intro/features.en.md b/docs/intro/features.en.md new file mode 100644 index 00000000..82ae4f1d --- /dev/null +++ b/docs/intro/features.en.md @@ -0,0 +1,62 @@ +[Documentation](../../README.md#documentation) → Introduction → Features + +----- + +[Читать на русском](features.ru.md) + +# Features + +- [Server-side features](#server-side-features) +- [Plugins and tools](#plugins-and-tools) +- [Roadmap](#roadmap) + +## Server-side features + +- Basic part: highly-available block storage with symmetric clustering and no SPOF +- [Performance](../performance/comparison1.en.md) ;-D +- [Multiple redundancy schemes](../config/pool.en.md#scheme): Replication, XOR n+1, Reed-Solomon erasure codes + based on jerasure library with any number of data and parity drives in a group +- Configuration via simple JSON data structures in etcd (parameters, pools and images) +- Automatic data distribution over OSDs, with support for: + - Mathematical optimization for better uniformity and less data movement + - Multiple pools + - Placement tree, OSD selection by tags (device classes) and placement root + - Configurable failure domains +- Recovery of degraded blocks +- Rebalancing (data movement between OSDs) +- [Lazy fsync support](../config/layout-cluster.en.md#immediate_commit) +- Per-OSD and per-image I/O and space usage statistics in etcd +- Snapshots and copy-on-write image clones +- [Write throttling to smooth random write workloads in SSD+HDD configurations](../config/osd.en.md#throttle_small_writes) +- [RDMA/RoCEv2 support via libibverbs](../config/network.en.md#rdma_device) + +## Plugins and tools + +- [Debian and CentOS packages](../installation/packages.en.md) +- [Image management CLI (vitastor-cli)](../usage/cli.en.md) +- Generic user-space client library +- [Native QEMU driver](../usage/qemu.en.md) +- [Loadable fio engine for benchmarks](../usage/fio.en.md) +- [NBD proxy for kernel mounts](../usage/nbd.en.md) +- [CSI plugin for Kubernetes](../installation/kubernetes.en.md) +- [OpenStack support: Cinder driver, Nova and libvirt patches](../installation/openstack.en.md) +- [Proxmox storage plugin and packages](../installation/proxmox.en.md) +- [Simplified NFS proxy for file-based image access emulation (suitable for VMWare)](../usage/nfs.en.md) + +## Roadmap + +The following features are planned for the future: + +- Better OSD creation and auto-start tools +- Other administrative tools +- Web GUI +- OpenNebula plugin +- iSCSI proxy +- Multi-threaded client +- Faster failover +- Scrubbing without checksums (verification of replicas) +- Checksums +- Tiered storage (SSD caching) +- NVDIMM support +- Compression (possibly) +- Read caching using system page cache (possibly) diff --git a/docs/intro/features.ru.md b/docs/intro/features.ru.md new file mode 100644 index 00000000..6806a13f --- /dev/null +++ b/docs/intro/features.ru.md @@ -0,0 +1,62 @@ +[Документация](../../README-ru.md#документация) → Введение → Возможности Vitastor + +----- + +[Read in English](features.en.md) + +# Возможности Vitastor + +- [Серверные функции](#серверные-функции) +- [Драйверы и инструменты](#драйверы-и-инструменты) +- [Планы развития](#планы-развития) + +## Серверные функции + +- Базовая часть - надёжное кластерное блочное хранилище без единой точки отказа +- [Производительность](../comparison1.ru.md) ;-D +- [Несколько схем отказоустойчивости](../config/pool.ru.md#scheme): репликация, XOR n+1 (1 диск чётности), коды коррекции ошибок + Рида-Соломона на основе библиотеки jerasure с любым числом дисков данных и чётности в группе +- Конфигурация через простые человекочитаемые JSON-структуры в etcd +- Автоматическое распределение данных по OSD, с поддержкой: + - Математической оптимизации для лучшей равномерности распределения и минимизации перемещений данных + - Нескольких пулов с разными схемами избыточности + - Дерева распределения, выбора OSD по тегам / классам устройств (только SSD, только HDD) и по поддереву + - Настраиваемых доменов отказа (диск/сервер/стойка и т.п.) +- Восстановление деградированных блоков +- Ребаланс, то есть перемещение данных между OSD (дисками) +- [Поддержка "ленивого" fsync (fsync не на каждую операцию)](../config/layout-cluster.ru.md#immediate_commit) +- Сбор статистики ввода/вывода в etcd +- Статистика операций ввода/вывода и занятого места в разрезе инодов +- Именование инодов через хранение их метаданных в etcd +- Снапшоты и copy-on-write клоны +- [Сглаживание производительности случайной записи в SSD+HDD конфигурациях](../config/osd.ru.md#throttle_small_writes) +- [Поддержка RDMA/RoCEv2 через libibverbs](../config/network.ru.md#rdma_device) + +## Драйверы и инструменты + +- [Пакеты для Debian и CentOS](../installation/packages.ru.md) +- [Консольный интерфейс управления образами (vitastor-cli)](../usage/cli.ru.md) +- Общая пользовательская клиентская библиотека для работы с кластером +- [Драйвер диска для QEMU](../usage/qemu.ru.md) +- [Драйвер диска для утилиты тестирования производительности fio](../usage/fio.ru.md) +- [NBD-прокси для монтирования образов ядром](../usage/nbd.ru.md) ("блочное устройство в режиме пользователя") +- [CSI-плагин для Kubernetes](../installation/kubernetes.ru.md) +- [Базовая поддержка OpenStack: драйвер Cinder, патчи для Nova и libvirt](../installation/openstack.ru.md) +- [Плагин для Proxmox](../installation/proxmox.ru.md) +- [Упрощённая NFS-прокси для эмуляции файлового доступа к образам (подходит для VMWare)](../usage/nfs.ru.md) + +## Планы развития + +- Более корректные скрипты разметки дисков и автоматического запуска OSD +- Другие инструменты администрирования +- Web-интерфейс +- Плагин для OpenNebula +- iSCSI-прокси +- Многопоточный клиент +- Более быстрое переключение при отказах +- Фоновая проверка целостности без контрольных сумм (сверка реплик) +- Контрольные суммы +- Поддержка SSD-кэширования (tiered storage) +- Поддержка NVDIMM +- Возможно, сжатие +- Возможно, поддержка кэширования данных через системный page cache diff --git a/docs/intro/quickstart.en.md b/docs/intro/quickstart.en.md new file mode 100644 index 00000000..052ac1f0 --- /dev/null +++ b/docs/intro/quickstart.en.md @@ -0,0 +1,95 @@ +[Documentation](../../README.md#documentation) → Introduction → Quick Start + +----- + +[Читать на русском](quickstart.ru.md) + +# Quick Start + +- [Preparation](#preparation) +- [Configure monitors](#configure-monitors) +- [Configure OSDs](#configure-osds) +- [Create a pool](#create-a-pool) +- [Check cluster status](#check-cluster-status) +- [Create an image](#create-an-image) +- [Install plugins](#install-plugins) + +## Preparation + +- Get some SATA or NVMe SSDs with capacitors (server-grade drives). You can use desktop SSDs + with lazy fsync, but prepare for inferior single-thread latency. Read more about capacitors + [here](../config/layout-cluster.en.md#immediate_commit). +- Get a fast network (at least 10 Gbit/s). Something like Mellanox ConnectX-4 with RoCEv2 is ideal. +- Disable CPU powersaving: `cpupower idle-set -D 0 && cpupower frequency-set -g performance`. +- [Install Vitastor packages](../installation/packages.en.md). + +## Configure monitors + +On the monitor hosts: +- Edit variables at the top of `/usr/lib/vitastor/mon/make-units.sh` to desired values. +- Create systemd units for the monitor and etcd: `/usr/lib/vitastor/mon/make-units.sh` +- Start etcd and monitors: `systemctl start etcd vitastor-mon` + +## Configure OSDs + +- Put etcd_address and osd_network into `/etc/vitastor/vitastor.conf`. Example: + ``` + { + "etcd_address": ["10.200.1.10:2379","10.200.1.11:2379","10.200.1.12:2379"], + "osd_network": "10.200.1.0/24" + } + ``` +- Initialize OSDs: + - Simplest, SSD-only: `/usr/lib/vitastor/mon/make-osd.sh /dev/disk/by-partuuid/XXX [/dev/disk/by-partuuid/YYY ...]` + **Warning!** This very simple script by default makes units for server-grade SSDs with write-through cache! + If it's not your case, you MUST remove disable_data_fsync and immediate_commit from systemd units. + - Hybrid, HDD+SSD: `/usr/lib/vitastor/mon/make-osd-hybrid.js /dev/sda /dev/sdb ...` — pass all your + devices (HDD and SSD) to this script — it will partition disks and initialize journals on its own. + This script skips HDDs which are already partitioned so if you want to use non-empty disks for + Vitastor you should first wipe them with `wipefs -a`. SSDs with GPT partition table are not skipped, + but some free unpartitioned space must be available because the script creates new partitions for journals. +- You can change OSD configuration in units or in `vitastor.conf`. + Check [Configuration Reference](../config.en.md) for parameter descriptions. +- If all your drives have capacitors, create global configuration in etcd: \ + `etcdctl --endpoints=... put /vitastor/config/global '{"immediate_commit":"all"}'` +- Start all OSDs: `systemctl start vitastor.target` + +## Create a pool + +Create pool configuration in etcd: + +``` +etcdctl --endpoints=... put /vitastor/config/pools '{"1":{"name":"testpool", + "scheme":"replicated","pg_size":2,"pg_minsize":1,"pg_count":256,"failure_domain":"host"}}' +``` + +For jerasure pools the configuration should look like the following: + +``` +etcdctl --endpoints=... put /vitastor/config/pools '{"2":{"name":"ecpool", + "scheme":"jerasure","pg_size":4,"parity_chunks":2,"pg_minsize":2,"pg_count":256,"failure_domain":"host"}` +``` + +After you do this, one of the monitors will configure PGs and OSDs will start them. + +## Check cluster status + +`vitastor-cli status` + +Or you can check PG states with `etcdctl --endpoints=... get --prefix /vitastor/pg/state`. All PGs should become 'active'. + +## Create an image + +Use vitastor-cli ([read CLI documentation here](../usage/cli.en.md)): + +``` +vitastor-cli create -s 10G testimg +``` + +After that, you can [run benchmarks](../usage/fio.en.md) or [start QEMU manually](../usage/qemu.en.md) with this image. + +## Install plugins + +- [Proxmox](../installation/proxmox.en.md) +- [OpenStack](../installation/openstack.en.md) +- [Kubernetes CSI](../installation/kubernetes.en.md) diff --git a/docs/intro/quickstart.ru.md b/docs/intro/quickstart.ru.md new file mode 100644 index 00000000..be63e9fd --- /dev/null +++ b/docs/intro/quickstart.ru.md @@ -0,0 +1,103 @@ +[Документация](../../README-ru.md#документация) → Введение → Быстрый старт + +----- + +[Read in English](quickstart.en.md) + +# Быстрый старт + +- [Подготовка](#подготовка) +- [Настройте мониторы](#настройте-мониторы) +- [Настройте OSD](#настройте-osd) +- [Создайте пул](#создайте-пул) +- [Проверьте состояние кластера](#проверьте-состояние-кластера) +- [Создайте образ](#создайте-образ) +- [Установите плагины](#установите-плагины) + +## Подготовка + +- Возьмите серверы с SSD (SATA или NVMe), желательно с конденсаторами (серверные SSD). Можно + использовать и десктопные SSD, включив режим отложенного fsync, но производительность будет хуже. + О конденсаторах читайте [здесь](../config/layout-cluster.ru.md#immediate_commit). +- Возьмите быструю сеть, минимум 10 гбит/с. Идеал - что-то вроде Mellanox ConnectX-4 с RoCEv2. +- Для лучшей производительности отключите энергосбережение CPU: `cpupower idle-set -D 0 && cpupower frequency-set -g performance`. +- [Установите пакеты Vitastor](../installation/packages.ru.md). + +## Настройте мониторы + +На хостах, выделенных под мониторы: +- Пропишите нужные вам значения в файле `/usr/lib/vitastor/mon/make-units.sh` +- Создайте юниты systemd для etcd и мониторов: `/usr/lib/vitastor/mon/make-units.sh` +- Запустите etcd и мониторы: `systemctl start etcd vitastor-mon` +- Пропишите etcd_address и osd_network в `/etc/vitastor/vitastor.conf`. Например: + ``` + { + "etcd_address": ["10.200.1.10:2379","10.200.1.11:2379","10.200.1.12:2379"], + "osd_network": "10.200.1.0/24" + } + ``` + +## Настройте OSD + +- Пропишите etcd_address и osd_network в `/etc/vitastor/vitastor.conf`. Например: + ``` + { + "etcd_address": ["10.200.1.10:2379","10.200.1.11:2379","10.200.1.12:2379"], + "osd_network": "10.200.1.0/24" + } + ``` +- Инициализуйте OSD: + - SSD: `/usr/lib/vitastor/make-osd.sh /dev/disk/by-partuuid/XXX [/dev/disk/by-partuuid/YYY ...]`. \ + **Внимание!** Скрипт по умолчанию рассчитан на то, что у вас диски с конденсаторами и отключённым + кэшем! Если это не так, из юнитов systemd нужно убрать строчки disable_data_fsync и immediate_commit! + - Гибридные, HDD+SSD: `/usr/lib/vitastor/mon/make-osd-hybrid.js /dev/sda /dev/sdb ...` - передайте + все ваши SSD и HDD скрипту в командной строке подряд, скрипт автоматически выделит разделы под + журналы на SSD и данные на HDD. Скрипт пропускает HDD, на которых уже есть разделы + или вообще какие-то данные, поэтому если диски непустые, сначала очистите их с помощью + `wipefs -a`. SSD с таблицей разделов не пропускаются, но так как скрипт создаёт новые разделы + для журналов, на SSD должно быть доступно свободное нераспределённое место. +- Вы можете менять параметры OSD в юнитах systemd или в `vitastor.conf`. Описания параметров + смотрите в [справке по конфигурации](../config.ru.md). +- Если все ваши диски - серверные с конденсаторами, пропишите это в глобальную конфигурацию в etcd: \ + `etcdctl --endpoints=... put /vitastor/config/global '{"immediate_commit":"all"}'` +- Запустите все OSD: `systemctl start vitastor.target` + +## Создайте пул + +Создайте конфигурацию пула с помощью etcdctl: + +``` +etcdctl --endpoints=... put /vitastor/config/pools '{"1":{"name":"testpool", + "scheme":"replicated","pg_size":2,"pg_minsize":1,"pg_count":256,"failure_domain":"host"}}' +``` + +Для пулов с кодами коррекции ошибок конфигурация должна выглядеть примерно так: + +``` +etcdctl --endpoints=... put /vitastor/config/pools '{"2":{"name":"ecpool", + "scheme":"jerasure","pg_size":4,"parity_chunks":2,"pg_minsize":2,"pg_count":256,"failure_domain":"host"}` +``` + +После этого один из мониторов должен сконфигурировать PG, а OSD должны запустить их. + +## Проверьте состояние кластера + +`vitastor-cli status` + +Либо же вы можете проверять состояние PG прямо в etcd: `etcdctl --endpoints=... get --prefix /vitastor/pg/state`. Все PG должны быть 'active'. + +## Создайте образ + +Используйте vitastor-cli ([смотрите документацию CLI здесь](../usage/cli.ru.md)): + +``` +vitastor-cli create -s 10G testimg +``` + +После этого вы можете [запускать тесты](../usage/fio.ru.md) или [вручную запускать QEMU](../usage/qemu.ru.md) с новым образом. + +## Установите плагины + +- [Proxmox](../installation/proxmox.ru.md) +- [OpenStack](../installation/openstack.ru.md) +- [Kubernetes CSI](../installation/kubernetes.ru.md) diff --git a/docs/performance/comparison1.en.md b/docs/performance/comparison1.en.md new file mode 100644 index 00000000..cfa87ab5 --- /dev/null +++ b/docs/performance/comparison1.en.md @@ -0,0 +1,108 @@ +[Documentation](../../README.md#documentation) → Performance → Example Comparison with Ceph + +----- + +[Читать на русском](comparison1.ru.md) + +# Example Comparison with Ceph + +- [Test environment](#test-environment) +- [Raw drive performance](#raw-drive-performance) +- [2 replicas](#2-replicas) + - [Ceph 15.2.4 (Bluestore)](#ceph-15-2-4-bluestore) + - [Vitastor 0.4.0 (native)](#vitastor-0-4-0-native) + - [Vitastor 0.4.0 (NBD)](#vitastor-0-4-0-nbd) +- [EC/XOR 2+1](#ec/xor-2-1) + - [Ceph 15.2.4](#ceph-15-2-4) + - [Vitastor 0.4.0](#vitastor-0-4-0) + +## Test environment + +Hardware configuration: 4 nodes, each with: +- 6x SATA SSD Intel D3-S4510 3.84 TB +- 2x Xeon Gold 6242 (16 cores @ 2.8 GHz) +- 384 GB RAM +- 1x 25 GbE network interface (Mellanox ConnectX-4 LX), connected to a Juniper QFX5200 switch + +CPU powersaving was disabled. Both Vitastor and Ceph were configured with 2 OSDs per 1 SSD. + +All of the results below apply to 4 KB blocks and random access (unless indicated otherwise). + +T8Q64 tests were conducted over 8 400GB RBD images from all hosts (every host was running 2 instances of fio). +This is because Ceph has performance penalties related to running multiple clients over a single RBD image. + +cephx_sign_messages was set to false during tests, RocksDB and Bluestore settings were left at defaults. + +T8Q64 read test was conducted over 1 larger inode (3.2T) from all hosts (every host was running 2 instances of fio). +Vitastor has no performance penalties related to running multiple clients over a single inode. +If conducted from one node with all primary OSDs moved to other nodes the result was slightly lower (689000 iops), +this is because all operations resulted in network roundtrips between the client and the primary OSD. +When fio was colocated with OSDs (like in Ceph benchmarks above), 1/4 of the read workload actually +used the loopback network. + +Vitastor was configured with: `--disable_data_fsync true --immediate_commit all --flusher_count 8 + --disk_alignment 4096 --journal_block_size 4096 --meta_block_size 4096 + --journal_no_same_sector_overwrites true --journal_sector_buffer_count 1024 + --journal_size 16777216`. + +## Raw drive performance + +- T1Q1 write ~27000 iops (~0.037ms latency) +- T1Q1 read ~9800 iops (~0.101ms latency) +- T1Q32 write ~60000 iops +- T1Q32 read ~81700 iops + +## 2 replicas + +### Ceph 15.2.4 (Bluestore) + +- T1Q1 write ~1000 iops (~1ms latency) +- T1Q1 read ~1750 iops (~0.57ms latency) +- T8Q64 write ~100000 iops, total CPU usage by OSDs about 40 virtual cores on each node +- T8Q64 read ~480000 iops, total CPU usage by OSDs about 40 virtual cores on each node + +In fact, not that bad for Ceph. These servers are an example of well-balanced Ceph nodes. +However, CPU usage and I/O latency were through the roof, as usual. + +### Vitastor 0.4.0 (native) + +- T1Q1 write: 7087 iops (0.14ms latency) +- T1Q1 read: 6838 iops (0.145ms latency) +- T2Q64 write: 162000 iops, total CPU usage by OSDs about 3 virtual cores on each node +- T8Q64 read: 895000 iops, total CPU usage by OSDs about 4 virtual cores on each node +- Linear write (4M T1Q32): 2800 MB/s +- Linear read (4M T1Q32): 1500 MB/s + +### Vitastor 0.4.0 (NBD) + +NBD is currently required to mount Vitastor via kernel, but it imposes additional overhead +due to additional copying between the kernel and userspace. This mostly hurts linear +bandwidth, not iops. + +Vitastor with single-threaded NBD on the same hardware: +- T1Q1 write: 6000 iops (0.166ms latency) +- T1Q1 read: 5518 iops (0.18ms latency) +- T1Q128 write: 94400 iops +- T1Q128 read: 103000 iops +- Linear write (4M T1Q128): 1266 MB/s (compared to 2800 MB/s via fio) +- Linear read (4M T1Q128): 975 MB/s (compared to 1500 MB/s via fio) + +## EC/XOR 2+1 + +### Ceph 15.2.4 + +- T1Q1 write: 730 iops (~1.37ms latency) +- T1Q1 read: 1500 iops with cold cache (~0.66ms latency), 2300 iops after 2 minute metadata cache warmup (~0.435ms latency) +- T4Q128 write (4 RBD images): 45300 iops, total CPU usage by OSDs about 30 virtual cores on each node +- T8Q64 read (4 RBD images): 278600 iops, total CPU usage by OSDs about 40 virtual cores on each node +- Linear write (4M T1Q32): 1950 MB/s before preallocation, 2500 MB/s after preallocation +- Linear read (4M T1Q32): 2400 MB/s + +### Vitastor 0.4.0 + +- T1Q1 write: 2808 iops (~0.355ms latency) +- T1Q1 read: 6190 iops (~0.16ms latency) +- T2Q64 write: 85500 iops, total CPU usage by OSDs about 3.4 virtual cores on each node +- T8Q64 read: 812000 iops, total CPU usage by OSDs about 4.7 virtual cores on each node +- Linear write (4M T1Q32): 3200 MB/s +- Linear read (4M T1Q32): 1800 MB/s diff --git a/docs/performance/comparison1.ru.md b/docs/performance/comparison1.ru.md new file mode 100644 index 00000000..6d7f06fd --- /dev/null +++ b/docs/performance/comparison1.ru.md @@ -0,0 +1,113 @@ +[Документация](../../README-ru.md#документация) → Производительность → Пример сравнения с Ceph + +----- + +[Read in English](comparison1.en.md) + +# Пример сравнения с Ceph + +- [Описание стенда](#описание-стенда) +- [Производительность голых дисков](#производительность-голых-дисков) +- [2 реплики](#2-реплики) + - [Ceph 15.2.4 (Bluestore)](#ceph-15-2-4-bluestore) + - [Vitastor 0.4.0 (нативный драйвер fio)](#vitastor-0-4-0-нативный-драйвер-fio) + - [Vitastor 0.4.0 (NBD)](#vitastor-0-4-0-nbd) +- [EC/XOR 2+1](#ec/xor-2-1) + - [Ceph 15.2.4](#ceph-15-2-4) + - [Vitastor 0.4.0](#vitastor-0-4-0) + +## Описание стенда + +Железо: 4 сервера, в каждом: +- 6x SATA SSD Intel D3-4510 3.84 TB +- 2x Xeon Gold 6242 (16 cores @ 2.8 GHz) +- 384 GB RAM +- 1x 25 GbE сетевая карта (Mellanox ConnectX-4 LX), подключённая к свитчу Juniper QFX5200 + +Экономия энергии CPU отключена. В тестах и Vitastor, и Ceph развёрнуто по 2 OSD на 1 SSD. + +Все результаты ниже относятся к случайной нагрузке 4 КБ блоками (если явно не указано обратное). + +Тесты в 8 потоков проводились на 8 400GB RBD образах со всех хостов (с каждого хоста запускалось 2 процесса fio). +Это нужно потому, что в Ceph несколько RBD-клиентов, пишущих в 1 образ, очень сильно замедляются. + +Настройки RocksDB и Bluestore в Ceph не менялись, единственным изменением было отключение cephx_sign_messages. + +Тест на чтение в 8 потоков проводился на 1 большом образе (3.2 ТБ) со всех хостов (опять же, по 2 fio с каждого). +В Vitastor никакой разницы между 1 образом и 8-ю нет. Естественно, примерно 1/4 запросов чтения +в такой конфигурации, как и в тестах Ceph выше, обслуживалась с локальной машины. Если проводить +тест так, чтобы все операции всегда обращались к первичным OSD по сети - тест сильнее упирался +в сеть и результат составлял примерно 689000 iops. + +Настройки Vitastor: `--disable_data_fsync true --immediate_commit all --flusher_count 8 + --disk_alignment 4096 --journal_block_size 4096 --meta_block_size 4096 + --journal_no_same_sector_overwrites true --journal_sector_buffer_count 1024 + --journal_size 16777216`. + +## Производительность голых дисков + +- T1Q1 запись ~27000 iops (задержка ~0.037ms) +- T1Q1 чтение ~9800 iops (задержка ~0.101ms) +- T1Q32 запись ~60000 iops +- T1Q32 чтение ~81700 iops + +## 2 реплики + +### Ceph 15.2.4 (Bluestore) + +- T1Q1 запись ~1000 iops (задержка ~1ms) +- T1Q1 чтение ~1750 iops (задержка ~0.57ms) +- T8Q64 запись ~100000 iops, потребление CPU процессами OSD около 40 ядер на каждом сервере +- T8Q64 чтение ~480000 iops, потребление CPU процессами OSD около 40 ядер на каждом сервере + +Если не учитывать как обычно запредельное потребление CPU (40 ядер), не так уж и плохо для Ceph. +Данные серверы - как раз хороший пример сбалансированных Ceph-нод - 6 SATA SSD как раз +утилизируют 25-гигабитную сеть, а без 2 мощных процессоров Ceph-у бы не хватило ядер, +чтобы выдать пристойный результат. + +### Vitastor 0.4.0 (нативный драйвер fio) + +- T1Q1 запись: 7087 iops (задержка 0.14ms) +- T1Q1 чтение: 6838 iops (задержка 0.145ms) +- T2Q64 запись: 162000 iops, потребление CPU - 3 ядра на каждом сервере +- T8Q64 чтение: 895000 iops, потребление CPU - 4 ядра на каждом сервере +- Линейная запись (4M T1Q32): 2800 МБ/с +- Линейное чтение (4M T1Q32): 1500 МБ/с + +### Vitastor 0.4.0 (NBD) + +NBD расшифровывается как "сетевое блочное устройство", но на самом деле оно также +работает просто как аналог FUSE для блочных устройств, то есть, представляет собой +"блочное устройство в пространстве пользователя". + +NBD - на данный момент единственный способ монтировать Vitastor ядром Linux. Его +производительность немного хуже из-за дополнительных операций копирований данных +между ядром и пространством пользователя, что, правда, в основном затрагивает линейное +чтение/запись, а не случайный доступ. + +- T1Q1 запись: 6000 iops (задержка 0.166ms) +- T1Q1 чтение: 5518 iops (задержка 0.18ms) +- T1Q128 запись: 94400 iops +- T1Q128 чтение: 103000 iops +- Линейная запись (4M T1Q128): 1266 МБ/с (в сравнении с 2800 МБ/с через fio) +- Линейное чтение (4M T1Q128): 975 МБ/с (в сравнении с 1500 МБ/с через fio) + +## EC/XOR 2+1 + +### Ceph 15.2.4 + +- T1Q1 запись: 730 iops (задержка ~1.37ms latency) +- T1Q1 чтение: 1500 iops с холодным кэшем метаданных (задержка ~0.66ms), 2300 iops через 2 минуты прогрева (задержка ~0.435ms) +- T4Q128 запись (4 RBD images): 45300 iops, потребление CPU - 30 ядер на каждом сервере +- T8Q64 чтение (4 RBD images): 278600 iops, потребление CPU - 40 ядер на каждом сервере +- Линейная запись (4M T1Q32): 1950 МБ/с в пустой образ, 2500 МБ/с в заполненный образ +- Линейное чтение (4M T1Q32): 2400 МБ/с + +### Vitastor 0.4.0 + +- T1Q1 запись: 2808 iops (задержка ~0.355ms) +- T1Q1 чтение: 6190 iops (задержка ~0.16ms) +- T2Q64 запись: 85500 iops, потребление CPU - 3.4 ядра на каждом сервере +- T8Q64 чтение: 812000 iops, потребление CPU - 4.7 ядра на каждом сервере +- Линейная запись (4M T1Q32): 3200 МБ/с +- Линейное чтение (4M T1Q32): 1800 МБ/с diff --git a/docs/performance/theoretical.en.md b/docs/performance/theoretical.en.md new file mode 100644 index 00000000..82101f1b --- /dev/null +++ b/docs/performance/theoretical.en.md @@ -0,0 +1,49 @@ +[Documentation](../../README.md#documentation) → Performance → Vitastor's Theoretical Maximum Performance + +----- + +[Читать на русском](theoretical.ru.md) + +# Vitastor's Theoretical Maximum Performance + +Replicated setups: +- Single-threaded (T1Q1) read latency: 1 network roundtrip + 1 disk read. +- Single-threaded write+fsync latency: + - With immediate commit: 2 network roundtrips + 1 disk write. + - With lazy commit: 4 network roundtrips + 1 disk write + 1 disk flush. +- Saturated parallel read iops: min(network bandwidth, sum(disk read iops)). +- Saturated parallel write iops: min(network bandwidth, sum(disk write iops / number of replicas / write amplification)). + +EC/XOR setups: +- Single-threaded (T1Q1) read latency: 1.5 network roundtrips + 1 disk read. +- Single-threaded write+fsync latency: + - With immediate commit: 3.5 network roundtrips + 1 disk read + 2 disk writes. + - With lazy commit: 5.5 network roundtrips + 1 disk read + 2 disk writes + 2 disk fsyncs. + - 0.5 in actually (k-1)/k which means that an additional roundtrip doesn't happen when + the read sub-operation can be served locally. +- Saturated parallel read iops: min(network bandwidth, sum(disk read iops)). +- Saturated parallel write iops: min(network bandwidth, sum(disk write iops * number of data drives / (number of data + parity drives) / write amplification)). + In fact, you should put disk write iops under the condition of ~10% reads / ~90% writes in this formula. + +Write amplification for 4 KB blocks is usually 3-5 in Vitastor: +1. Journal block write +2. Journal data write +3. Metadata block write +4. Another journal block write for EC/XOR setups +5. Data block write + +If you manage to get an SSD which handles 512 byte blocks well (Optane?) you may +lower 1, 3 and 4 to 512 bytes (1/8 of data size) and get WA as low as 2.375. + +Lazy fsync also reduces WA for parallel workloads because journal blocks are only +written when they fill up or fsync is requested. + +## In Practice + +In practice, using tests from [Understanding Performance](understanding.en.md) +and good server-grade SSD/NVMe drives, you should head for: +- At least 5000 T1Q1 replicated read and write iops (maximum 0.2ms latency) +- At least ~80k parallel read iops or ~30k write iops per 1 core (1 OSD) +- Disk-speed or wire-speed linear reads and writes, whichever is the bottleneck in your case + +Lower results may mean that you have bad drives, bad network or some kind of misconfiguration. diff --git a/docs/performance/theoretical.ru.md b/docs/performance/theoretical.ru.md new file mode 100644 index 00000000..9a95bded --- /dev/null +++ b/docs/performance/theoretical.ru.md @@ -0,0 +1,41 @@ +[Документация](../../README-ru.md#документация) → Производительность → Теоретическая максимальная производительность Vitastor + +----- + +[Read in English](theoretical.en.md) + +# Теоретическая максимальная производительность Vitastor + +При использовании репликации: +- Задержка чтения в 1 поток (T1Q1): 1 сетевой RTT + 1 чтение с диска. +- Запись+fsync в 1 поток: + - С мгновенным сбросом: 2 RTT + 1 запись. + - С отложенным ("ленивым") сбросом: 4 RTT + 1 запись + 1 fsync. +- Параллельное чтение: сумма IOPS всех дисков либо производительность сети, если в сеть упрётся раньше. +- Параллельная запись: сумма IOPS всех дисков / число реплик / WA либо производительность сети, если в сеть упрётся раньше. + +При использовании кодов коррекции ошибок (EC): +- Задержка чтения в 1 поток (T1Q1): 1.5 RTT + 1 чтение. +- Запись+fsync в 1 поток: + - С мгновенным сбросом: 3.5 RTT + 1 чтение + 2 записи. + - С отложенным ("ленивым") сбросом: 5.5 RTT + 1 чтение + 2 записи + 2 fsync. +- Под 0.5 на самом деле подразумевается (k-1)/k, где k - число дисков данных, + что означает, что дополнительное обращение по сети не нужно, когда операция + чтения обслуживается локально. +- Параллельное чтение: сумма IOPS всех дисков либо производительность сети, если в сеть упрётся раньше. +- Параллельная запись: сумма IOPS всех дисков / общее число дисков данных и чётности / WA либо производительность сети, если в сеть упрётся раньше. + Примечание: IOPS дисков в данном случае надо брать в смешанном режиме чтения/записи в пропорции, аналогичной формулам выше. + +WA (мультипликатор записи) для 4 КБ блоков в Vitastor обычно составляет 3-5: +1. Запись метаданных в журнал +2. Запись блока данных в журнал +3. Запись метаданных в БД +4. Ещё одна запись метаданных в журнал при использовании EC +5. Запись блока данных на диск данных + +Если вы найдёте SSD, хорошо работающий с 512-байтными блоками данных (Optane?), +то 1, 3 и 4 можно снизить до 512 байт (1/8 от размера данных) и получить WA всего 2.375. + +Кроме того, WA снижается при использовании отложенного/ленивого сброса при параллельной +нагрузке, т.к. блоки журнала записываются на диск только когда они заполняются или явным +образом запрашивается fsync. diff --git a/docs/performance/understanding.en.md b/docs/performance/understanding.en.md new file mode 100644 index 00000000..3191b703 --- /dev/null +++ b/docs/performance/understanding.en.md @@ -0,0 +1,57 @@ +[Documentation](../../README.md#documentation) → Performance → Understanding Storage Performance + +----- + +[Читать на русском](understanding.ru.md) + +# Understanding Storage Performance + +The most important thing for fast storage is latency, not parallel iops. + +The best possible latency is achieved with one thread and queue depth of 1 which basically means +"client load as low as possible". In this case IOPS = 1/latency, and this number doesn't +scale with number of servers, drives, server processes or threads and so on. +Single-threaded IOPS and latency numbers only depend on *how fast a single daemon is*. + +Why is it important? It's important because some of the applications *can't* use +queue depth greater than 1 because their task isn't parallelizable. A notable example +is any ACID DBMS because all of them write their WALs sequentially with fsync()s. + +fsync, by the way, is another important thing often missing in benchmarks. The point is +that drives have cache buffers and don't guarantee that your data is actually persisted +until you call fsync() which is translated to a FLUSH CACHE command by the OS. + +Desktop SSDs are very fast without fsync - NVMes, for example, can process ~80000 write +operations per second with queue depth of 1 without fsync - but they're really slow with +fsync because they have to actually write data to flash chips when you call fsync. Typical +number is around 1000-2000 iops with fsync. + +Server SSDs often have supercapacitors that act as a built-in UPS and allow the drive +to flush its DRAM cache to the persistent flash storage when a power loss occurs. +This makes them perform equally well with and without fsync. This feature is called +"Advanced Power Loss Protection" by Intel; other vendors either call it similarly +or directly as "Full Capacitor-Based Power Loss Protection". + +All software-defined storages that I currently know are slow in terms of latency. +Notable examples are Ceph and internal SDSes used by cloud providers like Amazon, Google, +Yandex and so on. They're all slow and can only reach ~0.3ms read and ~0.6ms 4 KB write latency +with best-in-slot hardware. + +And that's in the SSD era when you can buy an SSD that has ~0.04ms latency for 100 $. + +## fio commands + +I use the following 6 commands with small variations to benchmark block storage: + +- Linear write (results in MB/s): + `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4M -iodepth=32 -rw=write -runtime=60 -filename=/dev/sdX` +- Linear read (results in MB/s): + `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4M -iodepth=32 -rw=read -runtime=60 -filename=/dev/sdX` +- Random write latency (T1Q1, this hurts storages the most) (results in iops or milliseconds of latency): + `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=1 -fsync=1 -rw=randwrite -runtime=60 -filename=/dev/sdX` +- Random read latency (T1Q1) (results in iops or milliseconds of latency): + `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=1 -rw=randread -runtime=60 -filename=/dev/sdX` +- Parallel write iops (use numjobs=4 if a single CPU core is insufficient to saturate the load) (results only in iops): + `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=128 [-numjobs=4 -group_reporting] -rw=randwrite -runtime=60 -filename=/dev/sdX` +- Parallel read iops (use numjobs if a single CPU core is insufficient to saturate the load) (results only in iops): + `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=128 [-numjobs=4 -group_reporting] -rw=randread -runtime=60 -filename=/dev/sdX` diff --git a/docs/performance/understanding.ru.md b/docs/performance/understanding.ru.md new file mode 100644 index 00000000..63d46fce --- /dev/null +++ b/docs/performance/understanding.ru.md @@ -0,0 +1,65 @@ +[Документация](../../README-ru.md#документация) → Производительность → Понимание сути производительности систем хранения + +----- + +[Read in English](understanding.en.md) + +# Понимание сути производительности систем хранения + +Вкратце: для быстрой хранилки задержки важнее, чем пиковые iops-ы. + +Лучшая возможная задержка достигается при тестировании в 1 поток с глубиной очереди 1, +что приблизительно означает минимально нагруженное состояние кластера. В данном случае +IOPS = 1/задержка. Ни числом серверов, ни дисков, ни серверных процессов/потоков +задержка не масштабируется... Она зависит только от того, насколько быстро один +серверный процесс (и клиент) обрабатывают одну операцию. + +Почему задержки важны? Потому, что некоторые приложения *не могут* использовать глубину +очереди больше 1, ибо их задача не параллелизуется. Важный пример - это все СУБД +с поддержкой консистентности (ACID), потому что все они обеспечивают её через +журналирование, а журналы пишутся последовательно и с fsync() после каждой операции. + +fsync, кстати - это ещё одна очень важная вещь, про которую почти всегда забывают в тестах. +Смысл в том, что все современные диски имеют кэши/буферы записи и не гарантируют, что +данные реально физически записываются на носитель до того, как вы делаете fsync(), +который транслируется в команду сброса кэша операционной системой. + +Дешёвые SSD для настольных ПК и ноутбуков очень быстрые без fsync - NVMe диски, например, +могут обработать порядка 80000 операций записи в секунду с глубиной очереди 1 без fsync. +Однако с fsync, когда они реально вынуждены писать каждый блок данных во флеш-память, +они выжимают лишь 1000-2000 операций записи в секунду (число практически постоянное +для всех моделей SSD). + +Серверные SSD часто имеют суперконденсаторы, работающие как встроенный источник +бесперебойного питания и дающие дискам успеть сбросить их DRAM-кэш в постоянную +флеш-память при отключении питания. Благодаря этому диски с чистой совестью +*игнорируют fsync*, так как точно знают, что данные из кэша доедут до постоянной +памяти. + +Все наиболее известные программные СХД, например, Ceph и внутренние СХД, используемые +такими облачными провайдерами, как Amazon, Google, Яндекс, медленные в смысле задержки. +В лучшем случае они дают задержки от 0.3мс на чтение и 0.6мс на запись 4 КБ блоками +даже при условии использования наилучшего возможного железа. + +И это в эпоху SSD, когда вы можете пойти на рынок и купить там SSD, задержка которого +на чтение будет 0.1мс, а на запись - 0.04мс, за 100$ или даже дешевле. + +## Команды fio + +Когда мне нужно быстро протестировать производительность блочного устройства, я +использую следующие 6 команд, с небольшими вариациями: + +- Линейная запись (результаты в МБ/с): + `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4M -iodepth=32 -rw=write -runtime=60 -filename=/dev/sdX` +- Линейное чтение (результаты в МБ/с): + `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4M -iodepth=32 -rw=read -runtime=60 -filename=/dev/sdX` +- Запись в 1 поток (T1Q1) (результаты в iops или миллисекундах задержки): + `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=1 -fsync=1 -rw=randwrite -runtime=60 -filename=/dev/sdX` +- Чтение в 1 поток (T1Q1) (результаты в iops или миллисекундах задержки): + `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=1 -rw=randread -runtime=60 -filename=/dev/sdX` +- Параллельная запись (numjobs=4 использовать, когда 1 ядро CPU не может насытить диск) (результаты только в iops): + `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=128 [-numjobs=4 -group_reporting] -rw=randwrite -runtime=60 -filename=/dev/sdX` +- Параллельное чтение (numjobs - аналогично) (результаты только в iops): + `fio -ioengine=libaio -direct=1 -invalidate=1 -name=test -bs=4k -iodepth=128 [-numjobs=4 -group_reporting] -rw=randread -runtime=60 -filename=/dev/sdX` + +Почему нужно тестировать именно так - см. [тут](https://yourcmc.ru/wiki/Производительность_Ceph#.D0.9B.D0.B8.D1.80.D0.B8.D1.87.D0.B5.D1.81.D0.BA.D0.BE.D0.B5_.D0.BE.D1.82.D1.81.D1.82.D1.83.D0.BF.D0.BB.D0.B5.D0.BD.D0.B8.D0.B5). diff --git a/docs/usage/cli.en.md b/docs/usage/cli.en.md new file mode 100644 index 00000000..5328b1ac --- /dev/null +++ b/docs/usage/cli.en.md @@ -0,0 +1,206 @@ +[Documentation](../../README.md#documentation) → Usage → Vitastor CLI + +----- + +[Читать на русском](cli.ru.md) + +# Vitastor CLI + +vitastor-cli is a command-line tool for administrative tasks like image management. + +It supports the following commands: + +- [status](#status) +- [df](#df) +- [ls](#ls) +- [create](#create) +- [modify](#modify) +- [rm](#rm) +- [flatten](#flatten) +- [rm-data](#rm-data) +- [merge-data](#merge-data) +- [alloc-osd](#alloc-osd) +- [simple-offsets](#simple-offsets) + +Global options: + +``` +--etcd_address ADDR Etcd connection address +--iodepth N Send N operations in parallel to each OSD when possible (default 32) +--parallel_osds M Work with M osds in parallel when possible (default 4) +--progress 1|0 Report progress (default 1) +--cas 1|0 Use CAS writes for flatten, merge, rm (default is decide automatically) +--no-color Disable colored output +--json JSON output +``` + +## status + +`vitastor-cli status` + +Показать состояние кластера. + +Пример вывода: + +``` + cluster: + etcd: 1 / 1 up, 1.8 M database size + mon: 1 up, master stump + osd: 8 / 12 up + + data: + raw: 498.5 G used, 301.2 G / 799.7 G available, 399.8 G down + state: 156.6 G clean, 97.6 G misplaced + pools: 2 / 3 active + pgs: 30 active + 34 active+has_misplaced + 32 offline + + io: + client: 0 B/s rd, 0 op/s rd, 0 B/s wr, 0 op/s wr + rebalance: 989.8 M/s, 7.9 K op/s +``` + +## df + +`vitastor-cli df` + +Показать список пулов и занятое место. + +Пример вывода: + +``` +NAME SCHEME PGS TOTAL USED AVAILABLE USED% EFFICIENCY +testpool 2/1 32 100 G 34.2 G 60.7 G 39.23% 100% +size1 1/1 32 199.9 G 10 G 121.5 G 39.23% 100% +kaveri 2/1 32 0 B 10 G 0 B 100% 0% +``` + +В примере у пула "kaveri" эффективность равна нулю, так как все OSD выключены. + +## ls + +`vitastor-cli ls [-l] [-p POOL] [--sort FIELD] [-r] [-n N] [ ...]` + +Показать список образов, если переданы шаблоны ``, то только с именами, +соответствующими этим шаблонам (стандартные ФС-шаблоны с * и ?). + +Опции: + +``` +-p|--pool POOL Фильтровать образы по пулу (ID или имени) +-l|--long Также выводить статистику занятого места и ввода-вывода +--del Также выводить статистику операций удаления +--sort FIELD Сортировать по заданному полю (name, size, used_size, _) +-r|--reverse Сортировать в обратном порядке +-n|--count N Показывать только первые N записей +``` + +Пример вывода: + +``` +NAME POOL SIZE USED READ IOPS QUEUE LAT WRITE IOPS QUEUE LAT FLAGS PARENT +debian9 testpool 20 G 12.3 G 0 B/s 0 0 0 us 0 B/s 0 0 0 us RO +pve/vm-100-disk-0 testpool 20 G 0 B 0 B/s 0 0 0 us 0 B/s 0 0 0 us - debian9 +pve/base-101-disk-0 testpool 20 G 0 B 0 B/s 0 0 0 us 0 B/s 0 0 0 us RO debian9 +pve/vm-102-disk-0 testpool 32 G 36.4 M 0 B/s 0 0 0 us 0 B/s 0 0 0 us - pve/base-101-disk-0 +debian9-test testpool 20 G 36.6 M 0 B/s 0 0 0 us 0 B/s 0 0 0 us - debian9 +bench testpool 10 G 10 G 0 B/s 0 0 0 us 0 B/s 0 0 0 us - +bench-kaveri kaveri 10 G 10 G 0 B/s 0 0 0 us 0 B/s 0 0 0 us - +``` + +## create + +`vitastor-cli create -s|--size [-p|--pool ] [--parent [@]] ` + +Создать образ. Для размера `` можно использовать суффиксы K/M/G/T (килобайт-мегабайт-гигабайт-терабайт). +Если указана опция `--parent`, создаётся клон образа. Родитель `[@]` должен быть +снимком (или просто немодифицируемым образом). Пул обязательно указывать, если в кластере больше одного пула. + +``` +vitastor-cli create --snapshot [-p|--pool ] +vitastor-cli snap-create [-p|--pool ] @ +``` + +Создать снимок образа `` (можно использовать любую форму команды). Снимок можно создавать без остановки +клиентов, если пишущий клиент максимум 1. + +## modify + +`vitastor-cli modify [--rename ] [--resize ] [--readonly | --readwrite] [-f|--force]` + +Изменить размер, имя образа или флаг "только для чтения". Снимать флаг "только для чтения" +и уменьшать размер образов, у которых есть дочерние клоны, без `--force` нельзя. + +Если новый размер меньше старого, "лишние" данные будут удалены, поэтому перед уменьшением +образа сначала уменьшите файловую систему в нём. + +``` +-f|--force Разрешить уменьшение или перевод в чтение-запись образа, у которого есть клоны. +``` + +## rm + +`vitastor-cli rm [] [--writers-stopped]` + +Удалить образ `` или все слои от `` до `` (`` должен быть дочерним +образом ``), одновременно меняя родительские образы их клонов (если таковые есть). + +`--writers-stopped` позволяет чуть более эффективно удалять образы в частом случае, когда +у удаляемой цепочки есть только один дочерний образ, содержащий небольшой объём данных. +В этом случае дочерний образ вливается в родительский и удаляется, а родительский +переименовывается в дочерний. + +В других случаях родительские слои вливаются в дочерние. + +## flatten + +`vitastor-cli flatten ` + +Сделай образ `` плоским, то есть, скопировать в него данные и разорвать его +соединение с родительскими. + +## rm-data + +`vitastor-cli rm-data --pool --inode [--wait-list] [--min-offset ]` + +Удалить данные инода, не меняя метаданные образов. + +``` +--wait-list Сначала запросить полный листинг объектов, а потом начать удалять. + Требует больше памяти, но позволяет правильно печатать прогресс удаления. +--min-offset Удалять только данные, начиная с заданного смещения. +``` + +## merge-data + +`vitastor-cli merge-data [--target ]` + +Слить данные слоёв, не меняя метаданные. Вливает данные из слоёв от `` до `` +в целевой образ ``. `` должен быть дочерним образом ``, а `` +должен быть одним из слоёв между `` и ``, включая сами `` и ``. + +## alloc-osd + +`vitastor-cli alloc-osd` + +Атомарно выделить новый номер OSD и зарезервировать его, создав в etcd пустой +ключ `/osd/stats/`. + +## simple-offsets + +`vitastor-cli simple-offsets ` + +Рассчитать смещения для простого и тупого создания OSD на диске (без суперблока). + +Опции (см. также [Дисковые параметры уровня кластера](../config/layout-cluster.ru.md)): + +``` +--object_size 128k Размер блока хранилища +--bitmap_granularity 4k Гранулярность битовых карт +--journal_size 32M Размер журнала +--device_block_size 4k Размер блока устройства +--journal_offset 0 Смещение журнала +--device_size 0 Размер устройства +--format text Формат результата: json, options, env или text +``` diff --git a/docs/usage/cli.ru.md b/docs/usage/cli.ru.md new file mode 100644 index 00000000..8fbabdce --- /dev/null +++ b/docs/usage/cli.ru.md @@ -0,0 +1,197 @@ +[Документация](../../README-ru.md#документация) → Использование → Консольный интерфейс Vitastor + +----- + +[Read in English](cli.en.md) + +# Консольный интерфейс Vitastor + +vitastor-cli - интерфейс командной строки для административных задач, таких, как +управление образами дисков. + +Поддерживаются следующие команды: + +- [status](#status) +- [df](#df) +- [ls](#ls) +- [create](#create) +- [modify](#modify) +- [rm](#rm) +- [flatten](#flatten) +- [rm-data](#rm-data) +- [merge-data](#merge-data) +- [alloc-osd](#alloc-osd) +- [simple-offsets](#simple-offsets) + +Глобальные опции: + +``` +--etcd_address ADDR Адрес соединения с etcd +--iodepth N Отправлять параллельно N операций на каждый OSD (по умолчанию 32) +--parallel_osds M Работать параллельно с M OSD (по умолчанию 4) +--progress 1|0 Печатать прогресс выполнения (по умолчанию 1) +--cas 1|0 Для команд flatten, merge, rm - использовать CAS при записи (по умолчанию - решение принимается автоматически) +--no-color Отключить цветной вывод +--json Включить JSON-вывод +``` + +## status + +`vitastor-cli status` + +Show cluster status. + +Example output: + +``` + cluster: + etcd: 1 / 1 up, 1.8 M database size + mon: 1 up, master stump + osd: 8 / 12 up + + data: + raw: 498.5 G used, 301.2 G / 799.7 G available, 399.8 G down + state: 156.6 G clean, 97.6 G misplaced + pools: 2 / 3 active + pgs: 30 active + 34 active+has_misplaced + 32 offline + + io: + client: 0 B/s rd, 0 op/s rd, 0 B/s wr, 0 op/s wr + rebalance: 989.8 M/s, 7.9 K op/s +``` + +## df + +`vitastor-cli df` + +Show pool space statistics. + +Example output: + +``` +NAME SCHEME PGS TOTAL USED AVAILABLE USED% EFFICIENCY +testpool 2/1 32 100 G 34.2 G 60.7 G 39.23% 100% +size1 1/1 32 199.9 G 10 G 121.5 G 39.23% 100% +kaveri 2/1 32 0 B 10 G 0 B 100% 0% +``` + +In the example above, "kaveri" pool has "zero" efficiency because all its OSD are down. + +## ls + +`vitastor-cli ls [-l] [-p POOL] [--sort FIELD] [-r] [-n N] [ ...]` + +List images (only matching `` pattern(s) if passed). + +Options: + +``` +-p|--pool POOL Filter images by pool ID or name +-l|--long Also report allocated size and I/O statistics +--del Also include delete operation statistics +--sort FIELD Sort by specified field (name, size, used_size, _) +-r|--reverse Sort in descending order +-n|--count N Only list first N items +``` + +Example output: + +``` +NAME POOL SIZE USED READ IOPS QUEUE LAT WRITE IOPS QUEUE LAT FLAGS PARENT +debian9 testpool 20 G 12.3 G 0 B/s 0 0 0 us 0 B/s 0 0 0 us RO +pve/vm-100-disk-0 testpool 20 G 0 B 0 B/s 0 0 0 us 0 B/s 0 0 0 us - debian9 +pve/base-101-disk-0 testpool 20 G 0 B 0 B/s 0 0 0 us 0 B/s 0 0 0 us RO debian9 +pve/vm-102-disk-0 testpool 32 G 36.4 M 0 B/s 0 0 0 us 0 B/s 0 0 0 us - pve/base-101-disk-0 +debian9-test testpool 20 G 36.6 M 0 B/s 0 0 0 us 0 B/s 0 0 0 us - debian9 +bench testpool 10 G 10 G 0 B/s 0 0 0 us 0 B/s 0 0 0 us - +bench-kaveri kaveri 10 G 10 G 0 B/s 0 0 0 us 0 B/s 0 0 0 us - +``` + +## create + +`vitastor-cli create -s|--size [-p|--pool ] [--parent [@]] ` + +Create an image. You may use K/M/G/T suffixes for ``. If `--parent` is specified, +a copy-on-write image clone is created. Parent must be a snapshot (readonly image). +Pool must be specified if there is more than one pool. + +``` +vitastor-cli create --snapshot [-p|--pool ] +vitastor-cli snap-create [-p|--pool ] @ +``` + +Create a snapshot of image `` (either form can be used). May be used live if only a single writer is active. + +## modify + +`vitastor-cli modify [--rename ] [--resize ] [--readonly | --readwrite] [-f|--force]` + +Rename, resize image or change its readonly status. Images with children can't be made read-write. +If the new size is smaller than the old size, extra data will be purged. +You should resize file system in the image, if present, before shrinking it. + +``` +-f|--force Proceed with shrinking or setting readwrite flag even if the image has children. +``` + +## rm + +`vitastor-cli rm [] [--writers-stopped]` + +Remove `` or all layers between `` and `` (`` must be a child of ``), +rebasing all their children accordingly. --writers-stopped allows merging to be a bit +more effective in case of a single 'slim' read-write child and 'fat' removed parent: +the child is merged into parent and parent is renamed to child in that case. +In other cases parent layers are always merged into children. + +## flatten + +`vitastor-cli flatten ` + +Flatten a layer, i.e. merge data and detach it from parents. + +## rm-data + +`vitastor-cli rm-data --pool --inode [--wait-list] [--min-offset ]` + +Remove inode data without changing metadata. + +``` +--wait-list Retrieve full objects listings before starting to remove objects. + Requires more memory, but allows to show correct removal progress. +--min-offset Purge only data starting with specified offset. +``` + +## merge-data + +`vitastor-cli merge-data [--target ]` + +Merge layer data without changing metadata. Merge ``..`` to ``. +`` must be a child of `` and `` may be one of the layers between +`` and ``, including `` and ``. + +## alloc-osd + +`vitastor-cli alloc-osd` + +Allocate a new OSD number and reserve it by creating empty `/osd/stats/` key. + +## simple-offsets + +`vitastor-cli simple-offsets ` + +Calculate offsets for simple&stupid (no superblock) OSD deployment. + +Options (see also [Cluster-Wide Disk Layout Parameters](../config/layout-cluster.en.md)): + +``` +--object_size 128k Set blockstore block size +--bitmap_granularity 4k Set bitmap granularity +--journal_size 32M Set journal size +--device_block_size 4k Set device block size +--journal_offset 0 Set journal offset +--device_size 0 Set device size +--format text Result format: json, options, env, or text +``` diff --git a/docs/usage/fio.en.md b/docs/usage/fio.en.md new file mode 100644 index 00000000..90ffb147 --- /dev/null +++ b/docs/usage/fio.en.md @@ -0,0 +1,23 @@ +[Documentation](../../README.md#documentation) → Usage → fio driver + +----- + +[Читать на русском](fio.ru.md) + +# fio driver + +[fio](https://fio.readthedocs.io/en/latest/fio_doc.html) (Flexible I/O tester) is the +best utility for benchmarking block devices. + +Vitastor has a fio driver which can be installed from the package vitastor-fio. + +Use the following command as an example to run tests with fio against a Vitastor cluster: + +``` +fio -thread -ioengine=libfio_vitastor.so -name=test -bs=4M -direct=1 -iodepth=16 -rw=write -etcd=10.115.0.10:2379/v3 -image=testimg +``` + +If you don't want to access your image by name, you can specify pool number, inode number and size +(`-pool=1 -inode=1 -size=400G`) instead of the image name (`-image=testimg`). + +See exact fio commands to use for benchmarking [here](../performance/understanding.en.md#команды-fio). diff --git a/docs/usage/fio.ru.md b/docs/usage/fio.ru.md new file mode 100644 index 00000000..27b62425 --- /dev/null +++ b/docs/usage/fio.ru.md @@ -0,0 +1,23 @@ +[Документация](../../README-ru.md#документация) → Использование → Драйвер fio + +----- + +[Read in English](fio.en.md) + +# Драйвер fio + +[fio](https://fio.readthedocs.io/en/latest/fio_doc.html) (Flexible I/O tester) - лучшая +актуальная утилита для тестирования производительности блочных устройств. + +В Vitastor есть драйвер для fio, устанавливаемый из пакета vitastor-fio. + +Используйте следующую команду как пример для запуска тестов кластера Vitastor через fio: + +``` +fio -thread -ioengine=libfio_vitastor.so -name=test -bs=4M -direct=1 -iodepth=16 -rw=write -etcd=10.115.0.10:2379/v3 -image=testimg +``` + +Вместо обращения к образу по имени (`-image=testimg`) можно указать номер пула, номер инода и размер: +`-pool=1 -inode=1 -size=400G`. + +Конкретные команды fio для тестирования производительности можно посмотреть [здесь](../performance/understanding.ru.md#команды-fio). diff --git a/docs/usage/nbd.en.md b/docs/usage/nbd.en.md new file mode 100644 index 00000000..7cc89f5d --- /dev/null +++ b/docs/usage/nbd.en.md @@ -0,0 +1,34 @@ +[Documentation](../../README.md#documentation) → Usage → NBD + +----- + +[Читать на русском](nbd.ru.md) + +# NBD + +NBD stands for "Network Block Device", but in fact it also functions as "BUSE" +(Block Device in UserSpace). NBD is currently required to mount Vitastor via kernel. +NBD slighly lowers the performance due to additional overhead, but performance still +remains decent (see an example [here](../performance/comparison1.en.md#vitastor-0-4-0-nbd)). + +Vitastor Kubernetes CSI driver is based on NBD. + +## Map image + +To create a local block device for a Vitastor image run: + +``` +vitastor-nbd map --etcd_address 10.115.0.10:2379/v3 --image testimg +``` + +It will output a block device name like /dev/nbd0 which you can then use as a normal disk. + +You can also use `--pool --inode --size ` instead of `--image ` if you want. + +## Unmap image + +To unmap the device run: + +``` +vitastor-nbd unmap /dev/nbd0 +``` diff --git a/docs/usage/nbd.ru.md b/docs/usage/nbd.ru.md new file mode 100644 index 00000000..a562f18f --- /dev/null +++ b/docs/usage/nbd.ru.md @@ -0,0 +1,39 @@ +[Документация](../../README-ru.md#документация) → Использование → NBD + +----- + +[Read in English](nbd.en.md) + +# NBD + +NBD расшифровывается как "сетевое блочное устройство", но на самом деле оно также +работает просто как аналог FUSE для блочных устройств, то есть, представляет собой +"блочное устройство в пространстве пользователя". + +NBD на данный момент необходимо, чтобы монтировать диски Vitastor ядром Linux. +NBD немного снижает производительность из-за дополнительных копирований памяти, +но она всё равно остаётся на неплохом уровне (см. для примера [тест](../performance/comparison1.ru.md#vitastor-0-4-0-nbd)). + +CSI-драйвер Kubernetes Vitastor основан на NBD. + +## Подключить устройство + +Чтобы создать локальное блочное устройство для образа, выполните команду: + +``` +vitastor-nbd map --etcd_address 10.115.0.10:2379/v3 --image testimg +``` + +Команда напечатает название блочного устройства вида /dev/nbd0, которое потом можно +будет использовать как обычный диск. + +Для обращения по номеру инода, аналогично другим командам, можно использовать опции +`--pool --inode --size ` вместо `--image testimg`. + +## Отключить устройство + +Для отключения устройства выполните: + +``` +vitastor-nbd unmap /dev/nbd0 +``` diff --git a/docs/usage/nfs.en.md b/docs/usage/nfs.en.md new file mode 100644 index 00000000..cafdea6a --- /dev/null +++ b/docs/usage/nfs.en.md @@ -0,0 +1,45 @@ +[Documentation](../../README.md#documentation) → Usage → NFS + +----- + +[Читать на русском](nfs.ru.md) + +# NFS + +Vitastor has a simplified NFS 3.0 proxy for file-based image access emulation. It's not +suitable as a full-featured file system, at least because all file/image metadata is stored +in etcd and kept in memory all the time - thus you can't put a lot of files in it. + +However, NFS proxy is totally fine as a method to provide VM image access and allows to +plug Vitastor into, for example, VMWare. It's important to note that for VMWare it's a much +better access method than iSCSI, because with iSCSI we'd have to put all VM images into one +Vitastor image exported as a LUN to VMWare and formatted with VMFS. VMWare doesn't use VMFS +over NFS. + +NFS proxy is stateless if you use immediate_commit=all mode (for SSD with capacitors or +HDDs with disabled cache), so you can run multiple NFS proxies and use a network load +balancer or any failover method you want to in that case. + +vitastor-nfs usage: + +``` +vitastor-nfs [--etcd_address ADDR] [OTHER OPTIONS] + +--subdir export images prefixed / (default empty - export all images) +--portmap 0 do not listen on port 111 (portmap/rpcbind, requires root) +--bind bind service to address (default 0.0.0.0) +--nfspath set NFS export path to (default is /) +--port use port for NFS services (default is 2049) +--pool use as default pool for new files (images) +--foreground 1 stay in foreground, do not daemonize +``` + +Example start and mount commands: + +``` +vitastor-nfs --etcd_address 192.168.5.10:2379 --portmap 0 --port 2050 --pool testpool +``` + +``` +mount localhost:/ /mnt/ -o port=2050,mountport=2050,nfsvers=3,soft,nolock,tcp +``` diff --git a/docs/usage/nfs.ru.md b/docs/usage/nfs.ru.md new file mode 100644 index 00000000..25088025 --- /dev/null +++ b/docs/usage/nfs.ru.md @@ -0,0 +1,44 @@ +[Документация](../../README-ru.md#документация) → Использование → NFS + +----- + +[Read in English](nfs.en.md) + +# NFS + +В Vitastor реализована упрощённая NFS 3.0 прокси для эмуляции файлового доступа к образам. +Это не полноценная файловая система, т.к. метаданные всех файлов (образов) сохраняются +в etcd и всё время хранятся в оперативной памяти - то есть, положить туда много файлов +не получится. + +Однако в качестве способа доступа к образам виртуальных машин NFS прокси прекрасно подходит +и позволяет подключить Vitastor, например, к VMWare. + +При этом, если вы используете режим immediate_commit=all (для SSD с конденсаторами или HDD +с отключённым кэшем), то NFS-сервер не имеет состояния и вы можете свободно поднять +его в нескольких экземплярах и использовать поверх них сетевой балансировщик нагрузки или +схему с отказоустойчивостью. + +Использование vitastor-nfs: + +``` +vitastor-nfs [--etcd_address ADDR] [ДРУГИЕ ОПЦИИ] + +--subdir экспортировать "поддиректорию" - образы с префиксом имени / (по умолчанию пусто - экспортировать все образы) +--portmap 0 отключить сервис portmap/rpcbind на порту 111 (по умолчанию включён и требует root привилегий) +--bind принимать соединения по адресу (по умолчанию 0.0.0.0 - на всех) +--nfspath установить путь NFS-экспорта в (по умолчанию /) +--port использовать порт для NFS-сервисов (по умолчанию 2049) +--pool исползовать пул для новых образов (обязательно, если пул в кластере не один) +--foreground 1 не уходить в фон после запуска +``` + +Пример монтирования Vitastor через NFS: + +``` +vitastor-nfs --etcd_address 192.168.5.10:2379 --portmap 0 --port 2050 --pool testpool +``` + +``` +mount localhost:/ /mnt/ -o port=2050,mountport=2050,nfsvers=3,soft,nolock,tcp +``` diff --git a/docs/usage/qemu.en.md b/docs/usage/qemu.en.md new file mode 100644 index 00000000..525c0d94 --- /dev/null +++ b/docs/usage/qemu.en.md @@ -0,0 +1,48 @@ +[Documentation](../../README.md#documentation) → Usage → QEMU and qemu-img + +----- + +[Читать на русском](qemu.ru.md) + +# QEMU and qemu-img + +## QEMU + +You need patched QEMU version to use Vitastor driver. Pre-built [packages](../installation/packages.en.md) are available. + +To start a VM using plain QEMU command-line with Vitastor disk, use the following commands: + +Old syntax (-drive): + +``` +qemu-system-x86_64 -enable-kvm -m 1024 \ + -drive 'file=vitastor:etcd_host=192.168.7.2\:2379/v3:image=debian9', + format=raw,if=none,id=drive-virtio-disk0,cache=none \ + -device 'virtio-blk-pci,scsi=off,bus=pci.0,addr=0x5,drive=drive-virtio-disk0, + id=virtio-disk0,bootindex=1,write-cache=off' \ + -vnc 0.0.0.0:0 +``` + +New syntax (-blockdev): + +``` +qemu-system-x86_64 -enable-kvm -m 1024 \ + -blockdev '{"node-name":"drive-virtio-disk0","driver":"vitastor","image":"debian9", + "cache":{"direct":true,"no-flush":false},"auto-read-only":true,"discard":"unmap"}' \ + -device 'virtio-blk-pci,scsi=off,bus=pci.0,addr=0x5,drive=drive-virtio-disk0, + id=virtio-disk0,bootindex=1,write-cache=off' \ + -vnc 0.0.0.0:0 +``` + +## qemu-img + +For qemu-img, you should use `vitastor:etcd_host=:image=` as filename. + +For example, to upload a VM image into Vitastor, run: + +``` +qemu-img convert -f qcow2 debian10.qcow2 -p -O raw 'vitastor:etcd_host=192.168.7.2\:2379/v3:image=debian10' +``` + +You can also specify `:pool=:inode=:size=` instead of `:image=` +if you don't want to use inode metadata. diff --git a/docs/usage/qemu.ru.md b/docs/usage/qemu.ru.md new file mode 100644 index 00000000..a73d532f --- /dev/null +++ b/docs/usage/qemu.ru.md @@ -0,0 +1,52 @@ +[Документация](../../README-ru.md#документация) → Использование → QEMU и qemu-img + +----- + +[Read in English](qemu.en.md) + +# QEMU и qemu-img + +## QEMU + +Чтобы использовать Vitastor-диски в QEMU, вам нужна доработанная версия QEMU. +Её можно установить [из пакетов](../installation/packages.ru.md). + +Для ручного запуска виртуальной машины QEMU из командной строки с Vitastor-диском +используйте один из следующих вариантов команд: + +Старый синтаксис (-drive): + +``` +qemu-system-x86_64 -enable-kvm -m 1024 \ + -drive 'file=vitastor:etcd_host=192.168.7.2\:2379/v3:image=debian9', + format=raw,if=none,id=drive-virtio-disk0,cache=none \ + -device 'virtio-blk-pci,scsi=off,bus=pci.0,addr=0x5,drive=drive-virtio-disk0, + id=virtio-disk0,bootindex=1,write-cache=off' \ + -vnc 0.0.0.0:0 +``` + +Новый синтаксис (-blockdev): + +``` +qemu-system-x86_64 -enable-kvm -m 1024 \ + -blockdev '{"node-name":"drive-virtio-disk0","driver":"vitastor","image":"debian9", + "cache":{"direct":true,"no-flush":false},"auto-read-only":true,"discard":"unmap"}' \ + -device 'virtio-blk-pci,scsi=off,bus=pci.0,addr=0x5,drive=drive-virtio-disk0, + id=virtio-disk0,bootindex=1,write-cache=off' \ + -vnc 0.0.0.0:0 +``` + +Вместо `:image=` также можно указывать номер инода, пул и размер: `:pool=:inode=:size=`. + +## qemu-img + +Для qemu-img используйте строку `vitastor:etcd_host=:image=` в качестве имени файла диска. + +Например, чтобы загрузить образ диска в Vitastor: + +``` +qemu-img convert -f qcow2 debian10.qcow2 -p -O raw 'vitastor:etcd_host=10.115.0.10\:2379/v3:image=testimg' +``` + +Если вы не хотите обращаться к образу по имени, вместо `:image=` можно указать номер пула, номер инода и размер: +`:pool=:inode=:size=`. diff --git a/src/cli.cpp b/src/cli.cpp index 44af0449..fefc99a3 100644 --- a/src/cli.cpp +++ b/src/cli.cpp @@ -155,7 +155,7 @@ static void help() " --iodepth N Send N operations in parallel to each OSD when possible (default 32)\n" " --parallel_osds M Work with M osds in parallel when possible (default 4)\n" " --progress 1|0 Report progress (default 1)\n" - " --cas 1|0 Use online CAS writes when possible (default auto)\n" + " --cas 1|0 Use CAS writes for flatten, merge, rm (default is decide automatically)\n" " --no-color Disable colored output\n" " --json JSON output\n" ,