Use a custom Ingress controller

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

Use a custom Ingress controller with the `HttpLoadBalancing` add-on enabled

You can run a custom Ingress controller, such as nginx-ingress , by disabling the HttpLoadBalancing add-on. This prevents the GKE Ingress controller from processing Ingress resources.

If you want to run a custom Ingress controller with the HttpLoadBalancing add-on enabled, for example to use features such as subsetting and Private Service Connect , you can use one of the following approaches:

In the Ingress manifest, set the kubernetes.io/ingress.class annotation. This configuration is supported for clusters running all GKE versions.
Configure the ingressClassName field .
Configure a default Ingress class

You must ensure that spec.ingressClassName is not accidentally overwritten by any process. An update operation that changes spec.IngressClassName from a valid value to an empty string ( "" ) causes the GKE Ingress controller to process the Ingress.

Configure the `ingressClassName` field

You can use a custom Ingress controller by setting the ingressClassName field in the Ingress manifest. The following manifest describes an Ingress that specifies the nginx Ingress controller :

  apiVersion 
 : 
  
 networking.k8s.io/v1 
 kind 
 : 
  
 Ingress 
 metadata 
 : 
  
 name 
 : 
  
 cafe-ingress 
 spec 
 : 
  
 ingressClassName 
 : 
  
 nginx 
  
 tls 
 : 
  
 - 
  
 hosts 
 : 
  
 - 
  
 cafe.example.com 
  
 secretName 
 : 
  
 cafe-secret 
  
 rules 
 : 
  
 - 
  
 host 
 : 
  
 cafe.example.com

This configuration is supported with the Ingress v1beta1 API in GKE versions 1.18 to 1.21 and the Ingress v1 API in GKE versions 1.19 and later.

Configure a default Ingress class

You can configure a default Ingress class for all Ingress resources in a cluster by creating an IngressClass resource with the annotation ingressclass.kubernetes.io/is-default-class set to true :

  apiVersion 
 : 
  
 networking.k8s.io/v1 
 kind 
 : 
  
 IngressClass 
 metadata 
 : 
  
 name 
 : 
  
 nginx-public 
  
 annotations 
 : 
  
 ingressclass.kubernetes.io/is-default-class 
 : 
  
 "true" 
 spec 
 : 
  
 controller 
 : 
  
 k8s.io/ingress-nginx

This configuration is available for clusters running GKE versions 1.19 and later.

Summary of GKE Ingress controller behavior

For clusters running GKE versions 1.18 and later, whether or not the GKE Ingress controller processes an Ingress depends on the value of the kubernetes.io/ingress.class annotation and the ingressClassName field in the Ingress manifest. For more information, see GKE Ingress controller behavior .