Add administration docs

2024-03-31 01:15:46 +03:00 · 2024-03-31 01:15:46 +03:00 · 5d3aaf016b
parent 0b097ca3f2
commit 5d3aaf016b
8 changed files with 559 additions and 0 deletions
--- a/README-ru.md
+++ b/README-ru.md
@ -64,6 +64,7 @@ Vitastor поддерживает QEMU-драйвер, протоколы NBD и
  - [NBD](docs/usage/nbd.ru.md) для монтирования ядром
  - [QEMU и qemu-img](docs/usage/qemu.ru.md)
  - [NFS](docs/usage/nfs.ru.md) кластерная файловая система и псевдо-ФС прокси
+  - [Администрирование](docs/usage/admin.ru.md)
 - Производительность
  - [Понимание сути производительности](docs/performance/understanding.ru.md)
  - [Теоретический максимум](docs/performance/theoretical.ru.md)
--- a/README.md
+++ b/README.md
@ -64,6 +64,7 @@ Read more details below in the documentation.
  - [NBD](docs/usage/nbd.en.md) for kernel mounts
  - [QEMU and qemu-img](docs/usage/qemu.en.md)
  - [NFS](docs/usage/nfs.en.md) clustered file system and pseudo-FS proxy
+  - [Administration](docs/usage/admin.en.md)
 - Performance
  - [Understanding storage performance](docs/performance/understanding.en.md)
  - [Theoretical performance](docs/performance/theoretical.en.md)
--- a/docs/config/src/included.en.md
+++ b/docs/config/src/included.en.md
@ -56,6 +56,8 @@

 {{../../usage/nfs.en.md}}

+{{../../usage/admin.en.md}}
+
 ## Performance

 {{../../performance/understanding.en.md}}
--- a/docs/config/src/included.ru.md
+++ b/docs/config/src/included.ru.md
@ -56,6 +56,8 @@

 {{../../usage/nfs.ru.md}}

+{{../../usage/admin.ru.md}}
+
 ## Производительность

 {{../../performance/understanding.ru.md}}
