Routing traffic

Apoxy uses Kubernetes Gateway API resources as the control surface for routing. The resources live under the gateway.apoxy.dev/v1 API group — the spec is identical to the upstream gateway.networking.k8s.io types, hosted on Apoxy's per-project apiserver. This guide walks through the core workflow: create a Backend and route, attach them to the default Gateway, and confirm everything is wired up.

The model

• Every project comes with a default Gateway that listens on ports 80 (HTTP) and 443 (HTTPS).
• Routes attach to the Gateway through parentRefs and define how requests get matched and forwarded.
• Backends define upstream services that routes forward traffic to.
• Apoxy resolves these resources and programs the backplane to route traffic accordingly.

Create a Backend

A Backend defines the upstream service Apoxy connects to — either by FQDN or IP address:

apiVersion: core.apoxy.dev/v1alpha2
kind: Backend
metadata:
  name: api-backend
spec:
  endpoints:
  - fqdn: api.internal.example.com

The Backend must exist before a route can resolve its reference. Apply the Backend before or alongside the route.

For details on endpoint types, protocols, and health checking, see the Backends reference.

Attach an HTTPRoute

Routes bind to Gateways through parentRefs. Create a route that matches a hostname and forwards to a backend:

apiVersion: gateway.apoxy.dev/v1
kind: HTTPRoute
metadata:
  name: api-route
spec:
  parentRefs:
  - name: default
  hostnames:
  - api.your-org.apoxy.app
  rules:
  - backendRefs:
    - kind: Backend
      name: api-backend
      port: 8080

Apply both:

apoxy apply -f backend.yaml -f route.yaml

Verify the attachment

Use apoxy gateway get to confirm the route attached:

apoxy gateway get default

This prints the Gateway object along with a summary of all attached routes. You should see api-route listed as an attached HTTPRoute.

You can also inspect routes directly:

apoxy gateway routes list
apoxy gateway routes get http/api-route

The declarative workflow

The recommended pattern for managing routes:

1. Author Backend and route YAML in source control.
2. Apply with apoxy apply -f.
3. Confirm with apoxy gateway get default that attachments and route counts match your intent.
4. Iterate on parentRefs, hostnames, or backend references as needed.

This keeps configuration reviewable and repeatable across environments.

Route types

The Gateway API supports several route types depending on the protocol:

• HTTPRoute — HTTP/HTTPS traffic with path, header, and query matching.
• TCPRoute — Raw TCP forwarding.
• TLSRoute — TLS-terminated or passthrough routing.

Each route type uses the same parentRefs attachment model but offers different matching and forwarding capabilities.

Common attachment problems

When a route doesn't appear where you expect, check these:

• Wrong Gateway name — the route's parentRefs must reference an existing Gateway by name. Use default for the project's default Gateway.
• Kind mismatch — a TCPRoute won't attach to a listener expecting HTTP.
• Hostname mismatch — if the Gateway listener restricts hostnames, the route's hostnames must overlap.
• Listener protocol — the route type must match the listener's protocol.

Inspect both the route spec and apoxy gateway get default to see what's attached and what isn't.