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](../ingress-proxypass/README.md) |

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

```yaml
# 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 }}"
```

```bash
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

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

### Basic auth

```yaml
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.

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

```yaml
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.

## Примеры

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

```yaml
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 для всех записей

```yaml
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 для всех записей

```yaml
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 для конкретной записи
```

## Диагностика

```bash
# Посмотреть все созданные 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/)
- Официальная документация: [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/](https://kubernetes.github.io/ingress-nginx/deploy/)