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
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Хост (доменное имя) сервера. Это должен быть допустимый поддомен, как
определено в RFC 1123, например |
|
Да |
|
Конфигурация завершения TLS. |
Нет |
|
|
Включает или отключает
распаковку
архивированных ответов для клиентов. Допустимые пары значений: “on” и
“off”, “true” и “false” или “yes” и “no”. Если значение |
|
Нет |
|
Конфигурация ExternalDNS для VirtualServer. |
Нет |
|
|
Ссылка на DosProtectedResource; установка этого параметра включает защиту VirtualServer от DOS-атак. |
|
Нет |
|
Список политик. |
Нет |
|
|
Список апстримов. |
Нет |
|
|
Список маршрутов. |
Нет |
|
|
Указывает, какой Ingress Controller должен обрабатывать ресурс VirtualServer. |
|
Нет |
|
Указывает, является ли ресурс VirtualServer внутренним маршрутом. |
|
Нет |
|
Задает пользовательский фрагмент в контексте http. |
|
Нет |
|
Задает пользовательский фрагмент в контексте . Имеет приоритет над
ключом ConfigMap |
|
Нет |
VirtualServer.TLS¶
Поле tls определяет конфигурацию TLS для ресурса VirtualServer. Например:
secret: cafe-secret
redirect:
enable: true
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Имя секрета с сертификатом TLS и ключом. Секрет должен принадлежать тому
же пространству имен, что и VirtualServer. Секрет должен иметь тип
|
|
Нет |
|
Конфигурация перенаправления TLS для VirtualServer. |
Нет |
|
|
Конфигурация TLS cert-manager для VirtualServer. |
Нет |
VirtualServer.TLS.Redirect¶
Поле перенаправления настраивает перенаправление TLS для VirtualServer:
enable: true
code: 301
basedOn: scheme
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Включает перенаправление TLS для VirtualServer. Значение по умолчанию
равно |
|
Нет |
|
Код состояния перенаправления. Допустимые значения: |
|
Нет |
|
Атрибут запроса, который Angie будет оценивать для отправки
перенаправления. Допустимыми значениями являются |
|
Нет |
VirtualServer.TLS.CertManager¶
Поле cert-manager настраивает автоматическое управление сертификатами x509 для ресурсов VirtualServer с помощью cert-manager (cert-manager.io). Ознакомьтесь с документацией по конфигурации cert-manager для получения дополнительной информации о развертывании и настройке эмитентов (Issuer). Пример:
cert-manager:
cluster-issuer: "my-issuer-name"
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Имя эмитента. Эмитент - это ресурс cert-manager, который описывает центр сертификации, способный подписывать сертификаты. Он должен находиться в том же пространстве имен, что и ресурс VirtualServer. Обратите внимание, что требуется задать issuer или cluster-issuer, но эти параметры взаимоисключающие - должен быть задан один и только один. |
|
Нет |
|
Имя ClusterIssuer. ClusterIssuer - это ресурс cert-manager, который описывает центр сертификации, способный подписывать сертификаты. Не имеет значения, в каком пространстве имен находится ваш VirtualServer, поскольку ClusterIssuer - это ресурсы, не относящиеся к пространствам имен. Обратите внимание, что требуется задать issuer или cluster-issuer, но эти параметры взаимоисключающие - должен быть задан один и только один. |
|
Нет |
|
Тип внешнего ресурса-эмитента, например AWSPCAIssuer. Это необходимо только для сторонних эмитентов. Его нельзя задавать, если также задан cluster-issuer. |
|
Нет |
|
Группа API внешнего контроллера-эмитента, например awspca.cert-manager.io. Это необходимо только для сторонних эмитентов. Его нельзя задавать, если также задан cluster-issuer. |
|
Нет |
|
Это поле позволяет настроить spec.commonName для создаваемого сертификата. Эта конфигурация добавляет CN к сертификату x509. |
|
Нет |
|
Это поле позволяет настроить поле spec.duration для генерируемого сертификата. Оно должно быть задано с использованием формата time.Duration в Go, который не допускает суффикса d (дни). Указывайте такие значения, используя вместо них суффиксы s, m и h. |
|
Нет |
|
Эта аннотация позволяет настроить поле spec.renewBefore для генерируемого сертификата. Оно должно быть задано с использованием формата time.Duration в Go, который не допускает суффикса d (дни). Указывайте такие значения, используя вместо них суффиксы s, m и h. |
|
Нет |
|
Позволяет настроить поле spec.usages для генерируемого сертификата.
Задайте строку со значениями, разделенными запятыми, т. е. |
|
Нет |
VirtualServer.ExternalDNS¶
Поле ExternalDNS настраивает динамическое управление записями DNS для ресурсов VirtualServer с использованием ExternalDNS . Ознакомьтесь с документацией по конфигурации ExternalDNS для получения дополнительной информации о развертывании и настройке ExternalDNS и поставщиков. Пример:
enable: true
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Включает интеграцию ExternalDNS для ресурса VirtualServer. Значение по
умолчанию равно |
|
Нет |
|
Настраивает метки, применяемые к ресурсам конечной точки, которые будут использоваться ExternalDNS. |
|
Нет |
|
Настраивает свойства, относящиеся к конкретному поставщику, которые содержат имя и значение конфигурации, специфичной для отдельных поставщиков DNS. |
Нет |
|
|
TTL для записи DNS. По умолчанию это значение равно 0. См. документацию ExternalDNS TTL для определения значений по умолчанию для конкретного поставщика |
|
Нет |
|
Тип создаваемой записи, например «A», «AAAA», «CNAME». Если значение не задано, оно автоматически вычисляется на основе внешних конечных точек. |
|
Нет |
VirtualServer.ExternalDNS.ProviderSpecific¶
Поле providerSpecific блока ExternalDNS позволяет указать свойства, специфичные для поставщика, которые представляют собой список пар «ключ-значение» для конфигураций, специфичных для отдельных поставщиков DNS. Пример:
- name: my-name
value: my-value
- name: my-name2
value: my-value2
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Имя в паре «ключ-значение». |
|
Да |
|
Значение в паре «ключ-значение». |
|
Да |
VirtualServer.Policy¶
Ссылается на ресурс Policy по имени и необязательному пространству имен. Например:
name: access-control
Поле |
Описание |
Тип |
Требуется |
---|---|---|---|
|
Имя политики. Если
политика не существует
или недействительна,
Angie выдаст сообщение
об ошибке с кодом
состояния |
|
Да |
|
Пространство имен политики. Если не указано, используется пространство имен ресурса VirtualServer. |
|
Нет |
VirtualServer.Route¶
Маршрут определяет правила для сопоставления клиентских запросов с такими действиями, как передача запроса апстриму. Например:
path: /tea
action:
pass: tea
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Путь маршрута. Angie сопоставит его с URI запроса. Возможные значения:
префикс ( |
|
Да |
|
Список политик. Эти политики имеют приоритет над политиками того же
типа, определенными в |
Нет |
|
|
Действие по умолчанию, выполняемое для запроса. |
Нет |
|
|
Ссылка на DosProtectedResource; установка этого параметра включает защиту маршрута VirtualServer от DOS-атак. |
|
Нет |
|
Конфигурация разделения трафика по умолчанию. Должно быть не менее 2 разделений. |
Нет |
|
|
Правила сопоставления для продвинутой маршрутизации на основе
содержимого. Требуется задать |
Нет |
|
|
Имя ресурса VirtualServerRoute, который определяет этот маршрут. Если
VirtualServerRoute не принадлежит к тому же пространству имен, что и
VirtualServer, необходимо включить пространство имен. Например:
|
|
Нет |
|
Настраиваемые ответы на коды ошибок. Angie будет использовать эти ответы вместо того, чтобы возвращать ответы об ошибках с серверов апстрима или ответы по умолчанию, сгенерированные Angie. Настраиваемый ответ может быть перенаправлением или сохраненным ответом. Например, это может быть перенаправление на другой URL-адрес, если вышестоящий сервер ответил кодом состояния 404. |
Нет |
|
|
Задает пользовательский фрагмент в контексте местоположения. Имеет
приоритет над ключом ConfigMap |
|
Нет |
Примечание
Маршрут должен включать в себя ровно одно из следующих действий:
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.
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Хост (доменное имя) сервера. Это должен быть допустимый поддомен, как
определено в RFC 1123, например |
|
Да |
|
Список апстримов. |
Нет |
|
|
Список вложенных маршрутов. |
Нет |
|
|
Указывает, какой Ingress Controller должен обрабатывать ресурс
VirtualServerRoute. Значение должно совпадать с |
|
Нет |
VirtualServerRoute.Subroute¶
Определяет правила сопоставления клиентских запросов и действий, например передача запроса апстриму. Например:
path: /coffee
action:
pass: coffee
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Путь вложенного маршрута. Angie сопоставит его с URI запроса. Возможные
значения: префикс ( |
|
Да |
|
Список политик. Эти политики имеют приоритет над всеми политиками,
определенными в маршруте VirtualServer, который ссылается на этот
ресурс. Они также имеют приоритет над политиками того же типа,
определенными в |
Нет |
|
|
Действие по умолчанию, выполняемое для запроса. |
Нет |
|
|
Ссылка на DosProtectedResource; установка этого параметра включает защиту вложенного маршрута VirtualServerRoute от DOS-атак. |
|
Нет |
|
Конфигурация разделения трафика по умолчанию. Должно быть не менее 2 разделений. |
Нет |
|
|
Правила сопоставления для продвинутой маршрутизации на основе
содержимого. Требуется задать |
Нет |
|
|
Настраиваемые ответы на коды ошибок. Angie будет использовать эти ответы вместо того, чтобы возвращать ответы об ошибках с серверов апстрима или ответы по умолчанию, сгенерированные Angie. Настраиваемый ответ может быть перенаправлением или сохраненным ответом. Например, это может быть перенаправление на другой URL-адрес, если вышестоящий сервер ответил кодом состояния 404. |
Нет |
|
|
Задает пользовательский фрагмент в контексте местоположения.
Переопределяет значение |
|
Нет |
Примечание
Вложенный маршрут должен включать в себя ровно одно из следующих действий:
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 поддерживается без какой-либо дополнительной настройки.
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Имя апстрима. Это должна быть допустимая метка DNS, как определено в RFC
1035. Например, допустимы значения |
|
Да |
|
Название сервиса.
Сервис должен принадлежать к тому же пространству имен, что и ресурс.
Если сервиса не существует, Angie предположит, что у него нет конечных
точек, и будет возвращать ответ |
|
Да |
|
Выбирает поды внутри сервиса, используя ключи меток и значения. По умолчанию выбраны все поды сервиса. Примечание. Ожидается, что указанные метки будут присутствовать в подах при их создании. Если метки подов изменяются, Ingress Controller не увидит это изменение до тех пор, пока не будет изменено количество подов. |
|
Нет |
|
Позволяет использовать IP-адрес кластера и порт сервиса вместо
использования IP-адреса и порта подов по умолчанию. Когда это поле
включено, поля, которые настраивают поведение Angie, относящееся к
нескольким серверам апстрима (например, |
|
Нет |
|
Порт службы. Если у сервиса не определен этот порт, Angie предположит,
что у него нет конечных точек, и будет возвращать ответ |
|
Да |
|
Метод балансировки нагрузки. Чтобы использовать
циклический метод, укажите |
|
Нет |
|
Время, в течение которого должно произойти указанное количество
неудачных попыток установить связь с сервером апстрима, чтобы он
считался недоступным. См. параметр fail_timeout директивы
сервера. Значение по умолчанию задано в ключе ConfigMap
|
|
Нет |
|
Количество неудачных попыток установить связь с сервером апстрима,
которые должны произойти в течение времени, заданного в
|
|
Нет |
|
Максимальное количество одновременных активных подключений к серверу
апстрима. См. параметр max_conns директивы
сервера. По умолчанию ограничений нет. Примечание. Если включены
соединения keepalive, общее количество активных и неактивных соединений
keepalive к серверу апстрима может превышать значение |
|
Нет |
|
Настраивает кэш для подключений к серверам апстрима. Значение |
|
Нет |
|
Тайм-аут для установления соединения с сервером апстрима. См. директиву
proxy_connect_timeout.
Значение по умолчанию указано в ключе ConfigMap |
|
Нет |
|
Тайм-аут для чтения ответа от сервера апстрима. См. директиву
proxy_read_timeout.
Значение по умолчанию указано в ключе ConfigMap |
|
Нет |
|
Тайм-аут для передачи запроса на сервер апстрима. См. директиву
proxy_send_timeout.
Значение по умолчанию указано в ключе ConfigMap |
|
Нет |
|
Указывает, в каких случаях запрос должен быть передан следующему серверу
апстрима. См. директиву proxy_next_upstream.
Значение по умолчанию - |
|
Нет |
|
Время, в течение которого запрос может быть передан следующему серверу
апстрима. См. директиву proxy_next_upstream_timeout.
Значение |
|
Нет |
|
Количество возможных попыток передачи запроса на следующий сервер
апстрима. См. директиву proxy_next_upstream_tries.
Значение |
|
Нет |
|
Задает максимальный размер текста клиентского запроса. См. директиву
client_max_body_size.
Значение по умолчанию задано в ключе ConfigMap |
|
Нет |
|
Конфигурация TLS для апстрима. |
Нет |
|
|
Включает буферизацию ответов от сервера апстрима. См. директиву
proxy_buffering.
Значение по умолчанию задано в ключе ConfigMap |
|
Нет |
|
Настраивает буферы, используемые для чтения ответа от сервера апстрима в рамках одного соединения. |
Нет |
|
|
Устанавливает размер буфера, используемого для считывания первой части
ответа, полученного от сервера апстрима. См. директиву
proxy_buffer_size.
Значение по умолчанию задано в ключе ConfigMap |
|
Нет |
|
Тип апстрима. Поддерживаются значения |
|
Нет |
Upstream.Buffers¶
Настраивает буферы, используемые для чтения ответа от сервера апстрима в рамках одного соединения.
number: 4
size: 8K
См. директиву proxy_buffers для получения дополнительной информации.
Поле |
Описание |
Тип |
Требуется |
---|---|---|---|
|
Задает количество буферов.
Значение по умолчанию
задано в ключе ConfigMap
|
|
Да |
|
Задает размер буфера.
Значение по умолчанию
задано в ключе ConfigMap
|
|
Да |
Upstream.TLS¶
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Включает HTTPS для запросов к серверам апстрима. Значение по умолчанию
равно |
|
Нет |
Upstream.SessionRoute¶
Поле sessionRoute настраивает сохранение маршрутов, что позволяет передавать запросы от одного и того же клиента на один и тот же сервер апстрима. Информация о назначенном сервере апстрима поддерживается в режиме route Angie.
В приведенном ниже примере мы формируем директиву Angie
sticky route $cookie_route $arg_route;
:
sessionRoute:
enable: true
variables:
\- "\$cookie_route"
\- "\$arg_route"
См. описание режима route
директивы
sticky
для получения дополнительной информации.
Параметры:
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Включает сохранение сеанса в режиме |
|
Нет |
|
Список переменных, подставляемых в директиву |
|
Нет |
Header¶
Определяет HTTP-заголовок:
name: Host
value: example.com
Поле |
Описание |
Тип |
Требуется |
---|---|---|---|
|
Имя заголовка. |
|
Да |
|
Значение заголовка. |
|
Нет |
Action¶
Определяет действие, которое необходимо выполнить для запроса.
В приведенном ниже примере клиентские запросы передаются на апстрим
coffee
:
path: /coffee
action:
pass: coffee
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Передает запросы серверу апстрима. Апстрим с таким именем должен быть определен в ресурсе. |
|
Нет |
|
Перенаправляет запросы на указанный URL-адрес. |
Нет |
|
|
Возвращает предварительно сконфигурированный ответ. |
Нет |
|
|
Передает запросы апстриму, добавляет возможность изменять запрос и ответ (например, переписывать URI или изменять заголовки). |
Нет |
Примечание
Действие должно включать в себя ровно одно из следующих значений: pass
,
redirect
, return
или proxy
.
Action.Redirect¶
Определяет перенаправление, возвращаемое для запроса.
В приведенном ниже примере клиентские запросы направляются на URL-адреса
http://myhost.ru
:
redirect:
url: http://myhost.ru
code: 301
Поле |
Описание |
Тип |
Требуется |
---|---|---|---|
|
URL-адрес, на который будет
перенаправлен запрос.
Поддерживаемые переменные
Angie: |
|
Да |
|
Код состояния перенаправления.
Допустимые значения: |
|
Нет |
Action.Return¶
Определяет предварительно сконфигурированный ответ на запрос.
В приведенном ниже примере Angie будет отвечать предварительно настроенным ответом на каждый запрос:
return:
code: 200
type: text/plain
body: "Hello World\n"
Поле |
Описание |
Тип |
Требуется |
---|---|---|---|
|
Код состояния ответа.
Допустимые значения: |
|
Нет |
|
MIME-тип ответа. Значение по
умолчанию - |
|
Нет |
|
Основная часть ответа.
Поддерживает переменные
Angie*. Переменные должны
быть заключены в фигурные
скобки. Например:
|
|
Да |
Примечание
Поддерживаемые переменные 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 запроса переписывается на /
, а
заголовки запроса и ответа изменяются:
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: /
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Имя апстрима, куда будут проксироваться запросы. Апстрим с таким именем должен быть определен в ресурсе. |
|
Да |
|
Изменения заголовков запросов. |
Нет |
|
|
Изменения в заголовках ответов. |
Нет |
|
|
Переписанный URI. Если путь маршрута является регулярным выражением, т.
е. начинается с ~, то rewritePath может включать группы захвата
|
|
Нет |
Action.Proxy.RequestHeaders¶
Поле requestHeaders изменяет заголовки запроса к проксируемому серверу апстрима.
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Передает исходные заголовки запроса на проксируемый сервер апстрима. Дополнительные сведения см. в описании директивы proxy_pass_request_header. Значение по умолчанию - true. |
|
Нет |
|
Позволяет переопределять или добавлять поля для представления заголовков запросов, передаваемых на проксируемые серверы апстрима. Дополнительные сведения см. в описании директивы proxy_set_header. |
Нет |
Action.Proxy.RequestHeaders.Set.Header¶
Определяет HTTP-заголовок:
name: My-Header
value: My-Value
Можно переопределить значение заголовка Host
по умолчанию, которое Ingress
Controller устанавливает равным $host:
name: Host
value: example.com
Поле |
Описание |
Тип |
Требуется |
---|---|---|---|
|
Имя заголовка. |
|
Да |
|
Значение заголовка.
Поддерживает переменные
Angie*. Переменные должны
быть заключены в фигурные
скобки. Например:
|
|
Нет |
Примечание
Поддерживаемые переменные 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 изменяет заголовки ответа клиенту.
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Заголовки, которые не будут переданы в ответе клиенту с проксируемого сервера апстрима. Дополнительные сведения см. в описании директивы proxy_hide_header. |
|
Нет |
|
Позволяет передавать скрытые поля заголовка клиенту с проксируемого сервера апстрима. Дополнительные сведения см. в описании директивы proxy_pass_header. |
|
Нет |
|
Отключает обработку определенных заголовков** при передаче клиенту ответа с проксируемого сервера апстрима. Дополнительные сведения см. в описании директивы proxy_ignore_headers. |
|
Нет |
|
Добавляет заголовки к ответу для клиента. |
Нет |
Примечание
Скрытые заголовки по умолчанию: 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
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Имя заголовка. |
|
Да |
|
Значение заголовка. Поддерживает переменные Angie*. Переменные должны
быть заключены в фигурные скобки. Например: |
|
Нет |
|
Если установлено значение true, добавляет заголовок независимо от кода состояния ответа**. Значение по умолчанию - false. Дополнительные сведения см. в описании директивы add_header. |
|
Нет |
Примечание
Поддерживаемые переменные 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
.
Примечание
Если значение 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
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Вес действия. Значение должно попадать в диапазон |
|
Да |
|
Действие, которое необходимо выполнить для запроса. |
: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
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Список условий. Должен включать по крайней мере одно условие. |
Да |
|
|
Действие, которое необходимо выполнить для запроса. |
Нет |
|
|
Конфигурация разбиений для разделения трафика. Должно быть указано не менее двух разделений. |
Нет |
Примечание
Сопоставление должно использовать ровно одно из следующих значений:
action
или splits
.
Condition¶
Определяет условие в сопоставлении.
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Имя заголовка. Должно состоять из буквенно-цифровых символов или |
|
Нет |
|
Имя cookie. Должно состоять из буквенно-цифровых символов или |
|
Нет |
|
Имя аргумента. Должно состоять из буквенно-цифровых символов или |
|
Нет |
|
Имя переменной Angie. Должно начинаться с |
|
Нет |
|
Значение, которому должно соответствовать условие. Как определить значение, показано ниже в таблице. |
|
Да |
Примечание
Условие должно включать ровно одно из следующих значений: 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!"
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Список кодов состояния ошибки. |
|
Да |
|
Действие перенаправления для заданных кодов состояния. |
Нет |
|
|
Сохраненное ответное действие для заданных кодов состояния. |
Нет |
Примечание
Страница с ошибкой должна содержать ровно одно из следующих значений:
return
или redirect
.
ErrorPage.Redirect¶
Определяет перенаправление для errorPage.
В приведенном ниже примере Angie отвечает перенаправлением, когда ответ от сервера апстрима имеет код состояния 404.
codes: [404]
redirect:
code: 301
url: ${scheme}://cafe.example.com/error.html
Поле |
Описание |
Тип |
Требуется |
---|---|---|---|
|
Код состояния перенаправления.
Допустимые значения: |
|
Нет |
|
URL-адрес, на который будет
перенаправлен запрос.
Поддерживаемые переменные
Angie: |
|
Да |
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}
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Код состояния ответа. По умолчанию используется код состояния исходного ответа. |
|
Нет |
|
MIME-тип ответа. Значение по умолчанию - |
|
Нет |
|
Тело ответа. Поддерживаемая переменная Angie: |
|
Да |
|
Настраиваемые заголовки ответа. |
Нет |
ErrorPage.Return.Header¶
Определяет HTTP-заголовок для сохраненного ответа у errorPage:
name: x-debug-original-statuses
value: ${upstream_status}
Поле |
Описание |
Тип |
Требуется |
---|---|---|---|
|
Имя заголовка. |
|
Да |
|
Значение заголовка.
Поддерживаемая переменная
Angie: |
|
Нет |
Использование 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