Ingress2gateway: миграция с Ingress на Gateway API

Область применения

Ingress2gateway в первую очередь предназначен для преобразования ресурсов Ingress и провайдерских ресурсов (CRD) в ресурсы Gateway API. Широко используемые провайдерские аннотации и/или CRD могут по-прежнему не поддерживаться. Актуальный список поддерживаемых провайдеров и их документацию смотрите в разделе поддерживаемые провайдеры. Вклад в поддержку провайдерских аннотаций и/или CRD приветствуется при условии, что они могут быть непосредственно преобразованы в ресурсы Gateway API.

Примечание

Ingress2gateway не предназначен для копирования аннотаций из Ingress в Gateway API.

Провайдеры и эмиттеры

Ingress2gateway состоит из двух основных компонентов: провайдеров (providers) и эмиттеров (emitters).

Провайдеры читают ресурсы Ingress и провайдерские CRD, а затем преобразуют их в универсальное промежуточное представление (IR — intermediate representation).
Эмиттеры принимают это IR и формируют итоговый вывод в формате Gateway API. Стандартный эмиттер standard (используемый по умолчанию) генерирует базовые ресурсы Gateway API (например, Gateway и HTTPRoute), тогда как другие эмиттеры могут дополнительно создавать ресурсы, специфичные для конкретного проекта Gateway API (например, EnvoyGateway BackendTrafficPolicy или GKE HealthCheckPolicy).

Подробное описание архитектуры приведено в docs/emitters.md.

Поддерживаемые провайдеры

Если ваш провайдер или отдельная функциональность пока не поддерживаются, откройте issue и опишите свой сценарий использования.

Чтобы добавить поддержку нового провайдера, прочитайте CONTRIBUTING.md.

Поддерживаемые эмиттеры

Установка

Через go install

Если на вашем компьютере настроена среда разработки Go, установить ingress2gateway можно командой:

go install github.com/kubernetes-sigs/ingress2gateway@v1.0.0

Бинарный файл ingress2gateway будет помещён в $(go env GOPATH)/bin.

Также можно скачать готовый бинарный файл на странице релизов.

На macOS и Linux через Homebrew

Убедитесь, что Homebrew установлен в вашей системе.

brew install ingress2gateway

Сборка из исходного кода

