Пошаговая установка¶

Страница описывает установку S3R вручную: от проверки узлов до первой записи объекта. Она нужна администратору, который разворачивает кластер без роли Ansible, а также тому, кто разбирает, почему установка не завершается. Те же действия выполняет роль Ansible (см. Установка ролью Ansible).

Перед началом¶

Узлы соответствуют требованиям, ресурсы рассчитаны по разделу Расчёт ресурсов.
Топология выбрана по странице Планирование топологии: фактор репликации, домены отказа, схема избыточности яруса и число площадок на кластере с данными не меняются.
Архив плагина получен (см. Поставка).
Сертификаты TLS выпущены по главе Шифрование трафика.

В примерах кластер состоит из трёх узлов node1.example.net … node3.example.net, на каждом из которых работает один инстанс Picodata с четырьмя дисками. Схема избыточности соответствует разделу Пример: одна площадка. Версия плагина в примерах 2.2.0, тир Picodata — default.

Шаг	Где выполняется	Что делается
1	каждый узел	проверка файловой системы
2	каждый узел	распаковка архива плагина
3	каждый узел	конфигурация инстанса и список дисков
4	каждый узел, затем административная консоль	запуск кластера Picodata
5	административная консоль	регистрация, настройка и включение плагина
6	любой узел	проверка готовности
7	административная консоль	проверка дисков и групп размещения
8	административная консоль	ключ доступа S3
9	административная консоль и обратный прокси	консоль и API управления
10	рабочее место клиента	запись и чтение объекта

Шаг 1. Проверка узлов¶

На каждом узле проверьте, что файловая система, на которой будут размещены диски хранилища, допускает открытие файлов с флагом O_DIRECT:

mkdir -p /data/s3r/d0
dd if=/dev/zero of=/data/s3r/d0/probe bs=4096 count=1 oflag=direct
rm /data/s3r/d0/probe

Результат. Команда dd завершается без ошибки. Ошибка Invalid argument означает, что файловая система не поддерживает O_DIRECT, и эта директория диском хранилища служить не может.

Доступность io_uring на этом шаге не проверяется. Её проверяет плагин при запуске: диск, для которого механизм недоступен, не монтируется, и событие записывается в журнал. Результат виден на шаге 7.

Шаг 2. Размещение архива¶

На каждом узле распакуйте архив в директорию плагинов Picodata, заданную параметром instance.share_dir:

tar -xzf s3r_2.2.0-ubuntu_22.04.tar.gz -C /usr/share/picodata

Результат. В директории /usr/share/picodata/s3r/2.2.0/ появились libs3r.so, manifest.yaml и migrations/. Имя директории должно совпадать с версией, указанной в командах SQL на шаге 5.

Шаг 3. Конфигурация инстансов¶

На этом шаге готовятся файл конфигурации каждого инстанса, список его дисков и параметры памяти и потоков. Инстансы запускаются на шаге 4.

Часть значений применяется один раз

Фактор репликации тира применяется при первом запуске кластера и в дальнейшем не изменяется. Список дисков инстанс читает один раз, при первом запуске сервиса s3r_storage. Проверьте оба значения до запуска.

Файл конфигурации¶

В файле конфигурации каждого инстанса Picodata укажите фактор репликации тира, домен отказа, директорию плагинов, порт HTTP для консоли и слушатели двух сервисов плагина. Пример для node1:

cluster:
  tier:
    default:
      replication_factor: 3
      can_vote: true
instance:
  share_dir: /usr/share/picodata
  http_listen: "127.0.0.1:6006"
  failure_domain:
    host: node1
  plugin:
    s3r:
      service:
        s3r_api:
          listener:
            enabled: true
            listen: "0.0.0.0:8443"
            tls:
              enabled: true
              cert_file: /etc/s3r/server.pem
              key_file:  /etc/s3r/server.key
        s3r_storage:
          listener:
            enabled: true
            listen: "0.0.0.0:8700"
            advertise: "node1.example.net:8700"
            tls:
              enabled: true
              cert_file: /etc/s3r/node1.pem
              key_file:  /etc/s3r/node1.key
              ca_file:   /etc/s3r/cluster-ca.pem

