K3S/docs/addons.md

Аддоны

Все аддоны управляются через флаги в group_vars/all/addons.yml. Порядок установки в playbooks/addons.yml фиксирован (NFS → CSI → Ingress → cert-manager → остальные).

Установка аддонов

# Установить все включённые аддоны:
make install-addons

# Конкретный аддон (флаг из addons.yml игнорируется):
make addon-<name>

# Примеры:
make addon-prometheus-stack
make addon-argocd
make addon-jenkins
make addon-netbird

Проверка аддонов перед деплоем

# Проверка конкретного аддона:
make molecule-addon-argocd

# Полный прогон всех addon-сценариев:
make molecule-addon-all

# Пройти дальше даже если часть аддонов падает:
make -k molecule-addon-all

Практический цикл исправления:

1. make molecule-addon-all — получить первый упавший аддон.
2. Исправить сценарий/шаблон.
3. Прогнать make molecule-addon-<name>.
4. Снова make molecule-addon-all.

Каталог аддонов

Аддон	Флаг	Описание	README
Сеть
ingress-nginx	addon_ingress_nginx	HTTP/S Ingress controller	→
cert-manager	addon_cert_manager	TLS сертификаты (Let's Encrypt / self-signed)	→
istio	addon_istio	Service mesh + Kiali UI	→
netbird	addon_netbird	Self-hosted WireGuard VPN	→
crowdsec	addon_crowdsec	IDS/IPS, nginx bouncer	→
Хранилище
nfs-server	addon_nfs_server	NFS сервер	→
csi-nfs	addon_csi_nfs	CSI NFS Driver + StorageClass	→
longhorn	addon_longhorn	Distributed block storage	→
minio	addon_minio	S3-совместимое объектное хранилище	→
csi-s3	addon_csi_s3	S3/MinIO как PVC	→
csi-ceph	addon_csi_ceph	Rook-Ceph distributed storage	→
csi-glusterfs	addon_csi_glusterfs	GlusterFS CSI driver	→
Базы данных
postgresql	addon_postgresql	PostgreSQL (shared для аддонов)	→
mysql	addon_mysql	MySQL (Bitnami)	→
databasus	addon_databasus	Web UI для бэкапов БД	→
Observability
metrics-server	addon_metrics_server	kubectl top + HPA	→
prometheus-stack	addon_prometheus_stack	Prometheus + Grafana + Alertmanager	→
loki	addon_loki	Агрегация логов	→
promtail	addon_promtail	Агент сбора логов → Loki	→
tempo	addon_tempo	Distributed tracing	→
pushgateway	addon_pushgateway	Метрики batch-задач	→
CI/CD
jenkins	addon_jenkins	Jenkins CI/CD + k8s agents	→
gitea	addon_gitea	Git hosting + Gitea Actions	→
argocd	addon_argocd	GitOps (ArgoCD)	→
Безопасность
vault	addon_vault	HashiCorp Vault	→
external-secrets	addon_external_secrets	External Secrets Operator → Vault	→
vaultwarden	addon_vaultwarden	Self-hosted Bitwarden	→
Инфраструктура
harbor	addon_harbor	Container registry + proxy cache	→
kubernetes-dashboard	addon_kubernetes_dashboard	K8S Web UI	→
velero	addon_velero	Бэкап кластера + PVC в S3	→
smtp-relay	addon_smtp_relay	Postfix relay для email из подов	→
Файловые хранилища
nextcloud	addon_nextcloud	Nextcloud облачное хранилище	→
owncloud	addon_owncloud	ownCloud OCIS	→
Медиасервер
mediaserver	addon_mediaserver	Plex, Sonarr, Radarr, Lidarr, Bazarr, Prowlarr + Hysteria2 sidecar, Overseerr, Transmission, Samba	→
Сеть / VPN
splitgw	addon_splitgw	Прозрачный split-tunnel gateway: sing-box + Hysteria2 TPROXY, YouTube→прокси, RU→прямой	→
ingress-proxypass	addon_ingress_proxypass	Проксировать внешние сервисы (IP:PORT) через ingress-nginx по домену — Service + Endpoints + Ingress	→
ingress-add-domains	addon_ingress_add_domains	Добавить домены к существующим K8s сервисам — только Ingress, без Service/Endpoints	→
yandex-dns-controller	addon_yandex_dns_controller	CronJob-контроллер Yandex 360 DNS — ConfigMap → DNS, safe mode (managed:true only)	→
technitium-dns	addon_technitium_dns	HA DNS: Primary + Secondary с kube-vip LB, авто-sync зон, ExternalDNS (RFC 2136)	→
SSO / Auth
authelia	addon_authelia	SSO Forward-auth + OIDC provider: Gitea, Grafana, ArgoCD, MinIO, Vault, Nextcloud	→

Конфигурация addons.yml

# group_vars/all/addons.yml — включи нужные аддоны:

# ── Core ──────────────────────────────────────────────────────────────────────
addon_ingress_nginx: true          # обязателен для большинства аддонов
addon_cert_manager: true           # TLS сертификаты
addon_metrics_server: true         # kubectl top + HPA

# ── Observability ─────────────────────────────────────────────────────────────
addon_prometheus_stack: true       # Prometheus + Grafana + Alertmanager
addon_loki: true                   # логи
addon_promtail: true               # агент сбора логов
addon_tempo: false                 # distributed tracing
addon_pushgateway: false           # batch метрики

# ── Хранилище ─────────────────────────────────────────────────────────────────
addon_longhorn: false              # distributed block storage
addon_minio: false                 # S3 объектное хранилище
addon_csi_s3: false                # S3 как PVC

# ── Базы данных ───────────────────────────────────────────────────────────────
addon_postgresql: false            # shared PostgreSQL
addon_mysql: false

# ── CI/CD ─────────────────────────────────────────────────────────────────────
addon_gitea: false
addon_jenkins: false
addon_argocd: false

# ── Безопасность ──────────────────────────────────────────────────────────────
addon_vault: false
addon_external_secrets: false
addon_vaultwarden: false
addon_crowdsec: false

# ── Инфраструктура ────────────────────────────────────────────────────────────
addon_harbor: false
addon_velero: false
addon_netbird: false
addon_smtp_relay: false

# ── Медиасервер ───────────────────────────────────────────────────────────────
addon_mediaserver: false           # Plex + *arr + Transmission + Prowlarr/Hysteria2 + Samba

# ── Split Gateway ─────────────────────────────────────────────────────────────
addon_splitgw: false               # sing-box + Hysteria2 TPROXY (host или k8s DaemonSet)

# ── External Services Ingress Proxy ───────────────────────────────────────────
addon_ingress_proxypass: false             # проксировать внешние сервисы через ingress-nginx
addon_ingress_add_domains: false          # добавить домены к существующим K8s сервисам (только Ingress)

# ── DNS ───────────────────────────────────────────────────────────────────────
addon_yandex_dns_controller: false     # Yandex 360 DNS controller (managed records)
addon_technitium_dns: false            # HA DNS сервер (Primary+Secondary, kube-vip)

# ── SSO ───────────────────────────────────────────────────────────────────────
addon_authelia: false                  # SSO Forward-auth + OIDC (Gitea/Grafana/ArgoCD/...)

Зависимости между аддонами

Аддон	Зависит от	Автоинтеграция
promtail	loki	URL Loki берётся автоматически
loki	minio (опционально)	S3 backend при addon_minio: true
velero	minio	S3 backend для бэкапов
csi-s3	minio (опционально)	Endpoint берётся автоматически
gitea	postgresql (опционально)	Своя БД при addon_postgresql: true
harbor	postgresql (опционально)	Своя БД при addon_postgresql: true
nextcloud	postgresql (опционально)	Своя БД при addon_postgresql: true
databasus	postgresql, mysql, minio	Все подключения автоматические
jenkins	vault (опционально)	JCasC Vault URL при addon_vault: true
external-secrets	vault	ClusterSecretStore к Vault
istio	prometheus-stack (опционально)	Kiali ↔ Prometheus/Grafana авто
crowdsec	ingress-nginx	Bouncer интеграция при addon_crowdsec
mediaserver	csi-nfs (рекомендуется)	Shared PVC требует RWX StorageClass
splitgw	Hysteria2 сервер (vault_hysteria2_url)	URL из Shadowrocket / NekoBox
ingress-proxypass	ingress-nginx	Требует работающий Ingress controller
ingress-add-domains	ingress-nginx	Требует работающий Ingress controller
technitium-dns	kube-vip	LoadBalancer IP через kube-vip аннотацию
authelia	ingress-nginx	Forward-auth через annotations; PostgreSQL/Redis — опционально

MediaServer

Полный self-hosted медиасервер: Plex, *arr стек, Transmission, Prowlarr с Hysteria2 SOCKS5 прокси и Samba для LAN-доступа.

make addon-mediaserver

# Без Hysteria2 прокси:
make addon-mediaserver ARGS="-e mediaserver_hysteria2_enabled=false"

Минимальная конфигурация в vault.yml:

vault_plex_claim_token: "claim-xxxxxxxxx"       # https://plex.tv/claim (4 мин)

# URL из Shadowrocket / NekoBox / Hiddify — автоматически разберётся:
vault_hysteria2_url: "hysteria2://password@vps.example.com:443?obfs=salamander&obfs-password=secret"

vault_samba_password: "my-samba-password"
vault_transmission_password: "my-torrent-password"

Hysteria2 работает только как sidecar в Prowlarr поде — не cluster-wide VPN. Init-контейнер автоматически прописывает SOCKS5 127.0.0.1:1080 в config.xml Prowlarr.

Все 9 сервисов используют один shared PVC (RWX NFS):

/data/config/<service>/   ← конфиг каждого сервиса
/data/data/downloads/     ← Transmission
/data/data/movies/        ← Radarr
/data/data/series/        ← Sonarr
/data/data/music/         ← Lidarr

Samba получает IP от kube-vip (LoadBalancer) — подключение из LAN: \\<ip>\media.

Подробнее: addons/mediaserver/README.md

External Services Ingress Proxy

Проксирует внешние сервисы (вне кластера) через ingress-nginx по доменному имени. Для каждого сервиса автоматически создаёт Service (ClusterIP, no selector) + Endpoints + Ingress. Поддерживает TLS, basic auth, WebSocket, несколько хостов и несколько backend IP.

make addon-ingress-proxypass

Конфигурация в group_vars/all/addons.yml:

ingress_proxypass_proxies:
  - name: plex
    hosts: [plex.home.ru]
    ips: [192.168.1.50]
    port: 32400

  - name: grafana
    hosts: [grafana.home.ru]
    ips: [192.168.1.60]
    port: 3000
    tls:
      enabled: true
      secretName: wildcard-cert

Подробнее: addons/ingress-proxypass/README.md

---

Ingress Add Domains

Добавляет дополнительные домены к уже существующим K8s сервисам. Создаёт только Ingress в namespace целевого сервиса — Service и Endpoints не трогает. Поддерживает TLS с cert-manager, basic auth (автохэш пароля), WebSocket.

make addon-ingress-add-domains

Конфигурация в group_vars/all/addons.yml:

ingress_add_domains_entries:
  - name: gitea-local
    hosts: [gitea.local]
    service:
      name: gitea-http
      namespace: gitea
      port: 3000

  - name: gitea-home
    hosts: [gitea.home.ru]
    service:
      name: gitea-http
      namespace: gitea
      port: 3000
    tls:
      enabled: true
      certManager:
        enabled: true
        issuer: letsencrypt-prod
    auth:
      enabled: true
      username: admin
      password: "{{ vault_gitea_password }}"

Подробнее: addons/ingress-add-domains/README.md

---

Split Gateway

Прозрачный split-tunnel proxy на базе sing-box с Hysteria2 как outbound. Перехватывает трафик с TV/устройств через TPROXY и маршрутизирует по правилам: YouTube → Hysteria2, RU-сервисы и частные сети → прямой маршрут.

# Режим systemd (установка на хост из группы [splitgw]):
make addon-splitgw

# Режим K8s DaemonSet:
make addon-splitgw ARGS="-e splitgw_deploy_mode=k8s"

Настройки в group_vars/all/addons.yml:

# IP-адреса устройств, трафик которых перехватывается:
splitgw_tv_sources:
  - "192.168.1.100/32"   # Smart TV

# IP роутера (для разворота DNS):
splitgw_router_ip: "192.168.1.1"

# URL из Shadowrocket / NekoBox (разбирается автоматически):
# vault_hysteria2_url задаётся в vault.yml

Vault секрет (тот же что для mediaserver):

vault_hysteria2_url: "hysteria2://password@vps.example.com:443?obfs=salamander&obfs-password=secret"

Keenetic: создай политику маршрутизации для TV с шлюзом на ноду splitgw.

Подробнее: addons/splitgw/README.md

---

Prometheus метрики

Все аддоны создают ServiceMonitor автоматически при addon_prometheus_stack: true:

• ingress-nginx, cert-manager, ArgoCD, Gitea, Harbor, Jenkins
• PostgreSQL, MySQL, MinIO, Loki, Tempo, Pushgateway
• Longhorn, Velero, CrowdSec, Vaultwarden, Nextcloud, ownCloud

Vault секреты

Полный список vault.yml переменных — group_vars/all/vault.yml.example:

vault_k3s_token: ""
vault_grafana_user: "admin"
vault_grafana_password: ""
vault_kiali_token: ""
vault_gitea_admin_password: ""
vault_gitea_db_password: ""
vault_harbor_admin_password: "Harbor12345"
vault_harbor_db_password: ""
vault_postgresql_postgres_password: ""
vault_postgresql_password: ""
vault_mysql_root_password: ""
vault_mysql_password: ""
vault_minio_root_user: "admin"
vault_minio_root_password: ""
vault_velero_s3_access_key: ""
vault_velero_s3_secret_key: ""
vault_crowdsec_enroll_key: ""
vault_nextcloud_admin_password: ""
vault_nextcloud_db_password: ""
vault_owncloud_admin_password: ""
vault_jenkins_admin_password: ""
vault_netbird_coturn_password: ""
vault_netbird_router_setup_key: ""
vault_netbird_exit_node_setup_key: ""
vault_plex_claim_token: ""
vault_hysteria2_url: ""            # URL целиком из Shadowrocket/NekoBox — для mediaserver и splitgw
vault_hysteria2_server: ""
vault_hysteria2_auth: ""
vault_samba_password: ""
vault_transmission_password: ""
vault_vaultwarden_admin_token: ""
vault_vaultwarden_smtp_password: ""
vault_smtp_relay_password: ""
vault_glusterfs_heketi_secret: ""
vault_databasus_db_password: ""
vault_aws_kms_access_key: ""
vault_aws_kms_secret_key: ""
vault_transit_seal_token: ""
vault_azure_kv_client_secret: ""
vault_eso_approle_secret_id: ""