NGINX Ingress: Basic Auth для Kubernetes

Логотип Kubernetes на экране смартфона

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

Создание файла HTPasswd
Добавление Kubernetes Secret
Изменение Ingress
Альтернативный формат секрета
Более продвинутая аутентификация
Плейбук и проверочные тесты
Резюме

NGINX Ingress — популярный контроллер входящего трафика в Kubernetes. Ресурс Ingress позволяет сопоставлять HTTP-запросы с сервисами в кластере. Ниже подробно описано, как защитить такие маршруты с помощью HTTP Basic Authentication.

Создание файла HTPasswd

Создайте файл htpasswd локально перед созданием манифестов Kubernetes. На Linux/Ubuntu можно установить утилиту и создать файл для одного пользователя:

apt install apache2-utils

htpasswd -c auth example-user

Вас попросят ввести пароль. В рабочей директории появится файл с именем auth.

Затем преобразуйте содержимое в base64, чтобы использовать как значение в Kubernetes Secret:

cat auth | base64

Скопируйте результат в буфер обмена. Мы используем его при создании секрета.

Важно

Не храните необработанные пароли в публичных репозиториях. Используйте безопасное хранилище секретов или CI/CD для подстановки значений.

Добавление Kubernetes Secret

NGINX Ingress ожидает htpasswd-формат, помещённый в Kubernetes Secret. Содержимое файла хранится в ключе auth в секрете типа Opaque. Вариант basic-auth в Kubernetes подходит не всегда для NGINX Ingress.

Пример манифеста секрета (формат auth-file):

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: htpasswd
data:
  auth:

Добавьте в auth вашу base64-строку, полученную ранее. Затем примените манифест:

kubectl apply -f htpasswd-secret.yaml

Если вы используете приватное хранилище секретов (Vault, SealedSecrets, External Secrets), отдавайте предпочтение ему для автоматической подстановки секретов в кластер.

Изменение ресурса Ingress

NGINX Ingress поддерживает аннотации, которые добавляют поведение к Ingress. Для включения HTTP Basic Auth задайте тип аутентификации и ссылку на секрет.

Пример (использует API v1beta1 как в оригинальном примере):

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    nginx.ingress.kubernetes.io/auth-type: basic
    nginx.ingress.kubernetes.io/auth-secret: htpasswd
    nginx.ingress.kubernetes.io/auth-realm: "Enter your credentials"
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        backend:
          serviceName: example-service
          servicePort: 80

Если ваш кластер использует современный API networking.k8s.io/v1, можно привести пример с pathType:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    nginx.ingress.kubernetes.io/auth-type: basic
    nginx.ingress.kubernetes.io/auth-secret: htpasswd
    nginx.ingress.kubernetes.io/auth-realm: "Enter your credentials"
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 80

Аннотации говорят NGINX требовать логин для всех запросов, попадающих под этот Ingress. Тип basic использует креденшелы из секрета htpasswd. auth-realm определяет сообщение, показываемое пользователю при запросе учётных данных.

Запросы, соответствующие этому Ingress, будут требовать аутентификацию; браузер, как правило, отображает всплывающее окно для ввода логина и пароля.

Альтернативный формат секрета

Помимо формата с одним ключом auth (auth-file), NGINX Ingress поддерживает вариант auth-map. В нём ключам соответствуют пользователи, а значения — их хэши паролей, закодированные в base64.

Пример манифеста в формате auth-map:

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: htpasswd
data:
  user1: 
  user2:

Чтобы получить значения:

Сгенерируйте строку с помощью htpasswd (без флага -c для добавления пользователей):

htpasswd -bB -C 10 auth user1 'P@ssw0rd'

Вы увидите строку вида user1:.
Возьмите часть после двоеточия (только хэш) и закодируйте её в base64:

echo -n '' | base64

Добавьте полученную base64-строку в манифест.

Преимущество auth-map — прозрачность: сразу видно, какие пользователи существуют, и проще управлять несколькими аккаунтами.

Более продвинутая аутентификация

Если необходим полный жизненный цикл аутентификации (SSO, 2FA, централизованная авторизация), подключите внешнего поставщика аутентификации. NGINX Ingress умеет перенаправлять запросы на внешний auth-сервис.

Ключевые аннотации:

nginx.ingress.kubernetes.io/auth-url — URL внешнего сервиса проверки.
nginx.ingress.kubernetes.io/auth-signin — URL для перенаправления при ошибке (страница входа).
nginx.ingress.kubernetes.io/auth-signin-redirect-param — имя параметра, куда передаётся исходный URL для возврата.

Поведение:

Входящий запрос переадресовывается на auth-url.
Если внешний сервис возвращает HTTP 200 — доступ разрешён.
Иначе — редирект на auth-signin.

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

Когда такой подход не подходит

