Расширенная конфигурация с помощью аннотаций

Здесь объясняется, как включить расширенную функциональность ANIC с помощью аннотаций.

Ресурс Ingress может использовать базовые функции Angie, такие как маршрутизация на основе хоста или пути и TLS-терминация. Расширенные функции, такие как переписывание URI запроса или вставка дополнительных заголовков ответа, могут быть включены с помощью аннотаций. Аннотации позволяют настраивать поведение Angie для каждого Ingress-ресурса.

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

Настройка также доступна через ресурсы ConfigMap: аннотации имеют приоритет.

Использование аннотаций

Этот пример использует аннотации для настройки конфигурации ресурса Ingress:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress-with-annotations
  annotations:
    ``angie.software/proxy-connect-timeout: "30s"
    ``angie.software/proxy-read-timeout: "20s"
    ``angie.software/client-max-body-size: "4m"
    ``angie.software/server-snippets: |
      location / {
        return 302 /coffee;
      }
spec:
  rules:
  - host: cafe.example.com
    http:
      paths:
      - path: /tea
        pathType: Prefix
        backend:
          service:
            name: tea-svc
            port:
              number: 80
      - path: /coffee
        pathType: Prefix
        backend:
          service:
            name: coffee-svc
            port:
              number: 80

Валидация

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

Вы можете проверить, успешно ли ANIC применил конфигурацию для ресурса Ingress. Для примера Ingress cafe-ingress-with-annotations вы можете выполнить следующую команду:

$ kubectl describe ing cafe-ingress-with-annotations

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

Раздел событий включает событие Normal с причиной AddedOrUpdated, которое сообщает нам, что конфигурация была успешно применена.

Если вы создадите некорректный Ingress, ANIC отклонит его и сгенерирует событие Rejected. Например, если вы создадите Ingress cafe-ingress-with-annotations с аннотацией angie.software/redirect-to-https, установленной на yes please вместо true, вы получите:

$ kubectl describe ing cafe-ingress-with-annotations

Events:
  Type     Reason    Age   From                      Message
  ----     ------    ----  ----                      -------
  Warning  Rejected  13s   angie-ingress-controller  annotations.``angie.software/redirect-to-https: Invalid value: "yes please": must be a boolean

Обратите внимание, что раздел событий включает событие Warning с причиной Rejected.

Примечание

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

Сводка аннотаций

В таблице ниже приведены доступные аннотации.

Общая настройка

Аннотация	Ключ ConfigMap	Описание	Значение по умолчанию	Пример
angie.software/proxy-connect-timeout	proxy-connect-timeout	Устанавливает значение для директив proxy_connect_timeout и grpc_connect_timeout.	60s
angie.software/proxy-read-timeout	proxy-read-timeout	Устанавливает значение для директив proxy_read_timeout и grpc_read_timeout.	60s
angie.software/proxy-send-timeout	proxy-send-timeout	Устанавливает значение для директив proxy_send_timeout и grpc_send_timeout.	60s
angie.software/client-max-body-size	client-max-body-size	Устанавливает значение для директивы client_max_body_size (ограничивает размер тела запроса клиента). Alias для nginx.ingress.kubernetes.io/proxy-body-size.	1m
angie.software/proxy-body-size	proxy-body-size	Устанавливает максимально допустимый размер тела запроса клиента, передаваемого прокси-сервером дальше. См. также client_max_body_size.	1m
angie.software/proxy-buffering	proxy-buffering	Включает или отключает буферизацию ответов от проксируемого сервера. Alias для nginx.ingress.kubernetes.io/proxy-buffering.	True
angie.software/proxy-buffers	proxy-buffers	Устанавливает значение для директивы proxy_buffers. Alias для nginx.ingress.kubernetes.io/proxy-buffers-number.	Зависит от платформы.
angie.software/proxy-buffer-size	proxy-buffer-size	Устанавливает значение для директив proxy_buffer_size. Alias для nginx.ingress.kubernetes.io/proxy-buffer-size. и grpc_buffer_size.	Зависит от платформы.
angie.software/proxy-max-temp-file-size	proxy-max-temp-file-size	Устанавливает значение для директивы proxy_max_temp_file_size. Alias для nginx.ingress.kubernetes.io/proxy-max-temp-file-size.	1024m
angie.software/server-tokens	server-tokens	Включает или отключает директиву server_tokens. Кроме того, с Angie можно указать строковое значение, включая пустую строку, что отключает вывод поля "Server".	True
angie.software/path-regex	Нет	Включает модификаторы регулярных выражений для параметра пути Ingress. Это соответствует директиве Angie location. Можно указать одно из значений: "case_sensitive", "case_insensitive" или "exact". Аннотация применяется к ресурсу Ingress и его путям. При использовании Master и Minion Ingresses (т.е. Mergeable Ingresses) эту аннотацию можно указывать для Minion-типов. Аннотация path-regex, указанная для Master, игнорируется и не влияет на пути, определенные в Minions. Подробнее см. также статью о сопоставлении путей Ingress-ресурсов с помощью регулярных выражений.	Нет
angie.software/configmap	Нет	Позволяет задать конкретный ConfigMap для настройки ресурса Ingress. Заданный ConfigMap будет иметь приоритет над глобальным. В случае, если глобальный и заданный ConfigMap совпадают, применится заданный. Пример: angie.software/configmap: "namespace/configmap"	False	См. переопределение ConfigMap для ресурса Ingress.

