Документация / Конфигурация
Конфигурация платформы
Для администратораПеред развертыванием и при каждом изменении
Вся платформа описана одним документом. В нем записано, сколько экземпляров у каждого сервиса, сколько им дано памяти, какие базы данных подняты, что уходит наружу и что хранится. Платформа собирает по этому документу свою конфигурацию сама, поэтому изменение на работающей платформе начинается с правки документа, а не сервера.
Термин страницы. Этот документ называется описателем платформы. Он состоит из трех файлов, которые складываются в один. Два приезжают в поставке, третий пишете вы.
Три слоя описателя
Слои идут снизу вверх. Верхний перекрывает нижний, и только верхний принадлежит вам.
Состав сервисов, их проверки состояния, зависимости и значения по умолчанию. Приезжает в поставке и соответствует версии платформы. Правке не подлежит.
Один из трех. Показной профиль ставится на один сервер для оценки. Промышленный поднимает несколько экземпляров сервисов, репликацию баз данных и полные резервные копии. Закрытый профиль делает то же самое, но разрешить в нем выход в интернет нельзя.
Числа и адреса вашей компании. Сколько памяти дать сервису, какие поставщики языковых моделей разрешены, к каким внешним адресам платформа обращается, расписание резервных копий, сроки хранения данных. Единственный слой, который вы ведете сами.
Чем отличаются три профиля
Профиль выбирается один раз и задает поведение целых разделов. Различия между ними не косметические.
| Что задает профиль | Показной | Промышленный | Закрытый |
|---|---|---|---|
| Экземпляров у ядра и обработки | Один | Два | Два |
| Обмен событиями внутри платформы | Внутри процесса | Через отдельное хранилище | Через отдельное хранилище |
| Базы данных | По одному экземпляру | С запасной копией | С запасной копией |
| Сертификат периметра | Самоподписанный | Ваш, из секретов | Ваш, из секретов |
| Отправка телеметрии наружу | Разрешена настройкой | Разрешена настройкой | Выключена и включить нельзя |
| Выход в интернет | Разрешен | Разрешен объявленным адресам | Невыразим, валидатор отклонит |
Показной профиль ставится на один сервер для оценки, и перерыв в работе при обновлении в нем неизбежен, потому что заменять нечему. Промышленный и закрытый отличаются не составом, а тем, что в закрытом часть настроек становится невыразимой, а не просто нежелательной.
Как слои складываются
Правила слияния заданы жестко, чтобы результат не зависел от порядка чтения файлов.
- Разделы складываются вглубь. Если вы задали в своем слое только память сервиса, все остальные его свойства берутся из нижних слоев.
- Списки записей с именами складываются по имени. Запись с тем же именем заменяет поля нижнего слоя, а запись с новым именем добавляется к ним.
- Простые значения и списки без имен заменяются целиком.
- Пустое значение в верхнем слое удаляет ключ нижнего.
Проверяется не ваш файл, а итог сложения всех трех. Поэтому ошибка вида «мой файл маленький и очевидно правильный» находится там, где она проявляется (в готовом описании), а не там, где написана.
Из чего состоит описатель
| Раздел | Что задает | Кто обычно правит |
|---|---|---|
installation | Профиль, канал обновлений, сроки хранения служебных журналов | Вы |
services | Сервисы платформы, число экземпляров, память и ядра, проверки состояния | Вы, числами |
events | Как сервисы обмениваются событиями внутри платформы | Профиль |
models | Классы языковых моделей и их сопоставление поставщикам | Вы |
databases | PostgreSQL, ClickHouse, Redis и их режим отказоустойчивости | Профиль, вы уточняете |
storage | Тома данных и объектное хранилище | Вы, размерами |
network | Сегменты сети платформы | Профиль |
perimeter | Что публикуется наружу, сертификаты, правила доступности адресов | Вы |
egress | К каким внешним адресам платформе разрешено обращаться и какому сервису | Вы |
secrets | Имена секретов и откуда они берутся. Значений здесь нет | Вы |
backup | Расписание резервных копий, шифрование, сколько копий хранить | Вы |
monitoring | Сбор метрик, срок их хранения, пороги оповещений | Вы |
Чего в описателе нет намеренно
Настройки среды исполнения контейнеров в описателе выразить нельзя, платформа отвергает такие ключи отдельным сообщением. Причина в том, что описатель обязан оставаться одинаковым для разных способов развертывания, а прямая вставка настроек привязала бы платформу к одному из них.
Секреты
В описателе стоят имена секретов и то, откуда они берутся. Значений в описателе нет и быть не может, иначе он не мог бы лежать в вашей системе контроля версий.
| Откуда берется | Что это значит | Пример |
|---|---|---|
| Платформа сгенерирует | Значение рождается при развертывании и лежит в каталоге секретов платформы | Пароли баз данных, ключи обезличивания |
| Принесете вы | Платформа ждет готовое значение и без него не поднимется | Сертификат периметра, ключи поставщиков моделей, пароль почтового ящика |
| Пара ключей | Платформа заводит закрытую и открытую половины, у каждой свои потребители | Подпись квитанций обезличивания |
У каждого секрета перечислены потребители, то есть какие сервисы его читают. Секрет без потребителей валидатор отклоняет, потому что он означает либо забытую правку, либо лишний секрет на диске.
Каталог секретов принадлежит владельцу платформы и закрыт правами. Копируется он отдельно от резервных копий платформы, вашими средствами, и про это стоит прочитать на странице резервных копий.
Что проверяет валидатор описателя
Кроме схемы, у описателя есть смысловые правила, и их около семидесяти. Считать их наизусть не нужно, важно понимать, какого рода ошибки они ловят.
| Класс правила | Что ловит | Пример |
|---|---|---|
| Ссылки в никуда | Имя, которого нет | Сервис зависит от несуществующего, том или секрет не объявлены, поставщик модели не назван |
| Половина решения | Одна часть включена, вторая забыта | Прогонный контур включен флагом, а сервиса нет. Или класс модели объявлен без развертываний |
| Противоречие профилю | Настройка, несовместимая с выбранным профилем | Самоподписанный сертификат в промышленном профиле, выход в интернет в закрытом, логический дамп базы в промышленном |
| Опасная сеть | Настройка, открывающая больше, чем нужно | Публичный домен объявлен внутренним, перекрывающиеся маршруты периметра, открытый корень периметра |
| Несходящиеся числа | Значения, противоречащие друг другу | Несколько экземпляров ядра при обмене событиями внутри процесса, отсрочка меньше окна резервной копии |
Сообщение правила устроено одинаково. В квадратных скобках стоит код, дальше путь в описателе и объяснение. По коду правило ищется в документации поставки, а по пути находится место в вашем файле.
Поколение конфигурации
У собранной конфигурации есть номер поколения. Он растет с каждой пересборкой и нужен затем, чтобы отличать «сервис работает на свежей конфигурации» от «сервис поднялся на прошлой и не перечитал новую».
Практическое следствие такое. Если правка описателя не проявилась, первым делом смотрят, дошло ли новое поколение до сервиса, а не ищут ошибку в самой правке.
Что нельзя поменять на ходу
Часть настроек применяется пересборкой и перезапуском, а часть требует большего. Различать их стоит заранее, чтобы не планировать правку на рабочее время.
- Меняется пересборкой и перезапуском сервиса. Память и ядра, пороги оповещений, расписание копий, поставщики моделей, пределы расхода.
- Требует обновления с планом. Состав сервисов, режим отказоустойчивости баз, профиль платформы.
- Не меняется с экрана вовсе. Ничего из перечисленного.
Почему собранные файлы не правят руками
Файлы, которые платформа собрала из описателя, руками не редактируются. Такую правку платформа называет правкой в обход описателя и находит ее отдельной проверкой. Пока правка не принята явной командой, обновление и откат не выполняются.
Причина запрета простая. Обновление собирает конфигурацию заново, поэтому правка, сделанная руками в собранном файле, при следующем обновлении пропадет. Проверка на такие правки нужна для того, чтобы вместе с правкой не пропала причина, по которой ее сделали.
Изменение вносится в таком порядке.
- Правите свой слой описателя.
- Собираете конфигурацию заново.
- Проверяете готовность.
- Применяете обновление.
Экран конфигурации
Действующую конфигурацию видно в интерфейсе. Разделы свернуты, у каждого стоит имя, пояснение и число параметров, рядом кнопка копирования. Секретные значения замаскированы платформой, то есть в браузер они не попадают вовсе. Экран только показывает, менять конфигурацию с него нельзя, и это осознанное ограничение. Менять платформу можно одним способом, через описатель.
