Связаться с намиПодключиться

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

Статья создана
Обновлена 6 мая 2025 г.

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

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>
spec: <HTTPRouteSpec>

Где:

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

  • kind: HTTPRoute

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

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

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

      Имя ресурса. Подробнее о формате см. в документации Kubernetes.

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

    • namespace (string)

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

  • 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, которые должны обрабатывать запрос в качестве бэкенда.

      Ресурс Service, на который указывает это поле, должен быть описан по принятой конфигурации.

      • name (string)

        Имя сервиса Kubernetes.

      • namespace (string)

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

      • port (int32)

        Номер порта сервиса.

        Номер должен совпадать с одним из номеров портов, указанных в полях 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)

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

    • scheme (string)

      Новая схема в URI запроса: http или 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-код состояния, возвращаемый при перенаправлении.

Предыдущая
Gateway
Следующая
TLSRoute