K3S/addons/ingress-add-domains/README.md

ingress-add-domains

Добавляет дополнительные домены к уже существующим сервисам внутри кластера.

Не создаёт Service или Endpoints — только Ingress, указывающий на готовый K8s Service. Каждый Ingress создаётся в namespace целевого сервиса, что является требованием Kubernetes.

Поддерживает:

• Внутренние домены (*.local) без TLS
• Внешние домены (*.home.ru) с TLS и cert-manager
• Basic auth (логин/пароль — хэш генерируется автоматически)
• WebSocket
• Per-entry переопределение любых параметров

Когда использовать

Сценарий	Инструмент
Открыть сервис кластера по новому домену	ingress-add-domains
Проксировать сервис вне кластера (по IP)	ingress-proxypass

Быстрый старт

# group_vars/all/addons.yml
addon_ingress_add_domains: true

ingress_add_domains_entries:
  # Внутренний домен без TLS
  - name: gitea-local
    hosts: [gitea.local]
    service:
      name: gitea-http
      namespace: gitea
      port: 3000

  # Внешний домен с TLS + basic auth
  - name: gitea-home
    hosts: [gitea.home.ru]
    service:
      name: gitea-http
      namespace: gitea
      port: 3000
    tls:
      enabled: true
      certManager:
        enabled: true
        issuer: letsencrypt-prod
        issuerKind: ClusterIssuer
    auth:
      enabled: true
      username: admin
      password: "{{ vault_gitea_proxy_password }}"

make addon-ingress-add-domains

Конфигурация

Переменные Ansible

Переменная	По умолчанию	Описание
ingress_add_domains_release_name	ingress-add-domains	Имя Helm release
ingress_add_domains_release_namespace	ingress-add-domains	Namespace для Helm-метаданных
ingress_add_domains_defaults	см. ниже	Глобальные умолчания
ingress_add_domains_entries	[]	Список записей

Поля entry

Поле	Обязательно	Описание
name	да	Уникальное имя (становится именем Ingress-ресурса)
hosts	да	Список доменов
service.name	да	Имя существующего K8s Service
service.namespace	да	Namespace сервиса (Ingress создаётся в этом namespace)
service.port	да	Порт сервиса
tls	нет	Настройки TLS (см. ниже)
auth	нет	Basic auth (см. ниже)
websocket	нет	Включить поддержку WebSocket (true/false)
path	нет	URL-путь (по умолчанию /)
pathType	нет	Prefix или Exact (по умолчанию Prefix)
ingressClass	нет	Класс ingress (по умолчанию nginx)
annotations	нет	Дополнительные аннотации (перекрывают всё)

TLS

tls:
  enabled: true
  secretName: wildcard-tls        # использовать готовый Secret (опционально)
  certManager:
    enabled: true                 # автоматически создать Certificate
    issuer: letsencrypt-prod
    issuerKind: ClusterIssuer     # или Issuer

Basic auth

auth:
  enabled: true
  username: admin
  password: "{{ vault_password }}"   # хэш генерируется автоматически

  # ИЛИ готовая htpasswd-строка:
  # credentials: "admin:$apr1$..."

  # ИЛИ использовать существующий Secret:
  # secretName: my-auth-secret

Если задан username + password — Ansible автоматически хэширует пароль через openssl passwd -apr1 и создаёт K8s Secret. Открытый пароль не попадает в Helm values.

Глобальные умолчания

ingress_add_domains_defaults:
  ingressClass: nginx
  tls:
    enabled: false
    certManager:
      enabled: false
      issuer: ""
      issuerKind: ClusterIssuer
  auth:
    enabled: false
  websocket: false
  path: /
  pathType: Prefix
  annotations: {}

Любое поле defaults можно переопределить на уровне entry.

Примеры

Несколько доменов для одного сервиса

ingress_add_domains_entries:
  - name: nextcloud-all-domains
    hosts:
      - nextcloud.local
      - cloud.local
      - nextcloud.home.ru
    service:
      name: nextcloud
      namespace: nextcloud
      port: 8080
    tls:
      enabled: true
      secretName: wildcard-home-tls

Wildcard TLS Secret для всех записей

ingress_add_domains_defaults:
  tls:
    enabled: true
    secretName: wildcard-home-tls

ingress_add_domains_entries:
  - name: gitea-home
    hosts: [gitea.home.ru]
    service: {name: gitea-http, namespace: gitea, port: 3000}

  - name: harbor-home
    hosts: [harbor.home.ru]
    service: {name: harbor-core, namespace: harbor, port: 80}
    tls:
      secretName: harbor-specific-tls   # перекрывает default

Basic auth для всех записей

ingress_add_domains_defaults:
  auth:
    enabled: true
    username: admin
    password: "{{ vault_proxy_password }}"

ingress_add_domains_entries:
  - name: argocd-home
    hosts: [argocd.home.ru]
    service: {name: argocd-server, namespace: argocd, port: 80}

  - name: grafana-home
    hosts: [grafana.home.ru]
    service: {name: prometheus-stack-grafana, namespace: monitoring, port: 80}
    auth:
      enabled: false    # отключить auth для конкретной записи

Диагностика

# Посмотреть все созданные Ingresses
kubectl get ingress -A -l app.kubernetes.io/instance=ingress-add-domains

# Детали конкретного Ingress
kubectl describe ingress <name> -n <namespace>

# Логи ingress-nginx
kubectl -n ingress-nginx logs -l app.kubernetes.io/name=ingress-nginx --tail=50

# Проверить auth Secret
kubectl -n <namespace> get secret <name>-auth

Официальные ресурсы

• Официальный сайт: https://kubernetes.io/docs/concepts/services-networking/ingress/
• Официальная документация: https://kubernetes.io/docs/concepts/services-networking/ingress/
• Версии Helm chart / ПО: https://kubernetes.github.io/ingress-nginx/deploy/