Миграция с ALB Ingress Controller на Gwin

С помощью этой инструкции вы перенесете приложения Kubernetes с Ingress-контроллера Application Load Balancer на новый контроллер Gwin для Managed Service for Kubernetes.

Чтобы мигрировать приложение с Ingress-контроллера Application Load Balancer на контроллер Gwin:

1. Установите Gwin.
2. Запустите скрипт конвертации.
3. Создайте новые ресурсы в кластере.
4. Проверьте корректность балансировки нагрузки.
5. Перенаправьте трафик на новый балансировщик нагрузки.
6. Удалите ненужные ресурсы.

Установите GwinУстановите Gwin

Разверните контроллер Gwin в вашем кластере по инструкции. Контроллер не будет реагировать на ресурсы контроллера ALB Ingress, поскольку в его спецификации используется другой ingressClassName.

Запустите скрипт конвертацииЗапустите скрипт конвертации

Для автоматического преобразования существующих ресурсов контроллера ALB Ingress в формат контроллера Gwin используется инструмент alb-ingress-converter.

Конвертер выполняет следующие преобразования ресурсов Kubernetes:

• IngressClass — изменяет класс ALB Ingress на gwin-default.
• Аннотации — преобразует ingress.alb.yc.io/* в формат gwin.yandex.cloud/*.
• Backend Groups — преобразует HttpBackendGroup/GrpcBackendGroup в IngressBackendGroup.
• Storage Buckets — преобразует ссылки на бакеты Object Storage в ресурсы YCStorageBucket.
• Services — создает ресурсы IngressBackendGroup для групп бэкендов при необходимости.
• Path Types — обновляет типы путей для поддержки регулярных выражений (ImplementationSpecific).

Чтобы запустить скрипт конвертации:

1. Загрузите бинарный файл конвертера и сделайте его исполняемым. Файл хранится в публичном бакете Object Storage. Доступны сборки для следующих ОС:

   • Linux AMD64
   • Linux ARM64
   • macOS AMD64
   • macOS ARM64
   • Windows AMD64
   • Windows ARM64

   Пример загрузки файла для Linux:

   wget https://storage.yandexcloud.kz/gwin/utils/alb-ingress-converter/alb-ingress-converter-v1.0.0.linux-amd64.tar.gz &&
   tar -xzf alb-ingress-converter-v1.0.0.linux-amd64.tar.gz &&
   chmod +x alb-ingress-converter
   

2. (Опционально) Экспортируйте все ресурсы ALB Ingress из вашего кластера с помощью команды:

   kubectl get ingress,ingressclasses,ingressgroupsettings,httpbackendgroups,grpcbackendgroups,services \
       -A -o yaml > current-resources.yaml
   

   Также вы сможете запустить конвертер и получить ресурсы напрямую из кластера. При этом конвертер может использовать конфигурацию kubectl по умолчанию или конфигурацию, заданную в параметре -kubeconfig.

3. Запустите конвертер. Доступно несколько способов запуска:

   • Базовое использование конвертера:

     # Конвертация из файлов
     ./alb-ingress-converter -input-files current-resources.yaml
     
     # Конвертация напрямую из кластера
     ./alb-ingress-converter
     

   • Использование конвертера с расширенными опциями:

     # Указание директории для результатов
     ./alb-ingress-converter -input-files input.yaml -output-dir ./migration-output
     
     # Добавление префиксов/суффиксов к именам для избежания конфликтов
     ./alb-ingress-converter -input-files input.yaml -add-name-suffix "-migrated"
     
     # Сохранение diff-файлов для просмотра изменений
     ./alb-ingress-converter -input-files input.yaml -save-diff
     
     # Только валидация (без генерации вывода)
     ./alb-ingress-converter -input-files input.yaml -validate-only
     
     # Обработка нескольких файлов или директорий
     ./alb-ingress-converter -input-files file1.yaml,file2.yaml
     ./alb-ingress-converter -input-dirs ./manifests -recursive
     

     Для конвертера доступны параметры, перечисленные в таблице ниже.

     Флаг	Описание
     -kubeconfig	Путь к конфигурации kubectl.
     -input-files	Список YAML-файлов с исходной конфигурацией ресурсов через запятую.
     -input-dirs	Список директорий с исходной конфигурацией ресурсов через запятую.
     -recursive	Рекурсивное сканирование директорий. По умолчанию: false.
     -output-dir	Выходная директория. По умолчанию: ./alb-ingress-converter-output.
     -output-format	Формат вывода: files или stdout. По умолчанию: files.
     -save-diff	Сохранение diff-файлов с изменениями. По умолчанию: false.
     -validate-only	Только валидация входных файлов. По умолчанию: false.
     -add-name-prefix	Добавление префикса к именам генерируемых ресурсов. По умолчанию: "".
     -add-name-suffix	Добавление суффикса к именам генерируемых ресурсов. По умолчанию: "".
     -ingress-controller-name	Имя контроллера для фильтрации. По умолчанию: ingress.alb.yc.io/yc-alb-ingress-controller.

4. Проверьте результат работы конвертера. Директория с файлами вывода организована следующим образом:

   output/
   ├── alb-ingress/ # Оригинальные ресурсы ALB Ingress
   │   ├── ...
   ├── gwin/ # Преобразованные ресурсы Gwin
   │   ├── ...
   └── diff/  # Diff файлы (если использован параметр -save-diff)
       └── ...
   

Создайте новые ресурсы в кластереСоздайте новые ресурсы в кластере

Просмотрите преобразованные ресурсы и примените их к вашему кластеру:

1. Проверьте сгенерированные YAML-файлы в папке gwin.
2. Примените их с помощью команды kubectl apply -f <YAML_файл>. В результате будет создан новый балансировщик нагрузки.
3. Убедитесь, что все ресурсы созданы успешно. Для этого проверьте статус ресурсов командой kubectl get.

Новый балансировщик нагрузки будет создан без удаления существующего.

Проверьте корректность балансировки нагрузкиПроверьте корректность балансировки нагрузки

Протестируйте новый балансировщик нагрузки, чтобы убедиться в его корректной работе:

1. Получите IP-адрес нового балансировщика нагрузки:
   • Запросите статус ресурса Ingress командой kubectl get Ingress.
   • В консоли управления:
     • Перейдите на страницу кластера Managed Service for Kubernetes.
     • На панели слева выберите Сеть.
     • Перейдите на вкладку Ingress.
2. Убедитесь, что маршрутизация работает, как ожидается. Для этого протестируйте доступность HTTP/HTTPS-эндпоинтов вашего приложения.
3. Убедитесь, что проверки статуса бэкендов показывают их работоспособность.
4. Проверьте наличие ошибок в логах и наличие признаков проблем с производительностью в метриках балансировщика.

Перенаправьте трафик на новый балансировщик нагрузкиПеренаправьте трафик на новый балансировщик нагрузки

1. Обновите DNS-записи ваших доменов на IP-адрес нового балансировщика нагрузки для перенаправления трафика.
2. Следите за метриками приложения во время переключения трафика.
3. Убедитесь, что функциональность приложения полностью доступна после перенаправления трафика.

Удалите ненужные ресурсыУдалите ненужные ресурсы

1. Удалите старые ресурсы ALB Ingress — оригинальные Ingress-контроллеры, группы бэкендов и т. д.
2. Удалите приложение ALB Ingress Controller.
3. Удалите неиспользуемые балансировщики нагрузки или сертификаты.

Решение проблемРешение проблем

Ошибки в работе конвертераОшибки в работе конвертера

Ресурсы не найдены (No resources found):

• Убедитесь, что ресурсы IngressClass включены во входные данные.
• Проверьте, что фильтр имени контроллера соответствует вашей настройке.

Примеры изменения ресурсов при конвертацииПримеры изменения ресурсов при конвертации

Базовая конвертация ресурса IngressБазовая конвертация ресурса Ingress

До конвертации (класс ALB Ingress):

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.alb.yc.io/group-name: "my-group"
    ingress.alb.yc.io/security-groups: "sg-1,sg-2"
spec:
  ingressClassName: yc-alb-ingress
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: grpc-service
            port:
              number: 80

После конвертации (класс Gwin):

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    gwin.yandex.cloud/groupName: "my-group"
    gwin.yandex.cloud/securityGroups: "sg-1,sg-2"
spec:
  ingressClassName: gwin-default
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          resource:
            apiGroup: gwin.yandex.cloud
            kind: IngressBackendGroup
            name: grpc-service-80

Конвертация группы бэкендовКонвертация группы бэкендов

До конвертации (версия ALB Ingress):

apiVersion: alb.yc.io/v1alpha1
kind: HttpBackendGroup
metadata:
  name: weighted-backends
spec:
  backends:
  - name: v1
    service:
      name: app-v1
      port:
        number: 8080
    weight: 70

После конвертации (версия Gwin):

apiVersion: gwin.yandex.cloud/v1
kind: IngressBackendGroup
metadata:
  name: weighted-backends
spec:
  type: HTTP
  backends:
  - name: v1
    backendRef:
      name: app-v1
      port: 8080
    weight: 70