# Core Concepts > The building blocks of the Apoxy platform — projects, gateways, routing, backends, edge functions, and more. 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 | |---|---| | **Project** | Isolation boundary — your org's namespace for all resources | | **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 | | **EdgeFunction** | Custom code at the edge — JS, WASM, or Go plugins | | **Domain** | DNS zone + TLS — maps real domains to gateways | | **Tunnel** | QUIC overlay — connects remote services without VPNs | | **Traffic Policy** | Rate limits, retries, timeouts, circuit breaking | | **Auth** | JWT, OIDC, basic auth, external authz at the gateway | | **Observability** | Access logs, tracing, metrics via OpenTelemetry | --- ## 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. ```bash title="terminal" 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. 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](/docs/guides/routing-traffic.md) 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. ```yaml title="example.yaml" 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](/docs/guides/routing-traffic.md) for a hands-on walkthrough. ## Backends A Backend defines an upstream service that routes send traffic to. ```yaml title="example.yaml" 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. ```yaml title="example.yaml" 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. ```yaml title="example.yaml" 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. ```yaml title="example.yaml" 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](/docs/guides/basic-tunnels.md) 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.