Перейти к основному содержимому
Версия: v2.8.x

Установка инсталляции Логикор в Штурвал с помощью Ansible

В рамках данной лабораторной работы мы расскажем, как выполнить установку инсталляции Логикор в K8s-платформу Штурвал, что для этого необходимо, как выполнить проверку работоспособности Системы, и ответим на наиболее часто встречающиеся вопросы.

к сведению

Штурвал — Kubernetes-платформа (K8s), в которой разворачивается Система Логикор. Она обеспечивает управление узлами кластера, работу Ingress и других платформенных сервисов, а также реконсиляцию инфраструктуры.

AxelCloud — средство автоматизации развертывания, дополняющее встроенный инсталлятор платформы Штурвал. Оно выполняет дополнительные действия при установке, включая подготовительные и завершающие операции. Для запуска развертывания используется команда axelcloud install. Порядок работы описан в разделе «Развертывание платформы Штурвал (AxelCloud)».

Требования к серверам для выполнения установки​

Требования к узлам платформы Штурвал​

Узлы платформы Штурвал развертываются на физических серверах или виртуальных машинах на быстрых дисках — SSD, не менее 600 IOPS. Поддерживаемые операционные системы:

  • Debian 11, 12 (ядра 5.10, 6.1.0);
  • Astra Linux Special Edition 1.7, 1.8 (ядра 5.10, 5.15, 6.1, 6.6).

В таблице ниже приведены минимальные требования к ресурсам узлов и минимальный состав узлов, при которых в кластер возможно развернуть пользовательскую нагрузку:

Роль узлаCPU, ядерRAM, ГБДиск, ГБНазначение
control48250Развертывание и настройка платформы. Дополнительно размещает: makeself-пакет AxelCloud, офлайн-репозиторий Штурвала с образами и пакетами, офлайн-репозиторий Aptly и NFS-сервер для csi-nfs в K8s
master4860Управляющие узлы кластера
infra81660Системные сервисы платформы Штурвал
worker82460Пользовательская нагрузка. Требования могут увеличиваться в зависимости от характера нагрузки и целевого потока событий
к сведению

Важно! Приведенная конфигурация стенда — тестовая: по количеству узлов и выделенным ресурсам она не соответствует расчетной конфигурации продуктивной среды. Для роли worker указаны минимальные требования при потоке Системы до 1000 EPS. Для других профилей нагрузки и для отказоустойчивой конфигурации ориентируйтесь на статью Логикор. Аппаратные требования.

Пример конфигурации тестового стенда​

Приведенная ниже схема соответствует варианту Multi-Master + Infra Nodes + Worker Nodes — эта топология (кластер с выделенными узлами для инфраструктурных компонентов) рекомендуется для продуктивных окружений.

Узлы Kubernetes​

HostnameIPCPURAM, ГБSTORAGE, ГБ
k8s-master110.10.10.204860
k8s-master210.10.10.214860
k8s-master310.10.10.224860
k8s-infra110.10.10.2381660
k8s-infra210.10.10.2481660
k8s-worker-apps110.10.10.2582460
k8s-worker-apps210.10.10.2682460
k8s-worker-saturn110.10.10.2787260
k8s-worker-saturn210.10.10.2887260
k8s-worker-saturn310.10.10.2987260

Control-узлы​

HostnameIPCPURAM, ГБSTORAGE, ГБ
k8s-control10.10.10.1948250
logicore-control10.10.10.3048150

Узлы ClickHouse и ClickHouse Keeper (bare-metal)​

HostnameIPCPURAM, ГБSTORAGE, ГБ
click-keeper-110.10.10.312240
click-keeper-210.10.10.322240
click-keeper-310.10.10.332240
click1-110.10.10.34161640/300
click2-110.10.10.35161640/300

Узлы инфраструктуры (bare-metal)​

HostnameIPCPURAM, ГБSTORAGE, ГБ
logicore-infra110.10.10.364860
logicore-infra210.10.10.374860
logicore-infra310.10.10.384860

Виртуальные IP-адреса​

IP-адресНазначение
10.10.10.245VIP-адрес для точки доступа к API Kubernetes
10.10.10.246VIP для Ingress
к сведению

Виртуальные IP-адреса должны быть свободны: они не должны быть заранее настроены на узлах кластера или использоваться где-либо еще.

к сведению

Дистрибутив Системы должен иметь имя logicore_x.x.x-offline_amd64.run, где x.x.x — номер версии.

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

внимание

На каждом сервере должна быть выполнена интеграция с корпоративным NTP-сервером.

Процесс установки Системы подразумевает развертывание с помощью утилит Docker и Ansible. Все команды и скрипты выполняются с control-узла Логикор (logicore-control). Такой вариант установки требует доступа ко всем узлам по протоколу SSH. Рассмотрим процесс установки более подробно.

Настройка SSH-подключения​

к сведению

OpenSSH должен быть настроен на стандартном 22 порту.

Для настройки выполите следующие действия:

Шаг 1. Если для установки Логикор имеется потребность в использовании непривилегированного пользователя, отличного от root, то создайте целевого SSH-пользователя на всех узлах, если этого не было сделано ранее:

sudo useradd -m -s /usr/bin/bash -g users -G sudo <целевой_ssh_пользователь>
sudo groupadd <целевой_ssh_пользователь>

Шаг 2. Если целевой пользователь является непривилегированным, отличным от root, то на каждом узле добавьте пользователя в sudo с отключением ввода пароля:

echo '<целевой_ssh_пользователь> ALL=(ALL) NOPASSWD: ALL' | sudo tee -a /etc/sudoers

Шаг 3. На control-узле Логикор (logicore-control) выполните генерацию SSH-ключей под целевым пользователем, под которым будет запускаться установка Логикор:

su - <целевой_ssh_пользователь>
ssh-keygen -t rsa

Шаг 4. Скопируйте публичный SSH-ключ с control-узла на узлы ClickHouse и ClickHouse Keeper (bare-metal), если ключи ранее не копировались:

