Установка CockroachDB на Ubuntu 24.04 — кластер из двух узлов

О чём эта инструкция

Это практическое руководство предназначено для администраторов и инженеров, которые хотят развернуть отказоустойчивый кластер CockroachDB на Ubuntu 24.04. В нём описаны требования, команды и рекомендуемые практики для безопасного запуска кластера из двух (или трёх) узлов. Если вы уже знакомы с PostgreSQL, вам будет проще понять модель совместимости SQL.

Краткое определение: CockroachDB — распределённая SQL-база данных с сильной консистентностью и автоматическим реплицированием данных между узлами.

Основные преимущества CockroachDB

• Сильная консистентность данных благодаря транзакциям по модели распределённых систем.
• Горизонтальная масштабируемость: добавление узлов расширяет ёмкость и пропускную способность.
• Высокая доступность: данные реплицируются и выдерживают отказы отдельных узлов.
• Совместимость с PostgreSQL на уровне клиентских протоколов и SQL-диалекта.

Важно: инструкция нацелена на локальные или приватные сети. Для облачных деплоев или публичных IP-адресов дополнительно настройте брандмауэр и политики безопасности.

Технические требования

• Два или три сервера с Ubuntu 24.04 (рекомендуется три для отказоустойчивости quorum, но двухузловой кластер возможен с внешним резервированием).
• Нетривиальный пользователь с правами администратора (не root) для повседневных операций.
• Доступ по SSH между серверами для передачи сертификатов.
• Права на изменение /opt и создание systemd-сервисов.

Примечание: если вы планируете развернуть более трёх узлов, адаптируйте разделы про конфигурацию –join и сетевые адреса.

Создание системного пользователя и структуры директорий

Мы создаём отдельного пользователя и группу cockroach, чтобы запускать сервис с минимальными привилегиями.

Выполните на всех серверах (server1 и server2):

sudo adduser --home /opt/cockroachdb --system --group cockroach
sudo chown -R cockroach:cockroach /opt/cockroachdb

Почему это важно: запуск служб под собственным системным пользователем снижает риск эскалации привилегий и ограничивает доступ к данным сервиса.

Загрузка и установка бинарника CockroachDB

Скачайте последний стабильный релиз CockroachDB с официального зеркала. В примере используется версия v24.1.1; замените ссылку при необходимости.

wget https://binaries.cockroachdb.com/cockroach-v24.1.1.linux-amd64.tgz
tar -xf cockroach-v24.1.1.linux-amd64.tgz
sudo cp -i cockroach-*/cockroach /usr/bin/

Проверьте установленную версию:

cockroach --version

Ожидаемый результат: вывод с номером версии CockroachDB v24.x.

Совет: поддерживайте /usr/bin/cockroach в системе обновлений (rpm/deb или собственный CI) и документируйте версию в конфигурации инфраструктуры.

Подготовка TLS-сертификатов

CockroachDB требует TLS для защищённого взаимодействия между узлами и клиентами. Мы создадим CA, подпишем серверные и клиентские сертификаты и распределим их между серверами.

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

sudo mkdir -p /opt/cockroachdb/{certs,private}
sudo chown -R $(whoami):$(whoami) /opt/cockroachdb/{certs,private}

Примечание: в примерах далее команды по генерации CA выполняются на server1. Затем CA-ключ и сертификат переносятся на server2.

Генерация CA

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

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

После команды в директориях появятся ca.crt и приватный ключ ca.key. Перенесите их на server2 с помощью scp (или другого защищённого канала):

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

Важное ограничение: держите ca.key в надёжном, ограниченном доступом хранилище. Потеря или компрометация CA-ключа требует перевыпуска сертификатов для всего кластера.

Клиентские сертификаты

Сертификат клиента нужен администраторам и автоматизированным инструментам управления.

Пример создания клиентского сертификата для пользователя root (выполняется на server1 где есть ca.key):

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

Выдастся набор файлов: root.crt и root.key в папке certs и private соответственно.

Сертификаты узлов кластера

Сертификат узла (node) должен включать в SAN IP-адрес и имена, по которым к нему будут обращаться.

На server1 выполните (замените IP и hostname на свои):

cockroach cert create-node \
server1 \
192.168.5.15 \
localhost \
--certs-dir=/opt/cockroachdb/certs \
--ca-key=/opt/cockroachdb/private/ca.key

