Связаться с экспертомПопробовать бесплатно
Создавайте контент и получайте гранты!Готовы написать своё руководство? Участвуйте в контент-программе и получайте гранты на работу с облачными сервисами!
Подробнее о программе
Проект Яндекса
© 2026 ТОО «Облачные Сервисы Казахстан»

Поля ресурса HTTPRoute

Статья создана
Обновлена 24 июня 2026 г.
Открыть в Markdown

В ресурсе HTTPRoute определяются правила маршрутизации трафика по бэкендам — сервисам Kubernetes (ресурсам Service) или перенаправления трафика. HTTPRoute получает входящий трафик от тех ресурсов Gateway, требованиям которых он соответствует.

Совет

Вместо ALB Ingress-контроллера и Gateway API рекомендуется использовать новый контроллер Yandex Cloud Gwin.

HTTPRoute предназначен для разработчиков приложений. Оператор кластера должен использовать Gateway.

HTTPRoute — ресурс Kubernetes, определенный проектом Kubernetes Gateway API. Ниже описаны поля и аннотации ресурса, с которыми работает Gateway API Application Load Balancer. Полное описание конфигурации ресурса приведено в документации Kubernetes Gateway API.

HTTPRoute

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: <string>
  namespace: <string>
  annotations:
    gateway.alb.yc.io/rules.backends.http.useHTTP2: <bool>
    gateway.alb.yc.io/rules.backends.balancing.mode: <string>
    gateway.alb.yc.io/rules.backends.balancing.localityAwareRouting: <string>
    gateway.alb.yc.io/rules.backends.balancing.strictLocality: <bool>
    gateway.alb.yc.io/rules.backends.balancing.panicThreshold: <string>
    gateway.alb.yc.io/rule.<имя_правила>.backends.balancing.mode: <string>
    gateway.alb.yc.io/rules.backends.hc.timeout: <string>
    gateway.alb.yc.io/rules.backends.hc.interval: <string>
    gateway.alb.yc.io/rules.backends.hc.healthyThreshold: <string>
    gateway.alb.yc.io/rules.backends.hc.unhealthyThreshold: <string>
    gateway.alb.yc.io/rules.backends.hc.port: <string>
    gateway.alb.yc.io/rules.backends.hc.http.path: <string>
    gateway.alb.yc.io/rules.backends.hc.http.useHTTP2: <bool>
    gateway.alb.yc.io/rules.backends.hc.http.host: <string>
    gateway.alb.yc.io/rules.backends.hc.grpc.serviceName: "Check"
    gateway.alb.yc.io/rules.backends.hc.stream.send: <string>
    gateway.alb.yc.io/rules.backends.hc.stream.receive: <string>
    gateway.alb.yc.io/rules.sessionAffinity.header.name: <string>
    gateway.alb.yc.io/rules.sessionAffinity.cookie.name: <string>
    gateway.alb.yc.io/rules.sessionAffinity.cookie.ttl: <string>
    gateway.alb.yc.io/rules.sessionAffinity.sourceIP: <bool>
    gateway.alb.yc.io/rules.timeout: <string>
    gateway.alb.yc.io/rules.idleTimeout: <string>
    gateway.alb.yc.io/rule.<имя_правила>.timeout: <string>
    gateway.alb.yc.io/rule.<имя_правила>.idleTimeout: <string>
    gateway.alb.yc.io/rules.httpUpgradeTypes: <string>
    gateway.alb.yc.io/rules.securityProfileId: <string>
    gateway.alb.yc.io/rules.rbac.action: <string>
    gateway.alb.yc.io/rules.rbac.principals.<имя_группы>.<имя_принципала>.header.name: <string>
    gateway.alb.yc.io/rules.rbac.principals.<имя_группы>.<имя_принципала>.header.regex: <string>
    gateway.alb.yc.io/rules.rbac.principals.<имя_группы>.<имя_принципала>.header.exact: <string>
    gateway.alb.yc.io/rules.rbac.principals.<имя_группы>.<имя_принципала>.header.prefix: <string>
    gateway.alb.yc.io/rules.rbac.principals.<имя_группы>.<имя_принципала>.ip.remoteIp: <string>
    gateway.alb.yc.io/rules.rbac.principals.<имя_группы>.<имя_принципала>.any: <bool>
    gateway.alb.yc.io/hosts.securityProfileId: <string>
    gateway.alb.yc.io/hosts.rbac.action: <string>
