Feat/expand migration examples 596

content/docs/envoy/main/migrate/examples/_index.md

@@ -14,3 +14,24 @@ Each example walks through the following steps:
 4. Applying them to your cluster.
 
 Pick the example that matches your use case, or work through them all to get familiar with the migration workflow.
+
+{{< cards >}}
+  {{< card link="basic" title="Basic Ingress" >}}
+  {{< card link="session-affinity" title="Session Affinity" >}}
+  {{< card link="rate-limiting" title="Rate Limiting" >}}
+  {{< card link="basic-auth" title="Basic Auth" >}}
+  {{< card link="jwt-auth" title="JWT Authentication" >}}
+  {{< card link="api-key-auth" title="API Key Authentication" >}}
+  {{< card link="oidc-auth" title="OIDC Authentication" >}}
+  {{< card link="header-modifiers" title="Header Modifiers" >}}
+  {{< card link="timeouts" title="Timeouts" >}}
+  {{< card link="url-rewriting" title="URL Rewriting" >}}
+  {{< card link="request-buffering" title="Request Buffering" >}}
+  {{< card link="traffic-mirroring" title="Traffic Mirroring" >}}
+  {{< card link="client-tls" title="Client TLS (mTLS)" >}}
+  {{< card link="cors" title="CORS" >}}
+  {{< card link="ssl-redirect" title="SSL Redirect" >}}
+  {{< card link="external-auth" title="External Auth" >}}
+  {{< card link="canary" title="Canary Release" >}}
+  {{< card link="backend-tls" title="Backend TLS" >}}
+{{< /cards >}}

content/docs/envoy/main/migrate/examples/api-key-auth.md

@@ -0,0 +1,82 @@
+---
+title: "API Key Authentication"
+weight: 33
+---
+
+In open-source NGINX, API key validation is often implemented using a `configuration-snippet` that checks for a specific header. kgateway provides a more robust, native `apiKeyAuth` mechanism in its `TrafficPolicy`.
+
+## Before: Ingress with API Key Check
+
+This is a common way to enforce API keys in NGINX Ingress:
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: api-key-demo
+  annotations:
+    nginx.ingress.kubernetes.io/configuration-snippet: |
+      if ($http_x_api_key = "") {
+        return 401;
+      }
+spec:
+  ingressClassName: nginx
+  rules:
+  - host: api.example.com
+    http:
+      paths:
+      - backend:
+          service:
+            name: httpbin
+            port:
+              number: 8000
+        path: /
+        pathType: Prefix
+```
+
+## Convert
+
+```bash
+ingress2gateway print --providers=ingress-nginx --emitter=kgateway \
+  --input-file api-key-ingress.yaml > api-key-kgateway.yaml
+```
+
+## After: TrafficPolicy with API Key Auth
+
+Instead of a raw if-statement, you define the source (e.g., header name) and a secret containing the valid keys.
+
+```yaml
+apiVersion: gateway.kgateway.dev/v1alpha1
+kind: TrafficPolicy
+metadata:
+  name: api-key-policy
+spec:
+  targetRefs:
+  - group: gateway.networking.k8s.io
+    kind: HTTPRoute
+    name: api-key-demo-api-example-com
+  apiKeyAuth:
+    keySources:
+    - header: X-API-Key
+    secretRef:
+      name: valid-api-keys
+```
+
+Each entry in the secret represents a valid client/key pair:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: valid-api-keys
+stringData:
+  client-a: "key-12345"
+  client-b: "key-67890"
+```
+
+## Apply and verify
+
+```bash
+kubectl apply -f api-key-kgateway.yaml
+kubectl get trafficpolicies
+```

content/docs/envoy/main/migrate/examples/basic-auth.md

@@ -0,0 +1,72 @@
+---
+title: "Basic Auth"
+weight: 31
+---
+
+This example demonstrates how to migrate NGINX-style basic authentication to kgateway. In NGINX, this is typically handled via `auth-type: basic` and a secret reference. In kgateway, we use a `TrafficPolicy` with the `basicAuth` configuration.
+
+## Before: Ingress with Basic Auth
+
+Here is a standard NGINX Ingress using basic authentication:
+
+```bash
+cat <<'EOF' > basic-auth-ingress.yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: basic-auth-demo
+  annotations:
+    nginx.ingress.kubernetes.io/auth-type: basic
+    nginx.ingress.kubernetes.io/auth-secret: my-htpasswd-secret
+    nginx.ingress.kubernetes.io/auth-realm: "Authentication Required"
+spec:
+  ingressClassName: nginx
+  rules:
+  - host: auth.example.com
+    http:
+      paths:
+      - backend:
+          service:
+            name: httpbin
+            port:
+              number: 8000
+        path: /
+        pathType: Prefix
+EOF
+```
+
+## Convert
+
+Run the conversion tool to generate the Gateway API resources:
+
+```bash
+ingress2gateway print --providers=ingress-nginx --emitter=kgateway \
+  --input-file basic-auth-ingress.yaml > basic-auth-kgateway.yaml
+```
+
+## After: TrafficPolicy with Basic Auth
+
+While the tool helps with the structure, you'll want to ensure your `TrafficPolicy` correctly points to the secret containing your credentials. The secret should contain your `htpasswd` data (typically in a key named `.htpasswd`).
+
+```yaml
+apiVersion: gateway.kgateway.dev/v1alpha1
+kind: TrafficPolicy
+metadata:
+  name: basic-auth-policy
+spec:
+  targetRefs:
+  - group: gateway.networking.k8s.io
+    kind: HTTPRoute
+    name: basic-auth-demo-auth-example-com
+  basicAuth:
+    secretRef:
+      name: my-htpasswd-secret
+      namespace: default
+```
+
+## Apply and verify
+
+```bash
+kubectl apply -f basic-auth-kgateway.yaml
+kubectl get trafficpolicies
+```

