TransportServer#
Ресурс TransportServer позволяет настраивать балансировку нагрузки по протоколам TCP, UDP и TLS Passthrough. Он реализован как пользовательский ресурс.
Это справочная документация по ресурсу TransportServer.
Предварительные требования#
Для TCP и UDP ресурс TransportServer должен использоваться совместно с ресурсом GlobalConfiguration, который должен быть создан отдельно.
Для TLS Passthrough обязательно включите параметр командной строки
-enable-tls-passthrough
в ANIC.
Спецификация TransportServer#
Ресурс TransportServer определяет конфигурацию балансировки нагрузки для трафика TCP, UDP или TLS Passthrough. Ниже приведено несколько примеров:
-
Балансировка нагрузки TCP:
apiVersion: k8s.angie.software/v1alpha1 kind: TransportServer metadata: name: dns-tcp spec: listener: name: dns-tcp protocol: TCP tls: secret: cafe-secret upstreams: - name: dns-app service: dns-service port: 5353 action: pass: dns-app
-
Балансировка нагрузки UDP:
apiVersion: k8s.angie.software/v1alpha1 kind: TransportServer metadata: name: dns-udp spec: listener: name: dns-udp protocol: UDP upstreams: - name: dns-app service: dns-service port: 5353 upstreamParameters: udpRequests: 1 udpResponses: 1 action: pass: dns-app
-
Балансировка нагрузки TLS Passthrough:
apiVersion: k8s.angie.software/v1alpha1 kind: TransportServer metadata: name: secure-app spec: listener: name: tls-passthrough protocol: TLS_PASSTHROUGH host: app.example.com upstreams: - name: secure-app service: secure-app port: 8443 action: pass: secure-app
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Прослушиватель, через который Angie будет принимать входящие соединения и датаграммы. |
Да |
|
|
Хост (доменное имя) сервера. Это должен быть допустимый поддомен, как определено в RFC 1123, например |
|
Нет |
|
Конфигурация завершения TLS. Не поддерживается для балансировки нагрузки TLS Passthrough. |
Нет |
|
|
Список апстримов. |
Да |
|
|
Параметры апстрима. |
Нет |
|
|
Действие, выполняемое для клиентского соединения или датаграммы. |
Да |
|
|
Указывает, какой экземпляр ANIC должен обрабатывать ресурс TransportServer. |
|
Нет |
|
Задает пользовательский фрагмент в контексте |
|
Нет |
|
Задает пользовательский фрагмент в контексте |
|
Нет |
Listener#
Ссылается на прослушиватель, через который Angie будет принимать входящий
трафик к TransportServer. Для TCP и UDP прослушиватель должен быть определен в
ресурсе GlobalConfiguration.
При ссылке на прослушиватель должны совпадать как имя, так и протокол. Для TLS
Passthrough используйте встроенный прослушиватель с именем tls-passthrough
и протоколом TLS_PASSTHROUGH
.
Пример:
listener:
name: dns-udp
protocol: UDP
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Имя прослушивателя. |
|
Да |
|
Протокол прослушивателя. |
|
Да |
TLS#
Поле tls определяет конфигурацию TLS для TransportServer. Обратите внимание, что текущая реализация поддерживает завершение TLS на нескольких портах, где каждому приложению принадлежит выделенный порт. При этом ANIC завершает TLS-соединения на каждом порту, где каждое приложение использует свой собственный сертификат или ключ, и направляет соединения соответствующему приложению (сервису) на основе этого входящего порта (т. е. любое TLS-соединение независимо от настроек SNI на порту будет перенаправлено в приложение, соответствующее этому порту).
Пример конфигурации показан ниже:
secret: cafe-secret
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Имя секрета с сертификатом TLS и ключом. Секрет должен принадлежать тому же
пространству имен, что и транспортный сервер. Секрет должен иметь тип
|
|
Нет |
Upstream#
Определяет конечное место назначения для TransportServer. Например:
name: secure-app
service: secure-app
port: 8443
maxFails: 3
maxConns: 100
failTimeout: 30s
loadBalancingMethod: least_conn
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Имя апстрима. Это должна быть допустимая метка DNS, как определено в RFC
1035. Например, допустимы значения |
|
Да |
|
Название сервиса. Сервис должен принадлежать к тому же пространству имен, что и ресурс. Если сервиса не существует, Angie предположит, что у него нет конечных точек, и будет закрывать клиентские соединения и игнорировать датаграммы. |
|
Да |
|
Порт службы. Если у сервиса этот порт не задан, Angie предположит, что у
него нет конечных точек, и будет закрывать клиентские соединения и
игнорировать датаграммы. Значение должно находиться в диапазоне
|
|
Да |
|
Задает число неудачных попыток установить связь с
сервером, которые должны произойти в течение времени, заданного
параметром |
|
Нет |
|
Задает максимальное число <s_u_server> подключений к проксируемому
серверу. Значение по умолчанию равно нулю, что означает отсутствие
ограничений. Значение по умолчанию равно |
|
Нет |
|
Задает время, в течение которого должно произойти
указанное количество неудачных попыток установить связь с сервером, чтобы
считать сервер недоступным, и период времени, в течение которого сервер
будет считаться недоступным. Значение по умолчанию равно |
|
Нет |
|
Метод балансировки нагрузки между серверами апстрима. По умолчанию соединения распределяются между серверами по методу взвешенной циклической балансировки. Доступные методы и подробности смотрите в разделе Апстрим. |
|
Нет |
UpstreamParameters#
Различные параметры апстрима:
upstreamParameters:
udpRequests: 1
udpResponses: 1
connectTimeout: 60s
nextUpstream: true
nextUpstreamTimeout: 50s
nextUpstreamTries: 1
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Количество датаграмм, после получения которых следующая датаграмма от
того же клиента запускает новый сеанс. См. директиву
proxy_requests. Значение по умолчанию равно |
|
Нет |
|
Количество датаграмм, ожидаемых от проксируемого сервера в ответ на клиентскую датаграмму. См. директиву proxy_responses. По умолчанию количество датаграмм не ограничено. |
|
Нет |
|
Тайм-аут установки соединения с проксируемым сервером. См. директиву
proxy_connect_timeout.
Значение по умолчанию - |
|
Нет |
|
Если соединение с проксируемым сервером установить не удается,
определяет, будет ли клиентское соединение передано на следующий сервер.
См. директиву proxy_next_upstream.
Значение по умолчанию равно |
|
Нет |
|
Количество попыток до передачи соединения к следующему серверу. См.
директиву proxy_next_upstream_tries.
Значение по умолчанию равно |
|
Нет |
|
Время, отведенное для передачи соединения к следующему серверу. См.
директиву proxy_next_upstream_timeout.
Значение по умолчанию - |
|
Нет |
SessionParameters#
Различные параметры для TCP-соединений и UDP-сеансов.
sessionParameters:
timeout: 50s
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Тайм-аут между двумя последовательными операциями чтения или записи в
соединениях с клиентом или проксируемым сервером. См. директиву
proxy_timeout.
Значение по умолчанию равно |
|
Нет |
Action#
Действие, которое необходимо выполнить для клиентского соединения или датаграммы.
В приведенном ниже примере клиентские подключения и датаграммы
передаются на апстрим в dns-app
:
action:
pass: dns-app
Поле |
Описание |
Тип |
Обязательно |
---|---|---|---|
|
Передает соединения и датаграммы апстриму. Апстрим с таким именем должен быть определен в ресурсе. |
|
Да |
Использование TransportServer#
Для работы с ресурсами TransportServer можно использовать обычные
команды kubectl
, аналогично ресурсам Ingress.
Например, следующая команда создает ресурс TransportServer, определенный
в transport-server-passthrough.yaml
, с именем secure-app
:
kubectl apply -f transport-server-passthrough.yaml
transportserver.k8s.angie.software/secure-app created
Вы можете получить ресурс, выполнив:
kubectl get transportserver secure-app
NAME AGE
secure-app 46sm
В kubectl get
и подобных командах также можно использовать короткое имя
ts
вместо transportserver
.
Использование фрагментов#
Фрагменты позволяют вставлять элементы конфигурации Angie в различные контексты конфигурации Angie. В приведенном ниже примере мы используем фрагменты для настройки контроля доступа на TransportServer:
apiVersion: k8s.angie.software/v1alpha1
kind: TransportServer
metadata:
name: cafe
spec:
host: cafe.example.com
serverSnippets: |
deny 192.168.1.1;
allow 192.168.1.0/24;
upstreams:
- name: tea
service: tea-svc
port: 80
Фрагменты также можно указать для потока. В приведенном ниже примере мы используем фрагменты для ограничения количества подключений:
apiVersion: k8s.angie.software/v1alpha1
kind: TransportServer
metadata:
name: cafe
spec:
host: cafe.example.com
streamSnippets: limit_conn_zone $binary_remote_addr zone=addr:10m;
serverSnippets: limit_conn addr 1;
upstreams:
- name: tea
service: tea-svc
port: 80
Фрагменты предназначены для продвинутых пользователей Angie, которым требуется больше контроля над генерируемой конфигурацией Angie.
Однако из-за недостатков, описанных ниже, фрагменты по умолчанию отключены.
Чтобы использовать фрагменты, задайте аргумент командной строки
enable-snippets
.
Недостатки использования фрагментов:
-
Сложность. Чтобы использовать фрагменты, требуется:
Понимать примитивы конфигурации Angie и реализовать правильную конфигурацию Angie.
Понимать, как ANIC генерирует конфигурацию Angie, чтобы фрагмент не мешал другим функциям конфигурации.
Сниженная надежность. Неправильный фрагмент делает конфигурацию Angie недействительной, что приведет к ошибке при перезагрузке. Это помешает применить какие-либо обновления конфигурации, включая обновления для другого ресурса TransportServer, пока фрагмент не будет исправлен.
Последствия для безопасности. Фрагменты предоставляют доступ к примитивам конфигурации Angie, и эти примитивы не проверяются самим ANIC.
Примечание
Пока конфигурация Angie содержит недопустимый фрагмент, Angie будет продолжать работать с последней допустимой конфигурацией.
Примечание
Чтобы настроить фрагменты в контексте stream
,
используйте ключ stream-snippets
ConfigMap.
Валидация#
Для ресурса TransportServer доступны два типа валидации:
Структурная валидация с помощью
kubectl
и сервера Kubernetes API.Всесторонняя валидация с помощью ANIC.
Структурная валидация#
Пользовательское определение ресурса для TransportServer включает структурную схему OpenAPI, которая описывает тип каждого поля ресурса.
Если вы попытаетесь создать (или обновить) ресурс с нарушением
структурной схемы (например, используете строковое значение для поля
порта апстрима), сервер kubectl
и Kubernetes API отклонят такой
ресурс:
-
Пример проверки
kubectl
:kubectl apply -f transport-server-passthrough.yaml error: error validating "transport-server-passthrough.yaml": error validating data: ValidationError(TransportServer.spec.upstreams[0].port): invalid type for software.angie.k8s.v1alpha1.TransportServer.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 transport-server-passthrough.yaml --validate=false The TransportServer "secure-app" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list: spec.upstreams.port in body must be of type integer: "string"
Если ресурс не отклонен (то есть не нарушает структурную схему), ANIC проверит его дополнительно.
Всесторонняя валидация#
ANIC проверяет поля ресурса TransportServer. Если ресурс недействителен, ANIC отклонит его: ресурс продолжит существовать в кластере, но ANIC будет его игнорировать.
Вы можете проверить, успешно ли ANIC применил конфигурацию
TransportServer. Для примера TransportServer secure-app
мы можем запустить:
kubectl describe ts secure-app
. . .
Events:
Type Reason Age From Message
-----
Normal AddedOrUpdated 3s angie-ingress-controller Configuration for default/secure-app was added or updated
Обратите внимание, что раздел Events
(События) включает событие Normal
с
причиной AddedOrUpdated
, которое информирует нас о том, что конфигурация была
успешно применена.
Если вы создадите недопустимый ресурс, ANIC отклонит его и выдаст
событие Rejected
. Например, если вы создадите TransportServer secure-app
с
действием pass
, которое ссылается на несуществующий апстрим, вы получите:
kubectl describe ts secure-app
. . .
Events:
Type Reason Age From Message
-----
Warning Rejected 2s angie-ingress-controller TransportServer default/secure-app is invalid and was rejected: spec.action.pass: Not found: "some-app"
Обратите внимание, что раздел событий включает событие Warning
с причиной
Rejected
.
Примечание
Если вы внесете ошибку в уже существующий ресурс, ANIC отклонит его и удалит соответствующую конфигурацию из Angie.
Настройка с помощью ConfigMap#
Ключи ConfigMap
(за исключением stream-snippets
, stream-log-format
,
resolver-addresses
, resolver-ipv6
, resolver-valid
и
resolver-timeout
) не влияют на ресурсы TransportServer.