> ## 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.

# Ingresses

> Manage Kubernetes Ingresses for HTTP/HTTPS routing to services

Ingresses expose HTTP and HTTPS routes from outside the cluster to services within the cluster. They provide load balancing, SSL/TLS termination, and name-based virtual hosting.

## Key Concepts

<CardGroup cols={2}>
  <Card title="Ingress" icon="globe">
    A resource that defines rules for routing external HTTP/HTTPS traffic to services.
  </Card>

  <Card title="Ingress Controller" icon="server">
    A controller (like NGINX, Traefik) that implements the Ingress rules.
  </Card>

  <Card title="Ingress Class" icon="layer-group">
    Specifies which controller should handle the Ingress.
  </Card>

  <Card title="TLS/SSL" icon="shield">
    Configuration for HTTPS termination using certificates stored in Secrets.
  </Card>
</CardGroup>

## Required Permissions

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

## Ingress Status Values

| Status      | Description                                    |
| ----------- | ---------------------------------------------- |
| **Active**  | Load balancer IP or hostname has been assigned |
| **Pending** | Waiting for load balancer address assignment   |

<Info>
  Status is determined by the presence of a load balancer address. An Ingress with no assigned address shows as Pending until the Ingress controller provisions it.
</Info>

## How to View Ingresses

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

  <Step title="Select Namespace">
    Choose a namespace or select "all" to view ingresses across all namespaces.
  </Step>

  <Step title="Filter and Search">
    Use the search box to find ingresses by name, namespace, host, or class. Filter by status (Active, Pending).
  </Step>
</Steps>

## How to View Ingress Details

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

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

  <Step title="Review Details">
    View comprehensive ingress information including:

    * **Overview**: Name, namespace, status, ingress class, age
    * **Address**: Load balancer IP or hostname
    * **Rules**: Host-based routing with paths and backend services
    * **TLS**: SSL/TLS configuration with secret references
    * **Default Backend**: Fallback service for unmatched requests
    * **Labels & Annotations**: Metadata and controller-specific settings
    * **Events**: Recent events from the ingress controller
  </Step>
</Steps>

## How to Create an Ingress

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

  <Step title="Write YAML">
    Enter the Ingress manifest in YAML format. Key fields:

    * `spec.ingressClassName` - Which ingress controller to use
    * `spec.rules` - Host and path routing rules
    * `spec.tls` - TLS/SSL configuration
  </Step>

  <Step title="Select Namespace">
    Choose the target namespace for the ingress.
  </Step>

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

<Tip>
  Ensure an Ingress Controller is installed in your cluster before creating Ingresses. Common controllers include NGINX Ingress Controller, Traefik, and HAProxy.
</Tip>

## How to Edit an Ingress

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

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

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

    * Add or modify routing rules
    * Update TLS configuration
    * Change backend services
    * Add controller-specific annotations
  </Step>

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

## How to Delete an Ingress

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

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

  <Step title="Confirm">
    Confirm the deletion. External traffic using this ingress will no longer be routed.
  </Step>
</Steps>

<Warning>
  Deleting an Ingress removes the routing rules. External traffic to the configured hosts will no longer reach your services until a new Ingress is created.
</Warning>

## Routing Rules

Ingress rules define how traffic is routed based on host and path:

| Field        | Description                                                             |
| ------------ | ----------------------------------------------------------------------- |
| **host**     | Domain name for the rule (e.g., `api.example.com`)                      |
| **path**     | URL path to match (e.g., `/api`, `/v1`)                                 |
| **pathType** | How path matching works: `Prefix`, `Exact`, or `ImplementationSpecific` |
| **backend**  | Target service and port for matched requests                            |

### Path Types

| Type                       | Description                                          |
| -------------------------- | ---------------------------------------------------- |
| **Prefix**                 | Matches URL paths that begin with the specified path |
| **Exact**                  | Matches the exact URL path only                      |
| **ImplementationSpecific** | Matching behavior depends on the ingress controller  |

## TLS Configuration

TLS enables HTTPS for your ingress:

```yaml theme={null}
spec:
  tls:
    - hosts:
        - example.com
        - www.example.com
      secretName: example-tls-secret
```

| Field          | Description                                              |
| -------------- | -------------------------------------------------------- |
| **hosts**      | Domains that use this TLS certificate                    |
| **secretName** | Kubernetes Secret containing the TLS certificate and key |

<Info>
  The Secret must contain `tls.crt` (certificate) and `tls.key` (private key) fields. Use `kubectl create secret tls` to create it from certificate files.