spec: <HTTPRouteSpec>

Где:

  • apiVersion: gateway.networking.k8s.io/v1

  • kind: HTTPRoute

  • metadata (ObjectMeta, обязательное)

    Метаданные ресурса.

    • name (string, обязательное)

      Имя ресурса. Формат описан в документации Kubernetes.

      Не является именем маршрута в Application Load Balancer.

    • namespace (string)

      Пространство имен, к которому относится ресурс. Значение по умолчанию — default.

    • annotations (map[string]string)

      Аннотации ресурса.

      Примечание

      Вы можете определить ресурс RoutePolicy вместо аннотаций. Набор параметров ресурса RoutePolicy и аннотации HTTPRoute равнозначны.

      • gateway.alb.yc.io/rules.timeout (string)

        Таймаут для HTTP-соединения балансировщика и бэкенда. Соединение поддерживается до истечения указанного времени, независимо от того, происходит ли передача данных. При достижении таймаута ресурс возвращает статус UNAVAILABLE.

      • gateway.alb.yc.io/rules.idleTimeout (string)

        Таймаут неактивного HTTP-соединения, в течение которого отсутствует передача данных. По истечении таймаута возвращает статус 504 Gateway Timeout.

      • gateway.alb.yc.io/rules.securityProfileId (string)

        Идентификатор профиля безопасности Smart Web Security для маршрута.

      • gateway.alb.yc.io/hosts.securityProfileId (string)

        Идентификатор профиля безопасности для хоста.

      • gateway.alb.yc.io/rules.backends.http.useHTTP2

        Использовать HTTP/2 для соединения между балансировщиком и бэкендом.

      • gateway.alb.yc.io/rules.sessionAffinity.header.name

        Имя HTTP-заголовка для привязки сессий (session affinity).

      • gateway.alb.yc.io/rules.sessionAffinity.cookie.name

        Имя cookie для привязки сессий.

      • gateway.alb.yc.io/rules.sessionAffinity.cookie.ttl

        Время жизни cookie для привязки сессий.

      • gateway.alb.yc.io/rules.sessionAffinity.sourceIP

        Признак использования IP-адреса клиента для привязки сессий.

      • gateway.alb.yc.io/rules.backends.balancing.mode

        Режим балансировки нагрузки. Возможные значения: RANDOM, ROUND_ROBIN, LEAST_REQUEST.

      • gateway.alb.yc.io/rules.backends.balancing.localityAwareRouting

        Процент трафика, направляемого в зону доступности ресурса HTTPRoute, где размещены бэкенды в статусе healthy. Остальной трафик делится между другими зонами доступности. Параметр не применяется, если задан strictLocality=true (смотрите ниже).

      • gateway.alb.yc.io/rules.backends.balancing.strictLocality

        Строгая локальность маршрутизации трафика на бэкенды (только в зоне доступности ресурса HTTPRoute)

      • gateway.alb.yc.io/rules.backends.balancing.panicThreshold

        Порог panic mode для балансировки (%).

      • gateway.alb.yc.io/rules.backends.hc.timeout

        Таймаут ответа на проверку состояния.

      • gateway.alb.yc.io/rules.backends.hc.interval

        Интервал между проверками состояния.

      • gateway.alb.yc.io/rules.backends.hc.healthyThreshold

        Количество успешных проверок для присвоения ресурсу статуса healthy.

      • gateway.alb.yc.io/rules.backends.hc.unhealthyThreshold

        Количество неуспешных проверок для присвоения ресурсу статуса unhealthy.

      • gateway.alb.yc.io/rules.backends.hc.port

        Порт для проверок health check.

      • gateway.alb.yc.io/rules.backends.hc.http.path

        Путь для HTTP-проверок health check. Пример: /health. Используется для HTTP(S)-бэкендов.

      • gateway.alb.yc.io/rules.backends.hc.http.useHTTP2

        Использовать HTTP/2 для проверок health check. По умолчанию используется HTTP/1.1. Используется для HTTP(S)-бэкендов.

      • gateway.alb.yc.io/rules.backends.hc.http.host

        Адрес хоста для HTTP-проверок health check.

      • gateway.alb.yc.io/rules.backends.hc.grpc.serviceName

        Имя gRPC-сервиса для проверок health check gRPC-бэкендов.

      • gateway.alb.yc.io/rules.backends.hc.stream.send

        Данные для отправки при TCP health check. Используется для бэкендов с TCP-интерфейсом.

      • gateway.alb.yc.io/rules.backends.hc.stream.receive

        Ожидаемый ответ при TCP health check. Используется для бэкендов с TCP-интерфейсом.

      • gateway.alb.yc.io/rules.timeout

        Общий таймаут HTTP-соединения между балансировщиком и бэкендом.

      • gateway.alb.yc.io/rules.idleTimeout

        Таймаут неактивного HTTP-соединения.

      • gateway.alb.yc.io/rules.httpUpgradeTypes

        Поддерживаемые значения HTTP Upgrade (например, websocket).

      • gateway.alb.yc.io/rules.securityProfileId

        Идентификатор профиля безопасности Smart Web Security для маршрута.

      • gateway.alb.yc.io/rules.rbac.action

        Действие при совпадении заданных условий (ALLOW/DENY) для контроля доступа к бэкендам.

      • gateway.alb.yc.io/rules.rbac.principals.<имя_группы>.<имя_принципала>.header.name

        Имя заголовка для проверок условий RBAC.

      • gateway.alb.yc.io/rules.rbac.principals.<имя_группы>.<имя_принципала>.header.regex

        Регулярное выражение для проверки значения заголовка для управления доступом к хосту по RBAC.

      • gateway.alb.yc.io/rules.rbac.principals.<имя_группы>.<имя_принципала>.header.exact

        Точное значение заголовка для управления доступом к хосту по RBAC.

      • gateway.alb.yc.io/rules.rbac.principals.<имя_группы>.<имя_принципала>.header.prefix

        Префикс значения заголовка для управления доступом к хосту по RBAC.

      • gateway.alb.yc.io/rules.rbac.principals.<имя_группы>.<имя_принципала>.ip.remoteIp

        IP-адрес или CIDR-блок для управления доступом к хосту по RBAC.

      • gateway.alb.yc.io/rules.rbac.principals.<имя_группы>.<имя_принципала>.any

        Любое совпадение заданных условий для управления доступом к хосту по RBAC (true/false).

      • gateway.alb.yc.io/hosts.rbac.action

        Действие при совпадении заданных условий (ALLOW/DENY) для контроля доступа к хосту по RBAC.

      • gateway.alb.yc.io/rule.<имя_правила>.backends.balancing.mode

        Режим балансировки для конкретного правила. Возможные значения: RANDOM, ROUND_ROBIN, LEAST_REQUEST.

      • gateway.alb.yc.io/rule.<имя_правила>.timeout

        Таймаут для конкретного правила балансировки.

      • gateway.alb.yc.io/rule.<имя_правила>.idleTimeout

        Таймаут неактивности для конкретного правила балансировки.

  • spec (HTTPRouteSpec, обязательное)

    Спецификация ресурса. Подробности ниже.

