Установка контроллера Gwin

Статья создана

Улучшена

Обновлена 13 марта 2026 г.

Необходимые платные ресурсы
Перед началом работы
Установите Gwin
- Установка с помощью Yandex Cloud Marketplace
- Установка с помощью Helm-чарта
Подготовьте тестовое приложение
Проверьте результат
Удалите созданные ресурсы

Gwin — инструмент для управления балансировщиками нагрузки Yandex Application Load Balancer в кластерах Yandex Managed Service for Kubernetes.

Следуя этому руководству, вы установите в кластер Managed Service for Kubernetes контроллер Gwin. По конфигурации ресурсов Ingress или Gateway API контроллер автоматически развернет балансировщик Application Load Balancer, который:

автоматически получает динамический публичный IP-адрес;
принимает HTTP-трафик на порт 80;
принимает HTTPS-трафик на порт 443, используя сертификат Certificate Manager;
отправляет GET-запросы к тестовому сервису example-service.

Важно

Не изменяйте и не удаляйте балансировщик нагрузки и его дочерние ресурсы, созданные с помощью Managed Service for Kubernetes, через интерфейсы Yandex Cloud (консоль управления, Terraform, CLI и API). Это может привести к некорректной работе кластера.

Необходимые платные ресурсы

В стоимость поддержки инфраструктуры входит:

Плата за мастер Managed Service for Kubernetes (см. тарифы Managed Service for Kubernetes).
Плата за узлы кластера Managed Service for Kubernetes: использование вычислительных ресурсов и хранилища (см. тарифы Compute Cloud).
Плата за публичные IP-адреса для хостов кластера Managed Service for Kubernetes и узлов кластера Managed Service for Kubernetes, если для них включен публичный доступ (см. тарифы Virtual Private Cloud).
Плата за использование вычислительных ресурсов балансировщика (см. тарифы Application Load Balancer).

Перед началом работы

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.
Создайте группы безопасности для кластера Managed Service for Kubernetes и входящих в него групп узлов.

Также настройте группы безопасности, необходимые для работы Application Load Balancer.

Важно

От настройки групп безопасности зависит работоспособность и доступность кластера, а также запущенных в нем сервисов и приложений.
Создайте кластер Managed Service for Kubernetes. При создании укажите группы безопасности, подготовленные ранее.
Создайте группу узлов. Выделите ей публичный адрес, чтобы предоставить доступ в интернет и возможность скачивать Docker-образы и компоненты. Укажите группы безопасности, подготовленные ранее.
Установите kubectl и настройте его на работу с созданным кластером.
Создайте сервисный аккаунт IAM, от имени которого контроллер будет создавать ресурсы Application Load Balancer, и назначьте ему роли на каталог:
- alb.editor — для создания необходимых ресурсов Application Load Balancer.
- vpc.publicAdmin — для управления внешней сетевой связностью.
- certificate-manager.certificates.downloader — при использовании облачных сертификатов, зарегистрированных в сервисе Yandex Certificate Manager.
- certificate-manager.editor — при использовании сертификатов кластеров Managed Service for Kubernetes. В этом случае контроллер создает соответствующие им облачные сертификаты.
- compute.viewer — для использования узлов кластера Managed Service for Kubernetes в целевых группах L7-балансировщика.
- k8s.viewer — для определения, в какой сети контроллеру нужно развернуть L7-балансировщик.
- (опционально) smart-web-security.editor — для подключения профиля безопасности Yandex Smart Web Security к виртуальному хосту L7-балансировщика.
- (опционально) logging.writer — при указании в ресурсе Gateway лог-группы для записи логов L7-балансировщика в Yandex Cloud Logging.
Выберите способ аутентификации Gwin в API Yandex Cloud для создания и управления балансировщиками нагрузки Yandex Application Load Balancer.

