Домены, Routes и TLS

Для управляемого DNS Cloudflare сначала настройте интеграцию Cloudflare, затем выбирайте зоны и создавайте записи доменов. DNS-коннектор не заменяет входящую ноду и её настройки TLS.

Эта цепочка ресурсов превращает приложение в стабильный публичный адрес. Domain представляет имя хоста и место его обслуживания, Route определяет действие Opfield для подходящих запросов, а TLS-сертификат подтверждает имя хоста клиентам HTTPS. Результат — один ответственный владелец имени хоста, зашифрованный трафик, явно выбранная целевая служба и проверяемый путь отката.

До настройки определите, кто отвечает за DNS, продление сертификата, состояние приложения и переключение рабочей среды. Opfield координирует эти ресурсы и поддерживаемые действия поставщика, но внешний DNS и готовность приложения остаются вне его контроля, если ими явно не управляет интеграция.

Настройка успешна, когда каноническое имя хоста разрешается в адрес нужной ноды Ingress, HTTPS показывает ожидаемый сертификат, Route достигает нужного приложения, а состояние в Opfield совпадает с результатом независимого внешнего запроса.

Ресурсы Domain

Зарегистрируйте каждое имя хоста один раз и назначьте его подходящей ноде nginx с обнаруженным публичным служебным адресом. Route и его Domain должны находиться на одной ноде. Для ресурсов Domain, которыми управляет Cloudflare, Opfield может согласовывать записи A/AAAA; за внешний DNS отвечает оператор. Открытие Domain только читает его записи DNS; записи в Cloudflare Opfield исправляет только по вашему запросу.

В API и MCP параметр nginxNodeId можно не указывать, если праву domains:create вызывающего доступна ровно одна подходящая нода с обнаруженным публичным адресом. Иначе запрос завершается ошибкой 409 DOMAIN_NGINX_NODE_REQUIRED со списком подходящих нод. GET /api/domains/nginx-nodes или операция list_nginx_nodes инструмента manage_domain в MCP показывает их любому обладателю domains:create; права на ноды не нужны.

Сертификаты

Выпустите сертификат Let’s Encrypt через HTTP-01 или DNS-01 либо загрузите существующий сертификат. Для HTTP-01 назначенная нода должна быть доступна из публичной сети по порту 80. Opfield передаёт закрытый ключ только тем нодам, где включены использующие его TLS Routes.

Ресурсы Route

Выберите Domain, поведение, целевую службу, TLS-сертификат и политику состояния. Включайте WebSockets, правила переписывания, заголовки, буферизацию и изменённые тайм-ауты только тогда, когда они нужны приложению.

Нода Ingress отвечает по TLS только для имён, которые обслуживает один из её Routes. Запрос TLS для любого другого имени отклоняется на этапе рукопожатия, а не получает сертификат и сайт другого Route. Обновление демона добавляет это на существующих нодах; если собственный nginx ноды уже задаёт сервер по умолчанию на порту 443, обновление пропускает этот шаг и пишет предупреждение в журнал. Когда nginx отклоняет изменение конфигурации, изменение завершается ошибкой 422 NGINX_CONFIG_FAILED — одинаково для HTTP- и HTTPS-Routes, — а текст ошибки содержит вывод nginx -t; нода сохраняет прежнюю конфигурацию. Route без проверок состояния помечается No health check.

Raw Config Mode передаёт вам всю конфигурацию nginx для Route. Она начинается с отрисованной конфигурации, и Opfield перестаёт отрисовывать Route, пока исходный режим не выключен. Route к рабочей нагрузке Docker сохраняет в этом режиме свой Secure Link: подставленный upstream — сокет привязки на ноде Ingress — по-прежнему ведёт к рабочей нагрузке и следует за ней при пересоздании контейнера, поэтому меняйте конфигурацию как нужно, но продолжайте проксировать на этот upstream. Исходная конфигурация, содержимое шаблонов nginx и расширенная конфигурация Additional Routes проходят одни и те же проверки директив: без proxy:unrestricted запрещённые директивы отклоняются, а журналы nginx можно писать только в /var/log/nginx.