--- a/docs/usage/admin.en.md
+++ b/docs/usage/admin.en.md
@ -0,0 +1,215 @@
+[Documentation](../../README.md#documentation) → Usage → Administration
+
+-----
+
+[Читать на русском](admin.ru.md)
+
+# Administration
+
+- [Pool states](#pool-states)
+- [PG states](#pg-states)
+  - [Base PG states](#base-pg-states)
+  - [Additional PG states](#additional-pg-states)
+- [Removing a healthy disk](#removing-a-healthy-disk)
+- [Removing a failed disk](#removing-a-failed-disk)
+- [Adding a disk](#adding-a-disk)
+- [Restoring from lost pool configuration](#restoring-from-lost-pool-configuration)
+- [Upgrading Vitastor](#upgrading-vitastor)
+- [OSD memory usage](#osd-memory-usage)
+
+## Pool states
+
+Pool is active — that is, fully available for client input/output — when all its PGs are
+'active' (maybe with some additional state flags).
+
+If at least 1 PG is inactive, pool is also inactive and all clients suspend their I/O and
+wait until you fix the cluster. :-)
+
+## PG states
+
+PG states may be seen in [vitastor-cli status](cli.en.md#status) output.
+
+PG state consists of exactly 1 base state and an arbitrary number of additional states.
+
+### Base PG states
+
+PG state always includes exactly 1 of the following base states:
+- **active** — PG is active and handles user I/O.
+- **incomplete** — Not enough OSDs are available to activate this PG. That is, more disks
+  are lost than it's allowed by the pool's redundancy scheme. For example, if the pool has
+  pg_size=3 and pg_minsize=1, part of the data may be written only to 1 OSD. If that exact
+  OSD is lost, PG will become **incomplete**.
+- **offline** — PG isn't activated by any OSD at all. Either primary OSD isn't set for
+  this PG at all (if the pool is just created), or an unavailable OSD is set as primary,
+  or the primary OSD refuses to start this PG (for example, because of wrong block_size),
+  or the PG is stopped by the monitor using `pause: true` flag in `/vitastor/config/pgs` in etcd.
+- **starting** — primary OSD has acquired PG lock in etcd, PG is starting.
+- **peering** — primary OSD requests PG object listings from secondary OSDs and calculates
+  the PG state.
+- **repeering** — PG is waiting for current I/O operations to complete and will
+  then transition to **peering**.
+- **stopping** — PG is waiting for current I/O operations to complete and will
+  then transition to **offline** or be activated by another OSD.
+
+All states except **active** mean that PG is inactive and client I/O is suspended.
+
+**peering** state is normally visible only for a short period of time during OSD restarts
+and during switching primary OSD of PGs.
+
+**starting**, **repeering**, **stopping** states normally almost aren't visible at all.
+If you notice them for any noticeable time — chances are some operations on some OSDs hung.
+Search for "slow op" in OSD logs to find them — operations hung for more than
+[slow_log_interval](../config/osd.en.md#slow_log_interval) are logged as "slow ops".
+
+State transition diagram:
+
+![PG state transitions](pg_states.svg "PG state transitions")
+
+### Additional PG states
+
+If a PG is active it can also have any number of the following additional states:
+
+- **degraded** — PG is running on reduced number of drives (OSDs), redundancy of all
+  objects in this PG is reduced.
+- **has_incomplete** — some objects in this PG are incomplete (unrecoverable), that is,
+  they have too many lost EC parts (more than pool's [parity_chunks](../config/pool.en.md#parity_chunks)).
+- **has_degraded** — some objects in this PG have reduced redundancy
+  compared to the rest of the PG (so PG can be degraded+has_degraded at the same time).
+  These objects should be healed automatically by recovery process, unless
+  it's disabled by [no_recovery](../config/osd.en.md#no_recovery).
+- **has_misplaced** — some objects in this PG are stored on an OSD set different from
+  the target set of the PG. These objects should be moved automatically, unless
+  rebalance is disabled by [no_rebalance](../config/osd.en.md#no_rebalance). Objects
+  that are degraded and misplaced at the same time are treated as just degraded.
+- **has_unclean** — one more state normally noticeable only for very short time during
+  PG activation. It's used only with EC pools and means that some objects of this PG
+  have started but not finished modifications. All such objects are either quickly
+  committed or rolled back by the primary OSD when starting the PG, that is why the
+  state shouldn't be noticeable. If you notice it, it probably means that commit or
+  rollback operations are hung.
+- **has_invalid** — PG contains objects with incorrect part ID. Never occurs normally.
+  It can only occur if you delete a non-empty EC pool and then recreate it as a replica
+  pool or with smaller data part count.
+- **has_corrupted** — PG has corrupted objects, discovered by checking checksums during
+  read or during scrub. When possible, such objects should be recovered automatically.
+  If objects remain corrupted, use [vitastor-cli describe](cli.en.md#describe) to find
+  out details and/or look into the log of the primary OSD of the PG.
+- **has_inconsistent** — PG has objects with non-matching parts or copies on different OSDs,
+  and it's impossible to determine which copy is correct automatically. It may happen
+  if you use a pool with 2 replica and you don't enable checksums, and if data on one
+  of replicas becomes corrupted. You should also use vitastor-cli [describe](cli.en.md#describe)
+  and [fix](cli.en.md#fix) commands to remove the incorrect version in this case.
+- **left_on_dead** — part of the data of this PG is left on unavailable OSD that isn't
+  fully removed from the cluster. You should either start the corresponding OSD back and
+  let it remove the unneeded data or remove it from cluster using vitastor-cli
+  [rm-osd](cli.en.md#rm-osd) if you know that it's gone forever (for example, if the disk died).
+- **scrubbing** — data [scrub](../config/osd.en.md#auto_scrub) is running for this PG.
+
+## Removing a healthy disk
+
+Befor removing a healthy disk from the cluster set its OSD weight(s) to 0 to
+move data away. To do that, add `"reweight":0` to etcd key `/vitastor/config/osd/<OSD_NUMBER>`.
+For example:
+
+```
+etcdctl --endpoints=http://1.1.1.1:2379/v3 put /vitastor/config/osd/1 '{"reweight":0}'
+```
+
+Then wait until rebalance finishes and remove OSD by running `vitastor-disk purge /dev/vitastor/osdN-data`.
+
+## Removing a failed disk
+
+If a disk is already dead, its OSD(s) are likely already stopped.
+
+In this case just remove OSD(s) from the cluster by running `vitastor-cli rm-osd OSD_NUMBER`.
+
+## Adding a disk
+
+If you're adding a server, first install Vitastor packages and copy the
+`/etc/vitastor/vitastor.conf` configuration file to it.
+
+After that you can just run `vitastor-disk prepare /dev/nvmeXXX`, of course with
+the same parameters which you used for other OSDs in your cluster before.
+
+## Restoring from lost pool configuration
+
+If you remove or corrupt `/vitastor/config/pools` key in etcd all pools will
+be deleted. Don't worry, the data won't be lost, but you'll need to perform
+a specific recovery procedure.
+
+First you need to restore previous configuration of the pool with the same ID
+and EC/replica parameters and wait until pool PGs appear in `vitastor-cli status`.
+
+Then add all OSDs into the history records of all PGs. You can do it by running
+the following script (just don't forget to use your own PG_COUNT and POOL_ID):
+
+```
+PG_COUNT=32
+POOL_ID=1
+ALL_OSDS=$(etcdctl --endpoints=your_etcd_address:2379 get --keys-only --prefix /vitastor/osd/stats/ | \
+    perl -e '$/ = undef; $a = <>; $a =~ s/\s*$//; $a =~ s!/vitastor/osd/stats/!!g; $a =~ s/\s+/,/g; print $a')
+for i in $(seq 1 $PG_COUNT); do
+    etcdctl --endpoints=your_etcd_address:2379 put /vitastor/pg/history/$POOL_ID/$i '{"all_peers":['$ALL_OSDS']}'; done
+done
+```
+
+After that all PGs should peer and find all previous data.
+
+## Upgrading Vitastor
+
+Every upcoming Vitastor version is usually compatible with previous both forward
+and backward regarding the network protocol and etcd data structures.
+
+So, by default, if this page doesn't contain explicit different instructions, you
+can upgrade your Vitastor cluster by simply upgrading packages and restarting all
+OSDs and monitors in any order.
+
+Upgrading is performed without stopping clients (VMs/containers), you just need to
+upgrade and restart servers one by one. However, ideally you should restart VMs too
+to make them use the new version of the client library.
+
+Exceptions (specific upgrade instructions):
+- Upgrading <= 1.1.x to 1.2.0 or later, if you use EC n+k with k>=2, is recommended
+  to be performed with full downtime: first you should stop all clients, then all OSDs,
+  then upgrade and start everything back — because versions before 1.2.0 have several
+  bugs leading to invalid data being read in EC n+k, k>=2 configurations in degraded pools.
+- Versions <= 0.8.7 are incompatible with versions >= 0.9.0, so you should first
+  upgrade from <= 0.8.7 to 0.8.8 or 0.8.9, and only then to >= 0.9.x. If you upgrade
+  without this intermediate step, client I/O will hang until the end of upgrade process.
+- Upgrading from <= 0.5.x to >= 0.6.x is not supported.
+
+Rollback:
+- Version 1.0.0 has a new disk format, so OSDs initiaziled on 1.0.0 can't be rolled
+  back to 0.9.x or previous versions.
+- Versions before 0.8.0 don't have vitastor-disk, so OSDs, initialized by it, won't
+  start with 0.7.x or 0.6.x. :-)
+
+## OSD memory usage
+
+OSD uses RAM mainly for:
+
+- Metadata index: `data_size`/[`block_size`](../config/layout-cluster.en.md#block_size) * `approximately 1.1` * `32` bytes.
+  Consumed always.
+- Copy of the on-disk metadata area: `data_size`/[`block_size`](../config/layout-cluster.en.md#block_size) * `28` bytes.
+  Consumed if [inmemory_metadata](../config/osd.en.md#inmemory_metadata) isn't disabled.
+- Bitmaps: `data_size`/[`bitmap_granularity`](../config/layout-cluster.en.md#bitmap_granularity)/`8` * `2` bytes.
+  Consumed always.
+- Journal index: between 0 and, approximately, journal size. Consumed always.
+- Copy of the on-disk journal area: exactly journal size. Consumed if
+  [inmemory_journal](../config/osd.en.md#inmemory_journal) isn't disabled.
+- Checksums: `data_size`/[`csum_block_size`](../config/osd.en.md#csum_block_size) * 4 bytes.
+  Consumed if checksums are enabled and [inmemory_metadata](../config/osd.en.md#inmemory_metadata) isn't disabled.
+
+bitmap_granularity is almost always 4 KB.
+
+So with default SSD settings (block_size=128k, journal_size=32M, csum_block_size=4k) memory usage is:
+
+- Metadata and bitmaps: ~600 MB per 1 TB of data.
+- Journal: up to 64 MB per 1 OSD.
+- Checksums: 1 GB per 1 TB of data.
+
+With default HDD settings (block_size=1M, journal_size=128M, csum_block_size=32k):
+
+- Metadata and bitmaps: ~128 MB per 1 TB of data.
+- Journal: up to 256 MB per 1 OSD.
+- Checksums: 128 MB per 1 TB of data.
--- a/docs/usage/admin.ru.md
+++ b/docs/usage/admin.ru.md
@ -0,0 +1,211 @@
+[Документация](../../README-ru.md#документация) → Использование → Администрирование
+
+-----
+
+[Read in English](admin.en.md)
+
+# Администрирование
+
+- [Состояния пулов](#состояния-пулов)
+- [Состояния PG](#состояния-pg)
+  - [Базовые состояния PG](#базовые-состояния-pg)
+  - [Дополнительные состояния PG](#дополнительные-состояния-pg)
+- [Удаление исправного диска](#удаление-исправного-диска)
+- [Удаление неисправного диска](#удаление-неисправного-диска)
+- [Добавление диска](#добавление-диска)
+- [Восстановление потерянной конфигурации пулов](#восстановление-потерянной-конфигурации-пулов)
+- [Обновление Vitastor](#обновление-vitastor)
+- [Потребление памяти OSD](#потребление-памяти-osd)
+
+## Состояния пулов
+
+Пул активен — то есть, полностью доступен для клиентского ввода-вывода — когда все его PG
+активны, то есть, имеют статус active, возможно, с любым набором дополнительных флагов.
+
+Если хотя бы 1 PG неактивна, пул неактивен и все клиенты зависают и ждут, пока вы почините
+кластер. :-)
+
+## Состояния PG
+
+Вы можете видеть состояния PG в выводе команды [vitastor-cli status](cli.ru.md#status).
+
+Состояние PG состоит из ровно 1 базового флага состояния, плюс любого числа дополнительных.
+
+### Базовые состояния PG
+
+Состояние PG включает в себя ровно 1 флаг из следующих:
+- **active** — PG активна и обрабатывает запросы ввода-вывода от пользователей.
+- **incomplete** — Недостаточно живых OSD, чтобы включить эту PG.
+  То есть, дисков потеряно больше, чем разрешено схемой отказоустойчивости пула и pg_minsize.
+  Например, если у пула pg_size=3 и pg_minsize=1, то часть данных может записаться всего на 1 OSD.
+  Если потом конкретно этот OSD упадёт, PG окажется **incomplete**.
+- **offline** — PG вообще не активирована ни одним OSD. Либо первичный OSD не назначен вообще
+  (если пул только создан), либо в качестве первичного назначен недоступный OSD, либо
+  назначенный OSD отказывается запускать эту PG (например, из-за несовпадения block_size),
+  либо PG остановлена монитором через флаг `pause: true` в `/vitastor/config/pgs` в etcd.
+- **starting** — первичный OSD захватил блокировку PG в etcd, PG запускается.
+- **peering** — первичный OSD опрашивает вторичные OSD на предмет списков объектов данной PG и рассчитывает её состояние.
+- **repeering** — PG ожидает завершения текущих операций ввода-вывода, после чего перейдёт в состояние **peering**.
+- **stopping** — PG ожидает завершения текущих операций ввода-вывода, после чего перейдёт в состояние **offline** или поднимется на другом OSD.
+
+Все состояния, кроме **active**, означают, что PG неактивна и ввод-вывод приостановлен.
+
+Состояние **peering** в норме заметно только при перезапуске OSD или переключении первичных
+OSD, на протяжении небольшого периода времени.
+
+Состояния **starting**, **repeering**, **stopping** в норме практически не заметны вообще,
+PG должны очень быстро переходить из них в другие. Если эти состояния заметны
+хоть сколько-то значительное время — вероятно, какие-то операции на каких-то OSD зависли.
+Чтобы найти их, ищите "slow op" в журналах OSD — операции, зависшие дольше,
+чем на [slow_log_interval](../config/osd.ru.md#slow_log_interval), записываются в
+журналы OSD как "slow op".
+
+Диаграмма переходов:
+
+![Диаграмма переходов](pg_states.svg "Диаграмма переходов")
+
+### Дополнительные состояния PG
+
+Если PG активна, она также может иметь любое число дополнительных флагов состояний:
+
+- **degraded** — PG поднята на неполном числе дисков (OSD), избыточность хранения всех объектов снижена.
+- **has_incomplete** — часть объектов в PG неполные (невосстановимые), то есть, у них потеряно
+  слишком много EC-частей (больше, чем [parity_chunks](../config/pool.ru.md#parity_chunks) пула).
+- **has_degraded** — часть объектов в PG деградированы, избыточность их хранения снижена по сравнению
+  с остальным содержимым данной PG (то есть, PG может одновременно быть degraded+has_degraded).
+  Данные объекты должны восстановиться автоматически, если только восстановление не отключено
+  через [no_recovery](../config/osd.ru.md#no_recovery).
+- **has_misplaced** — часть объектов в PG сейчас расположена не на целевом наборе OSD этой PG.
+  Данные объекты должны переместиться автоматически, если только перебалансировка не отключена
+  через [no_rebalance](../config/osd.ru.md#no_rebalance). Объекты, являющиеся одновременно
+  degraded и misplaced, считаются просто degraded.
+- **has_unclean** — ещё одно состояние, в норме заметное только очень короткое время при поднятии PG.
+  Применяется только к EC и означает, что на каких-то OSD этой PG есть EC-части объектов, для которых
+  был начат, но не завершён процесс записи. Все такие объекты первичный OSD либо завершает, либо
+  откатывает при поднятии PG первым делом, поэтому состояние и не должно быть заметно. Опять-таки,
+  если оно заметно — значит, скорее всего, операции отката или завершения записи на каких-то OSD зависли.
+- **has_invalid** — в PG найдены объекты с некорректными ID части. В норме не проявляется вообще
+  никогда, проявляется только если, не удалив данные, создать на месте EC-пула либо реплика-пул,
+  либо EC-пул с меньшим числом частей данных.
+- **has_corrupted** — в PG есть повреждённые объекты, обнаруженные с помощью контрольных сумм или
+  скраба (сверки копий). Если объекты можно восстановить, они восстановятся автоматически. Если
+  не восстанавливаются, используйте команду [vitastor-cli describe](cli.ru.md#describe) для
+  выяснения деталей и/или смотрите в журнал первичного OSD данной PG.
+- **has_inconsistent** — в PG есть объекты, у которых не совпадают копии/части данных на разных OSD,
+  и при этом автоматически определить, какая копия верная, а какая нет, невозможно. Такое может
+  произойти, если вы используете 2 реплики, не включали контрольные суммы, и на одной из реплик
+  данные повредились. В этом случае тоже надо использовать команды vitastor-cli [describe](cli.ru.md#describe)
+  и [fix](cli.ru.md#fix) для удаления некорректной версии.
+- **left_on_dead** — часть данных PG осталась на отключённом, но не удалённом из кластера окончательно,
+  OSD. Вам нужно либо вернуть соответствующий OSD в строй и дать ему очистить лишние данные, либо
+  удалить его из кластера окончательно с помощью vitastor-cli [rm-osd](cli.ru.md#rm-osd), если
+  известно, что он уже не вернётся (например, если умер диск).
+- **scrubbing** — идёт фоновая проверка данных PG ([скраб](../config/osd.ru.md#auto_scrub)).
+
+## Удаление исправного диска
+
+Перед удалением исправного диска из кластера установите его OSD вес в 0, чтобы убрать с него данные.
+Для этого добавьте в ключ `/vitastor/config/osd/<НОМЕР_OSD>` в etcd значение `"reweight":0`, например:
+
+```
+etcdctl --endpoints=http://1.1.1.1:2379/v3 put /vitastor/config/osd/1 '{"reweight":0}'
+```
+
+Дождитесь завершения ребаланса, после чего удалите OSD командой `vitastor-disk purge /dev/vitastor/osdN-data`.
+
+## Удаление неисправного диска
+
+Если диск уже умер, его OSD, скорее всего, уже будет/будут остановлен(ы).
+
+В этом случае просто удалите OSD из etcd командой `vitastor-cli rm-osd НОМЕР_OSD`.
+
+## Добавление диска
+
+Если сервер новый, установите на него пакеты Vitastor и скопируйте файл конфигурации
+`/etc/vitastor/vitastor.conf`.
+
+После этого достаточно выполнить команду `vitastor-disk prepare /dev/nvmeXXX`, разумеется,
+с параметрами, аналогичными другим OSD в вашем кластере.
+
+## Восстановление потерянной конфигурации пулов
+
+Если удалить или повредить ключ `/vitastor/config/pools` в etcd, все пулы будут удалены.
+Не волнуйтесь, данные потеряны не будут, но вам нужно будет провести специальную
+процедуру восстановления.
+
+Сначала нужно будет восстановить конфигурацию пулов, создав пул с таким же ID и
+с такими же параметрами EC/реплик, и подождать, пока PG пула появятся в `vitastor-cli status`.
+
+Далее нужно будет добавить все OSD в исторические записи всех PG. Примерно так
+(только подставьте свои PG_COUNT и POOL_ID):
+
+```
+PG_COUNT=32
+POOL_ID=1
+ALL_OSDS=$(etcdctl --endpoints=your_etcd_address:2379 get --keys-only --prefix /vitastor/osd/stats/ | \
+    perl -e '$/ = undef; $a = <>; $a =~ s/\s*$//; $a =~ s!/vitastor/osd/stats/!!g; $a =~ s/\s+/,/g; print $a')
+for i in $(seq 1 $PG_COUNT); do
+    etcdctl --endpoints=your_etcd_address:2379 put /vitastor/pg/history/$POOL_ID/$i '{"all_peers":['$ALL_OSDS']}'; done
+done
+```
+
+После этого все PG должны пройти peering и найти все предыдущие данные.
+
+## Обновление Vitastor
+
+Обычно каждая следующая версия Vitastor совместима с предыдущими и "вперёд", и "назад"
+с точки зрения сетевого протокола и структур данных в etcd.
+
+Так что по умолчанию, если на данной странице не указано обратное, считается, что для
+обновления достаточно обновить пакеты и перезапустить все OSD и мониторы Vitastor в
+произвольном порядке.
+
+Обновление производится без остановки клиентов (виртуальных машин/контейнеров), для этого
+достаточно обновлять серверы по одному. Однако, конечно, чтобы запущенные виртуальные машины
+начали использовать новую версию клиентской библиотеки, их тоже нужно перезапустить.
+
+Исключения (особые указания при обновлении):
+- Обновляться с версий <= 1.1.x до версий >= 1.2.0, если вы используете EC n+k и k>=2,
+  рекомендуется с временной остановкой кластера — сначала нужно остановить всех клиентов,
+  потом все OSD, потом обновить и запустить всё обратно — из-за нескольких багов, которые
+  могли приводить к некорректному чтению данных в деградированных EC-пулах.
+- Версии <= 0.8.7 несовместимы с версиями >= 0.9.0, поэтому при обновлении с <= 0.8.7
+  нужно сначала обновиться до 0.8.8 или 0.8.9, а уже потом до любых версий >= 0.9.x.
+  Иначе клиентский ввод-вывод зависнет до завершения обновления.
+- Обновление с версий 0.5.x и более ранних до 0.6.x и более поздних не поддерживается.
+
+Откат:
+- В версии 1.0.0 поменялся дисковый формат, поэтому OSD, созданные на версии >= 1.0.0,
+  нельзя откатить до версии 0.9.x и более ранних.
+- В версиях ранее 0.8.0 нет vitastor-disk, значит, созданные им OSD нельзя откатить
+  до 0.7.x или 0.6.x. :-)
+
+## Потребление памяти OSD
+
+Основное потребление памяти складывается из:
+
+- Индекс метаданных: `размер_данных`/[`block_size`](../config/layout-cluster.ru.md#block_size) * `примерно 1.1` * `32` байт.
+  Потребляется всегда.
+- Копия дисковой области метаданных: `размер_данных`/[`block_size`](../config/layout-cluster.ru.md#block_size) * `28` байт.
+  Потребляется, если не отключена настройка [inmemory_metadata](../config/osd.ru.md#inmemory_metadata).
+- Битмапы: `размер_данных`/[`bitmap_granularity`](../config/layout-cluster.ru.md#bitmap_granularity)/`8` * `2` байт.
+  Потребляется всегда.
+- Индекс журнала: от 0 до, приблизительно, размера журнала. Потребляется всегда.
+- Копия дисковой области журнала: в точности размер журнала. Потребляется,
+  если не отключена настройка [inmemory_journal](../config/osd.ru.md#inmemory_journal).
+- Контрольные суммы: `размер_данных`/[`csum_block_size`](../config/osd.ru.md#csum_block_size) * `4` байт.
+  Потребляется, если включены контрольные суммы и не отключена настройка [inmemory_metadata](../config/osd.ru.md#inmemory_metadata).
+
+bitmap_granularity, как правило, никогда не меняется и равен 4 килобайтам.
+
+Таким образом, при SSD-настройках по умолчанию (block_size=128k, journal_size=32M, csum_block_size=4k) потребляется:
+
+- Метаданные и битмапы: ~600 МБ на 1 ТБ данных
+- Журнал: до 64 МБ на 1 OSD
+- Контрольные суммы: 1 ГБ на 1 ТБ данных
+
+При HDD-настройках по умолчанию (block_size=1M, journal_size=128M, csum_block_size=32k):
+
+- Метаданные и битмапы: ~128 МБ на 1 ТБ данных
+- Журнал: до 256 МБ на 1 OSD
+- Контрольные суммы: 128 МБ на 1 ТБ данных
--- a/docs/usage/pg_states.dot
+++ b/docs/usage/pg_states.dot
@ -0,0 +1,13 @@
+digraph G {
+    rankdir=LR;
+    bgcolor=transparent;
+    edge [color="#00A000"];
+    node [shape=hexagon, fillcolor="#A0A000", fontcolor=white, fontname="sans-serif", fontsize=12, style=filled, penwidth=0];
+    offline -> starting -> peering -> offline;
+    stopping -> offline;
+    starting -> incomplete -> offline;
+    active -> repeering -> peering -> active -> stopping;
+    offline [fillcolor="#A00000"];
+    incomplete [fillcolor="#A00000"];
+    active [fillcolor="#00A000"];
+}
--- a/docs/usage/pg_states.svg
+++ b/docs/usage/pg_states.svg
@ -0,0 +1,114 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.43.0 (0)
+ -->
+<!-- Title: G Pages: 1 -->
+<svg width="603pt" height="123pt"
+ viewBox="0.00 0.00 602.66 122.55" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 118.55)">
+<title>G</title>
+<!-- offline -->
+<g id="node1" class="node">
+<title>offline</title>
+<polygon fill="#a00000" stroke="black" stroke-width="0" points="75.52,-56 56.6,-74 18.75,-74 -0.17,-56 18.75,-38 56.6,-38 75.52,-56"/>
+<text text-anchor="middle" x="37.67" y="-52.9" font-family="sans-serif" font-size="12.00" fill="white">offline</text>
+</g>
+<!-- starting -->
+<g id="node2" class="node">
+<title>starting</title>
+<polygon fill="#a0a000" stroke="black" stroke-width="0" points="199.56,-79 177.49,-97 133.35,-97 111.28,-79 133.35,-61 177.49,-61 199.56,-79"/>
+<text text-anchor="middle" x="155.42" y="-75.9" font-family="sans-serif" font-size="12.00" fill="white">starting</text>
+</g>
+<!-- offline&#45;&gt;starting -->
+<g id="edge1" class="edge">
+<title>offline&#45;&gt;starting</title>
+<path fill="none" stroke="#00a000" d="M69.39,-62.1C81.66,-64.54 96.04,-67.4 109.45,-70.06"/>
+<polygon fill="#00a000" stroke="#00a000" points="108.98,-73.54 119.47,-72.05 110.34,-66.67 108.98,-73.54"/>
+</g>
+<!-- peering -->
+<g id="node3" class="node">
+<title>peering</title>
+<polygon fill="#a0a000" stroke="black" stroke-width="0" points="335.57,-95 313.96,-113 270.74,-113 249.13,-95 270.74,-77 313.96,-77 335.57,-95"/>
+<text text-anchor="middle" x="292.35" y="-91.9" font-family="sans-serif" font-size="12.00" fill="white">peering</text>
+</g>
+<!-- starting&#45;&gt;peering -->
+<g id="edge2" class="edge">
+<title>starting&#45;&gt;peering</title>
+<path fill="none" stroke="#00a000" d="M194.36,-83.5C209.71,-85.32 227.6,-87.44 243.8,-89.36"/>
+<polygon fill="#00a000" stroke="#00a000" points="243.82,-92.89 254.16,-90.59 244.64,-85.94 243.82,-92.89"/>
+</g>
+<!-- incomplete -->
+<g id="node5" class="node">
+<title>incomplete</title>
+<polygon fill="#a00000" stroke="black" stroke-width="0" points="349.09,-41 320.72,-59 263.99,-59 235.62,-41 263.99,-23 320.72,-23 349.09,-41"/>
+<text text-anchor="middle" x="292.35" y="-37.9" font-family="sans-serif" font-size="12.00" fill="white">incomplete</text>
+</g>
+<!-- starting&#45;&gt;incomplete -->
+<g id="edge5" class="edge">
+<title>starting&#45;&gt;incomplete</title>
+<path fill="none" stroke="#00a000" d="M188.74,-69.9C204.92,-65.34 224.85,-59.73 242.82,-54.67"/>
+<polygon fill="#00a000" stroke="#00a000" points="243.9,-58 252.57,-51.92 242,-51.26 243.9,-58"/>
+</g>
+<!-- peering&#45;&gt;offline -->
+<g id="edge3" class="edge">
+<title>peering&#45;&gt;offline</title>
+<path fill="none" stroke="#00a000" d="M259.32,-103.69C222.67,-112.11 161.28,-121.52 111.35,-106 94.55,-100.78 78.2,-90.18 65.27,-80.08"/>
+<polygon fill="#00a000" stroke="#00a000" points="67.26,-77.19 57.3,-73.58 62.84,-82.61 67.26,-77.19"/>
+</g>
+<!-- active -->
+<g id="node6" class="node">
+<title>active</title>
+<polygon fill="#00a000" stroke="black" stroke-width="0" points="456.34,-49 438.55,-67 402.97,-67 385.18,-49 402.97,-31 438.55,-31 456.34,-49"/>
+<text text-anchor="middle" x="420.76" y="-45.9" font-family="sans-serif" font-size="12.00" fill="white">active</text>
+</g>
+<!-- peering&#45;&gt;active -->
+<g id="edge9" class="edge">
+<title>peering&#45;&gt;active</title>
+<path fill="none" stroke="#00a000" d="M322.99,-84.22C341.47,-77.49 365.34,-68.8 384.75,-61.74"/>
+<polygon fill="#00a000" stroke="#00a000" points="385.96,-65.03 394.16,-58.32 383.56,-58.45 385.96,-65.03"/>
+</g>
+<!-- stopping -->
+<g id="node4" class="node">
+<title>stopping</title>
+<polygon fill="#a0a000" stroke="black" stroke-width="0" points="591.65,-18 567.57,-36 519.39,-36 495.31,-18 519.39,0 567.57,0 591.65,-18"/>
+<text text-anchor="middle" x="543.48" y="-14.9" font-family="sans-serif" font-size="12.00" fill="white">stopping</text>
+</g>
+<!-- stopping&#45;&gt;offline -->
+<g id="edge4" class="edge">
+<title>stopping&#45;&gt;offline</title>
+<path fill="none" stroke="#00a000" d="M500.13,-14.3C440.78,-9.83 329.58,-4.07 235.49,-14 179.71,-19.89 116.5,-34.9 77.11,-45.29"/>
+<polygon fill="#00a000" stroke="#00a000" points="76.14,-41.92 67.38,-47.89 77.94,-48.69 76.14,-41.92"/>
+</g>
+<!-- incomplete&#45;&gt;offline -->
+<g id="edge6" class="edge">
+<title>incomplete&#45;&gt;offline</title>
+<path fill="none" stroke="#00a000" d="M240.25,-44.03C194.33,-46.76 127.57,-50.72 83.64,-53.33"/>
+<polygon fill="#00a000" stroke="#00a000" points="83.32,-49.84 73.54,-53.93 83.73,-56.83 83.32,-49.84"/>
+</g>
+<!-- active&#45;&gt;stopping -->
+<g id="edge10" class="edge">
+<title>active&#45;&gt;stopping</title>
+<path fill="none" stroke="#00a000" d="M449.46,-41.89C463.64,-38.25 481.26,-33.72 497.34,-29.59"/>
+<polygon fill="#00a000" stroke="#00a000" points="498.29,-32.96 507.11,-27.08 496.55,-26.18 498.29,-32.96"/>
+</g>
+<!-- repeering -->
+<g id="node7" class="node">
+<title>repeering</title>
+<polygon fill="#a0a000" stroke="black" stroke-width="0" points="594.84,-83 569.16,-101 517.8,-101 492.12,-83 517.8,-65 569.16,-65 594.84,-83"/>
+<text text-anchor="middle" x="543.48" y="-79.9" font-family="sans-serif" font-size="12.00" fill="white">repeering</text>
+</g>
+<!-- active&#45;&gt;repeering -->
+<g id="edge7" class="edge">
+<title>active&#45;&gt;repeering</title>
+<path fill="none" stroke="#00a000" d="M448.85,-56.63C462.9,-60.59 480.44,-65.53 496.53,-70.06"/>
+<polygon fill="#00a000" stroke="#00a000" points="495.74,-73.47 506.32,-72.82 497.64,-66.74 495.74,-73.47"/>
+</g>
+<!-- repeering&#45;&gt;peering -->
+<g id="edge8" class="edge">
+<title>repeering&#45;&gt;peering</title>
+<path fill="none" stroke="#00a000" d="M495.33,-85.27C451.99,-87.36 387.93,-90.44 343.63,-92.58"/>
+<polygon fill="#00a000" stroke="#00a000" points="343.2,-89.09 333.38,-93.07 343.54,-96.09 343.2,-89.09"/>
+</g>
+</g>
+</svg>