Установка и настройка CockroachDB на AlmaLinux 9

Кратко: пошаговое руководство по развертыванию надежного CockroachDB-кластера на двух серверах AlmaLinux 9. Вы настроите FQDN, откроете нужные порты в firewalld, сгенерируете SSL/TLS-сертификаты, добавите systemd‑службу, инициализируете кластер, создадите администратора и проверите репликацию данных. Включены советы по безопасности, контрольные списки и сценарии приёмки.

Important: все команды выполните под пользователем с sudo, сохраняйте приватные ключи в защищённом месте.

Обзор и цель инструкции

CockroachDB — распределённая SQL‑СУБД с акцентом на консистентность и автоматическую репликацию данных между узлами. Цель этого материала — дать воспроизводимый набор команд и проверок для развёртывания защищённого CockroachDB‑кластера на AlmaLinux 9 и показать базовые операции (создание БД, таблиц, вставка и чтение данных).

К чему готовиться:

• Минимум два сервера AlmaLinux 9 (в примерах srv1 192.168.10.20 и srv2 192.168.10.21).
• Пользователь с правами sudo на каждом сервере.
• Доступ по SSH между серверами для копирования сертификатов.

Короткое пояснение терминов:

• FQDN: полное доменное имя хоста (Fully Qualified Domain Name).
• CA: центр сертификации, который подписывает сертификаты узлов и клиентов.
• Node certificate: сертификат узла CockroachDB (идентифицирует сервер в кластере).

Содержание

• Требования
• Настройка FQDN
• Установка CockroachDB (бинарник)
• Настройка firewalld
• Генерация SSL/TLS сертификатов
  • CA
  • Клиентские сертификаты
  • Node сертификаты
• Запуск CockroachDB как systemd‑службы
• Инициализация кластера
• Создание администратора и веб‑доступ
• Базовые операции: БД, таблица, INSERT/SELECT
• Проверка репликации
• Отладка и распространённые проблемы
• Безопасность и бэкап
• Критерии приёмки и тесты
• Ролевые чеклисты
• Ментальные модели и рекомендации

Требования

Перед началом убедитесь, что:

• Есть два либо более сервера AlmaLinux 9 с корректными IP.
• На каждом сервере пользователь с sudo.
• SSH‑доступ между серверами для передачи сертификатов.
• Понимание базовых команд systemd, firewall‑cmd и работы с файлами.

Пример среды в документе:

• srv1 — 192.168.10.20, FQDN srv1.hwdomain.lan
• srv2 — 192.168.10.21, FQDN srv2.hwdomain.lan

Настройка FQDN

Чтобы кластер корректно идентифицировал узлы, задайте FQDN и внесите записи в /etc/hosts.

На srv1 выполните:

sudo hostnamectl set-hostname srv1.hwdomain.lan

На srv2:

sudo hostnamectl set-hostname srv2.hwdomain.lan

Откройте /etc/hosts и добавьте строки (на обоих серверах):

192.168.10.20 srv1.hwdomain.lan srv1
192.168.10.21 srv2.hwdomain.lan srv2

Сохраните файл и проверьте:

sudo hostname -f
ping -c3 srv1.hwdomain.lan
ping -c3 srv2.hwdomain.lan

ALT: Интерактивная иллюстрация настройки FQDN и проверки ping между серверами

Установка CockroachDB (бинарный пакет)

CockroachDB можно запускать в контейнере или как бинарник. Здесь используем предсобранный бинарный пакет.

1. Установите curl, если он не установлен:

sudo dnf install curl -y

ALT: Терминал с командой установки curl через dnf

2. Скачайте и распакуйте бинарь (версия в примере v23.1.3 — при необходимости замените на актуальную):

curl https://binaries.cockroachdb.com/cockroach-v23.1.3.linux-amd64.tgz --output cockroach-v23.1.3.linux-amd64.tgz

tar -xzf cockroach-v23.1.3.linux-amd64.tgz

3. Скопируйте исполняемый файл в /usr/bin:

sudo cp -i cockroach-v23.1.3.linux-amd64/cockroach /usr/bin/

ALT: Окно терминала с распаковкой пакета CockroachDB и копированием бинарника

4. Проверьте путь и версию:

which cockroach
cockroach version

ALT: Вывод команд which и cockroach version в терминале

Настройка firewalld

Откройте порты, которые использует CockroachDB:

• 26257/tcp — клиентское подключение к кластеру (SQL)
• 8080/tcp — веб‑админка

Выполните на каждом узле:

sudo firewall-cmd --add-port={8080/tcp,26257/tcp} --permanent
sudo firewall-cmd --reload
sudo firewall-cmd --list-all