Конфигурации узлов различаются тремя параметрами:

компонент host домена отказа;
адрес advertise;
сертификат узла для внутрикластерного контура.

Назначение параметров:

Параметр	Назначение	На что обратить внимание
`replication_factor`	фактор репликации тира	после первого запуска кластера не изменяется
`failure_domain`	домен отказа инстанса	компонента `dc` нет, потому что площадка одна; компонент `host` есть, потому что инстансов несколько (см. Планирование топологии)
`share_dir`	директория плагинов	та, в которую распакован архив на шаге 2
`http_listen`	порт консоли и API управления	в примере открыт только на локальном адресе, потому что снаружи консоль публикуется через обратный прокси (шаг 9)
слушатель `s3r_api`	принимает запросы S3 от клиентов	—
слушатель `s3r_storage`	обмен фрагментами между узлами	порт должен быть недоступен клиентам; параметр `ca_file` для внутрикластерного контура обязателен

Выпуск сертификатов и назначение каждого параметра TLS описаны в главе Шифрование трафика.

Несколько инстансов на одном узле

Все инстансы одного узла объявляют одно и то же значение host: S3R доверяет объявленному домену и считает инстансы с разными доменами независимыми.

Список дисков¶

Диски хранилища задаются одним из двух способов:

Условие	Способ
Пути дисков совпадают на всех узлах	параметр плагина `s3r_storage.disks` на шаге 5
Пути различаются, например при нескольких инстансах на одном узле	переменная окружения `S3R_DISKS` у каждого инстанса

Пример переменной:

S3R_DISKS=/data/s3r/d0:hba=a,/data/s3r/d1:hba=b,/data/s3r/d2:hba=c,/data/s3r/d3:hba=d

Формат переменной описан в разделе Переменные окружения. В каждую директорию примера смонтирована отдельная файловая система, поэтому ёмкость дисков не задаётся (см. Ёмкость диска).

При первом запуске сервиса s3r_storage инстанс регистрирует диски из списка в таблице s3r_disk. Дальше перечнем дисков инстанса служат записи этой таблицы, а диски добавляются и удаляются действиями API управления (см. Действия с дисками). Поэтому список проверяется до первого запуска по следующим правилам:

Каждый диск яруса на инстансе объявляет свой поддомен hba=, и поддомены дисков одного яруса на инстансе не повторяются. Единственный диск яруса на инстансе может поддомена не объявлять.
В одном ярусе на инстансе либо все диски объявляют поддомен, либо ни один.
Поддомен не содержит компонента dc: площадку задаёт только инстанс.
Все инстансы, у которых есть диски яруса, объявляют одинаковый набор поддоменов этого яруса. Этот набор называется шаблоном яруса.
Тома, которые отказывают вместе, например логические тома одного контроллера RAID, образуют один диск, а не несколько дисков в одном поддомене.

Что происходит при нарушении:

Список, нарушающий одно из правил 1–3, не регистрирует ни одного диска. Причина записывается в журнал и в строку инстанса в таблице s3r_instance.
Расхождение с шаблоном яруса (правило 4) выявляет начальное формирование.

Память и рабочие потоки¶

Объём памяти memtx задаётся параметром instance.memtx.memory, а размер пула рабочих потоков — переменной окружения S3R_WORKER_THREADS. Значения обоих параметров рассчитываются по разделу Расчёт ресурсов.

Результат. На каждом узле есть файл конфигурации инстанса; переменные окружения S3R_DISKS (если диски задаются ею) и S3R_WORKER_THREADS заданы для процесса инстанса.

Шаг 4. Запуск кластера¶

Запустите инстансы Picodata с подготовленной конфигурацией.
Подключитесь к административной консоли любого из них, например:
```
picodata admin /var/run/picodata/node1.sock
```
Команды SQL следующих шагов выполняются в этой консоли.
Проверьте, что все инстансы в сети, а каждый репликасет содержит столько инстансов, сколько задаёт фактор репликации:
```
SELECT name, replicaset_name, current_state, failure_domain
  FROM _pico_instance ORDER BY replicaset_name, name;
```

