Установка Консоли управления с помощью инсталлятора¶

В инструкции описана установка Консоли управления «ПроAPI Защита» на выделенные серверы с помощью инсталлятора. Инсталлятор разворачивает на серверах кластер Kubernetes, Консоль управления и её базы данных и при необходимости настраивает отказоустойчивость.

Инструкция относится к версии «ПроAPI Защита» 3.0.0. Установка выполняется из дистрибутива этой версии (Дистрибутив); доступ к интернет серверам и рабочему месту администратора не нужен.

Фильтрующие ноды устанавливаются тем же инсталлятором по инструкции Установка фильтрующей ноды с помощью инсталлятора.
Для пилотного проекта фильтрующую ноду допускается установить на сервер Консоли управления профиля standalone (Фильтрующая нода на сервере Консоли управления).

Компоненты¶

• Консоль управления – веб-интерфейс и API для управления фильтрующими нодами, политиками безопасности и мониторинга. Хранит данные в PostgreSQL и ClickHouse.
• Фильтрующая нода – компонент, который проверяет трафик защищаемых приложений по спецификации OpenAPI. Подключается к Консоли управления по HTTPS.
• Инсталлятор (installer) – программа, которая устанавливает, обновляет, проверяет и удаляет Консоль управления. Запускается на рабочем месте администратора и подключается к серверам по SSH.
• Серверы Консоли управления – серверы, на которые устанавливается Консоль управления. На них работает кластер Kubernetes (дистрибутив k0s).

       Пользователи (браузер)               Фильтрующие ноды
                 │  HTTPS 443                     │  HTTPS 443
                 ▼                                ▼
┌── Адрес Консоли управления (VIP Консоли или балансировщик) ──┐
│                                                              │
│      Сервер 1            Сервер 2            Сервер 3        │
│    Консоль + БД        Консоль + БД        Консоль + БД      │
│                                                              │
└──────────────────── VIP Kubernetes API ──────────────────────────┘
                              ▲
                              │  SSH 22, TCP 6443
               Рабочее место администратора
                         (installer)

Варианты установки¶

Количество серверов¶

Отказоустойчивому профилю нужно не меньше трёх серверов: кластер и базы данных сохраняют работоспособность, пока доступно большинство серверов (2 из 3).

Публикация Консоли управления (профиль ha)¶

Дистрибутив¶

Дистрибутив «ПроAPI Защита» 3.0.0 передаётся по ссылке с паролем. Ссылку и пароль предоставляет менеджер WMX. По ссылке открывается папка 3.0.0 с файлами:

• Бандл – файл со всеми программами и образами контейнеров, которые нужны для установки. Инсталлятор устанавливает компоненты из бандла, поэтому доступ в интернет не нужен.
• Для Консоли управления нужен один бандл –того профиля, который выбран для установки (Количество серверов). Бандл профиля standalone не подходит для профиля ha, и наоборот.
• Бандл ноды нужен, только если фильтрующие ноды устанавливаются этим инсталлятором (Установка фильтрующей ноды с помощью инсталлятора).
• Инсталлятор и бандлы используются только из одного дистрибутива.

Требования¶

Серверы Консоли управления¶

Сетевые адреса¶

• IP-адрес или DNS-имя каждого сервера для подключения по SSH.
• Для профиля ha, если у серверов несколько сетей: адрес каждого сервера во внутренней сети, через которую серверы связываются между собой.
• Для профиля ha: свободный IP-адрес для VIP Kubernetes API в подсети серверов, вне диапазона DHCP, и маска подсети, например /24.
• Для профиля ha со способом публикации VIP: свободный IP-адрес для VIP Консоли управления в той же подсети, вне диапазона DHCP.
• DNS-имя Консоли управления, например proapi.example.ru. Запись типа A указывает:
  • для standalone – на IP-адрес сервера;
  • для ha со способом VIP – на VIP Консоли управления;
  • для ha со способом external – на адрес балансировщика.

Сертификат¶

Выберите один из вариантов (подробнее – в разделе TLS-сертификат Консоли управления):