Манипуляция URI и заголовками запросов

Аннотация	Ключ ConfigMap	Описание	Значение по умолчанию	Пример
angie.software/proxy-hide-headers	proxy-hide-headers	Устанавливает значение одной или нескольких директив proxy_hide_header. Пример: "`angie.software/proxy-hide-headers": "header-a,header-b"`	Нет
angie.software/proxy-pass-headers	proxy-pass-headers	Устанавливает значение одной или нескольких директив proxy_pass_header. Пример: "`angie.software/proxy-pass-headers": "header-a,header-b"`	Нет
angie.software/rewrites	Нет	Конфигурирует перезапись URI с использованием директивы proxy_pass.	Нет

Аутентификация и SSL/TLS

Аннотация	Ключ ConfigMap	Описание	Значение по умолчанию	Пример
angie.software/redirect-to-https	redirect-to-https	Устанавливает правило перенаправления 301 на основе значения заголовка http_x_forwarded_proto в серверном блоке, чтобы заставить входящий трафик проходить через HTTPS. Полезно при SSL-терминации в балансировщике нагрузки перед ANIC.	False
angie.software/ssl-redirect	ssl-redirect	Устанавливает некондиционное правило перенаправления 301 для всего входящего HTTP трафика, чтобы заставить входящий трафик проходить через HTTPS.	True
angie.software/hsts	hsts	Включает HTTP Strict Transport Security (HSTS): заголовок HSTS добавляется к ответам от проксируемых серверов. В заголовок включается директива preload.	False
angie.software/hsts-max-age	hsts-max-age	Устанавливает значение директивы max-age заголовка HSTS.	2592000 (1 месяц)
angie.software/hsts-include-subdomains	hsts-include-subdomains	Добавляет директиву includeSubDomains в заголовок HSTS.	False
angie.software/hsts-behind-proxy	hsts-behind-proxy	Включает HSTS на основе значения заголовка запроса http_x_forwarded_proto. Следует использовать, только когда в балансировщике нагрузки (прокси) перед ANIC настроена TLS-терминация. Примечание Для управления перенаправлением с HTTP на HTTPS настройте аннотацию angie.software/redirect-to-https.	False
angie.software/basic-auth-secret	Нет	Указывает ресурс Secret с списком пользователей для HTTP Basic аутентификации.	Нет
angie.software/basic-auth-realm	Нет	Указывает область.	Нет

Прослушиватели

Аннотация	Ключ ConfigMap	Описание	Значение по умолчанию	Пример
angie.software/listen-ports	Нет	Конфигурирует HTTP порты, на которых Angie будет слушать.	[80]
angie.software/listen-ports-ssl	Нет	Конфигурирует HTTPS порты, на которых Angie будет слушать.	[443]

Бэкенд-сервисы (апстримы)