Убедитесь, что ваша система соответствует следующим требованиям:
- Установите Git: Git необходим для клонирования репозитория проекта.
- Установите Go версии 1.25.5 или новее: убедитесь, что Go установлен в системе. Скачать его можно с официального сайта (https://golang.org/dl/), следуя инструкциям по установке.

Клонируйте репозиторий проекта:

git clone https://github.com/kubernetes-sigs/ingress2gateway.git && cd ingress2gateway

Соберите проект:
```
make build
```
Установите бинарный файл в систему:
```
go install .
```

Использование

Ingress2gateway читает ресурсы Ingress и/или провайдерские CRD из кластера Kubernetes либо из файла и выводит эквивалентные ресурсы Gateway API в формате YAML, JSON или KYAML в стандартный вывод. Простейший пример — конвертация всех Ingress одного провайдера (здесь используется ingress-nginx):

ingress2gateway print --providers=ingress-nginx

Эта команда выполнит следующие действия:

Прочитает файл конфигурации Kube для получения учётных данных кластера и текущего активного пространства имён.
Найдёт ресурсы ingress-nginx в этом пространстве имён.
Преобразует их в ресурсы Gateway API.
Предупредит о любых непереведённых полях или неподдерживаемых функциях.

Параметры

Команда `print`

Флаг	Сокращение	Значение по умолчанию	Обязательный	Описание
all-namespaces	-A	false	Нет	При наличии перечисляет запрошенные объекты во всех пространствах имён. Пространство имён из текущего контекста игнорируется, даже если указано через --namespace.
allow-experimental-gw-api		false	Нет	При наличии включает экспериментальные поля Gateway API (например, URLRewrite) в вывод.
emitter		standard	Нет	Эмиттер, используемый для генерации ресурсов Gateway API.
input-file			Нет	Путь к файлу(ам) манифестов. Если указан, инструмент читает Ingress из файлов, а не из кластера. Поддерживает yaml и json. Можно указывать несколько раз.
kubeconfig			Нет	Файл kubeconfig для взаимодействия с кластером. Если флаг не задан, поиск выполняется в стандартных расположениях.
namespace	-n		Нет	При наличии ограничивает область действия команды указанным пространством имён.
no-color		false	Нет	Отключить коды ANSI-цветов в выводе.
output	-o	yaml	Нет	Формат вывода. Один из: yaml, json, kyaml.
providers			Да	Список провайдеров через запятую.

Флаг

Сокращение

Значение по умолчанию

Обязательный

Описание

all-namespaces

-A

false

Нет

При наличии перечисляет запрошенные объекты во всех пространствах имён. Пространство имён из текущего контекста игнорируется, даже если указано через --namespace.

allow-experimental-gw-api

false

Нет

При наличии включает экспериментальные поля Gateway API (например, URLRewrite) в вывод.

emitter

standard

Нет

Эмиттер, используемый для генерации ресурсов Gateway API.

input-file

Нет

Путь к файлу(ам) манифестов. Если указан, инструмент читает Ingress из файлов, а не из кластера. Поддерживает yaml и json. Можно указывать несколько раз.

kubeconfig

Нет

Файл kubeconfig для взаимодействия с кластером. Если флаг не задан, поиск выполняется в стандартных расположениях.

namespace

-n

Нет

При наличии ограничивает область действия команды указанным пространством имён.

no-color

false

Нет

Отключить коды ANSI-цветов в выводе.

output

-o

yaml

Нет

Формат вывода. Один из: yaml, json, kyaml.

providers

Да

Список провайдеров через запятую.

Флаги, специфичные для провайдеров

Флаг	Значение по умолчанию	Обязательный	Описание
gce-gateway-class-name		Нет	Специфично для провайдера: gce. Имя GatewayClass, используемого для Gateway.
ingress-nginx-ingress-class	nginx	Нет	Специфично для провайдера: ingress-nginx. Имя класса Ingress для выбора.
openapi3-backend		Нет	Специфично для провайдера: openapi3. Имя бэкенд-сервиса для использования в HTTPRoute.
openapi3-gateway-class-name		Нет	Специфично для провайдера: openapi3. Имя класса Gateway для использования в Gateway.
openapi3-tls-secret		Нет	Специфично для провайдера: openapi3. Имя секрета для ссылок на TLS-сертификат в Gateway.

Флаг

Значение по умолчанию

Обязательный

Описание

gce-gateway-class-name

Нет

Специфично для провайдера: gce. Имя GatewayClass, используемого для Gateway.

ingress-nginx-ingress-class

nginx

Нет

Специфично для провайдера: ingress-nginx. Имя класса Ingress для выбора.

openapi3-backend

Нет

Специфично для провайдера: openapi3. Имя бэкенд-сервиса для использования в HTTPRoute.

openapi3-gateway-class-name

Нет

Специфично для провайдера: openapi3. Имя класса Gateway для использования в Gateway.

openapi3-tls-secret

Нет

Специфично для провайдера: openapi3. Имя секрета для ссылок на TLS-сертификат в Gateway.

Поддержка версий Gateway API

Ingress2gateway поддерживает последнюю стабильную версию Gateway API, актуальную на момент выпуска.

Версия Ingress2gateway	Поддерживаемая версия Gateway API
v1.0	v1.5.0 ¹

Версия Ingress2gateway

Поддерживаемая версия Gateway API

v1.0

v1.5.0 ¹

¹ Вывод Ingress2Gateway v1.0 в целом совместим с Gateway API v1.4 с сохранением обратной совместимости.

Преобразование ресурсов Ingress в Gateway API

Порядок обработки и конфликты

Ресурсы Ingress обрабатываются в определённом порядке, что обеспечивает детерминированную генерацию конфигурации Gateway API. Этот порядок также определяет приоритет ресурсов Ingress и маршрутов при возникновении конфликтов.

Ресурсы Ingress с наиболее ранней меткой времени создания сортируются первыми и, соответственно, получают наивысший приоритет. Если метки времени создания совпадают, сортировка выполняется по значению namespace/name ресурсов. Если правило Ingress конфликтует с другим (например, совпадает путь, но указаны разные бэкенды), для ресурса, оказавшегося в сортировке позже, будет зафиксирована ошибка.

Поскольку спецификация Ingress v1 сама по себе не содержит руководства по разрешению конфликтов, мы приняли описанный выше подход. Эти правила аналогичны рекомендациям по разрешению конфликтов Gateway API.

Сопоставление полей Ingress с полями Gateway API

Для заданного набора ресурсов Ingress ingress2gateway создаёт Gateway с различными HTTP- и HTTPS-слушателями (Listener), а также HTTPRoute, представляющие эквивалентные правила маршрутизации.

Поле Ingress Конфигурация Gateway API

Поле Ingress	Конфигурация Gateway API
`ingressClassName`	Если задано в ресурсе Ingress, это значение будет использовано как `gatewayClassName` в соответствующем сгенерированном Gateway. Аннотация `kubernetes.io/ingress.class` ведёт себя аналогично.
`defaultBackend`	При наличии эта конфигурация генерирует Gateway Listener без указания `hostname`, а также catchall HTTPRoute, ссылающийся на этот слушатель. Указанный бэкенд преобразуется в элемент `rules[].backendRefs[]` HTTPRoute.
`tls[].hosts`	Каждый хост в IngressTLS приводит к созданию HTTPS-слушателя в сгенерированном Gateway со следующими параметрами: `listeners[].hostname` = указанный хост, `listeners[].port` = `443`, `listeners[].protocol` = `HTTPS`, `listeners[].tls.mode` = `Terminate`.
`tls[].secretName`	Указанный секрет будет указан в упомянутых выше HTTPS-слушателях Gateway в поле `listeners[].tls.certificateRefs`. Этот секрет получит каждый слушатель для каждого хоста в IngressTLS.
`rules[].host`	Если не пусто, каждое уникальное значение этого поля среди предоставленных ресурсов Ingress создаёт отдельный HTTP-слушатель Gateway с соответствующим `listeners[].hostname`. При этом `listeners[].port` устанавливается в `80`, а `listeners[].protocol` — в `HTTP`. Правила Ingress с одинаковым именем хоста генерируют правила HTTPRoute в HTTPRoute, где `hostnames` содержит этот хост как единственный элемент. Если поле пустое, аналогично `defaultBackend`, создаётся Gateway Listener без указания hostname (если он ещё не существует), а правила маршрутизации добавляются в catchall HTTPRoute.
`rules[].http.paths[].path`	Это поле преобразуется в конфигурацию `rules[].matches[].path.value` в HTTPRoute.
`rules[].http.paths[].pathType`	Это поле преобразуется в конфигурацию `rules[].matches[].path.type` в HTTPRoute. `Exact` в Ingress соответствует совпадению `Exact` в HTTPRoute. `Prefix` в Ingress соответствует совпадению `PathPrefix` в HTTPRoute.
`rules[].http.paths[].backend`	Указанный бэкенд преобразуется в элемент `rules[].backendRefs[]` HTTPRoute.

ingressClassName

Если задано в ресурсе Ingress, это значение будет использовано как gatewayClassName в соответствующем сгенерированном Gateway. Аннотация kubernetes.io/ingress.class ведёт себя аналогично.

defaultBackend

При наличии эта конфигурация генерирует Gateway Listener без указания hostname, а также catchall HTTPRoute, ссылающийся на этот слушатель. Указанный бэкенд преобразуется в элемент rules[].backendRefs[] HTTPRoute.

tls[].hosts

Каждый хост в IngressTLS приводит к созданию HTTPS-слушателя в сгенерированном Gateway со следующими параметрами: listeners[].hostname = указанный хост, listeners[].port = 443, listeners[].protocol = HTTPS, listeners[].tls.mode = Terminate.

tls[].secretName

Указанный секрет будет указан в упомянутых выше HTTPS-слушателях Gateway в поле listeners[].tls.certificateRefs. Этот секрет получит каждый слушатель для каждого хоста в IngressTLS.

rules[].host

Если не пусто, каждое уникальное значение этого поля среди предоставленных ресурсов Ingress создаёт отдельный HTTP-слушатель Gateway с соответствующим listeners[].hostname. При этом listeners[].port устанавливается в 80, а listeners[].protocol — в HTTP. Правила Ingress с одинаковым именем хоста генерируют правила HTTPRoute в HTTPRoute, где hostnames содержит этот хост как единственный элемент. Если поле пустое, аналогично defaultBackend, создаётся Gateway Listener без указания hostname (если он ещё не существует), а правила маршрутизации добавляются в catchall HTTPRoute.

rules[].http.paths[].path

Это поле преобразуется в конфигурацию rules[].matches[].path.value в HTTPRoute.

rules[].http.paths[].pathType

Это поле преобразуется в конфигурацию rules[].matches[].path.type в HTTPRoute. Exact в Ingress соответствует совпадению Exact в HTTPRoute. Prefix в Ingress соответствует совпадению PathPrefix в HTTPRoute.

rules[].http.paths[].backend

Указанный бэкенд преобразуется в элемент rules[].backendRefs[] HTTPRoute.

Участие в проекте

Обсуждение проекта ведётся в том же Slack-канале и на тех же встречах сообщества, что и остальные активности подпроекта Gateway API. Подробнее смотрите на странице Gateway API Community.

Кодекс поведения

Участие в сообществе Kubernetes регулируется Кодексом поведения Kubernetes.

Ingress2gateway: миграция с Ingress на Gateway API

Область применения

Провайдеры и эмиттеры

Поддерживаемые провайдеры

Поддерживаемые эмиттеры

Установка

Через go install

На macOS и Linux через Homebrew

Сборка из исходного кода

Использование

Параметры

Команда print

Флаги, специфичные для провайдеров

Поддержка версий Gateway API

Преобразование ресурсов Ingress в Gateway API

Порядок обработки и конфликты

Сопоставление полей Ingress с полями Gateway API

Участие в проекте

Кодекс поведения

Похожее

Команда `print`