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:

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.

What's next