Перенаправление на www через Nginx Ingress

Графика с логотипом Kubernetes

Если вы хотите, чтобы пользователи всегда попадали на один канонический адрес сайта, настроьте перенаправление с корневого домена (example.com) на поддомен www (www.example.com). В Nginx Ingress это делается простой аннотацией nginx.ingress.kubernetes.io/from-to-www-redirect: “true” и указанием обоих хостов в секции tls. Для окружений разработки используйте переменные Helm или условную логику, чтобы перенаправление включалось только в production.

Введение

Многие публичные веб‑сайты используют www‑версию домена как каноническую. Это помогает уникализировать адреса в поисковых системах, упрощает SSL/TLS‑настройки и делает поведение сайта предсказуемым для пользователей. При размещении приложений в Kubernetes вы можете реализовать традиционное перенаправление с bare domain (корневого домена без www) на www с помощью контроллера Nginx Ingress без кастомных правок в конфигурации Nginx.

В этой статье вы получите:

понятный пример манифеста Ingress с включённым www‑редиректом;
пример для TLS/HTTPS и интеграции с cert-manager;
способ сделать домен переменной в Helm и условно отключать редирект в CI/стейджинге;
чек‑лист, методику тестирования и шаги отладки.

Важно

Добавление аннотации активирует внутреннюю логику перенаправления в контроллере nginx‑ingress. Вам не нужно писать собственные правила rewrite в конфигурации Nginx.

Быстрые ссылки

Использование аннотации
Настройка хостов
Добавление HTTPS
Делание домена переменной (Helm)
Обработка окружений разработки
Тестирование и отладка
Рекомендации по безопасности
Сводка

Использование аннотации

Nginx Ingress предоставляет аннотацию, которая включает встроенный механизм перенаправления между bare domain и www. Достаточно добавить в манифест Ingress следующее:

nginx.ingress.kubernetes.io/from-to-www-redirect: "true"

Эту аннотацию необходимо поместить в metadata.annotations вашего ресурса Ingress. Ниже приведён полный минимальный рабочий пример, который демонстрирует, как это выглядит в целом.

Настройка хостов

Добавьте хост в секцию rules. Достаточно одной строки host — укажите тот хост, который хотите считать каноническим (обычно www.example.com). Контроллер nginx‑ingress автоматически обработает запросы к bare domain и выполнит перенаправление.

Пример минимального Ingress (формат YAML сохранён):

apiVersion: networking.k8s.io/v1beta1

kind: Ingress

metadata:

name: my-ingress

namespace: my-namespace

annotations:

kubernetes.io/ingress.class: nginx-ingress

nginx.ingress.kubernetes.io/from-to-www-redirect: “true”

spec:

rules:

host: www.example.com

http:

paths:

path: /

backend:

serviceName: my-service

servicePort: 80


Этот минимальный пример позволит увидеть редирект в действии: переход по bare domain немедленно перенаправит на www. Это гарантирует единый входной путь для пользователей.

## Добавление HTTPS

В продакшене почти всегда требуется HTTPS. Для корректной работы HTTPS обе версии хоста (example.com и www.example.com) должны быть покрыты одним сертификатом или разными сертификатами, применимыми к обоим хостам.

Обновлённый манифест с TLS (обратите внимание на дополнительные строки tls и аннотацию certmanager):

apiVersion: networking.k8s.io/v1beta1


kind: Ingress

metadata:

name: my-ingress

namespace: my-namespace

annotations:

kubernetes.io/ingress.class: nginx-ingress

certmanager.k8s.io/cluster-issuer: letsencrypt-prod

nginx.ingress.kubernetes.io/from-to-www-redirect: "true"

spec:

rules:

- host: www.example.com

http:

paths:

- path: /

backend:

serviceName: my-service

servicePort: 80

tls:

- hosts:

- example.com

- www.example.com

secretName: ingress-tls-secret

Ключевые моменты:

TLS секция должна содержать оба хоста, чтобы при подключении к любому из них сертификат совпадал с запрошенным именем.
Пример использует cert‑manager и ClusterIssuer letsencrypt‑prod. Если у вас нет cert‑manager, выполните его установку или используйте другой контроллер сертификатов.
Аннотация certmanager.k8s.io/cluster-issuer указывает, каким выпускателем генерировать TLS секрет.

Примечание

Вы можете использовать другой контроллер сертификатов. Для этого обновите аннотацию, указывая имя вашего issuer. Сам блок tls остаётся совместимым с большинством Kubernetes‑контроллеров сертификатов.

