Быстрый старт (1 узел)

Назначение

Кластер разворачивается одним сценарием Ansible — ролью zakroma-quick-start из архива поставки. Роль последовательно подготавливает узлы, настраивает PostgreSQL, применяет типовые настройки Закрома.Хранение и ZDS, выполняет preflight-проверки и устанавливает продукт.

Поддерживаются два варианта конфигурации — четырёхузловая и одноузловая (о ней в этой статье).

В одноузловом варианте на одном узле размещены как сервисы Закрома.Хранение и ZDS, так и PostgreSQL. Этот вариант сокращает количество серверов и подходит для первого знакомства с продуктом и проверки его функций.

В результате будут развёрнуты:

• один узел с Закрома.Хранение и ZDS: Закрома.Хранение предоставляет S3 API и управляет рабочими областями, бакетами и политиками доступа, а ZDS хранит данные объектов на диске узла;
• PostgreSQL на том же узле: база данных хранит метаданные, конфигурацию и служебную информацию Закрома.Хранение, но не содержимое S3-объектов;
• хранение в режиме Full Copy: объект хранится в одном экземпляре без отказоустойчивости и репликации;
• локальные пользователи без Keycloak и LDAP: учётные записи задаются в конфигурации Закрома.Хранение и используются для входа в Admin UI и последующего выпуска S3-ключей;
• HTTP-доступ без TLS и сертификатов;
• без опциональных сервисов Kafka, Nginx и отдельного балансировщика.

Не для production

Ресурсы из раздела «Минимальные требования» рассчитаны на функциональный пилот. В этом сценарии Admin UI и S3 API работают по HTTP: учётные данные, S3-ключи и объекты передаются без шифрования. Используйте конфигурацию только в изолированной тестовой сети. Для production нужны TLS, отдельный расчёт ресурсов, HA-кластер PostgreSQL и внешний отказоустойчивый балансировщик. См. Типовые варианты конфигурации.

Минимальные требования

Для быстрого старта необходим один физический или виртуальный узел стандартной архитектуры x86_64 (amd64). ARM-архитектура в этом сценарии не описывается.

В примере используется дистрибутив Debian 12. Роль quick-start рассчитана на использование именно с ним. С иными дистрибутивами рекомендуется использовать стандартный метод установки.

На узле должна быть включена синхронизация времени с внешним источником. Для функционального пилота достаточно сети 1 Гбит/с, для нагрузочных тестов рекомендуется минимум 10 Гбит/с.

Межсетевой экран на время установки отключите или настройте по разделу «Firewall». Не отключайте его вне изолированного тестового контура.

Диск на 50 ГБ даёт ровно 50 ГБ сырой ёмкости, так как все файлы хранятся в единственном экземпляре. Фактически доступно немного меньше из-за разметки файловой системы и служебных данных ZDS. Если объём тестовых данных превышает 50 ГБ, увеличьте размер каждого диска ZDS, чтобы сохранить запас свободного места. Подробнее о том, как ZDS хранит данные, см. Как ZDS хранит данные.

Схема стенда

Компоненты Закрома.Хранение и ZDS работают на одном узле совместно. Объекты и их метаданные хранятся на одном узле, и Закрома.Хранение использует PostgreSQL на том же узле по адресу postgresql.zakroma.internal:5432.

Параметры примера

Узлы и их IP-адреса приведены в таблице раздела «Схема стенда».

Замените примеры на адреса и имена из своей инфраструктуры.

Подготовка до запуска Ansible

Перед первым запуском плейбука выполните на узлах настройки из этого раздела.

Записи DNS

Если используете DNS, создайте A-записи:

Wildcard-запись покрывает global.zakroma.internal и имена вида <workspace>.zakroma.internal. Если DNS-сервер не поддерживает wildcard, создайте отдельные записи для global и каждой рабочей области.

DNS-сервер на узлах Debian 12

На узле и на управляющем сервере укажите адрес DNS-сервера, в котором созданы записи из таблицы выше. В примере ниже DNS-сервер — 192.168.1.2; замените его на IP-адрес своего DNS-сервера.

Сначала проверьте, какая служба управляет разрешением имён:

Copy
1ls -l /etc/resolv.conf
2resolvectl status 2>/dev/null || systemd-resolve --status 2>/dev/null

Если /etc/resolv.conf — симлинк на systemd-resolved (типично для Debian 12), задайте DNS через конфиг:

Copy
1sudo install -d -m 0755 /etc/systemd/resolved.conf.d
2sudo tee /etc/systemd/resolved.conf.d/zakroma.conf >/dev/null <<'EOF'
3[Resolve]
4DNS=192.168.1.2
5FallbackDNS=1.1.1.1
6Domains=zakroma.internal
7EOF
8sudo systemctl restart systemd-resolved
9resolvectl status

Проверьте, что в выводе resolvectl status для активного интерфейса указан DNS Servers: 192.168.1.2 и домен zakroma.internal.

Если узел настроен статически через /etc/network/interfaces, DNS можно указать в описании интерфейса:

Copy
1auto ens3
2iface ens3 inet static
3    address 192.168.1.11
4    netmask 255.255.255.0
5    gateway 192.168.1.1
6    dns-nameservers 192.168.1.2
7    dns-search zakroma.internal

После изменения перезапустите сеть (sudo ifdown ens3 && sudo ifup ens3) или перезагрузите узел.

Без отдельного DNS

Если своего DNS-сервера нет, записи можно не настраивать: на стадии bootstrap ответьте yes на вопрос «Прописать /etc/hosts на узлах» — роль добавит нужные имена локально. Файл /etc/hosts не поддерживает wildcard-записи, поэтому для клиентов и S3 вне кластера каждую рабочую область придётся прописать отдельно или использовать DNS.

Проверка DNS

На управляющем сервере и на узле:

Copy
1sudo apt-get update
2sudo apt-get install -y dnsutils
3getent ahostsv4 postgresql.zakroma.internal
4getent ahostsv4 zakroma-admin.zakroma.internal
5getent ahostsv4 global.zakroma.internal

Если DNS не используется, пропустите проверку.

Firewall

Проверьте межсетевой экран на узлах:

Copy
1command -v ufw && sudo ufw status
2command -v firewall-cmd && sudo firewall-cmd --state
3command -v nft && sudo nft list ruleset

Для изолированного пилотного контура firewall можно временно отключить. Если он включён, разрешите:

Пример правил UFW для подсети 192.168.1.0/24:

Copy
1# На узле Закрома.Хранение и ZDS.
2sudo ufw allow from 192.168.1.0/24 to any port 22 proto tcp
3sudo ufw allow from 192.168.1.0/24 to any port 6443 proto tcp
4sudo ufw allow from 192.168.1.0/24 to any port 8444 proto tcp
5sudo ufw status numbered

Если управляющий сервер или S3-клиенты находятся в другой подсети, добавьте отдельные точечные правила для их адресов.

Диски ZDS

На будущем узле Закрома.Хранение и ZDS смонтируйте отдельный диск в /data/zds до запуска роли. Роль проверяет, что /data/zds — точка монтирования отдельного тома, и создаёт внутри неё каталоги db, vacuum-state, scan-state, disk.

Форматирование удалит данные

Команда mkfs.xfs безвозвратно удалит данные на выбранном устройстве. Сверьте /dev/vdb с фактическим диском для данных.

Copy
1lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINTS,MODEL
2sudo wipefs --no-act /dev/vdb
3sudo mkfs.xfs /dev/vdb
4sudo install -d -m 0755 /data/zds
5ZDS_UUID=$(sudo blkid -s UUID -o value /dev/vdb)
6FSTAB_LINE="UUID=${ZDS_UUID} /data/zds xfs defaults,noatime 0 2"
7sudo grep -Fqx "$FSTAB_LINE" /etc/fstab || printf '%s\n' "$FSTAB_LINE" | sudo tee -a /etc/fstab
8sudo mount -a
9findmnt --target /data/zds

SSH-доступ

С управляющего сервера должен работать SSH с sudo на будущий узел Закрома.Хранение под одним пользователем. Пользователь и ключ передаются при запуске плейбука через -u и --private-key, в inventory они не сохраняются.

Copy
1ssh -i ~/.ssh/key_name user@192.168.1.11 'sudo -n true'

Подготовка поставки

Получите:

1. Архив zakroma-roles-<версия>.tar.gz. См. Таблица соответствия версий.
2. Файл лицензии.
3. Управляющий сервер с Ansible 2.15.0–2.18.15 и SSH/sudo-доступом к узлу.

Распакуйте архив:

Copy
1RELEASE_VERSION=8.1.0
2tar -xvzf "zakroma-roles-${RELEASE_VERSION}.tar.gz"
3cd "zakroma-roles-${RELEASE_VERSION}"
4ansible --version

Положите лицензию в каталог поставки:

Copy
1install -m 0644 /path/to/licence files/zakroma-licence/licence

Развёртывание кластера