# не забываем актуализировать ip_list, ssh_user и ssh_pass
ssh-keygen

sudo apt install sshpass -y

ip_list=10.10.10.31,10.10.10.32,10.10.10.33,10.10.10.34,10.10.10.35
ssh_user=<целевой_ssh_пользователь>
ssh_pass=<пароль_целевого_ssh_пользователя>

IFS=',' read -ra ip_array <<< "$ip_list"

for ip in "${ip_array[@]}"; do
echo $ip
ssh-keyscan $ip >> ~/.ssh/known_hosts
sshpass -p "$ssh_pass" ssh-copy-id -i ~/.ssh/id_rsa.pub $ssh_user@$ip
done

Перенос дистрибутива Логикор для установки​

Для установки Системы необходимо загрузить дистрибутив Логикор на control-узел и затем распаковать. Для этого выполните следующие действия:

Шаг 1. Подключите USB-накопитель к устройству, с которого имеется доступ по SSH к control-узлу, и передайте на него дистрибутив:

scp <путь_к_офлайн-сборке_на_USB-накопителе> <целевой_ssh_пользователь>@<адрес_control_сервера>:/opt/logicore_<версия_Логикор>-offline_amd64.run

Шаг 2. Войдите в терминал control-узла и выполните распаковку офлайн-дистрибутива:

sudo chmod +x /opt/logicore_<версия_Логикор>-offline_amd64.run
sudo /opt/logicore_<версия_Логикор>-offline_amd64.run

Доменная зона для K8s​

Доменная зона для платформы Штурвал. Пример: k8s.domain.corp.

В доменной зоне необходимо создать следующие записи DNS:

  • A-запись registry — офлайн-зеркало платформы Штурвал. Привязывается к IP-адресу control-сервера. Пример: registry.k8s.domain.corp.
  • A-запись api — для Kube-API. Привязывается к VIP-адресу Kube-API. Пример: api.k8s.domain.corp.
  • Wildcard A-запись *.apps — для Ingress. Привязывается к VIP-адресу Ingress. Пример: *.apps.k8s.domain.corp.

Развертывание платформы Штурвал (AxelCloud)​

Подготовка​

  1. Проверьте, что инфраструктура соответствует требованиям к платформе Штурвал (раздел «Требования к узлам платформы Штурвал»).
  2. Проверьте, что количество выделенных серверов и ресурсов соответствует расчетной конфигурации.
  3. Проверьте, что на узлах выполнены предварительные условия, перечисленные ниже.

Предварительные условия​

1. OpenSSH. На всех узлах установлен и настроен openssh-server на стандартном 22 порту.

2. Сервисный пользователь. На каждом сервере создается сервисная учетная запись axelcloud: под ней запускается утилита axelcloud, и с control-узла под ней же выполняются SSH-подключения на все managed-узлы:

sudo useradd axelcloud -m -s /bin/bash

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

sudo visudo
# добавить строку:
axelcloud ALL=(ALL) NOPASSWD:ALL

3. Авторизация по SSH-ключу. На control-узле под пользователем axelcloud сгенерируйте SSH-ключ. Приватный ключ размещается в каталоге /home/axelcloud/.ssh и должен быть без пароля (passphrase) — Штурвал не работает с зашифрованными ключами:

ssh-keygen -t ed25519

Поддерживаются ключи любого типа (ed25519, ecdsa, rsa, dsa) и с любым именем файла. По умолчанию ключ определяется автоматически: сначала проверяются id_ed25519, id_ecdsa, id_rsa, id_dsa, затем — любой другой приватный ключ в каталоге. Если ключей несколько и нужно использовать конкретный, его путь указывается в параметре deploy.ssh_private_key конфигурационного файла AxelCloud.

Публичный ключ добавляется на каждый managed-узел:

ssh-copy-id -i /home/axelcloud/.ssh/id_ed25519.pub axelcloud@<IP_адрес_или_FQDN_managed_узла_N>

4. Сетевая адресация. На всех узлах платформы (control, master, infra и worker) обязательна статическая IP-адресация: назначение адресов узлам кластера через DHCP не допускается.

5. Сетевые имена узлов. Каждый узел кластера должен иметь уникальное сетевое имя — валидное DNS-имя длиной не более 63 символов:

sudo hostnamectl set-hostname k8s-master1
echo "127.0.1.1 k8s-master1" | sudo tee -a /etc/hosts

6. DNS-зона и VIP. В инфраструктурном DNS создаются доменная зона и записи registry, api, *.apps (раздел «Доменная зона для K8s»), а для Kube-API и Ingress резервируются два свободных виртуальных IP-адреса (таблица в разделе «Виртуальные IP-адреса»).

7. NTP. Все узлы кластера должны иметь синхронизированное системное время: рассинхронизация времени между узлами Kubernetes может приводить к ошибкам TLS-сертификатов, проблемам аутентификации, нестабильной работе etcd и нарушению работы компонентов платформы.

внимание

NTP-клиент (chrony) и часовой пояс на узлах платформы настраиваются автоматически средствами AxelCloud — параметрами ntp.enable, ntp.timezone и ntp.servers в конфигурационном файле. Указанные NTP-серверы должны быть доступны по сети со всех узлов платформы. Если NTP-клиенты и часовой пояс уже настроены на узлах заранее и автоматическая настройка не требуется, автоматизацию отключают параметром ntp.enable: "false".

Установка платформы​

Шаг 1. Подключитесь по SSH к control-узлу платформы (k8s-control) и передайте офлайн-дистрибутив AxelCloud — например, с USB-накопителя:

scp <путь_к_офлайн-сборке_на_USB-накопителе> axelcloud@<адрес_control_сервера>:/opt/axelcloud_<версия_AxelCloud>-offline_amd64.run

Шаг 2. Распакуйте офлайн-дистрибутив и отредактируйте конфигурационный файл:

cd /opt/
sudo chmod +x /opt/axelcloud_<версия_AxelCloud>-offline_amd64.run
sudo /opt/axelcloud_<версия_AxelCloud>-offline_amd64.run
vi /etc/axelcloud/config.yml
к сведению