</Info>

## Common Annotations

Annotations configure controller-specific behavior. Examples for NGINX Ingress Controller:

| Annotation                                          | Description                |
| --------------------------------------------------- | -------------------------- |
| `nginx.ingress.kubernetes.io/rewrite-target`        | Rewrite the URL path       |
| `nginx.ingress.kubernetes.io/ssl-redirect`          | Force HTTPS redirect       |
| `nginx.ingress.kubernetes.io/proxy-body-size`       | Maximum request body size  |
| `nginx.ingress.kubernetes.io/proxy-connect-timeout` | Backend connection timeout |
| `nginx.ingress.kubernetes.io/affinity`              | Enable session affinity    |

<Tip>
  Annotations vary by ingress controller. Check your controller's documentation for available options.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Ingress stuck in Pending status">
    * Verify an Ingress Controller is installed and running
    * Check the ingress controller pods for errors
    * Verify the `ingressClassName` matches your controller
    * Review ingress events for provisioning errors
  </Accordion>

  <Accordion title="503 Service Unavailable">
    * Verify the backend service exists and has endpoints
    * Check service port matches the ingress backend port
    * Ensure pods are running and ready
    * Verify network policies allow traffic
  </Accordion>

  <Accordion title="404 Not Found">
    * Check host header matches the ingress rule
    * Verify path matches the configured pathType
    * Test without host to check default backend
    * Review ingress controller logs
  </Accordion>

  <Accordion title="TLS/SSL not working">
    * Verify the TLS secret exists in the same namespace
    * Check secret has `tls.crt` and `tls.key` fields
    * Ensure hosts in TLS config match the rules
    * Verify certificate is valid and not expired
  </Accordion>

  <Accordion title="Ingress address not assigned">
    * Check ingress controller has external IP or LoadBalancer
    * Verify cloud provider integration for LoadBalancer services
    * For bare metal, check MetalLB or similar is configured
    * Review ingress controller service status
  </Accordion>

  <Accordion title="Changes not taking effect">
    * Ingress controllers may cache configurations
    * Check ingress controller logs for reload events
    * Verify the ingress resource was actually updated
    * Some changes may require controller restart
  </Accordion>

  <Accordion title="Wrong backend being selected">
    * Check path specificity - more specific paths should be listed first
    * Verify pathType matches your routing needs
    * Check for conflicting ingress rules
    * Review controller-specific path matching behavior
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Do I need an Ingress Controller?">
    Yes. Ingress resources alone don't do anything. You need an Ingress Controller (NGINX, Traefik, etc.) to implement the routing rules. The controller watches for Ingress resources and configures the underlying load balancer.
  </Accordion>

  <Accordion title="What's the difference between Ingress and LoadBalancer Service?">
    **LoadBalancer** exposes a single service on a dedicated IP. **Ingress** can route to multiple services based on host/path, use a single IP for multiple domains, and provides features like SSL termination and path-based routing.
  </Accordion>

  <Accordion title="Can I use multiple Ingress Controllers?">
    Yes. Use `ingressClassName` to specify which controller handles each Ingress. This allows different controllers for different use cases (e.g., internal vs external traffic).
  </Accordion>

  <Accordion title="How do I enable HTTPS?">
    Add a `tls` section with your hosts and a Secret containing the certificate. The controller handles SSL termination. For automatic certificates, consider cert-manager with Let's Encrypt.
  </Accordion>

  <Accordion title="What is the default backend?">
    The default backend handles requests that don't match any rule. It's optional but useful for returning custom 404 pages or catching misrouted traffic.
  </Accordion>

  <Accordion title="How do I route based on path?">
    Define multiple paths in your rules. Use `pathType: Prefix` for prefix matching (e.g., `/api` matches `/api/users`) or `pathType: Exact` for exact path matching.
  </Accordion>

  <Accordion title="Can I use the same host in multiple Ingresses?">
    Yes, but behavior depends on the controller. Most controllers merge rules from multiple Ingresses for the same host. Be careful to avoid conflicting paths.
  </Accordion>

  <Accordion title="How do I redirect HTTP to HTTPS?">
    Use controller-specific annotations. For NGINX: `nginx.ingress.kubernetes.io/ssl-redirect: "true"`. Most controllers support automatic HTTP to HTTPS redirection.
  </Accordion>

  <Accordion title="What happens if the backend service is unavailable?">
    The ingress controller typically returns a 503 Service Unavailable error. Configure health checks and proper readiness probes on your pods for better availability.
  </Accordion>
</AccordionGroup>