Два включённых Routes на одной ноде не могут обслуживать одно и то же имя: nginx обслуживал бы только один из них. Создание, включение или изменение Route, а также его перенос на другую ноду, после которых он обслуживал бы имя, уже обслуживаемое другим включённым Route на этой ноде, завершается ошибкой 409 PROXY_HOST_DOMAIN_CONFLICT с указанием другого Route. Имена сравниваются без учёта регистра. Routes, которые пересекались ещё до обновления до 2.11, сохраняют свою конфигурацию; см. «Конфликты, разрешённые при обновлении до 2.11».

Выбор ноды Ingress

Route работает на одной ноде nginx Ingress или на каждом участнике группы Ingress. В диалоге Create Route выбор зарегистрированного Domain подставляет его ноду. Пользователи, которые могут создавать Routes в общем виде или в папке, также могут выбрать Automatic (from the registered domain), и ноду выберет Opfield; если это невозможно, ошибка перечислит ноды для выбора. В API и MCP параметр nodeId для POST /api/proxy-hosts и create_route необязателен, и Opfield определяет ноду в таком порядке:

1. Явно переданный nodeId используется как есть.
2. Зарегистрированные Domains среди имён Route закрепляют свою ноду Ingress — при точном совпадении или через охватывающий подстановочный домен. Зарегистрированные Domains на разных нодах не могут входить в один Route: 409 DOMAIN_NGINX_NODE_MISMATCH.
3. Иначе используется единственная нода nginx, на которой вызывающий может создавать Routes в этом месте назначения, если она подключена. Ноды, ещё не завершившие регистрацию, никогда не выбираются и не предлагаются. Opfield никогда не размещает Route автоматически на отключённой ноде; чтобы разместить его там, передайте идентификатор этой ноды явно.
4. Иначе запрос завершается ошибкой: 409 ROUTE_INGRESS_NODE_REQUIRED, если подходят несколько нод или единственная подходящая отключена, — они перечислены в сообщении и в details.eligibleNodes; 409 ROUTE_INGRESS_NODE_UNAVAILABLE, если доступной ноды нет; 403, если у вызывающего нет права proxy:create для места назначения.

GET /api/proxy-hosts/ingress-nodes или инструмент MCP list_route_ingress_nodes перечисляет подходящие ноды, показывая только идентификатор, отображаемое имя, имя хоста и состояние. Для него нужно любое право proxy:create и не нужны права на ноды. Общее право proxy:create или право на папку охватывает все ноды nginx, право на node/<nodeId> — только эту ноду, а ноды, закрытые для новых сервисов, не предлагаются никогда. Передавайте folderId, если Route будет создан в папке; вызывающему с правом только на папку его нужно передавать в любом случае. Выбранная нода проходит обычные проверки: право на ноду, папку назначения, размещение Domain и блокировку создания сервисов.

Миграция

Для переноса Domain и его Routes используйте явный сценарий миграции Ingress. Во время переключения Opfield может изменить DNS Cloudflare; внешний DNS должен обновить и подтвердить оператор. Проверьте целевое размещение до удаления исходного. Если включённый Route на целевой ноде уже обслуживает одно из переносимых имён, миграция отклоняется с 409 DOMAIN_INGRESS_TARGET_DOMAIN_CONFLICT до каких-либо изменений.

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

Целевая нода Ingress должна быть подключена, сообщать пригодный служебный адрес и поддерживать выбранный способ проверки сертификата. Пользователю нужен доступ к Domain, Route, сертификату, целевой рабочей нагрузке и каждому переиспользуемому Access List, участвующему в изменении.

Если DNS управляется вне Opfield, уменьшите TTL до запланированной миграции и зафиксируйте текущие записи. Для DNS под управлением Cloudflare проверьте область действия коннектора и список разрешённых зон до запроса на изменение записей.

Настройте полную цепочку

