KIKIMR-20945: update Ansible installation instructions (#5863)

2 files changed, 65 insertions, 77 deletions

diff --git a/ydb/docs/en/core/devops/ansible/initial-deployment.md b/ydb/docs/en/core/devops/ansible/initial-deployment.md
index 935ec0a269..acdd2ee152 100644
--- a/ydb/docs/en/core/devops/ansible/initial-deployment.md
+++ b/ydb/docs/en/core/devops/ansible/initial-deployment.md
@@ -52,49 +52,42 @@ To work with the project on a local (intermediate or installation) machine, you
 
 {% endlist %}
 
-
-## Configuring the Ansible project {#ansible-project-setup}
-
 Navigate to the root directory of the downloaded repository and execute the command `ansible-galaxy install -r requirements.yaml` – this will download the Ansible collections `ydb_platform.ydb` and `community.general`, which contain roles and plugins for installing {{ ydb-short-name }}.
 
-[Download](../../downloads/index.md#ydb-server) the archive of the current version of {{ ydb-short-name }} into the project's root directory. For example, using wget: `wget https://binaries.ydb.tech/release/23.3.17/ydbd-23.3.17-linux-amd64.tar.gz` and also copy the private part of the SSH key for accessing the {{ ydb-short-name }} cluster servers to the same location. The SSH key should have the following permissions:
-```text
--rw------- (600)  # Only the owner has read and write permission.
-```
-You can set the required permissions with the command `sudo chmod 600 <ssh-key name>`.
-
-Next, you can go to the TLS directory and specify in the file ydb-ca-nodes.txt a list of FQDNs for which TLS certificates will be generated. By default, the list looks as follows:
-```text
-static-node-1 static-node-1.ydb-cluster.com
-static-node-2 static-node-2.ydb-cluster.com
-static-node-3 static-node-3.ydb-cluster.com
-```
-
-Generate a set of TLS certificates, which will be placed in the CA subdirectory (`TLS/CA/certs/<create date_crete time>`) using the script `ydb-ca-update.sh`.
+## Configure the Ansible project {#ansible-project-setup}
 
-After generating the TLS certificates, installing the Ansible collections, uploading the private part of the SSH key, and downloading the current version of {{ ydb-short-name }}, you need to update the inventory files according to the chosen type of cluster for deployment.
+### Edit the inventory files {#inventory-edit}
 
-### Editing the project's inventory files {#inventory-edit}
-
-Regardless of the type of cluster being created (eight servers – `8-nodes-block-4-2` or nine servers – `9-nodes-mirror-3-dc`), the main parameters for installing and configuring {{ ydb-short-name }} are contained in the inventory file `50-inventory.yaml`, which is located in the `<cluster model>/inventory/` directory.
+Regardless of the chosen cluster topology (`3-nodes-mirror-3-dc`, `9-nodes-mirror-3-dc`, or `8-nodes-block-4-2`), the main parameters for installing and configuring {{ ydb-short-name }} are contained in the inventory file `50-inventory.yaml`, which is located in the `inventory/` directory.
 
 In the inventory file `50-inventory.yaml`, you need to specify the current list of FQDNs of the servers where {{ ydb-short-name }} will be installed. By default, the list appears as follows:
   ```yaml
   all:
     children:
-        ydb:
-        hosts:
-          static-node-1.ydb-cluster.com:
-          static-node-2.ydb-cluster.com:
-          static-node-3.ydb-cluster.com:
+      ydb:
+        static-node-1.ydb-cluster.com:
+        static-node-2.ydb-cluster.com:
+        static-node-3.ydb-cluster.com:
   ```
 
 Next, you need to make the following changes in the `vars` section of the inventory file:
+
   * `ansible_user` – specify the user for Ansible to connect via SSH.
-  * `ansible_ssh_common_args: "-o ProxyJump=<ansible_user>@<static-node-1 IP>"` – option for connecting Ansible to a server by IP, from which {{ ydb-short-name }} will be installed (including ProxyJump server). It is used when installing {{ ydb-short-name }} from a local machine that is not included in the private DNS zone.
-  * `ansible_ssh_private_key_file` – change the default ssh-key name to the actual one: `"../<ssh-private-key-name>"`.
-  * `ydb_archive` — specify the path to the previously downloaded archive with the {{ ydb-short-name }} distribution.
-  * `ydb_tls_dir` – specify the current path part (`/files/CA/certs/<date_time create certs>`) to the security certificates after they have been generated by the `ydb-ca-update.sh` script.
+  * `ansible_ssh_common_args: "-o ProxyJump=<ansible_user>@<static-node-1-IP>"` – option for connecting Ansible to a server by IP, from which {{ ydb-short-name }} will be installed (including ProxyJump server). It is used when installing {{ ydb-short-name }} from a local machine not included in the private DNS zone.
+  * `ansible_ssh_private_key_file` – change the default private SSH-key path to the actual one: `"../<ssh-private-key-name>"`.
+  * Choose one of the available options for deploying {{ ydb-short-name }} executables:
+    * `ydb_version`: automatically download one of the [{{ ydb-short-name }} official releases](../../downloads/index.md#ydb-server) by version number. For example, `23.4.11`.
+    * `ydb_git_version`: automatically compile the {{ ydb-short-name }} executables from the source code, downloaded from [the official GitHub repository](https://github.com/ydb-platform/ydb). The setting's value is a branch, tag, or commit name. For example, `main`.
+    * `ydb_archive`: a local filesystem path for a {{ ydb-short-name }} distribution archive [downloaded](../../downloads/index.md#ydb-server) or otherwise prepared in advance.
+    * `ydbd_binary` and `ydb_cli_binary`: local filesystem paths for {{ ydb-short-name }} server and client executables, [downloaded](../../downloads/index.md#ydb-server) or otherwise prepared in advance.
+
+#### Optional changes in the inventory files
+
+Feel free to change these settings if needed, but it is not necessary in straightforward cases:
+
+  * `ydb_cores_static` – set the number of CPU cores allocated to static nodes.
+  * `ydb_cores_dynamic` – set the number of CPU cores allocated to dynamic nodes.
+  * `ydb_tls_dir` – specify a local path to a folder with TLS certificates prepared in advance. It must contain the `ca.crt` file and subdirectories with names matching node hostnames, containing certificates for a given node. If omitted, self-signed TLS certificates will be generated automatically for the whole {{ ydb-short-name }} cluster.
   * `ydb_brokers` – list the FQDNs of the broker nodes. For example:
     ```yaml
     ydb_brokers:
@@ -102,8 +95,6 @@ Next, you need to make the following changes in the `vars` section of the invent
         - static-node-2.ydb-cluster.com
         - static-node-3.ydb-cluster.com
     ``` 
-  * `ydb_cores_static` – set the number of CPU cores consumed by the static node;
-  * `ydb_cores_dynamic` – set the number of CPU cores consumed by the dynamic node;
 
 The value of the `ydb_database_groups` variable in the `vars` section has a fixed value tied to the redundancy type and does not depend on the size of the cluster:
 * For the redundancy type `block-4-2`, the value of `ydb_database_groups` is seven.
@@ -129,21 +120,24 @@ The values of the `system_timezone` and `system_ntp_servers` variables depend on
 
 {% endlist %}
 
-No changes to other sections of the `50-inventory.yaml` configuration file are required. Next, you can change the standard YDB root user password contained in the encrypted inventory file `99-inventory-vault.yaml` and in the file `ansible_vault_password_file.txt`. To change the password – specify the new password in the `ansible_vault_password_file.txt` file and duplicate it in the `99-inventory-vault.yaml` file in the format:
+No changes to other sections of the `50-inventory.yaml` configuration file are required.
+
+#### Changing the root user password { #change-password }
+
+Next, you can change the standard YDB root user password contained in the encrypted inventory file `99-inventory-vault.yaml` and in the file `ansible_vault_password_file.txt`. To change the password – specify the new password in the `ansible_vault_password_file.txt` file and duplicate it in the `99-inventory-vault.yaml` file in the format:
   ```yaml
   all:
-        children:
-          ydb:
-            vars:
-              ydb_password: <new password>
+    children:
+      ydb:
+        vars:
+          ydb_password: <new-password>
   ```
 
 To encrypt `99-inventory-vault.yaml`, execute the command `ansible-vault encrypt inventory/99-inventory-vault.yaml`.
 
 After modifying the inventory files, you can proceed to prepare the {{ ydb-short-name }} configuration file.
 
-
-### Preparing the {{ ydb-short-name }} Configuration File {#ydb-config-prepare}
+### Prepare the {{ ydb-short-name }} configuration file {#ydb-config-prepare}
 
 The {{ ydb-short-name }} configuration file contains the settings for {{ ydb-short-name }} nodes and is located in the subdirectory `/files/config.yaml`. A detailed description of the configuration file settings for {{ ydb-short-name }} can be found in the article [{#T}](../../deploy/configuration/config.md).
 
diff --git a/ydb/docs/ru/core/devops/ansible/initial-deployment.md b/ydb/docs/ru/core/devops/ansible/initial-deployment.md
index 72af1495bb..9d4e6000f6 100644
--- a/ydb/docs/ru/core/devops/ansible/initial-deployment.md
+++ b/ydb/docs/ru/core/devops/ansible/initial-deployment.md
@@ -51,59 +51,49 @@
 
 {% endlist %}
 
+Перейдите в корневой каталог загруженного репозитория и выполните команду `ansible-galaxy install -r requirements.yaml` – она скачает коллекции Ansible `ydb_platform.ydb` и `community.general`, которые содержат роли и плагины для установки {{ ydb-short-name }}.
 
-## Настройка Ansible проекта { #ansible-project-setup } 
+## Настройка проекта Ansible {#ansible-project-setup}
 
-Перейдите в корневую директорию скачанного репозитория и выполните команду `ansible-galaxy install -r requirements.yaml` – будут скачаны Ansible коллекции `ydb_platform.ydb` и `community.general`, которые содержат роли и плагины для установки {{ ydb-short-name }}.
+### Редактирование инвентори-файлов {#inventory-edit}
 
-[Скачайте](../../downloads/index.md#ydb-server) архив актуальной версию {{ ydb-short-name }} в корневую директорию проекта. Например, с помощью wget: `wget https://binaries.ydb.tech/release/23.3.17/ydbd-23.3.17-linux-amd64.tar.gz` и скопируйте сюда же приватную часть SSH-ключа для доступа к серверам кластера {{ ydb-short-name }}. На SSH-ключе должны быть установлены следующие права:
-```text
--rw------- (600)  #Только владелец имеет разрешение на чтение и запись. 
-```
-Установить нужные права можно командой `sudo chmod 600 <ssh-key name>`.
-
-Далее можно перейти в директорию TLS и указать в файле `ydb-ca-nodes.txt` список FQDN серверов, для которых будут сгенерированы TLS сертификаты. По умолчанию список выглядит следующим образом:
-```text
-static-node-1 static-node-1.ydb-cluster.com
-static-node-2 static-node-2.ydb-cluster.com
-static-node-3 static-node-3.ydb-cluster.com
-```
-
-Сгенерировать набор TLS сертификатов, который будут размещены в поддиректории CA (`TLS/CA/certs/<create date_crete time>`) можно скриптом `ydb-ca-update.sh`.
-
-После генерации TLS сертификатов, установки Ansible коллекций, загрузки приватной части ssh-ключа и скачивания актуальной версии {{ ydb-short-name }} необходимо обновить инвентаризационные файлы в соответствии с выбранным видом кластера для развертывания.  
-
-### Изменения инвентаризационных файлов проекта { #inventory-edit }
+Независимо от выбранной топологии кластера (`3-nodes-mirror-3-dc`, `9-nodes-mirror-3-dc` или `8-nodes-block-4-2`), основные параметры для установки и настройки {{ ydb-short-name }} содержатся в инвентори-файле `50-inventory.yaml`, который находится в каталоге `inventory/`.
 
-Вне зависимости от вида создаваемого кластера (восемь серверов – `8-nodes-block-4-2` или девять серверов – `9-nodes-mirror-3-dc`) основные параметра установки и настройки {{ ydb-short-name }} содержатся в инвентаризационном файле `50-inventory.yaml`, который расположен в директории `<cluster model>/inventory/`.
-
-В инвентаризационном файле `50-inventory.yaml` нужно указать актуальный список FQDN серверов, на которые будет установлена {{ ydb-short-name }}. По умолчанию список выглядит следующим образом:
+В инвентори-файле `50-inventory.yaml` необходимо указать текущий список FQDN серверов, на которых будет установлен {{ ydb-short-name }}. По умолчанию список выглядит следующим образом:
   ```yaml
   all:
     children:
       ydb:
-        hosts:
-          static-node-1.ydb-cluster.com:
-          static-node-2.ydb-cluster.com:
-          static-node-3.ydb-cluster.com:
+        static-node-1.ydb-cluster.com:
+        static-node-2.ydb-cluster.com:
+        static-node-3.ydb-cluster.com:
   ```
 
-Далее нужно внести следующие изменения в раздел `vars` инвентаризационного файла:
+Далее необходимо внести следующие изменения в разделе `vars` инвентори-файла:
+
+  * `ansible_user` – укажите пользователя, от имени которого Ansible будет подключаться через SSH.
+  * `ansible_ssh_common_args: "-o ProxyJump=<ansible_user>@<static-node-1-IP>"` – опция для подключения Ansible к серверу по IP, с которого будет установлен {{ ydb-short-name }} (включая сервер ProxyJump). Используется при установке {{ ydb-short-name }} с локальной машины, не входящей в частную DNS-зону.
+  * `ansible_ssh_private_key_file` – измените путь до приватного SSH-ключа  на фактическое: `"../<ssh-private-key-name>"`.
+  * Выберите один из доступных вариантов развёртывания исполняемых файлов {{ ydb-short-name }}:
+    * `ydb_version`: автоматически загрузить один из [официальных релизов {{ ydb-short-name }}](../../downloads/index.md#ydb-server) по номеру версии. Например, `23.4.11`.
+    * `ydb_git_version`: автоматически скомпилировать исполняемые файлы {{ ydb-short-name }} из исходного кода, загруженного из [официального репозитория GitHub](https://github.com/ydb-platform/ydb). Значение настройки – это имя ветки, тега или коммита. Например, `main`.
+    * `ydb_archive`: локальный путь к архиву с дистрибутивом {{ ydb-short-name }}, [загруженного](../../downloads/index.md#ydb-server) или подготовленного заранее.
+    * `ydbd_binary` и `ydb_cli_binary`: локальные пути к исполняемым файлам сервера и клиента {{ ydb-short-name }}, [загруженным](../../downloads/index.md#ydb-server) или подготовленным заранее.
+
+#### Дополнительные изменения в инвентори-файлах
 
-  * `ansible_user` – укажите пользователь для подключения Ansible по SSH.
-  * `ansible_ssh_common_args: "-o ProxyJump=<ansible_user>@<static-node-1 IP>"` – опция для подключения Ansible к серверу по IP, с которого будет устанавливаться {{ ydb-short-name }} (включая ProxyJump сервер). Используется при установки {{ ydb-short-name }} с локальной машины, не входящей в приватную DNS-зону.
-  * `ansible_ssh_private_key_file` – измените дефолтное название ssh-ключа, на актуальное: `"../<ssh-private-key-name>"`.
-  * `ydb_archive` — укажите путь к скачанному ранее архиву с дистрибутивом {{ ydb-short-name }}.
-  * `ydb_tls_dir` – укажите актуальную часть пути (`/files/CA/certs/<date_time create certs>`) к сертификатам безопасности после их генерации скриптом `ydb-ca-update.sh`.
-  * `ydb_brokers` – укажите список FQDN нод брокеров. Например:
+При необходимости можно изменить эти настройки, но это не обязательно в простых случаях:
+
+  * `ydb_cores_static` – количество процессорных ядер, выделенных для статических узлов.
+  * `ydb_cores_dynamic` – количество процессорных ядер, выделенных для динамических узлов.
+  * `ydb_tls_dir` – укажите локальный путь к папке с заранее подготовленными TLS-сертификатами. Она должна содержать файл `ca.crt` и подкаталоги с именами, соответствующими именам узлов, содержащие сертификаты для каждого узла. Если параметр не указан, самоподписанные TLS-сертификаты будут сгенерированы автоматически для всего кластера {{ ydb-short-name }}.
+  * `ydb_brokers` – укажите список FQDN брокерных узлов. Например:
     ```yaml
     ydb_brokers:
       - static-node-1.ydb-cluster.com
       - static-node-2.ydb-cluster.com
       - static-node-3.ydb-cluster.com
     ``` 
-  * `ydb_cores_static` – задайте количество ядер CPU, потребляемое статической нодой;
-  * `ydb_cores_dynamic` – задайте количество ядер CPU, потребляемое динамической нодой.
 
 Значение переменной `ydb_database_groups` в разделе `vars` имеет фиксированное значение, которое привязано к типу избыточности и не зависит от размера кластера:
 
@@ -134,13 +124,17 @@ static-node-3 static-node-3.ydb-cluster.com
 
 {% endlist %}
 
-Изменения других секций конфигурационного файла `50-inventory.yaml` не требуются. Далее можно изменить стандартный пароль root пользователя {{ ydb-short-name }}, который содержится в зашифрованном инвентаризационном файле `99-inventory-vault.yaml` и файле `ansible_vault_password_file.txt`. Для изменения пароля укажите новый пароль в файле `ansible_vault_password_file.txt` и продублируйте его в файле `99-inventory-vault.yaml` в формате:
+Изменения других секций конфигурационного файла `50-inventory.yaml` не требуются.
+
+#### Изменение пароля пользователя root { #change-password }
+
+ Далее можно изменить стандартный пароль root пользователя {{ ydb-short-name }}, который содержится в зашифрованном инвентаризационном файле `99-inventory-vault.yaml` и файле `ansible_vault_password_file.txt`. Для изменения пароля укажите новый пароль в файле `ansible_vault_password_file.txt` и продублируйте его в файле `99-inventory-vault.yaml` в формате:
   ```yaml
   all:
     children:
       ydb:
         vars:
-          ydb_password: <new password>
+          ydb_password: <new-password>
   ```
 
 Для шифрования `99-inventory-vault.yaml` выполните команду `ansible-vault encrypt inventory/99-inventory-vault.yaml`.