HTTPRouteSpec

parentRefs:
  - group: <string>
    kind: <string>
    namespace: <string>
    name: <string>
    sectionName: <string>
  - ...
hostnames:
  - <string>
  - ...
rules:
  - matches:
      - path:
          type: <string>
          value: <string>
        method: <string>
      - ...
    filters:
      - <HTTPRouteFilter>
      - ...
    backendRefs:
      - group: <string>
        kind: <string>
        name: <string>
        namespace: <string>
        port: <int32>
        weight: <int32>
        filters:
          - <HTTPRouteFilter>
          - ...
      - ...
  - ...

Где:

  • parentRefs ([]ParentReference, обязательное)

    Список ресурсов Gateway (или их обработчиков из поля spec.listeners — подробнее в справочнике), к которым должен быть привязан HTTPRoute.

    Также маршрут должен удовлетворять правилам, описанным в конфигурации Gateway (поле spec.listeners.allowedRoutes).

    • namespace (string)

      Пространство имен, к которому относится ресурс Gateway (указано в его метаданных — в поле metadata.namespace).

      По умолчанию совпадает с пространством имен ресурса HTTPRoute (поле metadata.namespace).

    • name (string, обязательное)

      Имя ресурса Gateway (указано в его метаданных — в поле metadata.name).

    • sectionName (string)

      Имя обработчика, указанного в ресурсе Gateway (указано в поле spec.listeners.name).

  • hostnames ([]string)

    Список доменных имен (значений заголовка Host для HTTP/1.1 или псевдозаголовка :authority для HTTP/2), соответствующих маршруту. Для каждого доменного имени будут созданы виртуальные хосты в HTTP-роутерах.

    Чтобы указать на все возможные поддомены любых уровней, вместо первого уровня доменного имени используйте звездочку *. В этом случае значение нужно обернуть в кавычки.

    Например, значение "*.example.com" соответствует доменным именам foo.example.com, foo-bar.example.com, foo.bar.example.com, foo.bar.baz.example.com и т. п. (но не example.com).

    Заменить звездочкой только часть первого уровня доменного имени, например *foo.example.com, нельзя.

  • rules ([]HTTPRouteRule)

    Правила маршрутизации и перенаправления запросов.

    • matches ([]HTTPRouteMatch)

      Список условий, хотя бы одному из которых должен соответствовать запрос, чтобы к нему было применено правило.

      Например, следующему списку условий будут удовлетворять все запросы к пути /foo методом POST и все запросы к пути /bar любым методом:

      matches:
  - path:
      value: /foo
    method: POST
  - path:
      value: /bar

      Поддерживаются только поля, перечисленные ниже. Другие поля, описанные в справочнике Gateway API (headers, queryParams), не поддерживаются.

      • path (HTTPPathMatch)

        Указание на путь в URI запроса.

        • type (string)

          Тип указания на путь в URI запроса:

          • Exact: путь должен совпадать со значением поля rules.matches.path.value.
          • PathPrefix: путь должен начинаться со значения поля rules.matches.path.value.

          Помимо распределения трафика, от типа зависит механизм замены пути при перенаправлении. Подробности ниже.

        • value (string)

          Путь в URI входящего запроса (если тип — Exact) или его начало (если тип — PathPrefix).

      • method (HTTPMethod)

        HTTP-метод запроса.

    • filters ([]HTTPRouteFilter)

      Список фильтров, которые описывают изменение заголовков запроса при маршрутизации в любой бэкенд или перенаправление запроса. Подробности ниже.

      Разрешается указывать либо фильтр типа RequestHeaderModifier (изменение заголовков), либо фильтр типа RequestRedirect (перенаправление), но не оба сразу.

    • backendRefs ([]HTTPBackendRef)

      Список сервисов Kubernetes, которые должны обрабатывать запрос в качестве бэкенда.

      Можно указать ресурс YCStorageBucket (бакет Object Storage) либо ресурс Service.

      • name (string)

        Имя сервиса Kubernetes или ресурса с бакетом.

      • namespace (string)

        Пространство имен, к которому относится сервис или ресурс с бакетом.

      • group (string)

        Имя группы API Kubernetes, к которой относится ресурс с бакетом, например gwin.yandex.cloud. Только для ресурса YCStorageBucket.

        Значение по умолчанию — пустая строка, обозначающая корневую группу API.

      • kind (string)

        Тип ресурса Kubernetes с бакетом. Только для ресурса YCStorageBucket. Используется значение YCStorageBucket.

      • port (int32)

        Номер порта сервиса. Только для ресурса Service.

        Номер должен совпадать с одним из номеров портов, указанных в полях spec.ports.port ресурса Service. Подробнее в конфигурации ресурса.

        Поле предназначено для работы Gateway API и не соответствует ни одному из полей ресурсов Application Load Balancer.

      • weight (int32)

        Относительный вес бэкенда. Трафик между бэкендами в группе распределяется пропорционально их весам.

        Веса должны быть указаны либо у всех бэкендов в группе, либо ни у одного из них. Между бэкендами без указанных весов трафик распределяется, как если бы у них были указаны одинаковые положительные веса.

        Если указан неположительный вес, бэкенд не будет получать трафик.

      • filters ([]HTTPRouteFilter)

        Настройки изменения заголовков запроса при маршрутизации в бэкенд. Подробности ниже.

        Разрешается указывать только фильтр типа RequestHeaderModifier (изменение заголовков).

