Core Concepts

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

Projects

A project is the isolation boundary for everything in Apoxy. Each project gets its own Kubernetes-style apiserver, its own resources, and its own data plane instances. Resources in one project are invisible to another.

apoxy project list          # See all projects you have access to
apoxy project use my-proj   # Switch to a project

When you apoxy apply a resource, it's scoped to the current project. Projects map to organizations or teams — they're both a security boundary and a logical grouping for billing.

Gateways

A gateway is the edge deployment unit — an Envoy instance 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.

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.

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.

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.

Edge Functions

EdgeFunctions run custom code at the edge. Deploy JavaScript, raw WebAssembly, or Go plugins — Apoxy handles compilation and versioning.

apiVersion: extensions.apoxy.dev/v1alpha2
kind: EdgeFunction
metadata:
  name: auth-check
spec:
  template:
    mode: filter
    code:
      jsSource:
        entrypoint: index.js
        assets:
          files:
            - path: index.js
              content: |
                export default {
                  async request(req) {
                    const token = req.headers.get("authorization");
                    if (!token) return new Response("Unauthorized", { status: 401 });
                    return null; // pass through to backend
                  }
                }
    runtime:
      timeout: 5s
      capabilities:
        fetchAPI: true
        kv: true

Two modes: filter (runs before the backend — transform headers, validate requests, log) and backend (replaces the origin entirely). Load code from inline assets, a Git repo, npm, or an OCI image.

Edge functions get access to the Fetch API, a key-value store, and full request/response inspection. Apoxy automatically creates EdgeFunctionRevision objects for rollback and version pinning.

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.

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 from Let's Encrypt. 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.

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 an HTTPRoute at a Backend with a tunnel-connected address and traffic flows through transparently.

Two client modes: kernel (TUN device + iptables, highest performance) and user (gVisor netstack + SOCKS5, works in containers without elevated privileges).

See the Basic tunnels guide to get started.

Traffic Policies

Policies attach to routes or gateways to control traffic behavior beyond routing rules.

• Rate limiting — Global (distributed state) or local (per-instance). Per second, minute, hour, or day. Shadow mode for testing.
• Circuit breaking — Eject unhealthy endpoints after configurable failure thresholds. Auto-recovery.
• Retries — Automatic resend on 5xx, connection timeout, or reset. Per-retry timeouts.
• Timeouts — Request, connection, and idle timeouts enforced at the gateway.
• Load balancing — Round-robin, least-request, ring-hash, maglev, random, or consistent-hash.
• Fault injection — Synthetic delays and errors for resilience testing.

Authentication & Authorization

Apoxy handles auth at the gateway so your backends don't have to.

• JWT — Validate tokens from one or more issuers. Apoxy fetches JWKS and verifies signatures, expiry, and claims.
• OIDC — Full OpenID Connect flow at the gateway. Handles token exchange, cookie signing, and redirects.
• Basic auth — Username/password via htpasswd format.
• External authz — Delegate to your own gRPC or HTTP auth service.
• CORS — Origin matching, allowed methods/headers, preflight caching.

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.