VirtualServer, VirtualServerRoute¶

Ресурсы VirtualServer и VirtualServerRoute, представленные в версии 1.5, реализуют сценарии использования, не поддерживаемые ресурсом Ingress, такие как разделение трафика и продвинутая маршрутизация на основе содержимого. Они реализованы как пользовательские ресурсы .

Это справочная документация по обоим ресурсам.

Спецификация VirtualServer¶

Ресурс VirtualServer определяет конфигурацию балансировки нагрузки для доменного имени, например example.com. Ниже приведен пример такой конфигурации:

apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
  name: cafe
spec:
  host: cafe.example.com
  tls:
    secret: cafe-secret
  gunzip: on
  upstreams:
  - name: tea
    service: tea-svc
    port: 80
  - name: coffee
    service: coffee-svc
    port: 80
  routes:
  - path: /tea
    action:
      pass: tea
  - path: /coffee
    action:
      pass: coffee
  - path: ~ ^/decaf/.\*\\.jpg$
    action:
      pass: coffee
  - path: = /green/tea
    action:
      pass: tea

Поле	Описание	Тип	Обязательно
`host`	Хост (доменное имя) сервера. Это должен быть допустимый поддомен, как определено в RFC 1123, например `my-app` или `hello.example.com`. При использовании домена с подстановочным знаком, например `*.example.com`, домен должен быть заключен в двойные кавычки. Значение `host` должно быть уникальным среди всех ресурсов Ingress и VirtualServer.	`string`	Да
`tls`	Конфигурация завершения TLS.	tls	Нет
`gunzip`	Включает или отключает распаковку архивированных ответов для клиентов. Допустимые пары значений: “on” и “off”, “true” и “false” или “yes” и “no”. Если значение `gunzip` не установлено, то по умолчанию оно равно `off`.	`boolean`	Нет
`ExternalDNS`	Конфигурация ExternalDNS для VirtualServer.	ExternalDNS	Нет
`dos`	Ссылка на DosProtectedResource; установка этого параметра включает защиту VirtualServer от DOS-атак.	`string`	Нет
`policies`	Список политик.	[]policy	Нет
`upstreams`	Список апстримов.	[]upstream	Нет
`routes`	Список маршрутов.	[]route	Нет
`ingressClassName`	Указывает, какой Ingress Controller должен обрабатывать ресурс VirtualServer.	`string`	Нет
`internalRoute`	Указывает, является ли ресурс VirtualServer внутренним маршрутом.	`boolean`	Нет
`http-snippets`	Задает пользовательский фрагмент в контексте http.	`string`	Нет
`server-snippets`	Задает пользовательский фрагмент в контексте . Имеет приоритет над ключом ConfigMap `server-snippets`.	`string`	Нет

VirtualServer.TLS¶

Поле tls определяет конфигурацию TLS для ресурса VirtualServer. Например:

secret: cafe-secret
redirect:
  enable: true

Поле	Описание	Тип	Обязательно
`secret`	Имя секрета с сертификатом TLS и ключом. Секрет должен принадлежать тому же пространству имен, что и VirtualServer. Секрет должен иметь тип `kubernetes.io/tls` и содержать ключи с именами `tls.crt` и `tls.key`, содержащие сертификат и закрытый ключ, как описано здесь. Если секрет не существует или недействителен, Angie прервет любую попытку установить TLS-соединение с хостом VirtualServer. Если секрет не указан, но настроен секрет TLS с подстановочным знаком, Angie будет использовать секрет со знаком для завершения TLS.	`string`	Нет
`redirect`	Конфигурация перенаправления TLS для VirtualServer.	tls.redirect	Нет
`cert-manager`	Конфигурация TLS cert-manager для VirtualServer.	tls.cert-manager	Нет

VirtualServer.TLS.Redirect¶

Поле перенаправления настраивает перенаправление TLS для VirtualServer:

enable: true
code: 301
basedOn: scheme

Поле	Описание	Тип	Обязательно
`enable`	Включает перенаправление TLS для VirtualServer. Значение по умолчанию равно `false`.	`boolean`	Нет
`код`	Код состояния перенаправления. Допустимые значения: `301`, `302`, `307`, `308`. Значение по умолчанию - `301`.	`int`	Нет
`basedOn`	Атрибут запроса, который Angie будет оценивать для отправки перенаправления. Допустимыми значениями являются `scheme` (схема запроса) или `x-forwarded-proto` (заголовок `X-Forwarded-Proto` запроса). Значение по умолчанию - `scheme`.	`string`	Нет

VirtualServer.TLS.CertManager¶

Поле cert-manager настраивает автоматическое управление сертификатами x509 для ресурсов VirtualServer с помощью cert-manager (cert-manager.io). Ознакомьтесь с документацией по конфигурации cert-manager для получения дополнительной информации о развертывании и настройке эмитентов (Issuer). Пример:

cert-manager:
  cluster-issuer: "my-issuer-name"

Поле	Описание	Тип	Обязательно
`issuer`	Имя эмитента. Эмитент - это ресурс cert-manager, который описывает центр сертификации, способный подписывать сертификаты. Он должен находиться в том же пространстве имен, что и ресурс VirtualServer. Обратите внимание, что требуется задать issuer или cluster-issuer, но эти параметры взаимоисключающие - должен быть задан один и только один.	`string`	Нет
`cluster-issuer`	Имя ClusterIssuer. ClusterIssuer - это ресурс cert-manager, который описывает центр сертификации, способный подписывать сертификаты. Не имеет значения, в каком пространстве имен находится ваш VirtualServer, поскольку ClusterIssuer - это ресурсы, не относящиеся к пространствам имен. Обратите внимание, что требуется задать issuer или cluster-issuer, но эти параметры взаимоисключающие - должен быть задан один и только один.	`string`	Нет
`issuer-kind`	Тип внешнего ресурса-эмитента, например AWSPCAIssuer. Это необходимо только для сторонних эмитентов. Его нельзя задавать, если также задан cluster-issuer.	`string`	Нет
`issuer-group`	Группа API внешнего контроллера-эмитента, например awspca.cert-manager.io. Это необходимо только для сторонних эмитентов. Его нельзя задавать, если также задан cluster-issuer.	`string`	Нет
`common-name`	Это поле позволяет настроить spec.commonName для создаваемого сертификата. Эта конфигурация добавляет CN к сертификату x509.	`string`	Нет
`duration`	Это поле позволяет настроить поле spec.duration для генерируемого сертификата. Оно должно быть задано с использованием формата time.Duration в Go, который не допускает суффикса d (дни). Указывайте такие значения, используя вместо них суффиксы s, m и h.	`string`	Нет
`renew-before`	Эта аннотация позволяет настроить поле spec.renewBefore для генерируемого сертификата. Оно должно быть задано с использованием формата time.Duration в Go, который не допускает суффикса d (дни). Указывайте такие значения, используя вместо них суффиксы s, m и h.	`string`	Нет
`usages`	Позволяет настроить поле spec.usages для генерируемого сертификата. Задайте строку со значениями, разделенными запятыми, т. е. `соглашение о ключе, цифровая подпись, серверная аутентификация`. Исчерпывающий список поддерживаемых способов использования ключей можно найти в документации API cert-manager.	`string`	Нет

