[YDBOPS-3677] WIP Manual deployment docs

ref:9d501b7585806a966652fd6101aa0e879f6bfb35

8 files changed, 438 insertions, 0 deletions

diff --git a/ydb/docs/ru/core/deploy/manual/_includes/generate-ssl.md b/ydb/docs/ru/core/deploy/manual/_includes/generate-ssl.md
new file mode 100644
index 0000000000..638ee0bfdc
--- /dev/null
+++ b/ydb/docs/ru/core/deploy/manual/_includes/generate-ssl.md
@@ -0,0 +1,98 @@
+## Создайте TLS сертификаты с использование OpenSSL {# generate-tls}
+{% note info %}
+
+Вы можете использовать существующие TLS сертификаты. Важно, чтобы сертификаты поддерживали как серверную, так и клиентскую аутентификацию (`extendedKeyUsage = serverAuth,clientAuth`)
+
+{% endnote %}
+
+## Создайте CA ключ {# generate-ca}
+Создайте директории `secure`, в которой будет храниться ключ CA и `certs` для сертифкатов и ключей нод:
+```bash
+mkdir secure
+mkdir certs
+```
+
+Создайте конфигурационный файл `ca.cnf` со следующим содержимым
+```text
+[ ca ]
+default_ca = CA_default
+
+[ CA_default ]
+default_days = 365
+database = index.txt
+serial = serial.txt
+default_md = sha256
+copy_extensions = copy
+unique_subject = no
+
+[ req ]
+prompt=no
+distinguished_name = distinguished_name
+x509_extensions = extensions
+
+[ distinguished_name ]
+organizationName = YDB
+commonName = YDB CA
+
+[ extensions ]
+keyUsage = critical,digitalSignature,nonRepudiation,keyEncipherment,keyCertSign
+basicConstraints = critical,CA:true,pathlen:1
+
+[ signing_policy ]
+organizationName = supplied
+commonName = optional
+
+[ signing_node_req ]
+keyUsage = critical,digitalSignature,keyEncipherment
+extendedKeyUsage = serverAuth,clientAuth
+
+# Used to sign client certificates.
+[ signing_client_req ]
+keyUsage = critical,digitalSignature,keyEncipherment
+extendedKeyUsage = clientAuth
+```
+
+Создайте CA ключ, выполнив команду
+```bash
+openssl genrsa -out secure/ca.key 2048
+```
+ Сохраните этот ключ отдельно, он необходим для выписывания сертификатов. При его утере вам необходимо будет перевыпустить все сертификаты.
+
+ Создайте частный Certificate Authority (CA) сертификат, выполнив команду
+```bash
+openssl req -new -x509 -config ca.cnf -key secure/ca.key -out ca.crt -days 365 -batch
+```
+
+### Создание ключей и сертификатов для нод кластера {# generate-node-keypair}
+Создайте конфигурационный файл `node.conf` со следующим содержимым:
+```text
+# OpenSSL node configuration file
+[ req ]
+prompt=no
+distinguished_name = distinguished_name
+req_extensions = extensions
+
+[ distinguished_name ]
+organizationName = YDB
+
+[ extensions ]
+subjectAltName = DNS:<node>.<domain>
+```
+
+Создайте ключ сертификата следующей командой:
+```bash
+openssl genrsa -out node.key 2048
+```
+
+Создайте Certificate Signing Request (CSR) следующей командой:
+```bash
+openssl req -new -sha256 -config node.cnf -key certs/node.key -out node.csr -batch
+```
+
+Создайте сертификат ноды следующей командой:
+```bash
+openssl ca -config ca.cnf -keyfile secure/ca.key -cert certs/ca.crt -policy signing_policy \
+-extensions signing_node_req -out certs/node.crt -outdir certs/ -in node.csr -batch
+```
+
+Создайте аналогичные пары сертификат-ключ для каждой ноды.
\ No newline at end of file
diff --git a/ydb/docs/ru/core/deploy/manual/_includes/prepare-configs.md b/ydb/docs/ru/core/deploy/manual/_includes/prepare-configs.md
new file mode 100644
index 0000000000..ce03cbef55
--- /dev/null
+++ b/ydb/docs/ru/core/deploy/manual/_includes/prepare-configs.md
@@ -0,0 +1,39 @@
+## Подготовьте конфигурационный файл {{ ydb-short-name }} {# preprate-configs}
+Скачайте пример конфига для соответствующей модели отказа вашего кластера: 
+ * [block-4-2](https://github.com/ydb-platform/ydb/blob/main/ydb/deploy/yaml_config_examples/block-4-2.yaml) - для однодатацентрового кластера
+ * [mirror-3dc](https://github.com/ydb-platform/ydb/blob/main/ydb/deploy/yaml_config_examples/mirror-3dc-9-nodes.yaml) - для crossDC кластера из 9 нод 
+ * [mirror-3dc](https://github.com/ydb-platform/ydb/blob/main/ydb/deploy/yaml_config_examples/mirror-3dc-3-nodes.yaml) - для crossDC кластера из 3 нод 
+
+1. В секции host_configs укажите все диски и их тип на каждой из нод кластера. Возможные варианты типов дисков:
+```text
+host_configs:
+- drive:
+  - path: /dev/disk/by-partlabel/ydb_disk_01
+    type: SSD
+  host_config_id: 1
+```
+ * ROT (rotational) - HDD диски
+ * SSD - SSD или NVMe диски
+
+2. В секции `hosts` укажите FQDN всех нод, их конфигурацию и расположение по датацентрам (`data_center`) и стойкам (`rack`)
+```text
+hosts:
+- host: node1.ydb.tech
+  host_config_id: 1
+  walle_location:
+    body: 1
+    data_center: 'zone-a'
+    rack: '1'
+- host: node2.ydb.tech
+  host_config_id: 1
+  walle_location:
+    body: 2
+    data_center: 'zone-b'
+    rack: '1'
+- host: node3.ydb.tech
+  host_config_id: 1
+  walle_location:
+    body: 3
+    data_center: 'zone-c'
+    rack: '1'
+```
\ No newline at end of file
diff --git a/ydb/docs/ru/core/deploy/manual/concepts.md b/ydb/docs/ru/core/deploy/manual/concepts.md
new file mode 100644
index 0000000000..cdf1a6d8a7
--- /dev/null
+++ b/ydb/docs/ru/core/deploy/manual/concepts.md
@@ -0,0 +1,6 @@
+## Ручная установка
+
+### Термины и определения
+YDB состоит из двух компонентов:
+ * статическая нода (static node) - ноды, обеспечивающие слой хранения данных;
+ * динамическая нода (dynamic node) - нода, реализующие доступ к данным и их обработку. Для каждой базы данных необходима одна или более отдельная динамическая нода.
diff --git a/ydb/docs/ru/core/deploy/manual/deploy-ydb-on-premises.md b/ydb/docs/ru/core/deploy/manual/deploy-ydb-on-premises.md
new file mode 100644
index 0000000000..6bc2b2005b
--- /dev/null
+++ b/ydb/docs/ru/core/deploy/manual/deploy-ydb-on-premises.md
@@ -0,0 +1,264 @@
+## Deploy YDB On-Premises {# deploy-on-premise}
+Данный документ описывает способ развернуть мультитенантный кластер YDB на нескольких серверах.
+
+## Перед началом работы {# before-start}
+### Требования {# requirements}
+У вас должен быть ssh доступ на все сервера. Это необходимо для установки артефактов и запуска бинарника YDB.
+Ваша сетевая конфигурация должна разрешать TCP соединения по следующим портам (по-умолчанию):
+ * 2135, 2136 - grpc для клиент-кластерного взаимодействия;
+ * 19001, 19002 - Interconnect для внутрикластерного взаимодействия нод;
+ * 8765, 8766 - http интерфейс для мониторинга кластера.
+
+Ознакомьтесь с [Production checklist](../production_checklist.md) и рекомендованной топологией кластера;
+Выберите сервера и диски, которые будут использоваться для хранения данных:
+* Используйте схему отказоустойчивости `block-4-2` для деплоя кластера в одной зоне доступности (AZ). Чтобы переживать выпадения 2 нод используйте не менее 8 нод.
+* Используйте схему отказоустойчивости `mirror-3-dc` для деплоя кластера в трех зонах доступности (AZ). Чтобы переживать выпадения 1 AZ и 1 ноды в другом AZ используйте не менее 9 нод. Количество нод в каждой AZ должно быть одинаковым.
+
+Запускайте каждую статическую ноду на отдельном сервере. 
+
+## Создайте системного пользователя и группу, от имени которого будет работать {{ ydb-short-name }} {# create-user}
+На каждом сервере, где будет запущен YDB выполните:
+```bash
+sudo groupadd ydb
+sudo useradd ydb -g ydb
+```
+
+Для того, чтобы {{ ydb-short-name }} server имел доступ к блочным дискам для работы, необходимо добавить пользователя, под которым будет запущен процесс, в группу disk
+ ```bash
+sudo usermod -aG disk ydb
+```
+
+## Подготовьте и отформатируйте диски на каждом сервере {# prepare-disks}
+
+{% note warning %}
+
+Мы не рекомендуем использовать для хранения данных диски, которые используются другими процессами (в т.ч. операционной системой)
+
+{% endnote %}
+
+1. Создайте раздел на выбранном диске 
+
+{% note alert %}
+
+Будьте внимательны! Следующая операция удалят все разделы на указанных дисках!
+Убедитесь, что вы указали диски, на которых нет других данных!
+
+{% endnote %}
+
+```bash
+sudo parted /dev/nvme0n1 mklabel gpt -s
+sudo parted -a optimal /dev/nvme0n1 mkpart primary 0% 100%
+sudo parted /dev/nvme0n1 name 1 ydb_disk_01
+sudo partx --u /dev/nvme0n1
+```
+После выполнения в системе появится диск с лейблом `/dev/disk/by-partlabel/ydb_disk_01` 
+
+
+Если вы планируете использовать более одного диска на каждом сервере - укажите для каждого свой уникальный лейбл вместо `ydb_disk_01`. Эти диски необходимо будет использовать в конфигурационных файлах далее.
+
+Скачайте архив с исполняемым файлом `ydbd` и необходимыми для работы YDB библиотеками:
+```bash
+curl https://binaries.ydb.tech/ydbd-main-linux-amd64.tar.gz | tar -xz
+```
+Создайте директории для запуска:
+```bash
+mkdir -p /opt/ydb
+chown ydb:ydb /opt/ydb
+mkdir /opt/ydb/bin
+mkdir /opt/ydb/cfg
+```
+
+3. Скопируйте бинарник, библиотеки и конфигурационный файл в соответствующие директории:
+```bash
+sudo cp -i ydbd-main-linux-amd64/bin/ydbd /opt/ydb/bin/
+sudo cp -i ydbd-main-linux-amd64/lib/libaio.so /opt/ydb/lib/
+sudo cp -i ydbd-main-linux-amd64/lib/libiconv.so /opt/ydb/lib/
+sudo cp -i ydbd-main-linux-amd64/lib/libidn.so /opt/ydb/lib/
+```
+3. Отформатируйте диск встроенной командой 
+```bash
+sudo LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib /opt/ydb/bin/ydbd admin bs disk obliterate /dev/disk/by-partlabel/ydb_disk_01 
+```
+Проделайте данную операцию для каждого диска, который будет использоваться для хранения данных.
+
+Подготовьте конфигурационные файлы:
+
+{% list tabs %}
+
+- Незащищенный режим
+
+  В данном режиме трафик между нодами кластера а также между клиентом и кластером использует нешифрованное соединение. Используйте данный режим для тестовых задач.
+  
+  {% include [prepare-configs.md](_includes/prepare-configs.md) %}
+
+  Сохраните конфигурационный файл {{ ydb-short-name }} под именем `/opt/ydb/cfg/config.yaml`
+
+- Защищенный режим
+
+  В данном режиме трафик между нодами кластера, а также между клиентом и кластером шифруется протоколом TLS.
+
+  {% include [generate-ssl.md](_includes/generate-ssl.md) %}
+
+  Создайте на каждой ноде директирии для сертификатов
+  ```bash
+  mkdir /opt/ydb/certs
+  chmod 0750 /opt/ydb/certs
+  ```
+
+  Скопируйте сертификаты и ключи ноды
+  ```bash
+  sudo -u ydb cp certs/ca.crt certs/node.crt certs/node.key /opt/ydb/certs/
+  ```
+
+  {% include [prepare-configs.md](_includes/prepare-configs.md) %}
+
+  3. В секциях `interconnect_config` и `grpc_config` укажите путь до сертификата, ключа и CA сертификаты:
+  ```text
+    interconnect_config:
+        start_tcp: true
+        encryption_mode: OPTIONAL
+        path_to_certificate_file: "/opt/ydb/certs/node.crt"
+        path_to_private_key_file: "/opt/ydb/certs/node.key"
+        path_to_ca_file: "/opt/ydb/certs/ca.crt"
+  
+    grpc_config:
+        cert: "/opt/ydb/certs/node.crt"
+        key: "/opt/ydb/certs/node.key"
+        ca: "/opt/ydb/certs/ca.crt"
+  ```
+  Сохраните конфигурационный файл под именем `/opt/ydb/cfg/config.yaml`
+
+{% endlist %}
+
+
+## Запустите статические ноды {# start-storage}
+
+{% list tabs %}
+
+- Вручную
+
+  1. Запустите на каждой ноде {{ ydb-short-name }} storage:
+  ```bash
+  sudo su - ydb
+  cd /opt/ydb
+  export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib
+  /opt/ydb/bin/ydbd server --log-level 3 --syslog --tcp --yaml-config /opt/ydb/cfg/config.yaml  \
+  --grpc-port 2135 --ic-port 19001 --mon-port 8765 --node static
+  ```
+  TBD: как и куда писать логи? Ротация логов
+
+- С использованием systemd
+  
+  1. Создайте на каждой ноде конфигурационный файл `/etc/systemd/system/ydbd-storage.service` со следующим содержимым 
+  ```text
+  [Unit]
+  Description=YDB storage node
+  After=network-online.target rc-local.service
+  Wants=network-online.target
+  StartLimitInterval=10
+  StartLimitBurst=15
+
+  [Service]
+  Restart=always
+  RestartSec=1
+  User=ydb
+  PermissionsStartOnly=true
+  StandardOutput=syslog
+  StandardError=syslog
+  SyslogIdentifier=ydbd
+  SyslogFacility=daemon
+  SyslogLevel=err
+  Environment=LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib
+  ExecStart=/opt/ydb/bin/ydbd server --log-level 3 --syslog --tcp --yaml-config  /opt/ydb/cfg/config.yaml --grpc-port 2135 --ic-port 19001 --mon-port 8765 --node static
+  LimitNOFILE=65536
+  LimitCORE=0
+  LimitMEMLOCK=3221225472
+
+  [Install]
+  WantedBy=multi-user.target
+  ```
+  
+  2. Запустите на каждой ноде {{ ydb-short-name }} storage:
+    ```bash
+  sudo systemctl start ydbd-storage
+  ```
+{% endlist %}
+
+## Инициализируйте кластер {# initialize-cluster}
+На одной из нод кластера выполните команду:
+```bash
+LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib ; /opt/ydb/bin/ydbd admin blobstorage config init --yaml-file  /opt/ydb/cfg/config.yaml ; echo $?
+```
+Код завершения команды должен быть нулевым.
+
+## Создание первой базы данных {# create-fist-db}
+Для работы с таблицами необходимо создать как минимум одну базу данных и поднять процесс, обслуживающий эту базу данных (динамическую ноду).
+```bash
+LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib ; /opt/ydb/bin/ydbd admin database /Root/testdb create ssd:1
+```
+
+## Запустите динамическую ноду базы {# start-dynnode}
+{% list tabs %}
+- Вручную
+
+  1. Запустите динамическую ноду {{ ydb-short-name }} для базы /Root/testdb:
+  ```bash
+  sudo su - ydb
+  cd /opt/ydb
+  export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib
+  /opt/ydbd/bin/ydbd server --grpc-port 2136 --ic-port 19002 --mon-port 8766 --yaml-config  /opt/ydb/cfg/config.yaml \
+  --tenant /Root/testdb --node-broker --node-broker --node-broker
+  ```
+  Запустите дополнительные динноды на других серверах для обеспечения доступности базы данных. 
+
+- С использованием systemd
+
+  1. Создайте конфигурационный файл `/etc/systemd/system/ydbd-testdb.service` со следующим содержимым:
+  ```text
+  [Unit]
+  Description=YDB testdb dynamic node
+  After=network-online.target rc-local.service
+  Wants=network-online.target
+  StartLimitInterval=10
+  StartLimitBurst=15
+
+  [Service]
+  Restart=always
+  RestartSec=1
+  User=ydb
+  PermissionsStartOnly=true
+  StandardOutput=syslog
+  StandardError=syslog
+  SyslogIdentifier=ydbd
+  SyslogFacility=daemon
+  SyslogLevel=err
+  Environment=LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib
+  ExecStart=LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ydb/lib ; /opt/ydb/bin/ydbd server --grpc-port 2136 --ic-port 19002 --mon-port 8766 --yaml-config  /opt/ydb/cfg/config.yaml --tenant /Root/testdb --node-broker --node-broker --node-broker
+  LimitNOFILE=65536
+  LimitCORE=0
+  LimitMEMLOCK=32212254720
+
+  [Install]
+  WantedBy=multi-user.target
+  ```
+  
+  2. Запустите динамическую ноду {{ ydb-short-name }} для базы /Root/testdb:
+  ```bash
+  sudo systemctl start ydbd-testdb
+  ```
+  3. Запустите дополнительные динноды на других серверах для обеспечения доступности базы данных.
+
+{% endlist %}
+
+## Протестируйте работу с созданной базой {# try-first-db}
+1. Установите YDB CLI как описано в статье [Установка YDB CLI](../../reference/ydb-cli/install.md)
+2. Создайте тестовую таблицу `test_table`:
+```bash
+ydb -e grpc://<node1.domain>:2136 -d /Root/testdb scripting yql \
+--script 'CREATE TABLE `testdir/test_table` (id Uint64, title Utf8, PRIMARY KEY (id));'
+```
+Где node.domain - FQDN сервера, на котором запущены динамическая нода, обслуживающие базу `/Root/testdb`
+
+
+
+
diff --git a/ydb/docs/ru/core/deploy/manual/toc_i.yaml b/ydb/docs/ru/core/deploy/manual/toc_i.yaml
new file mode 100644
index 0000000000..3484b61e92
--- /dev/null
+++ b/ydb/docs/ru/core/deploy/manual/toc_i.yaml
@@ -0,0 +1,5 @@
+items:
+- name: Обзор
+  href: concepts.md
+- name: Локальная установка
+  href: deploy-ydb-on-premises.md
diff --git a/ydb/docs/ru/core/deploy/manual/toc_p.yaml b/ydb/docs/ru/core/deploy/manual/toc_p.yaml
new file mode 100644
index 0000000000..5bfec4365d
--- /dev/null
+++ b/ydb/docs/ru/core/deploy/manual/toc_p.yaml
@@ -0,0 +1,2 @@
+items:
+- include: { mode: link, path: toc_i.yaml }
\ No newline at end of file
diff --git a/ydb/docs/ru/core/deploy/production_checklist.md b/ydb/docs/ru/core/deploy/production_checklist.md
new file mode 100644
index 0000000000..9e4b8a4929
--- /dev/null
+++ b/ydb/docs/ru/core/deploy/production_checklist.md
@@ -0,0 +1,20 @@
+## Чек-лист для развертывания продуктового окружения
+В данном разделе проводятся рекомендации для развертывания {{ ydb-full-name }} в продуктовых окружениях.
+
+## Топология
+При планировании развертывания важно правильно выбрать топологию кластера, исходя из необходимой отказоустойчивости:
+ * Режим mirror-3dc-3-nodes - для данного режима необходимо минимум 3 сервера по 3 диска в каждом. Для обеспечения наибольшей отказоуcтойчивости каждый сервер должен находиться в независимом датацентре. В данном режиме кластер находится в рабочем состоянии при выходе из строя не более 1 сервера.
+ * Режим mirror-3dc - для данного режима необходимо минимум 9 серверов. Для обеспечения наибольшей отказоуcтойчивости сервера должны находиться в трех независимых датацентрах и разных серверных стойках в каждом. В данном режиме кластер находится в рабочем состоянии при выходе из строя полностью 1 датацентре и 1 сервера в другом датацентре.
+ * Режим block-4-2 - для данного режима необходимо минимум 8 серверов в одном датацентре. Для обеспечения наибольшей отказоуcтойчивости сервера должны находиться в 8 независимых стойках. 
+
+
+TBD.  mirror-3dc vs block-4-2 - хотим ли мы в доке такое:
+- существенно больше сетевой трафик
+- больше накладные расходы на хранение
+
+## Аппаратная конфигурация
+Для корректной работы мы рекомендуем использовать процессоры x86_64 архитектуры с поддержкой следующих инструкций:
+- SSE
+- ???
+
+## Программная конфигурация 
\ No newline at end of file
diff --git a/ydb/docs/ru/core/getting_started/toc_i.yaml b/ydb/docs/ru/core/getting_started/toc_i.yaml
index 77c8fcf603..0ff668e65e 100644
--- a/ydb/docs/ru/core/getting_started/toc_i.yaml
+++ b/ydb/docs/ru/core/getting_started/toc_i.yaml
@@ -23,6 +23,10 @@ items:
     # when: audience == "tech"
   - name: Kubernetes
     include: { mode: link, path: ../deploy/orchestrated/toc_p.yaml }
+  - name: Вручную
+    include: { mode: link, path: ../deploy/manual/toc_p.yaml }
+  - name: Production checklist
+    href: ../deploy/production_checklist.md
 - name: Полезные ссылки
   href: useful_links.md