Перейти к основному содержимому

Автоматизированная установка API-gateway

Предусловия​

Перед началом установки убедитесь, что выполнены следующие условия:

  1. Подготовлено окружение.
  2. Дистрибутив CopyWala распакован в соответствии с инструкцией, приведенной в разделе Установка, шаг Распаковка дистрибутива CopyWala.

Последовательность действий​

Выполните шаги в следующем порядке:

  1. Подготовка среды Ansible.
  2. Установка Ansible-коллекций.
  3. Генерация TLS-сертификатов.
  4. Подготовка inventory-файла и переменных ролей.
  5. Запуск установки.

Подготовка среды Ansible​

Рекомендуется запускать установку модуля API-gateway в виртуальной среде Python.

к сведению

Данный шаг выполняется на управляющем узле Ansible (control node) — машине, с которой запускаются Ansible-плейбуки.

Создание виртуальной среды позволяет избежать конфликтов с уже предустановленными пакетами и не затрагивать существующую среду на текущей машине. Для подготовки виртуального окружения выполните следующие шаги:

  1. Создайте виртуальное окружение. Рекомендуется использовать Python 3.9:

    python3 -m venv .pbr

  2. Активируйте виртуальное окружение:

    source .pbr/bin/activate

  3. Установите необходимые пакеты:

    python3.9 -m pip install 'ansible==8.7.0'

  4. Проверьте, что установка Ansible прошла успешно: ansible --version. В результате вывод не должен содержать ошибок. Команда pip list должна вывести зависимости:

        ansible             8.7.0
        ansible-core        2.15.13
к сведению

После завершения установки компонентов виртуальную среду можно отключить. Выполните консольную команду: deactivate.

Установка Ansible-коллекций​

к сведению

Данный шаг выполняется на управляющем узле Ansible (control node) — машине, с которой запускаются Ansible-плейбуки.

Установите или обновите Ansible-коллекции с помощью ansible-galaxy. Необходимые зависимости:

Название Ansible-коллекции

Версия

Установка

sbt-pbr (поставляется в составе дистрибутива продукта CopyWala)

1.0.0

Перейдите в директорию с распакованным дистрибутивом любого компонента CopyWala и запустите команду:

ansible-galaxy collection install package/scripts/Ansible/collections/sbt-pbr-1.0.0.tar.gz

Community.Postgresql (устанавливается из внешнего репозитория Ansible Galaxy)

3.9.1

ansible-galaxy collection install community.postgresql:3.9.1

Community.Library_Inventory_Filtering_V1 (устанавливается из внешнего репозитория Ansible Galaxy)

1.0.2

ansible-galaxy collection install community.library_inventory_filtering_v1:1.0.2

Генерация TLS-сертификатов​

Сгенерируйте TLS-сертификаты, необходимые для работы модуля API-gateway с шифрованием.

Для генерации используйте Ansible-роль certs. Работа с ролью описана в дополнительной документации для автоматизированного варианта установки (с помощью Ansible) в разделе Генерация сертификатов с помощью Ansible-роли certs.

