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

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

• 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.chaosMonkeyбулевый

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

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

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

• spec.configобъект

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

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

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

• spec.controllerVersionстрока

  Версия Ingress NGINX-контроллера.

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

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

• spec.customErrorsобъект

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

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

  • 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 Controller.

    • spec.defaultSSLCertificate.secretRef.nameстрока

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

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

    • spec.defaultSSLCertificate.secretRef.namespaceстрока

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

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

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

• spec.disableHTTP2булевый

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

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

• spec.enableIstioSidecarбулевый

  Добавить к Pod’ам контроллера аннотации для автоматического инжекта istio-сайдкаров. При включении этого параметра, к Pod’ам 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 перехватывает трафик только в сторону диапазона ServiceCIDR, остальные запросы отправляются напрямую.
  • 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-класса для обслуживания Ingress NGINX 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 controller и заказывается сервис с типом LoadBalancer.
  • LoadBalancerWithProxyProtocol — устанавливается Ingress controller и заказывается сервис с типом LoadBalancer. Ingress controller использует proxy-protocol для получения настоящего IP-адреса клиента.
  • HostPort — устанавливается Ingress controller, который доступен на портах узлов через hostPort.

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

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

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

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

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

  Допустимые значения: 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объект

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

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

  • spec.loadBalancer.behindL7Proxyбулевый

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

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

  • spec.loadBalancer.realIPHeaderстрока

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

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

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

    Пример:

    realIPHeader: CF-Connecting-IP
    

  • spec.loadBalancer.sourceRangesмассив строк

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

    Облачный провайдер может не поддерживать данную опцию и игнорировать её.

    • Элемент массивастрока

      Шаблон: ^(([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объект

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

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

  • spec.loadBalancerWithProxyProtocol.sourceRangesмассив строк

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

    Облачный провайдер может не поддерживать данную опцию и игнорировать её.

    • Элемент массивастрока

      Шаблон: ^(([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 у Pod’ов.

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

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

• spec.resourcesRequestsобъект

  Настройки максимальных значений CPU и memory, которые может запросить Pod при выборе узла (если 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 у Pod’ов.

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

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

  • 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, когда Pod перейдет в статус Terminating.