diff --git a/docs/config/pool.en.md b/docs/config/pool.en.md index bb48b9e0..c7043896 100644 --- a/docs/config/pool.en.md +++ b/docs/config/pool.en.md @@ -154,8 +154,25 @@ 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). -That is, pg_size minus pg_minsize sets the number of disk failures to tolerate -without temporary downtime (for [osd_out_time](monitor.en.md#osd_out_time)). +For example, the difference between pg_minsize 2 and 1 in a 3-way replicated +pool (pg_size=3) is: +- If 2 hosts go down with pg_minsize=2, the pool becomes inactive and remains + inactive for [osd_out_time](monitor.en.md#osd_out_time) (10 minutes). After + this timeout, the monitor selects replacement hosts/OSDs and the pool comes + up and starts to heal. Therefore, if you don't have replacement OSDs, i.e. + if you only have 3 hosts with OSDs and 2 of them are down, the pool remains + inactive until you add or return at least 1 host (or change failure_domain + to "osd"). +- If 2 hosts go down with pg_minsize=1, the pool only experiences a short + I/O pause until the monitor notices that OSDs are down (5-10 seconds with + the default [etcd_report_interval](osd.en.md#etcd_report_interval)). After + this pause, I/O resumes, but new data is temporarily written in only 1 copy. + Then, after osd_out_time, the monitor also selects replacement OSDs and the + pool starts to heal. + +So, pg_minsize regulates the number of failures that a pool can tolerate +without temporary downtime for [osd_out_time](monitor.en.md#osd_out_time), +but at a cost of slightly reduced storage reliability. FIXME: pg_minsize behaviour may be changed in the future to only make PGs read-only instead of deactivating them. @@ -168,8 +185,8 @@ read-only instead of deactivating them. 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, +"Enough" is usually around 10-100 PGs per OSD, i.e. you set pg_count for pool +to (total OSD count * 10 / 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. diff --git a/docs/config/pool.ru.md b/docs/config/pool.ru.md index b488d9c0..52bd3bf6 100644 --- a/docs/config/pool.ru.md +++ b/docs/config/pool.ru.md @@ -157,9 +157,25 @@ OSD, PG деактивируется на чтение и запись. Иными словами, всегда известно, что новые блоки данных всегда записываются как минимум на pg_minsize дисков. -По сути, разница pg_size и pg_minsize задаёт число отказов дисков, которые пул -может пережить без временной (на [osd_out_time](monitor.ru.md#osd_out_time)) -остановки обслуживания. +Для примера, разница между pg_minsize 2 и 1 в реплицированном пуле с 3 копиями +данных (pg_size=3), проявляется следующим образом: +- Если 2 сервера отключаются при pg_minsize=2, пул становится неактивным и + остаётся неактивным в течение [osd_out_time](monitor.en.md#osd_out_time) + (10 минут), после чего монитор назначает другие OSD/серверы на замену, пул + поднимается и начинает восстанавливать недостающие копии данных. Соответственно, + если OSD на замену нет - то есть, если у вас всего 3 сервера с OSD и 2 из них + недоступны - пул так и остаётся недоступным до тех пор, пока вы не вернёте + или не добавите хотя бы 1 сервер (или не переключите failure_domain на "osd"). +- Если 2 сервера отключаются при pg_minsize=1, ввод-вывод лишь приостанавливается + на короткое время, до тех пор, пока монитор не поймёт, что OSD отключены + (что занимает 5-10 секунд при стандартном [etcd_report_interval](osd.en.md#etcd_report_interval)). + После этого ввод-вывод восстанавливается, но новые данные временно пишутся + всего в 1 копии. Когда же проходит osd_out_time, монитор точно так же назначает + другие OSD на замену выбывшим и пул начинает восстанавливать копии данных. + +То есть, pg_minsize регулирует число отказов, которые пул может пережить без +временной остановки обслуживания на [osd_out_time](monitor.ru.md#osd_out_time), +но ценой немного пониженных гарантий надёжности. FIXME: Поведение pg_minsize может быть изменено в будущем с полной деактивации PG на перевод их в режим только для чтения. @@ -172,8 +188,8 @@ PG на перевод их в режим только для чтения. Число PG для данного пула. Число должно быть достаточно большим, чтобы монитор мог равномерно распределить по ним данные. -Обычно это означает примерно 64-128 PG на 1 OSD, т.е. pg_count можно устанавливать -равным (общему числу OSD * 100 / pg_size). Значение можно округлить до ближайшей +Обычно это означает примерно 10-100 PG на 1 OSD, т.е. pg_count можно устанавливать +равным (общему числу OSD * 10 / pg_size). Значение можно округлить до ближайшей степени 2, чтобы потом было легче уменьшать или увеличивать число PG, умножая или деля его на 2. diff --git a/docs/intro/quickstart.en.md b/docs/intro/quickstart.en.md index ea85a08f..7209ab10 100644 --- a/docs/intro/quickstart.en.md +++ b/docs/intro/quickstart.en.md @@ -75,18 +75,16 @@ On the monitor hosts: ## Create a pool -Create pool configuration in etcd: +Create a pool using vitastor-cli: ``` -etcdctl --endpoints=... put /vitastor/config/pools '{"1":{"name":"testpool", - "scheme":"replicated","pg_size":2,"pg_minsize":1,"pg_count":256,"failure_domain":"host"}}' +vitastor-cli create-pool testpool --pg_size 2 --pg_count 256 ``` For EC pools the configuration should look like the following: ``` -etcdctl --endpoints=... put /vitastor/config/pools '{"2":{"name":"ecpool", - "scheme":"ec","pg_size":4,"parity_chunks":2,"pg_minsize":2,"pg_count":256,"failure_domain":"host"}}' +vitastor-cli create-pool testpool --ec 2+2 --pg_count 256 ``` After you do this, one of the monitors will configure PGs and OSDs will start them. diff --git a/docs/intro/quickstart.ru.md b/docs/intro/quickstart.ru.md index d04df01c..2585bf02 100644 --- a/docs/intro/quickstart.ru.md +++ b/docs/intro/quickstart.ru.md @@ -77,18 +77,16 @@ ## Создайте пул -Создайте конфигурацию пула с помощью etcdctl: +Создайте пул с помощью vitastor-cli: ``` -etcdctl --endpoints=... put /vitastor/config/pools '{"1":{"name":"testpool", - "scheme":"replicated","pg_size":2,"pg_minsize":1,"pg_count":256,"failure_domain":"host"}}' +vitastor-cli create-pool testpool --pg_size 2 --pg_count 256 ``` Для пулов с кодами коррекции ошибок конфигурация должна выглядеть примерно так: ``` -etcdctl --endpoints=... put /vitastor/config/pools '{"2":{"name":"ecpool", - "scheme":"ec","pg_size":4,"parity_chunks":2,"pg_minsize":2,"pg_count":256,"failure_domain":"host"}}' +vitastor-cli create-pool testpool --ec 2+2 --pg_count 256 ``` После этого один из мониторов должен сконфигурировать PG, а OSD должны запустить их. diff --git a/docs/usage/cli.en.md b/docs/usage/cli.en.md index b8adcb5b..c7084409 100644 --- a/docs/usage/cli.en.md +++ b/docs/usage/cli.en.md @@ -24,6 +24,10 @@ It supports the following commands: - [fix](#fix) - [alloc-osd](#alloc-osd) - [rm-osd](#rm-osd) +- [create-pool](#create-pool) +- [modify-pool](#modify-pool) +- [ls-pools](#ls-pools) +- [rm-pool](#rm-pool) Global options: @@ -238,3 +242,84 @@ Refuses to remove OSDs with data without `--force` and `--allow-data-loss`. With `--dry-run` only checks if deletion is possible without data loss and redundancy degradation. + +## create-pool + +`vitastor-cli create-pool|pool-create (-s |--ec +) -n [OPTIONS]` + +Create a pool. Required parameters: + +| `-s|--pg_size R` | Number of replicas for replicated pools | +| `--ec N+K` | Number of data (N) and parity (K) chunks for erasure-coded pools | +| `-n|--pg_count N` | PG count for the new pool (start with 10*/pg_size rounded to a power of 2) | + +Optional parameters: + +| `--pg_minsize ` | R or N+K minus number of failures to tolerate without downtime ([details](../config/pool.en.md#pg_minsize)) | +| `--failure_domain host` | Failure domain: host, osd or a level from placement_levels. Default: host | +| `--root_node ` | Put pool only on child OSDs of this placement tree node | +| `--osd_tags [,]...` | Put pool only on OSDs tagged with all specified tags | +| `--block_size 128k` | Put pool only on OSDs with this data block size | +| `--bitmap_granularity 4k` | Put pool only on OSDs with this logical sector size | +| `--immediate_commit none` | Put pool only on OSDs with this or larger immediate_commit (none < small < all) | +| `--primary_affinity_tags tags` | Prefer to put primary copies on OSDs with all specified tags | +| `--scrub_interval