Дистрибутив AxelCloud должен иметь имя axelcloud_x.x.x-offline_amd64.run, где x.x.x — номер версии.

/etc/axelcloud/config.yml
# ⚠️ Перед выполнением настройки убедитесь, что изучили и выполнили предварительные условия для развертывания AxelCloud

deploy: # Удалите {} и раскомментируйте параметры ниже для переопределения их значений
# Переопределение пользователя SSH для доступа с control-узла на managed-узлы
# По умолчанию: axelcloud
user: "axelcloud"
# Путь к приватному SSH-ключу control-узла. Указывается, если в каталоге /home/axelcloud/.ssh несколько ключей
# и нужно использовать конкретный. Ключ должен быть без пароля (passphrase)
#ssh_private_key: "/home/axelcloud/.ssh/id_ed25519"

control:
# Укажите IP-адрес или полное доменное имя (FQDN) control-узла
host: "10.10.10.19"
# Переопределение типа соединения ansible c control-узлом
# Доступные типы соединения: local, ssh
# По умолчанию: local
#ansible_connection: "ssh"

shturval:
# Укажите лицензионный ключ платформы Штурвал
license_key: "<ключ_лицензии_Штурвала>"

cluster:
# Укажите IP-адрес или полное доменное имя (FQDN) master и worker узлов платформы Штурвал. Не используйте локальные адреса, такие как: localhost, 127.0.0.1 ,::1
# Доступные типы: master, infra, worker
# Минимальный размер: 1 master узел
- host: "10.10.10.20"
type: "master"
- host: "10.10.10.21"
type: "master"
- host: "10.10.10.22"
type: "master"
- host: "10.10.10.23"
type: "infra"
- host: "10.10.10.24"
type: "infra"
- host: "10.10.10.25"
type: "worker"
- host: "10.10.10.26"
type: "worker"
- host: "10.10.10.27"
type: "worker"
- host: "10.10.10.28"
type: "worker"
- host: "10.10.10.29"
type: "worker"

# По умолчанию создается пользователь admin, имеется возможность переопределить его пароль по умолчанию или/и добавить новых пользователей.
users: # Удалите [] и раскомментируйте параметры ниже для переопределения их значений
- name: "admin"
password: "CHANGEME"
groups:
- shturval-embedded-admin

# Доступные групповые роли: shturval-view, shturval-view-restricted, shturval-cluster-admin, shturval-cluster-admin-restricted

config:
#nfs_server_share: "/opt/k8s_nfs_share"
logs_retention_period: "7d"
logs_max_disk_space_usage_bytes: "45GB"
logs_disk_size: "50Gi"
monitoring_retention_period: "15d"
monitoring_disk_size: "50Gi"

network:
# Укажите доменную зону для платформы Штурвал. Пример: k8s.domain.corp
base_domain: "k8s.domain.corp"
# Укажите свободный виртуальный IP-адрес (VIP) для эндпоинта Kube-API платформы Штурвал
api_virtual_ip: "10.10.10.245"
# Укажите свободный виртуальный IP-адрес (VIP) для Ingress платформы Штурвал
ingress_virtual_ip: "10.10.10.246"
# Для тестовых окружений имеется возможность использовать преднастроенный локальный DNS сервер из поставки AxelCloud
# ⚠️ ВРЕМЕННО: функция локального DNS принудительно отключена в ansible/plugins/inventory/axelcloud_inventory.py —
# значение enabled: "true" игнорируется. Используйте инфраструктурный DNS с зоной и записями registry, api, *.apps
local_dns:
enabled: "false"
# Установите дополнительные записи для локального DNS-сервера в доменной зоне из параметра `network.base_domain`, по умолчанию добавляются записи: registry, api, *.apps
extra_records: [] # Удалите [] и раскомментируйте параметры ниже для переопределения их значений
#- name: "new-record"
# ip: "10.11.12.13"
# IP-адреса внешних DNS серверов (инфраструктурный DNS-сервер и/или публичный DNS-сервер) для переадресации на них запросов через локальный DNS сервер
forward_external_dns: [] # Удалите [] и раскомментируйте параметры ниже для переопределения их значений
#- "192.168.1.1"
#- "8.8.8.8"

ntp:
enable: "true"
# Укажите часовой пояс для узлов платформы Штурвал
timezone: "Europe/Moscow"
# Укажите NTP-серверы для синхронизации времени узлов платформы Штурвал
servers:
- "0.ru.pool.ntp.org"
- "1.ru.pool.ntp.org"

Шаг 3. Запустите установку платформы:

# ! Обязательно запускаем в tmux !

axelcloud install

Справка об использовании утилиты axelcloud​

Использование: axelcloud <command> [-f /etc/axelcloud/config.yml]
Команды:
install Развернуть платформу Штурвал
get-config Вывести конфигурацию AxelCloud
Дополнительные флаги:
-f <config> Путь к конфигурационному файлу AxelCloud
По умолчанию используется /etc/axelcloud/config.yml
--version|-v|version Вывести версию AxelCloud
--help|-h|help Вывести эту справку и выйти

Обновление платформы Штурвал (AxelCloud)​

Процесс обновления платформы Штурвал выполняется в два этапа.

Этап 1. Обновление офлайн-зеркала платформы Штурвал. Загрузите и установите на control-узел (k8s-control) пакет AxelCloud с новой версией Штурвала — так же, как при первичном развертывании (раздел «Развертывание платформы Штурвал (AxelCloud)»).

Этап 2. Обновление платформы через графический интерфейс. Откройте дашборд кластера платформы:

https://shturval.apps.k8s.domain.corp/clusters/mgmt-shturval/dashboard

  • нажмите «Управлять» рядом с текущей версией кластера;
  • в открывшемся окне обновления запустите обновление вручную или настройте автоматическое обновление по расписанию.

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

к сведению