1. Создайте или выберите Domain и разместите его на ноде Ingress.
2. Убедитесь, что DNS указывает на выбранный публичный служебный адрес.
3. Выпустите или загрузите сертификат, покрывающий точное имя хоста.
4. Создайте Route и выберите поведение proxy, redirect или 404.
5. Выберите целевую службу и протокол приложения.
6. Подключите TLS, политику доступа, проверки состояния и параметры протокола.
7. Сохраните изменения и дождитесь успешной валидации и применения конфигурации nginx.
8. Проверьте публичный адрес из сети вне управляемой инфраструктуры.

Перед повторным использованием подстановочного сертификата или сертификата с несколькими именами проверьте каждое имя хоста. Наличие сертификата в Opfield ещё не означает, что он передан на нужную ноду: распространение зависит от размещения включённых TLS Routes.

Последствия изменений и удаления

• Перемещение Domain меняет место обслуживания всех его Routes.
• Замена сертификата после распространения затрагивает каждый подключённый TLS Route.
• Отключение Route сохраняет конфигурацию, но останавливает управляемый виртуальный хост.
• Удаление Route выводит принадлежащие ему Secure Links из эксплуатации, но не удаляет переиспользуемые сертификаты или Access Lists.
• Перед удалением Domain нужно удалить или перенести зависимые Routes.
• Сертификат, который использует Route или профиль подстановочного домена Pages, удалить нельзя: запрос завершается ошибкой 409 CERT_IN_USE с идентификаторами использующих его Routes. Сначала отсоедините сертификат; после этого удаление убирает управляемую копию Opfield.

Чек-лист проверки

• Внешний DNS разрешается в адрес нужной ноды.
• Поведение HTTP выбрано явно: перенаправление, ответ или отключение.
• HTTPS отдаёт ожидаемый сертификат и полную цепочку.
• Проверки состояния используют нужный путь и ожидаемый статус.
• Настройки WebSocket и тайм-аутов соответствуют приложению.
• Конфигурация nginx валидна, а последняя ревизия подтверждена.
• В журналах доступа и ошибок есть запрос внешней проверки.

Продление и изменение размещения

Продление сертификата и миграция Domain — разные операции. Обновлённый сертификат должен быть успешно выпущен, сохранён в Opfield, передан на каждую подходящую ноду Ingress с подключённым TLS Route и подтверждён nginx. Проверьте новый срок действия и сертификат, который реально отдаётся внешнему клиенту: успешная запись о выпуске сама по себе не завершает проверку.

Перед изменением размещения подготовьте целевую ноду. Подтвердите возможности nginx, публичные служебные адреса, доступность сертификата, конфигурацию Route, достижимость целевой службы и проверки состояния. При внешнем DNS меняйте записи только после готовности цели и сохраняйте исходное размещение как минимум на время ожидаемого TTL и кэширования. Даже если Opfield управляет DNS Cloudflare, проверьте итоговые публичные ответы вместо предположения, что действие поставщика мгновенно применилось повсеместно.

Границы сбоя и отката

Если конфигурация не прошла валидацию, откройте ошибку последней Task или ревизии nginx: это сигнал уровня конфигурации, и невалидная ревизия не должна заменять последнюю подтверждённую. Исправьте минимальную связанную настройку и снова примените изменения. Не отсоединяйте рабочий сертификат и не переносите Domain только ради обхода ошибки синтаксиса или выбора целевой службы.

Если миграция остановилась до переключения DNS, оставьте трафик на исходной ноде и исправьте целевую. Если внешний DNS уже изменён, восстановите записанные исходные значения или завершите ремонт цели в соответствии с решением по инциденту. Не переключайте записи многократно: рекурсивные DNS-серверы могут видеть разные состояния. После отката проверьте и публичное разрешение адреса, и сертификат, который действительно отдаёт исходная нода.

Opfield не может откатить записи приложения или изменения внешнего DNS, выполненные вне управляемого сценария. Сохраняйте прежние значения DNS, назначение сертификата и ревизию приложения в записи изменения.