.. _backup: Бекапирование Витрины данных НСУД ==================================== Состав резервной копии Типового ПО Витрина данных ---------------------------------------------------- Резервному копированию в Типовом ПО Витрина данных подлежат следующие компоненты: - логическая модель Prostore; - физические данные в СУБД; - часть модулей слоя адаптеров, хранящих в Zookeeper данные, подлежащие бекапированию. Модули слоя адаптеров Типового ПО Витрины данных, подлежащие резервному копированию ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. tabularcolumns:: |\Y{0.25}|\Y{0.25}|\Y{0.5}| .. table:: Перечень модулей, подлежащих бекапированию +-------------------------+----------------------------------------------+---------------------------------------------------------+ | **Имя модуля** | **Zookeeper, из которого выполняется бекап** | **Путь хранения Zookeeper, подлежащий бекапированию** | +=========================+==============================================+=========================================================+ | CSV-Uploader | ADS | /adapter/[env]/csv-uploader/config | +-------------------------+----------------------------------------------+---------------------------------------------------------+ | rest-uploader | ADS | /adapter/[env]/rest-uploader/ids | | | | | | | | /adapter/[env]/rest-uploader/conditions | +-------------------------+----------------------------------------------+---------------------------------------------------------+ | smev3-adapter | настройка zookeeper.connect-string | /adapter/[env]/smev3-adapter/[paramstorage.basePath] | | | | | | | | /adapter/[env]/smev3-adapter/[deltastorage.basePath] | +-------------------------+----------------------------------------------+---------------------------------------------------------+ | podd-adapter-replicator | ADS | /adapter/[env]/podd-adapter-replicator/subscription | | | | | | | | /adapter/[env]/podd-adapter-replicator/replication | | | | | | | | /adapter/[env]/podd-adapter-replicator/delta | +-------------------------+----------------------------------------------+---------------------------------------------------------+ | counter-provider | ADS | /adapter/[env]/counter-provider/counters/[counter-name] | +-------------------------+----------------------------------------------+---------------------------------------------------------+ Описание и механизм работы утилиты Backup Manager ----------------------------------------------------- Описание утилиты Backup Manager ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Для реализации механизма резервного копирования Витрины данных и восстановления из резервной копии разработана утилита **Backup manager**, для оркестрации процесса резервного копирования слоя адаптеров и утилиты **DTM-tools**, осуществляющей резервное копирование логической модели базы данных и физических данных СУБД, входящих в инсталляцию. В конфигурации утилиты сохранены: - путь к **DTM-tools** и параметры необходимые для работы утилиты **DTM-tools**: - маска топиков для бекапирования данных СУБД backend.backup.(datamart); - адрес Prostore (с переопределением через команду запуска); - адрес Кафки и имена топиков для: - передачи команд модулям адаптера; - получения статусов модулей адаптера; - бекапирования данных бекенда Витрины; - бекапирования данных модулей адаптеров; - путь к рабочей директории резервного копирования (доступный файловому коннектору) с переопределением через команду запуска; - хранимый объем топика (значение по умолчанию 1Тб); - время хранения топиков бекапа (значение по умолчанию 3 суток). Механизм работы утилиты Backup manager ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Backup Manager** запускается в консольном режиме, принимает команду в качестве аргумента, обеспечивает выполнение 2 операций: - backup - резервное копирование, вторым аргументом указывается целевой архив; - restore - восстановление из резервной копии. В процессе бекапирования или восстановления из бекапа утилита **Backup Manager** отдает в консольный вывод сообщения об основных шагах и выполняемых операциях вида: - отправлена команда остановки обработки запросов; - отправлена команда бекапирования датамарта (datamart). Также транслируется консольный вывод утилиты **DTM-tools**. Создание резервной копии Типового ПО Витрина данных с использованием утилиты **Backup Manager** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Схематическое решение по созданию резервной копии Типового ПО Витрина данных с использованием утилиты **Backup Manager** представлено на рисунке ниже (см :numref:`backup_create`) .. _backup_create: .. figure:: /_static/img/typical/ag/backup_create.png :align: center :alt: Схема создания резервной копии Схема создания резервной копии Типового ПО Витрина данных Механизм работы утилиты Backup manager при выполнении резервного копирования ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Для запуска механизма резервного копирования, администратору системы нужно перейти в директорию backup-tools (утилиты Backup Manager и DTM-Tools должны быть расположены в одной директории) и выполнить в консоли команду ``backup``: .. code-block:: bash java -jar backup-manager-1.10.0-SNAPSHOT.jar backup --dtmTools ./dtm-tools-1.12.0.jar --kafkaBrokers 10.81.7.90:12541 --prostore 10.81.7.90:12520 Процесс резервного копирования состоит из нескольких частей: 1. Подготовка к резервному копированию. 2. Остановка модулей, требующих консистентности с Prostore. 3. Ожидание остановки модулей, требующих консистентности с Prostore. 4. Резервное копирования слоя адаптеров Типового ПО Витрина данных. 5. Резервное копирование логической модели Prostore и физических данных СУБД с использованием утилиты **DTM-tools**. 6. Формирование архива c резервной копией. 7. Запуск остановленных модулей слоя адаптеров. 8. Завершение работы. Восстановление из резервной копии Типового ПО Витрина данных с использованием утилиты **Backup Manager** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Схематическое решение по восстановлению из резервной копии Типового ПО Витрина данных с использованием утилиты **Backup Manager** представлено на рисунке ниже (см :numref:`backup_restore`) .. _backup_restore: .. figure:: /_static/img/typical/ag/backup_restore.png :align: center :alt: Схема восстановления из резервной копии Схема восстановления из резервной копии Типового ПО Витрина данных .. note:: В процессе восстановления данные могут содержаться частично, могут быть не консистентны, поэтому требуется предварительная остановка агента ПОДД вручную перед запуском утилиты **Backup Manager**. После окончания процесса восстановления утилитой **Backup Manager**, работу агента ПОДД следует возобновить. Модуль СМЭВ3 адаптер нужно отключить от сервера (отключить сетевое соединение). После восстановления сетевое подключение к СМЭВ3 следует возобновить. Для запуска механизма восстановления из резервной копии, администратору системы нужно перейти в директорию backup-tools (утилиты Backup Manager и DTM-Tools должны быть расположены в одной директории) и выполнить в консоли команду ``restore``: .. code-block:: bash java -jar backup-manager-1.10.0-SNAPSHOT.jar restore --dtmTools ./dtm-tools-1.12.0.jar --kafkaBrokers 10.81.7.90:12541 --prostore 10.81.7.90:12520 --backupArchive ./backup_YYYY-MM-DD HH:MM:SS.zip Процесс восстановления из резервной копии состоит из нескольких частей: 1. Подготовка к восстановлению из резервной копии. 2. Остановка модулей слоя адаптеров, требующих консистентности с Prostore. 3. Ожидание остановки модулей, требующих консистентности с Prostore. 4. Перенос данных бекапа в топики резервного копирования. 5. Восстановление из резервной копии логической модели Prostore и физических данных СУБД с использованием утилиты **DTM-tools**. 6. Восстановление из резервной копии слоя адаптеров Типового ПО Витрина данных с остановкой модулей, требующих консистентности с Prostore. 7. Ожидание восстановления модулей слоя адаптеров. 8. Запуск остановленных модулей слоя адаптеров. 9. Завершение работы. Реализация бекапирования в слое адаптеров Типового ПО Витрина данных --------------------------------------------------------------------- Работа модулей для обеспечения резервного копирования ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Модули, подлежащие бекапированию, подписываются на топик ``adapter.command`` под одним groupId: ``(имя модуля)_adapter_command`` и создают продюсеров на топики: - adapter.status; - adapter.backup. Все топики размещаются во внутренней кафке ADS. Модули требующие консистентности с Prostore дополнительно подписываются на топик ``adapter.command.broadcast`` под уникальными groupId ``(случайными (имя модуля)_(UUID))``. Обработка команды не зависит от топика, через который она получена. Сообщения в топиках команд ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. tabularcolumns:: |\Y{0.3}|\Y{0.35}|\Y{0.2}|\Y{0.15}| .. table:: Сообщения в топиках команд +-----------------------------------------------+---------------------------+---------------+--------------+ | **Назначение команды** | **Топик** | **Ключ** | **Значение** | +===============================================+===========================+===============+==============+ | Приостановка обработки запросов для модулей, | adapter.command.broadcast | backup.pause | null | | которым требуется консистентность с Prostore | | | | +-----------------------------------------------+---------------------------+---------------+--------------+ | Возобновление обработки запросов для модулей, | adapter.command.broadcast | backup.resume | null | | которым требуется консистентность с Prostore | | | | +-----------------------------------------------+---------------------------+---------------+--------------+ | Запрос персистированых данных из Zookeeper | adapter.command | backup.get | backupId | | для резервной копии | | | | +-----------------------------------------------+---------------------------+---------------+--------------+ | Применение данных резервной копии и запись | adapter.command | backup.set | null | | персистированных данных в Zookeeper | | | | +-----------------------------------------------+---------------------------+---------------+--------------+ Статусы модулей ^^^^^^^^^^^^^^^^ Статусы модулей возвращаются через компактный топик ``adapter.status`` Формат сообщения статуса: ключ в формате json (идентификатор вертикла и ключ шаблона присутствуют только для smev3-adapter): .. code-block:: json { "group": "dev.nsud", "name": "smev3-adapter", "version": "4.0.13", "instance": "6f58378a-2205-42c9-80fc-c028ab12a3ba", "backupId": "2228378a-2205-42c9-80fc-c028ab12a222" } значение в формате json: .. code-block:: json { "timestamp": "2023-02-17T12:10:45Z", "status": "started" } Значения статусов ################## .. table:: +-----------------+----------------------------------------------+ | **Статус** | **Описание** | +=================+==============================================+ | started | работает | +-----------------+----------------------------------------------+ | stopping | приостановка модуля для бекапирования | +-----------------+----------------------------------------------+ | stopped | модуль приостановлен для бекапирования | +-----------------+----------------------------------------------+ | restoring | модуль восстановлен из резервной копии | +-----------------+----------------------------------------------+ | restored | модуль восстановлен из резервной копии | +-----------------+----------------------------------------------+ | error_restoring | ошибка восстановления из резервной копии | +-----------------+----------------------------------------------+ | error_stopping | ошибка приостановки модуля для бекапирования | +-----------------+----------------------------------------------+ Механизм приостановки модулей, требующих консистентности с Prostore -------------------------------------------------------------------- Обеспечение консистентности с Prostore реализовано для каждого экземпляра следующих модулей: - smev3-adapter; - podd-adapter-replicator. Все экземпляры модулей, требующих консистентности с Prostore подписаны на топик ``adapter.command.broadcast`` с уникальной groupId консьюмера: (имя модуля)_(UUID)) groupId. Приостановка модулей, требующих консистентности с Prostore ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. Каждый экземпляр модуля считывает команду ``backup.pause`` из топика ``adapter.command.broadcast`` и отправляет статус ``stopping`` в топик ``adapter.status``. 2. В каждом экземпляре модуля выполняется процесс приостановки процессов, влияющих на консистентные с Prostore данные. 3. После остановки всех процессов, каждый экземпляр модуля отправляет статус ``stopped`` в топик ``adapter.status``. Восстановление модулей, требующих консистентности с Prostore ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. Каждый экземпляр модуля считывает команду backup.resume из топика ``adapter.command.broadcast``. 2. В каждом экземпляре модуля выполняется повторный запуск процессов, влияющих на консистентные с Prostore данные. 3. После остановки всех процессов, каждый экземпляр модуля отправляет статус started в топик ``adapter.status``. Механизм резервного копирования и восстановления из резервной копии в модулях слоя адаптеров --------------------------------------------------------------------------------------------- Модули, данные которых необходимы для резервного копирования: - csv-uploader; - rest-uploader; - smev3-adapter; - podd-adapter-replicator v1; - counter-provider. Резервное копирование выполняет только один из экземпляров каждого типа модулей, который успел считать сообщение из топика ``adapter.command``. Механизм резервного копирования модулей слоя адаптеров ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ При выполнении резервного копирования все модули, участвующие в бекапировании: 1. Подписаны на топик ``adapter.command`` с общей ``qroupId`` для каждого типа модулей. 2. Один из экземпляров модуля считывает сообщение`` backup.get`` из топика ``adapter.command``. 3. Считывает метаданные, подлежащие бекапированию по пути в Zookeeper, в соответствии с путями хранения в сервисной БД. 4. Возвращает данные через топик ``adapter.backup`` в виде json. В ключе сообщения формируются стандартные данные о версии и сборке: .. code-block:: json { "group": "ru.itone.dtm.data.uploader" "name": "data-uploader", "version": "1.1.0-SNAPSHOT", "instance": "6f58378a-2205-42c9-80fc-c028ab12a3ba", "backupId": "2228378a-2205-42c9-80fc-c028ab12a222", "gitCommit": "a7c7770404ef61f62496983b783ef7b442989d74", "dateCommit": "2023-02-17T12:10:45Z", "branchCommit": "develop", "buildDate": "2023-02-17T12:11:36.627Z", "buildUnixTime": "1676635896" } В значении сообщения размещаются перситируемые данные, пример для модуля counter-provider. .. code-block:: json { "path":"/dev/counter-provider", "value":"test_data", "children":[ { "path":"/dev/counter-provider/child2", "value":"", "children":[] }, { "path":"/dev/counter-provider/child1", "value":"child1_data", "children":[] } ] } Механизм восстановления из резервной копии модулей слоя адаптеров ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ При выполнении резервного копирования все модули, участвующие в восстановлении из резервной копии: 1. Подписаны на топик ``adapter.command`` с общей qroupId для каждого типа модулей. 2. Один из экземпляров модуля считывает сообщение ``backup.set`` из топика ``adapter.command``. 3. Отправляют статус ``restoring`` в топик ``adapter.status``. 4. Удаляют данные по пути хранения метаданных в соответствии с путями хранения в сервисной БД. 5. Разбирают сообщения в топике ``adapter.backup``: сначала фильтруют данные, относящиеся к модулю. 6. Записывают данные в сервисную БД. 7. Отправляют статус ``restored`` в топик ``adapter.status``. Поведение в случае ошибок при выполнении резервного копирования --------------------------------------------------------------- При возникновении ошибок в процессе резервного копирования, утилита **Backup Manager** выполняет компенсирующие действия и завершает выполняемый процесс. В случае, если ошибки возникли в процессе восстановления из резервной копии, стоит обратить внимание на тот факт, что в этом случае Типовое ПО Витрина данных будет находится в не консистентном состоянии, требуется оперативный разбор ошибок и повторное восстановление из резервной копии. Ошибки резервного копирования и восстановления из резервной копии ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Ошибки, возможные в процессе резервного копирования/восстановления из резервной копии, и пути их устранения приведены ниже (см. :numref:`backup_error`) .. _backup_error: .. .. tabularcolumns:: |\Y{0.2}|\Y{0.2}|\Y{0.3}|\Y{0.3}| .. table:: Ошибки резервного копирования и восстановления из резервной копии :widths: auto +------------------------------+---------------------------------------------------+------------------------------------------------------------+-----------------------------------+ | **Ошибка** | **Описание ошибки** | **Действия утилиты Backup Manager** | **Устранение ошибки** | +==============================+===================================================+============================================================+===================================+ | "Observed active | Не удален файл ``backup.lock`` | - завершает процесс бекапирования/ восстановления | Может возникать при прерванной | | backupManager process, | | с выводом ошибки "Observed active backupManager process, | работе утилиты, требуется | | file backup.lock exists" | | file backup.lock exists" | ручное удаление файла | | | | | | | | | - выводит финальный статус: ``BACKUP/RESTORE is failed`` | | +------------------------------+---------------------------------------------------+------------------------------------------------------------+-----------------------------------+ | "Error stopping (module) | Ошибка приостановки одного из инстансов модулей, | - отправляет команду ``backup.resume`` на восстановление | Требуется анализ логов модуля, | | (instanse) (verticle) (key), | требующих консистентности с Prostore | работы модулей в топик ``adapter.command.broadcast`` без | в котором возникла ошибка, после | | see modul log for detail" | | ожидания статусов о восстановлении | ее устранения, повтор процесса | | | | | бекапирования/восстановления | | | | - завершает процесс бекапирования/ восстановления с | | | | | выводом ошибки "error stopping (module) (instanse) | | | | | (verticle) (key), see modul log for detail" | | | | | | | | | | - выводит финальный статус: ``BACKUP/RESTORE is failed`` | | +------------------------------+---------------------------------------------------+------------------------------------------------------------+-----------------------------------+ | "timeout stopping (module) | Таймаут приостановки одного из инстансов модулей, | - отправляет команду backup.resume на восстановление | Требуется анализ логов модуля, в | | (instanse) (verticle) (key), | требующих консистентности с Prostore | работы модулей в топик ``adapter.command.broadcast`` без | котором возникла ошибка, после ее | | see modul log for detail" | | ожидания статусов о восстановлении | устранения, повтор процесса | | | | | бекапирования/восстановления | | | | - завершает процесс бекапирования/ восстановления с | | | | | выводом ошибки: "timeout stopping (module) (instanse) | | | | | (verticle) (key), see modul log for detail" | | | | | | | | | | - выводит финальный статус: ``BACKUP/RESTORE is failed`` | | +------------------------------+---------------------------------------------------+------------------------------------------------------------+-----------------------------------+ | "timeout starting (module) | Таймаут восстановления работоспособности одного | - завершает процесс бекапирования/ восстановления | Требуется анализ логов модуля, в | | (instanse), see modul log | из инстансов модулей, требующих консистентности | завершается с выводом ошибки : "timeout starting | котором возникла ошибка, после ее | | for detail" | с Prostore | (module) (instanse), see modul log for detail" | устранения, повтор процесса | | | | | бекапирования/восстановления | | | | - завершает процесс восстановления с выводом ошибки: | | | | | "error restoring (module) (instanse), see modul log | | | | | for detail" | | | | | | | | | | - выводит финальный статус: ``RESTORE is failed`` | | +------------------------------+---------------------------------------------------+------------------------------------------------------------+-----------------------------------+ | "timeout restoring (module) | Таймаут восстановления из резервной копии модуля | - отправляет команду ``backup.resume`` на восстановление | Требуется анализ логов модуля, в | | (instanse), see modul log | слоя адаптеров | работы модулей в топик ``adapter.command.broadcast`` без | котором возникла ошибка, после ее | | for detail" | | ожидания статусов о восстановлении | устранения, повтор процесса | | | | | бекапирования/восстановления | | | | - завершает процесс восстановления с выводом ошибки: | | | | | "timeout restoring (module) (instanse), see modul log | | | | | for detail" | | | | | | | | | | - выводит финальный статус: ``RESTORE is failed`` | | +------------------------------+---------------------------------------------------+------------------------------------------------------------+-----------------------------------+ | Ошибки утилиты DTM-tools при | Ошибки не формализованы | В случае не успеха процесса бекапирования утилиты | Требуется анализ логов модуля, в | | создании резервной копии | | DTM-tools: | котором возникла ошибка, после ее | | | | | устранения, повтор процесса | | | | - отправляет команду ``backup.resume`` на восстановление | бекапирования/восстановления | | | | работы модулей в топик ``adapter.command.broadcast`` | | | | | без ожидания статусов о восстановлении | | | | | | | | | | - завершает процесс бекапирования с выводом ошибки, | | | | | переданной DTM-tools | | | | | | | | | | - выводит финальный статус: ``BACKUP is failed`` | | +------------------------------+---------------------------------------------------+------------------------------------------------------------+-----------------------------------+ | Ошибки утилиты DTM-tools при | Ошибки не формализованы | В случае не успеха процесса бекапирования утилиты | Требуется анализ логов модуля, в | | восстановлении из резервной | | DTM-tools: | котором возникла ошибка, после ее | | копии | | | устранения, повтор процесса | | | | - отправляет команду ``backup.resume`` на восстановление | бекапирования/восстановления | | | | работы модулей в топик ``adapter.command.broadcast`` | | | | | без ожидания статусов о восстановлении | | | | | | | | | | - завершает процесс восстановления из бекапа | | | | | с выводом ошибки, переданной DTM-tools | | | | | | | | | | - выводит финальный статус: ``RESTORE is failed`` | | +------------------------------+---------------------------------------------------+------------------------------------------------------------+-----------------------------------+ Поведение в случае остановки утилиты **Backup Manager** в процессе снятия/восстановления из резервной копии ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ В случае экстренного прекращения работы утилиты командой ``kill`` возможно как не консистентное состояние витрины (при восстановлении из резервной копии), так как и ее частичная неработоспособность, так как утилита **Backup Manager** в этом случае не успеет выполнить компенсирующие действия и восстановить работу остановленных модулей. Рекомендуется в случае экстренного прекращения работы утилиты перезапустить поды модулей podd-adapter-replicator и smev3-adapter. Ограничения ~~~~~~~~~~~~~ 1. При выполнении DDL операций бэкап завершается ошибкой. 2. Для корректного выполнения функции бекапирования для каждого слоя адаптеров должен быть развернут свой экземпляр Kafka. .. _back_up_kafka: .. figure:: /_static/img/typical/ag/back_up_kafka.png :align: center :alt: Схема развертывания экземпляра Kafka Схема развертывания экземпляра Kafka