Аннотация	Ключ ConfigMap	Описание	Значение по умолчанию	Пример
nginx.ingress.kubernetes.io/backend-protocol	Нет	Устанавливает протокол для взаимодействия с backend-подами (службами) в Kubernetes.	Нет
angie.software/lb-method	lb-method	Устанавливает метод балансировки нагрузки. Для использования метода round-robin укажите "round_robin".	"random two least_conn"
angie.software/ssl-services	Нет	Включает HTTPS или gRPC через SSL при подключении к конечным точкам сервисов.	Нет
angie.software/grpc-services	Нет	Включает gRPC для сервисов. Примечание Требует HTTP/2 (см. ключ http2 в ConfigMap); работает только для Ingress с включенной TLS-терминацией.	Нет
angie.software/websocket-services	Нет	Включает WebSocket для сервисов.	Нет
angie.software/max-fails	max-fails	Устанавливает значение параметра max_fails директивы server.	1
angie.software/max-conns	Нет	Устанавливает значение параметра max_conns директивы server.	0
angie.software/upstream-zone-size	upstream-zone-size	Устанавливает размер зоны разделяемой памяти для апстрима. Для Angie специальное значение 0 отключает зоны общей памяти. Для Angie зоны общей памяти требуются и не могут быть отключены. Специальное значение 0 будет проигнорировано.	256K
angie.software/fail-timeout	fail-timeout	Устанавливает значение параметра fail_timeout директивы u_server.	10s
angie.software/sticky-cookie-services	Нет	Конфигурирует сохранение сеансов.	Нет
angie.software/keepalive	keepalive	Устанавливает значение директивы keepalive. Обратите внимание, что proxy_set_header Connection ""; добавляется в сгенерированную конфигурацию, когда значение > 0.	0
angie.software/health-checks	Нет	Включает активные проверки состояния.	False
angie.software/health-checks-mandatory	Нет	Конфигурирует активные проверки состояния как обязательные.	False
angie.software/health-checks-mandatory-queue	Нет	Когда активные проверки состояния обязательны, создает очередь, в которой входящие запросы временно хранятся, пока Angie проверяет состояние конечных точек после перезагрузки конфигурации.	0
angie.software/slow-start	Нет	Устанавливает период медленного запуска сервера для апстрима. По умолчанию медленный запуск активируется после того, как сервер становится доступным или здоровым. Для включения медленного запуска для новоназначенных серверов настройте обязательные активные проверки состояния.	"0s"
angie.software/use-cluster-ip	Нет	Включает использование IP-адреса и порта кластера сервиса вместо поведения по умолчанию, когда используются IP и порт подов. Когда это поле включено, поля, которые настраивают поведение Angie, связанное с несколькими апстримами (такими как lb-method и next-upstream), не будут иметь эффекта, так как ANIC настроит Angie только с одним апстримом, который будет соответствовать IP кластера сервиса.	False

Ограничение скорости

Аннотация	Ключ ConfigMap	Описание	Значение по умолчанию	Пример
angie.software/limit-req-rate	Нет	Включает ограничение скорости запросов для этого Ingress, создавая limit_req_zone и применяя limit_req для каждого location. Все серверы/location одного Ingress используют одну зону. Должен иметь единицу r/s или r/m.	Нет	200r/s
angie.software/limit-req-key	Нет	Ключ, к которому применяется ограничение скорости. Может содержать текст, переменные или их комбинацию. Переменные должны быть окружены ${}.	${binary_remote_addr}	${binary_remote_addr}
angie.software/limit-req-zone-size	Нет	Конфигурирует размер созданной limit_req_zone.	10m	20m
angie.software/limit-req-delay	Нет	Конфигурирует параметр delay директивы limit_req.	0	100
angie.software/limit-req-no-delay	Нет	Конфигурирует параметр nodelay директивы limit_req.	false	true
angie.software/limit-req-burst	Нет	Конфигурирует параметр burst директивы limit_req.	Нет	100
angie.software/limit-req-dry-run	Нет	Включает режим проверки. В этом режиме ограничение скорости не применяется, но количество избыточных запросов учитывается, как обычно, в зоне общей памяти.	false	true
angie.software/limit-req-log-level	Нет	Устанавливает желаемый уровень логирования для случаев, когда сервер отказывается обрабатывать запросы из-за превышения скорости или задержек в обработке запросов. Разрешенные значения: info, notice, warn или error.	error	info
angie.software/limit-req-reject-code	Нет	Устанавливает код состояния, который возвращается в ответ на отклоненные запросы. Должен находиться в диапазоне 400..599.	429	503
angie.software/limit-req-scale	Нет	Включает постоянное ограничение скорости, деля настроенное значение скорости на количество подов Ingress, в настоящее время обслуживающих трафик. Эта корректировка обеспечивает постоянство ограничения скорости, даже если количество подов изменяется из-за автоскейлинга. Примечание Это не будет работать правильно, если запросы от клиента не распределяются равномерно между всеми подами Ingress (привязка сеансов, длительные TCP-соединения с множеством запросов и т.д.). В таких случаях лучшие результаты даст использование функции синхронизации зон Angie.	false	true

Фрагменты и пользовательские шаблоны

Аннотация	Ключ ConfigMap	Описание	Значение по умолчанию	Пример
angie.software/location-snippets	location-snippets	Устанавливает пользовательский фрагмент в контексте location.	Нет
angie.software/server-snippets	server-snippets	Устанавливает пользовательский фрагмент в контексте server.	Нет