Настройка программной синхронизации Avanpost FAM

[ Общие сведения ] [ Инициализация механизма синхронизации ] [ Подключение удалённого узла к текущему узлу ] [ Обновление кластера ] [ Приложение А. Пример заполненного конфигурационного файла в рамках кластера ]

Общие сведения

Поддерживаемые версии

Данная функциональность доступна в Avanpost FAM, начиная с версии 1.12.

Функциональность программной синхронизации предназначена для синхронизации между узлами следующих сведений:

  • Основных атрибутов профиля пользователя;
  • Дополнительных атрибутов профиля пользователя;
  • Аутентификаторов.

Данная функциональность функционирует в режиме pull («вытягивания»): узел, которому требуется получить информацию с других узлов, подключается к узлам, с которых необходимо выполнить синхронизацию. 

Если требуется настройка двунаправленной синхронизации, то пункты указанной инструкции выполняются на двух узлах.

Описание работы механизма программной синхронизации приведено на странице описания масштабирования и кластеризации.

FAM Server поддерживает произвольные (кастомные) схем, т. е. администратор может разместить все таблицы FAM в одной или нескольких собственных схемах, а не только в public (для основных таблиц: пользователи, группы и т.д.) и sync (для таблиц репликации). Кастомные схемы устанавливаются через параметр search_path основного конфигурационного файла. При этом для репликатора поддерживаются только стандартные схемы. 

Инициализация механизма синхронизации

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

Для этого необходимо выполнить следующие действия:

  1. Если версия FAM ниже 1.16, требуется установить последние миграции, т.е. выполнить migratedb (по умолчанию - логин "avanpost", база данных - "idp"):
    ./fam_linux_amd64 -migratedb postgres

    Проводить миграции вручную требуется только для FAM версии ниже 1.16. Для версий 1.16 и выше миграции выполняются автоматически при каждом запуске Avanpost FAM.

  2. Найти и отредактировать конфиг-файл базы данных postgresql.conf (ориентировочный путь размещения данного файла - /etc/postgresql/14/main/postgresql.conf, но может отличаться в зависимости от версии PostgreSQL и ОС Linux), раскомментировав, либо добавив параметры (значение параметра max_wal_replication_slots должно быть больше значения max_wal_senders):
    wal_level = logical
max_wal_senders = 10
max_wal_replication_slots = 20
  3. Перезапустить кластер СУБД PostgreSQL:
    sudo systemctl restart postgresql
  4. В PostgreSQL с помощью учетной записи суперпользователя или любой другой с соответствующими правами (например "postgres") подключиться к базе данных "idp" и выполнить:
    --
CREATE extension IF NOT exists hstore ;
  5. Для автоматического старта службы idp следует создать соответствующий сервис (если он не был создан ранее):
    1. Создать сервис idp посредством комады:
      sudo vi /etc/systemd/system/idp.service

    2. Настроить конфигурационный файл службы idp согласно примеру

      [Unit]
Description=IDP

[Service]
WorkingDirectory=/opt/idp
ExecStart=/opt/idp/fam_linux_amd64
Restart=always
RestartSec=10
SyslogIdentifier=idp
User=idp
Environment="SSO_CFG=/opt/idp/config.toml"
Environment="http_proxy=127.0.0.1:9090"
Environment="https_proxy=127.0.0.1:9090"
Environment="SSO_API_SERVICE_WITH_NO_PROXY=0"
Environment="SSO_PUSH_SERVICE_WITH_NO_PROXY=0"
TimeoutStopSec=5

