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

Управление конфигурацией

Кластер 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_dir JetStream: сервер не переносит хранилище при перечитывании.

Перечитывание меняет политику: кто подключается, что делает и сколько хранит. Оно не меняет идентичность: адреса прослушивания и расположение данных. Для них нужен последовательный перезапуск.

Полный набор перечитываемых параметров находится в Справочнике → Конфигурация. Здесь рассмотрены необходимые нашему кластеру.

Проверка перед перечитыванием​

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 остаётся доступным.

Перейдите к последовательным обновлениям.

См. также​