Кастомизация системных сервисов (NFS, monitoring, log-collector, Grafana и т.д.) хранится в патчах ShturvalServicePatch, поэтому обновление платформы ее не затрагивает. Если при обновлении (или при выключении/включении модуля в интерфейсе) системный сервис был пересоздан, патчи удаляются вместе с ним — в этом случае необходимо повторно выполнить кастомизацию.

Установка Логикор в Штурвал​

Выполняется с control-узла Логикор (logicore-control).

Подготовка конфигурационного файла Логикор​

Общая информация​

Конфигурация Логикор описывается в конфигурационном файле, представляющем собой Ansible Inventory-файл.

Путь к конфигурационному файлу​

Все параметры устанавливаемой Системы задаются в конфигурационном .yml-файле. Путь к конфигурационному файлу Логикор можно указать через флаг -f </conf/path>. Если параметр не указан, то по умолчанию используется путь /etc/lctl/config.yml.

Процесс подготовки конфигурационного файла​

Конфигурационный файл создается на control-узле Логикор по пути /etc/lctl/config.yml — этот путь используется по умолчанию; при необходимости его можно переопределить флагом -f </conf/path> в командах lctl.

Содержимое конфигурационного файла для данного варианта установки приведено ниже, в разделе «Пример конфигурационного файла».

Переопределение переменных Ansible​

Все переменные Ansible со значениями по умолчанию находятся во внутреннем файле /usr/share/lctl/ansible/inventories/defaults.yml. При необходимости любое из этих значений можно переопределить во внешнем конфигурационном файле /etc/lctl/config.yml (секция variables_overrides), а также на уровне конкретного хоста в секции hosts — такое переопределение имеет более высокий приоритет.

Файл defaults.yml также можно использовать как справочник — в нем перечислены все доступные параметры и настройки продукта Логикор, а также показана структура вложенности YAML.

внимание

Важно строго придерживаться этой структуры при переопределении параметров: если нарушить вложенность или формат, изменения не будут применены.

Пример конфигурационного файла​

В данной лабораторной работе Система устанавливается в K8s-платформу Штурвал: сервисы продукта разворачиваются в кластере, а слой хранения (ClickHouse, ClickHouse Keeper) — на выделенных bare-metal узлах. Ниже приведен пример конфигурационного файла Логикор для такого варианта установки — его содержимое размещается в файле /etc/lctl/config.yml на control-узле Логикор:

/etc/lctl/config.yml
hosts:
- name: "control-node"
address: "127.0.0.1"
connection: "local"

- name: "click1-1"
address: "10.10.10.34"
connection: "ssh"
user: "<целевой_ssh_пользователь>"
deployment_type: "bare-metal"
clickhouse_shard_id: "shard-01"
clickhouse_replica_id: "replica-01-01"

- name: "click2-1"
address: "10.10.10.35"
connection: "ssh"
user: "<целевой_ssh_пользователь>"
deployment_type: "bare-metal"
clickhouse_shard_id: "shard-02"
clickhouse_replica_id: "replica-01-01"

- name: "click-keeper-1"
address: "10.10.10.31"
connection: "ssh"
user: "<целевой_ssh_пользователь>"
deployment_type: "bare-metal"

- name: "click-keeper-2"
address: "10.10.10.32"
connection: "ssh"
user: "<целевой_ssh_пользователь>"
deployment_type: "bare-metal"

- name: "click-keeper-3"
address: "10.10.10.33"
connection: "ssh"
user: "<целевой_ssh_пользователь>"
deployment_type: "bare-metal"

# Переопределение целевых хостов для конкретных компонентов продукта. По умолчанию для всех компонентов используется локальный хост `control-node`.
# Список доступных компонентов: clickhouse, clickhouse_keeper, postgres, s3, apigw, aptly, registry, vault, portainer, mpsiem_rabbitmq, venus, earth, saturn, mercury, mars, docs, prometheus, grafana, victoriametrics, openldap, mailhog, docker
targets_overrides:
clickhouse:
hosts:
- click1-1
- click2-1
clickhouse_keeper:
hosts:
- click-keeper-1
- click-keeper-2
- click-keeper-3