HTTPRouteFilter

type: <string>
requestHeaderModifier:
  set:
    - name: <string>
      value: <string>
    - ...
  add:
    - name: <string>
      value: <string>
    - ...
  remove:
    - <string>
    - ...
requestRedirect:
  scheme: <string>
  hostname: <string>
  path:
    type: <string>
    replaceFullPath: <string>
    replacePrefixMatch: <string>
  port: <int32>
  statusCode: <int>

Где:

  • type (string)

    Тип фильтра:

    • RequestHeaderModifier — изменение заголовков запроса. Настройки указываются в поле requestHeaderModifier.
    • RequestRedirect — перенаправление запроса. Настройки указываются в поле requestRedirect.

  • requestHeaderModifier (HTTPRequestHeaderFilter)

    Настройки изменения заголовков запроса для фильтра типа RequestHeaderModifier.

    • set ([]HTTPHeader)

      Список перезаписываемых заголовков.

      • name (string)

        Имя перезаписываемого заголовка.

      • value (string)

        Значение, записываемое в заголовок.

    • add ([]HTTPHeader)

      Список добавляемых заголовков.

      • name (string)

        Имя добавляемого заголовка.

      • value (string)

        Значение добавляемого заголовка.

    • remove ([]string)

      Список имен удаляемых заголовков.

  • requestRedirect (HTTPRequestRedirectFilter)

    Примечание

    Настройки перенаправления для изменения схемы (scheme) и доменного имени (hostname) поддерживаются в Gateway API версии 0.4.31 и выше.

    Установите актуальную версию Gateway API, если нужна поддержка этих настроек.

    Настройки перенаправления запроса для фильтра типа RequestRedirect.

    • scheme (string)

      Новая схема в URI запроса: http или https. По умолчанию схема остается без изменений.

      Чтобы перенаправление работало, для Gateway должен быть настроен обработчик HTTPS-трафика.

      Пример перенаправления запроса с изменением схемы приведен ниже.

    • hostname (string)

      Новое доменное имя в URI запроса. По умолчанию доменное имя остается без изменений.

      Пример перенаправления запроса с изменением доменного имени приведен ниже.

    • path (HTTPPathModifier)

      Настройки замены пути в URI запроса.

      • type (string)

        Тип замены пути:

        • ReplaceFullPath — замена всего пути. Новый путь указывается в поле replaceFullPath.
        • ReplacePrefixMatch — замена в зависимости от указания пути спецификации HTTPRoute (поле spec.rules.matches.path): если указан тип Exact, заменяется весь путь, если PathPrefix — только его начало. Новый путь или его начало указывается в поле replacePrefixMatch.

      • replaceFullPath (string)

        Новый путь при типе замены ReplaceFullPath.

      • replacePrefixMatch (string)

        Новый путь или его начало при типе замены ReplacePrefixMatch (смотрите описание типа выше).

    • port (int32)

      Новый порт в URI запроса.

    • statusCode (int)

      HTTP-код состояния, возвращаемый при перенаправлении.