content/docs/envoy/main/migrate/examples/client-tls.md

@@ -0,0 +1,77 @@
+---
+title: "Client TLS (mTLS)"
+weight: 40
+---
+
+Mutual TLS (mTLS) allows the gateway to verify the identity of the client via a certificate. NGINX uses annotations like `auth-tls-verify-client`, whereas Gateway API handles this through `frontendValidation` on a Gateway listener.
+
+{{< callout type="warning" >}}
+`tls.frontendValidation` was added to Gateway API v1.3 and is still under the experimental channel in some builds. Make sure your cluster has the experimental Gateway API CRDs installed (`experimental-install.yaml`) before applying the manifest below.
+{{< /callout >}}
+
+## Before: Ingress with Client Verification
+
+An NGINX Ingress requiring a client certificate verified against a specific CA:
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: mtls-demo
+  annotations:
+    nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
+    nginx.ingress.kubernetes.io/auth-tls-secret: "default/client-ca"
+    nginx.ingress.kubernetes.io/auth-tls-verify-depth: "2"
+spec:
+  ingressClassName: nginx
+  rules:
+  - host: secure.example.com
+    http:
+      paths:
+      - backend:
+          service:
+            name: secret-svc
+            port:
+              number: 8443
+        path: /
+```
+
+## Convert
+
+```bash
+ingress2gateway print --providers=ingress-nginx --emitter=kgateway \
+  --input-file mtls-ingress.yaml > mtls-kgateway.yaml
+```
+
+## After: Gateway Listener with Frontend Validation
+
+In Gateway API, mTLS is configured on the `Gateway` resource's listener using `frontendValidation`.
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: gateway-mtls
+spec:
+  gatewayClassName: kgateway
+  listeners:
+  - name: https
+    hostname: secure.example.com
+    port: 443
+    protocol: HTTPS
+    tls:
+      mode: Terminate
+      certificateRefs:
+      - name: server-cert
+      frontendValidation:
+        caCertificateRefs:
+        - name: client-ca
+          kind: Secret
+```
+
+## Apply and verify
+
+```bash
+kubectl apply -f mtls-kgateway.yaml
+kubectl get gateways
+```

content/docs/envoy/main/migrate/examples/header-modifiers.md

@@ -0,0 +1,73 @@
+---
+title: "Header Modifiers"
+weight: 35
+---
+
+Whether you're adding security headers or passing custom metadata to your backends, NGINX uses the `add_header` directive or `configuration-snippet`. In Gateway API, this is a native feature of the `HTTPRoute` resource.
+
+## Before: Ingress with Custom Headers
+
+An NGINX Ingress adding a custom header to requests:
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: headers-demo
+  annotations:
+    nginx.ingress.kubernetes.io/configuration-snippet: |
+      more_set_headers "X-Environment: production";
+spec:
+  ingressClassName: nginx
+  rules:
+  - host: app.example.com
+    http:
+      paths:
+      - backend:
+          service:
+            name: web-backend
+            port:
+              number: 80
+        path: /
+        pathType: Prefix
+```
+
+## Convert
+
+```bash
+ingress2gateway print --providers=ingress-nginx --emitter=kgateway \
+  --input-file headers-ingress.yaml > headers-kgateway.yaml
+```
+
+## After: HTTPRoute with Header Filters
+
+The Gateway API `HTTPRoute` includes a `RequestHeaderModifier` filter to handle this natively:
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: headers-demo-app-example-com
+spec:
+  hostnames:
+  - app.example.com
+  parentRefs:
+  - name: nginx
+  rules:
+  - backendRefs:
+    - name: web-backend
+      port: 80
+    filters:
+    - type: RequestHeaderModifier
+      requestHeaderModifier:
+        add:
+        - name: X-Environment
+          value: production
+```
+
+## Apply and verify
+
+```bash
+kubectl apply -f headers-kgateway.yaml
+kubectl get httproutes
+```