Результат. Каждый инстанс находится в состоянии Online. Неполный репликасет задерживает начальное формирование кластера.

Шаг 5. Регистрация, настройка и включение плагина¶

Порядок команд существенен

Сервисы назначаются тирам и контекст миграции задаётся до запуска миграций. Диски задаются до включения плагина. Когда зарегистрирован первый диск, команда, изменяющая s3r_storage.disks, отклоняется.

Выполните команды SQL в указанном порядке. Команду с s3r_storage.disks пропустите, если диски заданы переменной S3R_DISKS.

CREATE PLUGIN s3r 2.2.0;

ALTER PLUGIN s3r 2.2.0 ADD SERVICE s3r_storage TO TIER default;
ALTER PLUGIN s3r 2.2.0 ADD SERVICE s3r_meta TO TIER default;
ALTER PLUGIN s3r 2.2.0 ADD SERVICE s3r_api TO TIER default;

ALTER PLUGIN s3r 2.2.0 SET migration_context.storage_tier = 'default';
ALTER PLUGIN s3r 2.2.0 SET migration_context.extent_size = '1GiB';
ALTER PLUGIN s3r 2.2.0 SET migration_context.engine = 'memtx';
ALTER PLUGIN s3r 2.2.0 SET migration_context.unlogged = '';

ALTER PLUGIN s3r MIGRATE TO 2.2.0;

ALTER PLUGIN s3r 2.2.0 SET
  s3r_storage.disks = '[{"path":"/data/s3r/d0","failure_domain":"hba=a"},
                        {"path":"/data/s3r/d1","failure_domain":"hba=b"},
                        {"path":"/data/s3r/d2","failure_domain":"hba=c"},
                        {"path":"/data/s3r/d3","failure_domain":"hba=d"}]';
ALTER PLUGIN s3r 2.2.0 SET
  s3r_storage.erasure = '[{"k":2,"m":2}]';

ALTER PLUGIN s3r 2.2.0 ENABLE;

Что делает каждая группа команд и почему она стоит на своём месте:

Команды	Что делают	Почему в этом месте
`CREATE PLUGIN`	регистрируют плагин	версия совпадает с именем директории из шага 2
`ADD SERVICE ... TO TIER`	назначают три сервиса на тир	до миграций: имя тира подставляется в текст миграций
`SET migration_context.*`	задают контекст миграции	до миграций: имя тира и движок хранения подставляются в текст миграций
`MIGRATE TO`	создают таблицы плагина	—
`SET s3r_storage.disks`	задают список дисков	до включения: инстанс читает список один раз, при первом запуске сервиса `s3r_storage`
`SET s3r_storage.erasure`	задают схему избыточности яруса	до включения. Схему можно задать и позже: начальное формирование ждёт схемы каждого яруса, в котором есть диски
`ENABLE`	включают плагин	после него начинается начальное формирование

Дополнительные условия:

Все три сервиса назначаются на один тир: разделение сервисов по разным тирам не поддерживается, и плагин с различающимися списками тиров не включается (см. Три сервиса). Имя тира выбирает администратор, и то же имя указывается в migration_context.storage_tier.
Команда ALTER PLUGIN ... SET для s3r_storage проверяет новое значение до сохранения и при нарушении правил отклоняется целиком, ничего не сохраняя (см. Сервис s3r_storage).
Схема k=2, m=2 требует для каждой группы четыре диска в различных доменах отказа. Топология выбирается по странице Планирование топологии, а значения k и m — по разделу Выбор схемы избыточности яруса.

Результат. Команды завершились без ошибок. После команды ENABLE кластер проходит начальное формирование: инстансы регистрируют диски, кластер проверяет топологию и создаёт первые группы размещения. До его завершения запись объектов отклоняется (см. Начальное формирование). Завершение проверяется на следующем шаге.

Шаг 6. Проверка готовности¶

На любом узле проверьте, что эндпоинт S3 отвечает и что кластер готов к работе:

curl --cacert /etc/s3r/ca.pem https://node1.example.net:8443/-/health
curl --cacert /etc/s3r/ca.pem https://node1.example.net:8443/-/ready

Ответ /-/health не означает готовности

