Руководство администратора

Процесс публикации приложения с помощью модуля alb включает следующие шаги:

1. Создание cluster-scoped (используется ресурс ClusterALBInstance) или в неймспейсе (используется ресурс ALBInstance) объекта Gateway (шлюз).
2. Для HTTP/HTTPS-, gRPC- или TLS-трафика — создание объекта ListenerSet, который привязывается к созданному на предыдущем шаге объекту Gateway и управляет приёмом входящих запросов.
3. Создание объектов-маршрутов и их привязка к нужному родителю:
   • HTTPRoute, GRPCRoute и TLSRoute — к ListenerSet;
   • TCPRoute и UDPRoute для обычных TCP/UDP-портов из additionalPorts — напрямую к слушателю Gateway (контроллер обновляет слушатели Gateway из additionalPorts; отдельный ListenerSet для этих портов создавать не нужно).

Примеры настройки обычного TCP/UDP приведены в разделе «Открытие дополнительного TCP/UDP-порта».

Совместное использование с другими модулями и сторонним решениями

Модуль alb может использоваться в кластере одновременно с модулем ingress-nginx. В таком случае для каждого из них рекомендуется использовать отдельный объект ClusterIssuer.

Это позволяет выпускать отдельные сертификаты для схемы с Ingress (с использованием модуля ingress-nginx) и для схемы с Gateway API (с использованием модуля alb), раздельно управляя настройками и жизненными циклами сертификатов.

Использование сторонних решений Gateway API допускается при условии, что в кластере используются следующие, совместимые с контроллером модуля alb, версии API для объектов Gateway API:

• BackendTLSPolicy: v1;
• GatewayClass: v1;
• Gateway: v1;
• ListenerSet: v1;
• GRPCRoute: v1;
• HTTPRoute: v1;
• ReferenceGrant: v1beta1;
• TCPRoute: v1alpha2/v1;
• UDPRoute: v1alpha2/v1;
• TLSRoute: v1.

Контроллер модуля alb в процессе запуска проверяет текущие хранимые версии объектов Gateway API и в случае обнаружения расхождения между установленными и требуемыми версиями, прекращает работу. Если же в кластере полностью отсутствует тот или иной тип объекта Gateway API, нужная версия будет создана контроллером автоматически и он продолжит работу.

Для ручной проверки совместимости версий установленных объектов Gateway API в кластере можно использовать команду:

declare -A want=([gatewayclasses.gateway.networking.k8s.io]=v1 [gateways.gateway.networking.k8s.io]=v1 [grpcroutes.gateway.networking.k8s.io]=v1 [httproutes.gateway.networking.k8s.io]=v1 [listenersets.gateway.networking.k8s.io]=v1 [referencegrants.gateway.networking.k8s.io]=v1beta1 [tcproutes.gateway.networking.k8s.io]="v1|v1alpha2" [udproutes.gateway.networking.k8s.io]="v1|v1alpha2" [tlsroutes.gateway.networking.k8s.io]=v1 [backendtlspolicies.gateway.networking.k8s.io]=v1); for crd in "${!want[@]}"; do got="$(d8 k get crd "$crd" -o jsonpath='{.spec.versions[?(@.storage==true)].name}' 2>/dev/null || true)"; if [[ -n "$got" && "$got" =~ ^(${want[$crd]})$ ]]; then echo "$crd OK storage=$got"; else echo "$crd FAILED cluster=${got:-MISSING} expected=${want[$crd]}"; fi; done | sort

В остальном модуль конфигурирует и управляет только объектами Gateway определённого GatewayClass, что минимизирует риск возникновения конфликтов при использовании сторонних решений Gateway API.

Особенности использования ресурсов ClusterALBInstance и ALBInstance

Для публикации пользовательских приложений может использоваться ресурс ClusterALBInstance или ALBInstance. ClusterALBInstance также может использоваться для доступа к системным доменам кластера DKP. В таком случае перед включением модуля alb убедитесь в том, что указан глобальный параметр publicDomainTemplate. А после включения модуля настройте доступ к системным компонентам через ClusterALBInstance.

Автоматически управляемые ресурсы безопасности

SecurityPolicyException для инлета HostPort

Если в кластере доступен API SecurityPolicyException, предоставляемый модулем admission-policy-engine, модуль alb автоматически создаёт SecurityPolicyException (SPE) для каждого ClusterALBInstance с инлетом HostPort. SPE разрешает подам прокси использовать только TCP- и UDP-порты узла, настроенные в ClusterALBInstance. Остальные проверки Pod Security Standards продолжают действовать. Создавать SPE вручную не требуется.

Контроллер обновляет SPE при изменении портов и удаляет его вместе с ClusterALBInstance. Ссылка на SPE добавляется в шаблон пода независимо от доступности API, поэтому включение или отключение admission-policy-engine само по себе не приводит к перезапуску подов прокси.

SecurityPolicyException для init-контейнера Istio

Если доступен API SPE и в ALBInstance или ClusterALBInstance включён параметр istioSidecar.enabled, модуль также создаёт отдельный SPE для внедрённого контейнера istio-init. Он разрешает только запуск с UID 0 и добавление capabilities NET_ADMIN и NET_RAW, необходимых для настройки перенаправления трафика. На остальные контейнеры и проверки Pod Security Standards это исключение не распространяется. При недоступном API ссылка на SPE остаётся в шаблоне пода.

Настройка доступа к системным компонентам DKP с использованием Gateway API

Для предоставления доступа к системным доменам кластера DKP с использованием модуля alb укажите шлюз по умолчанию. Для этого выполните следующие действия:

