HTTP Routes

HTTPRoute is the standard way to publish HTTP traffic on Kupe Cloud.

Create the route in your workload namespace, point it at a Service, and attach it to the shared external-gateway in kube-system. Kupe runs the gateway layer for you, so you do not need a separate ingress controller or a dedicated gateway per app.

Minimal example

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web
  namespace: web
spec:
  parentRefs:
    - name: external-gateway
      namespace: kube-system
  hostnames:
    - web.<tenant>.kupe.cloud
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: web
          port: 80

What matters in this spec

parentRefs attaches the route to the shared public gateway
hostnames defines the public hostname for the application
backendRefs points at the Service that receives traffic
the route should live in the same namespace as the workload it exposes

For a custom domain instead of a *.kupe.cloud hostname, keep the same route model and follow Custom Domains.

Common patterns

Route an entire hostname to one service

This is the most common pattern. One hostname maps to one backend service.

Split traffic by path

rules:
  - matches:
      - path:
          type: PathPrefix
          value: /api
    backendRefs:
      - name: api
        port: 80
  - matches:
      - path:
          type: PathPrefix
          value: /
    backendRefs:
      - name: web
        port: 80

Reuse the same route model for custom domains

The only real change is the hostname:

hostnames:
  - app.example.com

The gateway attachment and backend service model stay the same.

Validation

After applying the route, check:

the route exists in the expected namespace
the backend Service is present and healthy
the route conditions show Accepted=True
the route conditions show ResolvedRefs=True
requests reach the expected backend

Useful checks:

kubectl get httproute -n <namespace>
kubectl describe httproute <name> -n <namespace>
kubectl get svc,pods -n <namespace>

If the route is externally exposed, also test the public URL directly after it becomes ready.

Common first-time mistakes

using the wrong gateway name or namespace
pointing backendRefs at a Service that does not exist
using the wrong service port
exposing the route before the workload is actually ready
assuming custom domains need a different route type