Модуль ingress-nginx: Custom Resources

Устаревший ресурс. Поддержка ресурса может быть исключена в следующих версиях.

• spec

  объект

  Обязательный параметр

  • spec.acceptRequestsFrom

    массив строк

    Список адресов в формате CIDR, которым разрешено подключаться к контроллеру.

    Независимо от inlet’а всегда проверяется непосредственный адрес (в логах содержится в поле original_address), с которого производится подключение, а не «адрес клиента», который может передаваться в некоторых inlet’ах через заголовки или с использованием proxy protocol.

    Параметр реализован с помощью map module, и если адрес, с которого непосредственно производится подключение, не разрешен – NGINX закрывает соединение (используя return 444).

    По умолчанию к контроллеру можно подключаться с любых адресов.

    • Элемент массива

      строка

      Шаблон: ^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$

  • spec.additionalHeaders

    объект

    Дополнительные header’ы, которые будут добавлены к каждому запросу. Указываются в формате ключ: значение(строка).

  • spec.additionalLogFields

    объект

    Дополнительные поля, которые будут добавлены в логи nginx. Указываются в формате ключ: значение(строка).

  • spec.annotationValidationEnabled

    булевый

    Включить валидацию аннотаций Ingress-правил.

    Требуется версия контроллера 1.9.

    По умолчанию: false

  • spec.chaosMonkey

    булевый

    Инструмент, позволяющий систематически вызывать случайные прерывания работы подов контроллера.

    Предназначен для проверки Ingress-контроллера на реальную работу отказоустойчивости.

    По умолчанию: false

  • spec.config

    объект

    Секция настроек Ingress-контроллера, в которую в формате ключ: значение(строка) можно записать любые возможные опции.

    Внимание! Ошибка в указании опций может привести к отказу в работе Ingress-контроллера.

    Внимание! Не рекомендуется использовать данную опцию, так как не гарантируется обратная совместимость или работоспособность Ingress-контроллера.

  • spec.controllerVersion

    строка

    Версия NGINX Ingress controller.

    По умолчанию используется версия из настроек модуля.

    Допустимые значения: 1.6, 1.9, 1.10

  • spec.customErrors

    объект

    Секция с настройкой кастомизации HTTP-ошибок.

    Если секция определена, все параметры в ней являются обязательными, изменение любого параметра приводит к перезапуску всех NGINX Ingress controller’ов.

    • spec.customErrors.codes

      массив строк

      Обязательный параметр

      Список кодов ответа (массив), при которых запрос будет перенаправляться на custom default backend.

      • Элемент массива

        строка

        Шаблон: ^[1-5][0-9][0-9]$

    • spec.customErrors.namespace

      строка

      Обязательный параметр

      Имя namespace, в котором будет находиться сервис, используемый как custom default backend.

      Пример:

      namespace: default
      

    • spec.customErrors.serviceName

      строка

      Обязательный параметр

      Имя сервиса, который будет использоваться как custom default backend.

      Пример:

      serviceName: custom-errors-backend-service
      

  • spec.defaultSSLCertificate

    объект

    Сертификат, который используется:

    • при запросах на catch-all-сервер (подразумевается директива server nginx). На catch-all-сервер попадают запросы, для которых нет соответствующего Ingress-ресурса;
    • для Ingress–ресурсов, в которых не задан secretName в секции tls.

    По умолчанию используется самоподписанный сертификат.

    Внимание! Параметр не влияет на сертификаты, используемые в Ingress-ресурсах модулей Deckhouse. Для указания сертификата, который будет использоваться в Ingress-ресурсах модулей Deckhouse, используйте глобальный параметр modules.https.customCertificate.

    • spec.defaultSSLCertificate.secretRef

      объект

      Ссылка на Secret для передачи Ingress-контроллеру.

      • spec.defaultSSLCertificate.secretRef.name

        строка

        Имя Secret’а, содержащего SSL–сертификат.

        Шаблон: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

      • spec.defaultSSLCertificate.secretRef.namespace

        строка

        Имя namespace, в котором находится Secret с SSL—сертификатом.

        По умолчанию: "d8-ingress-nginx"

        Шаблон: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

  • spec.disableHTTP2

    булевый

    Выключить ли HTTP/2.

    По умолчанию: false

  • spec.enableIstioSidecar

    булевый

    Добавить к подам контроллера аннотации для автоматического инжекта сайдкаров Istio. При включении этого параметра к подам Ingress-контроллера добавляются аннотации sidecar.istio.io/inject: "true" и traffic.sidecar.istio.io/includeOutboundIPRanges: "<Service CIDR>". При создании таких подов к ним автоматически будут добавлены сайдкары Istio с помощью mutating webhook. После этого весь трафик в сторону Service CIDR будет перехватываться сайдкаром.

    Чтобы воспользоваться этой функцией, необходимо доработать прикладные Ingress-ресурсы, добавив аннотации:

    • nginx.ingress.kubernetes.io/service-upstream: "true" — с этой аннотацией Ingress-контроллер будет отправлять запросы на ClusterIP сервиса (из диапазона Service CIDR) вместо того, чтобы слать их напрямую в поды приложения. Сайдкар istio-proxy перехватывает трафик только в сторону диапазона Service CIDR, остальные запросы отправляются напрямую;
    • nginx.ingress.kubernetes.io/upstream-vhost: myservice.myns.svc — с данной аннотацией сайдкар сможет идентифицировать прикладной сервис, для которого предназначен запрос.
  • spec.geoIP2

    объект

    Опции для включения GeoIP2.

    • spec.geoIP2.maxmindEditionIDs

      массив строк

      Список ревизий баз данных, которые будут скачаны при старте.

      Подробнее…

      По умолчанию: ["GeoLite2-City","GeoLite2-ASN"]

      • Элемент массива

        строка

        Допустимые значения: GeoIP2-Anonymous-IP, GeoIP2-Country, GeoIP2-City, GeoIP2-Connection-Type, GeoIP2-Domain, GeoIP2-ISP, GeoIP2-ASN, GeoLite2-ASN, GeoLite2-Country, GeoLite2-City

    • spec.geoIP2.maxmindLicenseKey

      строка

      Лицензионный ключ для скачивания базы данных GeoIP2.

      Указание ключа в конфигурации включает скачивание базы GeoIP2 при каждом старте контроллера. Подробнее о получении ключа.

  • spec.hostPort

    объект

    Секция настроек для inlet’а HostPort.

    • spec.hostPort.behindL7Proxy

      булевый

      Включает обработку и передачу заголовков X-Forwarded-*.

      Внимание! При использовании этой опции необходимо быть уверенным, что запросы к Ingress-контроллеру направляются только от доверенных источников. Одним из способов настройки ограничения может служить опция acceptRequestsFrom.

    • spec.hostPort.httpPort

      целочисленный

      Порт для небезопасного подключения по HTTP.

      Если параметр не указан, возможность подключения по HTTP отсутствует.

      Обязательный параметр, если не указан httpsPort.

      Пример:

      httpPort: '80'
      

    • spec.hostPort.httpsPort

      целочисленный

      Порт для безопасного подключения по HTTPS.

      Если параметр не указан, возможность подключения по HTTPS отсутствует.

      Обязательный параметр, если не указан httpPort.

      Пример:

      httpsPort: '443'
      

    • spec.hostPort.realIPHeader

      строка

      Заголовок, из которого будет получен настоящий IP-адрес клиента.

      Работает только при включении behindL7Proxy.

      По умолчанию: "X-Forwarded-For"

      Пример:

      realIPHeader: CF-Connecting-IP
      

  • spec.hostPortWithProxyProtocol

    объект

    Секция настроек для inlet’а HostPortWithProxyProtocol.

    • spec.hostPortWithProxyProtocol.httpPort

      целочисленный

      Порт для небезопасного подключения по HTTP.

      Если параметр не указан, возможность подключения по HTTP отсутствует.

      Обязательный параметр, если не указан httpsPort.

      Пример:

      httpPort: '80'
      

    • spec.hostPortWithProxyProtocol.httpsPort

      целочисленный

      Порт для безопасного подключения по HTTPS.

      Если параметр не указан, возможность подключения по HTTPS отсутствует.

      Обязательный параметр, если не указан httpPort.

      Пример:

      httpsPort: '443'
      

  • spec.hsts

    булевый

    Включен ли HSTS. Подробнее….

    По умолчанию: false

  • spec.hstsOptions

    объект

    Параметры HTTP Strict Transport Security.

    • spec.hstsOptions.includeSubDomains

      булевый

      Применять ли настройки HSTS ко всем поддоменам сайта.

      По умолчанию: false

    • spec.hstsOptions.maxAge

      строка

      Время в секундах, в течение которого браузер должен помнить, что сайт доступен только с помощью HTTPS.

      По умолчанию: "31536000"

      Шаблон: ^[1-9][0-9]*$

      Пример:

      maxAge: '31536000'
      

    • spec.hstsOptions.preload

      булевый

      Добавлять ли сайт в список предзагрузки.

      Эти списки используются современными браузерами и разрешают подключение к сайту только по HTTPS.

      По умолчанию: false

  • spec.ingressClass

    строка

    Имя Ingress-класса для обслуживания NGINX Ingress controller.

    Позволяет создать несколько контроллеров для обслуживания одного Ingress-класса.

    Важно! Если указать значение “nginx”, дополнительно будут обрабатываться Ingress-ресурсы без аннотации kubernetes.io/ingress.class или поля spec.ingressClassName.

    По умолчанию: "nginx"

    Шаблон: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

    Пример:

    ingressClass: nginx
    

  • spec.inlet

    строка

    Обязательный параметр

    Способ приема трафика из внешней сети. Изменение установленного способа невозможно.

    • LoadBalancer — устанавливается Ingress-контроллер и заказывается сервис с типом LoadBalancer;
    • LoadBalancerWithProxyProtocol — устанавливается Ingress-контроллер и заказывается сервис с типом LoadBalancer. Ingress-контроллер использует proxy-protocol для получения настоящего IP-адреса клиента;

    • HostPort — устанавливается Ingress-контроллер, который доступен на портах узлов через hostPort;

      Требуется обязательная установка параметров в секции spec.HostPort.

    • HostPortWithProxyProtocol — устанавливается Ingress-контроллер, который доступен на портах узлов через hostPort и использует proxy-protocol для получения настоящего IP-адреса клиента;

      Требуется обязательная установка параметров в секции spec.HostPortWithProxyProtocol.

      Внимание! При использовании этого инлета, убедитесь, что запросы к Ingress-контроллеру направляются только от доверенных источников. Одним из способов настройки ограничения может служить параметр acceptRequestsFrom.

    • HostWithFailover — устанавливаются два Ingress-контроллера — основной и резервный. Основной контроллер запускается в hostNetwork. Если поды основного контроллера недоступны, трафик уходит в резервный контроллер;

      Внимание! На одном хосте может быть только один контроллер с данным типом inlet’а.

      Внимание! Необходимо, чтобы на узле были свободны следующие порты: 80, 81, 443, 444, 4207, 4208.

      Внимание! Чтобы поменять инлет, удалите правила iptables и перезапустите поды kube-proxy или перезагрузите узлы, на которых размещались Ingress-контроллеры.

    Допустимые значения: LoadBalancer, LoadBalancerWithProxyProtocol, HostPort, HostPortWithProxyProtocol, HostWithFailover

  • spec.legacySSL

    булевый

    Включены ли старые версии TLS. Также опция разрешает legacy cipher suites для поддержки старых библиотек и программ: OWASP Cipher String ‘C’ . Подробнее здесь.

    По умолчанию включены только TLSv1.2 и самые новые cipher suites.

  • spec.loadBalancer

    объект

    Необязательный параметр.

    Секция настроек для inlet’а LoadBalancer.

    • spec.loadBalancer.annotations

      объект

      Аннотации, которые будут проставлены сервису для гибкой настройки балансировщика.

      Внимание! Модуль не учитывает особенности указания аннотаций в различных облаках. Если аннотации для заказа LoadBalancer’а применяются только при создании сервиса, для обновления подобных параметров необходимо будет пересоздать IngressNginxController (или создать новый, затем удалив старый).

    • spec.loadBalancer.behindL7Proxy

      булевый

      Включает обработку и передачу заголовков X-Forwarded-*.

      Внимание! При использовании этой опции вы должны быть уверены, что запросы к Ingress направляются только от доверенных источников.

    • spec.loadBalancer.loadBalancerClass

      строка

      Класс балансировщика входящих сетевых запросов (пробрасывается в параметр spec.loadBalancerClass заказанного сервиса с типом LoadBalancer).

    • spec.loadBalancer.realIPHeader

      строка

      Заголовок, из которого будет получен настоящий IP-адрес клиента.

      Работает только при включении behindL7Proxy.

      По умолчанию: "X-Forwarded-For"

      Пример:

      realIPHeader: CF-Connecting-IP
      

    • spec.loadBalancer.sourceRanges

      массив строк

      Список адресов в формате CIDR, которым разрешен доступ на балансировщик.

      Внимание! Облачный провайдер может не поддерживать данную опцию и игнорировать ее. Провайдеры поддерживающие опцию: AWS, GCP, Azure Провайдеры игнорирующие опцию: YandexCloud Для остальных облачных провайдеров поведение может зависеть от особенностей реализации облака. Перед промышленным использованием опции рекомендуется тестирование.

      • Элемент массива

        строка

        Шаблон: ^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$

  • spec.loadBalancerWithProxyProtocol

    объект

    Необязательный параметр.

    Секция настроек для inlet’а LoadBalancerWithProxyProtocol.

    • spec.loadBalancerWithProxyProtocol.annotations

      объект

      Аннотации, которые будут проставлены сервису для гибкой настройки балансировщика.

      Внимание! Модуль не учитывает особенности указания аннотаций в различных облаках. Если аннотации для заказа LoadBalancer’а применяются только при создании сервиса, для обновления подобных параметров необходимо будет пересоздать IngressNginxController (или создать новый, затем удалив старый).

    • spec.loadBalancerWithProxyProtocol.loadBalancerClass

      строка

      Класс балансировщика входящих сетевых запросов (пробрасывается в параметр spec.loadBalancerClass заказанного сервиса с типом LoadBalancer).

    • spec.loadBalancerWithProxyProtocol.sourceRanges

      массив строк

      Список адресов в формате CIDR, которым разрешен доступ на балансировщик.

      Внимание! Облачный провайдер может не поддерживать данную опцию и игнорировать ее. Провайдеры поддерживающие опцию: AWS, GCP, Azure Провайдеры игнорирующие опцию: YandexCloud Для остальных облачных провайдеров поведение может зависеть от особенностей реализации облака. Перед промышленным использованием опции рекомендуется тестирование.

      • Элемент массива

        строка

        Шаблон: ^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$

  • spec.maxReplicas

    целочисленный

    Максимально количество реплик LoadBalancer и LoadBalancerWithProxyProtocol для HPA.

    По умолчанию: 1

    Допустимые значения: 1 <= X

  • spec.minReplicas

    целочисленный

    Минимальное количество реплик LoadBalancer и LoadBalancerWithProxyProtocol для HPA.

    По умолчанию: 1

    Допустимые значения: 1 <= X

  • spec.nodeSelector

    объект

    Как в spec.nodeSelector у подов.

    Если ничего не указано или указано false, будет использоваться автоматика.

    Формат: стандартный список nodeSelector. Поды инстанса унаследуют это поле как есть.

  • spec.resourcesRequests

    объект

    Настройки максимальных значений CPU и memory, которые может запросить под при выборе узла (если VPA выключен, максимальные значения становятся значениями по умолчанию).

    • spec.resourcesRequests.mode

      строка

      Обязательный параметр

      Режим управления реквестами ресурсов.

      По умолчанию: "VPA"

      Допустимые значения: VPA, Static

    • spec.resourcesRequests.static

      объект

      Настройки статического режима управления.

      • spec.resourcesRequests.static.cpu

        строка

        Значение для реквеста к CPU.

        По умолчанию: "350m"

      • spec.resourcesRequests.static.memory

        строка

        Значение для реквеста к memory.

        По умолчанию: "500Mi"

    • spec.resourcesRequests.vpa

      объект

      Настройки VPA режима управления.

      • spec.resourcesRequests.vpa.cpu

        объект

        Настройки для CPU.

        • spec.resourcesRequests.vpa.cpu.max

          строка

          Максимальное значение, которое может выставить VPA для реквеста к CPU.

          По умолчанию: "50m"

        • spec.resourcesRequests.vpa.cpu.min

          строка

          Минимальное значение, которое может выставить VPA для реквеста к CPU.

          По умолчанию: "10m"

      • spec.resourcesRequests.vpa.memory

        объект

        Значение для запроса memory.

        • spec.resourcesRequests.vpa.memory.max

          строка

          Максимальное значение, которое может выставить VPA для реквеста к memory.

          По умолчанию: "200Mi"

        • spec.resourcesRequests.vpa.memory.min

          строка

          Минимальное значение, которое может выставить VPA для реквеста к memory.

          По умолчанию: "50Mi"

      • spec.resourcesRequests.vpa.mode

        строка

        Режим работы VPA.

        По умолчанию: "Initial"

        Допустимые значения: Initial, Auto

  • spec.tolerations

    массив объектов

    Как в spec.tolerations у подов.

    Если ничего не указано или указано false, будет использоваться автоматика.

    Формат: стандартный список toleration. Поды инстанса унаследуют это поле как есть.

    • spec.tolerations.effect

      строка

      Допустимые значения: NoSchedule, PreferNoSchedule, NoExecute

    • spec.tolerations.key

      строка
    • spec.tolerations.operator

      строка

      По умолчанию: "Equal"

      Допустимые значения: Exists, Equal

    • spec.tolerations.tolerationSeconds

      целочисленный
    • spec.tolerations.value

      строка
  • spec.underscoresInHeaders

    булевый

    Разрешены ли нижние подчеркивания в заголовках.

    Подробнее….

    Почему не стоит бездумно это включать.

    По умолчанию: false

  • spec.validationEnabled

    булевый

    Включить валидацию Ingress-правил.

    По умолчанию: true

  • spec.waitLoadBalancerOnTerminating

    целочисленный

    Количество секунд до того, как /healthz начнет возвращать код 500, когда под перейдет в статус Terminating.