Аутентификация осуществляется с помощью IAM-токена с ограниченным сроком жизни. Получить IAM-токен изнутри кластера можно следующими инструментами:
- Федерация сервисных аккаунтов (Workload Identity Federation) — связь между внешними системами и Yandex Cloud по протоколу OpenID Connect (OIDC) без использования долгоживущих ключей. Это более безопасный способ, минимизирующий риск утечки учетных данных и возможность несанкционированного доступа.
- Авторизованный ключ — ключ с алгоритмом шифрования RSA-2048 или RSA-4096 с неограниченным сроком жизни.
Федерация сервисных аккаунтов

Авторизованный ключ
1. Настройте поддержку федерации сервисных аккаунтов в кластере и группе узлов.
2. Создайте федерацию сервисных аккаунтов:
  - В качестве Значение Issuer (iss) и Допустимые значения Audience (aud) используйте значение URL эмитента, полученное при настройке кластера.
  - В качестве Адрес JWKS используйте значение URL набора ключей JWKS, полученное при настройке кластера.
3. Привяжите сервисный аккаунт IAM к федерации.
  
  В качестве идентификатора внешнего субъекта используйте следующее значение:
  system:serviceaccount:<пространство_имен>:<имя_сервисного_аккаунта_Kubernetes>
  Где:
  - <пространство_имен> — пространство имен кластера, в которое вы хотите установить Gwin.
  - <имя_сервисного_аккаунта_Kubernetes> — имя сервисного аккаунта Kubernetes для Gwin. По умолчанию — gwin.
    
    Совет
    
    Чтобы переопределить имя сервисного аккаунта Kubernetes для Gwin, при установке с помощью Helm-чарта используйте параметр --set controller.names.serviceAccount=<имя_сервисного_аккаунта_Kubernetes>.
Подробнее см. на странице Доступ к API Yandex Cloud из кластера Managed Service for Kubernetes с помощью федерации сервисных аккаунтов Identity and Access Management.
Создайте авторизованный ключ для сервисного аккаунта IAM в формате JSON и сохраните его в файл sa-key.json:
```
yc iam key create \
  --service-account-name <имя_сервисного_аккаунта_IAM> \
  --output sa-key.json
```

Установите Gwin

Установка с помощью Yandex Cloud Marketplace

Перейдите на страницу каталога и выберите сервис Managed Service for Kubernetes.
Нажмите на имя нужного кластера Managed Service for Kubernetes и выберите вкладку Marketplace.
В разделе Доступные для установки приложения выберите Gwin и нажмите кнопку Перейти к установке.
Задайте настройки приложения:
- Пространство имен — создайте новое пространство имен (например, gwin-space). Если вы оставите пространство имен по умолчанию, Gwin может работать некорректно.
- Название приложения — укажите название приложения.
- Идентификатор каталога — укажите идентификатор каталога, в котором будет работать Gwin.
В зависимости от того, какой способ аутентификации вы выбрали, укажите один из параметров:
- Ключ сервисного аккаунта — скопируйте содержимое файла sa-key.json.
- Сервисный аккаунт, привязанный к WLIF — выберите сервисный аккаунт IAM, настроенный ранее.
Нажмите кнопку Установить.
Дождитесь перехода приложения в статус Deployed.

Установка с помощью Helm-чарта

Установите менеджер пакетов Helm версии не ниже 3.8.0.

Для установки Helm-чарта с контроллером Gwin в зависимости от выбранного способа аутентификации выполните команду:

Федерация сервисных аккаунтов

Авторизованный ключ

helm pull oci://cr.yandexcloud.kz/yc-marketplace/yandex-cloud/gwin/gwin-chart \
  --version v1.0.10 \
  --untar \
helm install \
  --namespace <пространство_имен> \
  --create-namespace \
  --set controller.folderId=<идентификатор_каталога> \
  --set controller.ycServiceAccount.workloadIdentityFederation.serviceAccountID=<идентификатор_сервисного_аккаунта_IAM> \
  gwin ./gwin-chart