• Самоподписанный (по умолчанию). Подготовка не требуется: инсталлятор создаёт собственный центр сертификации (CA) и выпускает сертификат для DNS-имени Консоли управления. Файл CA передаётся на фильтрующие ноды.
• Собственный сертификат от вашего или публичного центра сертификации: файл сертификата с цепочкой (fullchain.pem) и файл закрытого ключа без пароля (privkey.pem), выданные на DNS-имя Консоли управления.
• Let's Encrypt – публичный сертификат, который программа certbot на одном из серверов получает и продлевает автоматически. Требуются публичное DNS-имя и доступ к Консоли управления из интернета по TCP 80 и 443. Вариант недоступен, если Консоль управления перенесена с порта 80 параметром ingress.httpPort.
• Без TLS – только если перед Консолью управления стоит прокси-сервер или балансировщик, который сам завершает TLS.

Учётные данные и файлы¶

• Ссылка на дистрибутив «ПроAPI Защита» 3.0.0 и пароль к ней (см. Дистрибутив).
• Лицензионный ключ «ПроAPI Защита».
• Email для учётной записи первого администратора Консоли управления; пароль создаёт инсталлятор (см. Первый администратор и пароли).

Рабочее место администратора¶

• Linux x86-64 с клиентом OpenSSH (команды ssh, ssh-keygen).
• Свободное место: не меньше 5 ГБ в домашнем каталоге (файлы дистрибутива) и не меньше 3 ГБ в каталоге /tmp (инсталлятор временно распаковывает в него бандл).
• Для скачивания дистрибутива – любой компьютер с доступом в интернет и способ перенести файлы на рабочее место, например съёмный носитель.
• Рабочим местом может быть отдельный компьютер или один из серверов Консоли управления. Во втором случае инсталлятор запускается от имени пользователя, указанного в ssh.user (с правом sudo без пароля), и обращается к своему серверу без SSH. Права root инсталлятор получает сам через sudo; запуск через sudo или от имени root не требуется.

Сетевое взаимодействие¶

Обозначения в таблицах:

• Серверы – все серверы Консоли управления;
• Контроллеры – первые три сервера в списке hosts файла installer.yaml (в профиле standalone – единственный сервер);
• Рабочее место – компьютер, с которого запускается инсталлятор;
• VIP API и VIP Консоли – адреса из файла installer.yaml.

Пользователи и фильтрующие ноды → Консоль управления¶

Адрес Консоли управления – VIP Консоли, адрес балансировщика или IP-адрес сервера (standalone).

Если заданы параметры ingress.httpsPort и ingress.httpPort (например, 8443 и 8080, когда на сервере Консоли управления установлена фильтрующая нода), вместо портов 443 и 80 используются указанные.

В варианте без TLS Консоль управления принимает только HTTP на порту 80 или на порту из параметра ingress.httpPort, порт 443 закрыт. Доступ к этим портам разрешается только с вашего прокси-сервера.

Рабочее место → серверы¶

Доступ нужен на время установки, обновления и проверки состояния.

Между серверами¶

Рекомендуется разрешить весь трафик между серверами Консоли управления в их общей сети. Если политика безопасности требует перечислить порты:

Внешний балансировщик → серверы (профиль ha, способ external)¶

Настройки балансировщика:

• режим балансировки – TCP (не HTTP): TLS-сертификат установлен на серверах Консоли управления;
• проверка доступности – TCP на порт 443, интервал 2–5 секунд, исключение сервера после 2–3 неудачных проверок подряд;
• чтобы Консоль управления получала IP-адреса пользователей, включите PROXY protocol (IP-адреса пользователей за балансировщиком);
• в пул входят все серверы Консоли управления.

Службы организации¶

Доступ в интернет серверам и рабочему месту не нужен: все компоненты устанавливаются из дистрибутива.

Let's Encrypt¶

Требуется только при использовании сертификата Let's Encrypt.

Адреса серверов Let's Encrypt не публикуются, поэтому ограничить доступ к портам 80 и 443 по источнику нельзя.

Порты, которые не открываются наружу¶

Порты 2380, 9443, 8132, 10250, 179, 7946 и порты баз данных (5432, 8123, 9000, 9181) используются только между серверами Консоли управления. Не открывайте их для пользовательских сетей и интернета.

Подготовка рабочего места администратора¶

Скачивание дистрибутива¶