Первый запуск (интерактивный)

Запускайте из корня распакованной поставки. Нужен TTY — сценарий задаёт вопросы через интерактивный ввод.

Copy
1ANSIBLE_CONFIG=ansible.cfg ansible-playbook \
2  -u user --private-key ~/.ssh/key_name \
3  -i inventories/quick-start/hosts \
4  playbooks/sample-play-quick-start-single-node.yml

На стадии bootstrap роль:

1. Скопирует group_vars из inventories/single-node в inventories/quick-start.
2. Спросит IP узла Закрома.Хранение и PostgreSQL (введите FQDN или IP).
3. Спросит базовый домен, точку монтирования ZDS (/data/zds), запись /etc/hosts (yes/no), пароли PostgreSQL, Admin UI и ZDS.
4. Если пакеты отсутствуют в roles/zakroma-storage/files и roles/zakroma-zds/files, спросит логин и пароль для их скачивания.
5. Запишет указанные данные в inventories/quick-start/hosts, group_vars/all/quick-start.yml и group_vars/all/quick-start-secrets.yml.

Далее выполняются стадии prepare, postgres, licence, preflight и install. Установка Закрома.Хранение и ZDS выполняется отдельным этапом плейбука после preflight.

Пароли

Пустой ввод пароля генерирует случайную строку. Сгенерированные пароли выводятся в консоль на стадии bootstrap. Не используйте символы :, ', " в паролях — они нарушают разбор YAML-конфигурации Закрома.Хранение.

CIDR для PostgreSQL

Роль добавляет в pg_hba.conf правило для подсетей из zakroma_quick_start_pg_cidrs. Если список пуст, используются /32-адреса узлов Закрома.Хранение. На стадии bootstrap можно указать свою подсеть, например 192.168.1.0/24.

Повторный запуск

Когда inventory и секреты уже записаны, запустите плейбук без интерактивного ввода. SSH-пользователь и ключ по-прежнему задаются флагами -u и --private-key или переменными ANSIBLE_USER и ANSIBLE_PRIVATE_KEY_FILE в окружении оператора; в inventory они не сохраняются.

Copy
1ANSIBLE_CONFIG=ansible.cfg ansible-playbook \
2  -u user --private-key ~/.ssh/key_name \
3  -i inventories/quick-start/hosts \
4  -e zakroma_quick_start_interactive=false \
5  playbooks/sample-play-quick-start-single-node.yml

Отдельные стадии

Copy
1# Только блок «Доступ» (URL, пароли, /etc/hosts для клиента)
2ANSIBLE_CONFIG=ansible.cfg ansible-playbook -i inventories/quick-start/hosts \
3  -u user --private-key ~/.ssh/key_name \
4  -e zakroma_quick_start_stage=access \
5  playbooks/sample-play-quick-start-single-node.yml
6
7# Только установка продукта (после успешного preflight)
8ANSIBLE_CONFIG=ansible.cfg ansible-playbook -i inventories/quick-start/hosts \
9  -u user --private-key ~/.ssh/key_name \
10  -e zakroma_quick_start_stage=install \
11  playbooks/sample-play-quick-start-single-node.yml

Сохранённые файлы inventory

После первого запуска в inventories/quick-start/ появятся:

Полное описание переменных одноузловой конфигурации: Установка Single Node.

Проверка сервисов

На узле Закрома.Хранение и ZDS проверьте:

Copy
1sudo systemctl is-active zakroma-storage-monolith.service
2sudo systemctl is-active zakroma-ds-agent.service
3sudo systemctl is-enabled zakroma-storage-monolith.service
4sudo systemctl is-enabled zakroma-ds-agent.service

Ожидаются active и enabled. Если сервис не запущен:

Copy
1sudo journalctl -u zakroma-storage-monolith.service -n 100 --no-pager
2sudo journalctl -u zakroma-ds-agent.service -n 100 --no-pager

Проверьте ZDS. curl запросит пароль из quick-start-secrets.yml (zakroma_zds_password):

Copy
1curl --fail --silent --show-error --user zakromaadmin http://localhost:8088/inner/status | jq -e '.status == "RUNNING" and .clusterStatus == "RW" and all(.volumes[]; .status == "RUNNING") and all(.nodes[]; .status == "RUNNING")'

Проверьте доступность PostgreSQL:

Copy
1sudo systemctl is-active postgresql
2sudo -u postgres psql -d zakroma -c '\dn+'

Проверьте разрешение доменного имени PostgreSQL:

