С Traefik на APISIX на однонодовом k0s: что сломалось
Published: 2026-07-15
Traefik проработал на моём k0s 224 дня без единой жалобы: держал 80/443 через hostNetwork, писал access-логи в JSON и ни разу не упал. Переехал я на APISIX не потому, что "Traefik плохой", а потому, что "хочется стек помоложе и полегче, раз уж всё равно навожу порядок в мониторинге и логах". На бумаге замена ingress-контроллера выглядит как обычный rolling update. На bare-metal кластере из одной ноды это превратилось в прямое переключение с простоем и десятком проблем. Часть из них молча сломала бы продакшен, если бы я не проверил каждую вживую.
Проблема
Кластер - один физический узел с k0s, без внешнего балансировщика. Traefik держал 80/443 через hostNetwork: true. Это единственный рабочий вариант, когда Service типа LoadBalancer вечно висит в <pending>. 19 доменов (личный сайт, VPN-дашборд, Docker registry, Grafana, VictoriaMetrics, webmail) шли через Traefik IngressRoute - собственный CRD Traefik, а не стандартный networking.k8s.io/v1 Ingress.
План был красивый: поставить APISIX рядом с Traefik, прогнать тесты и переключить трафик, не потеряв ни секунды. План умер на первой же попытке: планировщик Kubernetes отказался размещать под APISIX.
text0/1 nodes are available: 1 node(s) didn't have free ports for the requested pod ports
Два пода с hostNetwork: true, оба хотят 80 и 443, а узел один. Без второй ноды blue-green здесь физически невозможен. Значит, сначала уходит Traefik, сразу за ним приходит APISIX, а всё, что сломается по дороге, чиню на живую.
Как это устроено
apisix-ingress-controller вместе с чартом apisix/apisix - это два компонента в одном Helm-релизе. Первый - сам шлюз (data plane на OpenResty). Второй - контроллер, который следит за объектами Ingress и отправляет конфигурацию в APISIX через Admin API. По умолчанию APISIX тянет за собой etcd. Данные приложений там не хранятся: etcd служит промежуточным хранилищем маршрутов между контроллером и шлюзом.
bashhelm repo add apisix https://apache.github.io/apisix-helm-chart
helm repo update
Дальше - установка с полным набором флагов, которые мне на самом деле понадобились (каждый объясню ниже):
bashhelm upgrade --install apisix apisix/apisix \
--namespace apisix \
-f apisix-logs-values.yaml \
--set apisix.ssl.enabled=true \
--set apisix.ssl.containerPort=443 \
--set ingress-controller.enabled=true \
--set ingress-controller.gatewayProxy.createDefault=true \
--set ingress-controller.gatewayProxy.provider.controlPlane.service.name=apisix-admin \
--set ingress-controller.gatewayProxy.provider.controlPlane.auth.adminKey.value=edd1c9f034335f136f87ad84b625c8f1 \
--set hostNetwork=true \
--set service.http.containerPort=80 \
--set service.type=ClusterIP \
--set 'securityContext.capabilities.add[0]=NET_BIND_SERVICE' \
--set securityContext.runAsUser=0 \
--set updateStrategy.type=Recreate \
--set etcd.replicaCount=1 \
--set etcd.persistence.enabled=false \
--wait --timeout 180s
Каждая строчка здесь стоила мне одной неудачной попытки.
Шаг за шагом
Шаг 1: HTTPS по умолчанию выключен
Первая установка прошла без ошибок, поды поднялись, но HTTPS не отвечал вообще. Причина: в values чарта apisix.ssl.enabled по умолчанию равен false. Без него шлюз просто не слушает 443, что бы ни было написано в Service или в настройках hostNetwork.
bashhelm show values apisix/apisix | grep -A3 "^ ssl:"
yamlssl:
enabled: false # вот он
containerPort: 9443
Минут двадцать я разглядывал порты и Service'ы, и только потом догадался проверить сам флаг, а не всё, что вокруг него.
Шаг 2: правильный ключ для TLS-порта
Раз есть service.http.containerPort, логично ожидать и service.tls.containerPort. Такого ключа в чарте нет. Я проверил это через helm show values, а не стал гадать по памяти:
yamlservice:
tls:
servicePort: 443
# containerPort здесь нет вообще
Порт HTTPS-листенера задаётся в другом месте: apisix.ssl.containerPort, в отдельной секции про SSL, а не в секции Service. Одна и та же настройка живёт в двух разных местах дерева values. Типичная ловушка в Helm-чартах, где структура менялась быстрее документации.
Шаг 3: запятые в --set ломают JSON-строку
Access-логи в JSON были одной из причин всего переезда. Задал формат:
bash--set apisix.nginx.logs.accessLogFormat='{"time":"$time_iso8601","host":"$http_host","status":$status}'
Установка прошла без ошибок. Логи внутри пода выглядели так:
text["time":"2026-07-15T07:26:53+00:00" "host":"antonnovikov.com" "status":200]
Квадратные скобки вместо фигурных, пробелы вместо запятых. Валидный JSON превратился в мусор, а Helm не выдал ни одной ошибки. Причина: --set делит значение по неэкранированным запятым и считает их разделителями между разными парами key=value. В строке с JSON-форматом запятые на каждом шагу. Helm молча превратил одну строку в YAML-список из отдельных пар "ключ":"значение", а шаблон чарта отрендерил этот список как придётся.
Правильный способ - вообще не использовать --set для значений с запятыми и передавать их через файл:
yaml# apisix-logs-values.yaml
apisix:
nginx:
logs:
accessLogFormat: '{"time":"$time_iso8601","remote_addr":"$remote_addr","host":"$http_host","request_uri":"$request_uri","status":$status}'
accessLogFormatEscape: json
bashhelm upgrade apisix apisix/apisix -n apisix -f apisix-logs-values.yaml --reuse-values
Шаг 4: под не может занять порт 80
text2026/07/15 07:26:53 [emerg] 1#1: bind() to 0.0.0.0:80 failed (13: Permission denied)
Для портов ниже 1024 нужен либо root, либо capability CAP_NET_BIND_SERVICE. В values чарта Traefik это уже было настроено, а для APISIX я просто забыл перенести ту же настройку:
yamlsecurityContext:
capabilities:
add: [NET_BIND_SERVICE]
runAsNonRoot: false
runAsUser: 0
Шаг 5: etcd просит PersistentVolumeClaim, которого нет
textFailedBinding: no persistent volumes available for this claim and no storage class is set
На bare-metal k0s без динамического выделения томов etcd из чарта запрашивает PVC и навсегда зависает в Pending. Здесь можно спокойно поставить etcd.persistence.enabled=false. В etcd лежит только текущая конфигурация маршрутов, и ей не нужно переживать перезапуск пода: контроллер за секунды соберёт её заново из объектов Ingress.
Шаг 6: GatewayProxy сам не создаётся
ingress-controller.enabled=true включает контроллер, но без GatewayProxy он не знает, куда отправлять конфигурацию:
textINFO provider.client syncing all resources
INFO provider.client no GatewayProxy configs provided
GatewayProxy - отдельный CRD, который связывает IngressClass с Admin API конкретного шлюза (адрес, порт, ключ авторизации). Флаг gatewayProxy.createDefault=true создаёт его автоматически, но имя Service с Admin API и ключ всё равно нужно указать явно:
bash--set ingress-controller.gatewayProxy.createDefault=true \
--set ingress-controller.gatewayProxy.provider.controlPlane.service.name=apisix-admin \
--set ingress-controller.gatewayProxy.provider.controlPlane.auth.adminKey.value=edd1c9f034335f136f87ad84b625c8f1
Ключ edd1c9f034335f136f87ad84b625c8f1 - стандартный демо-ключ самого APISIX. Из коробки он совпадает у шлюза и контроллера, но лучше задать его явно, чем надеяться, что значения по умолчанию совпадут.
Шаг 7: hostNetwork + rolling update - тупик на одной ноде
Каждый следующий helm upgrade зависал на несколько минут:
textWaiting for daemon set... 0 out of 1 new pods have been updated
Стратегия обновления по умолчанию - RollingUpdate: сначала поднять новый под, потом убить старый. С hostNetwork: true и одной нодой это невозможно: новый под хочет те же 80/443, которые всё ещё держит старый. Та же проблема, что и в самом начале, только теперь она бьёт по каждому обновлению, а не только по первой установке рядом с Traefik.
bash--set updateStrategy.type=Recreate
Recreate сначала убивает старый под, потом создаёт новый. Секунда простоя на каждом обновлении, зато никаких бесконечных зависаний.
Шаг 8: 404 на CSS и JS после переключения маршрутов
Сайт поднялся, домены отвечали 200, но консоль браузера была забита таким:
textRefused to apply style from '.../assets/css/styles.css' because its MIME type
('text/html') is not a supported stylesheet MIME type
Ошибка была в моей собственной логике переноса. В Traefik семь поддоменов (cv., weblog., status. и другие) используют один под сайта через middleware addPrefix: cv.antonnovikov.com/ перед проксированием превращается в /cv/. Когда я переводил маршруты на стандартный Ingress, я повесил аннотацию с rewrite на все пути без исключения. В том числе на /assets/*, которые лежат в общей папке без префикса. Запрос уходил на /cv/assets/... вместо /assets/... и получал 404. Бэкенд услужливо отдавал HTML-страницу ошибки вместо CSS, отсюда и MIME-тип text/html.
В Traefik для этого было отдельное правило маршрута для /assets без rewrite, и в первой версии переноса я его просто не заметил. Решение - два Ingress на домен вместо одного: первый без rewrite для статики и собственного префикса домена, второй с rewrite для всего остального.
yaml# passthrough - без rewrite, для /assets и статических файлов
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cv-subdomain-passthrough
annotations:
k8s.apisix.apache.org/http-to-https: "true"
spec:
ingressClassName: apisix
rules:
- host: cv.antonnovikov.com
http:
paths:
- path: /assets
pathType: Prefix
backend: {service: {name: antonnovikov-site, port: {number: 80}}}
- path: /cv
pathType: Prefix
backend: {service: {name: antonnovikov-site, port: {number: 80}}}
---
# catchall - с rewrite, для корня и всего остального
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cv-subdomain
annotations:
k8s.apisix.apache.org/http-to-https: "true"
k8s.apisix.apache.org/rewrite-target-regex: "^/(.*)"
k8s.apisix.apache.org/rewrite-target-regex-template: "/cv/$1"
spec:
ingressClassName: apisix
rules:
- host: cv.antonnovikov.com
http:
paths:
- path: /
pathType: Prefix
backend: {service: {name: antonnovikov-site, port: {number: 80}}}
Стандартный Ingress API сам разбирается с приоритетом: правило с более точным путём (/assets, /cv) побеждает общий /, ничего дополнительно настраивать не пришлось.
Шаг 9: два домена оказались редиректами, а не сайтом
В дампе Traefik tg.antonnovikov.com и sofyanovikova.ru выглядели как обычные маршруты на бэкенд сайта. Когда я разобрал middleware, оказалось, что это постоянные редиректы на Telegram-каналы, а не проксирование: redirectRegex с шаблоном .*, который ведёт на фиксированный URL. Первая версия переноса честно скопировала их как обычные домены. Они перестали бы перенаправлять и начали бы показывать сайт. В APISIX для этого есть готовая аннотация, отдельный CRD не нужен:
yamlmetadata:
annotations:
k8s.apisix.apache.org/http-redirect: "https://t.me/example"
k8s.apisix.apache.org/http-redirect-code: "301"
Шаг 10: метрики есть, но не те
apisix_nginx_http_current_connections появилась в /apisix/prometheus/metrics сразу. А apisix_http_status, apisix_http_latency и apisix_bandwidth - нет, хотя трафик уже шёл. Базовые метрики уровня nginx пишутся всегда, а для метрик по каждому запросу нужен глобально включённый плагин prometheus:
yamlapiVersion: apisix.apache.org/v2
kind: ApisixGlobalRule
metadata:
name: prometheus-metrics
namespace: apisix
spec:
ingressClassName: apisix
plugins:
- name: prometheus
enable: true
Кроме того, экспортер по умолчанию слушает 127.0.0.1:9091 внутри пода. Снаружи через Kubernetes Service до него не достучаться, только через port-forward, а port-forward при отладке как раз прячет проблему. Пришлось явно сменить адрес:
yamlapisix:
pluginAttrs:
prometheus:
export_addr:
ip: "0.0.0.0"
port: 9091
И создать Service, который чарт сам не создаёт:
yamlapiVersion: v1
kind: Service
metadata:
name: apisix-metrics
namespace: apisix
spec:
selector:
app.kubernetes.io/name: apisix
app.kubernetes.io/instance: apisix
ports:
- name: metrics
port: 9091
targetPort: 9091
Шаг 11: --reuse-values после неудачного обновления тихо всё откатил
После одного из исправлений JSON-формата я запустил helm upgrade --reuse-values --set updateStrategy.type=Recreate, и формат логов вернулся к сломанному виду из шага 3. --reuse-values берёт значения не из последней попытки обновления, а из последнего успешно развёрнутого релиза. Одна из промежуточных попыток получила статус failed: истёк таймаут --wait, хотя ресурсы применились. Helm взял релиз до неё и молча похоронил исправление. Урок: после --reuse-values всегда сверяйтесь с helm get values -n <ns> -a и не верьте на слово, что обновление применило именно то, что вы только что поправили.
Что может пойти не так
Домен отдаёт 200, но содержимое не то. Проверяйте не только код ответа, но и реальный <title> или конкретный файл. 404 от бэкенда может выглядеть как 200, если фронтенд перехватывает ошибку своей SPA-страницей.
Ingress-контроллер без конца пишет в лог no GatewayProxy configs provided. GatewayProxy не создался или ссылается не на тот Service. Проверка: kubectl get gatewayproxy -n apisix и kubectl logs -n apisix -l app.kubernetes.io/name=ingress-controller.
После helm upgrade под завис в Pending. На одной ноде с hostNetwork: true это почти всегда конфликт портов со старым подом той же роли. Проверка: kubectl get events -n <ns> | grep FailedScheduling. Лечится через updateStrategy.type=Recreate, а не увеличением таймаута.
Метрика в PromQL есть, а данных нет. Проверьте, что плагин действительно подключён (ApisixGlobalRule) и что порт экспортера слушает 0.0.0.0, а не 127.0.0.1. kubectl exec в под и локальный curl этого не покажут, нужен запрос именно через Service.
Итого
- На одной bare-metal ноде с
hostNetworkblue-green между двумя ingress-контроллерами невозможен: планировщик не даст запустить поды с одинаковыми портами. Это прямое переключение с запланированным простоем, а не rolling update. helm show valuesперед установкой - не формальность. Три реальных бага (ssl.enabled, неверный ключ порта, сломанный--setс запятыми) я нашёл только с его помощью, а не по документации.- Никогда не передавайте через
--setзначения с запятыми: JSON-строки, списки, что угодно с,внутри. Только-f values.yaml. - Перенос маршрутов - не механическая замена одного CRD на другой. Middleware, которые казались мелочью (
addPrefixтолько на части путей,redirectRegexвместо проксирования), меняют поведение, если их не воспроизвести точно. hostNetwork+ одна нода означаютupdateStrategy: Recreateнавсегда, а не только для первой установки.- Метрики и логи ingress-контроллера - отдельная работа после переключения. Сами по себе после установки чарта они не появятся.