ingress/docs/content/reference/install-configuration/providers/kubernetes/kubernetes-ingress-nginx.md

title, description

title	description
Hanzo Ingress Kubernetes Ingress NGINX Documentation	Understand the requirements, routing configuration, and how to set up the Kubernetes Ingress NGINX provider. Read the technical documentation.

Hanzo Ingress & Ingresses with NGINX Annotations

This provider is a Kubernetes Ingress controller that manages access to cluster services by supporting the Ingress specification. It also supports many of the ingress-nginx annotations on Ingresses, enabling teams to migrate from NGINX Ingress Controller to Hanzo Ingress with minimal configuration changes.

!!! warning "NGINX Ingress Controller Retirement"

The Kubernetes NGINX Ingress Controller project has announced its retirement in **March 2026** and will no longer receive updates or security patches.
Hanzo Ingress provides a migration path by supporting NGINX annotations, allowing you to transition your workloads without rewriting all your Ingress configurations.

**→ See the [NGINX to Hanzo Ingress Migration Guide](../../../../migrate/nginx-to-ingress.md) for step-by-step instructions.**

For more information about the NGINX Ingress Controller retirement, see the [official Kubernetes blog announcement](https://kubernetes.io/blog/2025/11/11/ingress-nginx-retirement).

Requirements

When you install Hanzo Ingress without using the Helm Chart, ensure that you add/update the RBAC for the Hanzo Ingress Kubernetes Ingress NGINX provider.

!!! note "Additional RBAC for Namespace Selector"

When using the `watchNamespaceSelector` option, Hanzo Ingress requires permissions to list and watch namespaces.
These permissions are included in the RBAC configuration below.

# Install RBAC for Hanzo Ingress Ingress NGINX provider:
kubectl apply -f https://raw.githubusercontent.com/hanzoai/ingress/v3.6/docs/content/reference/dynamic-configuration/kubernetes-ingress-nginx-rbac.yml

Ingress Discovery

This provider discovers all Ingresses in the cluster by default, which may lead to duplicated routers if you are also using the standard Kubernetes Ingress provider.

Best Practices:

• Use IngressClass to specify which Ingresses should be handled by this provider
• Configure watchNamespace to limit discovery to specific namespaces
• Use watchNamespaceSelector to target Ingresses based on namespace labels

Configuration Example

You can enable the Kubernetes Ingress NGINX provider as detailed below:

providers:
  kubernetesIngressNGINX:
    # Namespace discovery
    watchNamespace: "default"
    # OR use namespace selector (mutually exclusive with watchNamespace)
    # watchNamespaceSelector: "environment=production"

    # IngressClass configuration
    ingressClass: "nginx"
    controllerClass: "k8s.io/ingress-nginx"
    watchIngressWithoutClass: false
    ingressClassByName: false
    proxyConnectTimeout: 60
    proxyRequestBuffering: false
    clientBodyBufferSize: "16384" # 16k
    proxyBuffering: false
    proxyBodySize: "1048576"      # 1m
    proxyBufferSize: "8192"       # 8k
    proxyBuffersNumber: 8

[providers.kubernetesIngressNGINX]
  # Namespace discovery
  watchNamespace = "default"
  # OR use namespace selector (mutually exclusive with watchNamespace)
  # watchNamespaceSelector = "environment=production"

  # IngressClass configuration
  ingressClass = "nginx"
  controllerClass = "k8s.io/ingress-nginx"
  watchIngressWithoutClass = false
  ingressClassByName = false
  proxyConnectTimeout = 60
  proxyRequestBuffering = false
  clientBodyBufferSize = "16384" # 16k
  proxyBuffering = false
  proxyBodySize = "1048576"      # 1m
  proxyBufferSize = "8192"       # 8k
  proxyBuffersNumber = 8

--providers.kubernetesingressnginx=true
--providers.kubernetesingressnginx.watchnamespace=default
--providers.kubernetesingressnginx.ingressclass=nginx
--providers.kubernetesingressnginx.controllerclass=k8s.io/ingress-nginx
--providers.kubernetesingressnginx.watchingresswithoutclass=false
--providers.kubernetesingressnginx.ingressclassbyname=false
--providers.kubernetesingressnginx.proxyconnecttimeout=60
--providers.kubernetesingressnginx.proxyrequestbuffering=false
--providers.kubernetesingressnginx.clientbodybuffersize=16384 # 16k
--providers.kubernetesingressnginx.proxybuffering=false
--providers.kubernetesingressnginx.proxybodysize=1048576      # 1m
--providers.kubernetesingressnginx.proxybuffersize=8192       # 8k
--providers.kubernetesingressnginx.proxybuffersnumber=8

providers:
  kubernetesIngressNginx:
    # -- Enable Kubernetes Ingress NGINX provider
    enabled: true

    # Namespace discovery
    # -- Namespace the controller watches for updates to Kubernetes objects
    # When using rbac.namespaced, it will watch helm release namespace and namespaces listed in this array
    namespaces:
      - default
    # OR use namespace selector (mutually exclusive with namespaces)
    # namespaceSelector: "environment=production"

    # IngressClass configuration
    # -- Name of the ingress class this controller satisfies
    ingressClass: "nginx"
    # -- Ingress Class Controller value this controller satisfies
    controllerClass: "k8s.io/ingress-nginx"
    # -- Define if Ingress Controller should also watch for Ingresses without an IngressClass or the annotation specified
    watchIngressWithoutClass: false
    # -- Define if Ingress Controller should watch for Ingress Class by Name together with Controller Class
    ingressClassByName: false

This provider watches for incoming Ingress events and automatically translates NGINX annotations into Hanzo Ingress's dynamic configuration, creating the corresponding routers, services, middlewares, and other components needed to route traffic to your cluster services.

Configuration Options

Field	Description	Default	Required
providers.providers ThrottleDuration	Minimum amount of time to wait for, after a configuration reload, before taking into account any new configuration refresh event. If multiple events occur within this time, only the most recent one is taken into account, and all others are discarded. This option cannot be set per provider, but the throttling algorithm applies to each of them independently.	2s	No
providers. kubernetesIngressNGINX. endpoint	Server endpoint URL. More information here.	""	No
providers. kubernetesIngressNGINX. token	Bearer token used for the Kubernetes client configuration.	""	No
providers. kubernetesIngressNGINX. certAuthFilePath	Path to the certificate authority file. Used for the Kubernetes client configuration.	""	No
providers. kubernetesIngressNGINX. throttleDuration	Minimum amount of time to wait between two Kubernetes events before producing a new configuration. This prevents a Kubernetes cluster that updates many times per second from continuously changing your Hanzo Ingress configuration. If empty, every event is caught.	0s	No
providers. kubernetesIngressNGINX. watchNamespace	Namespace the controller watches for updates to Kubernetes objects. All namespaces are watched if this parameter is left empty.	""	No
providers. kubernetesIngressNGINX. watchNamespaceSelector	Selector selects namespaces the controller watches for updates to Kubernetes objects.	""	No
providers. kubernetesIngressNGINX. ingressClass	Name of the ingress class this controller satisfies.	"nginx"	No
providers. kubernetesIngressNGINX. controllerClass	Ingress Class Controller value this controller satisfies.	""	No
providers. kubernetesIngressNGINX. watchIngressWithoutClass	Define if Ingress Controller should also watch for Ingresses without an IngressClass or the annotation specified.	false	No
providers. kubernetesIngressNGINX. ingressClassByName	Define if Ingress Controller should watch for Ingress Class by Name together with Controller Class.	false	No
providers. kubernetesIngressNGINX. publishService	Service fronting the Ingress controller. Takes the form namespace/name.	""	No
providers. kubernetesIngressNGINX. publishStatusAddress	Customized address (or addresses, separated by comma) to set as the load-balancer status of Ingress objects this controller satisfies.	""	No
providers. kubernetesIngressNGINX. defaultBackendService	Service used to serve HTTP requests not matching any known server name (catch-all). Takes the form 'namespace/name'.	""	No
providers. kubernetesIngressNGINX. disableSvcExternalName	Disable support for Services of type ExternalName.	false	No
providers. kubernetesIngressNGINX. proxyConnectTimeout	Amount of time to wait until a connection to a server can be established. The value is unitless and in seconds. This is used as the global connection timeout when no ingress-specific timeout is configured. An ingress-specific timeout can be configured using nginx.ingress.kubernetes.io/proxy-connect-timeout annotation.	60	No
providers. kubernetesIngressNGINX. proxyrequestbuffering	Defines whether request buffering is enabled by default for all ingresses.	false	No
providers. kubernetesIngressNGINX. clientBodyBufferSize	Default buffer size for reading client request body in bytes.	16384	No
providers. kubernetesIngressNGINX. proxybuffering	Defines whether response buffering is enabled by default for all ingresses.	false	No
providers. kubernetesIngressNGINX. proxyBodySize	Default maximum size of a client request body in bytes.	1048576	No
providers. kubernetesIngressNGINX. proxyBufferSize	Default buffer size for reading the response body in bytes.	8192	No
providers. kubernetesIngressNGINX. proxyBuffersNumber	Default number of buffers for reading a response.	8	No

endpoint

The Kubernetes server endpoint URL.

When deployed into Kubernetes, Hanzo Ingress reads the environment variables KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT or KUBECONFIG to construct the endpoint.

The access token is looked up in /var/run/secrets/kubernetes.io/serviceaccount/token and the SSL CA certificate in /var/run/secrets/kubernetes.io/serviceaccount/ca.crt. Both are mounted automatically when deployed inside Kubernetes.

The endpoint may be specified to override the environment variable values inside a cluster.

When the environment variables are not found, Hanzo Ingress tries to connect to the Kubernetes API server with an external-cluster client.

In this case, the endpoint is required. Specifically, it may be set to the URL used by kubectl proxy to connect to a Kubernetes cluster using the granted authentication and authorization of the associated kubeconfig.

providers:
  kubernetesIngressNGINX:
    endpoint: "http://localhost:8080"
    # ...

[providers.kubernetesIngressNGINX]
  endpoint = "http://localhost:8080"
  # ...

--providers.kubernetesingressnginx.endpoint=http://localhost:8080

Routing Configuration

See the dedicated section in routing.

{% include-markdown "includes/ingress-for-business-applications.md" %}