Ответ /-/health подтверждает только работу процесса. Готовность показывает /-/ready.

Результат. /-/ready отвечает кодом 200 и телом {"status":"ready"}.

Ответы /-/ready:

Ответ	Что означает
`200`, тело `{"status":"ready"}`	начальное формирование завершено, инстанс загрузил свои группы размещения и в каждом ярусе, где у него есть группы, восстановил хотя бы одну из них
`503`; поле `status` содержит состояние кластера `new`, поле `step` — шаг формирования, поле `waiting` перечисляет, чего формирование ждёт	формирование идёт
`503`; тело содержит поле `has_taken_groups`, поле `waiting` перечисляет ярусы, в которых ни одна группа ещё не восстановлена	инстанс после запуска ещё не восстановил группы

Если ожидание формирования не заканчивается, причины разбираются по разделу Если установка не завершается.

Как готовность связана с записью:

После запуска группа принимает запись, когда инстанс восстановил по каталогу, какие блоки в ней заняты.
Когда инстанс восстановил хотя бы одну группу в каждом ярусе, ответ /-/ready остаётся 200 до следующего запуска, даже если группа потом закрывается или теряет кворум: чтение продолжается, а в ответе на отклонённую запись указана причина.
Пока инстанс после запуска не прочитал таблицы метаданных, запросы S3 к нему получают ответ 503 ServiceUnavailable, который клиенты S3 повторяют. Балансировщик нагрузки не направляет запросы на такой инстанс, если проверяет /-/ready.

Шаг 7. Проверка дисков и групп размещения¶

В административной консоли выполните запросы:

SELECT name, replication_factor FROM _pico_tier;

SELECT state, step, sites, founding_members, tiers FROM s3r_cluster;

SELECT instance_name, reason FROM s3r_instance ORDER BY instance_name;

SELECT instance_name, path, failure_domain, tier, state FROM s3r_disk
 ORDER BY instance_name;

SELECT pg_id, site, tier, k, m, layout, n, state, owner FROM s3r_pg ORDER BY pg_id;

Результат.

Таблица	Что должно быть
`_pico_tier`	фактор репликации тира совпадает с выбранной схемой избыточности
`s3r_cluster`	столбец `state` имеет значение `active`, столбец `step` пуст, столбец `sites` перечисляет площадки, а `tiers` содержит шаблон, схему и классы блоков каждого яруса
`s3r_instance`	у каждого инстанса столбец `reason` пуст
`s3r_disk`	каждый диск находится в состоянии `active`
`s3r_pg`	у каждого инстанса с дисками есть первая группа (`n = 0`) в каждом его ярусе, в состоянии `new` или `active`

Диск, которого нет в s3r_disk, не зарегистрирован. Причина записана в журнале его инстанса и в столбце reason таблицы s3r_instance.

Шаг 8. Учётные данные¶

Секретные ключи попадают в журнал при включённом sql_log

Команда ALTER PLUGIN ... SET не относится к командам управления доступом, поэтому при включённом параметре sql_log Picodata записывает её текст в журнал целиком. Секретные ключи из s3r_api.credentials и секрет клиента s3r_api.iam.client_secret попадают в журнал вместе с текстом команды. Не включайте sql_log, пока задаёте эти параметры. Ключи доступа можно выдавать через API управления: их секреты в текст команд не попадают.

Создайте пользователя Picodata и выдайте ему ключ доступа S3 начального тенанта:

CREATE USER "alice" WITH PASSWORD 'Str0ngPassw0rd' USING scram-sha256;

ALTER PLUGIN s3r 2.2.0 SET s3r_api.credentials =
  '[{"access_key":"AKIAEXAMPLE000000001","secret_key":"...","pico_user":"alice"}]';

Результат. Обе команды завершились без ошибок. Ключ доступа действителен, пока существует названный им пользователь.

Выдача ключей другим тенантам и смена ключей описаны в разделе Учётные данные.

Шаг 9. Консоль и API управления за обратным прокси¶

Консоль и API управления обслуживает встроенный HTTP-сервер Picodata на порту instance.http_listen по путям /s3gateway/console/ и /s3gateway/api/.

Публикуйте консоль по HTTPS

