С APISIX на kgateway на однонодовом k0s: Gateway API вместо аннотаций
Published: 2026-11-13
Четыре месяца назад я перевёл свой k0s с Traefik на APISIX и описал, что по дороге сломалось. Сегодня APISIX уехал тоже: оба кластера (основной в Праге и маленький RU-узел) теперь работают на kgateway, CNCF-реализации Gateway API поверх Envoy. Главные причины две: у APISIX три компонента (шлюз, etcd, ingress-controller) и публичный по природе Admin API, из-за которого у меня уже был инцидент, а вся маршрутизация описана аннотациями, которые понимает только один контроллер. Ниже - как я проверял, встанет ли kgateway на однонодовый bare-metal кластер, что пришлось переписать руками и какие две ошибки я поймал в проде.
Зачем это было нужно
Стек до переезда выглядел так:
apache/apisix:3.17сhostNetwork: trueна портах 80/443;- etcd как промежуточное хранилище маршрутов;
apisix-ingress-controller2.1 с сайдкаромadc-server, который переводитIngressи аннотацииk8s.apisix.apache.org/*в вызовы Admin API.
Вместе это около 386 MiB памяти на основном узле и 241 MiB на RU-узле. Admin API слушает 9180 на хосте, и в сентябре его уже нашли снаружи вместе с демо-ключом. Закрыл файрволом и отдельным Secret, но сам класс проблемы никуда не делся: пока есть Admin API, его надо охранять.
kgateway устроен проще. Контроллер читает объекты Gateway API из Kubernetes и раздаёт конфигурацию Envoy по xDS. Своего хранилища нет, Admin API наружу нет, а маршруты - стандартные HTTPRoute, которые поймёт любой другой контроллер Gateway API.
Сначала проверить, встанет ли вообще
Прежде чем что-то ставить, я сверил версии. kgateway 2.5.1 поддерживает Kubernetes 1.33-1.37 и требует CRD Gateway API 1.5-1.7. Кластеры: k0s 1.34.2 и 1.36.4, тут всё в порядке. А вот с CRD было интереснее:
bashkubectl --context k0s get crd gateways.gateway.networking.k8s.io \
-o jsonpath='{.metadata.annotations.gateway\.networking\.k8s\.io/bundle-version}'
# v1.4.0
kubectl --context k0s get crd tcproutes.gateway.networking.k8s.io \
-o jsonpath='{.status.storedVersions}'
# ["v1alpha2"]
На основном кластере стоял bundle v1.4.0 standard плюс экспериментальные TCPRoute/TLSRoute/UDPRoute v1.3.0, которые когда-то принёс чарт APISIX. Если в storedVersions осталась версия, которой нет в новом CRD, API-сервер откажет в обновлении. Объектов Gateway API в кластере не было ни одного, но гадать я не стал и прогнал серверный dry-run:
bashkubectl apply --server-side --force-conflicts --dry-run=server \
-f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.0/standard-install.yaml
Dry-run прошёл чисто, поэтому на основном узле я поставил v1.6.0, как на RU-узле, а не v1.7.0, которую предлагает quickstart. Одна версия на обоих кластерах проще в поддержке.
Второй важный факт: kgateway не читает networking.k8s.io/v1 Ingress вообще. В RBAC чарта нет прав на ingresses, в коде нет такого контроллера. ingress2gateway из APISIX-аннотаций понимает только http-to-https. Значит, все 20 маршрутов с аннотациями переписываются руками.
Установка
Два OCI-чарта, никаких внешних репозиториев:
bashhelm upgrade -i kgateway-crds oci://cr.kgateway.dev/kgateway-dev/charts/kgateway-crds \
--version v2.5.1 -n kgateway-system --create-namespace
helm upgrade -i kgateway oci://cr.kgateway.dev/kgateway-dev/charts/kgateway \
--version v2.5.1 -n kgateway-system \
--set controller.resources.requests.memory=64Mi \
--set controller.resources.limits.memory=384Mi --wait
По умолчанию у контроллера нет ни requests, ни limits, поэтому лимит памяти я задал сразу. Чарт сам создаёт GatewayClass kgateway. Под Envoy контроллер создаёт отдельно на каждый Gateway.
Как выставить Envoy на 80/443 без LoadBalancer
У меня одна нода и нет балансировщика: APISIX держал порты через hostNetwork. В GatewayParameters kgateway нет поля hostNetwork или hostPort. Есть deploymentOverlay - strategic merge patch поверх сгенерированного Deployment:
yamlapiVersion: gateway.kgateway.dev/v1alpha1
kind: GatewayParameters
metadata:
name: edge
namespace: kgateway-system
spec:
kube:
service:
type: ClusterIP
envoyContainer:
resources:
requests: {cpu: 50m, memory: 64Mi}
limits: {memory: 384Mi}
deploymentOverlay:
spec:
strategy: # одна нода + hostPort: сначала освободить порты
type: RollingUpdate
rollingUpdate: {maxSurge: 0, maxUnavailable: 1}
template:
spec:
containers:
- name: kgateway-proxy
ports:
- {name: http, containerPort: 80, hostPort: 80, protocol: TCP}
- {name: https, containerPort: 443, hostPort: 443, protocol: TCP}
Я выбрал hostPort, а не hostNetwork, по двум причинам. Первая: если порт listener'а меньше 1024, контроллер сам добавляет поду sysctl net.ipv4.ip_unprivileged_port_start=0. С hostNetwork kubelet такой sysctl отклоняет, и под просто не стартует. Вторая: при hostPort CNI-плагин portmap делает только DNAT, и Envoy видит настоящий IP клиента. Я проверил, что portmap есть в цепочке flannel на обеих нодах:
bashssh root@node 'cat /etc/cni/net.d/*.conflist' | grep -A2 portmap
Gateway ссылается на эти параметры через infrastructure.parametersRef.
Две ошибки, которые я поймал в проде
Начал с RU-узла: там один маршрут, без авторизации и rewrite. Gateway применил сначала без deploymentOverlay, проверил через port-forward и только потом остановил APISIX и добавил overlay. Тут и посыпалось.
Ошибка 1: Recreate в overlay не работает
Первая версия overlay задавала strategy.type: Recreate и rollingUpdate: null, чтобы убрать дефолтный rollingUpdate. APISIX уже был остановлен, а новый под не появлялся. В логах контроллера:
textfailed to apply object apps/v1, Kind=Deployment kgateway-system/edge:
Deployment.apps "edge" is invalid: spec.strategy.rollingUpdate: Forbidden:
may not be specified when strategy `type` is 'Recreate'
null вычищается схемой CRD, и до strategic merge он не доходит, а сгенерированный Deployment всегда содержит rollingUpdate. Решение - оставить RollingUpdate с maxSurge: 0, maxUnavailable: 1. На одной ноде это работает как Recreate: старый под освобождает порты, новый их занимает. Сайт на RU-узле лежал около трёх минут. Мораль простая: overlay стоит прогонять через --dry-run=server до остановки старого шлюза, а не после.
Ошибка 2: 404 из-за HTTP/2 connection coalescing
Сразу после переключения с RU-узла пришло сообщение: https://vpn.ru.antonnovikov.com/ 404. У меня curl показывал 200. Причина была в listener'ах. Я сделал по одному HTTPS-listener'у на hostname:
yamllisteners:
- name: https-ru
hostname: ru.antonnovikov.com
...
- name: https-vpn
hostname: vpn.ru.antonnovikov.com
...
Оба имени покрыты одним сертификатом. Браузер, у которого уже открыто HTTP/2-соединение с ru., по правилам HTTP/2 переиспользует его для vpn.ru.: тот же IP, сертификат подходит. Но в Envoy соединение привязано к filter chain по SNI, то есть к listener'у https-ru, и виртуальных хостов vpn.ru. в нём нет. Отсюда 404. curl каждый раз открывает новое соединение, поэтому проблему не видит. Воспроизвести можно, если подменить заголовок Host при другом SNI:
bashcurl -s -o /dev/null -w '%{http_code}\n' --http2 \
--resolve ru.antonnovikov.com:443:<RU_IP> \
-H 'Host: vpn.ru.antonnovikov.com' https://ru.antonnovikov.com/
Исправление - один HTTPS-listener без hostname со всеми сертификатами. kgateway складывает все certificateRefs в один TLS-контекст, и Envoy выбирает сертификат по SNI. Первый в списке отдаётся для неизвестного SNI. На основном кластере это особенно важно: там один SAN-сертификат на apex, www, trips и ещё 65 поддоменов (68 имён), а koalka.ru и www.koalka.ru тоже делят сертификат.
yaml- name: https
port: 443
protocol: HTTPS
allowedRoutes: {namespaces: {from: All}}
tls:
certificateRefs:
- {name: antonnovikov-com-san-tls, namespace: default} # default для неизвестного SNI
- {name: koalka-tls, namespace: default}
- {name: grafana-tls, namespace: monitoring}
# ... всего 15 Secret из 5 namespace
Секреты из других namespace требуют ReferenceGrant в каждом из них.
Как переводились аннотации
| APISIX | Gateway API / kgateway |
|---|---|
http-to-https: "true" |
один catch-all HTTPRoute на listener http с RequestRedirect scheme: https |
http-redirect + код 301 |
RequestRedirect на внешний hostname, маршрут на оба listener'а |
rewrite-target-regex |
TrafficPolicy.urlRewrite.pathRegex |
upstream-read-timeout |
rules[].timeouts.request или TrafficPolicy.timeouts |
response-rewrite-add-header |
фильтр ResponseHeaderModifier |
ApisixPluginConfig с proxy-rewrite |
фильтр RequestHeaderModifier |
auth-type: basicAuth + ApisixConsumer |
TrafficPolicy.basicAuth с htpasswd в Secret |
ApisixGlobalRule prometheus |
метрики Envoy на :9091/metrics |
Почти всё переносится один в один. Неочевидных мест пять.
Редирект раньше авторизации. В APISIX я поднимал приоритет плагина redirect до 3000, чтобы http:// уходил на https:// до basic-auth. Иначе браузер присылал пароль открытым текстом. В Gateway API это решается структурой: basicAuth вешается только на маршруты HTTPS-listener'а, а на http живёт только catch-all редирект. Приоритеты не нужны.
Basic-auth принимает только {SHA}. kgateway 2.5 понимает в htpasswd только SHA-1, bcrypt и apr1 пропускает с ошибкой. Пароли менять не пришлось: я собрал новый Secret из старых, не выводя значения в терминал:
bashfor s in monitoring-ui-basic-auth monitoring-federate-basic-auth; do
u=$(kubectl -n monitoring get secret $s -o jsonpath='{.data.username}' | base64 -d)
p=$(kubectl -n monitoring get secret $s -o jsonpath='{.data.password}' | base64 -d)
printf '%s:{SHA}%s\n' "$u" "$(printf '%s' "$p" | openssl dgst -sha1 -binary | base64)"
done > .htpasswd
kubectl -n monitoring create secret generic monitoring-htpasswd --from-file=.htpasswd
X-Real-IP. APISIX выставлял его из $remote_addr, а приложение строит на нём счётчик просмотров и rate limit. Envoy такой заголовок сам не ставит. Без него счётчик тихо ушёл бы в ноль, а лимиты стали бы ключеваться по подделываемому X-Forwarded-For. Я задал его политикой на весь Gateway:
yamlapiVersion: gateway.kgateway.dev/v1alpha1
kind: TrafficPolicy
metadata: {name: edge-defaults, namespace: kgateway-system}
spec:
targetRefs: [{group: gateway.networking.k8s.io, kind: Gateway, name: edge}]
headerModifiers:
request:
set: [{name: X-Real-IP, value: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%"}]
httpUpgrade: [{type: websocket}]
timeouts:
request: 60s
Envoy подставляет переменную, а set перезаписывает присланное клиентом значение. Проверка: curl -H 'X-Real-IP: 6.6.6.6' .../myip вернул мой настоящий адрес.
Таймауты и websocket. По умолчанию у маршрута Envoy таймаут 15 секунд, у APISIX было 60. Поэтому 60 секунд задано на весь Gateway, 180 секунд - для загрузки фото, а для Docker registry таймаут выключен (0s), иначе большие слои не скачаются. Websocket в kgateway по умолчанию выключен, без httpUpgrade Grafana Live бы не работала.
Hostname с подчёркиванием. Редирект tg. вёл на https://antonnovikov_opslaika.t.me/. Gateway API валидирует hostname в RequestRedirect и _ не пропускает. Пришлось переписать на эквивалентный https://t.me/<канал> с ReplaceFullPath.
cert-manager
Оба ClusterIssuer решали HTTP-01 через ingressClassName: apisix. Без APISIX продление сертификатов тихо сломалось бы через месяц. Нужны две вещи: флаг --enable-gateway-api у cert-manager и solver, который вешает временный HTTPRoute на listener http:
yamlsolvers:
- http01:
gatewayHTTPRoute:
parentRefs:
- {name: edge, namespace: kgateway-system, kind: Gateway, sectionName: http}
Маршрут solver'а точнее catch-all редиректа (hostname плюс точный путь /.well-known/acme-challenge/<token>), поэтому побеждает его. Проверил на staging-сертификате на обоих кластерах до удаления APISIX.
Отдельная ловушка - сертификаты, которые когда-то создал ingress-shim cert-manager по аннотации cert-manager.io/cluster-issuer на Ingress. У них ownerReferences указывает на Ingress, поэтому при удалении Ingress сборщик мусора удалит и Certificate. Перед удалением владельца я снял ссылку:
bashkubectl -n default patch certificate koalka-tls --type=json \
-p '[{"op":"remove","path":"/metadata/ownerReferences"}]'
Как я проверял, что ничего не поменялось
Gateway с маршрутами работал рядом с APISIX, только без hostPort. Я написал скрипт из 39 проверок: хосты, пути, редиректы с query string, basic-auth с правильным и неправильным паролем, /v2/ у registry. Один прогон шёл на живой APISIX, второй - на kgateway через port-forward:
basht() { curl -s -o /dev/null -m 20 --resolve "$2:$PORT:$IP" \
-w '%{http_code} %{redirect_url}' "$1://$2:$PORT$3"; }
./matrix.sh 443 80 <NODE_IP> > old.txt # APISIX
./matrix.sh 28443 28080 127.0.0.1 > new.txt # kgateway через port-forward
diff old.txt new.txt
Разница была только в tg, и та намеренная. После переключения я прогнал тот же скрипт на продакшене, потом ещё раз после удаления APISIX. Результат не изменился. Дополнительно проверил, что Envoy выбирает сертификат по SNI для каждого домена, и что в config dump у trips стоит таймаут 180 секунд и regex-rewrite.
Само переключение на основном узле - это kubectl scale deploy apisix --replicas=0, применение overlay и ожидание rollout. Простой получился меньше минуты. APISIX я оставил на несколько часов остановленным, чтобы можно было откатиться одним scale, и удалил только после деплоя приложения, которое читает HTTPRoute.
Мониторинг и логи
У метрик Envoy нет метки хоста. Есть envoy_http_conn_manager_prefix (listener) и envoy_cluster_name вида kube_<ns>_<svc>_<port>. Поэтому алерты по ошибкам теперь считаются по backend, а не по домену. Ещё одна особенность: на :9091/metrics kgateway отдаёт только счётчики, которые хоть раз менялись. Панель «connect failures» пустая, пока ошибок не было, - это нормально.
Access-лог в JSON включается через ListenerPolicy. Имена полей я оставил как в формате APISIX (remote_addr, host, status, request_uri), чтобы promtail и дашборды почти не пришлось менять. Время теперь в миллисекундах: поля называются request_time_ms, чтобы не смешивать единицы со старыми записями.
Что может пойти не так
Под Envoy висит в Pending или не обновляется. Сначала смотрите логи контроллера, а не events пода: ошибку применения overlay видно только там. kubectl -n kgateway-system logs deploy/kgateway | grep error. Если под ждёт порты, их держит старый шлюз или прошлый под Envoy - проверьте maxSurge: 0.
Один домен отдаёт 404, хотя маршрут есть. Если listener'ы разделены по hostname, а сертификат общий, это почти наверняка HTTP/2 coalescing. Проверка - curl с одним SNI и другим Host. Лечится одним HTTPS-listener'ом.
Basic-auth отвечает 401 на правильный пароль. В Secret не {SHA} или не тот ключ (по умолчанию .htpasswd). Статус TrafficPolicy покажет no valid users with {SHA} hash format found.
Сертификаты перестали продлеваться через месяц. cert-manager запущен без --enable-gateway-api или ClusterIssuer всё ещё ссылается на старый ingress class. У меня на основном кластере cert-manager ставится helm-расширением k0s, и флаг пока стоит живым патчем Deployment - его ещё нужно перенести в k0s.yaml, иначе он пропадёт при рестарте k0s.
Итого
- kgateway встал на оба однонодовых k0s без LoadBalancer:
hostPortчерезdeploymentOverlay,portmapсохраняет IP клиента. - Вместо шлюза, etcd и ingress-controller (386 MiB) остались Envoy и контроллер: 29 и 59 MiB на основном узле при моём трафике, 145 MiB против 241 MiB на RU-узле. Admin API и etcd больше нет.
- Ingress kgateway не читает. 20 маршрутов с аннотациями я переписал на
HTTPRouteиTrafficPolicyвручную, а одинаковое поведение подтвердил diff'ом 39 проверок до и после. - Делайте один HTTPS-listener на все сертификаты, иначе HTTP/2 coalescing даст 404 в браузере, которые не видно в curl.
- Проверьте X-Real-IP, таймауты (у Envoy по умолчанию 15 секунд), websocket и формат htpasswd. Это поведение APISIX по умолчанию, которое Envoy сам не повторит.