helm pull oci://cr.yandexcloud.kz/yc-marketplace/yandex-cloud/gwin/gwin-chart \
  --version v1.0.10 \
  --untar \
helm install \
  --namespace <пространство_имен> \
  --create-namespace \
  --set controller.folderId=<идентификатор_каталога> \
  --set-file controller.ycServiceAccount.secret.value=./sa-key.json \
  gwin ./gwin-chart

Если вы укажете в параметре namespace пространство имен по умолчанию, Gwin может работать некорректно. Рекомендуется указывать значение, отличное от всех существующих пространств имен (например, gwin-space).

Идентификатор каталога можно запросить со списком каталогов в облаке.

Подготовьте тестовое приложение

Чтобы проверить работу контроллера Gwin, создайте тестовое приложение example-app:

Создайте пользовательский сертификат для домена, который будет использоваться приложением:
```
openssl req -x509 -newkey rsa:4096 -keyout example-com.key -out example-com.crt -days 365 -nodes -subj \
"/C=RU/ST=Moscow/L=Moscow/O=Example/OU=IT/CN=example.com"
```
Команда выпустит самоподписанный сертификат и сгенерирует для него приватный ключ. Будут созданы два файла:
- example-com.crt — для сертификата.
- example-com.key — для приватного ключа.

Добавьте сертификат в Certificate Manager:

yc certificate-manager certificate create \
  --folder-id <идентификатор_каталога> \
  --name example-certificate \
  --chain example-com.crt \
  --key example-com.key

Проверьте результат и сохраните идентификатор сертификата, указанный в поле id:

id: fpqmg47avvim********
folder_id: b1g7gvsi89m3********
created_at: "2020-09-15T06:54:44.916325Z"
...
issued_at: "2020-09-15T06:54:44.916325Z"
not_after: "2021-09-15T06:48:26Z"
not_before: "2020-09-15T06:48:26Z"

Создайте для приложения пространство имен:
```
kubectl create namespace example-ns
```

В отдельной директории создайте конфигурационный файл приложения example-app.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-deployment
  namespace: example-ns
  labels:
    app: example-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: example-app
  template:
    metadata:
      labels:
        app: example-app
    spec:
      containers:
      - name: nginx
        image: nginx:alpine
        ports:
        - containerPort: 80
        volumeMounts:
        - name: config-volume
          mountPath: /etc/nginx/conf.d
      volumes:
      - name: config-volume
        configMap:
          name: example-html
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: example-html
  namespace: example-ns
data:
  default.conf: |
    server {
        listen 80;
        server_name _;
        
        location / {
            return 200 'Hello World';
            add_header Content-Type text/plain;
        }
    }
---
apiVersion: v1
kind: Service
metadata:
  name: example-service
  namespace: example-ns
  labels:
    app: example-app
spec:
  type: NodePort
  ports:
  - port: 80
    targetPort: 80
    nodePort: 30080
    protocol: TCP
    name: http
  selector:
    app: example-app

В той же директории создайте конфигурационный файл resources.yaml для ресурсов Gateway API или Ingress:

Gateway API

Ingress

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
  namespace: example-ns
  annotations:
    gwin.yandex.cloud/securityGroups: <идентификаторы_групп_безопасности_балансировщика>
spec:
  gatewayClassName: gwin-default
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      hostname: "example.com"
      allowedRoutes:
        namespaces:
          from: Same
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "example.com"
      allowedRoutes:
        namespaces:
          from: Same
      tls:
        certificateRefs:
          - group: gwin.yandex.cloud
            kind: YCCertificate
            name: example-certificate
  addresses:
    - type: gwin.yandex.cloud/autoIPv4
      value: auto
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: example-redirect-httproute
  namespace: example-ns
spec:
  hostnames:
    - "example.com"
  parentRefs:
    - name: example-gateway
      sectionName: http
  rules:
    - filters:
        - type: RequestRedirect
          requestRedirect:
            scheme: https
            statusCode: 301
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: example-httproute
  namespace: example-ns