1. Включите модуль alb в конфигурации кластера. Параметры модуля и порядок включения описаны на странице «Настройки модуля».
2. Создайте cluster-scoped объект ClusterALBInstance с нужным типом инлета и настройками.
3. Установите параметр spec.defaultDeckhouseGateway: true для данного ClusterALBInstance.
4. После применения изменений проверьте статус объекта ClusterALBInstance:

d8 k get clusteralbinstances

У объекта ClusterALBInstance должен появиться управляемый объект Gateway, а сам инстанс должен перейти в готовое состояние. После этого в соответствующих системных неймспейсах кластера должны появиться системные объекты ListenerSet и HTTPRoute.

d8 k get httproutes -A -l heritage=deckhouse -o json | jq -r '["MODULE","GATEWAY API SUPPORT"], (.items | map(.metadata.labels.module // "UNKNOWN") | unique[] | ["d8-" + ., "yes"]) | @tsv' | column -t -s $'\t'

Алгоритм выбора шлюза DKP по умолчанию при использовании нескольких ClusterALBInstance

В кластере может быть одновременно несколько cluster-scoped Gateway, помеченных как шлюз по умолчанию (флаг defaultDeckhouseGateway: true для соответствующих ClusterALBInstance). В этом случае шлюзом по умолчанию становится объект Gateway, созданный самым старым объектом ClusterALBInstance по creationTimestamp. Если ни один объект ClusterALBInstance не отмечен как шлюз по умолчанию, DKP допускает использование объекта Gateway, созданного модулем alb для инстанса с именем main, в качестве шлюза по умолчанию.

Смена шлюза DKP по умолчанию

Если системные домены DKP необходимо перенести на другой объект Gateway, выполните следующие шаги:

1. Создайте новый объект ClusterALBInstance, описывающий необходимые настройки, и задайте в нём параметр spec.defaultDeckhouseGateway: true.
2. В текущем объекте ClusterALBInstance, который предоставляет шлюз DKP по умолчанию, задайте spec.defaultDeckhouseGateway: false.
3. Проверьте, что все системные объекты ListenerSet теперь ссылаются на новый объект Gateway в spec.parentRef.

Смена инлета с сохранением текущего Gateway

Чтобы сменить инлет, используемый для уже созданного объекта Gateway, выполните следующие действия:

1. Создайте новый объект ClusterALBInstance или объект ALBInstance с другим именем, но с тем же значением spec.gatewayName, используя нужный тип инлета.
2. Проверьте, что новый путь приёма трафика работает корректно.
3. Удалите неактуальный объект ClusterALBInstance или объект ALBInstance.

Так как gatewayName не меняется, объект Gateway остаётся прежним. В большинстве случаев объект ListenerSet и маршруты при этом можно не пересоздавать.

Открытие дополнительного TCP/UDP-порта на общекластерном Gateway

Если кроме стандартных HTTP/HTTPS-слушателей на шлюзе (Gateway) нужен отдельный TCP/UDP-порт, добавьте в соответствующий ClusterALBInstance поле spec.inlet.additionalPorts с описанием порта. Пример:

spec:
  gatewayName: public-gw
  inlet:
    type: LoadBalancer
    loadBalancer: {}
    additionalPorts:
      - port: 9000
        protocol: TCP

Контроллер добавит на управляемый ClusterALBInstance’ом объект Gateway соответствующий обработчик TCP-трафика с именем секции (sectionName) вида tcp-port-9000. Затем можно создать объект (маршрут) TCPRoute, который будет ссылаться на этот объект Gateway и этот sectionName напрямую:

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
  name: app-tcp
  namespace: prod
spec:
  parentRefs:
    - name: public-gw
      namespace: d8-alb
      sectionName: tcp-port-9000
      port: 9000
  rules:
    - backendRefs:
        - name: tcp-svc
          port: 9000

Конфликты портов в случае использования нескольких ClusterALBInstance/ALBInstance для одного Gateway

Если один и тот же объект Gateway управляется несколькими объектами ClusterALBInstance/ALBInstance, результирующий набор слушателей, который попадает в объект Gateway, берётся из самого старого объекта ClusterALBInstance/ALBInstance. Для остальных инстансов (ClusterALBInstance/ALBInstance) в статусе появится признак конфликта портов с указанием наименования “управляющего” инстанса.

Просмотр конфигурации Envoy Proxy

Для диагностики полезно посмотреть, какую конфигурацию контроллер и конфигуратор прокси передали в Envoy Proxy, обслуживающий объект Gateway.

Для этого выполните следующие действия:

1. Выберите под Envoy Proxy для нужного объекта Gateway:

   d8 k -n d8-alb get pods -l alb.deckhouse.io/gateway=shared-gateway

2. Получите конфигурацию пода с помощью команды:

   d8 k -n d8-alb exec -it <envoy-proxy-pod-name> -- pilot-agent request GET /config_dump

   Если нужен только отдельный раздел конфигурации, можно явно указать интересующий раздел:

   d8 k -n d8-alb exec -it <envoy-proxy-pod-name> -- pilot-agent request GET /config_dump?resource=dynamic_listeners
   d8 k -n d8-alb exec -it <envoy-proxy-pod-name> -- pilot-agent request GET /config_dump?resource=dynamic_route_configs
   d8 k -n d8-alb exec -it <envoy-proxy-pod-name> -- pilot-agent request GET /config_dump?resource=dynamic_active_clusters

Так можно проверить, появились ли ожидаемые обработчики трафика, виртуальные хосты и upstream-кластеры после изменения объекта ListenerSet или объекта Route.