Describe OSD placement tree and reweights

docs/config.en.md

@@ -7,9 +7,10 @@
 # Configuration Reference
 
 Vitastor configuration consists of:
-- Configuration parameters (key-value), described here
+- [Configuration parameters (key-value)](#parameter-reference)
 - [Pool configuration](config/pool.en.md)
-- OSD placement tree configuration
+- [OSD placement tree configuration](config/pool.en.md#placement-tree)
+- [Separate OSD settings](config/pool.en.md#osd-settings)
 - [Inode configuration](config/inode.en.md) i.e. image metadata like name, size and parent reference
 
 Configuration parameters can be set in 3 places:
@@ -34,5 +35,3 @@ In the future, additional configuration methods may be added:
 - [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)

docs/config.ru.md

@@ -7,9 +7,10 @@
 # Конфигурация Vitastor
 
 Конфигурация Vitastor состоит из:
-- Параметров (ключ-значение), описанных на данной странице
+- [Параметров (ключ-значение)](#список-параметров)
 - [Настроек пулов](config/pool.ru.md)
-- Настроек дерева OSD
+- [Настроек дерева OSD](config/pool.ru.md#дерево-размещения)
+- [Настроек отдельных OSD](config/pool.ru.md#настройки-osd)
 - [Настроек инодов](config/inode.ru.md), т.е. метаданных образов, таких, как имя, размер и ссылки на
   родительский образ
 
@@ -36,4 +37,3 @@
 - [Дисковые параметры OSD](config/layout-osd.ru.md)
 - [Прочие параметры OSD](config/osd.ru.md)
 - [Параметры мониторов](config/monitor.ru.md)
-- [Настройки пулов](config/pool.ru.md)

docs/config/pool.en.md

@@ -18,6 +18,13 @@ JSON format:
 }
 ```
 
+Pool configuration is also affected by:
+
+- [OSD Placement Tree](#placement-tree)
+- [Separate OSD settings](#osd-settings)
+
+Parameters:
+
 - [name](#name)
 - [scheme](#scheme)
 - [pg_size](#pg_size)
@@ -36,7 +43,57 @@ Examples:
 - [Replicated Pool](#replicated-pool)
 - [Erasure-coded Pool](#erasure-coded-pool)
 
-# Parameters
+# Placement Tree
+
+OSD placement tree is set in a separate etcd key `/vitastor/config/node_placement`
+in the following JSON format:
+
+`
+{
+  "<node name or OSD number>": {
+    "level": "<level>",
+    "parent": "<parent node name, if any>"
+  },
+  ...
+}
+`
+
+Here, if a node name is a number then it is assumed to refer to an OSD.
+Level of the OSD is always "osd" and cannot be overriden. You may only
+override parent node of the OSD which is its host by default.
+
+Non-numeric node names refer to other placement tree nodes like hosts, racks,
+datacenters and so on.
+
+Hosts of all OSDs are auto-created in the tree with level "host" and name
+equal to the host name reported by a corresponding OSD. You can refer to them
+without adding them to this JSON tree manually.
+
+Level may be "host", "osd" or refer to some other placement tree level
+from [placement_levels](monitor.en.md#placement_levels).
+
+Parent node reference is required for intermediate tree nodes.
+
+# OSD settings
+
+Separate OSD settings are set in etc keys `/vitastor/config/osd/<number>`
+in JSON format `{"<key>":<value>}`.
+
+As of now, there is only one setting:
+
+## reweight
+
+- Type: number, between 0 and 1
+- Default: 1
+
+Every OSD receives PGs proportional to its size. Reweight is a multiplier for
+OSD size used during PG distribution.
+
+This means an OSD configured with reweight lower than 1 receives less PGs than
+it normally would. An OSD with reweight = 0 won't store any data. You can set
+reweight to 0 to trigger rebalance and remove all data from an OSD.
+
+# Pool parameters
 
 ## name
 

docs/config/pool.ru.md

@@ -17,6 +17,13 @@
 }
 ```
 
+На настройку пулов также влияют:
+
+- [Дерево размещения OSD](#дерево-размещения)
+- [Настройки отдельных OSD](#настройки-osd)
+
+Параметры:
+
 - [name](#name)
 - [scheme](#scheme)
 - [pg_size](#pg_size)
@@ -35,6 +42,57 @@
 - [Реплицированный пул](#реплицированный-пул)
 - [Пул с кодами коррекции ошибок 2+1](#пул-с-кодами-коррекции-ошибок)
 
+# Дерево размещения
+
+Дерево размещения OSD задаётся в отдельном ключе etcd `/vitastor/config/node_placement`
+в следующем JSON-формате:
+
+`
+{
+  "<имя узла или номер OSD>": {
+    "level": "<уровень>",
+    "parent": "<имя родительского узла, если есть>"
+  },
+  ...
+}
+`
+
+Здесь, если название узла - число, считается, что это OSD. Уровень OSD
+всегда равен "osd" и не может быть переопределён. Для OSD вы можете только
+переопределить родительский узел. По умолчанию родителем OSD считается его хост.
+
+Нечисловые имена узлов относятся к другим узлам дерева OSD, таким, как хосты (серверы),
+стойки, датацентры и так далее.
+
+Хосты всех OSD автоматически создаются в дереве с уровнем "host" и именем, равным имени хоста,
+сообщаемым соответствующим OSD. Вы можете ссылаться на эти хосты, не заводя их
+в дереве вручную.
+
+Уровень может быть "host", "osd" или относиться к другому уровню размещения из
+[placement_levels](monitor.ru.md#placement_levels).
+
+Родительский узел нужен только для промежуточных узлов дерева.
+
+# Настройки OSD
+
+Настройки отдельных OSD задаются в ключах etcd `/vitastor/config/osd/<number>`
+в JSON-формате `{"<key>":<value>}`.
+
+На данный момент поддерживается одна настройка:
+
+## reweight
+
+- Тип: число, от 0 до 1
+- По умолчанию: 1
+
+Каждый OSD получает число PG, пропорциональное его размеру. Reweight - это
+множитель для размера, используемый в процессе распределения PG.
+
+Это значит, что OSD, сконфигурированный с reweight меньше 1 будет получать
+меньше PG, чем обычно. OSD с reweight, равным 0, не будет участвовать в
+хранении данных вообще. Вы можете установить reweight в 0, чтобы убрать
+все данные с OSD.
+
 # Параметры
 
 ## name