Эти команды добавляют порты и перезагружают конфигурацию firewalld.

ALT: Вывод списка правил firewalld с добавленными портами 8080 и 26257

Генерация SSL/TLS сертификатов

CockroachDB требует TLS‑сертификаты для защищённых соединений между узлами и клиентами. Мы создаём CA, node и client сертификаты с помощью встроенной команды cockroach.

Общая структура каталогов (на каждом узле):

/opt/cockroachdb/
├─ certs/
└─ private/

Создайте каталоги на обоих серверах:

mkdir -p /opt/cockroachdb/{certs,private}

Генерация CA

На srv1 выполните:

cockroach cert create-ca \
--certs-dir=/opt/cockroachdb/certs \
--ca-key=/opt/cockroachdb/private/ca.key

Это создаст /opt/cockroachdb/certs/ca.crt и /opt/cockroachdb/private/ca.key.

ALT: Создание CA‑сертификата cockroach cert create-ca и расположение файлов

Скопируйте CA‑ключ и CA‑сертификат на srv2 (секретный ключ храните защищённо):

scp /opt/cockroachdb/private/ca.key [email protected]:/opt/cockroachdb/private/
scp /opt/cockroachdb/certs/ca.crt [email protected]:/opt/cockroachdb/certs/

Important: передача приватного ключа по SSH допустима в контролируемой сети; в продакшне рассмотрите безопасные хранилища ключей.

Генерация клиентских сертификатов

На srv1 создайте сертификат для пользователя root:

cockroach cert create-client \
root \
--certs-dir=/opt/cockroachdb/certs \
--ca-key=/opt/cockroachdb/private/ca.key

Это создаст client.root.crt и client.root.key.

ALT: Вывод команды создания клиентского сертификата для root

Генерация node‑сертификатов

На каждом сервере создайте node‑сертификат с указанием FQDN и IP, например для srv1:

cockroach cert create-node \
srv1.hwdomain.lan \
192.168.10.20 \
localhost \
--certs-dir=/opt/cockroachdb/certs \
--ca-key=/opt/cockroachdb/private/ca.key

Для srv2 аналогично, с заменой имени и IP.

После этого в /opt/cockroachdb/certs появятся node.crt и node.key.

ALT: Создание node сертификата на srv1 с перечислением SAN (FQDN, IP, localhost)

ALT: Создание node сертификата на srv2 с перечислением SAN (FQDN, IP, localhost)

Совет: проверьте права на приватные ключи — только root или системный пользователь cockroach должен иметь к ним доступ.

Запуск CockroachDB как systemd‑службы

Рекомендуемый способ — создавать системную службу, чтобы процесс автоматически запускался и перезапускался.

1. Создайте системного пользователя и установите владельца каталога сертификатов и данных:

sudo adduser -d /opt/cockroachdb -r -U cockroach
sudo chown -R cockroach:cockroach /opt/cockroachdb

2. Создайте файл юнита systemd на каждом сервере: /etc/systemd/system/cockroachdb.service

На srv1 пример содержимого (здесь важно указать –advertise-addr):

[Unit]
Description=Cockroach Database cluster node
Requires=network.target

[Service]
Type=notify
WorkingDirectory=/opt/cockroachdb
ExecStart=/usr/bin/cockroach start --certs-dir=/opt/cockroachdb/certs --advertise-addr=192.168.10.20 --join=192.168.10.20,192.168.10.21
TimeoutStopSec=60
Restart=always
RestartSec=10
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=cockroach
User=cockroach

[Install]
WantedBy=default.target

На srv2 укажите –advertise-addr=192.168.10.21 и тот же список –join.

После создания юнита выполните:

sudo systemctl daemon-reload
sudo systemctl start cockroachdb
sudo systemctl enable cockroachdb
sudo systemctl status cockroachdb

Ожидаемый статус — active (running).

ALT: Статус systemd‑службы cockroachdb, сервис запущен и активен

ALT: Вывод systemctl status на srv1

ALT: Вывод systemctl status на srv2

Инициализация CockroachDB‑кластера

На одном из узлов (рекомендуется на srv1) выполните команду инициализации:

cockroach init --certs-dir=/opt/cockroachdb/certs --host=192.168.10.20:26257

Ожидаемый вывод: “Cluster successfully initialized”.

Проверьте логи на предмет запуска узлов:

grep 'node starting' /opt/cockroachdb/cockroach-data/logs/cockroach.log -A 11

Затем проверьте список узлов и статус:

cockroach node --certs-dir=/opt/cockroachdb/certs --host=192.168.10.20 ls
cockroach node --certs-dir=/opt/cockroachdb/certs --host=192.168.10.20 status

Ожидается, что оба узла будут в состоянии live/available.

ALT: Вывод команды cockroach init и подтверждение запуска узлов

Создание администратора и веб‑доступ

Подключитесь к кластеру из локального терминала (srv1) как root:

cockroach sql --certs-dir=/opt/cockroachdb/certs --host=srv1.hwdomain.lan:26257

В интерактивной оболочке выполните:

SHOW DATABASES;

Вы увидите defaultdb, postgres, system.

Создайте пользователя alice и предоставьте роль admin (замените пароль на безопасный):

CREATE USER alice WITH PASSWORD 'password';
GRANT admin TO alice;

Завершите сеанс: quit или Ctrl+D.

Откройте веб‑админку в браузере: http://192.168.10.20:8080/ и войдите под alice.

ALT: Форма входа в веб‑интерфейс CockroachDB

ALT: Основной дашборд CockroachDB с информацией о кластере и узлах

Базовые операции: создание БД, таблицы, вставка и чтение

Подключитесь как alice:

cockroach sql --user=alice --certs-dir=/opt/cockroachdb/certs --host=srv1.hwdomain.lan:26257

Создайте базу данных testdb и таблицу users:

CREATE DATABASE testdb;
CREATE TABLE testdb.users (
  id INT PRIMARY KEY NOT NULL,
  name TEXT NOT NULL,
  age INT NOT NULL,
  address CHAR(50),
  salary REAL
);

Вставьте данные:

USE testdb;
INSERT INTO users (id,name,age,address,salary) VALUES (1, 'Paul', 32, 'California', 20000.00);
INSERT INTO users (id,name,age,address,salary) VALUES (2, 'Jesse', 35, 'Mexico', 30000.00);
INSERT INTO users (id,name,age,address,salary) VALUES (3, 'Linda', 27, 'Canada', 40000.00);

Проверьте:

SELECT * FROM users;

Данные должны отобразиться в терминале.

ALT: Выполнение SQL‑запросов создания таблицы в CockroachDB

ALT: Вставка нескольких строк в таблицу users

ALT: Результат SELECT * FROM users в терминале

Проверка репликации

Чтобы убедиться, что данные реплицируются на другие узлы, подключитесь к srv2 и выполните те же запросы от alice:

cockroach sql --user=alice --certs-dir=/opt/cockroachdb/certs --host=srv2.hwdomain.lan:26257

Проверьте базы и таблицы:

SHOW DATABASES;
USE testdb;
SELECT * FROM users;

Если репликация работает, вы увидите testdb и строки в таблице users на srv2.

ALT: Подключение к CockroachDB на srv2 и вывод SHOW DATABASES

ALT: Результат SELECT * FROM users на srv2, подтверждающий репликацию

Отладка и распространённые проблемы

1. Сервис не стартует — смотрите логи systemd:

sudo journalctl -u cockroachdb -b --no-pager | tail -n 200

2. Ошибки TLS — убедитесь в корректности SAN (FQDN и IP) в node‑сертификатах и правах на файлы (/opt/cockroachdb/private/ca.key должны быть доступны только root).

3. Узлы не видят друг друга — проверьте правила firewalld, SELinux (если включён) и маршрутизацию.

4. Проблемы с JOIN — в параметре –join укажите все известные адреса узлов через запятую.

5. Неправильный владелец файлов — каталог /opt/cockroachdb и его подкаталоги должны принадлежать пользователю cockroach, если служба запускается от него.

Безопасность и рекомендации по продакшну

• Используйте сильные пароли и ротацию ключей.
• Не храните приватные ключи в общедоступных местах; применяйте Vault/Key Management System для CA‑ключа.
• Ограничьте доступ к портам 26257 и 8080 только внутренней сети.
• Включите регулярные бэкапы (см. заметку ниже).
• Мониторьте метрики и логи (Prometheus, Grafana, централизованные лог‑сборщики).

Бэкап и восстановление (коротко)

CockroachDB поддерживает CREATE BACKUP и RESTORE:

-- пример бэкапа всей БД
cockroach sql --certs-dir=/opt/cockroachdb/certs --host=srv1.hwdomain.lan:26257 -e "BACKUP DATABASE testdb TO 'nodelocal://1/testdb-backup';"

-- восстановление
cockroach sql --certs-dir=/opt/cockroachdb/certs --host=srv1.hwdomain.lan:26257 -e "RESTORE DATABASE testdb FROM 'nodelocal://1/testdb-backup' WITH into_db='restored_testdb';"

