# Kubernetes Gateway API

## 1. Why Gateway API Exists

When applications run in Kubernetes, users must be able to access them from outside, and services inside the cluster must communicate with each other.

For a long time, Kubernetes used **Ingress** to expose applications. Ingress worked, but as systems grew larger and teams increased, many real problems appeared.

To solve these problems, Kubernetes introduced the **Gateway API**.

{/* TODO: Add architecture comparison diagram showing Ingress vs Gateway API role separation */}

{/* TODO: Add diagram showing Gateway API multi-team model (infra provider → GatewayClass, cluster operator → Gateway, app developer → HTTPRoute/TLSRoute) */}

## 2. Understanding Traffic in Kubernetes

Before learning Gateway API, we must understand how traffic moves.

### 2.1 North–South Traffic

North–South traffic means:

- Traffic coming **into** the cluster from outside
- Traffic going **out** of the cluster

Examples:

- User opens a website in a browser
- Mobile app calls an API in Kubernetes
- External system connects to a service

This is **external traffic**.

### 2.2 East–West Traffic

East–West traffic means:

- Traffic **inside** the cluster
- Service talking to another service

Examples:

- Frontend calls backend
- Order service calls payment service

This is **internal traffic**.

**Important Note:**

- **Ingress and Gateway API** → handle **North–South traffic**
- **Service Mesh** → handles **East–West traffic**

## 3. What Is Ingress?

Ingress is a Kubernetes object that:

- Exposes services outside the cluster
- Routes traffic using hostnames and paths

Example:

```
/     → frontend service
/api  → backend service
```

Ingress worked well for:

- Small clusters
- Single-team setups
- Basic routing

## 4. Problems with Ingress (Why Change Was Needed)

As Kubernetes moved to production at scale, the following issues became apparent:

- **Everything in one file** — Load balancer config, TLS config, routing rules — all mixed together.
- **Annotations everywhere** — Important logic hidden in annotations.
- **Hard to read and debug** — Large, complex Ingress manifests are difficult to maintain.
- **No clear ownership** — Application teams could modify infrastructure settings, creating risk in multi-team clusters.
- **Different behavior per controller** — The same YAML can behave differently with NGINX, ALB, and other controllers.
- **Security concerns and retirement** — The widely-used Ingress NGINX controller is being retired and will no longer receive updates or security patches after March 2026, making it unsuitable for long-term production use.

See the official retirement announcement: [https://kubernetes.io/blog/2025/11/11/ingress-nginx-retirement/](https://kubernetes.io/blog/2025/11/11/ingress-nginx-retirement/)

Ingress was simple, but not safe or scalable for large environments.

## 5. What Is Gateway API?

Gateway API is a **new Kubernetes networking API** designed to fix the limitations of Ingress.

It provides:

- Clear separation of responsibilities
- Standard behavior across implementations
- Safer configuration for production
- Support for advanced routing

Gateway API separates concerns across three roles:

| Role | Resource | Responsibility |
|------|----------|----------------|
| Infrastructure Provider | `GatewayClass` | Defines available gateway implementations |
| Cluster Operator | `Gateway` | Configures load balancers, TLS, listeners |
| Application Developer | `HTTPRoute` / `TLSRoute` | Defines application routing rules |

{/* TODO: Add Gateway API implementation guide covering:
  - Installing Gateway API CRDs on E2E Kubernetes
  - Choosing a Gateway implementation (e.g., Envoy Gateway, Istio)
  - Creating a GatewayClass resource
  - Creating a Gateway resource with listeners (HTTP and HTTPS)
  - Creating HTTPRoute resources for host-based routing
  - Creating HTTPRoute resources for path-based routing
  - TLS configuration using cert-manager
  - Verifying Gateway API routing
  - Migration considerations from Ingress to Gateway API
*/}


---