VirtualServer.ExternalDNS¶

Поле ExternalDNS настраивает динамическое управление записями DNS для ресурсов VirtualServer с использованием ExternalDNS . Ознакомьтесь с документацией по конфигурации ExternalDNS для получения дополнительной информации о развертывании и настройке ExternalDNS и поставщиков. Пример:

enable: true

Поле	Описание	Тип	Обязательно
`enable`	Включает интеграцию ExternalDNS для ресурса VirtualServer. Значение по умолчанию равно `false`.	`string`	Нет
`labels`	Настраивает метки, применяемые к ресурсам конечной точки, которые будут использоваться ExternalDNS.	`map[string]string`	Нет
`providerSpecific`	Настраивает свойства, относящиеся к конкретному поставщику, которые содержат имя и значение конфигурации, специфичной для отдельных поставщиков DNS.	[]ProviderSpecific	Нет
`recordTTL`	TTL для записи DNS. По умолчанию это значение равно 0. См. документацию ExternalDNS TTL для определения значений по умолчанию для конкретного поставщика	`int64`	Нет
`recordType`	Тип создаваемой записи, например «A», «AAAA», «CNAME». Если значение не задано, оно автоматически вычисляется на основе внешних конечных точек.	`string`	Нет

VirtualServer.ExternalDNS.ProviderSpecific¶

Поле providerSpecific блока ExternalDNS позволяет указать свойства, специфичные для поставщика, которые представляют собой список пар «ключ-значение» для конфигураций, специфичных для отдельных поставщиков DNS. Пример:

- name: my-name
  value: my-value
- name: my-name2
  value: my-value2

Поле	Описание	Тип	Обязательно
`name`	Имя в паре «ключ-значение».	`string`	Да
`value`	Значение в паре «ключ-значение».	`string`	Да

VirtualServer.Policy¶

Ссылается на ресурс Policy по имени и необязательному пространству имен. Например:

name: access-control

Поле	Описание	Тип	Требуется
`name`	Имя политики. Если политика не существует или недействительна, Angie выдаст сообщение об ошибке с кодом состояния `500`.	`string`	Да
`namespace`	Пространство имен политики. Если не указано, используется пространство имен ресурса VirtualServer.	`string`	Нет

VirtualServer.Route¶

Маршрут определяет правила для сопоставления клиентских запросов с такими действиями, как передача запроса апстриму. Например:

path: /tea
action:
  pass: tea

Поле	Описание	Тип	Обязательно
`path`	Путь маршрута. Angie сопоставит его с URI запроса. Возможные значения: префикс (`/`, `/path`), точное совпадение (`=/exact/match`), регулярное выражение без учета регистра (`~^/Bar.\.jpg`) или регулярное выражение с учетом регистра (`~^/foo.*\.jpg`). В случае префикса (должен начинаться с `/` ) или точного совпадения (должно начинаться с `=` ) путь не должен содержать никаких пробельных символов, `{` , `}` или `;`. В случае регулярных выражений все двойные кавычки `"` должны быть экранированы, при этом совпадение не может заканчиваться неэкранированной обратной косой чертой \. Путь должен быть уникальным среди путей всех маршрутов VirtualServer. Дополнительные сведения см. в описании директивы location.	`string`	Да
`policies`	Список политик. Эти политики имеют приоритет над политиками того же типа, определенными в `спецификации` VirtualServer. Более подробную информацию смотрите в Применение политик.	[]policy	Нет
`action`	Действие по умолчанию, выполняемое для запроса.	Action	Нет
`dos`	Ссылка на DosProtectedResource; установка этого параметра включает защиту маршрута VirtualServer от DOS-атак.	`string`	Нет
`splits`	Конфигурация разделения трафика по умолчанию. Должно быть не менее 2 разделений.	Split	Нет
`matches`	Правила сопоставления для продвинутой маршрутизации на основе содержимого. Требуется задать `action` или `splits` по умолчанию. Несопоставленные запросы будут обрабатываться `action` или `splits` по умолчанию.	matches	Нет
`route`	Имя ресурса VirtualServerRoute, который определяет этот маршрут. Если VirtualServerRoute не принадлежит к тому же пространству имен, что и VirtualServer, необходимо включить пространство имен. Например: `tea-namespace/tea`.	`string`	Нет
`errorPages`	Настраиваемые ответы на коды ошибок. Angie будет использовать эти ответы вместо того, чтобы возвращать ответы об ошибках с серверов апстрима или ответы по умолчанию, сгенерированные Angie. Настраиваемый ответ может быть перенаправлением или сохраненным ответом. Например, это может быть перенаправление на другой URL-адрес, если вышестоящий сервер ответил кодом состояния 404.	[]errorPage	Нет
`location-snippets`	Задает пользовательский фрагмент в контексте местоположения. Имеет приоритет над ключом ConfigMap `location-snippets`.	`string`	Нет

Примечание

Маршрут должен включать в себя ровно одно из следующих действий: action, splits или route.

