Управление конфигурацией
Кластер ORDERS работает в Kubernetes на nats-0, nats-1, nats-2. Неизбежно потребуется повысить ограничение учётной записи, заменить сертификат TLS или добавить пользователя сервиса. Вместо перезапуска можно перечитать конфигурацию: применить её к работающему серверу без разрыва соединений.
Безопасное изменение обеспечивают два механизма. Включаемые файлы делят большую конфигурацию на части с отдельными владельцами для учётных записей и регионов. Перечитывание без остановки применяет проверенный файл через SIGHUP. Так ограничения order-svc и сертификаты кластера меняются, пока ORDERS продолжает работать.
Включаемые файлы разделяют конфигурацию
Общий nats.conf рабочего кластера быстро растёт. Учётные записи, пользователи, региональные маршруты, TLS и ограничения JetStream в одном файле усложняют проверку и разделение ответственности.
Директива включения вставляет другой файл в указанное место. Ключевое слово — include, путь считается от каталога содержащего директиву файла, а не от рабочего каталога запуска сервера:
# /etc/nats-config/nats.conf — the main config for nats-0..2
# The Helm chart generates the identity keys — server_name and the cluster
# routes — uniquely per pod. You own the includes below.
server_name: $SERVER_NAME
listen: "0.0.0.0:4222"
cluster {
name: "east"
listen: "0.0.0.0:6222"
routes: [
"nats://nats-0.nats-headless:6222"
"nats://nats-1.nats-headless:6222"
"nats://nats-2.nats-headless:6222"
]
}
jetstream {
store_dir: "/data/jetstream"
}
# Pull in the shared TLS material and the per-region routing files.
include "tls.conf"
include "regions/us.conf"
include "regions/eu.conf"
Кластер JetStream не запустится без server_name и routes; чарт заполняет их отдельно для каждого пода. Пробная проверка может признать синтаксис корректным даже без возможности запуска (см. Проверка перед перечитыванием). Региональные файлы хранят принадлежащие региону маршруты: их можно проверять и менять независимо от главного файла и других регионов.
include "regions/us.conf" разрешается как /etc/nats-config/regions/us.conf. Запуск из /root или / ничего не меняет. Последствия неверного понимания этого правила разобраны в типичных ошибках.
Учётную запись можно вынести аналогично. Здесь оператор ACME хранит записи как JWT в resolver: они меняются через nats account edit и передаются серверу, а не включаются конфигурацией. Если записи хранятся в конфигурации, оберните каждую в блок accounts, чтобы сервер её разобрал:
# /etc/nats-config/accounts/orders.conf — config-based accounts (no operator)
# Reloadable: edit and SIGHUP.
accounts {
ORDERS: {
jetstream: { max_memory: 256MB, max_file: 10GB }
users: [
{ user: "order-svc", password: $ORDER_SVC_PASS }
]
}
}
$ORDER_SVC_PASS намеренно не заключён в кавычки. Токен $NAME без кавычек сначала ищет переменную конфигурации, затем окружения; отсутствие значения даёт ошибку разбора, обнаруживаемую пробной проверкой. "$ORDER_SVC_PASS" сохранило бы буквальную строку $ORDER_SVC_PASS. Поэтому хеши bcrypt, содержащие $, наоборот, нужно заключать в кавычки.
Перечитываемые и неперечитываемые параметры
Не все настройки можно менять на работающем сервере. Это определяет, достаточно ли перечитывания или потребуется перезапуск.
Перечитываемые параметры применяются на месте без переподключения:
- Учётные записи, пользователи и права: добавление
analytics-reader, сужение темorder-svc. - Ограничения соединений и сообщений:
max_connections,max_payload,max_control_line. Изменениеmax_subscriptionsперечитывание отклоняет. - Большинство ограничений учётных записей JetStream и сам флаг
jetstream: перечитывание включает или отключает JetStream. - Пути сертификатов и ключей TLS: сервер заново читает файлы.
- Маршруты кластера и журналирование. Маршруты шлюзов не перечитываются; для них можно только обновить TLS.
Неперечитываемые параметры требуют перезапуска, поскольку определяют идентичность сервера:
port/listen: адрес прослушивания сервера.- Адрес и порт слушателя кластера.
store_dirJetStream: сервер не переносит хранилище при перечитывании.
Перечитывание меняет политику: кто подключается, что делает и сколько хранит. Оно не меняет идентичность: адреса прослушивания и расположение данных. Для них нужен последовательный перезапуск.
Полный набор перечитываемых параметров находится в Справочнике → Конфигурация. Здесь рассмотрены необходимые нашему кластеру.
Проверка перед перечитыванием
NATS сначала проверяет новую конфигурацию. При ошибке разбора или проверки старая остаётся активной. Операция атомарна: либо новая конфигурация применяется целиком, либо ничего не меняется.
Тем не менее проверяйте файл до отправки сигнала: лучше увидеть опечатку в терминале, чем в журнале сервера. Пробный запуск разбирает файл и завершается, не запуская сервер:
nats-server -c /etc/nats/nats.conf -t
Корректный файл даёт nats-server: configuration file ... is valid и код 0. Некорректный — сообщение с проблемной строкой и ненулевой код, по которому можно разрешать дальнейший шаг в скрипте. Проверяется синтаксис и допустимость, но не фактическая возможность запуска: конфигурация кластера JetStream без server_name или routes проходит -t, но не стартует. Эти поля добавляет чарт.
После проверки отправьте SIGHUP процессу nats-server. Модуль systemd связывает с этим сигналом systemctl reload:
# Validate the edited config, then reload only if it is valid.
nats-server -c /etc/nats/nats.conf -t && systemctl reload nats-server
Сервер перечитывает файл, применяет допустимые изменения и пишет Reloaded server configuration. Открытые соединения, включая order-svc, продолжают работать без переподключения.
Вспомогательный контейнер перечитывания в Kubernetes
В Kubernetes нет systemctl reload. Конфигурация приходит из ConfigMap, смонтированного в под. Правка обновляет файл на диске, но сама не сообщает nats-server, что его нужно прочитать снова.
Это делает вспомогательный контейнер перечитывания. Он работает рядом с nats-server в каждом nats-0..2, следит за файлом через inotify, при изменении читает PID из /var/run/nats/nats.pid и отправляет SIGHUP. Чарт включает его по умолчанию, поэтому правка ConfigMap автоматически применяется на всех трёх подах:
# values.yaml — the reloader ships enabled in the Helm chart
reloader:
enabled: true
Анимация показывает весь путь: изменение файла, обнаружение контейнером, SIGHUP, применение на месте. Соединение order-svc остаётся открытым, пока соседи получают новые сведения о сервере.
При краткой недоступности сервера контейнер повторяет попытки: по умолчанию 30 раз с интервалом четыре секунды. Если файловая система не выдаёт inotify-события, добавьте --force-poll через reloader.merge; при этом список аргументов контейнера заменяется целиком.
Секреты как смонтированные файлы
Учётным данным и материалам TLS не место в тексте конфигурации. Их подключают файлами: Kubernetes Secret, спроецированный в под, или файл учётных данных на диске для systemd. Конфигурация содержит путь, сам секрет находится вне ConfigMap.
# A TLS path the config points at — the file itself is a mounted secret.
tls {
cert_file: "/etc/nats-certs/server-cert.pem"
key_file: "/etc/nats-certs/server-key.pem"
ca_file: "/etc/nats-certs/ca.pem"
}
Это важно для замены сертификатов. Замените файлы по cert_file и key_file, затем перечитайте конфигурацию. Новые соединения получат новый сертификат, уже открытые сохранят сессию. Текст конфигурации может не меняться — только указанный файл. Модель операторов, учётных записей и JWT объясняется в Безопасности; здесь мы подключаем файлы и задаём пути.
Типичные ошибки
Несколько ошибок превращают обычное перечитывание в простой. Они относятся к включаемым файлам и применению без остановки.
Пути include считаются от конфигурации, а не оболочки. include "regions/us.conf" разрешается по каталогу содержащего файла. Запуски из /root и /etc/nats-config находят один /etc/nats-config/regions/us.conf. Ловушка — перенести главный файл, ожидая разрешения от рабочего каталога. При сомнениях используйте абсолютные пути и проверяйте конфигурацию.
Перечитывание во время перераспределения может прервать передачу лидерства. SIGHUP конкурирует с перемещением реплик ORDERS и передачей Raft-лидерства. Дождитесь стабильного состояния кластера, затем меняйте настройки. На таком же безопасном окне построены последовательные обновления.
Уменьшение лимита не удаляет уже сохранённые данные. Если max_file учётной записи ORDERS станет меньше текущего объёма, сообщения останутся, но новые записи будут отклоняться, пока администратор не сократит поток. Меняется предел, а не содержимое. Перед уменьшением проверяйте объём.
Поздняя замена сертификата нарушает новые TLS-соединения. Сервер перечитывает cert_file и key_file, а открытые соединения сохраняют согласованные сессии независимо от истечения прежнего сертификата. Но после истечения новые подключения и переподключения не проходят TLS до установки действительного файла и перечитывания.
Заменяйте сертификаты заранее и отслеживайте срок действия, не дожидаясь оповещения об истечении. Модель сертификатов разобрана в Безопасности; эксплуатационное правило простое: заменить файл, перечитать и оставить запас времени.
Общий первый шаг: никогда не отправляйте SIGHUP с непроверенной конфигурацией. Пробный запуск не трогает работающий сервер. Сделайте его условием перечитывания:
# Validate first; only signal the running server if the config is valid.
if nats-server -c /etc/nats/nats.conf -t; then
systemctl reload nats-server
echo "reload sent"
else
echo "config invalid — running server left untouched" >&2
exit 1
fi
Сервер также проверяет файл сам и оставляет старую конфигурацию при ошибке. Поэтому даже пропущенная предварительной проверкой проблема не даст частично применённого состояния: изменение просто не вступит в силу.
Что уже готово
Конфигурация ORDERS разделена по учётным записям и регионам с отдельными владельцами. Вы умеете менять ограничения, пользователей и сертификаты, проверять файл и применять через SIGHUP без простоя и переподключений. В Kubernetes сигнал отправляет вспомогательный контейнер при изменении ConfigMap.
Перечитывание не меняет адреса, порты и расположение данных JetStream. Для этого требуется перезапуск процесса, последовательно по одному узлу.
Что дальше
Такой управляемый перезапуск — последовательное обновление. Режим плавного вывода освобождает узел, передаёт лидерство Raft и позволяет новой версии занять его место, пока поток R3 ORDERS остаётся доступным.
Перейдите к последовательным обновлениям.
См. также
- Справочник → Конфигурация — все перечитываемые и неперечитываемые параметры.
- Последовательные обновления — процедура для изменений, недоступных через SIGHUP.
- Безопасность — модель учётных данных, подключаемых файлами.