[Install]
WantedBy=multi-user.target
      ПараметрЗначение
      [Unit]
      DescriptionОписание сервиса для отображения администратору.
      [Service]
      WorkingDirectory Рабочая директория, в которой запускается процесс.
      ExecStartКоманда для запуска сервиса, в которой указывается расположение исполняемого файла Avanpost FAM Server.
      RestartПараметр настройки автоматического перезапуска сервиса.
      RestartSecВремя ожидания (в секундах) перед перезапуском сервиса после его остановки.
      SyslogIdentifierИмя, под которым логи сервиса записываются в системный журнал.
      UserИмя пользователя, от имени которого запускается процесс
      Environment

      Переменные окружения:

      • SSO_CFG - используется для определения местоположения конфигурационного файла FAM Server;
      • http_proxy - Адрес прокси-сервера для нешифрованного трафика;
      • https_proxy - Адрес прокси-сервера для шифрованного трафика;
      • SSO_API_SERVICE_WITH_NO_PROXY - Выключение обхода прокси-сервера для внутренних API-запросов (1 - функция no_proxy включена; 0 - функция no_proxy выключена и все запросы выполняются через прокси);
      • SSO_PUSH_SERVICE_WITH_NO_PROXY - Выключение обхода прокси-сервера для PUSH-запросов (1 - функция no_proxy включена; 0 - функция no_proxy выключена и все запросы выполняются через прокси).
      TimeoutStopSec

       Время ожидания (в секундах), в течение которого systemd ждёт завершения процесса idp после отправки сигнала завершения.

      [Install]
      WantedByПараметр, указывающий, когда должен быть запущен сервис (по умолчанию multi-user.target – сервис будет запускаться автоматически при загрузке системы).
  6. В PostgreSQL с помощью учетной записи суперпользователя или любой другой с соответствующими правами (например "postgres") подключиться к базе данных "idp" и создать пользователя репликации с паролем (в текущем примере создается пользователь "repladm" с паролем "repladm"): 
    --
 CREATE USER repladm WITH PASSWORD 'repladm' REPLICATION LOGIN ;
  7. Затем выполнить команды:

    В качестве параметра <sync_schema> требуется ввести наименование схемы синхронизации. Если не настроена (или не планируется к использованию) кастомная схема, следует использовать наименование стандартной схемы синхронизации sync. В качестве параметра <main_schema> требуется ввести наименование схемы для основных таблиц (группы, пользователи, приложения и т.п.). Если не настроена (или не планируется к использованию) кастомная схема, следует использовать наименование стандартной основной схемы public. Кастомные схемы устанавливаются через параметр search_path основного конфигурационного файла.



    --