Спецификация VirtualServerRoute¶

Ресурс VirtualServerRoute определяет маршрут для VirtualServer. Он может состоять из одного вложенного маршрута или нескольких. VirtualServerRoute является альтернативой объединяемым типам Ingress.

В приведенном ниже примере виртуальный сервер cafe из пространства имен cafe-ns определяет маршрут с путем /coffee, который далее определяется через VirtualServerRoute coffee из пространства имен coffee-ns.

VirtualServer:

apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
  name: cafe
  namespace: cafe-ns
spec:
  host: cafe.example.com
  upstreams:
  - name: tea
    service: tea-svc
    port: 80
  routes:
  - path: /tea
    action:
      pass: tea
  - path: /coffee
    route: coffee-ns/coffee

VirtualServerRoute:

apiVersion: k8s.angie.software/v1
kind: VirtualServerRoute
metadata:
  name: coffee
  namespace: coffee-ns
spec:
  host: cafe.example.com
  upstreams:
  - name: latte
    service: latte-svc
    port: 80
  - name: espresso
    service: espresso-svc
    port: 80
  subroutes:
  - path: /coffee/latte
    action:
      pass: latte
  - path: /coffee/espresso
    action:
      pass: espresso

Обратите внимание, что каждый вложенный маршрут должен иметь путь path, начинающийся с того же префикса (здесь «/coffee»), что и в маршруте VirtualServer. Кроме того, host в VirtualServerRoute должен совпадать с host у VirtualServer.

Поле	Описание	Тип	Обязательно
`host`	Хост (доменное имя) сервера. Это должен быть допустимый поддомен, как определено в RFC 1123, например `my-app` или `hello.example.com`. При использовании домена с подстановочным знаком, например `*.example.com`, домен должен быть заключен в двойные кавычки. Значение должно совпадать с `host` у VirtualServer, который ссылается на этот ресурс.	`string`	Да
`upstreams`	Список апстримов.	[]upstream	Нет
`subroutes`	Список вложенных маршрутов.	[]subroute	Нет
`ingressClassName`	Указывает, какой Ingress Controller должен обрабатывать ресурс VirtualServerRoute. Значение должно совпадать с `ingressClassName` у VirtualServer, который ссылается на этот ресурс.	`string`	Нет

VirtualServerRoute.Subroute¶

Определяет правила сопоставления клиентских запросов и действий, например передача запроса апстриму. Например:

path: /coffee
action:
  pass: coffee

Поле	Описание	Тип	Обязательно
`path`	Путь вложенного маршрута. Angie сопоставит его с URI запроса. Возможные значения: префикс (`/`, `/path`), точное совпадение (`=/exact/match`), регулярное выражение без учета регистра (`~^/Bar.\.jpg`) или регулярное выражение с учетом регистра (`~^/foo.*\.jpg`). В случае префикса путь должен начинаться с того же пути, что и путь маршрута VirtualServer, который ссылается на этот ресурс. В случае точного совпадения или регулярного выражения путь должен совпадать с путем маршрута VirtualServer, который ссылается на этот ресурс. В случае префикса или точного совпадения путь не должен содержать никаких пробельных символов, `{` , `}` или `;`. В случае регулярных выражений все двойные кавычки `"` должны быть экранированы, при этом совпадение не может заканчиваться неэкранированной обратной косой чертой . Путь должен быть уникальным среди путей всех вложенных маршрутов VirtualServerRoute.	`string`	Да
`policies`	Список политик. Эти политики имеют приоритет над всеми политиками, определенными в маршруте VirtualServer, который ссылается на этот ресурс. Они также имеют приоритет над политиками того же типа, определенными в `спецификации` VirtualServer. Более подробную информацию смотрите в разделе Применение политик.	[]policy	Нет
`action`	Действие по умолчанию, выполняемое для запроса.	Action	Нет
`dos`	Ссылка на DosProtectedResource; установка этого параметра включает защиту вложенного маршрута VirtualServerRoute от DOS-атак.	`string`	Нет
`splits`	Конфигурация разделения трафика по умолчанию. Должно быть не менее 2 разделений.	[]split	Нет
`matches`	Правила сопоставления для продвинутой маршрутизации на основе содержимого. Требуется задать `action` или `splits` по умолчанию. Несопоставленные запросы будут обрабатываться `action` или `splits` по умолчанию.	matches	Нет
`errorPages`	Настраиваемые ответы на коды ошибок. Angie будет использовать эти ответы вместо того, чтобы возвращать ответы об ошибках с серверов апстрима или ответы по умолчанию, сгенерированные Angie. Настраиваемый ответ может быть перенаправлением или сохраненным ответом. Например, это может быть перенаправление на другой URL-адрес, если вышестоящий сервер ответил кодом состояния 404.	[]errorPage	Нет
`location-snippets`	Задает пользовательский фрагмент в контексте местоположения. Переопределяет значение `location-snippets` VirtualServer (если задано) или ключ ConfigMap `location-snippets`.	`string`	Нет

Примечание

Вложенный маршрут должен включать в себя ровно одно из следующих действий: action или splits.

Общие части VirtualServer и VirtualServerRoute¶

Upstream¶

Апстрим определяет конечное место назначения для конфигурации маршрутизации. Например:

name: tea
service: tea-svc
subselector:
  version: canary
port: 80
lb-method: round_robin
fail-timeout: 10s
max-fails: 1
max-conns: 32
keepalive: 32
connect-timeout: 30s
read-timeout: 30s
send-timeout: 30s
next-upstream: "error timeout non_idempotent"
next-upstream-timeout: 5s
next-upstream-tries: 10
client-max-body-size: 2m
tls:
  enable: true

Примечание

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