На server2 выполните, указав его данные:

cockroach cert create-node \
server2 \
192.168.5.16 \
localhost \
--certs-dir=/opt/cockroachdb/certs \
--ca-key=/opt/cockroachdb/private/ca.key

После генерации убедитесь, что права доступа корректны и принадлежность файлов — пользователю cockroach:

sudo chown -R cockroach:cockroach /opt/cockroachdb/{certs,private}
sudo chmod 700 /opt/cockroachdb/private

Замечание по безопасности: ограничьте чтение приватных ключей только нужным системным пользователям и службам.

Настройка и запуск CockroachDB как systemd-сервиса

Чтобы CockroachDB запускался автоматически и корректно управляем был через systemctl, создадим systemd-юнит.

Создайте файл /etc/systemd/system/cockroachdb.service на каждом сервере и вставьте соответствующую конфигурацию. Для server1 пример:

[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.5.15 --join=192.168.5.15,192.168.5.16
TimeoutStopSec=60
Restart=always
RestartSec=10
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=cockroach
User=cockroach

[Install]
WantedBy=default.target

Для server2 той же файл, но с –advertise-addr=192.168.5.16.

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

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

Если статус показывает “active (running)”, сервис успешно стартовал.

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

После запуска демонов на всех узлах кластер нужно инициализировать из одного из узлов (обычно первичного).

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

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

Проверьте журналы на предмет сообщений о старте узла:

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

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

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

Доступ к SQL-оболочке:

sudo cockroach sql --certs-dir=/opt/cockroachdb/certs --host=server1:26257

Создание администратора:

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

Завершение сеанса: введите quit.

Рекомендация: замените простые пароли на сложные и храните учётные данные в менеджере секретов.

Веб-интерфейс администрирования

По умолчанию CockroachDB предоставляет HTTP-интерфейс на порту 8080. Доступ к нему осуществляется через браузер.

Откройте в браузере: http://server1:8080

Введите имя пользователя и пароль для доступа к панели управления. Интерфейс позволяет отслеживать топологию, метрики и логи.

Совет: если панель недоступна извне, настройте проброс портов или обратный прокси с аутентификацией.

Частые проблемы и способы диагностики

• Узлы не видят друг друга в –join: проверьте сетевую связность, firewall/ufw и маршрутизацию.
• Ошибка сертификата: убедитесь, что SAN в node-сертификате включает те имена/IP, которые используются при соединении.
• Сервис не стартует: изучите вывод journalctl -u cockroachdb и логи в cockroach-data/logs.

Примеры команд диагностики:

sudo journalctl -u cockroachdb --no-pager -n 200
sudo ss -tulpn | grep 26257
sudo ufw status verbose

Кейс: если вы запускаете кластер из двух узлов, учтите, что quorum для Raft требует нечётного числа реплик для автоматического избрания лидера в случае отказа узла. Рассмотрите добавление третьего (малого) голоса или использование внешнего storage/placement.

Резервное копирование и восстановление данных

CockroachDB поддерживает бэкап через команду cockroach dump/backup (зависит от версии). Используйте централизованное хранилище (S3/Cloud Storage) для долгосрочных снимков. Регулярно тестируйте восстановление на стенде.

Мини‑методология для бэкапов:

1. План: определите RPO/RTO и частоту снимков.
2. Выполнение: используйте cron/CI для периодического запуска резервных копий.
3. Валидация: тестируйте восстановление на тестовой среде ежемесячно.
4. Хранение: держите минимум 2 копии на разных носителях.

Роль‑ориентированные контрольные списки

Администратор (SRE):

• Проверить systemd-юнит и автозапуск.
• Настроить метрики и алерты.
• Держать доступ к CA-ключам в сейфе.

Инженер безопасности:

• Проверить права на /opt/cockroachdb.
• Настроить TLS и ротацию сертификатов.
• Контролировать доступ к веб-интерфейсу.

Разработчик БД:

• Тестировать SQL-совместимость с PostgreSQL.
• Планировать шардирование и размещение таблиц по зонам.

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

• Сервис cockroachdb запущен и активен на всех узлах.
• Cluster successfully initialized подтверждён при выполнении cockroach init.
• Узлы отображаются как active при выполнении cockroach node status.
• Веб‑панель доступна по http://:8080 и показывает метрики узлов.
• Установлен и проверен TLS между узлами и клиентами.

Тестовые сценарии и критерии приёма

1. Функциональный тест: создать базу, таблицу, вставить и прочитать данные. Ожидаемый результат — данные читаются консистентно.
2. Отказ узла: выключить server2, проверить, что кластер остаётся доступным (в зависимости от конфигурации quorum) и что при восстановлении узел синхронизируется.
3. Тест безопасности: попытка подключиться без сертификата должна завершаться ошибкой.

Откаты и восстановление при ошибках

Если вы случайно запустили ноду с неверными сертификатами или некорректными параметрами startup:

1. Остановите сервис: sudo systemctl stop cockroachdb.
2. Исправьте конфигурацию/сертификаты.
3. Пересоздайте node-сертификат при необходимости и перезапустите сервис.
4. Если требуется откат к резервной копии, выполните восстановление на тестовой среде перед продакшеном.

Альтернативы и когда CockroachDB может не подойти

• Если вам нужна строго OLAP-аналитика с колонковой оптимизацией, лучше выбрать специализированные движки (ClickHouse, Vertica).
• Если у вас очень простые требования и минимальные нагрузочные сценарии, то реляционные СУБД на одном хосте (PostgreSQL) могут быть дешевле и проще в поддержке.
• CockroachDB будет «избыточен», если нет требований к доступности и распределению нагрузки.

Советы по масштабированию и эксплуатации

• Начиная с трёх узлов легче обеспечить консенсус и отказоустойчивость.
• Мониторьте метрики задержки репликации и горячие ключи.
• Планируйте резервирование ресурсов (CPU/IO) для периодов пиковой нагрузки.

Совместимость и миграция

• CockroachDB совместим с клиентскими драйверами PostgreSQL, но перед миграцией проверяйте используемые расширения и нестандартные SQL-функции.
• Для миграции данных используйте экспорт/импорт через SQL или инструменты CDC, если требуются минимальные простои.

Краткая галерея крайних случаев

• Сертификат node не содержит IP/hostname — соединение TLS не установится.
• Некорректный –join список — узлы не образуют кластер.
• Недостаток числа узлов для quorum — при отказе одного узла кластер может потерять способность записывать данные.

Модель принятия решений (Mermaid)

flowchart TD
  A[Нужно ли горизонтально масштабировать данные?] -->|Да| B{Сколько узлов нужно}
  B --> |1-2| C[Рассмотрите PostgreSQL репликацию]
  B --> |3+| D[Использовать CockroachDB]
  A -->|Нет| E[Оставить монолитную БД]

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

• CA: центр сертификации, отвечает за подпись TLS-сертификатов.
• node: узел кластера CockroachDB.
• quorum: минимальное число реплик, необходимых для принятия решений в кластере.

Локальные особенности для Ubuntu 24.04

• Используйте systemd для управления сервисом.
• Проверяйте версии пакетов libc и ssl на совместимость с бинарником CockroachDB.
• На серверах с ограниченным диском устанавливайте ограничения логирования и упорядочьте retention для cockroach-data.

Короткое объявление для команды (пример)

Мы развернули кластер CockroachDB на Ubuntu 24.04 (server1, server2). Реестр сертификатов и systemd-юниты настроены. Администратор alice создан. Доступ к панели администрирования по http://server1:8080. Просьба тестировать на стенде до промо в прод.

Заключение

Вы установили и инициализировали кластер CockroachDB на Ubuntu 24.04. Мы прошли путь от создания системного пользователя до запуска systemd-сервиса и настройки TLS. В следующем шаге рекомендуется настроить мониторинг (Prometheus/Grafana), политику резервного копирования и план ротации сертификатов.

Важное: держите CA-ключ в защищённом хранилище и проверяйте права доступа на /opt/cockroachdb.

Краткое резюме:

• Создан системный пользователь и директории.
• Установлен бинарник CockroachDB.
• Сгенерированы CA, node и client сертификаты.
• Настроен systemd-юнит и инициализирован кластер.

Дополнительные материалы: используйте официальную документацию CockroachDB для подробных руководств по бэкапу, миграции и масштабированию.