Use a custom Ingress controller

This page describes how you can use a custom Ingress controller withGoogle Kubernetes Engine (GKE).

Caution: Google does not provide support for debugging issues with customIngress controllers.

Use a custom Ingress controller with theHttpLoadBalancing add-on enabled

You can run a custom Ingress controller, such asnginx-ingress, by disablingtheHttpLoadBalancing add-on. This prevents the GKE Ingresscontroller from processing Ingress resources.

If you want to run a custom Ingress controller with theHttpLoadBalancingadd-on enabled, for example to use features such assubsettingandPrivate Service Connect,you can use one of the following approaches:

You must ensure thatspec.ingressClassName is not accidentally overwritten byany process. An update operation that changesspec.IngressClassName from avalid value to an empty string ("") causes the GKE Ingresscontroller to process the Ingress.

Configure theingressClassName field

You can use a custom Ingress controller by setting theingressClassNamefield in the Ingress manifest. The following manifest describes an Ingress thatspecifies thenginx Ingress controller:

apiVersion:networking.k8s.io/v1kind:Ingressmetadata:name:cafe-ingressspec:ingressClassName:nginxtls:-hosts:-cafe.example.comsecretName:cafe-secretrules:-host:cafe.example.com
Note: If an Ingress has an emptyspec.ingressClassName orspec.ingressClassName is not present, and the Ingress does not have theannotationkubernetes.io/ingress.class, the GKE Ingresscontroller processes the Ingress.

This configuration is supported with the Ingressv1beta1 API inGKE versions 1.18 to 1.21 and the Ingressv1 API inGKE versions 1.19 and later.

Configure a default Ingress class

You can configure a default Ingress class for all Ingress resources in acluster by creating anIngressClass resource with the annotationingressclass.kubernetes.io/is-default-class settotrue:

apiVersion:networking.k8s.io/v1kind:IngressClassmetadata:name:nginx-publicannotations:ingressclass.kubernetes.io/is-default-class:"true"spec:controller:k8s.io/ingress-nginx
Note: Theadmission controller populates thespec.ingressClassName field for new Ingress resources in thecluster, but does not modify existing Ingress resources.

This configuration is available for clusters running GKEversions 1.19 and later.

Summary of GKE Ingress controller behavior

For clusters running GKE versions 1.18 and later, whether or notthe GKE Ingress controller processes an Ingress depends on thevalue of thekubernetes.io/ingress.class annotation and theingressClassNamefield in the Ingress manifest. For more information, seeGKE Ingress controller behavior.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.