Поле	Описание	Тип	Обязательно
`name`	Имя апстрима. Это должна быть допустимая метка DNS, как определено в RFC 1035. Например, допустимы значения `hello` и `upstream-123`. Имя должно быть уникальным среди всех апстримов ресурса.	`string`	Да
`service`	Название сервиса. Сервис должен принадлежать к тому же пространству имен, что и ресурс. Если сервиса не существует, Angie предположит, что у него нет конечных точек, и будет возвращать ответ `502` для запросов к этому апстриму.	`string`	Да
`subselector`	Выбирает поды внутри сервиса, используя ключи меток и значения. По умолчанию выбраны все поды сервиса. Примечание. Ожидается, что указанные метки будут присутствовать в подах при их создании. Если метки подов изменяются, Ingress Controller не увидит это изменение до тех пор, пока не будет изменено количество подов.	`map[string]string`	Нет
`use-cluster-ip`	Позволяет использовать IP-адрес кластера и порт сервиса вместо использования IP-адреса и порта подов по умолчанию. Когда это поле включено, поля, которые настраивают поведение Angie, относящееся к нескольким серверам апстрима (например, `lb-method` и `next-upstream`), не будут иметь никакого эффекта, поскольку Ingress Controller настроит Angie только с одним сервером апстрима, который будет соответствовать IP-адресу кластера сервиса.	`boolean`	Нет
`port`	Порт службы. Если у сервиса не определен этот порт, Angie предположит, что у него нет конечных точек, и будет возвращать ответ `502` для запросов к этому апстриму. Значение должно находиться в диапазоне `1..65535`.	`uint16`	Да
`lb-method`	Метод балансировки нагрузки. Чтобы использовать циклический метод, укажите `round_robin`. Значение по умолчанию указано в ключе `lb-method` ConfigMap.	`string`	Нет
`fail-timeout`	Время, в течение которого должно произойти указанное количество неудачных попыток установить связь с сервером апстрима, чтобы он считался недоступным. См. параметр fail_timeout директивы сервера. Значение по умолчанию задано в ключе ConfigMap `fail-timeout`.	`string`	Нет
`max-fails`	Количество неудачных попыток установить связь с сервером апстрима, которые должны произойти в течение времени, заданного в `fail-timeout`, чтобы считать сервер недоступным. См. параметр max_fails директивы сервера. Значение по умолчанию задано в ключе ConfigMap `max-fails`.	`int`	Нет
`max-conns`	Максимальное количество одновременных активных подключений к серверу апстрима. См. параметр max_conns директивы сервера. По умолчанию ограничений нет. Примечание. Если включены соединения keepalive, общее количество активных и неактивных соединений keepalive к серверу апстрима может превышать значение `max_conns`.	`int`	Нет
`keepalive`	Настраивает кэш для подключений к серверам апстрима. Значение `0` отключает кэш. См. директиву keepalive. Значение по умолчанию задано в ключе ConfigMap `keepalive`.	`int`	Нет
`connect-timeout`	Тайм-аут для установления соединения с сервером апстрима. См. директиву proxy_connect_timeout. Значение по умолчанию указано в ключе ConfigMap `proxy-connect-timeout`.	`string`	Нет
`read-timeout`	Тайм-аут для чтения ответа от сервера апстрима. См. директиву proxy_read_timeout. Значение по умолчанию указано в ключе ConfigMap `proxy-read-timeout`.	`string`	Нет
`send-timeout`	Тайм-аут для передачи запроса на сервер апстрима. См. директиву proxy_send_timeout. Значение по умолчанию указано в ключе ConfigMap `proxy-send-timeout`.	`string`	Нет
`next-upstream`	Указывает, в каких случаях запрос должен быть передан следующему серверу апстрима. См. директиву proxy_next_upstream. Значение по умолчанию - `тайм-аут ошибки`.	`string`	Нет
`next-upstream-timeout`	Время, в течение которого запрос может быть передан следующему серверу апстрима. См. директиву proxy_next_upstream_timeout. Значение `0` отключает ограничение по времени. Значение по умолчанию равно `0`.	`string`	Нет
`next-upstream-tries`	Количество возможных попыток передачи запроса на следующий сервер апстрима. См. директиву proxy_next_upstream_tries. Значение `0` отключает это ограничение. Значение по умолчанию равно `0`.	`int`	Нет
`client-max-body-size`	Задает максимальный размер текста клиентского запроса. См. директиву client_max_body_size. Значение по умолчанию задано в ключе ConfigMap `client-max-body-size`.	`string`	Нет
`tls`	Конфигурация TLS для апстрима.	tls	Нет
`buffering`	Включает буферизацию ответов от сервера апстрима. См. директиву proxy_buffering. Значение по умолчанию задано в ключе ConfigMap `proxy-buffering`.	`boolean`	Нет
`buffers`	Настраивает буферы, используемые для чтения ответа от сервера апстрима в рамках одного соединения.	buffers	Нет
`buffer-size`	Устанавливает размер буфера, используемого для считывания первой части ответа, полученного от сервера апстрима. См. директиву proxy_buffer_size. Значение по умолчанию задано в ключе ConfigMap `proxy-buffer-size`.	`string`	Нет
`type`	Тип апстрима. Поддерживаются значения `http` и `grpc`. По умолчанию используется `http`. Для gRPC необходимо включить HTTP/2 в `ConfigMap` и настроить завершение TLS на VirtualServer.	`string`	Нет

Upstream.Buffers¶

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

number: 4
size: 8K

См. директиву proxy_buffers для получения дополнительной информации.

Поле	Описание	Тип	Требуется
`number`	Задает количество буферов. Значение по умолчанию задано в ключе ConfigMap `proxy-buffers`.	`int`	Да
`size`	Задает размер буфера. Значение по умолчанию задано в ключе ConfigMap `proxy-buffers`.	`string`	Да

Upstream.TLS¶

Поле	Описание	Тип	Обязательно
`enable`	Включает HTTPS для запросов к серверам апстрима. Значение по умолчанию равно `False`, что означает, что будет использоваться HTTP. Примечание. По умолчанию Angie не будет проверять сертификат вышестоящего сервера. Чтобы включить проверку, настройте политику EgressMTLS.	`boolean`	Нет

Upstream.SessionCookie¶

Поле SessionCookie настраивает сохранение сеансов, что позволяет передавать запросы от одного и того же клиента на один и тот же сервер апстрима. Информация о назначенном сервере апстрима передается в сеансовом cookie, сгенерированном Angie.