Подготовка inventory-файла и переменных ролей​

  1. Перейдите в директорию со скриптами установки. Например, если дистрибутив был распакован в /path_to_dir/distrib/:

    cd /path_to_dir/distrib/pbr/owned/dbbr/package/scripts/Ansible

  2. Создайте inventory-файл на основе inventory_example.yml и в секции dbbr.hosts укажите IP-адреса узлов, на которые необходимо установить модуль API-gateway.

    Пример inventory-файла

    dbbr:
      hosts:
        dbbr_api:
          ansible_host: "<api_gw_ip_address>"

    Подсказка

    Если API-gateway необходимо установить на несколько хостов, добавьте дополнительные секции в inventory-файл по примеру ниже:

    Пример inventory-файла

    dbbr:
      hosts:
        dbbr_api1:
          ansible_host: "<api_gw_ip_address_1>"

        dbbr_api2:
          ansible_host: "<api_gw_ip_address_2>"
        
        # КОД ПРОПУЩЕН: секции с IP-адресами остальных хостов

  3. Задайте переменные роли api_gateway.

    примечание

    Роль api_gateway поддерживает два режима установки, которые определяются значением переменной api_gateway_rpm_path:

    • api_gateway_rpm_path задан (непустой путь) — устанавливается пакет SynGX из указанного файла. Пакет копируется на целевой узел в директорию /tmp/, после чего выполняется его установка. Путь к пакету SynGX можно задать вручную с помощью переменной api_gateway_rpm_path или определить автоматически с помощью роли common.
    • api_gateway_rpm_path не задан (пустая строка '', значение по умолчанию) — устанавливается стандартный nginx из репозитория.

    Задайте все переменные, у которых в таблице ниже в столбце «Обязательность заполнения» указано Да.

    примечание

    • Если переменная не задана явно в плейбуке, для нее используется значение по умолчанию, определенное в файле defaults/main.yml роли.

    • Из необязательных переменных рекомендуется заполнять секцию *_tls, где * — это префикс с именем модуля. Например, для Storage Manager секция будет выглядеть так:

      storage_manager_tls:
        rootca:
          local_path: /path/to/certs/certificates/rootCA.crt
        cert:
          local_path: /path/to/certs/certificates/storage-manager.crt
        key:
          local_path: /path/to/certs/certificates/storage-manager.key
Переменные Ansible-роли api_gateway

Название переменной

Описание

Значение по умолчанию

Обязательность заполнения

api_gateway_rpm_path

Путь к RPM-файлу установщика Syngx

''

Да или использовать роль common. При использовании роли common задавать эту переменную не требуется

api_gateway_server_name

Адрес, на который направляются запросы для последующей обработки Syngx

localhost

Нет

api_gateway_config_dir

Директория для конфигурационного файла

/opt/syngx/conf

Нет

api_gateway_port

Порт, на котором Syngx будет принимать входящие запросы

29000

Нет

api_gateway_admin_port

Порт, на котором будет доступна служебная информация

29001

Нет

api_gateway_agent_manager_ip

IP-адрес, на котором доступен Agent Manager

10.0.0.1

Нет

api_gateway_agent_manager_port

Порт, на котором доступен API Agent Manager

29010

Нет

api_gateway_agent_manager_ws_port

Порт, на котором доступен WebSocket Agent Manager

29015

Нет

api_gateway_agent_manager_tls

Использование tls-шифрования для подключения к Agent Manager

false

Нет

api_gateway_agent_manager_mtls

Использование взаимной аутентификации с помощью сертификатов для подключения к Agent Manager

false

Нет

api_gateway_storage_manager_ip

IP-адрес, на котором доступен Storage Manager

10.0.0.5

Нет

api_gateway_storage_manager_port

Порт, на котором доступен Storage Manager

29030

Нет

api_gateway_storage_manager_tls

Использование tls-шифрования для подключения к Storage Manager

false

Нет

api_gateway_storage_manager_mtls

Использование взаимной аутентификации с помощью сертификатов для подключения к Storage Manager

false

Нет

api_gateway_task_manager_ip

IP-адрес, на котором доступен Task Manager

10.0.0.3

Нет

api_gateway_task_manager_port

Порт, на котором доступен Task Manager

29020

Нет

api_gateway_task_manager_tls

Использование tls-шифрования для подключения к Task Manager

false

Нет

api_gateway_task_manager_mtls

Использование взаимной аутентификации с помощью сертификатов для подключения к Task Manager

false

Нет

api_gateway_upstream_rootca

Путь к сертификату, с помощью которого производится проверка валидности сертификатов у компонентов Copywala при перенаправлении запросов

''

Нет

api_gateway_downstream_rootca

Путь к сертификату, с помощью которого производится проверка валидности сертификатов у клиентских машин при перенаправлении запросов

''

Нет

api_gateway_tls

Словарь, указывающий пути к сертификатам Syngx. Содержит следующие ключи:<br />cert_file – путь к сертификату;<br />key_file – путь к ключу сертификата

{}

Нет

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

Пример заполнения

dbbr:
  hosts:
    dbbr_api:
      ansible_host: "<api_gw_ip_address>"
      api_gateway_rpm_path: ''

