|
1 | | -To switch the documentation language to Russian, follow this [link](./README-RU.md). |
2 | | -<hr> |
| 1 | +# Examples for managing YDB clusters with Ansible |
3 | 2 |
|
4 | | -# Installing YDB with Ansible |
| 3 | +This repository contains ready-to-use templates for deploying and managing [YDB](https://ydb.tech) clusters with [Ansible](https://www.ansible.com). |
5 | 4 |
|
6 | | -The repository contains ready-to-use templates for deploying a YDB cluster on servers, considering redundancy models `mirror-3-dc` and `block-4-2`. The templates can be scaled depending on the tasks. To download the repository, use the command `git clone https://github.com/ydb-platform/ydb-ansible-examples.git`. |
7 | | - |
8 | | -## Required dependencies, external files, and server requirements |
9 | | - |
10 | | -Please note that the machine onto which the repository is downloaded must meet the following requirements: |
11 | | -* Python 3 version 3.10+. |
12 | | -* Ansible core version not lower than 2.15.2. |
13 | | -* Network connectivity with the servers where YDB will be installed. |
14 | | - |
15 | | -The minimum number of servers required for deploying YDB is eight machines for the `block-4-2` redundancy type and nine machines for the `mirror-3-dc` redundancy type. The servers must meet the following requirements: |
16 | | -* 16 CPU cores. |
17 | | -* 16 GB RAM. |
18 | | -* SSD/HDD from 120 GB. |
19 | | -* SSH access via key. |
20 | | -* Local DNS zone. |
21 | | -* Internet access. |
22 | | - |
23 | | -To connect Ansible to the servers, a pre-prepared SSH key is required, which needs to be placed in the root directory of the downloaded repository and its name specified in the `ansible_ssh_private_key_file` variable of the inventory file `50-inventory.yaml` of the selected or cloned template. |
24 | | - |
25 | | -Also, the YDB current version [archive](https://ydb.tech/docs/ru/downloads/#ydb-server) needs to be uploaded to the root directory of the downloaded repository and the archive name specified in the `ydb_archive` variable of the inventory file `50-inventory.yaml`. |
26 | | - |
27 | | -To run the `setup_playbook.yaml` playbook, which executes the YDB cluster deployment scenario, it is necessary to install Ansible collections `ydb_platform.ydb` and `community.general`. The collections are installed with the command `ansible-galaxy install -r requirements.yaml`. After installing the collections, you can adapt an existing template from the repository or create your own template by cloning an existing one. |
28 | | - |
29 | | - |
30 | | -## Cluster deployment templates structure |
31 | | -The template directories (`8-nodes-block-4-2` and `9-nodes-mirror-3-dc`) are structured identically: |
32 | | -``` |
33 | | -. |
34 | | -├── ansible.cfg # Ansible configuration file. |
35 | | -├── ansible_vault_password_file # Password for the YDB root user. |
36 | | -├── creds # Environment variables defining the YDB user and password. |
37 | | -├── files # Subdirectory containing files to be uploaded to the server. |
38 | | -│ └── config.yaml # YDB configuration file. |
39 | | -├── inventory # Subdirectory containing Ansible inventory files. |
40 | | -│ ├── 50-inventory.yaml # Main inventory file containing hosts and vars. |
41 | | -│ └── 99-inventory-vault.yaml # Encrypted inventory file containing the root user password. |
42 | | -└── setup_playbook.yaml # YDB cluster deployment playbook. |
43 | | -``` |
44 | | -The main configuration file for the YDB deployment scenario is the `50-inventory.yaml` inventory file. It specifies: |
45 | | -* FQDNs of hosts where YDB will be deployed: |
46 | | - ```yaml |
47 | | - hosts: |
48 | | - static-node-1.ydb-cluster.com: |
49 | | - static-node-2.ydb-cluster.com: |
50 | | - static-node-3.ydb-cluster.com: |
51 | | - ... |
52 | | - ``` |
53 | | -* Cluster configuration and deployment variables: |
54 | | - + `ansible_user` – the user for Ansible to connect via SSH. |
55 | | - + `ansible_ssh_private_key_file` – path to the private part of the SSH key Ansible will use to connect to the servers. |
56 | | - + `system_timezone` – system timezone. |
57 | | - + `system_ntp_servers` – list of NTP server IPs for time synchronization on the servers. |
58 | | - + `ydb_archive` – path to the YDB archive for installation on the server. |
59 | | - + `ydb_config` – path to the YDB configuration file. |
60 | | - + `ydb_tls_dir` – path to the directory with TLS certificates. |
61 | | - + `ydb_user` – the name of the YDB user to be registered in the DBMS. |
62 | | - + `ydb_cores_static` – the number of CPU cores allocated for a static node. |
63 | | - + `ydb_disks`: |
64 | | - - `name`: /dev/vdb – path to the block device where the database will be located. |
65 | | - - `label`: ydb_disk_1 – label name to be assigned to the block device. |
66 | | - + `ydb_allow_format_drives` – variable that sets the condition for formatting the attached block device. |
67 | | - + `ydb_skip_data_loss_confirmation_prompt` – variable that determines the user's cancellation of the disk formatting confirmation (by default, the notification is not displayed). |
68 | | - + `ydb_domain` – the domain name (YDB cluster). |
69 | | - + `ydb_dbname` – the name of the database that will be automatically created after the cluster deployment. |
70 | | - + `ydb_pool_kind` – the type of disk. Can be ssd or hdd. |
71 | | - + `ydb_database_groups` – the number of storage groups. The variable has fixed values: seven for the `8-nodes-block-4-2` redundancy type and eight for `9-nodes-mirror-3-dc`, regardless of the number of servers. |
72 | | - + `ydb_cores_dynamic` – the number of CPU cores for dynamic nodes (per server). |
73 | | - + `ydb_dynnodes` – sets of dynamic node instances with an increment of the IC port offset. |
74 | | - + `ydb_brokers` – list of brokers. |
75 | | - |
76 | | -The other inventory file, `99-inventory-vault.yaml`, contains the password for the YDB root user in encrypted form. By default, the password is `password`. To change it, specify the new password in the following format: |
77 | | -```yaml |
78 | | -all: |
79 | | - children: |
80 | | - ydb: |
81 | | - vars: |
82 | | - ydb_password: <new password> |
83 | | -``` |
84 | | -Then execute the command `ansible-vault encrypt inventory/99-inventory-vault.yaml` to encrypt the file. Specify the new password in the ansible_vault_password_file. |
85 | | - |
86 | | -To generate a set of TLS certificates for encrypting traffic between cluster servers, you can use the `ydb-ca-update.sh` script, which uses the list of server FQDNs from the `ydb-ca-nodes.txt` file. |
87 | | - |
88 | | -When deploying the cluster, minor modifications to the YDB configuration file, located in the subdirectory `<template folder>/files/config.yaml`, are required. The following changes need to be made: |
89 | | -* Specify the current set of FQDNs for the servers in the `hosts` section: |
90 | | -```yaml |
91 | | - ... |
92 | | - hosts: |
93 | | - - host: static-node-1.ydb-cluster.com |
94 | | - host_config_id: 1 |
95 | | - walle_location: |
96 | | - body: 1 |
97 | | - data_center: 'zone-a' |
98 | | - rack: '1' |
99 | | - ... |
100 | | - ``` |
101 | | - |
102 | | -* Update the set of `node_id` in the `blob_storage_config` section: |
103 | | - ```yaml |
104 | | - ... |
105 | | - - fail_domains: |
106 | | - - vdisk_locations: |
107 | | - - node_id: static-node-1.ydb-cluster.com |
108 | | - pdisk_category: SSD |
109 | | - path: /dev/disk/by-partlabel/ydb_disk_1 |
110 | | - ... |
111 | | - ``` |
112 | | - |
113 | | -The other sections and settings of the configuration file remain unchanged. |
114 | | - |
115 | | -## Scaling the YDB cluster |
116 | | -To adapt the ready-made templates for the required number of servers, follow these steps: |
117 | | -1. Create a copy of the directory with the ready example (`9-nodes-mirror-3-dc` or `8-nodes-block-4-2`). |
118 | | -2. Specify the FQDNs of the servers in the `TLS/ydb-ca-nodes.txt` file and run the `ydb-ca-update.sh` script to generate sets of TLS certificates. |
119 | | -3. Make changes to the inventory files of the template `50-inventory.yaml` and `99-inventory-vault.yaml`. |
120 | | -4. Make changes to the YDB configuration file. |
121 | | -5. Execute the command `ansible-playbook setup_playbook.yaml` while in the directory of the cloned template. |
122 | | - |
123 | | - |
124 | | -## Verifying cluster operation |
125 | | - |
126 | | -As a result of executing the playbook, a YDB cluster will be created with a test database named `database`, a `root` user with maximum access rights will be created, and the Embedded UI will be launched on port 8765. To connect to the Embedded UI, you can set up SSH tunneling. To do this on your local machine, execute the command `ssh -L 8765:localhost:8765 -i <ssh private key> <user>@<first ydb static node ip>`. After successfully establishing the connection, you can navigate to the URL [localhost:8765](http://localhost:8765). |
| 5 | +For instructions on how to use them, refer to [YDB documentation](https://ydb.tech/docs/en/devops/ansible/). |
0 commit comments