В приведенном ниже примере мы настраиваем сохранение сеанса с помощью cookie сеанса для апстрима и задаем все доступные параметры:

name: tea
service: tea-svc
port: 80
sessionCookie:
  enable: true
  name: srv_id
  path: /
  expires: 1h
  domain: .example.com
  httpOnly: false
  secure: true
  samesite: strict

См. директиву sticky для получения дополнительной информации. Сеансовый cookie соответствует методу sticky cookie.

Поле	Описание	Тип	Обязательно
`enable`	Включает сохранение сеанса с помощью сеансового cookie для сервера апстрима. Значение по умолчанию равно `false`.	`boolean`	Нет
`name`	Имя cookie.	`string`	Да
`path`	Путь, для которого установлен cookie.	`string`	Нет
`expires`	Время, в течение которого браузер должен сохранять cookie. Может быть установлено специальное значение `max`; тогда срок действия cookie истечет `31 декабря 2037 года в 23:55:55 по Гринвичу`.	`string`	Нет
`domain`	Домен, для которого установлен cookie.	`string`	Нет
`httpOnly`	Добавляет атрибут `HttpOnly` к cookie.	`boolean`	Нет
`secure`	Добавляет атрибут `Secure` к cookie.	`boolean`	Нет
`samesite`	Добавляет атрибут `SameSite` к cookie. Допустимые значения: `strict`, `lax`, `none`	`string`	Нет

Upstream.SessionRoute¶

Поле sessionRoute настраивает сохранение маршрутов, что позволяет передавать запросы от одного и того же клиента на один и тот же сервер апстрима. Информация о назначенном сервере апстрима поддерживается в режиме route Angie.

В приведенном ниже примере мы формируем директиву Angie sticky route $cookie_route $arg_route;:

sessionRoute:
  enable: true
  variables:
    \- "\$cookie_route"
    \- "\$arg_route"

См. описание режима route директивы sticky для получения дополнительной информации.

Параметры:

Поле	Описание	Тип	Обязательно
`enable`	Включает сохранение сеанса в режиме `route` для сервера апстрима. Значение по умолчанию равно `false`.	`boolean`	Нет
`variables`	Список переменных, подставляемых в директиву `sticky route` в порядке следования.	`[]string`	Нет

Header¶

Определяет HTTP-заголовок:

name: Host
value: example.com

Поле	Описание	Тип	Требуется
`name`	Имя заголовка.	`string`	Да
`value`	Значение заголовка.	`string`	Нет

Action¶

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

В приведенном ниже примере клиентские запросы передаются на апстрим coffee:

path: /coffee
action:
 pass: coffee

Поле	Описание	Тип	Обязательно
`pass`	Передает запросы серверу апстрима. Апстрим с таким именем должен быть определен в ресурсе.	`string`	Нет
`redirect`	Перенаправляет запросы на указанный URL-адрес.	action.redirect	Нет
`return`	Возвращает предварительно сконфигурированный ответ.	action.return	Нет
`proxy`	Передает запросы апстриму, добавляет возможность изменять запрос и ответ (например, переписывать URI или изменять заголовки).	action.proxy	Нет

Примечание

Действие должно включать в себя ровно одно из следующих значений: pass, redirect, return или proxy.

Action.Redirect¶

Определяет перенаправление, возвращаемое для запроса.

В приведенном ниже примере клиентские запросы направляются на URL-адреса http://myhost.ru:

redirect:
  url: http://myhost.ru
  code: 301

Поле	Описание	Тип	Требуется
`url`	URL-адрес, на который будет перенаправлен запрос. Поддерживаемые переменные Angie: `$scheme` , `$http_x_forwarded_proto` , `$request_uri` , `$host`. Переменные должны быть заключены в фигурные скобки. Например: `${host}${request_uri}`.	`string`	Да
`код`	Код состояния перенаправления. Допустимые значения: `301`, `302`, `307`, `308`. Значение по умолчанию - `301`.	`int`	Нет

Action.Return¶

Определяет предварительно сконфигурированный ответ на запрос.

В приведенном ниже примере Angie будет отвечать предварительно настроенным ответом на каждый запрос:

return:
  code: 200
  type: text/plain
  body: "Hello World\n"

Поле	Описание	Тип	Требуется
`код`	Код состояния ответа. Допустимые значения: `2XX`, `4XX` или `5XX`. Значение по умолчанию равно `200`.	`int`	Нет
`тип`	MIME-тип ответа. Значение по умолчанию - `text/plain`.	`string`	Нет
`body`	Основная часть ответа. Поддерживает переменные Angie*. Переменные должны быть заключены в фигурные скобки. Например: `Зап рос равен ${request_uri}\n`.	`string`	Да

Примечание

Action.Proxy¶

Передает запросы апстриму с возможностью изменять запрос и ответ (например, переписывать URI или изменять заголовки).

В приведенном ниже примере URI запроса переписывается на /, а заголовки запроса и ответа изменяются:

proxy:
  upstream: coffee
  requestHeaders:
    pass: true
    set:
    - name: My-Header
      value: Value
    - name: Client-Cert
      value: ${ssl_client_escaped_cert}
  responseHeaders:
    add:
    - name: My-Header
      value: Value
    - name: IC-Angie-Version
      value: ${angie_version}
      always: true
    hide:
    - x-internal-version
    ignore:
    - Expires
    - Set-Cookie
    pass:
    - Server
  rewritePath: /

Поле	Описание	Тип	Обязательно
`upstream`	Имя апстрима, куда будут проксироваться запросы. Апстрим с таким именем должен быть определен в ресурсе.	`string`	Да
`requestHeaders`	Изменения заголовков запросов.	Action.Proxy.RequestHeaders	Нет
`responseHeaders`	Изменения в заголовках ответов.	Action.Proxy.ResponseHeaders	Нет
`rewritePath`	Переписанный URI. Если путь маршрута является регулярным выражением, т. е. начинается с ~, то rewritePath может включать группы захвата `$1-9`. Например, $1 - первая группа, и так далее.	`string`	Нет

Action.Proxy.RequestHeaders¶

Поле requestHeaders изменяет заголовки запроса к проксируемому серверу апстрима.