1. На компьютере с доступом в интернет откройте ссылку на дистрибутив и введите пароль. Скачайте по одному нужные файлы:

   Файл	Когда скачивать
   apifw-installer-linux-amd64	Всегда
   SHA256SUMS	Всегда
   proapi-3.0.0-standalone.bundle.tar.gz	Профиль standalone
   proapi-3.0.0-ha.bundle.tar.gz	Профиль ha
   proapi-node-3.0.0.bundle.tar.gz	Если устанавливаются фильтрующие ноды

   Файлы сохраняются с теми же именами, что в папке дистрибутива. Не переименовывайте их: имена используются в командах этой инструкции и в файле SHA256SUMS. Если браузер добавил к имени номер, например apifw-installer-linux-amd64 (1), удалите лишний файл и скачайте заново.

2. Перенесите скачанные файлы на рабочее место администратора в домашний каталог пользователя, например на съёмном носителе.

Каталог установки¶

3. Создайте каталог установки и переместите в него файлы дистрибутива:

   mkdir -p ~/proapi
   mv ~/apifw-installer-linux-amd64 ~/SHA256SUMS ~/proapi-*.bundle.tar.gz ~/proapi/
   cd ~/proapi && ls -l
   

   Команда ls выводит перенесённые файлы, например для профиля ha с фильтрующими нодами:

   SHA256SUMS
   apifw-installer-linux-amd64
   proapi-3.0.0-ha.bundle.tar.gz
   proapi-node-3.0.0.bundle.tar.gz
   

4. Проверьте, что файлы не повреждены:

   sha256sum -c --ignore-missing SHA256SUMS
   

   Для каждого файла должно выводиться OK, например proapi-3.0.0-ha.bundle.tar.gz: OK. Если для файла выводится FAILED, скачайте и перенесите этот файл заново. Файлы, которые не скачивались, команда пропускает.

5. Подготовьте инсталлятор и проверьте его запуск:

   cp apifw-installer-linux-amd64 installer
   chmod +x installer
   ./installer version
   

   Команда выводит версию инсталлятора и версии компонентов «ПроAPI Защита», с которыми он выпущен:

   installer 3.0.0 (commit …)
   
   Release components:
     chart     3.0.0
     manager   3.0.0
     ui        3.0.0
     module    3.0.0
     agent     3.0.0
     apistore  3.0.0
   

   Версию инсталлятора указывают при обращении в техническую поддержку. Файл apifw-installer-linux-amd64 оставьте в каталоге: он нужен для проверки контрольных сумм и для установки фильтрующих нод.

Файлы .tar.gz не распаковывайте: инсталлятор работает с ними как есть.

Все дальнейшие команды выполняются из каталога ~/proapi. Если рабочим местом служит один из серверов Консоли управления, команды выполняются от имени пользователя, указанного в ssh.user, без sudo перед ./installer.

SSH-ключ¶

Если SSH-ключа нет, создайте его:

ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ''

Скопируйте открытый ключ на каждый сервер (если инсталлятор запускается на сервере Консоли управления – на все остальные серверы). Команда один раз запросит пароль пользователя:

ssh-copy-id -i ~/.ssh/id_ed25519.pub root@10.0.0.11   # ЗАМЕНИТЕ пользователя и адрес

Ключи серверов¶

Инсталлятор подключается только к серверам, ключи которых уже известны рабочему месту. Подключитесь к каждому серверу один раз и подтвердите ключ ответом yes:

ssh root@10.0.0.11 hostname   # ЗАМЕНИТЕ; повторите для каждого сервера

Команда должна вывести имя сервера без запроса пароля. Если выводится предупреждение REMOTE HOST IDENTIFICATION HAS CHANGED, сервер был переустановлен: удалите старый ключ командой ssh-keygen -R 10.0.0.11 и подключитесь снова.

Подготовка серверов¶

Проверки инсталлятора¶

Перед изменениями на серверах инсталлятор проверяет каждый сервер и останавливается с сообщением о причине, если:

• архитектура сервера отличается от x86-64;
• на сервере остались данные предыдущей установки;
• для данных свободно меньше 20 ГБ;
• имена серверов совпадают;
• время на серверах расходится больше чем на 30 секунд;
• у пользователя нет прав root или sudo без пароля;
• сервер использует cgroup v1 вместо cgroup v2;
• в ядре нет нужных модулей или их загрузка запрещена;
• (ha) VIP-адрес занят или находится вне подсети серверов;
• на сервере нет нужных команд или места для бандла.

Следующие проверки выводят предупреждение WARNING: node <адрес>: ... и не останавливают установку: включён swap, в настройках ОС выключена пересылка пакетов (net.ipv4.ip_forward = 0), SELinux работает в режиме Enforcing без пакета container-selinux. Рекомендуется устранить их до установки (Настройки операционной системы).