Большие пользовательские базы: Basic Auth не масштабируется для тысяч пользователей. Лучше LDAP/OPA/IDP.
Нужна централизованная ротация паролей: используйте внешние провайдеры или секрет-менеджеры.
Требуется сильная защита паролей и аудит: Basic Auth даёт минимальную видимость и контроль.

Плейбук для деплоя (SOP)

Локально создайте или обновите файл auth через htpasswd.
Кодируйте содержимое: cat auth | base64.
Создайте манифест секрета htpasswd-secret.yaml с ключом auth или в формате auth-map.
Примените секрет: kubectl apply -f htpasswd-secret.yaml.
Обновите/создайте Ingress с нужными аннотациями и примените его.
Выполните smoke-тесты (см. раздел тестов).
Мониторьте логи NGINX Ingress Controller на предмет 401/403 и ошибок проксирования.
Автоматизируйте через CI/CD: храните base64 в защищённой переменной и подставляйте при деплое.

Ролевые чек-листы

Администратор кластера

Убедился, что Ingress Controller запущен и доступен.
Применил секрет через kubectl или External Secrets.
Обновил Ingress с аннотациями.

Инженер приложения

Проверил, что бекэнд доступен без аутентификации внутри кластера.
Обновил документацию для команды о новых шагах входа.

SRE / Безопасность

Настроил ротацию паролей и процедуры их смены.
Добавил мониторинг и алерты на частые 401/403.

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

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

Запрос к защищённому URL возвращает код 401 при отсутствии логина.
При корректных учётных данных возвращается 200 и содержимое сервиса.
Неправильные данные возвращают 401 или 403 по настройке.
Логи Ingress отражают факт аутентификации и не содержат паролей в явном виде.

Минимальные тесты

Без учётных данных: curl -i http://example.com/ -> ожидать 401.
С базовой аутентификацией: curl -i -u example-user:password http://example.com/ -> ожидать 200.
Неправильный пароль: ожидать 401.
Несколько последовательных запросов с авторизацией — проверить кеширование внешнего auth (если используется).

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

curl -i http://example.com/
curl -i -u example-user:correctPassword http://example.com/

Практические советы и шаблоны

Шаблон секрета (auth-file):

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: htpasswd
data:
  auth: REPLACE_WITH_BASE64

Шаблон Ingress с аннотациями:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: protected-ingress
  annotations:
    nginx.ingress.kubernetes.io/auth-type: basic
    nginx.ingress.kubernetes.io/auth-secret: htpasswd
    nginx.ingress.kubernetes.io/auth-realm: "Restricted Area"
spec:
  rules:
  - host: staging.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: app-service
            port:
              number: 80

Совет

При возможном использовании HTTPS обязательно обеспечьте TLS на уровне Ingress, чтобы не передавать креденшелы в открытом виде по сети.

Жёсткие меры безопасности

Используйте HTTPS/TLS для всех входящих соединений.
Храните секреты в защищённых системах (HashiCorp Vault, SealedSecrets, External Secrets) и избегайте коммитов с base64-строками в репозитории.
Включите логирование и аудит доступа к Ingress Controller.
Периодически меняйте пароли и используйте сложные политики паролей.
Для высокого уровня безопасности переходите на внешних провайдеров аутентификации (OAuth/OpenID Connect) с MFA.

Когда это не работает и типичные ошибки

Неправильный формат секрета: проверьте, что ключ называется auth для auth-file или что ключи соответствуют именам пользователей для auth-map.
Неподходящая версия контроллера: убедитесь, что используемый Ingress Controller поддерживает нужные аннотации.
Неправильные права доступа к секрету: Secret должен быть в том же неймспейсе, что и Ingress (или контроллер должен уметь читать секреты из другого неймспейса).
Кэширование на стороне браузера: некоторые браузеры кэшируют учётные данные; при тестах используйте режим инкогнито.

1-строчная глоссарий

htpasswd — утилита для создания файлов с хэшами паролей, используемых в Basic Auth.
Secret — объект Kubernetes для хранения конфиденциальных данных.
Ingress — объект Kubernetes для маршрутизации внешнего HTTP/S трафика к сервисам.
auth-map / auth-file — форматы хранения учётных данных для NGINX Ingress.

Резюме

HTTP Basic Authentication — простое средство защиты сайтов. Оно хорошо подходит для внутренних систем, staging-сайтов и быстрых защитных слоёв, когда у вас небольшой список пользователей и не требуется сложное централизованное управление учётными записями.

Использование Basic Auth с NGINX Ingress включает три шага: создание htpasswd, упаковка в Kubernetes Secret и добавление аннотаций в Ingress. Не храните секреты в явном виде в манифестах; применяйте защищённые механизмы доставки секретов через CI/CD или специализированные решения.

Важно