IngressNginxController

Scope: Cluster

  • spec (object)

    Required value.

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

      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]))$

    • additionalHeaders (object)

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

    • 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

    • 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

    • controllerVersion (string)

      One of the supported NGINX Ingress Controller versions.

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

      Allowed values: 0.25, 0.26, 0.33, 0.46, 0.48

    • 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 Ingress nginx controllers.

      • serviceName — the name of the service to use as the custom default backend.
      • namespace — the name of the namespace where the custom default backend service is running.
      • codes — a list of response codes (an array) for which the request will be redirected to the custom default backend.
      • codes (array of strings)

        Error codes which should be redirected to custom errors backend.

        Required value.

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

      • namespace (string)

        Namespace of custom errors backend.

        Example: "default"

        Required value.

      • serviceName (string)

        Name of kubernetes service that leads to custom errors backend.

        Example: "custom-errors-backend-service"

        Required value.

    • disableHTTP2 (boolean)

      Switch off HTTP2 support.

      Default: false

    • enableIstioSidecar (boolean)

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

      With this flag set, the controller can only serve services that Istio controls.

    • geoIP2 (object)

      Enable GeoIP2 databases (version "0.33" or later of the controller is required).

      • maxmindEditionIDs (array of strings)

        A list of database editions to download at startup.

        This article sheds light on the differences between GeoIP2-City and GeoLite2-City databases.

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

        Allowed values of the array: GeoIP2-Anonymous-IP, GeoIP2-Country, GeoIP2-City, GeoIP2-Connection-Type, GeoIP2-Domain, GeoIP2-ISP, GeoIP2-ASN, GeoLite2-ASN, GeoLite2-Country, GeoLite2-City

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

    • hostPort (object)

      HostPort inlet settings.

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

      • 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: 80

      • 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: 443

      • 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: "CF-Connecting-IP"

    • hostPortWithProxyProtocol (object)

      A section of parameters of the HostPortWithProxyProtocol inlet.

      • 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: 80

      • 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: 443

    • hsts (boolean)

      Determines whether hsts is enabled (read more…).

      Default: false

    • hstsOptions (object)

      Options for HTTP Strict Transport Security.

      • includeSubDomains (boolean)

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

        Default: false

      • 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: "31536000"

      • preload (boolean)

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

        Default: false

    • ingressClass (string)

      The name of the Ingress class to use with the Ingress nginx 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 will also be handled.

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

      Example: "nginx"

      Required value.

    • inlet (string)

      The way traffic goes to cluster from the outer network.

      • 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.
      • HostPortWithProxyProtocol — Ingress controller is deployed and available through nodes’ ports via `hostPort, it uses proxy-protocol to get a real IP of the client.

        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, 10354, 10355.

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

      Required value.

    • legacySSL (boolean)

      Enable old TLS protocol versions and legacy cipher suites.

      Also, this options enables legacy cipher suites to support legacy libraries and software: OWASP Cipher String ‘C’ . Learn more here.

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

    • loadBalancer (object)

      A section of parameters of the LoadBalancer inlet.

      Not required value.

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

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

      • 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: "CF-Connecting-IP"

      • sourceRanges (array of strings)

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

        The cloud provider may not support this option or ignore it. .

        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]))$

    • loadBalancerWithProxyProtocol (object)

      A section of parameters of the LoadBalancerWithProxyProtocol inlet.

      Not required value.

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

      • sourceRanges (array of strings)

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

        The cloud provider may not support this option or ignore it. .

        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]))$

    • maxReplicas (integer)

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

      Default: 1

      Allowed values: 1 <= X

    • minReplicas (integer)

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

      Default: 1

      Allowed values: 1 <= X

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

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

      • mode (string)

        The mode for managing resource requests.

        Default: "VPA"

        Allowed values: VPA, Static

        Required value.

      • static (object)

        Static mode settings.

        • cpu (string)

          CPU requests.

          Default: "350m"

        • memory (string)

          Memory requests.

          Default: "500Mi"

      • vpa (object)

        Parameters of the vpa mode.

        • cpu (object)

          CPU-related parameters.

          • max (string)

            Maximum allowed CPU requests.

            Default: "50m"

          • min (string)

            Minimum allowed CPU requests.

            Default: "10m"

        • memory (object)

          The amount of memory requested.

          • max (string)

            Maximum allowed memory requests.

            Default: "200Mi"

          • min (string)

            Minimum allowed memory requests.

            Default: "50Mi"

        • mode (string)

          The VPA usage mode.

          Default: "Initial"

          Allowed values: Initial, Auto

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

      • effect (string)

        Allowed values: NoSchedule, PreferNoSchedule, NoExecute

      • key (string)
      • operator (string)

        Default: "Equal"

        Allowed values: Exists, Equal

      • tolerationSeconds (integer)
      • value (string)
    • 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

    • validationEnabled (boolean)

      Enable ingress validation admission.

      Attention!: This feature doesn’t work for controllers of <0.33 version.

      Default: true

    • waitLoadBalancerOnTerminating (integer)

      The number of seconds before the /healthz location will start to return a 500 code when the pod enters the Terminating state.

      Default: 60

  • spec (object)

    Required value.

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

      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]))$

    • additionalHeaders (object)

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

    • 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

    • 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

    • controllerVersion (string)

      One of the supported NGINX Ingress Controller versions.

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

      Allowed values: 0.25, 0.26, 0.33, 0.46, 0.48

    • 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 Ingress nginx controllers.

      • serviceName — the name of the service to use as the custom default backend.
      • namespace — the name of the namespace where the custom default backend service is running.
      • codes — a list of response codes (an array) for which the request will be redirected to the custom default backend.
      • codes (array of strings)

        Error codes which should be redirected to custom errors backend.

        Required value.

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

      • namespace (string)

        Namespace of custom errors backend.

        Example: "default"

        Required value.

      • serviceName (string)

        Name of kubernetes service that leads to custom errors backend.

        Example: "custom-errors-backend-service"

        Required value.

    • disableHTTP2 (boolean)

      Switch off HTTP2 support.

      Default: false

    • enableIstioSidecar (boolean)

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

      With this flag set, the controller can only serve services that Istio controls.

    • geoIP2 (object)

      Enable GeoIP2 databases (version "0.33" or later of the controller is required).

      • maxmindEditionIDs (array of strings)

        A list of database editions to download at startup.

        This article sheds light on the differences between GeoIP2-City and GeoLite2-City databases.

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

        Allowed values of the array: GeoIP2-Anonymous-IP, GeoIP2-Country, GeoIP2-City, GeoIP2-Connection-Type, GeoIP2-Domain, GeoIP2-ISP, GeoIP2-ASN, GeoLite2-ASN, GeoLite2-Country, GeoLite2-City

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

    • hostPort (object)

      HostPort inlet settings.

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

      • 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: 80

      • 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: 443

      • 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: "CF-Connecting-IP"

    • hostPortWithProxyProtocol (object)

      A section of parameters of the HostPortWithProxyProtocol inlet.

      • 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: 80

      • 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: 443

    • hsts (boolean)

      Determines whether hsts is enabled (read more…).

      Default: false

    • hstsOptions (object)

      Options for HTTP Strict Transport Security.

      • includeSubDomains (boolean)

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

        Default: false

      • 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: "31536000"

      • preload (boolean)

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

        Default: false

    • ingressClass (string)

      The name of the Ingress class to use with the Ingress nginx 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 will also be handled.

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

      Example: "nginx"

      Required value.

    • inlet (string)

      The way traffic goes to cluster from the outer network.

      • 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.
      • HostPortWithProxyProtocol — Ingress controller is deployed and available through nodes’ ports via `hostPort, it uses proxy-protocol to get a real IP of the client.

        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, 10354, 10355.

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

      Required value.

    • legacySSL (boolean)

      Enable old TLS protocol versions and legacy cipher suites.

      Also, this options enables legacy cipher suites to support legacy libraries and software: OWASP Cipher String ‘C’ . Learn more here.

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

    • loadBalancer (object)

      A section of parameters of the LoadBalancer inlet.

      Not required value.

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

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

      • 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: "CF-Connecting-IP"

      • sourceRanges (array of strings)

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

        The cloud provider may not support this option or ignore it. .

        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]))$

    • loadBalancerWithProxyProtocol (object)

      A section of parameters of the LoadBalancerWithProxyProtocol inlet.

      Not required value.

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

      • sourceRanges (array of strings)

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

        The cloud provider may not support this option or ignore it. .

        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]))$

    • maxReplicas (integer)

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

      Default: 1

      Allowed values: 1 <= X

    • minReplicas (integer)

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

      Default: 1

      Allowed values: 1 <= X

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

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

      • mode (string)

        The mode for managing resource requests.

        Default: "VPA"

        Allowed values: VPA, Static

        Required value.

      • static (object)

        Static mode settings.

        • cpu (string)

          CPU requests.

          Default: "350m"

        • memory (string)

          Memory requests.

          Default: "500Mi"

      • vpa (object)

        Parameters of the vpa mode.

        • cpu (object)

          CPU-related parameters.

          • max (string)

            Maximum allowed CPU requests.

            Default: "50m"

          • min (string)

            Minimum allowed CPU requests.

            Default: "10m"

        • memory (object)

          The amount of memory requested.

          • max (string)

            Maximum allowed memory requests.

            Default: "200Mi"

          • min (string)

            Minimum allowed memory requests.

            Default: "50Mi"

        • mode (string)

          The VPA usage mode.

          Default: "Initial"

          Allowed values: Initial, Auto

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

      • effect (string)

        Allowed values: NoSchedule, PreferNoSchedule, NoExecute

      • key (string)
      • operator (string)

        Default: "Equal"

        Allowed values: Exists, Equal

      • tolerationSeconds (integer)
      • value (string)
    • 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

    • validationEnabled (boolean)

      Enable ingress validation admission.

      Attention!: This feature doesn’t work for controllers of <0.33 version.

      Default: true

    • waitLoadBalancerOnTerminating (integer)

      The number of seconds before the /healthz location will start to return a 500 code when the pod enters the Terminating state.

      Default: 60