# Переопределение переменных с параметрами развертывания продукта и его компонентов. Перечень доступных параметров и их структуру можно посмотреть в /usr/share/lctl/ansible/inventories/defaults.yml
variables_overrides:
deployment_type: "helm" # Обязательный параметр с указанием типа развертывания. Возможные значения: docker-compose, helm, bare-metal
offline_mode: "true"
init_aptly: "true"
use_repo_aptly: "true"
k8s_kubeconfig_path: "/home/<целевой_ssh_пользователь>/.kube/config"
# k8s_ingress_wildcard_domain: "" # by default, it is calculated from the ssc shturval-ingress-controller by the function get_k8s_ingress_wildcard_domain
clickhouse:
vault:
secret_path:
- clickhouse
secret_data:
clickhouse:
CLICKHOUSE_USER: "<пользователь_ClickHouse>"
CLICKHOUSE_PASSWORD: "CHANGEME"
CLICKHOUSE_READER_USER: "<пользователь_для_чтения_ClickHouse>"
CLICKHOUSE_READER_PASSWORD: "CHANGEME"
CLICKHOUSE_DB: "<имя_БД>"
mpsiem_rabbitmq:
use_external_instance: "true"
mailhog:
use_external_instance: "true"
openldap:
use_external_instance: "true"
portainer:
use_external_instance: "true"
s3:
use_external_instance: "true"
manual_set_endpoints:
urls:
- http://10.10.10.247:9100
vault:
secret_path:
- s3
secret_data:
s3:
MINIO_ROOT_USER: "<пользователь_S3>"
MINIO_ROOT_PASSWORD: "CHANGEME"
AWS_ACCESS_KEY_ID: "<access_key>"
AWS_SECRET_ACCESS_KEY: "CHANGEME"
postgres:
use_external_instance: "true"
manual_set_endpoints:
write_connections:
- host: 10.10.10.247
port: 5000
read_connections:
- host: 10.10.10.247
port: 5000
- host: 10.10.10.247
port: 5001
metrics_connections:
postgres:
- host: 10.10.10.36
script_exporter_metrics_port: 9469
- host: 10.10.10.37
script_exporter_metrics_port: 9469
- host: 10.10.10.38
script_exporter_metrics_port: 9469
postgres_patroni:
- host: 10.10.10.36
metrics_port: 8008
script_exporter_metrics_port: 9469
- host: 10.10.10.37
metrics_port: 8008
script_exporter_metrics_port: 9469
- host: 10.10.10.38
metrics_port: 8008
script_exporter_metrics_port: 9469
postgres_etcd:
- host: 10.10.10.36
metrics_port: 2379
script_exporter_metrics_port: 9469
- host: 10.10.10.37
metrics_port: 2379
script_exporter_metrics_port: 9469
- host: 10.10.10.38
metrics_port: 2379
script_exporter_metrics_port: 9469
postgres_haproxy:
- host: 10.10.10.36
script_exporter_metrics_port: 9469
- host: 10.10.10.37
script_exporter_metrics_port: 9469
- host: 10.10.10.38
script_exporter_metrics_port: 9469
vault:
secret_path:
- postgres
secret_data:
postgres:
PATRONI_SUPERUSER_USERNAME: "<пользователь_PostgreSQL>"
PATRONI_SUPERUSER_PASSWORD: "CHANGEME"
app_username: "<app_username>"
app_password: "CHANGEME"
earth:
config:
app:
frontend_url: "https://logicore.apps.k8s.domain.corp" # Укажите FQDN веб-интерфейса Системы (по умолчанию вычисляется как <namespace>.<доменная зона *.apps>)
clickhouse:
max_execution_time: 3600
max_concurrent_queries_for_user: 40 # Важно! Может потребоваться подбор более оптимального значения параметра под целевое окружение от 40 до 80
max_threads: 4 # Важно! Может потребоваться подбор более оптимального значения параметра в зависимости от нагрузки на CPU узлов Clickhouse
max_memory_usage_for_user: 20615843021 # Важно! Укажите 30% от объема RAM на одном узле ClickHouse (байты)
saturn:
k8s_node_selector:
- k8s-worker-saturn1
- k8s-worker-saturn2
- k8s-worker-saturn3
# При необходимости ограничьте ресурсы Сатурна под целевое окружение (также см. saturn.resources)
#resources:
# saturn:
# limits:
# cpu: ""
# memory: 70Gi
# requests:
# cpu: 7000m
# memory: 64512Mi
manual_set_endpoints:
mpsiem_rabbitmq: "<адрес_rabbitmq_MaxPatrol_SIEM>" # Укажите адрес rabbitmq MaxPatrol SIEM
vault:
secret_data:
saturn:
mpsiem_rabbitmq_username: "<пользователь_rabbitmq>" # можно удалить после первого деплоя
mpsiem_rabbitmq_password: "CHANGEME" # можно удалить после первого деплоя
venus:
manual_set_endpoints:
mpsiem_ptkb: "<адрес_PTKB_MaxPatrol_SIEM>" # Укажите адрес PTKB MaxPatrol SIEM
config:
tables_used: ["all"]
vault:
secret_data:
venus:
mpsiem_ptkb_username: "<пользователь_PTKB>" # можно удалить после первого деплоя
mpsiem_ptkb_password: "CHANGEME" # можно удалить после первого деплоя
mars:
# Важно! Укажите адрес PTKB MaxPatrol SIEM: при значении по умолчанию (127.0.0.1) конвертация правил в сервисе mars-worker работать не будет.
config:
mpsiem_ptkb:
hostname: "<адрес_PTKB_MaxPatrol_SIEM>" # Укажите адрес PTKB MaxPatrol SIEM
#scheme: "https"
#ms_port: 3334
#kb_port: 8091
#timeout: "300s"
#skip_tls_verify: "true"
vault:
secret_data:
mars:
mpsiem_ptkb_username: "<пользователь_PTKB>" # можно удалить после первого деплоя
mpsiem_ptkb_password: "CHANGEME" # можно удалить после первого деплоя
к сведению

При необходимости вы можете поменять формат записи событий. Для этого необходимо установить его значение для параметра taxonomy_format в конфигурационном файле. Для отображения в формате MPSIEM установите значение "mpsiem" (значение по умолчанию), для формата JSON — "json".

внимание

Переключение режима записи событий (значение параметра taxonomy_format) после развертывания стенда недопустимо.

Пример переопределения временных каталогов Ansible​

Во время распаковки крупных архивов (например, aptly или registry) Ansible использует временные каталоги, в которых должно быть достаточно свободного места. Каталог на целевых хостах задается параметром remote_tmp (в дистрибутиве — remote_tmp = /tmp/.ansible-${USER}/tmp в файле /usr/share/lctl/ansible/cfg/ansible.cfg), каталог на управляющем хосте — параметром local_tmp (по умолчанию ~/.ansible/tmp).

Если раздел /tmp имеет недостаточный размер (например, менее 10 ГБ), могут возникать ошибки при выполнении Ansible-задач, связанных с распаковкой крупных архивов. В этом случае переопределите используемые каталоги перед запуском lctl с помощью переменных окружения ANSIBLE_REMOTE_TMP и ANSIBLE_LOCAL_TEMP:

sudo mkdir -p /opt/.ansible/tmp && sudo chown -R ${USER}:${USER} /opt/.ansible
export ANSIBLE_REMOTE_TMP="/opt/.ansible/tmp"
export ANSIBLE_LOCAL_TEMP="/opt/.ansible/tmp"

Важно, чтобы каталоги существовали, а пользователь, под которым запускается Ansible, имел доступ на всех целевых хостах, перечисленных в hosts блоке в /etc/lctl/config.yml, включая control-node.

Запуск процесса подготовки хостов к установке Логикор​

Перед запуском процесса подготовки скопируйте ${HOME}/.kube/config с control-узла платформы (k8s-control) на control-узел Логикор (logicore-control) в ${HOME}/.kube/config (${HOME} — домашний каталог непривилегированного пользователя).