sudo без пароля¶

Если для подключения используется не root, разрешите пользователю sudo без пароля. На каждом сервере (команда один раз запрашивает пароль пользователя):

echo 'admin ALL=(ALL) NOPASSWD:ALL' | sudo tee /etc/sudoers.d/proapi   # ЗАМЕНИТЕ admin на имя пользователя
sudo chmod 440 /etc/sudoers.d/proapi
sudo visudo -cf /etc/sudoers.d/proapi                                 # проверка синтаксиса

Проверка с рабочего места: ssh admin@10.0.0.11 sudo -n true && echo OK.

Отдельный диск для данных (необязательно)¶

Данные Консоли управления хранятся в каталоге /var/lib/wmx/api-firewall/local-path. Чтобы хранить их на отдельном диске, смонтируйте диск в каталог /var/lib/wmx/api-firewall на каждом сервере до установки. Пример для диска /dev/sdb:

lsblk                                                 # найдите имя пустого диска
sudo mkfs.ext4 /dev/sdb                               # ВНИМАНИЕ: данные на диске будут удалены. ЗАМЕНИТЕ /dev/sdb
sudo mkdir -p /var/lib/wmx/api-firewall
echo "UUID=$(sudo blkid -s UUID -o value /dev/sdb) /var/lib/wmx/api-firewall ext4 defaults 0 2" | sudo tee -a /etc/fstab   # ЗАМЕНИТЕ /dev/sdb
sudo mount -a && df -h /var/lib/wmx/api-firewall

Команда df должна показать новый диск, а не системный (/).

• Новый диск должен быть пустым; каталог lost+found допускается.
• Компоненты кластера и образы контейнеров остаются на системном диске.
• Допускается монтирование диска в /var/lib/wmx/api-firewall/local-path. Другие точки монтирования внутри /var/lib/wmx/api-firewall не поддерживаются.
• Каталог /var/lib/wmx и путь к нему не должны быть символическими ссылками.

Настройки операционной системы¶

Инсталлятор проверяет настройки ОС автоматически. Выполняйте действия этого раздела, только если установка остановилась с ошибкой или вывела предупреждение. Требования действуют также для серверов фильтрующих нод.

cgroup v2. Сообщение the server uses cgroup v1, and Kubernetes needs cgroup v2. Проверка:

stat -fc %T /sys/fs/cgroup/      # требуется ответ cgroup2fs

Если ответ другой (например, tmpfs), включите cgroup v2 и перезагрузите сервер.

В РЕД ОС и других ОС с командой grubby:

sudo grubby --update-kernel=ALL --args="systemd.unified_cgroup_hierarchy=1"
sudo reboot

В Astra Linux, Альт, Debian, Ubuntu:

sudo sed -i 's/^GRUB_CMDLINE_LINUX="/&systemd.unified_cgroup_hierarchy=1 /' /etc/default/grub   # в Альт файл /etc/sysconfig/grub2
sudo update-grub
sudo reboot

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

Модули ядра. Кластер при запуске сам загружает модули overlay, nf_conntrack, br_netfilter, ip_tables и включает пересылку пакетов. Ручная настройка требуется только в следующих случаях:

• kernel modules ... are missing from the server's kernel – сервер загружен с нестандартным ядром. Загрузите стандартное ядро дистрибутива.

• loading modules is turned off on this server – в ОС запрещена загрузка модулей ядра. Настройте загрузку модулей при старте сервера:

  printf '%s\n' overlay nf_conntrack br_netfilter ip_tables | sudo tee /etc/modules-load.d/proapi.conf
  sudo reboot
  

• the modprobe command is missing – установите пакет kmod из репозитория ОС.

Пересылка пакетов. Предупреждение <файл> sets net.ipv4.ip_forward = 0. Кластер включает пересылку пакетов при запуске, но ОС может снова применить указанный файл, например при перезапуске сети. После этого сеть кластера перестаёт работать. Откройте файл (sudo nano <файл>) и замените в этой строке 0 на 1.

Swap. Предупреждение swap is on. При включённом swap и нехватке памяти работа кластера замедляется. Отключите swap:

sudo swapoff -a
sudo sed -i '/\sswap\s/s/^/#/' /etc/fstab      # swap не включится после перезагрузки
swapon --show                                  # пустой вывод: swap выключен