Copy
1getent ahostsv4 postgresql.zakroma.internal
2nc -vz -w 3 postgresql.zakroma.internal 5432

Подробнее: Настройка PostgreSQL.

Проверка DNS и HTTP после установки

Проверьте DNS с управляющего сервера (если DNS использовался в инсталляции):

Copy
1dig +short A zakroma-admin.zakroma.internal | sort -u
2dig +short A global.zakroma.internal | sort -u

Проверьте Admin UI:

Copy
1curl --fail --silent --show-error \
2  --resolve zakroma-admin.zakroma.internal:8444:192.168.1.11 \
3  http://zakroma-admin.zakroma.internal:8444/auth/config >/dev/null
4echo "OK: Admin UI on 192.168.1.11"
5

Admin UI:

Copy
1http://zakroma-admin.zakroma.internal:8444

Стадия access плейбука выводит те же URL, пароли и фрагмент /etc/hosts для клиентской машины — команда запуска приведена в разделе «Отдельные стадии».

Подключение ZDS и создание бакета

Войдите под zakromaadmin с паролем из inventories/quick-start/group_vars/all/quick-start-secrets.yml (zakroma_admin_password). Роль автоматически создаёт тестовый бакет в отдельной рабочей области и подключает хранилище ZDS.

Во вкладке «Хранилища» убедитесь, что присутствует хранилище с названием ZDS. Если оно отсутствует, то добавить его можно с помощью этой инструкции: Хранилища.

Во вкладке «Рабочие области» убедитесь, что присутствует рабочая область с названием demo-ws, а в ней есть бакет demo. Перейдите в этот бакет, откройте раздел «Объекты» и попробуйте загрузить любой объект в бакет. Загрузка должна произойти успешно, а загруженный объект отобразится в списке.

В случае отсутствия бакета или прав на загрузку обратитесь к инструкциям ниже.

Подробнее про политики доступа: Политики доступа.

Подробнее: Рабочие области и Бакеты.

Проверьте, что wildcard-запись разрешает имя созданной области:

Copy
1dig +short A demo-ws.zakroma.internal | sort -u

Ожидается IP-адрес узла Закрома.Хранение — 192.168.1.11.

Проверка S3

Создайте для локального пользователя S3-ключ в Admin UI: нажмите на имя пользователя в правой верхней части страницы, затем на «Установить ключ доступа»; параметры можно не менять. Идентификатор ключа — это AWS_ACCESS_KEY_ID, секретный ключ — AWS_SECRET_ACCESS_KEY.

Копирование ключей не работает без HTTPS

Кнопки копирования идентификатора и секретного ключа работают только при включённом TLS, поэтому в этой конфигурации они недоступны.

Затем установите AWS CLI на управляющем сервере и передайте ключи через переменные окружения:

Copy
1export AWS_ACCESS_KEY_ID='<access-key>'
2read -rsp 'AWS Secret Access Key: ' AWS_SECRET_ACCESS_KEY
3export AWS_SECRET_ACCESS_KEY
4echo
5export S3_ENDPOINT='http://demo-ws.zakroma.internal:6443'
6export S3_BUCKET='demo'

Создайте тестовый файл, загрузите его в бакет, скачайте обратно, сравните содержимое и удалите объект:

Copy
1object="quick-start-$(date +%s).txt"
2printf 'Zakroma quick-start S3 check\n' >/tmp/zakroma-s3-source.txt
3aws --endpoint-url "$S3_ENDPOINT" s3 cp /tmp/zakroma-s3-source.txt "s3://${S3_BUCKET}/${object}"
4aws --endpoint-url "$S3_ENDPOINT" s3 ls "s3://${S3_BUCKET}/${object}"
5aws --endpoint-url "$S3_ENDPOINT" s3 cp "s3://${S3_BUCKET}/${object}" /tmp/zakroma-s3-downloaded.txt
6cmp /tmp/zakroma-s3-source.txt /tmp/zakroma-s3-downloaded.txt
7aws --endpoint-url "$S3_ENDPOINT" s3 rm "s3://${S3_BUCKET}/${object}"
8rm -f /tmp/zakroma-s3-source.txt /tmp/zakroma-s3-downloaded.txt
9unset AWS_SECRET_ACCESS_KEY

Критерии готовности