spec:
  hostnames:
    - "example.com"
  parentRefs:
    - name: example-gateway
      sectionName: https
  rules:
    - matches:
        - path:
            value: /api
            type: PathPrefix
          method: GET
      backendRefs:
        - kind: Service
          name: example-service
          port: 80
---
apiVersion: gwin.yandex.cloud/v1
kind: YCCertificate
metadata:
  name: example-certificate
  namespace: example-ns
spec:
  certificateRef:
    certificateID: "<идентификатор_сертификата>"

Используйте идентификатор сертификата, сохраненный ранее.

Чтобы узнать идентификаторы групп безопасности, получите информацию об L7-балансировщике.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  namespace: example-ns
  annotations:
    gwin.yandex.cloud/groupName: example
    gwin.yandex.cloud/externalIPv4Address: auto
    gwin.yandex.cloud/rules.allowedMethods: "GET"
    gwin.yandex.cloud/securityGroups: <идентификаторы_групп_безопасности_балансировщика>
spec:
  ingressClassName: gwin-default
  rules:
    - host: example.com
      http:
        paths:
          - pathType: Prefix
            path: "/api"
            backend:
              service:
                name: example-service
                port:
                  number: 80
  tls:
    - hosts:
        - example.com
      secretName: "yc-certmgr-cert-id-<идентификатор_сертификата>"

Используйте идентификатор сертификата, сохраненный ранее.

Чтобы узнать идентификаторы групп безопасности, получите информацию об L7-балансировщике.

Примечание

В примерах конфигураций балансировщику присваивается динамический публичный IP-адрес. При удалении балансировщика из облака также будет удален его IP-адрес. Чтобы избежать потери IP-адреса в производственной среде, резервируйте и используйте статический IP-адрес.

Примените файлы конфигурации:

kubectl apply -f example-app.yaml && \
kubectl apply -f resources.yaml

Проверьте результат

Убедитесь, что балансировщик Application Load Balancer создан:
Gateway API

Ingress
1. Выполните команду:
  kubectl get gateway -n example-ns example-gateway
2. Проверьте, что в поле ADDRESS вывода команды отображается IP-адрес балансировщика:
  NAME CLASS ADDRESS PROGRAMMED AGE example-gateway gwin-default <IP-адрес> 32h
1. Выполните команду:
  kubectl get ingress -n example-ns example-ingress
2. Проверьте, что в поле ADDRESS вывода команды отображается IP-адрес балансировщика:
  NAME CLASS HOSTS ADDRESS PORTS AGE example-ingress gwin-default example.com <IP-адрес> 80, 443 31h

Убедитесь, что при запросах к тестовому приложению выполняется перенаправление с HTTP на HTTPS:

curl -I <IP-адрес_балансировщика> -H "Host:example.com"

Ожидаемый результат:

HTTP/1.1 301 Moved Permanently
location: https://example.com:443/
date: Sat, 06 Sep 2025 23:09:19 GMT
server: ycalb
transfer-encoding: chunked

Убедитесь, что выполняются HTTPS-запросы к тестовому приложению:

curl --resolve example.com:443:<IP-адрес_балансировщика> \
  --cacert example-com.crt \
  https://example.com/api/hello

Ожидаемый результат:

Hello World

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

Некоторые ресурсы платные. Удалите ресурсы, которые вы больше не будете использовать, чтобы за них не списывалась плата:

Удалите кластер Managed Service for Kubernetes.
Удалите балансировщик Application Load Balancer.

Установка контроллера Gwin

Необходимые платные ресурсыНеобходимые платные ресурсы

Перед началом работыПеред началом работы

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

Установка с помощью Yandex Cloud MarketplaceУстановка с помощью Yandex Cloud Marketplace

Установка с помощью Helm-чартаУстановка с помощью Helm-чарта

Подготовьте тестовое приложениеПодготовьте тестовое приложение

Проверьте результатПроверьте результат

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

Была ли статья полезна?