Делание домена переменной (Helm)

Чтобы не дублировать доменное имя в манифесте и упростить смену домена, превратите манифест в шаблон Helm. Предположим, что в values.yaml есть параметр ingressDomain.

Шаблон Ingress с использованием Helm (оставлен синтаксис Helm как в исходнике):

apiVersion: networking.k8s.io/v1beta1

kind: Ingress

metadata:

name: my-ingress

namespace: my-namespace

annotations:

kubernetes.io/ingress.class: nginx-ingress

certmanager.k8s.io/cluster-issuer: letsencrypt-prod

nginx.ingress.kubernetes.io/from-to-www-redirect: “true”

spec:

rules:

host: {{ print “www.” .Values.ingressDomain }}

http:

paths:

path: /

backend:

serviceName: my-service

servicePort: 80

tls:

hosts:
{{ print .Values.ingressDomain }}
{{ print “www” .Values.ingressDomain }}

secretName: ingress-tls-secret


Преимущества использования переменной:

- Меняется одно значение в values.yaml — всё обновляется.
- Упрощается развертывание в CI/CD: можно динамически генерировать домен для каждой ветки.

## Обработка окружений разработки

Если ваш CI создаёт уникальные поддомены для каждой ветки (например, my-branch.example.com), автоматическое добавление www может быть некорректным. Решение — разделить переменные:

- ingressBase — базовый домен, например example.com
- ingressDomain — текущий домен для развертывания, например my-branch.example.com

Используйте условную логику Helm и включайте www‑редирект только в production, когда ingressDomain == ingressBase.

Пример условного блока в шаблоне Helm:

spec:


rules:

{{ if eq .Values.ingressDomain .Values.ingressBase }}

- host: {{ print "www." .Values.ingressDomain }}

{{ else }}

- host: {{ print .Values.ingressDomain }}

{{ end }}

http:

paths:

- path: /

backend:

serviceName: my-service

servicePort: 80

tls:

- hosts:

- {{ .Values.ingressDomain }}

{{ if eq .Values.ingressDomain .Values.ingressBase }}

- {{ print "www." .Values.ingressDomain }}

{{ end }}

secretName: {{ .Values.ingressTlsSecret }}

Когда вы разворачиваете в production, выставьте ingressDomain = ingressBase — условие выполнится и будет создана запись www. Для веточных окружений условие не выполнится, и редирект не будет включён.

Тестирование и проверка

Быстрый чек‑лист для проверки правильности настройки:

Убедитесь, что аннотация nginx.ingress.kubernetes.io/from-to-www-redirect: “true” присутствует.
Проверьте, что в spec.rules указан желаемый host (www или bare, в зависимости от логики).
В tls.hosts перечислены оба варианта домена, и секрет TLS указан верно.
Наличие секретов: kubectl get secret -n my-namespace ingress-tls-secret
Проверка редиректа: curl -I http://example.com
- Ожидается код 301/308 и заголовок Location: https://www.example.com/
Проверка TLS: curl -vk https://example.com и https://www.example.com

Примеры команд для отладки:

Посмотреть Ingress ресурс: kubectl describe ingress my-ingress -n my-namespace
Посмотреть логи контроллера ingress‑nginx: kubectl logs -n ingress-nginx deploy/ingress-nginx-controller
Проверить правила nginx, сгенерированные контроллером (зависит от установки контроллера)

Критерии приёмки

HTTP запрос к example.com возвращает 301/308 с Location на https://www.example.com/
HTTPS доступ к example.com и www.example.com работает и сертификат валиден
Внутренние ссылки и мета‑теги указывают на канонический адрес (rel=canonical при необходимости)

Когда этот подход не сработает

DNS не настроен для обеих версий хоста — редирект не поможет, если имя не резолвится.
Внешние CDN/Proxy (Cloudflare, Fastly) могут перехватывать и изменять поведение редиректов; настройки нужно согласовать с провайдером.
HTTP Strict Transport Security (HSTS) с includeSubDomains может осложнить тестирование: браузер будет принудительно использовать HTTPS.
Сценарии с несколькими каноническими доменами (multi‑tenant) требуют иной логики, потому что одна универсальная переадресация может быть нежелательной.

Альтернативные подходы

Выполнить редирект на уровне приложения (например, в веб‑сервере или в коде приложения). Минус — дублирование логики во всех сервисах.
Использовать другой Ingress‑контроллер, например Traefik, который тоже поддерживает правила перенаправлений и middleware.
Настроить редирект на уровне DNS‑провайдера (если поддерживается) — часто менее гибко и не покрывает HTTPS правильно.

