The ingress-nginx module: Custom Resources

Deprecated resource. Support for the resource might be removed in a later release.

• spec

  object

  Required value

  • spec.acceptRequestsFrom

    array of strings

    IP or CIDR that is allowed to access the Ingress controller.

    Regardless of the inlet type, the source IP address gets always verified (the original_address field in logs) (the address that the connection was established from) and not the “address of the client” that can be passed in some inlets via headers or using the proxy protocol.

    This parameter is implemented using the map module. If the source address is not in the list of allowed addresses, nginx closes the connection immediately using HTTP code 444.

    By default, the connection to the controller can be made from any address.

    • Element of the array

      string

      Pattern: ^(([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

    object

    Additional headers to add to all request. (map: key (string)).

  • spec.additionalLogFields

    object

    Additional fields to add to nginx logs. (map: key (string)).

  • spec.annotationValidationEnabled

    boolean

    Enables the annotation validation feature.

    Requires a controller of 1.9 version.

    Default: false

  • spec.chaosMonkey

    boolean

    The instrument for unexpected and random termination of ingress controller Pods in a systemic manner. Chaos Monkey tests the resilience of ingress controller.

    Default: false

  • spec.config

    object

    The section with the Ingress controller parameters.

    You can specify any supported parameter in it in the key: value (string) format.

    Caution. An erroneous option may lead to the failure of the ingress controller;

    Caution. The usage of this parameter is not recommended; the backward compatibility or operability of the ingress controller that uses this option is not guaranteed

  • spec.controllerVersion

    string

    One of the supported NGINX Ingress controller versions.

    By default: the version in the module settings is used.

    Allowed values: 1.6, 1.9, 1.10

  • spec.customErrors

    object

    The section with parameters of custom HTTP errors.

    All parameters in this section are mandatory if it is defined. Changing any parameter leads to the restart of all NGINX Ingress controllers.

    • spec.customErrors.codes

      array of strings

      Required value

      Error codes which should be redirected to custom errors backend.

      • Element of the array

        string

        Pattern: ^[1-5][0-9][0-9]$

    • spec.customErrors.namespace

      string

      Required value

      Namespace of custom errors backend.

      Example:

      namespace: default
      

    • spec.customErrors.serviceName

      string

      Required value

      Name of kubernetes service that leads to custom errors backend.

      Example:

      serviceName: custom-errors-backend-service
      

  • spec.defaultSSLCertificate

    object

    This certificate is used:

    • for catch-all server requests (here, “catch-all server” refers to the nginx server directive. Requests for which there is no corresponding Ingress resource end up on the catch-all server.
    • for Ingress resources that do not have a secretName specified in the tls section.

    By default, a self-signed certificate is used.

    Caution. This parameter does not affect certificates used in the Ingress resources of the Deckhouse modules. You can specify the certificate to be used in the Ingress resources of the Deckhouse modules with the modules.https.customCertificate global parameter.

    • spec.defaultSSLCertificate.secretRef

      object

      The Secret reference to pass to the Ingress Controller.

      • spec.defaultSSLCertificate.secretRef.name

        string

        Name of Secret containing SSL—certificate.

        Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

      • spec.defaultSSLCertificate.secretRef.namespace

        string

        Namespace, where the Secret is located.

        Default: "d8-ingress-nginx"

        Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

  • spec.disableHTTP2

    boolean

    Switch off HTTP2 support.

    Default: false

  • spec.enableIstioSidecar

    boolean

    Attach annotations to the controller pods to automatically inject Istio sidecar containers.

    After setting this parameter, the sidecar.istio.io/inject: "true" and traffic.sidecar.istio.io/includeOutboundIPRanges: "<Service CIDR>" annotations will be attached to the ingress-controller pods. During pod creation, the Istio’s mutating webhook will add the sidecar to it. After that, the sidecar will catch the network traffic to Service CIDR.

    To use this feature in your application, you must add these annotations to your Ingress resources:

    • nginx.ingress.kubernetes.io/service-upstream: "true" — using this annotation, the ingress-controller sends requests to a single ClusterIP (from Service CIDR) while envoy load balances them. Istio sidecar containers only catching traffic directed to Service CIDR.
    • nginx.ingress.kubernetes.io/upstream-vhost: myservice.myns.svc — using this annotation, the sidecar can identify the application service that serves requests.
  • spec.geoIP2

    object

    Enable GeoIP2 databases.

    • spec.geoIP2.maxmindEditionIDs

      array of strings

      A list of database editions to download at startup.

      More info…

      Default: ["GeoLite2-City","GeoLite2-ASN"]

      • Element of the array

        string

        Allowed values: 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

      string

      A license key to download the GeoIP2 database.

      If the key is set, the module downloads the GeoIP2 database every time the controller is started. Click here to learn more about obtaining a license key.

  • spec.hostPort

    object

    HostPort inlet settings.

    • spec.hostPort.behindL7Proxy

      boolean

      Accepts all the incoming X-Forwarded-* headers and passes them to upstreams.

      Caution. Make sure that requests to the ingress are sent from trusted sources when using this option. The acceptRequestsFrom parameter can help you with defining trusted sources.

    • spec.hostPort.httpPort

      integer

      Port for insecure HTTP connections.

      If the parameter is not set, the connection over HTTP cannot be established.

      This parameter is mandatory if httpsPort is not set.

      Example:

      httpPort: 80
      

    • spec.hostPort.httpsPort

      integer

      Port for secure HTTPS connections.

      If the parameter is not set, the connection over HTTPS cannot be established.

      This parameter is mandatory if httpPort is not set.

      Example:

      httpsPort: 443
      

    • spec.hostPort.realIPHeader

      string

      Sets the header field for identifying the originating IP address of a client.

      This option works only if behindL7Proxy is enabled.

      Default: "X-Forwarded-For"

      Example:

      realIPHeader: CF-Connecting-IP
      

  • spec.hostPortWithProxyProtocol

    object

    A section of parameters of the HostPortWithProxyProtocol inlet.

    • spec.hostPortWithProxyProtocol.httpPort

      integer

      Port for insecure HTTP connections.

      If the parameter is not set, the connection over HTTP cannot be established.

      This parameter is mandatory if httpsPort is not set.

      Example:

      httpPort: 80
      

    • spec.hostPortWithProxyProtocol.httpsPort

      integer

      Port for secure HTTPS connections.

      If the parameter is not set, the connection over HTTPS cannot be established.

      This parameter is mandatory if httpPort is not set.

      Example:

      httpsPort: 443
      

  • spec.hsts

    boolean

    Determines whether hsts is enabled. Read more…).

    Default: false

  • spec.hstsOptions

    object

    Options for HTTP Strict Transport Security.

    • spec.hstsOptions.includeSubDomains

      boolean

      If this optional parameter is specified, this rule applies to all of subdomains as well.

      Default: false

    • spec.hstsOptions.maxAge

      string

      The time, in seconds, that the browser should remember that a site is only to be accessed using HTTPS.

      Default: "31536000"

      Pattern: ^[1-9][0-9]*$

      Example:

      maxAge: '31536000'
      

    • spec.hstsOptions.preload

      boolean

      Add your site to preload list to enforce to use SSL/TLS connections on your site.

      Default: false

  • spec.ingressClass

    string

    The name of the Ingress class to use with the NGINX Ingress controller.

    Using this option, you can create several controllers to use with a single ingress

    Caution. If you set it to “nginx”, then Ingress resources lacking the kubernetes.io/ingress.class annotation or spec.ingressClassName field will also be handled.

    Default: "nginx"

    Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

    Example:

    ingressClass: nginx
    

  • spec.inlet

    string

    Required value

    The way traffic from the external network is routed to the cluster. Once you have set the method, you cannot change it later.

    • LoadBalancer — Ingress controller is deployed and the service of LoadBalancer type is provisioned.
    • LoadBalancerWithProxyProtocol — Ingress controller is deployed and the service of LoadBalancer type is provisioned. Ingress controller uses proxy-protocol to get a real IP of the client.

    • HostPort — Ingress controller is deployed and available through nodes’ ports via hostPort;

      Settings are required in spec.HostPort.

    • HostPortWithProxyProtocol — Ingress controller is deployed and available through nodes’ ports via `hostPort, it uses proxy-protocol to get a real IP of the client;

      Settings are required in spec.HostPortWithProxyProtocol.

      Caution. Make sure that requests to the Ingress are sent from trusted sources when using this inlet. The acceptRequestsFrom parameter can help you with defining trusted sources.

    • HostWithFailover — installs two ingress controllers, the primary and the backup one. The primary controller runs in a hostNetwork. If the pods of the primary controller are not available, the traffic is routed to the backup one;

      Caution. There can be only one controller with this inlet type on a host.

      Caution. The following ports must be available on the node: 80, 81, 443, 444, 4207, 4208.

      Caution. To change inlet, remove the iptables rules and restart the kube-proxy pods or reboot the nodes hosting Ingress controllers.

    Allowed values: LoadBalancer, LoadBalancerWithProxyProtocol, HostPort, HostPortWithProxyProtocol, HostWithFailover

  • spec.legacySSL

    boolean

    Enable outdated versions of the TLS protocol and cipher suites.

    Enables the following TLS protocol versions: TLSv1, TLSv1.1, TLSv1.2, TLSv1.3.

    Enables the following combinations of cipher suites in order from the strongest to the weakest: ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-ECDSA-CHACHA20-POLY1305, ECDHE-RSA-CHACHA20-POLY1305, ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES256-SHA384, ECDHE-RSA-AES256-SHA384, ECDHE-ECDSA-AES128-SHA256, ECDHE-RSA-AES128-SHA256, ECDHE-ECDSA-AES256-SHA, ECDHE-RSA-AES256-SHA, ECDHE-ECDSA-AES128-SHA, ECDHE-RSA-AES128-SHA, AES256-GCM-SHA384, AES128-GCM-SHA256, AES256-SHA256, AES128-SHA256, AES256-SHA, AES128-SHA.

    By default, only TLSv1.2 and TLSv1.3 with the newest cipher suites are enabled.

  • spec.loadBalancer

    object

    Not required value.

    A section of parameters of the LoadBalancer inlet.

    • spec.loadBalancer.annotations

      object

      Annotations to assign to the service for flexible configuration of the load balancer.

      Caution. The module does not take into account the specifics of setting annotations in different clouds. Note that you will need to recreate IngressNginxController (or create a new controller and then delete the old one) if annotations to provision a load balancer are only used when creating the service.

    • spec.loadBalancer.behindL7Proxy

      boolean

      Accepts all the incoming X-Forwarded-* headers and passes them to upstreams.

      Caution. Make sure that requests to the Ingress controller are sent from trusted sources when using this option.

    • spec.loadBalancer.loadBalancerClass

      string

      The LoadBalancer class (it is passed to the spec.loadBalancerClass parameter of the provisioned service of the LoadBalancer type).

    • spec.loadBalancer.realIPHeader

      string

      Sets the header field for identifying the originating IP address of a client.

      This option works only if behindL7Proxy is enabled.

      Default: "X-Forwarded-For"

      Example:

      realIPHeader: CF-Connecting-IP
      

    • spec.loadBalancer.sourceRanges

      array of strings

      IP ranges (CIDR) that are allowed to access the load balancer.

      Caution. The cloud provider may not support this option or ignore it. Providers supporting the option: AWS, GCP, Azure. Providers ignoring the option: YandexCloud. For other cloud providers, the behavior may depend on the specifics of the cloud implementation. Testing is recommended before use of the option in production.

      • Element of the array

        string

        Pattern: ^(([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

    object

    Not required value.

    A section of parameters of the LoadBalancerWithProxyProtocol inlet.

    • spec.loadBalancerWithProxyProtocol.annotations

      object

      Annotations that will be passed to service with type load balancer to configure it.

      Caution. The module does not take into account the specifics of setting annotations in different clouds. Note that you will need to recreate IngressNginxController (or create a new controller and then delete the old one) if annotations to provision a load balancer are only used when creating the service.

    • spec.loadBalancerWithProxyProtocol.loadBalancerClass

      string

      The LoadBalancer class (it is passed to the spec.loadBalancerClass parameter of the provisioned service of the LoadBalancer type).

    • spec.loadBalancerWithProxyProtocol.sourceRanges

      array of strings

      IP ranges (CIDR) that are allowed to access the load balancer.

      Caution. The cloud provider may not support this option or ignore it. Providers supporting the option: AWS, GCP, Azure. Providers ignoring the option: YandexCloud. For other cloud providers, the behavior may depend on the specifics of the cloud implementation. Testing is recommended before use of the option in production.

      • Element of the array

        string

        Pattern: ^(([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

    integer

    LoadBalancer and LoadBalancerWithProxyProtocol controller’s Horizontal Pod Autoscaler maximum replicas count.

    Default: 1

    Allowed values: 1 <= X

  • spec.minReplicas

    integer

    LoadBalancer and LoadBalancerWithProxyProtocol controller’s Horizontal Pod Autoscaler minimum replicas count.

    Default: 1

    Allowed values: 1 <= X

  • spec.nodeSelector

    object

    The same as in the pods’ spec.nodeSelector parameter in Kubernetes.

    If the parameter is omitted or false, it will be determined automatically.

    Format: the standard nodeSelector list. Instance pods inherit this field as is.

  • spec.resourcesRequests

    object

    Max amounts of CPU and memory resources that the pod can request when selecting a node (if the VPA is disabled, then these values become the default ones).

    • spec.resourcesRequests.mode

      string

      Required value

      The mode for managing resource requests.

      Default: "VPA"

      Allowed values: VPA, Static

    • spec.resourcesRequests.static

      object

      Static mode settings.

      • spec.resourcesRequests.static.cpu

        string

        CPU requests.

        Default: "350m"

      • spec.resourcesRequests.static.memory

        string

        Memory requests.

        Default: "500Mi"

    • spec.resourcesRequests.vpa

      object

      Parameters of the vpa mode.

      • spec.resourcesRequests.vpa.cpu

        object

        CPU-related parameters.

        • spec.resourcesRequests.vpa.cpu.max

          string

          Maximum allowed CPU requests.

          Default: "50m"

        • spec.resourcesRequests.vpa.cpu.min

          string

          Minimum allowed CPU requests.

          Default: "10m"

      • spec.resourcesRequests.vpa.memory

        object

        The amount of memory requested.

        • spec.resourcesRequests.vpa.memory.max

          string

          Maximum allowed memory requests.

          Default: "200Mi"

        • spec.resourcesRequests.vpa.memory.min

          string

          Minimum allowed memory requests.

          Default: "50Mi"

      • spec.resourcesRequests.vpa.mode

        string

        The VPA usage mode.

        Default: "Initial"

        Allowed values: Initial, Auto

  • spec.tolerations

    array of objects

    The same as in the pods’ spec.tolerations parameter in Kubernetes;

    If the parameter is omitted or false, it will be determined automatically.

    Format: the standard toleration list. Instance pods inherit this field as is.

    • spec.tolerations.effect

      string

      Allowed values: NoSchedule, PreferNoSchedule, NoExecute

    • spec.tolerations.key

      string
    • spec.tolerations.operator

      string

      Default: "Equal"

      Allowed values: Exists, Equal

    • spec.tolerations.tolerationSeconds

      integer
    • spec.tolerations.value

      string
  • spec.underscoresInHeaders

    boolean

    Determines whether underscores are allowed in headers. Learn more….

    This tutorial sheds light on why you should not enable it without careful consideration.

    Default: false

  • spec.validationEnabled

    boolean

    Enable ingress validation admission.

    Default: true

  • spec.waitLoadBalancerOnTerminating

    integer

    The number of seconds before the /healthz location will start to return a 500 code when the pod enters the Terminating state. This parameter has default values:

    • 0s - for HostWithFailover
    • 60s - for HostPort and HostPortWithProxyProtocol
    • 120s - for LoadBalancer and LoadBalancerWithProxyProtocol