Примеры манифестов для ресурсов HTTPRoute

Примечание

Настройки перенаправления для изменения схемы (scheme) и доменного имени (hostname) поддерживаются в Gateway API версии 0.4.31 и выше.

Установите актуальную версию Gateway API, если нужна поддержка этих настроек.

Перенаправление запроса с изменением схемы

В этом примере маршрутизируются запросы, которые поступают к обработчику http, настроенному для Gateway sample-gateway. Чтобы перенаправление работало, для Gateway должен быть настроен обработчик HTTPS-трафика.

Все запросы к http://demo.example.com/sample будут перенаправлены на https://demo.example.com/sample с кодом HTTP 301 Moved Permanently.

Манифест для HTTPRoute — перенаправление запроса с изменением схемы
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: sample-scheme-redirect
  namespace: sample-namespace
spec:
  parentRefs:
  - name: sample-gateway
    sectionName: http
    namespace: gateways
  hostnames:
    - demo.example.com
  rules:
  - matches:
    - path:
        value: /sample
    filters:
    - type: RequestRedirect
      requestRedirect:
        scheme: https
        statusCode: 301

Перенаправление запроса с изменением доменного имени

В этом примере маршрутизируются запросы, которые поступают к обработчику http, настроенному для Gateway sample-gateway.

Все запросы к http://demo.example.com/sample будут перенаправлены на http://example.org/sample с кодом HTTP 301 Moved Permanently.

Манифест для HTTPRoute — перенаправление запроса с изменением доменного имени
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: sample-hostname-redirect
  namespace: sample-namespace
spec:
  parentRefs:
  - name: sample-gateway
    sectionName: http
    namespace: gateways
  hostnames:
    - demo.example.com
  rules:
  - matches:
    - path:
        value: /sample
    filters:
    - type: RequestRedirect
      requestRedirect:
        hostname: example.org
        statusCode: 301
Предыдущая
GatewayPolicy
Следующая
GRPCRoute