Для того чтобы запустить процесс подготовки хостов к установке Логикор, выполните на control-узле следующую команду:

# опциональный параметр: -f <путь_к_конфигурационному_файлу_Логикор>:
lctl prepare-host
к сведению

Помимо подготовки хостов команда lctl prepare-host устанавливает bash-автодополнение для lctl: в новом терминале после ее выполнения заработает автодополнение команд и компонентов (например, lctl up ea + Tab → earth).

внимание

Перед перезагрузкой узлов Kubernetes приостановите реконсиляцию инфраструктуры на платформе Штурвал. Порядок действий приведен в разделе «Приостановка реконсиляции перед перезагрузкой узлов Kubernetes».

Возобновите реконсиляцию только после того, как все перезагруженные узлы перейдут в состояние Ready.

После подготовки хостов перезагрузите узлы, чтобы применились настройки:

# выполнить на logicore-control для исключения ошибки "error setting rlimit type 6: operation not permitted: unknown" при развертывании registry
sudo reboot

# выполнить на всех узлах k8s-worker-saturn* для применения настроек sysctl
sudo reboot

# дожидаемся поднятия ранее перезагруженных узлов

Процесс установки Логикор​

Установка Логикор запускается из каталога сборки. Для этого на control-узле выполните следующие команды:

Шаг 1. Разверните Docker Registry и Vault:

lctl up registry
lctl up vault

Шаг 2. Разверните PostgreSQL и S3 на выделенных хостах:

В данной лабораторной работе PostgreSQL и S3 разворачиваются вручную на выделенных хостах и подключаются к Системе как внешние сервисы: в конфигурационном файле для них заданы use_external_instance: "true" и адреса в manual_set_endpoints (раздел «Пример конфигурационного файла»). Автоматизированное развертывание этих компонентов средствами lctl в таком варианте не выполняется.

Шаг 3. Разверните bare-metal ClickHouse:

lctl up clickhouse
к сведению

При необходимости вручную измените конфигурационные файлы ClickHouse с учетом особенностей целевой среды.

Важно! Начиная с версии 2.8.0 развертывание ClickHouse и ClickHouse Keeper пропускается на хостах, где эти компоненты уже установлены (проверяется наличие clickhouse-server и clickhouse-keeper). Именно поэтому ручные изменения конфигурационных файлов не перетираются при повторных запусках развертывания.

внимание

Параметр targets_overrides.clickhouse_keeper обязателен: если он не указан, развертывание ClickHouse в формате bare-metal прерывается с ошибкой.

Шаг 4. Создайте секреты PostgreSQL и S3 в Vault:

lctl up postgres s3
к сведению

Для PostgreSQL и S3 в конфигурационном файле задан параметр use_external_instance: "true" — благодаря ему эти компоненты не разворачиваются: развертывание и удаление для них пропускается. Команда lctl up postgres s3 в таком варианте установки только создает их секреты в HashiCorp Vault, а значения берутся из секции vault.secret_data конфигурационного файла /etc/lctl/config.yml (по умолчанию — тестовые значения CHANGEME, замените их на целевые перед выполнением команды).

Если секрет в Vault уже существует, ранее записанные в него значения не перезаписываются — из конфигурационного файла добавляются только отсутствующие ключи.

Шаг 5. Разверните сервисы и мониторинг:

lctl up services
lctl up monitoring

Проверка работоспособности Системы​

Для того чтобы проверить успешность завершения установки Логикор, перейдите в веб-интерфейс управления Системой:

Учетные данные по умолчанию:

  • Логин: admin;
  • Пароль: +L0giCore+.

Также проверьте работоспособность Системы: отправьте тестовые события через ns или loggen и убедитесь, что они поступают в Систему.

Эксплуатация​

Приостановка реконсиляции перед перезагрузкой узлов Kubernetes​

Перед выполнением любых работ, предполагающих перезагрузку узлов Kubernetes, а также при аварийных ситуациях, приводящих к их временной недоступности, необходимо приостановить реконсиляцию инфраструктуры.

Это необходимо, поскольку если узел остается недоступным более 10 минут, платформа Штурвал может считать узел потерянным и удалить его из состава кластера. После восстановления связи узел будет автоматически переустановлен, что существенно увеличит время восстановления работоспособности.

Порядок действий​

  1. Откройте в веб-интерфейсе системы управления страницу «Дашборд кластера»:

    https://shturval.apps.k8s.domain.corp/clusters/mgmt-shturval/nodes-management

  2. Пролистайте страницу до раздела «Реконсиляция инфраструктуры».

  3. Нажмите кнопку «Приостановить».

  4. Выполните необходимые работы на узлах (например, их перезагрузку).

  5. Дождитесь, пока все перезагруженные узлы перейдут в состояние Ready (статус можно проверить на странице «Управление узлами» или с помощью kubectl get nodes):

    https://shturval.apps.k8s.domain.corp/clusters/mgmt-shturval/nodes-management

  6. После того как все узлы станут доступны и перейдут в состояние Ready, вернитесь в раздел «Реконсиляция инфраструктуры» и возобновите реконсиляцию.

Когда необходимо выполнять данную процедуру​

  • плановые работы, требующие перезагрузки одного или нескольких узлов Kubernetes;
  • обновление ядра или операционной системы;
  • изменение системных настроек, требующее перезагрузки;
  • аварийные ситуации, при которых ожидается временная недоступность узлов более нескольких минут.
внимание

Важно: не возобновляйте реконсиляцию до тех пор, пока все перезагруженные узлы не восстановят работоспособность и не перейдут в состояние Ready.

Восстановление taint и label на выделенных узлах K8s для размещения Saturn​

Если по какой-то причине выделенный узел K8s для размещения Saturn был пересоздан платформой Штурвал, то необходимо выполнить одно из двух:

  • выполнить повторное развертывание Saturn с помощью lctl, что нежелательно, т.к. приведет к последовательному перезапуску всех подов Saturn;
  • вручную восстановить taint и label на узлах Saturn, где они были потеряны из-за повторного добавления в кластер.
