From 33f9d03d2267213cff04032b5d10e81ffb707da2 Mon Sep 17 00:00:00 2001 From: Vitaliy Filippov Date: Sat, 17 Apr 2021 17:40:12 +0300 Subject: [PATCH] Update documentation regarding image names and vitastor-nbd --- README-ru.md | 110 +++++++++++++++++++++++++++++++++++++++++---------- README.md | 98 ++++++++++++++++++++++++++++++++++++--------- 2 files changed, 169 insertions(+), 39 deletions(-) diff --git a/README-ru.md b/README-ru.md index dc22a707..88bb45e6 100644 --- a/README-ru.md +++ b/README-ru.md @@ -314,14 +314,15 @@ Ceph: ### NBD -NBD - на данный момент единственный способ монтировать Vitastor ядром Linux, но он -приводит к дополнительным копированиям данных, поэтому немного ухудшает производительность, -правда, в основном - линейную, а случайная затрагивается слабо. - NBD расшифровывается как "сетевое блочное устройство", но на самом деле оно также работает просто как аналог FUSE для блочных устройств, то есть, представляет собой "блочное устройство в пространстве пользователя". +NBD - на данный момент единственный способ монтировать Vitastor ядром Linux. +NBD немного снижает производительность, так как приводит к дополнительным копированиям +данных между ядром и пространством пользователя. Тем не менее, способ достаточно оптимален, +а производительность случайного доступа вообще затрагивается слабо. + Vitastor с однопоточной NBD прокси на том же стенде: - T1Q1 запись: 6000 iops (задержка 0.166ms) - T1Q1 чтение: 5518 iops (задержка 0.18ms) @@ -424,23 +425,90 @@ Vitastor с однопоточной NBD прокси на том же стен - Запустите все OSD: `systemctl start vitastor.target` - Ваш кластер должен быть готов - один из мониторов должен уже сконфигурировать PG, а OSD должны запустить их. - Вы можете проверить состояние PG прямо в etcd: `etcdctl --endpoints=... get --prefix /vitastor/pg/state`. Все PG должны быть 'active'. -- Пример команды для запуска тестов: `fio -thread -ioengine=libfio_vitastor.so -name=test -bs=4M -direct=1 -iodepth=16 -rw=write -etcd=10.115.0.10:2379/v3 -pool=1 -inode=1 -size=400G`. -- Пример команды для заливки образа ВМ в vitastor через qemu-img: - ``` - qemu-img convert -f qcow2 debian10.qcow2 -p -O raw 'vitastor:etcd_host=10.115.0.10\:2379/v3:pool=1:inode=1:size=2147483648' - ``` - Если вы используете немодифицированный QEMU, данной команде потребуется переменная окружения `LD_PRELOAD=/usr/lib/x86_64-linux-gnu/qemu/block-vitastor.so`. -- Пример команды запуска QEMU: - ``` - qemu-system-x86_64 -enable-kvm -m 1024 - -drive 'file=vitastor:etcd_host=10.115.0.10\:2379/v3:pool=1:inode=1:size=2147483648',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 - ``` -- Пример команды удаления образа (инода) из Vitastor: - ``` - vitastor-rm --etcd_address 10.115.0.10:2379/v3 --pool 1 --inode 1 --parallel_osds 16 --iodepth 32 - ``` + +### Задать имя образу + +``` +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-rm. Например: + +``` +vitastor-rm --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`. ## Известные проблемы diff --git a/README.md b/README.md index 38c2dda7..7235cdb6 100644 --- a/README.md +++ b/README.md @@ -379,24 +379,86 @@ and calculate disk offsets almost by hand. This will be fixed in near future. 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'. -- Run tests with (for example): `fio -thread -ioengine=libfio_vitastor.so -name=test -bs=4M -direct=1 -iodepth=16 -rw=write -etcd=10.115.0.10:2379/v3 -pool=1 -inode=1 -size=400G`. -- Upload VM disk image with qemu-img (for example): - ``` - qemu-img convert -f qcow2 debian10.qcow2 -p -O raw 'vitastor:etcd_host=10.115.0.10\:2379/v3:pool=1:inode=1:size=2147483648' - ``` - 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. -- Run QEMU with (for example): - ``` - qemu-system-x86_64 -enable-kvm -m 1024 - -drive 'file=vitastor:etcd_host=10.115.0.10\:2379/v3:pool=1:inode=1:size=2147483648',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 - ``` -- Remove inode with (for example): - ``` - vitastor-rm --etcd_address 10.115.0.10:2379/v3 --pool 1 --inode 1 --parallel_osds 16 --iodepth 32 - ``` + +### 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. For example: + +``` +vitastor-rm --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. ## Known Problems