Skip to main content
IngressClasses define which Ingress controller should handle Ingress resources. They allow multiple controllers in a cluster and specify controller-specific configuration parameters.

​
Key Concepts

IngressClass

A cluster-scoped resource that identifies an Ingress controller and its configuration.

Controller

The identifier of the Ingress controller that implements this class (e.g., k8s.io/ingress-nginx).

Default Class

The IngressClass used when an Ingress doesn’t specify ingressClassName.

Parameters

Optional reference to a resource containing controller-specific configuration.
IngressClass is a cluster-scoped resource, meaning it applies to the entire cluster rather than a specific namespace.

​
Required Permissions

ActionPermission
View ingressclassesiam:project:infrastructure:kubernetes:read
Create ingressclassiam:project:infrastructure:kubernetes:write
Edit ingressclassiam:project:infrastructure:kubernetes:write
Delete ingressclassiam:project:infrastructure:kubernetes:delete

​
How to View Ingress Classes

1

Select Cluster

Choose a cluster from the cluster dropdown.
2

View List

The list shows all IngressClasses in the cluster (cluster-scoped, no namespace filter).
3

Search

Use the search box to find IngressClasses by name or controller.

​
How to View IngressClass Details

1

Find the IngressClass

Locate the IngressClass in the list.
2

Click IngressClass Name

Click on the IngressClass name to open the detail drawer.
3

Review Details

View IngressClass information including:
  • Overview: Name, controller, default status, age
  • Parameters: Reference to controller configuration resource
  • Labels & Annotations: Metadata including default class annotation
  • Events: Related Kubernetes events

​
How to Create an IngressClass

1

Click Create IngressClass

Click the Create IngressClass button in the page header.
2

Write YAML

Enter the IngressClass manifest in YAML format. Key fields:
  • spec.controller - Controller identifier (required)
  • metadata.annotations - Include default class annotation if needed
  • spec.parameters - Optional controller configuration reference
3

Create

Click Create to apply the manifest.
To make an IngressClass the default, add the annotation ingressclass.kubernetes.io/is-default-class: "true" to its metadata.

​
How to Edit an IngressClass

1

Open Actions Menu

Click the actions menu (three dots) on the IngressClass row.
2

Click Edit IngressClass

Select Edit IngressClass to open the YAML editor.
3

Modify Spec

Edit the IngressClass specification. Common changes:
  • Set or remove default class annotation
  • Update parameters reference
  • Modify labels and annotations
4

Save

Click Update to apply changes.
The spec.controller field is immutable after creation. To change the controller, delete and recreate the IngressClass.

​
How to Delete an IngressClass

1

Open Actions Menu

Click the actions menu on the IngressClass row.
2

Click Delete

Select Delete from the menu.
3

Confirm

Confirm the deletion. Existing Ingresses referencing this class will lose their controller association.
Deleting the default IngressClass affects all Ingresses that don’t specify an ingressClassName. Those Ingresses will no longer be handled by any controller until a new default is set.

​
Default IngressClass

One IngressClass can be marked as the cluster default. Ingresses that don’t specify ingressClassName will use the default class. Setting the default: 
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nginx
  annotations:
    ingressclass.kubernetes.io/is-default-class: "true"
spec:
  controller: k8s.io/ingress-nginx
AnnotationDescription
ingressclass.kubernetes.io/is-default-classSet to "true" to make this the default (recommended)
kubernetes.io/ingress.class-defaultLegacy annotation, also supported
Only one IngressClass should be marked as default. If multiple are marked, behavior depends on the ingress controllers and Kubernetes version.

​
Controller Parameters

Parameters allow passing controller-specific configuration: 
spec:
  controller: k8s.io/ingress-nginx
  parameters:
    apiGroup: k8s.example.com
    kind: IngressParameters
    name: nginx-config
    namespace: ingress-nginx
    scope: Namespace
FieldDescription
apiGroupAPI group of the parameters resource
kindKind of the parameters resource
nameName of the parameters resource
namespaceNamespace of the resource (for Namespace scope)
scopeCluster for cluster-wide or Namespace for namespaced config

​
Common Ingress Controllers

ControllerController ValueDescription
NGINXk8s.io/ingress-nginxPopular, feature-rich controller
Traefiktraefik.io/ingress-controllerCloud-native, automatic HTTPS
HAProxyhaproxy.org/ingress-controllerHigh-performance load balancer
Contourprojectcontour.io/ingress-controllerEnvoy-based controller
AWS ALBingress.k8s.aws/albAWS Application Load Balancer
GCEgce.io/ingress-controllerGoogle Cloud Load Balancer

​
Troubleshooting

  • Verify the Ingress specifies the correct ingressClassName
  • Check if the IngressClass exists and has the right controller
  • Verify the controller pods are running
  • Check if a default IngressClass is set for Ingresses without explicit class
  • Ensure each Ingress specifies explicit ingressClassName
  • Only mark one IngressClass as default
  • Check for legacy kubernetes.io/ingress.class annotations on Ingresses
  • Verify the parameters resource exists
  • Check apiGroup, kind, and name are correct
  • Ensure the controller supports the parameter type
  • Verify scope matches the resource location
  • Check if Ingresses are still referencing this class
  • Verify you have delete permission
  • Check for finalizers blocking deletion
  • Verify annotation key is exactly ingressclass.kubernetes.io/is-default-class
  • Ensure value is the string "true" (quoted)
  • Check Kubernetes version supports default IngressClass (1.19+)
  • Verify only one IngressClass is marked as default

​
FAQ

Yes, for Kubernetes 1.19+. Each Ingress should specify an ingressClassName or rely on a default IngressClass. Without one, Ingresses may not be handled.
Yes. Multiple IngressClasses allow different controllers or configurations. Use ingressClassName on each Ingress to select which class handles it.
Existing Ingresses keep their reference but the controller won’t recognize them. Traffic routing stops until the IngressClass is recreated or Ingresses are updated.
Create an IngressClass with the matching controller and update Ingresses to use spec.ingressClassName instead of the kubernetes.io/ingress.class annotation.
No, the controller field is immutable. Delete the IngressClass and create a new one with the different controller.
Parameters reference a custom resource containing controller-specific configuration. For example, NGINX can reference a ConfigMap-like resource for global settings that apply to all Ingresses using this class.
It’s recommended for convenience. A default IngressClass handles Ingresses that don’t specify a class, reducing configuration burden and preventing unhandled Ingresses.
Check the spec.controller field. This string identifies the controller that watches for Ingresses with this class. Each controller has a unique identifier.