# Routing traffic

> Attach routes to the default Gateway and verify traffic flow using the Gateway API.

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:

```yaml
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](/docs/reference/core/backends.md).

## Attach an HTTPRoute

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

```yaml
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:

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

## Verify the attachment

Use `apoxy gateway get` to confirm the route attached:

```bash
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:

```bash
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.