• Узел соответствует минимальным ресурсам.
• На узле Закрома.Хранение /data/zds смонтирован как отдельный том.
• DNS или /etc/hosts на узле разрешают FQDN стенда.
• Firewall отключён в изолированном контуре либо разрешает необходимые соединения.
• Плейбук sample-play-quick-start-single-node.yml завершился без ошибок на всех стадиях.
• PostgreSQL доступен с узла Закрома.Хранение по postgresql.<domain>:5432.
• На узле активны сервисы Закрома.Хранение и ZDS.
• Тома ZDS в статусе RUNNING, кластер — RW.
• Admin UI и S3 API доступны по HTTP на портах 8444 и 6443.
• Группа хранения создана с FC.
• Проверка S3 успешно записывает, читает и удаляет объект.

Распространённые ошибки

Ниже — частые причины падения плейбука на стадиях prepare, preflight и install. Текст сообщений может отличаться в зависимости от версии роли.

Доменные имена не разрешаются

Симптом. На стадии prepare или preflight:

Copy
1Имя postgresql.zakroma.internal не резолвится на storage-1.
2Настройте DNS для zakroma.internal или включите zakroma_quick_start_write_hosts.

Или на стадии preflight:

Copy
1Timeout when waiting for postgresql.zakroma.internal:5432

Причина. При zakroma_quick_start_write_hosts: false FQDN стенда должны разрешаться через DNS на узле Закрома.Хранение, ZDS и PostgreSQL. Если DNS не настроен, имя есть только на управляющем сервере или /etc/hosts ещё не записан.

Что сделать.

1. Настройте A-записи для postgresql.<domain>, zakroma-admin.<domain>, global.<domain> и FQDN узлов (см. раздел «Записи DNS»).
2. Либо на стадии bootstrap ответьте yes на вопрос о /etc/hosts, либо задайте zakroma_quick_start_write_hosts: true в group_vars/all/quick-start.yml и повторите стадию prepare.
3. Проверьте разрешение имён на проблемном узле:

Copy
1getent ahostsv4 postgresql.zakroma.internal
2getent ahostsv4 zakroma-admin.zakroma.internal

Файл лицензии не найден

Симптом. В начале прогона, на стадии bootstrap или licence:

Copy
1Положите лицензию в .../files/zakroma-licence/licence
2или задайте zakroma_quick_start_licence_src.

Причина. Роль ожидает файл лицензии на управляющем сервере до копирования на узлы Закрома.Хранение. Путь по умолчанию — files/zakroma-licence/licence в корне распакованной поставки.

Что сделать.

Copy
1install -m 0644 /path/to/licence files/zakroma-licence/licence
2# или укажите другой путь:
3# -e zakroma_quick_start_licence_src=/path/to/licence

Убедитесь, что файл обычный (не каталог) и содержит все поля лицензии (owner, licenseId, validTo, product, environment, licensedVolume, signature).

Диск ZDS не смонтирован

Симптом. На стадии prepare, задача «Проверить, что диск ZDS смонтирован»:

Copy
1/data/zds должен быть точкой монтирования отдельного тома,
2не каталогом на корневой ФС.
3Смонтируйте диск в этот путь и повторите.

Причина. Роль не форматирует и не монтирует диски. Каталог /data/zds на корневой файловой системе или пустой mount не подходят — нужен отдельный том (в примере /dev/vdb).

Что сделать. На узле Закрома.Хранение и ZDS выполните подготовку диска (см. раздел «Диски ZDS»), затем повторите плейбук:

Copy
1findmnt --target /data/zds
2df -h /data/zds
3lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINT /dev/vdb

Точка монтирования должна совпадать с zakroma_quick_start_zds_mount (по умолчанию /data/zds).

Дополнительно о роли zakroma-quick-start

Роль входит в поставку zakroma-roles версии 8.1.0 и находится в каталоге roles/zakroma-quick-start. Плейбук — playbooks/sample-play-quick-start-single-node.yml, inventory для первого запуска — заглушка inventories/quick-start/hosts.

Форматирование дисков и настройка DNS-сервера выполняются до запуска Ansible — роль эти шаги не выполняет (см. разделы «Диски ZDS» и «Записи DNS»).

Параметры для Quick Start (HTTP, file-auth, FC, порты 6443/8444, пароли из Vault или интерактивного ввода) роль применяет сама в inventories/quick-start/group_vars/zakroma-storage.yml и zakroma-zds-fs.yml. Публикация Admin UI через балансировщик (zakroma_storage_admin.reverse_proxy), включённая в примере базового кластера, в плейбуке sample-play-quick-start-single-node.yml отключается. Ручное редактирование этих файлов для типового сценария не требуется.

Что дальше

• Варианты развёртывания.
• Установка Single Node.
• Политики доступа.
• Настройка хранения бакета.
• Проверка статуса сервисов.