SELinux. Предупреждение SELinux is in enforcing mode, and the container-selinux package is not installed. Установите пакет до установки Консоли управления:

sudo dnf install container-selinux

Если пакета нет в репозитории ОС, обратитесь в техническую поддержку.

Лицензионный ключ¶

Лицензионный ключ не сохраняется в файлах конфигурации. Если он не задан, инсталлятор запросит его при запуске; вводимые символы не отображаются.

Для повторных запусков удобно использовать файл:

cat > secrets.env <<'EOF'
APIFW_LICENSE_KEY='ЗАМЕНИТЕ_лицензионный_ключ'
EOF
chmod 600 secrets.env

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

set -a; . ./secrets.env; set +a

Конфигурация установки¶

Мастер настройки¶

./installer init

Мастер задаёт вопросы по одному и сохраняет ответы в файл installer.yaml; вопросы, которые к выбранному варианту не относятся, пропускаются. Стрелки выбирают вариант, Enter и Tab переходят к следующему шагу, Shift+Tab – к предыдущему, Alt+Enter добавляет строку в список, Ctrl+C завершает мастер без сохранения.

В конце мастер выводит все ответы под заголовком «Проверьте конфигурацию» и спрашивает «Сохранить конфигурацию?». Проверьте адреса серверов, DNS-имя, вариант TLS, порты Консоли управления и, для профиля ha, адреса VIP. Чтобы исправить ответ, выберите «Отмена» и запустите ./installer init снова: файл при этом не создаётся.

Мастер не перезаписывает существующий файл installer.yaml.

Дополнительные параметры профиля ha¶

Файл installer.yaml редактируется в текстовом редакторе. Для отступов используются только пробелы, по два на уровень.

Серверы с несколькими сетями. Мастер заполняет параметры сам. При ручной настройке укажите адрес во внутренней сети (privateAddress) для каждого сервера и интерфейс (interface) для VIP:

mode: ha
hosts:
  - address: 203.0.113.11        # адрес для SSH
    privateAddress: 192.168.0.11 # адрес во внутренней сети
  - address: 203.0.113.12
    privateAddress: 192.168.0.12
  - address: 203.0.113.13
    privateAddress: 192.168.0.13
ha:
  controlPlane:
    address: 192.168.0.100/24    # VIP API, с маской
    interface: eth1              # интерфейс внутренней сети
  ingress:
    address: 192.168.0.101       # VIP Консоли, без маски
    interface: eth1

Внешний балансировщик. VIP Консоли не указывается:

ha:
  controlPlane:
    address: 192.168.0.100/24
    interface: eth1
  ingress:
    mode: external

VIP API недоступен с рабочего места. Укажите DNS-имя или адрес трансляции (NAT), ведущий на VIP API:

ha:
  apiAddress: k8s-api.example.ru

В сети уже используется VRRP. Укажите уникальный номер виртуального маршрутизатора от 1 до 255:

ha:
  controlPlane:
    virtualRouterID: 77

Проверка конфигурации: ./installer status. Ошибки конфигурации выводятся с указанием параметра. Сообщение kubeconfig is unavailable до установки – штатное.

Первый администратор и пароли¶

Пароли баз данных, ключ подписи и пароль первого администратора создаёт инсталлятор. Задавать их вручную не требуется.

Первый администратор. Email (логин) задаётся в мастере настройки и хранится в installer.yaml:

admin:
  email: admin@example.ru
  organization: ООО Пример   # необязательно: название организации в Консоли управления

• Пароль генерируется при установке и выводится один раз в конце установки, в строке One-time password for admin@example.ru: .... Сохраните его до первого входа.
• Пароль выводится только в окно терминала и не попадает в файл install.log.
• При первом входе Консоль управления требует сменить пароль.
• Администратор создаётся только при установке. Изменение admin.email и admin.organization после установки не действует; новых пользователей добавляют в Консоли управления.

sudo k0s kubectl -n api-firewall get secret api-firewall-manager-secrets -o jsonpath='{.data.WMX_USER_PASSWORD}' | base64 -d; echo

Пароли баз данных и ключ подписи генерируются при установке и хранятся в кластере, в секрете api-firewall-manager-secrets. При обновлении используются те же значения. Не удаляйте и не изменяйте этот секрет: без него Консоль управления потеряет доступ к своим базам данных.

Установка¶