ALTER ROLE repladm SET session_replication_role = 'replica' ;
--
GRANT ALL ON SCHEMA <sync_schema> TO repladm ; 
--
GRANT ALL ON ALL TABLES IN SCHEMA <sync_schema> TO repladm ;
--
GRANT ALL ON SCHEMA <main_schema> TO repladm ; 
--
GRANT ALL ON ALL TABLES IN SCHEMA <main_schema> TO repladm ;    
--
DROP PUBLICATION IF EXISTS changes_pub ;
--
CREATE PUBLICATION changes_pub FOR TABLE sync.changes WITH (publish = 'insert') ;
--
ALTER PUBLICATION changes_pub OWNER to repladm ;
  8. Настроить параметры текущего узла синхронизации в конфигурационном файле replicator/conf.json (пример конфигурационного файла репликатора приведен в приложении А):
    ПараметрЗначение
    memberIDВвести свой UUID (например "33645877-70c1-45b1-b140-ab4028f1a401"): требуется уникальный UUID, сгенерированный любым удобным инструментом (например, https://www.uuidgenerator.net/version4). Должен быть разным для каждого узла в кластере.
    memberNameНазвание текущей ноды (например "node1").
    tokenТокен для подключения к текущей ноде (например, "token123456"): требуется секретный токен, который можно сгенерировать любым удобным инструментом (например, https://it-tools.tech/token-generator).
    address

    Адрес gRPC-интерфейса текущей ноды (например, 0.0.0.0:19090).

    Порт не должен совпадать с значением в параметре grpcServer конфигурационного файла config.toml компонента Avanpost FAM Server (допускается использовать любой другой свободный порт).

    postgresConnectionСтрока подключения к БД PostgresSQL с указанием ранее созданного пользователя с правами репликации (например, "postgres://repladm:repladm@192.168.0.83:5432/idp")
    postgresVersionBelow14Указывает, что версия PostgreSQL ниже 14. Если значение параметра true, используются совместимые настройки WAL.
    retrieveIntervalInSecondsИнтервал (в секундах) между pull-запросами изменений с удалённых узлов.
    retrieveLimits

    Максимальное количество изменений (в одной таблице), передаваемых за один запрос (лимит изменений записей по каждой таблице для случаев, когда нода предоставляет diff-списки и notExist-списки). При большем количестве изменения дробятся.

    Например, было 1200 изменений (update) существующих пользователей (в таблице "users") и было добавлено 1899 пользователей (в таблице "users"). При первом запросе в diff-список будет содержать 1000 изменений, notExist-список - 1000. При втором запросе diff-список будет содержать 200 изменений, notExist-список - 899.

    coordinatorУказывает, является ли узел координатором. В мультимастерной конфигурации может быть несколько узлов со значением параметра false
    metaTablesUnlogged

    Включение/выключение ведения таблиц метаинформации в журнале WAL (по умолчанию false). Использование журнала WAL повышает производительность, но может снижать надёжность.

    kvDataDirPath

    Путь к встроенному хранилищу key-value, где будет содержаться часть метаинформации, необходимой для репликации данных (по умолчанию /kv_data/).

    При запуске Avanpost FAM Server пользователю, от имени которого запускается репликатор, следует предоставить доступ на запись и чтение файлов из папки, где расположено хранилище key-value:

    1. Ввести команды изменения прав доступа:
      chmod 750 kv_data
chmod u+rw kv_data
    2. Изменить владельца папки (при необходимости) при помощи команды (в качестве значения /path_to_kv_data указать путь к папке /kv_data/):
      sudo chown -R idp:idp /path_to_kv_data

    tls – секция настроек TLS-шифрования для gRPC-интерфейса репликатора

    enabledВключение TLS-шифрования  для входящих gRPC-соединений.
    certPathПуть к файлу сертификата сервера в формате PEM.
    keyPathПуть к приватному ключу сервера в формате PEM.
    kvUpdateTimoutInSecondsТаймаут (в секундах) на обновление данных в key-value хранилище.
    cluster - секция настроек конфигурации кластера
    syncFrom

    Массив узлов, с которых текущий узел будет получать изменения. Для каждого элемента настраиваются следующие параметры:

    • memberID – UUID узла;
    • memberName – название узла;
    • address – адрес gRPC-интерфейса узла;
    • token – токен для подключения к узлу.
    tls

    Настройки TLS-шифрования для исходящих подключений. Содержит следующие параметры для каждого узла:

    • enabled – включение TLS для исходящего подключения к удалённому узлу;
    • skipVerify – настройка проверки сертификата удаленного узла (если true, сертификат не проверяется: не рекомендуется);
    • useSystemRootCA –  настройка использования системных корневых сертификатов (true - используются сетевые сертификаты, false— только сертификат, указанный в certPath);
    • certPath – путь к файлу CA-сертификата удалённого узла (PEM). 
    allMembersМассив UUID всех узлов в кластере. Необходимо ввести для корректной работы механизма синхронизации.
  9. Запустить службы idp и replicator посредством команды (запуск выполняется сперва на мастер-узле, затем на каждом слейв-узле):
    sudo systemctl start idp
sudo systemctl start replicator

Инициализация механизма программной синхронизации на узле будет успешно выполнена, но запуск механизма выполняется по мере добавления других узлов.

Подключение удалённого узла к текущему узлу

Для подключения текущего узла к удалённым узлам необходимо настроить секции syncFrom и allMembers раздела cluster в конфигурационном файле replicator/conf.json. Для это отредактировать конфигурационный файл replicator/conf.json

  1. В секции "cluser" -> "syncFrom" указать другие параметры подключения к другим узлам синхронизации, с которых мы хотим получать обновления, например:
    "syncFrom": [
        {
            "memberID": "303429e3-5c5c-4169-8dc0-6b042824ac7c",
            "memberName": "node2",
            "address": "localhost:9797",
            "token": "token123456"
        },
        {
            "memberID": "2cf88875-ea5c-4507-928b-acaf44e05628",
            "memberName": "node3",
            "address": "localhost:9898",
            "token": "token123456"
        }
]
  2. Заполнить остальные параметры конфига: "cluser" -> "allMembers": перечислить массивом все uuid всех нод кластера:
  3. Выполнить команду ./replicator -reinit -c /path/to/conf.json
    для инициализации метахранилища. может занять определенное время в зависимости от количества записей в базе (в среднем до нескольких минут).
    (чтобы команда отработала корректно в папке с replicator должны лежать файлы "tables.toml" и "views-sql.toml")
  4. Запустить ./replicator -c /path/to/conf.json
    можно запускать с флагом (--debug для отладки)
  5. На других нодах проделать всё тоже самое, только в "syncFrom" указать остальные ноды синхронизации. 

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

Обновление кластера

Для обновления механизмов синхронизации (при переходе с FAM Server версии 1.14.13 и ниже на версию 1.15+) требуется выполнить следующие действия:

  1. Перед началом обновления совершить следующие действия:
    1. Выполнить резервное копирование базы данных на всех узлах и заархивировать конфигурационные файлы.
    2. Убедитесь, что все изменения на всех узлах реплицированы и отсутствуют задержки синхронизации.
    3. Проверить статус репликатора на всех узлах:
      systemctl status replicator
  2. На каждом из узлов остановить службы idp и репликатор, используя команду:
    sudo systemctl stop idp
sudo systemctl stop replicator
  3. На мастер-узле (в случае мультимастерной конфигурации мастер-узел определяется вручную) выполнить обновление Avanpost FAM Server согласно инструкции.
  4. Выполнить миграцию, используя команду:
    cd /opt/idp
./fam_linux_amd64 -migratedb postgres

    В процессе миграции будут автоматически сформированы таблицы authentication_methods (таблица с методами аутентификации) и authenticators (таблица с привязками аутентификаторов к пользователям). После завершения миграции FAM (службу Idp) не запускать.

  5. Подключитесь к БД idp от имени суперпользователя или пользователя idp:
    sudo -u postgres psql idp
  6. Выполнить следующие команды (в качестве <sync_schema> использовать наименование схемы синхронизации, в качестве <sync_schema> – наименование основной схемы):
    GRANT ALL ON SCHEMA <sync_schema> TO repladm;
GRANT ALL ON ALL TABLES IN SCHEMA <sync_schema> TO repladm;
GRANT ALL ON SCHEMA <main_schema> TO repladm;
GRANT ALL ON ALL TABLES IN SCHEMA <main_schema> TO repladm;
  7. Выйти из PostgreSQL:
    \q
  8. Обновить компонент репликатора: замените файлы: tables.toml, views-sql.toml и replicator. Убедиться, в tables.toml и views-sql.toml добавлены "authentication_methods" и "authenticators".
  9. Выполнить реинициализацию репликатора:
    ./replicator -reinit

    Не стоит запускать службу replicator и idp на мастер-узле до завершения обновления всех слейв-узлов.

  10. Обновить все ведомые узлы:
    1. Обновить FAM Server и применить миграции по аналогии с мастер-узлом.
    2. Во избежание дублирования данных при последующей синхронизации следует очистить таблицу "authenticators":
      psql -U avanpost -d idp -c "TRUNCATE public.authenticators;"
    3. Повторить шаги, описанные в пунктах 5 - 9 данной инструкции, для оставшихся слейв-узлов. 
  11. После завершения обновления запустить службы на узлах (сперва запускаются службы на мастер-узле, затем на каждом слейв-узле):
    sudo systemctl start replicator
sudo systemctl start idp
  12. Убедиться в корректности обновления:
    1. Проверить статус служб:
      systemctl status idp replicator
    2. Убедиться, что таблице authentication_methods имеются записи:
      SELECT * FROM authentication_methods;
    3. Убедиться, что таблица authenticators заполняется при привязывании аутентификаторов.
    4. Убедиться, что методы аутентификации в административной консоли отображаются корректно, а аутентификация пользователей проходит согласно настроенному сценарию.

Приложение А. Пример заполненного конфигурационного файла в рамках кластера

Пример заполненного файла конфигурации replicator/conf.json:

{
    "memberID": "33645877-70c1-45b1-b140-ab4028f1a401",
    "memberName": "node1",
    "token" : "token123456",
    "address": "0.0.0.0:9696",
     "tls": {
        "enabled": false,
        "certPath": "",
        "keyPath": ""
    },
    "postgresConnection": "postgres://repladm:repladm@192.168.0.101:5432/idp",
    "retrieveIntervalInSeconds": 15,
    "retrieveLimits": 1000,
    "coordinator": false,
    "metaTablesUnlogged": false,
    "kvDataDirPath": "kv_data",
    "cluster": {
        "syncFrom": [
            {
                "memberID": "303429e3-5c5c-4169-8dc0-6b042824ac7c",
                "memberName": "node2",
                "address": "localhost:9797",
                "token": "token123456",
                "tls": {
                    "enabled": false,
	                "skipVerify": false,
	                "useSystemRootCA": false,
	                "certPath": ""
                }
            },
            {
                "memberID": "2cf88875-ea5c-4507-928b-acaf44e05628",
                "memberName": "node3",
                "address": "localhost:9898",
                "token": "token123456",
                "tls": {
                    "enabled": false,
	                "skipVerify": false,
	                "useSystemRootCA": false,
	                "certPath": ""
                }
            }
        ],
        "allMembers": [
                        "33645877-70c1-45b1-b140-ab4028f1a401",
                        "303429e3-5c5c-4169-8dc0-6b042824ac7c",
                        "2cf88875-ea5c-4507-928b-acaf44e05628"
        ]
    }
}


Обсуждение