Подсказка

Пример плейбука также приведен в файле pbr/owned/dbbr/package/scripts/Ansible/playbook_example.yml.

Запуск установки​

примечание

Перед запуском убедитесь, что виртуальное окружение .pbr активировано.

  1. Перед запуском установки API-gateway, в install.yml закомментируйте или удалите роли компонентов, которые не требуется устанавливать.

    Пример

    - name: Install API Gateway
      hosts: dbbr
      roles:
    #   - agent_manager
        - api_gateway
    #   - task_manager
    #   - storage_manager

    #- name: Install Recovery Manager
    #  hosts: recovery
    #  roles:
    #   - recovery_manager

  2. Для запуска установки выполните команды:

    cd pbr/owned/dbbr/package/scripts/Ansible
    ansible-playbook -i inventory.yml install.yml
    примечание

    Если на шаге подготовка inventory-файла и переменных ролей переменные были заданы в отдельном файле, укажите его с помощью флага -e, например:

    cd pbr/owned/dbbr/package/scripts/Ansible
    ansible-playbook -i inventory.yml install.yml -e @api-gateway-vars.yml

Проверка результата​

  1. Проверьте статус сервера: $ systemctl status syngx.service.

  2. Положительным результатом проверки будут являться успешные записи в логах с выводом status=0/SUCCESS:

    syngx.service - The SYNGX HTTP and reverse proxy server
       Loaded: loaded (/etc/systemd/system/syngx.service; enabled; vendor preset: disabled)
      Drop-In: /etc/systemd/system/syngx.service.d
               └─service.conf
       Active: active (running) since Mon 2025-06-30 07:21:15 UTC; 5s ago
      Process: 106 ExecStart=/usr/sbin/syngx (code=exited, status=0/SUCCESS)
      Process: 105 ExecStartPre=/bin/bash -c chown syngx.syngx /opt/syngx/conf/syngx.conf.current (code=exited, status=0/SUCCESS)
      Process: 103 ExecStartPre=/bin/bash -c /sbin/syngx -T > /opt/syngx/conf/syngx.conf.current (code=exited, status=0/SUCCESS)
      Process: 99 ExecStartPre=/bin/bash -c VARTIME=`cat /proc/uptime | cut -d . -f 1`; if [ $VARTIME -le 300 ] ; then sleep 2; fi (code=exited, status=0/SUCCESS)
      Process: 98 ExecStartPre=/usr/sbin/syngx -t (code=exited, status=0/SUCCESS)
     Main PID: 107 (syngx)
        Tasks: 5 (limit: 26213)
       Memory: 4.6M
       CGroups: <Позиция syngx в иерархии cgroups>
    Jun 30 07:21:15 syngx2 systemd[1]: Starting The SYNGX HTTP and reverse proxy server...
    Jun 30 07:21:15 syngx2 syngx[98]: syngx: the configuration file /opt/syngx/conf/syngx.conf syntax is ok
    Jun 30 07:21:15 syngx2 syngx[98]: syngx: configuration file /opt/syngx/conf/syngx.conf test is successful
    Jun 30 07:21:15 syngx2 bash[104]: syngx: the configuration file /opt/syngx/conf/syngx.conf syntax is ok
    Jun 30 07:21:15 syngx2 bash[104]: syngx: configuration file /opt/syngx/conf/syngx.conf test is successful
    Jun 30 07:21:15 syngx2 systemd[1]: Started The SYNGX HTTP and reverse proxy server.

Пример запроса для проверки корректной обработки Syngx:

$ curl -I http://<DNS запись узла>:29001/metrics

Положительный ответ:

HTTP/1.1 200 OK
Server: SynGX/3.0.2 (based on nginx-1.24.0)
Date: Tue, 01 Jul 2025 08:26:34 GMT
Content-Type: text/html
Content-Length: 278
Connection: close
к сведению

После завершения установки данного модуля:

  1. При необходимости выполните установку других модулей Platform V CopyWala.
  2. Перейдите к следующему шагу — Настройка интеграции Platform V CopyWala с внешними сервисами.