Перед установкой в каталоге ~/proapi находятся: installer, бандл Консоли управления своего профиля, secrets.env, installer.yaml и, если они используются, файлы сертификата и ключа и файлы из chart.values.

Профиль standalone:

cd ~/proapi
set -a; . ./secrets.env; set +a
set -o pipefail
./installer install --bundle ./proapi-3.0.0-standalone.bundle.tar.gz --verbose 2>&1 | tee install.log

Профиль ha:

cd ~/proapi
set -a; . ./secrets.env; set +a
set -o pipefail
./installer install --bundle ./proapi-3.0.0-ha.bundle.tar.gz --verbose 2>&1 | tee install.log

• Перед изменениями на серверах инсталлятор проверяет целостность бандла, его версию и профиль, наличие нужных команд и свободное место на серверах. Затем бандл копируется на каждый сервер.
• Установка занимает 15–30 минут. Не закрывайте терминал и не допускайте перехода рабочего места в спящий режим.
• Полный вывод сохраняется в файл install.log.
• При успешной установке выводятся сообщение Installed product at https://<DNS-имя>, для самоподписанного сертификата – путь к файлу CA, логин первого администратора и, только в окне терминала, его одноразовый пароль (Первый администратор и пароли).

Если установка прервалась, выполните удаление и запустите установку снова.

Проверка установки¶

./installer status

Пример результата для профиля ha:

Cluster: READY; API /readyz: OK; nodes: 3/3 ready (expected 3)
Chart: deployed; release: api-firewall; version: 3.0.0
Readiness api-firewall: READY
Readiness api-firewall-operators: READY
Readiness metallb-system: READY
TLS: OK; self-signed; proapi.example.ru; valid until 2027-10-09 (364 days)

• Строка metallb-system выводится только для профиля ha со способом публикации VIP.
• Строка TLS показывает срок действия сертификата: WARNING – до окончания меньше 30 дней, EXPIRED – сертификат истёк.
• Состояние NOT READY в первые минуты после установки или перезагрузки сервера штатное. Если оно сохраняется дольше 15 минут (Устранение неполадок).

Команда использует файл installer.kubeconfig рядом с installer.yaml. Файл даёт полный доступ к кластеру: храните его как пароль администратора.

Откройте в браузере https://<DNS-имя Консоли управления> и войдите с email из admin.email и одноразовым паролем из вывода установки. Консоль управления предложит задать новый пароль.

TLS-сертификат Консоли управления¶

Вариант задаётся в разделе ingress.tls файла installer.yaml; мастер настройки заполняет его сам. Загружать сертификат в кластер вручную не нужно.

Самоподписанный сертификат (по умолчанию)¶

ingress:
  host: proapi.example.ru
  tls:
    mode: self-signed

• Инсталлятор создаёт центр сертификации (CA) сроком на 10 лет и выпускает им сертификат для DNS-имени Консоли управления сроком на 1 год.
• Сертификат CA сохраняется рядом с installer.yaml в файл installer.ca.pem. Файл передаётся на фильтрующие ноды (Подключение фильтрующих нод) и может быть добавлен в доверенные сертификаты браузеров пользователей.
• Сертификат выпускается заново тем же CA при обновлении, если до окончания срока осталось меньше 30 дней, а также по команде ./installer tls renew. Перенастраивать ноды не нужно.

Собственный сертификат¶

ingress:
  host: proapi.example.ru
  tls:
    mode: custom
    cert: certs/fullchain.pem   # сертификат сервера, затем промежуточные
    key: certs/privkey.pem      # закрытый ключ без пароля

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

Замена сертификата после установки или переход с самоподписанного сертификата:

./installer tls set --cert ./fullchain.pem --key ./privkey.pem

Команда выводит данные сертификата и запрашивает подтверждение (yes), применяет сертификат без остановки Консоли управления и сохраняет пути к файлам в installer.yaml. Возврат к самоподписанному сертификату: ./installer tls set --self-signed.

Сертификат Let's Encrypt¶

Сертификат Let's Encrypt получает и продлевает программа certbot на одном из серверов Консоли управления с проверкой через HTTP (HTTP-01).

Требования:

• DNS-имя Консоли управления публичное и указывает на её адрес (сервер, VIP или балансировщик);
• порты TCP 80 и 443 адреса Консоли управления доступны из интернета (Let's Encrypt в сетевом взаимодействии);
• у сервера с certbot есть доступ к acme-v02.api.letsencrypt.org по TCP 443.

Порты 80 и 443 на серверах занимает Консоль управления, поэтому certbot работает на другом порту, а инсталлятор направляет на него проверочные запросы со всех серверов.

1. Добавьте в installer.yaml:

   ingress:
     host: proapi.example.ru
     acmeChallenge:
       port: 8888          # порт certbot
       # host: 10.0.0.11   # необязательно: IP-адрес сервера с certbot, по умолчанию первый сервер из hosts
   

   При установке параметр применяется автоматически. После установки выполните ./installer tls renew.

2. На сервере с certbot разместите installer, installer.yaml и installer.kubeconfig, например в /root/proapi, установите certbot (apt install certbot или пакет вашей ОС) и получите сертификат:

   certbot certonly --standalone --http-01-port 8888 -d proapi.example.ru -m admin@example.ru --agree-tos --deploy-hook '/root/proapi/installer --config /root/proapi/installer.yaml tls set --cert $RENEWED_LINEAGE/fullchain.pem --key $RENEWED_LINEAGE/privkey.pem --yes'
   

   ЗАМЕНИТЕ DNS-имя, адрес электронной почты и каталог. Указанная в --deploy-hook команда применяет сертификат после получения и после каждого продления. certbot продлевает сертификат автоматически примерно за 30 дней до окончания 90-дневного срока. Проверка продления: certbot renew --dry-run --run-deploy-hooks.

3. Убедитесь, что ./installer status выводит TLS: OK; custom.

Фильтрующим нодам файл CA для сертификата Let's Encrypt не нужен. При переходе с самоподписанного сертификата связь нод с Консолью управления не прерывается.

Сертификат Let's Encrypt, полученный другим способом (на другом компьютере, с проверкой через DNS), применяется командой tls set, как собственный сертификат; параметр acmeChallenge в этом случае не нужен.

Без TLS (TLS завершает прокси-сервер)¶

ingress:
  host: proapi.example.ru
  tls:
    mode: none
  httpPort: 8080               # необязательно, по умолчанию 80
  trustedProxies:              # необязательно: адреса прокси-сервера
    - 10.244.0.0/16

• Консоль управления принимает только HTTP, порт 443 закрыт. Вариант допустим, только если перед Консолью управления стоит прокси-сервер или балансировщик, который сам завершает TLS.
• httpPort – порт Консоли управления, если порт 80 на сервере занят прокси-сервером. Прокси на том же сервере направляет запросы на http://127.0.0.1:8080, отдельный прокси – на http://<IP-адрес сервера>:8080.
• trustedProxies – адреса или подсети прокси-серверов, которые передают IP-адрес пользователя в заголовке X-Real-IP. Для прокси на самих серверах Консоли управления указывается внутренняя сеть кластера 10.244.0.0/16.
• Фильтрующие ноды подключаются к прокси-серверу по HTTPS или к Консоли управления напрямую по HTTP (параметр --manager http://… при установке ноды).

Смена варианта после установки¶

• Между самоподписанным и собственным сертификатом – командой tls set.
• Между TLS и вариантом без TLS, а также изменение httpPort, httpsPort, trustedProxies и proxyProtocol: измените раздел ingress в installer.yaml и выполните обновление с тем же бандлом. Данные Консоли управления сохраняются. Во время перенастройки возможны единичные ошибки запросов; фильтрующие ноды повторяют отправку данных.
• Перед переходом на вариант без TLS настройте и запустите прокси-сервер: порт 443 освобождается после обновления. При обратном переходе остановите прокси-сервер после обновления.
• При переходе с варианта без TLS на самоподписанный сертификат после обновления переключите каждую фильтрующую ноду на HTTPS командой
  

  sudo ./installer node upgrade --bundle ./proapi-node-3.0.0.bundle.tar.gz --manager https://proapi.example.ru --manager-ca installer.ca.pem
  

IP-адреса пользователей за балансировщиком¶

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

• Балансировщик в режиме TCP заголовков не добавляет. Включите на нём PROXY protocol (версии 1 или 2) для портов 80 и 443 и укажите его адреса в installer.yaml:

  ingress:
    proxyProtocol:
      - 10.0.0.5          # ЗАМЕНИТЕ: адрес или подсеть балансировщика
  

  PROXY protocol принимается только от указанных адресов. Соединения без заголовка также принимаются, поэтому порядок включения на балансировщике и в Консоли управления не важен.

• Прокси-сервер, завершающий TLS (вариант без TLS), указывается в trustedProxies и передаёт IP-адрес пользователя в заголовке X-Real-IP.

Изменения применяются обновлением с тем же бандлом.

Подключение фильтрующих нод¶

Фильтрующие ноды устанавливаются после Консоли управления, по инструкции Установка фильтрующей ноды с помощью инсталлятора. Для подключения потребуются:

• токен регистрации, который выдаёт Консоль управления в разделе Ноды (Создание ноды в Консоли управления);
• адрес Консоли управления, например https://proapi.example.ru;
• для самоподписанного сертификата – файл installer.ca.pem из каталога установки Консоли управления.

Работа при отказе сервера¶

В профиле ha при отказе одного сервера работа восстанавливается автоматически:

• фильтрующие ноды продолжают проверять и блокировать трафик без перерыва;
• VIP API переходит на работающий сервер за несколько секунд;
• веб-интерфейс снова доступен в течение минуты;
• PostgreSQL переключается на реплику; в это время вход в Консоль управления может быть недоступен до нескольких минут;
• после восстановления сервер автоматически подключается к кластеру, базы данных синхронизируются.

Действия администратора: восстановите сервер и проверьте состояние командой ./installer status.

Профиль ha не защищает от одновременного отказа двух серверов из трёх и не заменяет резервное копирование данных.

Обновление¶

Команда upgrade применяет к установленной Консоли управления версию из бандла и изменения раздела ingress в installer.yaml. Используется бандл того же профиля, что и при установке.

Профиль standalone:

cd ~/proapi
set -a; . ./secrets.env; set +a
set -o pipefail
./installer upgrade --bundle ./proapi-3.0.0-standalone.bundle.tar.gz --verbose 2>&1 | tee upgrade.log

Профиль ha:

cd ~/proapi
set -a; . ./secrets.env; set +a
set -o pipefail
./installer upgrade --bundle ./proapi-3.0.0-ha.bundle.tar.gz --verbose 2>&1 | tee upgrade.log

Переход на новую версию «ПроAPI Защита» выполняется по руководству новой версии, с инсталлятором и бандлом из её дистрибутива.

• Обновляются Консоль управления и операторы баз данных. Кластер и серверы не изменяются.
• Профиль standalone или ha при обновлении не меняется.
• Если предыдущее обновление было прервано, инсталлятор сообщает NOTE: release ... was left pending-upgrade by an interrupted upgrade, возвращает компонент к предыдущей версии и продолжает обновление.
• Изменения в разделе ingress (вариант TLS, httpPort, httpsPort, trustedProxies, proxyProtocol) применяются при обновлении.
• Фильтрующие ноды обновляются отдельно (Обновление фильтрующей ноды).
• Самоподписанный сертификат выпускается заново, если до окончания срока осталось меньше 30 дней. Собственный сертификат применяется из файлов, указанных в installer.yaml.
• Пароли баз данных и ключ подписи не меняются: используются значения, созданные при установке.

Устранение неполадок¶

Проверка перехода IP-адреса между серверами (профиль ha)¶

Некоторые сети блокируют IP-адреса, не закреплённые за портом сервера; в такой сети VIP не работает. Проверка (адрес 192.168.0.100, интерфейс eth1):

ip addr add 192.168.0.100/24 dev eth1   # на сервере 1; ЗАМЕНИТЕ адрес и интерфейс
ping -c 3 192.168.0.100                 # на сервере 2: ответы должны приходить
ip addr del 192.168.0.100/24 dev eth1   # на сервере 1

Если ответов нет, попросите администратора сети разрешить на портах серверов дополнительные IP-адреса и gratuitous ARP или используйте способ публикации external.

Обращение в техническую поддержку¶

Приложите к обращению файл install.log (или upgrade.log) и вывод команды ./installer status. Учётные данные в эти файлы не записываются.

Удаление¶

./installer reset

Инсталлятор выведет список серверов и запросит подтверждение: введите RESET. Серверы будут перезагружены.

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

Отдельный диск для данных очищается и остаётся смонтированным; повторно форматировать его не нужно. Файл installer.yaml сохраняется для повторной установки. Пароли Консоли управления удаляются вместе с кластером: при повторной установке создаются новые, в том числе новый одноразовый пароль администратора.

Термины¶