внимание

Важно: если не выполнить данное восстановление taint и label, то DaemonSet не сможет развернуть под Saturn на этом узле.

Ручное восстановление taint и label​

kubectl taint nodes <node-name> dedicated=logicore:NoSchedule
kubectl label node <node-name> dedicated-saturn-logicore=true

Справка об использовании скрипта развертывания Логикор​

Справка об использовании скрипта развертывания LogICore

Команды:
prepare-host Подготовить хосты и окружение к развертыванию или обновлению LogICore
Использование: lctl prepare-host [--ansible-tags <tag1,tag2,...>]
Опциональные параметры:
--ansible-tags <tag1,tag2,...> Указать теги для запуска определенных задач Ansible. Если параметр не указан, то по умолчанию указываются все доступные Ansible теги
Доступные Ansible теги:
security_disable,set_sysctl,init_aptly,os_packages_install,docker_install,hosts_file

deploy|uninstall Развернуть/обновить или удалить компоненты LogICore
Использование: lctl <deploy|uninstall> <module|service>… [-f </conf/path>]
Пример: lctl deploy earth,venus | lctl uninstall --components all

up|down Короткие алиасы: up = deploy, down = uninstall
Использование: lctl up <module|service>… [-f </conf/path>]
lctl down <module|service>… [-f </conf/path>]
Пример: lctl up earth mars | lctl up (без списка = все компоненты)

ls Список доступных модулей и сервисов

Список компонентов — один и тот же для deploy|uninstall|up|down, предпочтителен следующий формат:
lctl up earth mars
Разделители — запятая и/или пробел, регистр не важен, дубли отбрасываются; all — все модули.
Совместимый формат: --components earth,mars.

generate-helm-charts Сгенерировать Helm-чарты из Ansible-шаблонов без деплоя в Kubernetes
Использование: lctl generate-helm-charts [-f </conf/path>]
Результат: готовые чарты (values.yaml, files/, Chart.yaml, templates/) для ручного развертывания через helm
Документация: /usr/share/lctl/docs/vanilla-k8s/manual-deployment-in-k8s.md

ansible Прямой вызов ansible, путь к инвентарю необходимо передать через -f </conf/path> или создать его по пути /etc/lctl/config.yml
Использование: lctl ansible <ansible commands and flags>

ansible-playbook Прямой вызов ansible-playbook, путь к инвентарю необходимо передать через -f </conf/path> или создать его по пути /etc/lctl/config.yml
Использование: lctl ansible-playbook <ansible-playbook commands and flags>

get-config Вывести текущую полную конфигурацию LogICore
Использование: lctl get-config

get-example-conf Вывести пример конфигурационного файла LogICore
Использование: lctl get-example-conf

completion [bash|install] Автодополнение bash (самообновляемое)
Установка (один раз): lctl completion install # стаб в /etc/bash_completion.d (нужен sudo)
lctl completion install --user # без sudo, только своему пользователю (~/.bashrc)
Стаб генерирует дополнение из установленного lctl при старте шелла — файл не отстает от версии lctl.
На стенде ставится автоматически при 'lctl prepare-host'.
Новые терминалы подхватывают его сами; в текущем: source /etc/bash_completion.d/lctl (или exec bash).
Печать самого скрипта (просмотр/ручная установка): lctl completion bash
Работает и при запуске по пути (./bin/lctl): спеку bash ищет по имени команды, компоненты берутся из набранного бинарника.
Проверка: набрать 'lctl up ea' и нажать Tab — подставится 'earth'.

Вывести значение Vault Root Token:
Использование: lctl ansible-playbook ./ansible/playbooks/mgmt/get_hashi_vault_token.yml

Ограничение целевых узлов выполнения Ansible:
Использование: lctl deploy --components services --ansible-opts '--limit control-node,app1-node'
Обязательное условие: в параметре --limit всегда должен быть указан узел control-node

Дополнительные флаги:
-f </conf/path> Путь к конфигурационному файлу LogICore. Если параметр не указан, то по умолчанию используется /etc/lctl/config.yml
--ansible-opts '<--param1 --param2 -P3>' Дополнительные параметры Ansible, например, '-diff --check --list-tasks --limit'
--plan|--dry-run Показать состав, порядок работ и команды Ansible без запуска (deploy|uninstall|up|down)
-h|--help|help Вывести эту справку
-v|--version|version Вывести версию LogICore

Список доступных модулей и сервисов LogICore:
registry: registry
tools: portainer,vault
storage: clickhouse,s3,postgres,mpsiem_rabbitmq
external: openldap,mailhog
services: earth,apigw,docs,mercury,mars,saturn,venus
monitoring: prometheus,victoriametrics,grafana,traefik,cadvisor,docket-proxy,script-exporter,saturn-metrics-exporter,php-fpm-exporter

Для выбора всех вышеперечисленных модулей укажите: all

FAQ​

Что такое control-сервер?​

Control-сервер — это хост, с которого вы запускаете lctl и инструменты Ansible CLI (ansible-playbook, ansible, ansible-vault и другие).

В конфигурационном файле Логикор control-сервер описан как хост control-node с типом подключения local: этот узел всегда должен быть указан в секции hosts, а при ограничении целевых узлов через --ansible-opts '--limit …' — и в списке --limit.

Вы можете использовать любой компьютер, который соответствует требованиям к программному обеспечению, в качестве control-сервера: например, ноутбук с Ubuntu/Debian (или Windows с WSL2), виртуальную машину с Ubuntu/Debian. Вы также можете запускать Ansible в контейнерах, известных как Execution Environments.

Что такое managed-серверы?​

Managed-серверы — это целевые хосты, которыми вы собираетесь управлять с помощью Ansible и на которые планируется развертывание компонентов Логикор.

Как указать компоненты при развертывании или остановке Логикор?​