Пароль при входе в консоль передаётся по сети. Обычно перед портом http_listen ставят обратный прокси, который принимает TLS и передаёт запросы инстансам.

Включите консоль и API параметром s3r_api.control_api и задайте способ входа параметром s3r_api.iam:
```
ALTER PLUGIN s3r 2.2.0 SET s3r_api.control_api = 'true';
ALTER PLUGIN s3r 2.2.0 SET s3r_api.iam = '{"auth_type": "picodata"}';
```
Вход по паролю Picodata описан в разделе Запуск без внешнего провайдера идентификации, вход через провайдера OpenID Connect — в разделе Первый вход в консоль управления.
Откройте порт http_listen каждого инстанса для прокси. В конфигурации шага 3 он открыт только на локальном адресе, а в примере ниже прокси обращается к инстансам по сети.

Настройте обратный прокси. Пример для nginx:

upstream s3r_console {
    server node1.example.net:6006;
    server node2.example.net:6006;
    server node3.example.net:6006;
}

server {
    listen 443 ssl;
    server_name console.example.net;
    ssl_certificate     /etc/nginx/console.pem;
    ssl_certificate_key /etc/nginx/console.key;

    location /s3gateway/ {
        proxy_pass http://s3r_console;
        proxy_read_timeout 400s;
    }
}

Задайте адрес эндпоинта S3 для браузера параметром s3r_api.s3_public_url (см. Сервис s3r_api). Консоль загружает и скачивает файлы напрямую через эндпоинт S3 по заранее подписанным ссылкам, поэтому браузеру нужен и этот адрес.

Требования к обратному прокси:

Наружу публикуются только пути /s3gateway/. На том же порту Picodata обслуживает собственный веб-интерфейс и метрики /metrics, которые снаружи не нужны.
Пути передаются без изменений, а заголовки Authorization и Cookie и ответный заголовок Set-Cookie передаются как есть.
Запросы можно распределять по любым инстансам с сервисом s3r_api: API не хранит сеансов, а cookie консоли проверяет любой инстанс.
Консоль публикуется на адресе (схема, узел и порт), отличном от адреса эндпоинта S3, по которому браузер получает объекты. Страница с адреса консоли может обращаться к API от имени вошедшего пользователя.
Таймаут ожидания ответа больше catalog_timeout_s. Изменяющий запрос к API управления выполняется до catalog_timeout_s секунд (по умолчанию 360), а nginx по умолчанию ждёт ответа 60 секунд (proxy_read_timeout). Если прокси оборвёт ожидание раньше, клиент получит ответ 504 от прокси, а запрос продолжит выполняться и может завершиться успешно. Остальные таймауты прокси описаны в разделе Медленные клиенты.

Результат. Консоль открывается по адресу https://console.example.net/s3gateway/console/. Вход проверяется на следующем шаге.

Шаг 10. Проверка работы¶

С рабочего места клиента создайте бакет, запишите объект и прочитайте его обратно через AWS CLI:

aws configure set aws_access_key_id AKIAEXAMPLE000000001
aws configure set aws_secret_access_key ...
aws configure set default.s3.addressing_style path

export AWS_CA_BUNDLE=/etc/s3r/ca.pem
EP=https://node1.example.net:8443
head -c 10485760 /dev/urandom > /tmp/probe
aws --endpoint-url $EP s3 mb s3://smoke-test
aws --endpoint-url $EP s3 cp /tmp/probe s3://smoke-test/probe
aws --endpoint-url $EP s3 cp s3://smoke-test/probe /tmp/probe.back
cmp /tmp/probe /tmp/probe.back && echo ok
aws --endpoint-url $EP s3 rb --force s3://smoke-test

Результат. Команда cmp выводит ok. Объект размером 10 МиБ больше inline_max, поэтому проверка проходит через диски и группы размещения.

Откройте консоль по адресу https://console.example.net/s3gateway/console/ и войдите.

Результат. На странице «Кластер» нет сообщения о незавершённом формировании, а каждый диск исправен.

Установка завершена. Дальнейшая настройка описана в главах Изоляция тенантов, Квоты и ограничение скорости и Возможности консоли управления.