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.
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:
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:
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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,["# Use a custom Ingress controller\n\n[Autopilot](/kubernetes-engine/docs/concepts/autopilot-overview) [Standard](/kubernetes-engine/docs/concepts/choose-cluster-mode)\n\n*** ** * ** ***\n\nThis page describes how you can use a custom Ingress controller with\nGoogle Kubernetes Engine (GKE).\n| **Caution:** Google does not provide support for debugging issues with custom Ingress controllers.\n\nUse a custom Ingress controller with the `HttpLoadBalancing` add-on enabled\n---------------------------------------------------------------------------\n\nYou can run a custom Ingress controller, such as `nginx-ingress`, by disabling\nthe `HttpLoadBalancing` add-on. This prevents the GKE Ingress\ncontroller from processing Ingress resources.\n\nIf you want to run a custom Ingress controller with the `HttpLoadBalancing`\nadd-on enabled, for example to use features such as\n[subsetting](/kubernetes-engine/docs/how-to/internal-load-balancing#subsetting)\nand\n[Private Service Connect](/kubernetes-engine/docs/how-to/internal-load-balancing-across-vpc-net),\nyou can use one of the following approaches:\n\n- In the Ingress manifest, set the [`kubernetes.io/ingress.class`](https://kubernetes.io/docs/concepts/services-networking/ingress/#deprecated-annotation) annotation. This configuration is supported for clusters running all GKE versions.\n- [Configure the `ingressClassName` field](#ingress_class).\n- [Configure a default Ingress class](#default_class)\n\nYou must ensure that `spec.ingressClassName` is not accidentally overwritten by\nany process. An update operation that changes `spec.IngressClassName` from a\nvalid value to an empty string (`\"\"`) causes the GKE Ingress\ncontroller to process the Ingress.\n\nConfigure the `ingressClassName` field\n--------------------------------------\n\nYou can use a custom Ingress controller by setting the `ingressClassName`\nfield in the Ingress manifest. The following manifest describes an Ingress that\nspecifies the\n[`nginx` Ingress controller](https://kubernetes.github.io/ingress-nginx/): \n\n apiVersion: networking.k8s.io/v1\n kind: Ingress\n metadata:\n name: cafe-ingress\n spec:\n ingressClassName: nginx\n tls:\n - hosts:\n - cafe.example.com\n secretName: cafe-secret\n rules:\n - host: cafe.example.com\n\n| **Note:** If an Ingress has an empty `spec.ingressClassName` or `spec.ingressClassName` is not present, and the Ingress does not have the annotation `kubernetes.io/ingress.class`, the GKE Ingress controller processes the Ingress.\n\nThis configuration is supported with the Ingress `v1beta1` API in\nGKE versions 1.18 to 1.21 and the Ingress `v1` API in\nGKE versions 1.19 and later.\n\nConfigure a default Ingress class\n---------------------------------\n\nYou can configure a default Ingress class for all Ingress resources in a\ncluster by creating an\n[`IngressClass`](https://kubernetes.io/docs/concepts/services-networking/ingress/#ingress-class)\nresource with the annotation `ingressclass.kubernetes.io/is-default-class` set\nto `true`: \n\n apiVersion: networking.k8s.io/v1\n kind: IngressClass\n metadata:\n name: nginx-public\n annotations:\n ingressclass.kubernetes.io/is-default-class: \"true\"\n spec:\n controller: k8s.io/ingress-nginx\n\n| **Note:** The [admission controller](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/) populates the `spec.ingressClassName` field for new Ingress resources in the cluster, but does not modify existing Ingress resources.\n\nThis configuration is available for clusters running GKE\nversions 1.19 and later.\n\nSummary of GKE Ingress controller behavior\n------------------------------------------\n\nFor clusters running GKE versions 1.18 and later, whether or not\nthe GKE Ingress controller processes an Ingress depends on the\nvalue of the `kubernetes.io/ingress.class` annotation and the `ingressClassName`\nfield in the Ingress manifest. For more information, see\n[GKE Ingress controller behavior](/kubernetes-engine/docs/concepts/ingress#controller_summary).\n\nWhat's next\n-----------\n\n- [Learn more about load balancing in Google Cloud](/load-balancing/docs/https).\n- [Learn how to configure Ingress for internal Application Load Balancers](/kubernetes-engine/docs/how-to/internal-load-balance-ingress).\n- [Learn how to configure Ingress for external Application Load Balancers](/kubernetes-engine/docs/how-to/load-balance-ingress).\n- [Implement GKE Ingress using NGNIX Ingress](https://github.com/GoogleCloudPlatform/gke-networking-recipes/tree/main/ingress/single-cluster/ingress-nginx)."]]