Поле	Описание	Тип	Обязательно
`pass`	Передает исходные заголовки запроса на проксируемый сервер апстрима. Дополнительные сведения см. в описании директивы proxy_pass_request_header. Значение по умолчанию - true.	`bool`	Нет
`set`	Позволяет переопределять или добавлять поля для представления заголовков запросов, передаваемых на проксируемые серверы апстрима. Дополнительные сведения см. в описании директивы proxy_set_header.	[]header	Нет

Action.Proxy.RequestHeaders.Set.Header¶

Определяет HTTP-заголовок:

name: My-Header
value: My-Value

Можно переопределить значение заголовка Host по умолчанию, которое Ingress Controller устанавливает равным $host:

name: Host
value: example.com

Поле	Описание	Тип	Требуется
`name`	Имя заголовка.	`string`	Да
`value`	Значение заголовка. Поддерживает переменные Angie*. Переменные должны быть заключены в фигурные скобки. Например: `${scheme}`.	`string`	Нет

Примечание

Поддерживаемые переменные Angie: $request_uri, $request_method, $request_body, $scheme, $http_, $args, $arg_, $cookie_, $host, $request_time, $request_length, $angie_version, $pid, $connection, $remote_addr, $remote_port, $time_iso8601, $time_local, $server_addr, $server_port, $server_name, $server_protocol, $connections_active, $connections_reading, $connections_writing, $connections_waiting, $ssl_cipher, $ssl_ciphers, $ssl_client_cert, $ssl_client_escaped_cert, $ssl_client_fingerprint, $ssl_client_i_dn, $ssl_client_i_dn_legacy, $ssl_client_raw_cert, $ssl_client_s_dn, $ssl_client_s_dn_legacy, $ssl_client_serial, $ssl_client_v_end, $ssl_client_v_remain, $ssl_client_v_start, $ssl_client_verify, $ssl_curves, $ssl_early_data, $ssl_protocol, $ssl_server_name, $ssl_session_id, $ssl_session_reused.

Action.Proxy.ResponseHeaders¶

Поле responseHeaders изменяет заголовки ответа клиенту.

Поле	Описание	Тип	Обязательно
`hide`	Заголовки, которые не будут переданы в ответе клиенту с проксируемого сервера апстрима. Дополнительные сведения см. в описании директивы proxy_hide_header.	`[]string`	Нет
`pass`	Позволяет передавать скрытые поля заголовка клиенту с проксируемого сервера апстрима. Дополнительные сведения см. в описании директивы proxy_pass_header.	`[]string`	Нет
`ignore`	Отключает обработку определенных заголовков** при передаче клиенту ответа с проксируемого сервера апстрима. Дополнительные сведения см. в описании директивы proxy_ignore_headers.	`[]string`	Нет
`add`	Добавляет заголовки к ответу для клиента.	[]addHeader	Нет

Примечание

Скрытые заголовки по умолчанию: Date, Server, X-Pad и X-Accel-....

Примечание

Следующие поля могут быть проигнорированы: X-Accel-Redirect, X-Accel-Expires, X-Accel-Limit-Rate, X-Accel-Buffering, X-Accel-Charset, Expires, Cache-Control, Set-Cookie и Vary.

AddHeader¶

Определяет HTTP-заголовок с необязательным полем always:

name: My-Header
value: My-Value
always: true

Поле	Описание	Тип	Обязательно
`name`	Имя заголовка.	`string`	Да
`value`	Значение заголовка. Поддерживает переменные Angie*. Переменные должны быть заключены в фигурные скобки. Например: `${scheme}`.	`string`	Нет
`always`	Если установлено значение true, добавляет заголовок независимо от кода состояния ответа**. Значение по умолчанию - false. Дополнительные сведения см. в описании директивы add_header.	`bool`	Нет

Примечание

Если значение always - false, заголовок ответа добавляется только в том случае, если код состояния ответа - это 200, 201, 204, 206, 301, 302, 303, 304, 307 или 308.

Split¶

Определяет вес действия в составе конфигурации разделений.

В приведенном ниже примере Angie передает 80% запросов вышестоящему coffee-v1, а оставшиеся 20% - coffee-v2:

splits:
  - weight: 80
    action:
      pass: coffee-v1
  - weight: 20
    action:
      pass: coffee-v2

Поле	Описание	Тип	Обязательно
`weight`	Вес действия. Значение должно попадать в диапазон `1..99`. Сумма весов всех разделений должна быть равна `100`.	`int`	Да
`action`	Действие, которое необходимо выполнить для запроса.	:ref`:action`	Да

Match¶

Определяет сопоставление между условиями и действием или разделениями.

В приведенном ниже примере Angie направляет запросы с путем «/coffee» в разные апстримы на основе значения cookie user:

user=john -> coffee-future
user=bob -> coffee-deprecated
Если cookie не установлен или не равен ни john, ни bob, Angie перенаправляет запрос в coffee-stable

path: /coffee
matches:
- conditions:
  - cookie: user
    value: john
    action:
    pass: coffee-future
- conditions:
  - cookie: user
    value: bob
    action:
      pass: coffee-deprecated
  action:
    pass: coffee-stable

В следующем примере Angie направляет запросы на основе значения встроенной переменной $request_method , которая представляет HTTP-метод запроса:

все запросы POST -> coffee-post
все прочие запросы -> coffee

path: /coffee
matches:
  - conditions:
    - variable: $request\_method
        value: POST
      action:
        pass: coffee-post
    action:
      pass: coffee

Поле	Описание	Тип	Обязательно
`conditions`	Список условий. Должен включать по крайней мере одно условие.	[]condition	Да
`action`	Действие, которое необходимо выполнить для запроса.	Action	Нет
`splits`	Конфигурация разбиений для разделения трафика. Должно быть указано не менее двух разделений.	[]split	Нет

Примечание

Сопоставление должно использовать ровно одно из следующих значений: action или splits.

Condition¶

Определяет условие в сопоставлении.