Модель мышления (ментальные эвристики)

Канонический хост = единая точка входа; всё остальное должно на него ссылаться.
TLS должен покрывать все видимые хосты одновременно, чтобы не было «страшных» исключений безопасности.
В CI/CD окружениях — отключаем «продуктовую» логику по умолчанию; включаем её только в production.

Фактбокс

Перенаправление предпочтительнее, чем дублирование контента с двух доменов — уменьшает риск дублированного индекса в поисковиках.
Аннотация nginx.ingress.kubernetes.io/from-to-www-redirect: “true” реализует поведение в контроллере nginx‑ingress без дополнительных rewrite‑правил.

Роли и чек‑листы

DevOps/SRE:
- Проверить наличие аннотации и TLS‑секрета.
- Убедиться, что cert‑manager настроен и ClusterIssuer корректен.
- Настроить CI/CD для параметризации ingressDomain/ingressBase.
Разработчик:
- Осуществить локальную проверку редиректов и убедиться, что приложение корректно обрабатывает заголовки Host.
- Проверить, что приложение не генерирует абсолютные ссылки на некорректный хост.
QA:
- Выполнить тесты редиректов (HTTP и HTTPS).
- Протестировать поведение в браузерах и curl.

SOP для развёртывания

Подготовить values.yaml с ingressDomain и ingressBase.
Убедиться, что DNS для обоих хостов указывает на ваш LB/Ingress.
Развернуть cert‑manager или убедиться в наличии подходящего issuer.
Применить Helm chart/манифест.
Проверить секрет TLS и состояние Ingress.
Выполнить curl‑проверки и проконтролировать логи ingress‑контроллера.

Инцидентный план и откат

Если после изменения Ingress пользователи теряют доступ:
- Откатить изменения манифеста (helm rollback или kubectl apply старой версии).
- Проверить события Kubernetes: kubectl get events -n my-namespace.
- Проверить доступ к секрету TLS и работоспособность контроллера.

Тесты и критерии приёмки

Тест 1: HTTP → проверка 301/308 к www
- Вход: curl -I http://example.com
- Ожидаемый результат: HTTP/1.1 301 или 308 с Location: https://www.example.com/
Тест 2: HTTPS оба хоста
- Вход: curl -vk https://example.com и https://www.example.com
- Ожидаемый результат: сертификат валиден, ответ приложения 200
Тест 3: Helm логика
- Вход: values: ingressDomain != ingressBase
- Ожидаемый результат: в конфигурации не создаётся host с www

Отладка: распространённые ошибки и их причины

Отсутствует секрет TLS: cert‑manager не выдал сертификат; проверьте ресурсы Certificate/Order/Challenge.
Аннотация игнорируется: проверьте, что вы используете контроллер ingress‑nginx (kubernetes.io/ingress.class).
DNS указывает не на Ingress: проверьте A/AAAA записи и балансировщик.

Рекомендации по безопасности

Всегда обеспечивайте HTTPS для обоих хостов.
Используйте HSTS в production, но будьте аккуратны при включении includeSubDomains.
Отключайте старые TLS‑версии и слабые шифры на уровне контроллера, если это поддерживается.

Примечание о конфиденциальности

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

Совместимость и миграция

Поддерживаемые версии: подход работает с общими версиями ingress‑nginx; проверьте документацию вашего релиза на предмет точного поведения аннотации.
При миграции с других контроллеров учитывайте отличия в синтаксисе аннотаций и middleware.

Сводка

Добавьте nginx.ingress.kubernetes.io/from-to-www-redirect: “true” в аннотации Ingress, чтобы автоматически перенаправлять с bare domain на www.
Убедитесь, что TLS покрывает оба хоста и cert‑manager (или другой issuer) корректно настроен.
Используйте Helm и условную логику, чтобы отключать www‑редирект в динамических окружениях.

Важно

После развёртывания проверьте клиентские и серверные лог‑файлы и выполните тесты, описанные в разделе тестирования. Правильная конфигурация снижает риск дублированного контента и улучшает поведение пользователей при доступе к вашему сервису.

Короткое резюме

Перенаправление bare‑domain → www с помощью Nginx Ingress — простое и масштабируемое решение для единообразного поведения сайта. Правильная конфигурация TLS и учёт CI/стейджинговых окружений делают его пригодным как для разработки, так и для production.