> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Ingress Classes

> Manage Kubernetes IngressClasses that define which controller handles Ingress resources

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

## Key Concepts

<CardGroup cols={2}>
  <Card title="IngressClass" icon="layer-group">
    A cluster-scoped resource that identifies an Ingress controller and its configuration.
  </Card>

  <Card title="Controller" icon="server">
    The identifier of the Ingress controller that implements this class (e.g., `k8s.io/ingress-nginx`).
  </Card>

  <Card title="Default Class" icon="star">
    The IngressClass used when an Ingress doesn't specify `ingressClassName`.
  </Card>

  <Card title="Parameters" icon="sliders">
    Optional reference to a resource containing controller-specific configuration.
  </Card>
</CardGroup>

<Info>
  IngressClass is a **cluster-scoped** resource, meaning it applies to the entire cluster rather than a specific namespace.
</Info>

## Required Permissions

| Action              | Permission                                     |
| ------------------- | ---------------------------------------------- |
| View ingressclasses | `iam:project:infrastructure:kubernetes:read`   |
| Create ingressclass | `iam:project:infrastructure:kubernetes:write`  |
| Edit ingressclass   | `iam:project:infrastructure:kubernetes:write`  |
| Delete ingressclass | `iam:project:infrastructure:kubernetes:delete` |

## How to View Ingress Classes

<Steps>
  <Step title="Select Cluster">
    Choose a cluster from the cluster dropdown.
  </Step>

  <Step title="View List">
    The list shows all IngressClasses in the cluster (cluster-scoped, no namespace filter).
  </Step>

  <Step title="Search">
    Use the search box to find IngressClasses by name or controller.
  </Step>
</Steps>

## How to View IngressClass Details

<Steps>
  <Step title="Find the IngressClass">
    Locate the IngressClass in the list.
  </Step>

  <Step title="Click IngressClass Name">
    Click on the IngressClass name to open the detail drawer.
  </Step>

  <Step title="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
  </Step>
</Steps>

## How to Create an IngressClass

<Steps>
  <Step title="Click Create IngressClass">
    Click the **Create IngressClass** button in the page header.
  </Step>

  <Step title="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
  </Step>

  <Step title="Create">
    Click **Create** to apply the manifest.
  </Step>
</Steps>

<Tip>
  To make an IngressClass the default, add the annotation `ingressclass.kubernetes.io/is-default-class: "true"` to its metadata.
</Tip>

## How to Edit an IngressClass

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu (three dots) on the IngressClass row.
  </Step>

  <Step title="Click Edit IngressClass">
    Select **Edit IngressClass** to open the YAML editor.
  </Step>

  <Step title="Modify Spec">
    Edit the IngressClass specification. Common changes:

    * Set or remove default class annotation
    * Update parameters reference
    * Modify labels and annotations
  </Step>

  <Step title="Save">
    Click **Update** to apply changes.
  </Step>
</Steps>

<Warning>
  The `spec.controller` field is immutable after creation. To change the controller, delete and recreate the IngressClass.
</Warning>

## How to Delete an IngressClass

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu on the IngressClass row.
  </Step>

  <Step title="Click Delete">
    Select **Delete** from the menu.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. Existing Ingresses referencing this class will lose their controller association.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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:**

```yaml theme={null}
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nginx
  annotations:
    ingressclass.kubernetes.io/is-default-class: "true"
spec:
  controller: k8s.io/ingress-nginx
```

| Annotation                                    | Description                                            |
| --------------------------------------------- | ------------------------------------------------------ |
| `ingressclass.kubernetes.io/is-default-class` | Set to `"true"` to make this the default (recommended) |
| `kubernetes.io/ingress.class-default`         | Legacy annotation, also supported                      |

<Info>
  Only one IngressClass should be marked as default. If multiple are marked, behavior depends on the ingress controllers and Kubernetes version.
</Info>

## Controller Parameters

Parameters allow passing controller-specific configuration:

```yaml theme={null}
spec:
  controller: k8s.io/ingress-nginx
  parameters:
    apiGroup: k8s.example.com
    kind: IngressParameters
    name: nginx-config
    namespace: ingress-nginx
    scope: Namespace
```

| Field         | Description                                                     |
| ------------- | --------------------------------------------------------------- |
| **apiGroup**  | API group of the parameters resource                            |
| **kind**      | Kind of the parameters resource                                 |
| **name**      | Name of the parameters resource                                 |
| **namespace** | Namespace of the resource (for Namespace scope)                 |
| **scope**     | `Cluster` for cluster-wide or `Namespace` for namespaced config |

## Common Ingress Controllers

| Controller  | Controller Value                       | Description                      |
| ----------- | -------------------------------------- | -------------------------------- |
| **NGINX**   | `k8s.io/ingress-nginx`                 | Popular, feature-rich controller |
| **Traefik** | `traefik.io/ingress-controller`        | Cloud-native, automatic HTTPS    |
| **HAProxy** | `haproxy.org/ingress-controller`       | High-performance load balancer   |
| **Contour** | `projectcontour.io/ingress-controller` | Envoy-based controller           |
| **AWS ALB** | `ingress.k8s.aws/alb`                  | AWS Application Load Balancer    |
| **GCE**     | `gce.io/ingress-controller`            | Google Cloud Load Balancer       |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Ingress not being handled">
    * 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
  </Accordion>

  <Accordion title="Multiple controllers responding">
    * Ensure each Ingress specifies explicit `ingressClassName`
    * Only mark one IngressClass as default
    * Check for legacy `kubernetes.io/ingress.class` annotations on Ingresses
  </Accordion>

  <Accordion title="Parameters not taking effect">
    * 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
  </Accordion>

  <Accordion title="Cannot delete IngressClass">
    * Check if Ingresses are still referencing this class
    * Verify you have delete permission
    * Check for finalizers blocking deletion
  </Accordion>

  <Accordion title="Default class not working">
    * 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
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Do I need an IngressClass?">
    Yes, for Kubernetes 1.19+. Each Ingress should specify an `ingressClassName` or rely on a default IngressClass. Without one, Ingresses may not be handled.
  </Accordion>

  <Accordion title="Can I have multiple IngressClasses?">
    Yes. Multiple IngressClasses allow different controllers or configurations. Use `ingressClassName` on each Ingress to select which class handles it.
  </Accordion>

  <Accordion title="What happens if I delete an IngressClass?">
    Existing Ingresses keep their reference but the controller won't recognize them. Traffic routing stops until the IngressClass is recreated or Ingresses are updated.
  </Accordion>

  <Accordion title="How do I migrate from the legacy ingress.class annotation?">
    Create an IngressClass with the matching controller and update Ingresses to use `spec.ingressClassName` instead of the `kubernetes.io/ingress.class` annotation.
  </Accordion>

  <Accordion title="Can I change the controller of an IngressClass?">
    No, the controller field is immutable. Delete the IngressClass and create a new one with the different controller.
  </Accordion>

  <Accordion title="What are parameters used for?">
    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.
  </Accordion>

  <Accordion title="Should I have a default IngressClass?">
    It's recommended for convenience. A default IngressClass handles Ingresses that don't specify a class, reducing configuration burden and preventing unhandled Ingresses.
  </Accordion>

  <Accordion title="How do I know which controller handles an IngressClass?">
    Check the `spec.controller` field. This string identifies the controller that watches for Ingresses with this class. Each controller has a unique identifier.
  </Accordion>
</AccordionGroup>