Поле	Описание	Тип	Обязательно
`header`	Имя заголовка. Должно состоять из буквенно-цифровых символов или `-`.	`string`	Нет
`cookie`	Имя cookie. Должно состоять из буквенно-цифровых символов или `_`.	`string`	Нет
`argument`	Имя аргумента. Должно состоять из буквенно-цифровых символов или `_`.	`string`	Нет
`variable`	Имя переменной Angie. Должно начинаться с `$`. См. список поддерживаемых переменных после таблицы.	`string`	Нет
`value`	Значение, которому должно соответствовать условие. Как определить значение, показано ниже в таблице.	`string`	Да

Примечание

Условие должно включать ровно одно из следующих значений: header, cookie, argument или variable.

Поддерживаемые переменные Angie: $args, $http2, $https, $remote_addr, $remote_port, $query_string, $request, $request_body, $request_uri, $request_method, $scheme.

Значение поддерживает два вида сопоставления:

Сравнение строк без учета регистра. Например:
- john - сопоставление без учета регистра, которое выполняется успешно для таких строк, как john, John, JOHN.
- !john - отрицание соответствия без учета регистра для john, которое выполняется успешно для таких строк, как bob, anything, " (пустая строка).
Сопоставление с регулярным выражением. Обратите внимание, что Angie поддерживает регулярные выражения, совместимые с языком программирования Perl (PCRE). Например:
- ~^yes - регулярное выражение с учетом регистра, которое соответствует любой строке, начинающейся с yes. Например: yes, yes123.
- !~^yes - отрицание предыдущего регулярного выражения, которое успешно выполняется для строк типа YES, Yes123, noyes. (Механизм отрицания не является частью синтаксиса PCRE).
- ~*no$ – регулярное выражение без учета регистра, которое соответствует любой строке, заканчивающейся на no. Например: no, 123no, 123NO.

Примечание