Нodelocal удобен для тестов. Для продакшна используйте объектные хранилища S3/GCS и планируйте регулярное сохранение snapshot‑ов.

Критерии приёмки

• Сервисы cockroachdb на обоих узлах в состоянии active (running).
• Команда cockroach init успешно выполнена с выводом Cluster successfully initialized.
• Веб‑интерфейс доступен по порту 8080 и вход по созданному пользователю alice работает.
• Запросы INSERT/SELECT показывают данные на обоих узлах.
• Логи не содержат критических ошибок TLS или network connection refused.

Тесты приёмки / кейсы

1. Проверка погашения отказа узла:
   • Остановите systemd‑службу на srv1, убедитесь, что srv2 продолжает отвечать на SELECT.
2. Проверка репликации:
   • Вставьте запись на srv1, выполните SELECT на srv2 и сравните строки.
3. Проверка безопасного доступа:
   • Попытайтесь подключиться без сертификатов — подключение должно быть запрещено.

Ролевые чеклисты

Администратор инфраструктуры:

• Настроить FQDN и /etc/hosts на всех узлах.
• Проверить правила firewall и SELinux.
• Создать системного пользователя cockroach и назначить права.

DBA / Системный администратор CockroachDB:

• Сгенерировать CA, node и client сертификаты.
• Инициализировать кластер и проверить статус узлов.
• Настроить регулярные бэкапы и мониторинг.

Разработчик приложения:

• Подключиться к кластеру с помощью клиентских сертификатов.
• Проверить корректность транзакций и запросов.

Ментальные модели и рекомендации

• Модель репликации: CockroachDB разбивает данные на диапазоны и реплицирует реплики диапазонов между узлами. Чем больше узлов, тем выше отказоустойчивость (обычно 3‑узловой кластер даёт устойчивость к отказу одного узла).
• Сбалансируйте количество реплик и доступное дисковое пространство: репликация увеличивает использование хранилища.

Мини‑методология развертывания (шаги высокого уровня)

1. Подготовка ОС и сети (FQDN, /etc/hosts, firewall).
2. Установка бинарей CockroachDB на все узлы.
3. Генерация CA и распространение сертификатов.
4. Создание systemd‑юнита и запуск службы на каждом узле.
5. Инициализация кластера на одном из узлов.
6. Создание пользователей, проверка веб‑интерфейса.
7. Тестирование репликации и создание бэкапов.

Модель зрелости кластера (рекомендации по росту)

• Начальный: 2 узла в тестовой сети, basic monitoring.
• Производственный: минимум 3 узла в разных стойках/зонах, централизованный мониторинг и бэкап в объектное хранилище.
• Продвинутый: гео‑репликация, шифрование на уровне хранилища, KMS для ключей, RBAC и аудит.

Частые ошибки и исправления

• “certificate signed by unknown authority”: проверьте, что ca.crt установлен в /opt/cockroachdb/certs на всех узлах и клиентах.
• Ошибки доступа к файлам: проверьте owner и mode приватных ключей.
• “connection refused”: откройте порт 26257 в firewalld и проверьте, что служба запущена.

Решение: откат изменений после ошибки развертывания

1. Остановите службу на узле: sudo systemctl stop cockroachdb
2. Удалите/переместите содержимое /opt/cockroachdb/cockroach-data (осторожно, приводит к потере данных):

sudo rm -rf /opt/cockroachdb/cockroach-data

3. Пересоздайте сертификаты и повторите init на контролирующем узле.

Notes: удаление данных — крайняя мера, используйте только в тестовой среде.

1‑строчный глоссарий

• Node: отдельный экземпляр CockroachDB, который участвует в кластере.
• CA: сертификат, подписывающий node/client сертификаты.
• nodelocal: локальное хранилище для бэкапов на нём же.

Факт‑бокс: ключевые пути и порты

• Сертификаты: /opt/cockroachdb/certs и /opt/cockroachdb/private
• Данные CockroachDB (по умолчанию): /opt/cockroachdb/cockroach-data
• Порты: 26257/tcp (SQL), 8080/tcp (web UI)

Заключение

Вы успешно развернули базовую конфигурацию CockroachDB на AlmaLinux 9, научились генерировать сертификаты, запускать службы через systemd, инициализировать кластер, создавать пользователей и проверять репликацию. Рекомендуется на следующих шагах автоматизировать развертывание (Ansible/Terraform), настроить мониторинг и реализовать политику бэкапов.

Summary: выполните контрольные тесты из раздела Критерии приёмки и Тесты приёмки, прежде чем переводить кластер в продуктив.