Компоненты перечисляются позиционно в командах lctl up (развернуть/обновить) и lctl down (остановить): lctl up vault services, lctl down vault services. Разделители — запятая и/или пробел, регистр не важен, дубли отбрасываются, all — все модули. Если список не указан, команда lctl up развернет все компоненты Логикор, а для lctl down список обязателен (защита от остановки всего стенда). Команды up и down — короткие алиасы команд deploy и uninstall; совместимый формат — lctl deploy --components vault,services. Подробнее описано в справке lctl --help.

Как посмотреть список доступных модулей и сервисов?​

Выполните команду lctl ls — она выведет модули, входящие в них сервисы и примеры команд. Машиночитаемый список (по одному компоненту на строку) — lctl ls --plain.

Как изменить конфигурацию Логикор при развертывании?​

Конфигурация Логикор описывается в конфигурационном файле, представляющем собой Ansible Inventory-файл. Путь к файлу указывается флагом -f </conf/path> (если параметр не указан, используется /etc/lctl/config.yml). В каталоге /usr/share/lctl/ansible/inventories/presets хранятся пресеты для различных конфигураций Логикор, которые можно использовать как есть для развертывания Логикор или для клонирования одного из пресетов с последующей перенастройкой Логикор под специфичные условия и окружение.

Как остановить работу служб?​

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

lctl down <список_служб_и/или_модулей> -f <путь_к_конфигурационному_файлу_Логикор>

Как проверить, что узлы платформы готовы к работам с перезагрузкой?​

Перед перезагрузкой узлов Kubernetes приостановите реконсиляцию инфраструктуры на платформе Штурвал и возобновите ее только после того, как все перезагруженные узлы перейдут в состояние Ready (раздел «Приостановка реконсиляции перед перезагрузкой узлов Kubernetes»).

Что делать, если выделенный узел K8s для размещения Saturn был пересоздан платформой?​

Восстановите taint и label на этом узле вручную (раздел «Восстановление taint и label на выделенных узлах K8s для размещения Saturn») либо выполните повторное развертывание Saturn с помощью lctl.

В каком namespace кластера разворачивается Система и можно ли его переопределить?​

По умолчанию Система разворачивается в namespace, совпадающем с runtime_id продукта: для чистой установки это logicore, для обновляемого legacy-стенда — logiq. Переопределить namespace можно параметром k8s_target_namespace_env в секции variables_overrides конфигурационного файла. Namespace создается автоматически — с аннотацией shturval.tech/system-namespace.

Можно ли развернуть Систему в произвольный кластер Kubernetes, а не в платформу Штурвал?​

Да. Команда lctl generate-helm-charts формирует Helm-чарты из Ansible-шаблонов без развертывания в кластер: готовые чарты (values.yaml, Chart.yaml, templates/, files/) складываются в каталог из параметра helm_charts_output_dir, после чего их можно развернуть вручную через helm. Порядок ручного развертывания описан в документе /usr/share/lctl/docs/vanilla-k8s/manual-deployment-in-k8s.md.

Обязательно ли выделять отдельные узлы под Saturn?​

Для продуктивной среды обязательно. Для тестовой среды — нет. По умолчанию saturn.k8s_node_selector пуст, и поды Saturn планируются стандартными средствами Kubernetes. Выделенные узлы (как в примере конфигурационного файла) дают изоляцию нагрузки Saturn и предсказуемые ресурсы; чтобы их задействовать, перечислите узлы в saturn.k8s_node_selector.

Зачем на узлах под Saturn появляются taint и label и почему их восстанавливают вручную?​

При развертывании lctl сам помечает узлы из saturn.k8s_node_selector: label dedicated-saturn-<namespace>=true и taint dedicated=<runtime_id>:NoSchedule. Label нужен, чтобы DaemonSet Saturn разворачивал под на этих узлах, taint — чтобы на выделенные узлы не планировалась другая нагрузка кластера. Если узел был пересоздан платформой, метки теряются — их восстанавливают вручную (раздел «Восстановление taint и label на выделенных узлах K8s для размещения Saturn») или выполняют повторное развертывание Saturn с помощью lctl.

Что делать, если Saturn не хватает ресурсов?​

Увеличьте ресурсы с помощью параметров конфигурационного файла saturn.resources.saturn.requests и saturn.resources.saturn.limits (cpu, memory). Эти значения передаются в блок resources подов Saturn.

При необходимости также измените параметры JVM: saturn.config.jvm_xms, jvm_xmx и jvm_xss, которые передаются в LS_JAVA_OPTS.

Заготовка этих настроек приведена в разделе «Пример конфигурационного файла» и закомментирована.

Как посмотреть, что развернуто в кластере, и состояние подов Системы?​

Выполните на control-узле Логикор (logicore-control) команду:

kubectl -n <namespace> get pods

kubeconfig для доступа к кластеру размещен на этом же узле — он используется и при развертывании (параметр k8s_kubeconfig_path). Состояние кластера и его узлов также отображается в веб-интерфейсе платформы Штурвал.

Как удалить Систему из кластера?​

Командой lctl down с обязательным списком компонентов. В варианте развертывания через helm при этом удаляются объекты Системы из кластера (релизы снимаются через helm uninstall); узлы кластера и сама платформа Штурвал не затрагиваются.

Что делать, если узел кластера недоступен дольше 10 минут?​

Если узел остается недоступным более 10 минут, платформа Штурвал может считать его потерянным и удалить из состава кластера, после чего узел будет переустановлен, — это существенно увеличит время восстановления работоспособности. Перед работами с перезагрузкой узлов приостановите реконсиляцию инфраструктуры (раздел «Приостановка реконсиляции перед перезагрузкой узлов Kubernetes») и возобновите ее только после того, как узлы вернутся в состояние Ready.

Как проверить, что стенд готов принимать данные после развертывания?​

Проверьте, что все узлы кластера находятся в состоянии Ready (kubectl get nodes или страница «Управление узлами» в интерфейсе платформы) и что реконсиляция инфраструктуры возобновлена. Затем проверьте Систему по разделу «Проверка работоспособности Системы»: доступность веб-интерфейса, успешный сбор метрик со всех настроенных целей, дашборд здоровья Системы и поступление тестовых событий.