Core Concepts

Every resource in Apoxy is a Kubernetes-style object you apply with apoxy apply -f. Here's what each one does.

Concept	What it is
Gateway	Edge deployment unit - Envoy accepting inbound traffic
Route	Traffic rule - matches requests and sends them to backends
Backend	Upstream service - where traffic actually goes
Service	JS/TS workers running on the Apoxy edge
DomainRecord	DNS zone + TLS - maps real domains to Gateways or TunnelNodes directly
TunnelNode	QUIC overlay - connects remote services without VPNs

Gateways

A Proxy-Gateway pair is the edge deployment unit - an Envoy Proxy deployment that accepts incoming traffic and routes it to backends.

Every project comes with a default Gateway and Proxy that listens on ports 80 and 443. In most cases, you don't need to create your own - just attach routes to the default.

Behind the scenes, two linked resources make up a gateway:

A Proxy (core.apoxy.dev/v1alpha2) configures where and how the gateway runs - provider, shutdown behavior, and telemetry.
A Gateway (gateway.apoxy.dev/v1) defines what traffic it accepts - listeners, TLS, and protocols. Routes attach to the Gateway via parentRefs.

The default Gateway is pre-configured with HTTP (port 80) and HTTPS (port 443) listeners on the Apoxy cloud provider.

Default Gateway

Most workflows only need to create Backends and Routes that reference the default Gateway via parentRefs. You only need to create custom Gateway and Proxy resources for advanced use cases like dedicated ports, custom TLS configurations, or self-hosted deployments.

See the Routing traffic guide for a hands-on walkthrough.

Routing

Apoxy uses Kubernetes Gateway API for all traffic routing. Routes live under the gateway.apoxy.dev/v1 API group - the spec is identical to the upstream gateway.networking.k8s.io types, but hosted on Apoxy's per-project apiserver. This means you get the same Gateway, HTTPRoute, GRPCRoute, TLSRoute, TCPRoute, and UDPRoute resources you already know, with the same fields and semantics, under an Apoxy-specific API group that scopes them to your project.

If you're using the Kubernetes mirror controller (apoxy k8s install --mirror gateway), you can author resources with the standard gateway.networking.k8s.io group in your cluster and the controller mirrors them into Apoxy's API automatically.

$httproute.yamlYAML

apiVersion: gateway.apoxy.dev/v1
kind: HTTPRoute
metadata:
  name: api-route
spec:
  parentRefs:
    - kind: Gateway
      name: default
  hostnames:
    - api.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1
      backendRefs:
        - kind: Backend
          name: api-backend
          port: 8080

Route types: HTTPRoute, GRPCRoute, TLSRoute, TCPRoute, UDPRoute. Match on path, hostname, headers, query params, or method. Actions include redirects, header modification, traffic mirroring, weighted backends for canary deploys, and direct responses.

Routes are evaluated in order. First match wins. Multiple routes on the same gateway coexist.

See the Routing traffic guide for a hands-on walkthrough.

Backends

A Backend defines an upstream service that routes send traffic to.

$backend.yamlYAML

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

Endpoints can be FQDN-based (Apoxy resolves via DNS) or IP-based (static addresses). Protocol options: plain, tls, h2, h2c.

Apoxy can actively health-check backends with HTTP or TCP probes, and automatically removes unhealthy endpoints from the load balancing pool.

Services

Services run your JavaScript/TypeScript workers on the Apoxy edge. Code ships as a bundle - an OCI artifact containing your modules - and the Service points at it by digest:

$service.yamlYAML

apiVersion: compute.apoxy.dev/v1alpha1
kind: Service
metadata:
  name: hello
spec:
  template:
    spec:
      backend:
        protocol: http1
  source:
    oci:
      repo: registry.example.com/acme/hello
      digest: sha256:0b7d...

Workers export the standard fetch handler and make outbound requests with plain fetch() - egress is mediated by EgressGateway policy. Secrets bind in as environment variables from a write-only SecretStore.