Значение не должно содержать неэкранированных двойных кавычек (") и не должно заканчиваться неэкранированной обратной косой чертой (\). Например, следующие значения недопустимы: some"value, somevalue\.

ErrorPage¶

Определяет настраиваемый ответ для маршрута на случай, когда сервер апстрима отвечает кодом состояния ошибки (или его генерирует Angie). В качестве ответа может быть задано перенаправление или сохраненный ответ. Дополнительные сведения см. в описании директивы error_page .

path: /coffee
errorPages:
  - codes: [502, 503]
    redirect:
      code: 301
      url: https://angie.software
  - codes: [404]
    return:
      code: 200
      body: "Original resource not found, but success!"

Поле	Описание	Тип	Обязательно
`codes`	Список кодов состояния ошибки.	`[]int`	Да
`redirect`	Действие перенаправления для заданных кодов состояния.	errorPage.Redirect	Нет
`return`	Сохраненное ответное действие для заданных кодов состояния.	errorPage.Return	Нет

Примечание

Страница с ошибкой должна содержать ровно одно из следующих значений: return или redirect.

ErrorPage.Redirect¶

Определяет перенаправление для errorPage.

В приведенном ниже примере Angie отвечает перенаправлением, когда ответ от сервера апстрима имеет код состояния 404.

codes: [404]
redirect:
  code: 301
  url: ${scheme}://cafe.example.com/error.html

Поле	Описание	Тип	Требуется
`код`	Код состояния перенаправления. Допустимые значения: `301`, `302`, `307`, `308`. Значение по умолчанию - `301`.	`int`	Нет
`url`	URL-адрес, на который будет перенаправлен запрос. Поддерживаемые переменные Angie: `$scheme` и `$http_x_forwarded_proto`. Переменные должны быть заключены в фигурные скобки. Например: `${scheme}`.	`string`	Да

ErrorPage.Return¶

Определяет сохраненный ответ для errorPage.

В приведенном ниже примере Angie выдает сохраненный ответ, когда ответ от сервера апстрима имеет код состояния 401 или 403.

codes: [401, 403]
return:
  code: 200
  type: application/json
  body: |
    {\"msg\": \"You don't have permission to do this\"}
  headers:
    - name: x-debug-original-statuses
      value: ${upstream\_status}

Поле	Описание	Тип	Обязательно
`code`	Код состояния ответа. По умолчанию используется код состояния исходного ответа.	`int`	Нет
`type`	MIME-тип ответа. Значение по умолчанию - `text/html`.	`string`	Нет
`body`	Тело ответа. Поддерживаемая переменная Angie: `$upstream_status`. Переменные должны быть заключены в фигурные скобки. Например: `${upstream_status}`.	`string`	Да
`headers`	Настраиваемые заголовки ответа.	errorPage.Return.Header	Нет

ErrorPage.Return.Header¶

Определяет HTTP-заголовок для сохраненного ответа у errorPage:

name: x-debug-original-statuses
value: ${upstream_status}

Поле	Описание	Тип	Требуется
`name`	Имя заголовка.	`string`	Да
`value`	Значение заголовка. Поддерживаемая переменная Angie: `$upstream_status`. Переменные должны быть заключены в фигурные скобки. Например: `${upstream_status}`.	`string`	Нет

Использование VirtualServer и VirtualServerRoute¶

Для работы с ресурсами VirtualServer и VirtualServerRoute можно использовать обычные команды kubectl, аналогично ресурсам Ingress.

Например, следующая команда создает ресурс VirtualServer, определенный в cafe-virtual-server.yaml с именем cafe:

kubectl apply -f cafe-virtual-server.yaml

virtualserver.k8s.angie.software "cafe" created

Вы можете получить ресурс, выполнив:

kubectl get virtualserver cafe

NAME   STATE   HOST                   IP            PORTS      AGE
cafe   Valid   cafe.example.com       12.13.23.123  [80,443]   3m

В kubectl get и подобных командах также можно использовать короткое имя vs вместо virtualserver.

Работать с ресурсами VirtualServerRoute можно аналогично. В командах kubectl используйте virtualserverroute или короткое имя vsr.

Использование фрагментов¶

Фрагменты позволяют вставлять элементы конфигурации Angie в различные контексты конфигурации Angie. В приведенном ниже примере мы используем фрагменты кода для настройки нескольких функций Angie на VirtualServer:

apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
  name: cafe
  namespace: cafe
spec:
  http-snippets: |
    limit_req_zone $binary_remote_addr zone=mylimit:10m rate=1r/s;
    proxy_cache_path /tmp keys_zone=one:10m;
  host: cafe.example.com
  tls:
    secret: cafe-secret
  server-snippets: |
    limit_req zone=mylimit burst=20;
  upstreams:
    - name: tea
      service: tea-svc
      port: 80
    - name: coffee
      service: coffee-svc
      port: 80
  routes:
    - path: /tea
      location-snippets: |
        proxy\_cache one;
        proxy\_cache\_valid 200 10m;
      action:
        pass: tea
    - path: /coffee
      action:
        pass: coffee

Фрагменты предназначены для продвинутых пользователей Angie, которым требуется больше контроля над генерируемой конфигурацией Angie.

Однако из-за недостатков, описанных ниже, фрагменты по умолчанию отключены. Чтобы использовать фрагменты, задайте аргумент командной строки enable-snippets.

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

Сложность. Чтобы использовать фрагменты, требуется:
- Понимать примитивы конфигурации Angie и реализовать правильную конфигурацию Angie.
- Понимать, как IC генерирует конфигурацию Angie, чтобы фрагмент не мешал другим функциям конфигурации.
Сниженная надежность. Неправильный фрагмент делает конфигурацию Angie недействительной, что приведет к ошибке при перезагрузке. Это помешает применить какие-либо обновления конфигурации, включая обновления для других ресурсов VirtualServer и VirtualServerRoute, пока фрагмент не будет исправлен.
Последствия для безопасности. Фрагменты предоставляют доступ к примитивам конфигурации Angie, и эти примитивы не проверяются самим Ingress Controller. Например, через фрагмент можно настроить в Angie произвольную отправку сертификатов TLS и ключей, используемых для завершения TLS у ресурсов Ingress и VirtualServer.

Чтобы помочь отлавливать ошибки при использовании фрагментов, Ingress Controller сообщает об ошибках перезагрузки конфигурации в журналах, а также в полях событий и состояния ресурсов VirtualServer и VirtualServerRoute.

Примечание. Пока конфигурация Angie содержит недопустимый фрагмент, Angie будет продолжать работать с последней допустимой конфигурацией.

Валидация¶

Для ресурсов VirtualServer и VirtualServerRoute доступны два типа валидации:

Структурная валидация с помощью kubectl и сервера Kubernetes API.
Всесторонняя валидация с помощью Ingress Controller.

Структурная валидация¶

Пользовательские определения ресурсов для VirtualServer и VirtualServerRoute включают структурную схему OpenAPI, которая описывает тип каждого поля этих ресурсов.

Если вы попытаетесь создать (или обновить) ресурс с нарушением структурной схемы (например, используете строковое значение для поля порта апстрима), kubectl и сервер Kubernetes API отклонят такой ресурс:

Пример проверки kubectl:

kubectl apply -f cafe-virtual-server.yaml

  error: error validating "cafe-virtual-server.yaml": error validating
  data: ValidationError(VirtualServer.spec.upstreams[0].port): invalid
  type for software.angie.k8s.v1.VirtualServer.spec.upstreams.port: got
  "string", expected "integer"; if you choose to ignore these errors,
  turn validation off with --validate=false

Пример проверки сервера Kubernetes API:

kubectl apply -f cafe-virtual-server.yaml --validate=false

  The VirtualServer "cafe" is invalid: []: Invalid value:
  map[string]interface {}{ ... }: validation failure list:
  spec.upstreams.port in body must be of type integer: "string"

Если ресурс не отклонен (т. е. не нарушает структурную схему), Ingress Controller проверит его дополнительно.

Всесторонняя валидация¶

Ingress Controller проверяет поля ресурсов VirtualServer и VirtualServerRoute. Если ресурс недействителен, Ingress Controller отклонит его: ресурс продолжит существовать в кластере, но Ingress Controller будет его игнорировать.

Вы можете проверить, успешно ли Ingress Controller применил конфигурацию для VirtualServer. Для нашего примера VirtualServer cafe мы можем запустить:

kubectl describe vs cafe

. . .
Events:
  Type    Reason          Age   From                      Message
  -----
  Normal  AddedOrUpdated  16s   angie-ingress-controller  Configuration for default/cafe was added or updated

Обратите внимание, что раздел «События» (Events) включает событие Normal с причиной AddedOrUpdated, которое информирует нас о том, что конфигурация была успешно применена.

Если вы создадите недопустимый ресурс, Ingress Controller отклонит его и выдаст событие Rejected. Например, если вы создадите VirtualServer cafe с двумя серверами апстрима с одинаковым именем tea, вы получите:

kubectl describe vs cafe

. . .
Events:
  Type     Reason    Age   From                      Message
  -----
  Warning  Rejected  12s   angie-ingress-controller  VirtualServer default/cafe is invalid and was rejected: spec.upstreams[1].name: Duplicate value: "tea"

Обратите внимание, что раздел «События» (Events) включает предупреждающее событие с указанием причины отклонения.

Кроме того, эта информация также доступна в поле status ресурса VirtualServer. Обратите внимание на раздел Status VirtualServer:

kubectl describe vs cafe

. . .
Status:
  External Endpoints:
    Ip:        12.13.23.123
    Ports:     [80,443]
  Message:  VirtualServer default/cafe is invalid and was rejected: spec.upstreams[1].name: Duplicate value: "tea"
  Reason:   Rejected
  State:    Invalid

Ingress Controller проверяет ресурсы VirtualServerRoute аналогичным образом.

Примечание

Если вы внесете ошибку в существующий ресурс, Ingress Controller отклонит его и удалит соответствующую конфигурацию из Angie.

Настройка с помощью ConfigMap¶

Вы можете дополнительно настроить конфигурацию Angie для ресурсов VirtualServer и VirtualServerRoutes, используя ConfigMap. Поддерживается большинство ключей ConfigMap, за следующими исключениями:

proxy-hide-headers
proxy-pass-headers
hsts
hsts-max-age
hsts-include-subdomains
hsts-behind-proxy
redirect-to-https
ssl-redirect