Add new article: Run YDB cluster in cloud. (#1355)

Co-authored-by: Ivan Blinkov <ivan@ydb.tech>

README.md

@@ -1,4 +1,4 @@
-<img width="64" src="ydb/docs/_assets/logo.svg"/><br/>
+<img width="64" src="ydb/docs/_assets/logo.svg" /><br/>
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/ydb-platform/ydb/blob/main/LICENSE)
 [![Release](https://img.shields.io/github/v/release/ydb-platform/ydb.svg?style=flat-square)](https://github.com/ydb-platform/ydb/releases)

ydb/docs/en/core/getting_started/_includes/ansible/ansible-install-steps.md

@@ -0,0 +1,89 @@
+1. [Role `packages`](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/packages/tasks/main.yaml). Tasks:
+  * `check dpkg audit` – Verifies the [dpkg](https://en.wikipedia.org/wiki/Dpkg) state using the `dpkg --audit` command and saves the command results in the `dpkg_audit_result` variable. The task will terminate with an error if the `dpkg_audit_result.rc` command returns a value other than 0 or 1.
+  * `run the equivalent of "apt-get clean" as a separate step` – Cleans the apt cache, similarly to the `apt-get clean` command.
+  * `run the equivalent of "apt-get update" as a separate step` – Updates the apt cache, akin to the `apt-get update` command.
+  * `fix unconfigured packages` – Fixes packages that are not configured using the `dpkg --configure --pending` command.
+  * `set vars_for_distribution_version variables` – Sets variables for a specific Linux distribution version.
+  * `setup apt repositories` – Configures apt repositories from a specified list.
+  * `setup apt preferences` – Configures apt preferences (variable contents are specified in `roles/packages/vars/distributions/<distributive name>/<version>/main.yaml`).
+  * `setup apt configs`– Configures apt settings.
+  * `flush handlers` – Forcibly runs all accumulated handlers. In this context, it triggers a handler that updates the apt cache.
+  * `install packages` – Installs apt packages considering specified parameters and cache validity.
+
+Links to the lists of packages that will be installed for Ubuntu 22.04 or Astra Linux 1.7:
+* [List](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/packages/vars/distributions/Ubuntu/22.04/main.yaml) of packages for Ubuntu 22.04;
+* [List](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/packages/vars/distributions/Astra%20Linux/1.7_x86-64/main.yaml) of packages for Astra Linux 1.7.
+
+2. [Role `system`](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/system/tasks/main.yaml). Tasks:
+  * `configure clock` – A block of tasks for setting up system clocks:
+    + `assert required variables are defined` – Checks for the existence of the `system_timezone` variable. This check ensures that the necessary variable is available for the next task in the block.
+    + `set system timezone` – Sets the system timezone. The timezone is determined by the value of the `system_timezone` variable, and the hardware clock (`hwclock`) is set to UTC. After completing the task, a notification is sent to restart the `cron` service.
+    + `flush handlers` – Forces the execution of accumulated handlers using the `meta` directive. This will restart the following processes: `timesyncd`, `journald`, `cron`, `cpufrequtils`, and execute the `sysctl -p` command.
+  * `configure systemd-timesyncd` – A task block for configuring `systemd-timesyncd`:
+    + `assert required variables are defined` asserts that the number of NTP servers (`system_ntp_servers`) is more than one if the variable `system_ntp_servers` is defined. If the variable `system_ntp_servers` is not defined, the execution of the `configure systemd-timesyncd` task block will be skipped, including the check for the number of NTP servers and the configuration of `systemd-timesyncd`.
+    + `create conf.d directory for timesyncd` - Creates the `/etc/systemd/timesyncd.conf.d` directory if the `system_ntp_servers` variable is defined.
+    + `configure systemd-timesyncd` - Creates a configuration file `/etc/systemd/timesyncd.conf.d/ydb.conf` for the `systemd-timesyncd` service with primary and backup NTP servers. The task is executed if the `system_ntp_servers` variable is defined. After completing the task, a notification is sent to restart the `timesyncd` service.
+    + `flush handlers` - Calls accumulated handlers. Executes the handler `restart timesyncd`, which restarts the `systemd-timesyncd.service`.
+    + `start timesyncd` - Starts and enables the `systemd-timesyncd.service`. Subsequently, the service will start automatically at system boot.
+  * `configure systemd-journald` – A block of tasks for configuring the `systemd-journald` service:
+    + `create conf.d directory for journald` - Creates the `/etc/systemd/journald.conf.d` directory for storing `systemd-journald` configuration files.
+    + `configure systemd-journald` - Creates a configuration file `/etc/systemd/journald.conf.d/ydb.conf` for `systemd-journald`, specifying a `Journal` section with the option `ForwardToWall=no`. The `ForwardToWall=no` setting in the `systemd-journald` configuration means that system log messages will not be forwarded as "wall" messages to all logged-in users. After completing the task, a notification is sent to restart the `journald` service.
+    + `flush handlers` - Calls accumulated handlers. Executes the handler `restart journald`, which restarts the `systemd-journald` service.
+    + `start journald` - Starts and enables the `systemd-journald.service`. Subsequently, the service will start automatically at system boot.
+  * `configure kernel` – A block of tasks for kernel configuration:  
+    + `configure /etc/modules-load.d dir` - Creates the `/etc/modules-load.d` directory with owner and group permissions for the root user and `0755` permissions.
+    + `setup conntrack module` - Copies the `nf_conntrack` line into the file `/etc/modules-load.d/conntrack.conf` to load the `nf_conntrack` module at system start.
+    + `load conntrack module` - Loads the `nf_conntrack` module in the current session.
+    + `setup sysctl files` - Applies templates to create configuration files in `/etc/sysctl.d/` for various system settings (such as security, network, and filesystem settings). The list of files includes `10-console-messages.conf`, `10-link-restrictions.conf`, and others. After completing this task, a notification is sent to apply the kernel settings changes.
+    + `flush handlers` - Calls accumulated handlers. Executes the handler `apply kernel settings`, which runs the `sysctl -p` command to apply the kernel parameters specified in `/etc/sysctl.conf` or in other files in the `/etc/sysctl.d/` directory.
+  * `configure cpu governor` – A block of tasks for configuring the CPU frequency management mode: 
+    + `install cpufrequtils` - Installs the `cpufrequtils` package from apt. The task is set with cache check parameters and a task timeout of 300 seconds to expedite task execution and avoid an infinite loop waiting for apt package updates.
+    + `use performance cpu governor` - Creates the file `/etc/default/cpufrequtils` with content "GOVERNOR=performance", which sets the CPU governor mode to "performance" (disabling power-saving mode when CPU cores are idle). After completing the task, a notification is sent to restart the `cpufrequtils` service.
+    + `disable ondemand.service` - Disables the `ondemand.service` if it is present in the system. The service is stopped, its automatic start is disabled, and it is masked (preventing its start). After completing the task, a notification is sent to restart cpufrequtils.
+    + `flush handlers` - Calls accumulated handlers. Executes the handler `restart cpufrequtils`, which restarts the `cpufrequtils` service.
+    + `start cpufrequtils` - Starts and enables the `cpufrequtils.service`. Subsequently, the service will start automatically at system boot.
+
+3. [Role](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/ydbd/tasks/main.yaml) `ydbd`. Tasks:
+  * `check if required variables are defined` – Checks that the variables `ydb_archive`, `ydb_config`, `ydb_tls_dir` are defined. If any of these are undefined, Ansible will display an appropriate error message and stop the playbook execution.
+  * `set vars_for_distribution variables` – Sets variables from the specified file in the `vars_for_distribution_file` variable during playbook execution. This task manages a set of variables dependent on the specific Linux distribution.
+  * `ensure libaio is installed` – Ensures that the `libaio` package is installed.
+  * `install custom libidn from archive` – Installs a custom version of the `libidn` library from an archive.
+  * `create certs group` – Creates a system group `certs`.
+  * `create ydb group` – Creates a system group `ydb`.
+  * `create ydb user` – Creates a system user `ydb` with a home directory.
+  * `install YDB server binary package from archive` – Installs {{ ydb-short-name }} from a downloaded archive.
+  * `create YDB audit directory` – Creates an `audit` subdirectory in the {{ ydb-short-name }} installation directory.
+  * `setup certificates` – A block of tasks for setting up security certificates:
+    + `create YDB certs directory` – Creates a `certs` subdirectory in the {{ ydb-short-name }} installation directory.
+    + `copy the TLS ca.crt` – Copies the root certificate `ca.crt` to the server.
+    + `copy the TLS node.crt` – Copies the TLS certificate `node.crt` from the generated certificates directory.
+    + `copy the TLS node.key` – Copies the TLS certificate `node.key` from the generated certificates directory.
+    + `copy the TLS web.pem` – Copies the TLS pem key `web.pem` from the generated certificates directory.
+  * `copy configuration file` – Copies the configuration file `config.yaml` to the server.
+  * `add configuration file updater script` – Copies the `update_config_file.sh` script to the server.
+
+4. [Role `ydbd_static`](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/ydbd_static/tasks/main.yaml). Tasks:
+  * `check if required variables are defined` – Checks that the variables `ydb_cores_static`, `ydb_disks`, `ydb_domain`, `ydb_user` are defined. If any of these variables are undefined, the task will fail and an appropriate error message will be displayed for each undefined variable.
+  * `check if required secrets are defined` – Verifies that the secret variable `ydb_password` is defined. If this variable is undefined, the task will fail and an error message will be displayed.
+  * `create static node configuration file` – Creates a static node configuration file by running the copied `update_config_file.sh` script with `ydbd-config.yaml` and `ydbd-config-static.yaml` configurations.
+  * `create static node systemd unit` – Creates a `ydbd-storage.service` file for the static node based on a template. After completing the task, a notification is sent to restart the `systemd` service.
+  * `flush handlers` – Executes accumulated handlers. Restarts all `systemd` services.
+  * `format drives confirmation block` – A block of tasks for formatting disks and interrupting playbook execution in case the user declines confirmation. A confirmation request to format the connected disk will be displayed in the terminal. Response options: `yes` – to continue executing the playbook with disk formatting. Any other value will be interpreted as a refusal to format. By default, disks are formatted automatically without asking the user for permission, as the variables `ydb_allow_format_drives` and `ydb_skip_data_loss_confirmation_prompt` are set to `true`. If user confirmation is required, the value of the `ydb_skip_data_loss_confirmation_prompt` variable should be changed to `false` in the inventory file `50-inventory.yaml`.
+  * `prepare drives` – A task for formatting connected disks. Calls the `drive_prepare` plugin – a specially developed Ansible module for {{ ydb-short-name }} installation, which is part of the {{ ydb-short-name }} collection and is located in the directory `.../.ansible/collections/ansible_collections/ydb_platform/ydb/plugins/action/drive_prepare.py`. The module will format the connected disk specified in the `ydb_disks` variable if the `ydb_allow_format_drives` variable is set to `true`.
+  * `start storage node` – Starts the storage node process using `systemd`. If any errors occur during service startup, playbook execution will be interrupted.
+  * `get ydb token` – Requests a YDB token to perform the storage initialization command. The token is stored in the `ydb_credentials` variable. The task calls the `get_token` module from the directory `.../.ansible/collections/ansible_collections/ydb_platform/ydb/plugins/modules`. If any errors occur at this step, playbook execution will be interrupted.
+  * `wait for ydb discovery to start working locally` – Calls the `wait_discovery` module, which performs a `ListEndpoints` request to YDB to check the operability of the cluster's basic subsystems. If the subsystems are working properly, storage initialization commands and database creation can be executed.
+  * `init YDB storage if not initialized` – Initializes the storage if it has not already been created. The task calls the `init_storage` plugin, which performs the storage initialization command using a grpcs request to the static node on port 2135. The command result is stored in the `init_storage` variable.
+  * `wait for ydb healthcheck switch to "GOOD" status` – Waits for the YDB healthcheck system to switch to a `GOOD` status. The task calls the `wait_healthcheck` plugin, which performs a health check command on YDB.
+  * `set cluster root password` – Sets the password for the YDB root user. The task is executed by the `set_user_password` plugin, which performs a grpcs request to YDB and sets a pre-defined password for the YDB root user. The password is specified in the `ydb_password` variable in the inventory file `/examples/9-nodes-mirror-3-dc/inventory/99-inventory-vault.yaml` in an encrypted form.
+
+
+5. [Role `ydbd_dynamic`](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/ydbd_dynamic/tasks/main.yaml). Tasks:
+  * `check if required variables are defined` – Verifies the presence of required variables (`ydb_domain`, `ydb_pool_kind`, `ydb_cores_dynamic`, `ydb_brokers`, `ydb_dbname`, `ydb_dynnodes`) and displays an error if any variable is missing.
+  * `create dynamic node configuration file` – Creates a configuration file for dynamic nodes.
+  * `create dynamic node systemd unit` – Creates a systemd service for dynamic nodes. After completing the task, a notification is sent to restart the `systemd` service.
+  * `flush handlers` – Executes accumulated handlers. This will restart `systemd`.
+  * `start dynamic nodes` – Starts the process of dynamic nodes using `systemd`.
+  * `get ydb token` – Obtains a token for creating a database.
+  * `create YDB database` – Creates a database. The task is executed by the `create_database` plugin, which performs a request to 99-inventory-vault.yaml to create the database.
+  * `wait for ydb discovery to start working locally` – Calls the `wait_discovery` module again to check the operability of the cluster's basic subsystems.

ydb/docs/en/core/getting_started/_includes/ansible/ansible.md

@@ -0,0 +1,280 @@
+# Deploying {{ ydb-short-name }} cluster with Ansible
+
+This guide outlines the process of deploying a {{ ydb-short-name }} cluster on a group of servers using Ansible. {{ ydb-short-name }} can be deployed on any desired number of servers, but the minimum number of servers in the cluster should not be less than eight for the `block-4-2` redundancy model and nine servers for the `mirror-3-dc` redundancy model. You can learn about redundancy models from the article [{#T}](../../../deploy/configuration/config.md#domains-blob).
+
+During operation, the cluster can be [expanded](../../../maintenance/manual/cluster_expansion.md) without suspending access to the databases for users.
+
+{% note info %}
+
+**Recommended Server Requirements**:
+* 16 CPUs (calculated based on the utilization of 8 CPUs by the storage node and 8 CPUs by the dynamic node).
+* 16 GB RAM (recommended minimum RAM).
+* An additional 120 GB network SSD drive (cannot be smaller – installation requirements for {{ ydb-short-name }}).
+* SSH access;
+* Network connectivity between machines in the cluster.
+* OS: Ubuntu 18+, Debian 9+. 
+* Internet access for updating repositories and downloading necessary packages.
+
+{% endnote %}
+
+You can download the repository with the playbook for installing {{ ydb-short-name }} on the cluster from GitHub – `git clone https://github.com/ydb-platform/ydb-ansible-examples.git`. This repository contains: installation templates for deploying {{ ydb-short-name }} on a cluster of eight servers – `8-nodes-block-4-2`, and nine servers – `9-nodes-mirror-3-dc`, as well as scripts for generating TLS certificates and requirement files for installing necessary Python packages.
+
+{% cut "Repository Structure" %}
+
+{% include [repo-tree](./repo-tree.md) %}
+
+{% endcut %}
+
+
+To work with the project on a local (intermediate or installation) machine, you will need: Python 3 version 3.10+ and Ansible core version 2.15.2 or higher. Ansible can be installed and run globally (installed in the system) or in a virtual environment. If Ansible is already installed – you can move on to the step ["Configuring the Ansible project"](#ansible-project-setup), if Ansible is not yet installed, install it using one of the following methods:
+
+{% list tabs %}
+
+- Installing Ansible globally (in the system)
+
+  * Update the apt package list – `sudo apt update`.
+  * Upgrade packages – `sudo apt upgrade`.
+  * Install the `software-properties-common` package to manage your distribution's software sources – `sudo apt install software-properties-common`.
+  * Add a new PPA to apt – `sudo add-apt-repository --yes --update ppa:ansible/ansible`.
+  * Install Ansible – `sudo apt install ansible-core`.
+  * Check the Ansible core version – `ansible --version`
+
+- Installing Ansible in a Python virtual environment
+
+  * Update the apt package list – `sudo apt update`.
+  * Install the `venv` package for Python3 – `sudo apt install python3-venv`
+  * Create a directory where the virtual environment will be created and where the playbooks will be downloaded. For example, `mkdir ydb-install-ansible`.
+  * Go to the created directory and create a virtual environment – `python3 -m venv ydb-ansible`.
+  * Activate the virtual environment – `source venv/bin/activate`. All further actions with Ansible are performed inside the virtual environment. You can exit it with the command `deactivate`.
+  * Install the recommended version of Ansible using the command `pip install -r requirements.txt`, while in the root directory of the downloaded repository.
+  * Check the Ansible core version – `ansible --version`
+
+{% 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
+static-node-4 static-node-4.ydb-cluster.com
+static-node-5 static-node-5.ydb-cluster.com
+static-node-6 static-node-6.ydb-cluster.com
+static-node-7 static-node-7.ydb-cluster.com
+static-node-8 static-node-8.ydb-cluster.com
+static-node-9 static-node-9.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`.
+
+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.
+
+### 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.
+
+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:
+          static-node-4.ydb-cluster.com:
+          static-node-5.ydb-cluster.com:
+          static-node-6.ydb-cluster.com:
+          static-node-7.ydb-cluster.com:
+          static-node-8.ydb-cluster.com:
+          static-node-9.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_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.
+  * `ydb_brokers` – list the FQDNs of the broker nodes. For example:
+    ```yaml
+    ydb_brokers:
+        - static-node-1.ydb-cluster.com
+        - 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.
+* For the redundancy type `mirror-3-dc`, the value of `ydb_database_groups` is eight.
+
+The values of the `system_timezone` and `system_ntp_servers` variables depend on the infrastructure properties where the YDB cluster is being deployed. By default, `system_ntp_servers` includes a set of NTP servers without considering the geographical location of the infrastructure on which the YDB cluster will be deployed. We strongly recommend using a local NTP server for on-premise infrastructure and the following NTP servers for cloud providers:
+
+{% list tabs %}
+
+- AWS
+  * `system_timezone`: USA/<region_name>
+  * `system_ntp_servers`: [169.254.169.123, time.aws.com] [Learn more](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/set-time.html#configure-time-sync) about AWS NTP server settings.
+
+- Azure
+  * You can read about how time synchronization is configured on Azure virtual machines in [this](https://learn.microsoft.com/en-us/azure/virtual-machines/linux/time-sync) article.
+
+- Alibaba
+  * The specifics of connecting to NTP servers in Alibaba are described in [this article](https://www.alibabacloud.com/help/en/ecs/user-guide/alibaba-cloud-ntp-server).
+
+- Yandex Cloud
+  * `system_timezone`: Europe/Moscow
+  * `system_ntp_servers`: [0.ru.pool.ntp.org, 1.ru.pool.ntp.org, ntp0.NL.net, ntp2.vniiftri.ru, ntp.ix.ru, ntps1-1.cs.tu-berlin.de] [Learn more](https://cloud.yandex.ru/en/docs/tutorials/infrastructure-management/ntp) about Yandex Cloud NTP server settings.
+
+{% 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:
+  ```yaml
+  all:
+        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}
+
+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).
+
+The default {{ ydb-short-name }} configuration file already includes almost all the necessary settings for deploying the cluster. You need to replace the standard FQDNs of hosts with the current FQDNs in the `hosts` and `blob_storage_config` sections:
+* `hosts` section:
+  ```yaml
+  ...
+  hosts:
+  - host: static-node-1.ydb-cluster.com
+    host_config_id: 1
+    walle_location:
+      body: 1
+      data_center: 'zone-a'
+      rack: '1'
+  ...    
+  ```  
+* `blob_storage_config` section:
+  ```yaml
+  ...
+  - fail_domains:
+      - vdisk_locations:
+        - node_id: static-node-1.ydb-cluster.com
+          pdisk_category: SSD
+          path: /dev/disk/by-partlabel/ydb_disk_1
+  ...        
+  ```
+
+The rest of the sections and settings in the configuration file can remain unchanged.
+
+
+## Deploying the {{ ydb-short-name }} cluster {#erasure-setup}
+
+{% note info %}
+
+The minimum number of servers in a {{ ydb-short-name }} cluster is eight servers for the `block-4-2` redundancy model and nine servers for the `mirror-3-dc` redundancy model.
+
+In `mirror-3-dc` servers should be distributed across three availability zones or datacenters as evenly as possible.
+
+{% endnote %}
+
+The [repository](https://github.com/ydb-platform/ydb-ansible-examples) contains two ready sets of templates for deploying a {{ ydb-short-name }} cluster of eight (redundancy model `block-4-2`) and nine servers (`mirror-3-dc`). Either of the provided options can be scaled to any required number of servers, taking into account a number of technical requirements.
+
+To prepare your own template, you can follow the instructions below:
+1. Create a copy of the directory with the ready example (`9-nodes-mirror-3-dc` or `8-nodes-block-4-2`).
+2. Specify the FQDNs of the servers in the file `TLS/ydb-ca-nodes.txt` and execute the script `ydb-ca-update.sh` to generate sets of TLS certificates.
+3. Make changes to the inventory files of the template according to the [instructions](#inventory-edit).
+4. Make changes to the {{ ydb-short-name }} configuration file according to the [instructions](#ydb-config-prepare).
+5. Execute the command `ansible-playbook setup_playbook.yaml`, while in the directory of the cloned template.
+
+
+## Installation script execution plan for {{ ydb-short-name }} {#ydb-playbook-run}
+
+The sequence of role executions and their brief descriptions:
+1. The `packages` role configures repositories, manages APT preferences and configurations, fixes unconfigured packages, and installs necessary software packages depending on the distribution version.
+2. The `system` role sets up system settings, including clock and timezone configuration, time synchronization via NTP with `systemd-timesyncd`, configuring `systemd-journald` for log management, kernel module loading configuration, kernel parameter optimization through `sysctl`, and CPU performance tuning using `cpufrequtils`.
+3. The `ydb` role performs tasks related to checking necessary variables, installing base components and dependencies, setting up system users and groups, deploying and configuring {{ ydb-short-name }}, including managing TLS certificates and updating configuration files.
+4. The `ydb-static` role prepares and launches static nodes of {{ ydb-short-name }}, including checking necessary variables and secrets, formatting and preparing disks, creating and launching `systemd unit` for the storage node, as well as initializing the storage and managing database access.
+5. The `ydb-dynamic` role configures and manages dynamic nodes of {{ ydb-short-name }}, including checking necessary variables, creating configuration and `systemd unit` files for each dynamic node, launching these nodes, obtaining a token for {{ ydb-short-name }} access, and creating a database in {{ ydb-short-name }}.
+
+{% cut "Detailed step-by-step installation process description" %}
+
+{% include [ansible-install-steps](./ansible-install-steps.md) %}
+
+{% endcut %}
+
+As a result of executing the playbook, a {{ ydb-short-name }} cluster will be created, with a test database named `database`, a `root` user with maximum access rights created, and [Embedded UI](../../../maintenance/embedded_monitoring/index.md) running on port 8765. To connect to the Embedded UI, you can set up SSH tunneling. For this, execute the command `ssh -L 8765:localhost:8765 -i <ssh private key> <user>@<first-ydb-static-node-ip>` on your local machine. After successfully establishing the connection, you can navigate to the URL [localhost:8765](http://localhost:8765):
+
+![ydb-web-ui](../../_assets/ydb-web-console.png)
+
+## Monitoring the cluster state {#troubleshooting}
+
+After successfully creating the {{ ydb-short-name }} cluster, you can check its state using the Embedded UI – [http://localhost:8765/monitoring/cluster/tenants](http://localhost:8765/monitoring/cluster/tenants):
+
+![ydb-cluster-check](../../_assets/ydb-cluster-check.png)
+
+This section displays the following parameters of the {{ ydb-short-name }} cluster, reflecting its state:
+* `Tablets` – a list of running [tablets](../../../concepts/cluster/common_scheme_ydb.md#tablets). All tablet state indicators should be green;
+* `Nodes` – the number and state of static and dynamic nodes launched in the cluster. The node state indicator should be green, and the ratio of created to launched nodes should be equal. For example, 27/27 for a nine-node cluster.
+The `Load` indicators (amount of RAM used) and `Storage` (amount of disk space used) should also be green.
+
+You can check the state of the storage group in the `storage` section – [http://localhost:8765/monitoring/cluster/storage](http://localhost:8765/monitoring/cluster/storage):
+
+![ydb-storage-gr-check](../../_assets/ydb-storage-gr-check.png)
+
+The `VDisks` indicators should be green, and the `state` status (found in the tooltip when hovering over the Vdisk indicator) should be `Ok`. More about the cluster state indicators and monitoring can be read in the article [{#T}](../../../maintenance/embedded_monitoring/ydb_monitoring.md).
+
+## Cluster Testing { #testing }
+
+You can test the cluster using the built-in load tests in YDB CLI. To do this, download YDB CLI version [2.5.0](https://storage.yandexcloud.net/yandexcloud-ydb/release/2.5.0/linux/amd64/ydb) to the machine where Ansible is installed. For example, using wget: `wget https://storage.yandexcloud.net/yandexcloud-ydb/release/2.5.0/linux/amd64/ydb`.
+
+Make the downloaded binary file executable – `chmod +x ydb` and execute the connection check command:
+```shell
+./ydb \
+config profile create <profile name> \
+-d /Root/database \
+-e grpcs://< FQDN node >:2135 \
+--ca-file <path to generated certs>/CA/certs/ca.crt \
+--user root \
+--password-file <path to vault password file>/ansible_vault_password_file
+```
+Command parameters and their values:
+* `config profile create` – This command is used to create a connection profile. You specify the profile name. More detailed information on how to create and modify profiles can be found in the article [{#T}](../../../reference/ydb-cli/profile/create.md).
+* `-e` – Endpoint, a string in the format `protocol://host:port`. You can specify the FQDN of any cluster node and omit the port. By default, port 2135 is used.
+* `--ca-file` – Path to the root certificate for connections to the database using `grpcs`. The certificate is created by the `ydb-ca-update.sh` script in the `TLS` directory and is located at the path `TLS/CA/certs/` relative to the root of the ydb-ansible-examples repository.
+* `--user` – The user for connecting to the database. By default, the user `root` is created when executing the `setup_playbook.yaml` playbook.
+* `--password-file` – Path to the password file. In each folder with a YDB cluster deployment template, there is an `ansible_vault_password_file` that contains the password for the user `root`.
+
+You can check if the profile has been created using the command `./ydb config profile list`, which will display a list of profiles. After creating a profile, you need to activate it with the command `./ydb config profile activate <profile name>`. To verify that the profile has been activated, you can rerun the command `./ydb config profile list` – the active profile will have an (active) mark.
+
+To execute a YQL query, you can use the command `./ydb yql -s 'select 1;'`, which will return the result of the `select 1` command in table form to the terminal. After checking the connection, you can create a test table with the command:
+`./ydb workload kv init --init-upserts 1000 --cols 4`. This will create a test table `kv_test` consisting of 4 columns and 1000 rows. You can verify that the `kv_test` table was created and filled with test data by using the command `./ydb yql -s 'select * from kv_test limit 10;'`.
+
+The terminal will display a table of 10 rows. Now you can perform cluster performance testing. The article [{#T}](../../../reference/ydb-cli/workload-kv.md) describes 5 types of workloads (`upsert`, `insert`, `select`, `read-rows`, `mixed`) and the parameters for their execution. An example of executing the `upsert` test workload with the parameter to print the execution time `--print-timestamp` and standard execution parameters is: `./ydb workload kv run upsert --print-timestamp`.
+
+A report of the following type will be displayed in the terminal:
+```
+Window	Txs/Sec	Retries	Errors	p50(ms)	p95(ms)	p99(ms)	pMax(ms)	Timestamp
+1	    727	0	0	11	27	71	116	2024-02-14T12:56:39Z
+2	    882	0	0	10	21	29	38	2024-02-14T12:56:40Z
+3	    848	0	0	10	22	30	105	2024-02-14T12:56:41Z
+...
+```
+
+After completing the tests, the `kv_test` table can be deleted with the command: `./ydb workload kv clean`. More details on the options for creating a test table and tests can be read in the article [{#T}](../../../reference/ydb-cli/workload-kv.md).

ydb/docs/en/core/getting_started/_includes/ansible/repo-tree.md

@@ -0,0 +1,18 @@
+```text
+├── 8-nodes-block-4-2 / 9-nodes-mirror-3-dc
+│   ├── ansible.cfg # An Ansible configuration file containing settings for connecting to servers and project structure options. It is essential for customizing Ansible's behavior and specifying default settings.
+│   ├── ansible_vault_password_file # A file containing the password for decrypting encrypted data with Ansible Vault, such as sensitive variables or configuration details. This is crucial for securely managing secrets like the root user password.
+│   ├── creds # A directory for environment variables that specify the username and password for YDB, facilitating secure access to the database.
+│   ├── files
+│   │   ├── config.yaml # A YDB configuration file, which contains settings for the database instances.
+│   ├── inventory # A directory containing inventory files, which list and organize the servers Ansible will manage.
+│   │   ├── 50-inventory.yaml # The main inventory file, specifying the hosts and groups for Ansible tasks.
+│   │   └── 99-inventory-vault.yaml #  An encrypted inventory file storing sensitive information, such as the root user's password for YDB, using Ansible Vault.
+│   ├── setup_playbook.yaml # A playbook file that initiates the installation and configuration roles for setting up YDB on the cluster.
+├── README.md # A markdown file providing a description of the repository, including how to use it, prerequisites, and any other relevant information.
+├── requirements.txt # A file listing Python package dependencies required for the virtual environment, ensuring all necessary tools and libraries are installed.
+├── requirements.yaml # Specifies the Ansible collections needed, pointing to the latest versions or specific versions required for the project.
+├── TLS #A directory intended for storing TLS (Transport Layer Security) certificates and keys for secure communication.
+│   ├── ydb-ca-nodes.txt # Contains a list of Fully Qualified Domain Names (FQDNs) of the servers for which TLS certificates will be generated, ensuring secure connections to each node.
+│   └── ydb-ca-update.sh # A script for generating TLS certificates from the ydb-ca-nodes.txt list, automating the process of securing communication within the cluster.
+```

ydb/docs/en/core/getting_started/ansible.md

@@ -0,0 +1 @@
+{% include [ansible-ydb-cluster](./_includes/ansible/ansible.md) %}

ydb/docs/en/core/toc_i.yaml

@@ -8,6 +8,8 @@ items:
     href: getting_started/quickstart.md
   - name: Kubernetes
     href: getting_started/kubernetes.md
+  - name: Ansible
+    href: getting_started/ansible.md
 
 # Main
 - { name: Concepts,                               include: { mode: link, path: concepts/toc_p.yaml } }