apoxy deploy builds, pushes, and applies in one step. Every source change mints an immutable ServiceRevision; traffic shifts make-before-break, and pinning spec.liveRevision rolls back. Routes send traffic to a Service the same way they do to a Backend - via backendRefs.

See the Deploying compute Services guide for the full workflow.

Domains & TLS

DomainZone represents your DNS zone. DomainRecord defines individual records inside it. Point your registrar's nameservers to Apoxy, and the platform becomes authoritative for the zone.

$example.yamlYAML

apiVersion: core.apoxy.dev/v1alpha3
kind: DomainRecord
metadata:
  name: api-example-com
spec:
  zone: example-com
  name: api.example.com
  ttl: 300
  target:
    ref:
      group: gateway.apoxy.dev
      kind: Gateway
      name: default

When a DomainRecord targets a Gateway via ref, Apoxy automatically provisions a TLS certificate via Let's Encrypt ACME. Certificates renew before expiry without intervention. Supports A, AAAA, CNAME, TXT, MX, NS, and more.

Tunnels

Tunnels create a QUIC/HTTP3 overlay that connects remote services into your gateway mesh. No open ports, no VPN management - run a tunnel client and get bidirectional traffic.

Customer

Clients

Public traffic to your domain

demo.your-zone.apoxy.app

HTTP · HTTPS · TCP · UDP

Any port with dedicated Proxy/Gateway

Apoxy Edge · multi-region

Edge PoP

us-west · eu-central + more

Envoy Gateway

configured via Gateway API

Gateway

HTTPRoute

Backend → my-tunnel.tun.apoxy.net

Tunnel Relay

QUIC / ICX · JWT-validated

QUIC · HTTP/3

TLS 1.3

Your network

Tunnel agent

kernel · TUN device

user · gVisor netstack

$ apoxy tunnel run my-tunnel --auto

Local service

SOCKS5 / HTTP proxy

:8080

Data plane - pick one

CONNECT-IP

Proxied IP over MASQUE, RFC 9484. Unprivileged, runs anywhere QUIC does.

ICX

Encrypted frames based on Google's PSP, kernel fast path.

Aggressive failure detection

BFD-lite (RFC 5880, simplified) on every path. Expiry fails over to the next relay. Admin Down drains gracefully.

Addressable ULA endpoint

Each connection gets an IPv6 address in your project's ULA prefix, DNS-resolvable as my-tunnel.tun.apoxy.net.

Egress too — outbound traffic rides the same tunnel: TAP mode (TUN device, transparent) or via SOCKS5 / HTTP proxy in user mode. egressGateway: enabled

FIG. 01Tunnel system flow - client to edge to your network

A TunnelNode declares the customer-side endpoint - one per agent you run:

$tunnel.yamlYAML

apiVersion: core.apoxy.dev/v1alpha
kind: TunnelNode
metadata:
  name: office-link
spec:
  egressGateway:
    enabled: true

Each TunnelNode gets its own IPv6 ULA prefix. Services behind a tunnel are DNS-resolvable - point HTTPRoute at a Backend with a tunnel-connected address and traffic flows through transparently.

Two client modes:

kernel TUN device + iptables, highest performance.
user gVisor netstack, works in containers without elevated privileges.

See the Basic tunnels guide to get started.

Observability

All telemetry flows through an OpenTelemetry Collector. Send data to Datadog, Grafana Cloud, Axiom, or any OTLP-compatible endpoint.

Access logs - Per-request detail with customizable format (Envoy command operators).
Content logging - Capture request/response bodies, filtered by content type or path.
Distributed tracing - Custom tags, configurable sampling, any tracing backend.
Proxy metrics - Request rates, latency percentiles (p50/p95/p99), upstream health, circuit breaker state.

Configure sinks via CloudMonitoringIntegration objects or a custom OTel collector config.