# VirtualServer, VirtualServerRoute Ресурсы VirtualServer и VirtualServerRoute реализуют сценарии использования, не поддерживаемые ресурсом Ingress, такие как разделение трафика и продвинутая маршрутизация на основе содержимого. Они реализованы как [пользовательские ресурсы](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) . Это справочная документация по обоим ресурсам. ## Спецификация VirtualServer Ресурс VirtualServer определяет конфигурацию балансировки нагрузки для доменного имени, например `example.com`. Ниже приведен пример такой конфигурации: ```yaml apiVersion: k8s.angie.software/v1 kind: VirtualServer metadata: name: cafe spec: host: cafe.example.com tls: secret: cafe-secret staticLocations: - type: root urlPath: /americano dirPath: /latte gunzip: on upstreams: - name: tea service: tea-svc port: 80 - name: coffee service: coffee-svc port: 80 routes: authRequest: /auth/p authRequestSets: - key: foo value: bar matches: - conditions: - variable: $request_method value: POST action: pass: tea-post action: pass: tea-post - path: /coffee action: pass: coffee - path: ~ ^/decaf/.\*\\.jpg$ action: pass: coffee - path: = /green/tea action: pass: tea activeHealthProbes: - name: activename1 upstream: tea uri: uri port: 80 interval: 3s isEssential: true isPersistent: true maxBody: 10m fails: 4 passes: 5 mode: onfail maps: - variable: $jwt_claim_iat source: $oidc_client parameters: - value: 'myclient' result: '80' - variable: $jwt_claim_iss source: $oidc_client parameters: - value: 'myclient' result: 'PROVIDER_URL' - variable: $jwt_claim_sub source: $oidc_client parameters: - value: 'myclient' result: 'myclient' - variable: $jwt_claim_aud source: $oidc_client parameters: - value: 'myclient' result: 'myclient' authRequestLocations: - path: /auth/path proxyPass: upstreamName: "tea" proxyPassHeaders: - key: Content-Length value: "100" ``` | Поле | Описание | Тип | Обязательно | |------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|---------------| | `host` | Хост (доменное имя) сервера. Это должен быть допустимый поддомен, как
определено в RFC 1123, например `my-app` или `hello.example.com`.
При использовании домена с подстановочным знаком, например
`*.example.com`, домен должен быть заключен в двойные кавычки.
Значение `host` должно быть уникальным среди всех ресурсов Ingress и
VirtualServer. | `string` | Да | | `tls` | Конфигурация терминации TLS. | [tls](#virtualservertls) | Нет | | `staticLocations` | Список каталогов для раздачи статических файлов. | [staticLocations[ ]](#staticlocations) | Нет | | `gunzip` | Включает или отключает [распаковку](https://angie.software//angie/docs/configuration/modules/http/http_gunzip.md#http-gunzip) архивированных
ответов для клиентов. Допустимые пары значений: "on" и "off", "true" и
"false" или "yes" и "no". Если значение `gunzip` не установлено, то по
умолчанию оно равно `off`. | `boolean` | Нет | | `ExternalDNS` | Конфигурация ExternalDNS для VirtualServer. | [ExternalDNS](#virtualserverexternaldns) | Нет | | `dos` | Ссылка на DosProtectedResource; установка этого параметра включает
защиту VirtualServer от DOS-атак. | `string` | Нет | | `policies` | Список политик. | [policy[ ]](#virtualserverpolicy) | Нет | | `upstreams` | Список апстримов. | [upstream[ ]](#virtualserverupstream) | Нет | | `routes` | Список маршрутов. | [route[ ]](#virtualserverroute) | Нет | | `activeHealthProbes` | Список активных проверок работоспособности. | [activeHealthProbes[ ]](#activehealthprobes) | Нет | | `maps` | Список переменных, необходимых для валидации токенов в процессе [аутентификации OIDC](https://angie.software//anic/docs/configuration/policy-resource.md#oidc-policy). | [maps[ ]](#virtualserver-maps) | Нет | | `ingressClassName` | Указывает, какой экземпляр ANIC должен обрабатывать ресурс
VirtualServer. | `string` | Нет | | `internalRoute` | Указывает, является ли ресурс VirtualServer внутренним маршрутом. | `boolean` | Нет | | `http-snippets` | Задает пользовательский фрагмент в контексте http. | `string` | Нет | | `server-snippets` | Задает пользовательский фрагмент в контексте . Имеет приоритет над
ключом ConfigMap `server-snippets`. | `string` | Нет | | `authRequestLocations` | Задает список точек авторизации клиента при настройке `authRequest`. | [authRequestLocations[ ]](#virtualserverroute-authrequestlocations) | Нет | ### VirtualServer.TLS Поле tls определяет конфигурацию TLS для ресурса VirtualServer. Например: ```yaml secret: cafe-secret redirect: enable: true ssl_session_timeout: 1h ssl_session_cache: shared:SSL:10m ssl_session_tickets: on ssl_stapling: on ssl_stapling_verify: on ``` | Поле | Описание | Тип | Обязательно | |------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------| | `secret` | Имя секрета с сертификатом TLS и ключом. Секрет должен принадлежать тому
же пространству имен, что и VirtualServer. Секрет должен иметь тип
`kubernetes.io/tls` и содержать ключи с именами `tls.crt` и
`tls.key`, содержащие сертификат и закрытый ключ, как описано [здесь](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls).
Если секрет не существует или недействителен, Angie прервет любую
попытку установить TLS-соединение с хостом VirtualServer. Если секрет не
указан, но настроен секрет TLS с подстановочным знаком,
Angie будет использовать секрет со знаком для терминации TLS. | `string` | Нет | | `redirect` | Конфигурация перенаправления TLS для VirtualServer. | [tls.redirect](#virtualservertlsredirect) | Нет | | `cert-manager` | Конфигурация TLS cert-manager для VirtualServer. | [tls.cert-manager](#virtualservertlscertmanager) | Нет | | `ssl_session_timeout` | Задает время, в течение которого клиент может повторно использовать параметры сессии. См. также директиву
[ssl_session_timeout](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-session-timeout) в документации Angie. Значение по умолчанию `10m`. | `string` | Нет | | `ssl_session_cache` | Задает тип и размеры кэшей для хранения параметров сессий. См. также директиву
[ssl_session_cache](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-session-cache) в документации Angie. Значение по умолчанию `shared:SSL:10m`. | `string` | Нет | | `sssl_session_tickets` | Разрешает или запрещает возобновление сессий при помощи TLS session tickets. См. также директиву
[ssl_session_tickets](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-session-tickets) в документации Angie. Значение по умолчанию `off`. | `string` | Нет | | `ssl_stapling` | Разрешает или запрещает прикрепление OCSP-ответов сервером. См. также директиву
[ssl_stapling](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-stapling) в документации Angie. Значение по умолчанию `on`. | `string` | Нет | | `ssl_stapling_verify` | Разрешает или запрещает проверку сервером ответов OCSP. См. также директиву
[ssl_stapling_verify](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-stapling-verify) в документации Angie. Значение по умолчанию `on`. | `string` | Нет | ### VirtualServer.TLS.Redirect Поле перенаправления настраивает перенаправление TLS для VirtualServer: ```yaml 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](https://cert-manager.io/docs/configuration/) для получения дополнительной информации о развертывании и настройке эмитентов (Issuer). Пример: ```yaml 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](https://pkg.go.dev/time#ParseDuration) в Go, который
не допускает суффикса d (дни). Указывайте такие значения, используя
вместо них суффиксы s, m и h. | `string` | Нет | | `renew-before` | Эта аннотация позволяет настроить поле spec.renewBefore для
генерируемого сертификата. Оно должно быть задано с использованием
формата [time.Duration](https://pkg.go.dev/time#ParseDuration) в Go,
который не допускает суффикса d (дни). Указывайте такие значения,
используя вместо них суффиксы s, m и h. | `string` | Нет | | `usages` | Позволяет настроить поле spec.usages для генерируемого сертификата.
Задайте строку со значениями, разделенными запятыми, т. е. `соглашение
о ключе, цифровая подпись, серверная аутентификация`. Исчерпывающий
список поддерживаемых способов использования ключей можно найти в
[документации API cert-manager](https://cert-manager.io/docs/reference/api-docs/#cert-manager.io/v1.KeyUsage). | `string` | Нет | ### VirtualServer.ExternalDNS Поле ExternalDNS настраивает динамическое управление записями DNS для ресурсов VirtualServer с использованием [ExternalDNS](https://github.com/kubernetes-sigs/external-dns) . Ознакомьтесь [с документацией по конфигурации ExternalDNS](https://kubernetes-sigs.github.io/external-dns/v0.12.0/) для получения дополнительной информации о развертывании и настройке ExternalDNS и поставщиков. Пример: ```yaml enable: true ``` | Поле | Описание | Тип | Обязательно | |--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|---------------| | `enable` | Включает интеграцию ExternalDNS для ресурса VirtualServer. Значение по
умолчанию равно `false`. | `string` | Нет | | `labels` | Настраивает метки, применяемые к ресурсам конечной точки, которые будут
использоваться ExternalDNS. | `map[string]string` | Нет | | `providerSpecific` | Настраивает свойства, относящиеся к конкретному поставщику, которые
содержат имя и значение конфигурации, специфичной для отдельных
поставщиков DNS. | [ProviderSpecific[ ]](#virtualserverexternaldnsproviderspecific) | Нет | | `recordTTL` | TTL для записи DNS. По умолчанию это значение равно 0. См. [документацию
ExternalDNS TTL для определения значений по умолчанию для конкретного
поставщика](https://kubernetes-sigs.github.io/external-dns/v0.12.0/ttl/#providers) | `int64` | Нет | | `recordType` | Тип создаваемой записи, например "A", "AAAA", "CNAME". Если значение не
задано, оно автоматически вычисляется на основе внешних конечных точек. | `string` | Нет | ### VirtualServer.ExternalDNS.ProviderSpecific Поле providerSpecific блока ExternalDNS позволяет указать свойства, специфичные для поставщика, которые представляют собой список пар "ключ-значение" для конфигураций, специфичных для отдельных поставщиков DNS. Пример: ```yaml - name: my-name value: my-value - name: my-name2 value: my-value2 ``` | Поле | Описание | Тип | Обязательно | |---------|----------------------------------|----------|---------------| | `name` | Имя в паре "ключ-значение". | `string` | Да | | `value` | Значение в паре "ключ-значение". | `string` | Да | ### VirtualServer.Policy Ссылается на [ресурс Policy](https://angie.software//anic/docs/configuration/policy-resource.md#policy-resource) по имени и необязательному пространству имен. Например: ```yaml name: access-control ``` | Поле | Описание | Тип | Обязательно | |-------------|------------------------------------------------------------------------------------------------------------------------------|----------|---------------| | `name` | Имя политики. Если политика не существует или недействительна,
Angie выдаст сообщение об ошибке с кодом состояния `500`. | `string` | Да | | `namespace` | Пространство имен политики. Если не указано, используется
пространство имен ресурса VirtualServer. | `string` | Нет | ### VirtualServer.Route Маршрут определяет правила для сопоставления клиентских запросов с такими действиями, как передача запроса апстриму. Например: ```yaml path: /tea action: pass: tea ``` | Поле | Описание | Тип | Обязательно | |---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|---------------| | `path` | Путь маршрута. Angie сопоставит его с URI запроса. Возможные значения:
префикс (`/`, `/path`), точное совпадение (`=/exact/match`),
регулярное выражение без учета регистра (`~*^/Bar.*.jpg`) или
регулярное выражение с учетом регистра (`~^/foo.*.jpg`). В случае
префикса (должен начинаться с `/` ) или точного совпадения (должно
начинаться с `=` ) путь не должен содержать никаких пробельных
символов, `{` , `}` или `;`. В случае регулярных выражений все
двойные кавычки `"` должны быть экранированы, при этом совпадение не
может заканчиваться неэкранированной обратной косой чертой \\. Путь
должен быть уникальным среди путей всех маршрутов VirtualServer.
Дополнительные сведения см. в описании директивы
[location](https://angie.software//angie/docs/configuration/modules/http/index.md#location). | `string` | Да | | `policies` | Список политик. Эти политики имеют приоритет над политиками того же
типа, определенными в `спецификации` VirtualServer. Более подробную
информацию смотрите в [Применение политик](https://angie.software//anic/docs/configuration/policy-resource.md#applying-policies). | [policy[ ]](#virtualserverpolicy) | Нет | | `action` | Действие по умолчанию, выполняемое для запроса. | [Action](https://angie.software//anic/docs/configuration/transportserver-resource.md#action) | Нет | | `dos` | Ссылка на DosProtectedResource; установка этого параметра включает
защиту маршрута VirtualServer от DOS-атак. | `string` | Нет | | `splits` | Конфигурация разделения трафика по умолчанию. Должно быть не менее 2
разделений. | [Split](#split) | Нет | | `matches` | Правила сопоставления для продвинутой маршрутизации на основе
содержимого. Требуется задать `action` или `splits` по умолчанию.
Несопоставленные запросы будут обрабатываться `action` или `splits`
по умолчанию. | [matches](#match) | Нет | | `route` | Имя ресурса VirtualServerRoute, который определяет этот маршрут. Если
VirtualServerRoute не принадлежит к тому же пространству имен, что и
VirtualServer, необходимо включить пространство имен. Например:
`tea-namespace/tea`. | `string` | Нет | | `errorPages` | Настраиваемые ответы на коды ошибок. Angie будет использовать эти ответы
вместо того, чтобы возвращать ответы об ошибках с серверов апстрима или
ответы по умолчанию, сгенерированные Angie. Настраиваемый ответ может
быть перенаправлением или сохраненным ответом. Например, это может быть
перенаправление на другой URL-адрес, если вышестоящий сервер ответил
кодом состояния 404. | [errorPage[ ]](#errorpage) | Нет | | `location-snippets` | Задает пользовательский фрагмент в контексте местоположения. Имеет
приоритет над ключом ConfigMap `location-snippets`. | `string` | Нет | | `authRequest` | Осуществляет авторизацию, основанную на результате выполнения подзапроса, и задает URI, на который будет отправлен подзапрос. | [auth_request[ ]](https://angie.software//angie/docs/configuration/modules/http/http_auth_request.md#id3) | Нет | | `authRequestSets` | После завершения запроса авторизации устанавливает указанное значение для переменной в запросе. | [auth_request_set[ ]](https://angie.software//angie/docs/configuration/modules/http/http_auth_request.md#auth-request-set) | Нет | #### NOTE Маршрут должен включать в себя ровно одно из следующих действий: `action`, `splits` или `route`. ### Maps Определяет обязательные переменные `$jwt_claim_iat`, `$jwt_claim_iss`, `$jwt_claim_sub` и `$jwt_claim_aud` для валидации токенов в процессе [аутентификации OIDC](https://angie.software//anic/docs/configuration/policy-resource.md#oidc-policy). ```yaml - variable: $jwt_claim_iat source: $oidc_client parameters: - value: 'myclient' result: '80' - variable: $jwt_claim_iss source: $oidc_client parameters: - value: 'myclient' result: 'PROVIDER_URL' - variable: $jwt_claim_sub source: $oidc_client parameters: - value: 'myclient' result: 'myclient' - variable: $jwt_claim_aud source: $oidc_client parameters: - value: 'myclient' result: 'myclient' ``` Пример включения переменных `map` в зависимости от входного значения (`default`, `volatile`, `include`, `hostnames`): ```yaml maps: - variable: $result_var source: $host parameters: - value: 'default' result: 'default_value' - value: 'volatile' result: '' - value: 'include' result: '/dev/stdout' - value: 'example.com' result: '1' - value: '*.example.com' result: '1' ``` См. также директиву [map](https://angie.software//angie/docs/configuration/modules/stream/stream_map.md#stream-map) в документации Angie. | Поле | Описание | Тип | Обязательно | |------------------|---------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------| | `$jwt_claim_iat` | Настраивает параметр `iat` (issued at, время выпуска токена) для клиента. | `string` | Да | | `$jwt_claim_iss` | Параметр `iss` (issuer, издатель токена) сопоставляется с URL-адресом `PROVIDER_URL`. Этот параметр указывает на сервис, выпустивший токен. | `string` | Да | | `$jwt_claim_sub` | Параметр `sub` (subject, субъект токена). Идентифицирует пользователя или субъект, для которого был выдан токен. | `string` | Да | | `$jwt_claim_aud` | Параметр `aud` (audience, аудитория). Идентифицирует клиент, для которого был предназначен токен. | `string` | Да | ### authRequestLocations Задает список точек авторизации для настройки `authRequest`. См. также директиву [auth_request](https://angie.software//angie/docs/configuration/modules/http/http_auth_request.md#id3) в документации Angie. ```yaml authRequestLocations: - path: /auth/path proxyPass: upstreamName: "tea" proxyPassHeaders: - key: Content-Length value: "100" ``` | Поле | Описание | Тип | Обязательно | |--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------| | `path` | Задает конкретный путь, на который будет отправляться запрос для проверки авторизации. | `string` | Да | | `proxyPass` | Задает список апстримов, к которым будет направлен запрос. См. также директиву [proxy_pass](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-pass) в документации Angie. | `string` | Да | | `proxyPassHeaders` | Список заголовков, которые будут добавлены или изменены при проксировании запросов. | `string` | Да | ## Спецификация VirtualServerRoute Ресурс VirtualServerRoute определяет маршрут для VirtualServer. Он может состоять из одного вложенного маршрута или нескольких. VirtualServerRoute является альтернативой объединяемым типам Ingress. В приведенном ниже примере виртуальный сервер `cafe` из пространства имен `cafe-ns` определяет маршрут с путем `/coffee`, который далее определяется через VirtualServerRoute `coffee` из пространства имен `coffee-ns`. VirtualServer: ```yaml 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: ```yaml 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[ ]](https://angie.software//anic/docs/configuration/transportserver-resource.md#upstream) | Нет | | `subroutes` | Список вложенных маршрутов. | [subroute[ ]](#virtualserverroutesubroute) | Нет | | `ingressClassName` | Указывает, какой экземпляр ANIC должен обрабатывать ресурс
VirtualServerRoute. Значение должно совпадать с `ingressClassName` у
VirtualServer, который ссылается на этот ресурс. | `string` | Нет | ### VirtualServerRoute.Subroute Определяет правила сопоставления клиентских запросов и действий, например передача запроса апстриму. Например: ```yaml path: /coffee action: pass: coffee ``` | Поле | Описание | Тип | Обязательно | |---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|---------------| | `path` | Путь вложенного маршрута. Angie сопоставит его с URI запроса. Возможные
значения: префикс (`/`, `/path`), точное совпадение
(`=/exact/match`), регулярное выражение без учета регистра
(`~*^/Bar.*.jpg`) или регулярное выражение с учетом регистра
(`~^/foo.*.jpg`). В случае префикса путь должен начинаться с того же
пути, что и путь маршрута VirtualServer, который ссылается на этот
ресурс. В случае точного совпадения или регулярного выражения путь
должен совпадать с путем маршрута VirtualServer, который ссылается на
этот ресурс. В случае префикса или точного совпадения путь не должен
содержать никаких пробельных символов, `{` , `}` или `;`. В
случае регулярных выражений все двойные кавычки `"` должны быть
экранированы, при этом совпадение не может заканчиваться
неэкранированной обратной косой чертой . Путь должен быть уникальным
среди путей всех вложенных маршрутов VirtualServerRoute. | `string` | Да | | `policies` | Список политик. Эти политики имеют приоритет над *всеми* политиками,
определенными в маршруте VirtualServer, который ссылается на этот
ресурс. Они также имеют приоритет над политиками того же типа,
определенными в `спецификации` VirtualServer. Более подробную
информацию смотрите в разделе [Применение политик](https://angie.software//anic/docs/configuration/policy-resource.md#applying-policies). | [policy[ ]](#virtualserverpolicy) | Нет | | `action` | Действие по умолчанию, выполняемое для запроса. | [Action](https://angie.software//anic/docs/configuration/transportserver-resource.md#action) | Нет | | `dos` | Ссылка на DosProtectedResource; установка этого параметра включает
защиту вложенного маршрута VirtualServerRoute от DOS-атак. | `string` | Нет | | `splits` | Конфигурация разделения трафика по умолчанию. Должно быть не менее 2
разделений. | [split[ ]](#split) | Нет | | `matches` | Правила сопоставления для продвинутой маршрутизации на основе
содержимого. Требуется задать `action` или `splits` по умолчанию.
Несопоставленные запросы будут обрабатываться `action` или `splits`
по умолчанию. | [matches](#match) | Нет | | `errorPages` | Настраиваемые ответы на коды ошибок. Angie будет использовать эти ответы
вместо того, чтобы возвращать ответы об ошибках с серверов апстрима или
ответы по умолчанию, сгенерированные Angie. Настраиваемый ответ может
быть перенаправлением или сохраненным ответом. Например, это может быть
перенаправление на другой URL-адрес, если вышестоящий сервер ответил
кодом состояния 404. | [errorPage[ ]](#errorpage) | Нет | | `location-snippets` | Задает пользовательский фрагмент в контексте местоположения.
Переопределяет значение `location-snippets` VirtualServer (если
задано) или ключ ConfigMap `location-snippets`. | `string` | Нет | #### NOTE Вложенный маршрут должен включать в себя ровно одно из следующих действий: `action` или `splits`. ## Общие части VirtualServer и VirtualServerRoute ### Upstream Апстрим определяет конечное место назначения для конфигурации маршрутизации. Например: ```yaml 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 ``` #### NOTE Протокол WebSocket поддерживается без какой-либо дополнительной настройки. | Поле | Описание | Тип | Обязательно | |-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|---------------| | `name` | Имя апстрима. Это должна быть допустимая метка DNS, как определено в RFC
1035. Например, допустимы значения `hello` и `upstream-123`. Имя
должно быть уникальным среди всех апстримов ресурса. | `string` | Да | | `service` | Название [сервиса](https://kubernetes.io/docs/concepts/services-networking/service/).
Сервис должен принадлежать к тому же пространству имен, что и ресурс.
Если сервиса не существует, Angie предположит, что у него нет конечных
точек, и будет возвращать ответ `502` для запросов к этому апстриму. | `string` | Да | | `subselector` | Выбирает поды внутри сервиса, используя ключи меток и значения. По
умолчанию выбраны все поды сервиса.

#### NOTE
Ожидается, что указанные метки будут присутствовать
в подах при их создании. Если метки подов
изменяются, ANIC не увидит это изменение до тех пор, пока
не будет изменено количество подов. | `map[string]string` | Нет | | `use-cluster-ip` | Позволяет использовать IP-адрес кластера и порт сервиса вместо
использования IP-адреса и порта подов по умолчанию. Когда это поле
включено, поля, которые настраивают поведение Angie, относящееся к
нескольким серверам апстрима (например, `lb-method` и
`next-upstream`), не будут иметь никакого эффекта, поскольку ANIC
настроит Angie только с одним сервером апстрима, который
будет соответствовать IP-адресу кластера сервиса. | `boolean` | Нет | | `port` | Порт службы. Если у сервиса не определен этот порт, Angie предположит,
что у него нет конечных точек, и будет возвращать ответ `502` для
запросов к этому апстриму. Значение должно находиться в диапазоне
`1..65535`. | `uint16` | Да | | `lb-method` | Метод [балансировки нагрузки](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream). Чтобы использовать
циклический метод, укажите `round_robin`. Значение по умолчанию указано
в ключе `lb-method` ConfigMap. | `string` | Нет | | `fail-timeout` | Время, в течение которого должно произойти указанное количество неудачных
попыток установить связь с сервером апстрима, чтобы он считался
недоступным. См. параметр `fail_timeout` директивы [server](https://angie.software//angie/docs/configuration/modules/http/index.md#server).
Значение по умолчанию задано в ключе ConfigMap `fail-timeout`. | `string` | Нет | | `max-fails` | Количество неудачных попыток установить связь с сервером апстрима,
которые должны произойти в течение времени, заданного в
`fail-timeout`, чтобы считать сервер недоступным. См. параметр
[max_fails](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails)
директивы сервера. Значение по умолчанию задано в ключе ConfigMap
`max-fails`. | `int` | Нет | | `max-conns` | Максимальное количество одновременных активных подключений к серверу
апстрима. См. параметр `max_conns`
директивы [server](https://angie.software//angie/docs/configuration/modules/http/index.md#server). По умолчанию ограничений нет.

#### NOTE
Если включены соединения keepalive, общее
количество активных и неактивных соединений keepalive
к серверу апстрима может превышать значение `max_conns`. | `int` | Нет | | `keepalive` | Настраивает кэш для подключений к серверам апстрима. Значение `0`
отключает кэш. См. директиву [keepalive](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive). Значение
по умолчанию задано в ключе ConfigMap `keepalive`. | `int` | Нет | | `connect-timeout` | Тайм-аут для установления соединения с сервером апстрима. См. директиву
[proxy_connect_timeout](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-connect-timeout).
Значение по умолчанию указано в ключе ConfigMap `proxy-connect-timeout`. | `string` | Нет | | `read-timeout` | Тайм-аут для чтения ответа от сервера апстрима. См. директиву
[proxy_read_timeout](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-read-timeout).
Значение по умолчанию указано в ключе ConfigMap `proxy-read-timeout`. | `string` | Нет | | `send-timeout` | Тайм-аут для передачи запроса на сервер апстрима. См. директиву
[proxy_send_timeout](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-send-timeout).
Значение по умолчанию указано в ключе ConfigMap `proxy-send-timeout`. | `string` | Нет | | `next-upstream` | Указывает, в каких случаях запрос должен быть передан следующему серверу
апстрима. См. директиву [proxy_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream).
Значение по умолчанию - `тайм-аут ошибки`. | `string` | Нет | | `next-upstream-timeout` | Время, в течение которого запрос может быть передан следующему серверу
апстрима. См. директиву [proxy_next_upstream_timeout](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream-timeout).
Значение `0` отключает ограничение по времени. Значение по умолчанию
равно `0`. | `string` | Нет | | `next-upstream-tries` | Количество возможных попыток передачи запроса на следующий сервер
апстрима. См. директиву [proxy_next_upstream_tries](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream-tries).
Значение `0` отключает это ограничение. Значение по умолчанию равно
`0`. | `int` | Нет | | `client-max-body-size` | Задает максимальный размер текста клиентского запроса. См. директиву
[client_max_body_size](https://angie.software//angie/docs/configuration/modules/http/index.md#client-max-body-size).
Значение по умолчанию задано в ключе ConfigMap `client-max-body-size`. | `string` | Нет | | `tls` | Конфигурация TLS для апстрима. | [tls](#upstreamtls) | Нет | | `buffering` | Включает буферизацию ответов от сервера апстрима. См. директиву
[proxy_buffering](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-buffering).
Значение по умолчанию задано в ключе ConfigMap `proxy-buffering`. | `boolean` | Нет | | `buffers` | Настраивает буферы, используемые для чтения ответа от сервера апстрима в
рамках одного соединения. | [buffers](#upstreambuffers) | Нет | | `buffer-size` | Устанавливает размер буфера, используемого для считывания первой части
ответа, полученного от сервера апстрима. См. директиву
[proxy_buffer_size](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-buffer-size).
Значение по умолчанию задано в ключе ConfigMap `proxy-buffer-size`. | `string` | Нет | | `type` | Тип апстрима. Поддерживаются значения `http` и `grpc`. По умолчанию
используется `http`. Для gRPC необходимо включить HTTP/2 в
`ConfigMap` и настроить терминацию TLS на VirtualServer. | `string` | Нет | ### Upstream.Buffers Настраивает буферы, используемые для чтения ответа от сервера апстрима в рамках одного соединения. ```yaml number: 4 size: 8K ``` См. директиву [proxy_buffers](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-buffers) для получения дополнительной информации. | Поле | Описание | Тип | Обязательно | |----------|----------------------------------------------------------------------------------------------------------------------------|----------|---------------| | `number` | Задает количество буферов. Значение по умолчанию задано в ключе ConfigMap `proxy-buffers`. | `int` | Да | | `size` | Задает размер буфера. Если значение не указано, то по умолчанию будет задано 8K. См. также ключ ConfigMap `proxy-buffers`. | `string` | Нет | ### Upstream.TLS | Поле | Описание | Тип | Обязательно | |----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------| | `enable` | Включает HTTPS для запросов к серверам апстрима. Значение по умолчанию
равно `False`, что означает, что будет использоваться HTTP.

#### NOTE
По умолчанию Angie не будет проверять сертификат вышестоящего сервера.
Чтобы включить проверку, настройте [политику EgressMTLS](https://angie.software//anic/docs/configuration/policy-resource.md#egressmtls). | `boolean` | Нет | ### Upstream.SessionCookie Поле SessionCookie настраивает сохранение сеансов, что позволяет передавать запросы от одного и того же клиента на один и тот же сервер апстрима. Информация о назначенном сервере апстрима передается в сеансовом cookie, сгенерированном Angie. В приведенном ниже примере мы настраиваем сохранение сеанса с помощью cookie сеанса для апстрима и задаем все доступные параметры: ```yaml 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](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-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;`: ```yaml sessionRoute: enable: true variables: \- "\$cookie_route" \- "\$arg_route" ``` См. описание режима `route` директивы [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) для получения дополнительной информации. Параметры: | Поле | Описание | Тип | Обязательно | |-------------|------------------------------------------------------------------------------------------------------------|-------------|---------------| | `enable` | Включает сохранение сеанса в режиме `route` для сервера
апстрима. Значение по умолчанию равно `false`. | `boolean` | Нет | | `variables` | Список переменных, подставляемых в директиву `sticky route`
в порядке следования. | `string[ ]` | Нет | ### ActiveHealthProbes Поле позволяет настроить активную проверку работоспособности (health probe) для [upstream](#virtualserverupstream). Вам необходимо задать имя проверки `name` и `upstream`, к которому она относится, а также другие параметры. Подробное описание параметров для активной проверки работоспособности см. в документации Angie, директива [upstream_probe](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#http-upstream-probe). Пример: ```yaml activeHealthProbes: - name: activename1 upstream: tea-post uri: uri port: 80 interval: 3s isEssential: true isPersistent: true maxBody: 10m fails: 4 passes: 5 mode: onfail ``` ### staticLocations Поле позволяет задать каталог, из которого будут раздаваться статические файлы. Вы можете указать корневой каталог с помощью директивы [root](https://angie.software//angie/docs/configuration/modules/http/index.md#root) или другое расположение с помощью директивы [alias](https://angie.software//angie/docs/configuration/modules/http/index.md#alias), см. описания директив в документации Angie. Пример конфигурации: ```yaml staticLocations: - type: root urlPath: /static dirPath: /var/www/html ``` | Поле | Описание | Тип | Обязательно | |-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------| | `type` | Способ определения пути к каталогу, из которого будут раздаваться статические файлы.
Возможные значения: `root`, `alias`. | `string` | Да | | `urlPath` | Префикс URL-адресов запрашиваемых статических файлов, используемый для
[location](https://angie.software//angie/docs/configuration/modules/http/index.md#location);
см. описание директивы в документации Angie. | `string` | Да | | `dirPath` | Каталог файловой системы, из которого будут обслуживаться запросы к указанному URL-адресу. | `string` | Да | ### Header Определяет HTTP-заголовок: ```yaml name: Host value: example.com ``` | Поле | Описание | Тип | Обязательно | |---------|---------------------|----------|---------------| | `name` | Имя заголовка. | `string` | Да | | `value` | Значение заголовка. | `string` | Нет | ### Action Определяет действие, которое необходимо выполнить для запроса. В приведенном ниже примере клиентские запросы передаются на апстрим `coffee`: ```yaml path: /coffee action: pass: coffee ``` | Поле | Описание | Тип | Обязательно | |------------|-----------------------------------------------------------------------------------------------------------------------------------|------------------------------------|---------------| | `pass` | Передает запросы серверу апстрима. Апстрим с таким именем должен быть
определен в ресурсе. | `string` | Нет | | `redirect` | Перенаправляет запросы на указанный URL-адрес. | [action.redirect](#actionredirect) | Нет | | `return` | Возвращает предварительно сконфигурированный ответ. | [action.return](#actionreturn) | Нет | | `proxy` | Передает запросы апстриму, добавляет возможность изменять запрос и ответ
(например, переписывать URI или изменять заголовки). | [action.proxy](#actionproxy) | Нет | #### NOTE Действие должно включать в себя ровно одно из следующих значений: `pass`, `redirect`, `return` или `proxy`. ### Action.Redirect Определяет перенаправление, возвращаемое для запроса. В приведенном ниже примере клиентские запросы направляются на URL-адреса `http://myhost.ru`: ```yaml 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 будет отвечать предварительно настроенным ответом на каждый запрос: ```yaml 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` | Да | #### NOTE Поддерживаемые переменные 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`. ### Action.Proxy Передает запросы апстриму с возможностью изменять запрос и ответ (например, переписывать URI или изменять заголовки). В приведенном ниже примере URI запроса переписывается на `/`, а заголовки запроса и ответа изменяются: ```yaml 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](#actionproxyrequestheaders) | Нет | | `responseHeaders` | Изменения в заголовках ответов. | [Action.Proxy.ResponseHeaders](#actionproxyresponseheaders) | Нет | | `rewritePath` | Переписанный URI. Если путь маршрута является регулярным выражением, т.
е. начинается с ~, то rewritePath может включать группы захвата
`$1-9`. Например, $1 - первая группа, и так далее. | `string` | Нет | ### Action.Proxy.RequestHeaders Поле requestHeaders изменяет заголовки запроса к проксируемому серверу апстрима. | Поле | Описание | Тип | Обязательно | |--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------| | `pass` | Передает исходные заголовки запроса на проксируемый сервер апстрима.
Дополнительные сведения см. в описании директивы
[proxy_pass_request_headers](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass-request-headers).
Значение по умолчанию - true. | `bool` | Нет | | `set` | Позволяет переопределять или добавлять поля для представления заголовков
запросов, передаваемых на проксируемые серверы апстрима. Дополнительные
сведения см. в описании директивы [proxy_set_header](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-set-header). | [header[ ]](#actionproxyrequestheaderssetheader) | Нет | ### Action.Proxy.RequestHeaders.Set.Header Определяет HTTP-заголовок: ```yaml name: My-Header value: My-Value ``` Можно переопределить значение заголовка `Host` по умолчанию, которое ANIC устанавливает равным [$host](https://angie.software//angie/docs/configuration/modules/http/index.md#v-host): ```yaml name: Host value: example.com ``` | Поле | Описание | Тип | Обязательно | |---------|-------------------------------------------------------------------------------------------------------------------------------------|----------|---------------| | `name` | Имя заголовка. | `string` | Да | | `value` | Значение заголовка. Поддерживает переменные Angie\*. Переменные должны
быть заключены в фигурные скобки. Например: `$*scheme*`. | `string` | Нет | #### NOTE Поддерживаемые переменные 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](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-hide-header). | `string[ ]` | Нет | | `pass` | Позволяет передавать скрытые поля заголовка клиенту с проксируемого
сервера апстрима. Дополнительные сведения см. в описании директивы
[proxy_pass_header](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass-header). | `string[ ]` | Нет | | `ignore` | Отключает обработку определенных заголовков\*\* при передаче клиенту
ответа с проксируемого сервера апстрима. Дополнительные сведения см. в
описании директивы [proxy_ignore_headers](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ignore-headers). | `string[ ]` | Нет | | `add` | Добавляет заголовки к ответу для клиента. | [addHeader[ ]](#addheader) | Нет | #### NOTE Скрытые заголовки по умолчанию: `Date`, `Server`, `X-Pad` и `X-Accel-...`. #### NOTE Следующие поля могут быть проигнорированы: `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`: ```yaml name: My-Header value: My-Value always: true ``` | Поле | Описание | Тип | Обязательно | |----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------| | `name` | Имя заголовка. | `string` | Да | | `value` | Значение заголовка. Поддерживает переменные Angie\*. Переменные должны
быть заключены в фигурные скобки. Например: `$*scheme*`. | `string` | Нет | | `always` | Если установлено значение true, добавляет заголовок независимо от кода
состояния ответа\*\*. Значение по умолчанию - false. Дополнительные
сведения см. в описании директивы [add_header](https://angie.software//angie/docs/configuration/modules/http/http_headers.md#add-header). | `bool` | Нет | #### NOTE Поддерживаемые переменные 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`. #### NOTE Если значение `always` - false, заголовок ответа добавляется только в том случае, если код состояния ответа - это `200`, `201`, `204`, `206`, `301`, `302`, `303`, `304`, `307` или `308`. ### Split Определяет вес действия в составе конфигурации разделений. В приведенном ниже примере Angie передает 80% запросов вышестоящему `coffee-v1`, а оставшиеся 20% - `coffee-v2`: ```yaml 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` ```yaml 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](https://angie.software//angie/docs/configuration/modules/http/index.md#v-request-method), которая представляет HTTP-метод запроса: - все запросы POST -> `coffee-post` - все прочие запросы -> `coffee` ```yaml path: /coffee matches: - conditions: - variable: $request\_method value: POST action: pass: coffee-post action: pass: coffee ``` | Поле | Описание | Тип | Обязательно | |--------------|--------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|---------------| | `conditions` | Список условий. Должен включать по крайней мере одно условие. | [condition[ ]](#condition) | Да | | `action` | Действие, которое необходимо выполнить для запроса. | [Action](https://angie.software//anic/docs/configuration/transportserver-resource.md#action) | Нет | | `splits` | Конфигурация разбиений для разделения трафика. Должно быть указано не
менее двух разделений. | [split[ ]](#split) | Нет | #### NOTE Сопоставление должно использовать ровно одно из следующих значений: `action` или `splits`. ### Condition Определяет условие в сопоставлении. | Поле | Описание | Тип | Обязательно | |------------|----------------------------------------------------------------------------------------------------------|----------|---------------| | `header` | Имя заголовка. Должно состоять из буквенно-цифровых символов или `-`. | `string` | Нет | | `cookie` | Имя cookie. Должно состоять из буквенно-цифровых символов или `_`. | `string` | Нет | | `argument` | Имя аргумента. Должно состоять из буквенно-цифровых символов или `_`. | `string` | Нет | | `variable` | Имя переменной Angie. Должно начинаться с `$`. См. список
поддерживаемых переменных после таблицы. | `string` | Нет | | `value` | Значение, которому должно соответствовать условие. Как определить
значение, показано ниже в таблице. | `string` | Да | #### NOTE Условие должно включать ровно одно из следующих значений: `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`. #### NOTE Значение не должно содержать неэкранированных двойных кавычек (`"`) и не должно заканчиваться неэкранированной обратной косой чертой (`\`). Например, следующие значения недопустимы: `some"value`, `somevalue\`. ### ErrorPage Определяет настраиваемый ответ для маршрута на случай, когда сервер апстрима отвечает кодом состояния ошибки (или его генерирует Angie). В качестве ответа может быть задано перенаправление или сохраненный ответ. Дополнительные сведения см. в описании директивы [error_page](https://angie.software//angie/docs/configuration/modules/http/index.md#error-page). ```yaml 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](#errorpageredirect) | Нет | | `return` | Сохраненное ответное действие для заданных кодов состояния. | [errorPage.Return](#errorpagereturn) | Нет | #### NOTE Страница с ошибкой должна содержать ровно одно из следующих значений: `return` или `redirect`. ### ErrorPage.Redirect Определяет перенаправление для errorPage. В приведенном ниже примере Angie отвечает перенаправлением, когда ответ от сервера апстрима имеет код состояния 404. ```yaml 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. ```yaml 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](#errorpagereturnheader) | Нет | ### ErrorPage.Return.Header Определяет HTTP-заголовок для сохраненного ответа у errorPage: ```yaml 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`: ```console kubectl apply -f cafe-virtual-server.yaml virtualserver.k8s.angie.software "cafe" created ``` Вы можете получить ресурс, выполнив: ```console 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: ```yaml 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. - Понимать, как ANIC генерирует конфигурацию Angie, чтобы фрагмент не мешал другим функциям конфигурации. - *Сниженная надежность*. Неправильный фрагмент делает конфигурацию Angie недействительной, что приведет к ошибке при перезагрузке. Это помешает применить какие-либо обновления конфигурации, включая обновления для других ресурсов VirtualServer и VirtualServerRoute, пока фрагмент не будет исправлен. - *Последствия для безопасности*. Фрагменты предоставляют доступ к примитивам конфигурации Angie, и эти примитивы не проверяются самим ANIC. Например, через фрагмент можно настроить в Angie произвольную отправку сертификатов TLS и ключей, используемых для терминации TLS у ресурсов Ingress и VirtualServer. Чтобы помочь отлавливать ошибки при использовании фрагментов, ANIC сообщает об ошибках перезагрузки конфигурации в журналах, а также в полях событий и состояния ресурсов VirtualServer и VirtualServerRoute. #### NOTE Пока конфигурация Angie содержит недопустимый фрагмент, Angie будет продолжать работать с последней допустимой конфигурацией. ### Валидация Для ресурсов VirtualServer и VirtualServerRoute доступны два типа валидации: - *Структурная валидация* с помощью `kubectl` и сервера Kubernetes API. - *Всесторонняя валидация* с помощью ANIC. #### Структурная валидация Пользовательские определения ресурсов для VirtualServer и VirtualServerRoute включают структурную схему OpenAPI, которая описывает тип каждого поля этих ресурсов. Если вы попытаетесь создать (или обновить) ресурс с нарушением структурной схемы (например, используете строковое значение для поля порта апстрима), `kubectl` и сервер Kubernetes API отклонят такой ресурс: - Пример проверки `kubectl`: ```console 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: ```console 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" ``` Если ресурс не отклонен (т. е. не нарушает структурную схему), ANIC проверит его дополнительно. #### Всесторонняя валидация ANIC проверяет поля ресурсов VirtualServer и VirtualServerRoute. Если ресурс недействителен, ANIC отклонит его: ресурс продолжит существовать в кластере, но ANIC будет его игнорировать. Вы можете проверить, успешно ли ANIC применил конфигурацию для VirtualServer. Для нашего примера VirtualServer `cafe` мы можем запустить: ```console 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, которое информирует нас о том, что конфигурация была успешно применена. Если вы создадите недопустимый ресурс, ANIC отклонит его и выдаст событие Rejected. Например, если вы создадите VirtualServer `cafe` с двумя серверами апстрима с одинаковым именем `tea`, вы получите: ```console 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: ```console 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 ``` ANIC проверяет ресурсы VirtualServerRoute аналогичным образом. #### NOTE Если вы внесете ошибку в существующий ресурс, ANIC отклонит его и удалит соответствующую конфигурацию из 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`