# Octopus > Documentation for Octopus, version 1.x. > Every entry links to the page's markdown source. Repository: https://github.com/xraph/octopus Site: https://www.xraph.com/docs/octopus ## Pages - [FARP Registration API](https://www.xraph.com/docs/octopus/api-reference/farp.md): The HTTP API services use to register with the Octopus gateway, send heartbeats, deregister, and read the federated schemas. - [API Reference](https://www.xraph.com/docs/octopus/api-reference.md): The HTTP APIs the Octopus gateway exposes — the Admin REST API, the FARP service-registration API, and the health and metrics endpoints. - [Codegen](https://www.xraph.com/docs/octopus/cli/codegen.md): octopus gen — turn OpenAPI, AsyncAPI, and FARP service specs into Octopus config fragments, an intermediate JSON schema, and a fully-typed TypeScript client with TanStack Query hooks. - [CLI](https://www.xraph.com/docs/octopus/cli.md): The octopus command-line interface — serve, validate, gen, crd, and version, with multi-file and directory configuration loading. - [Architecture](https://www.xraph.com/docs/octopus/concepts/architecture.md): Understanding the architecture and design of Octopus API Gateway - [Circuit Breaker](https://www.xraph.com/docs/octopus/concepts/circuit-breaker.md): Protect services from cascading failures - [FARP Protocol](https://www.xraph.com/docs/octopus/concepts/farp.md): Automatic service discovery and route generation - [Health Checks](https://www.xraph.com/docs/octopus/concepts/health-checks.md): Monitor and manage upstream health - [Core](https://www.xraph.com/docs/octopus/concepts.md): Understand the fundamental concepts of Octopus API Gateway - [Load Balancing](https://www.xraph.com/docs/octopus/concepts/load-balancing.md): Distribute traffic across backend instances - [Middleware](https://www.xraph.com/docs/octopus/concepts/middleware.md): Process requests and responses with middleware - [Plugins](https://www.xraph.com/docs/octopus/concepts/plugins.md): Extend Octopus with plugins - [Request Lifecycle](https://www.xraph.com/docs/octopus/concepts/request-lifecycle.md): The path a request takes through Octopus — listener and TLS, protocol detection, routing, the middleware chain, upstream proxying, and the response — grounded in the runtime source. - [Routing](https://www.xraph.com/docs/octopus/concepts/routing.md): How Octopus routes requests to upstream services - [Service Discovery](https://www.xraph.com/docs/octopus/concepts/service-discovery.md): The conceptual model of how Octopus learns about backends — static upstreams versus discovered ones, and the FARP discover → fetch-schema → generate-routes → reconcile loop. - [Admin](https://www.xraph.com/docs/octopus/configuration/admin.md): The admin section — protecting the admin dashboard with an auth provider and an IP allowlist. - [Authentication & authorization](https://www.xraph.com/docs/octopus/configuration/auth.md): The auth_providers, auth, authz, and global cors schema — JWT, OIDC, API key, forward auth, and mTLS providers, global enforcement, and the Rhai/OPA authorization engines. - [FARP & discovery](https://www.xraph.com/docs/octopus/configuration/farp.md): The farp section — service discovery and auto-routing, with mDNS, DNS, Consul, and Kubernetes discovery backends. - [Gateway](https://www.xraph.com/docs/octopus/configuration/gateway.md): The gateway section — listen address, worker threads, request and shutdown timeouts, body size limits, internal route prefix, SNI enforcement, health probes, and response compression. - [gRPC](https://www.xraph.com/docs/octopus/configuration/grpc.md): The grpc section — gRPC and gRPC-Web proxying, reflection, deadline propagation, and explicit service-to-upstream mapping. - [Configuration](https://www.xraph.com/docs/octopus/configuration.md): Complete configuration reference for the Octopus API Gateway — file formats, multi-file and directory merging, environment variable substitution, validation, and the top-level configuration schema. - [Kubernetes](https://www.xraph.com/docs/octopus/configuration/kubernetes.md): The kubernetes section — the in-process Gateway API controller, GatewayClass, watched namespaces, leader election, and operator-managed TLS. - [Middleware](https://www.xraph.com/docs/octopus/configuration/middleware.md): How middleware is configured in Octopus — through typed configuration fields and the plugin system, not a free-form middleware list. - [Observability](https://www.xraph.com/docs/octopus/configuration/observability.md): The observability section — logging, Prometheus metrics, and distributed tracing. - [Routes](https://www.xraph.com/docs/octopus/configuration/routes.md): The routes section — path matching, method filtering, prefix rewriting, priority, per-route authentication and authorization, per-route timeout, rate limiting, and CORS. - [TLS](https://www.xraph.com/docs/octopus/configuration/tls.md): The gateway.tls section — certificate and key files, mutual TLS, minimum TLS version, and certificate hot reload. - [Upstreams](https://www.xraph.com/docs/octopus/configuration/upstreams.md): The upstreams section — backend services, their instances, load-balancing policy, active health checks, and circuit breakers. - [Docker](https://www.xraph.com/docs/octopus/deployment/docker.md): Run the published Octopus container image, mount a configuration file, substitute environment variables at startup, and understand the container's ports and health check. - [Graceful shutdown](https://www.xraph.com/docs/octopus/deployment/graceful-shutdown.md): How Octopus drains in-flight requests on SIGTERM — readiness flips to 503, it waits gateway.pre_stop_delay so deregistration propagates, then drains within gateway.shutdown_timeout — and how to size terminationGracePeriodSeconds in Kubernetes. - [Deployment](https://www.xraph.com/docs/octopus/deployment.md): Ways to run Octopus in production — the published container image, Kubernetes, or a binary built from source — and the operational topics that matter once it is live. - [Kubernetes](https://www.xraph.com/docs/octopus/deployment/kubernetes.md): Deploying Octopus to Kubernetes — a short overview that points to the full Kubernetes section for install, the in-process operator, Helm, probes, and EndpointSlice discovery. - [Production checklist](https://www.xraph.com/docs/octopus/deployment/production-checklist.md): A practical pre-flight checklist for running Octopus in production — TLS, authentication, health probes, resource limits, graceful drain, and metrics scraping — grounded in features that actually work, with notes where configuration is known to be inert. - [Scaling](https://www.xraph.com/docs/octopus/deployment/scaling.md): Scaling Octopus — vertical scaling with gateway.workers, horizontal scaling across replicas, the Helm HorizontalPodAutoscaler, and the shared state store you need when running more than one instance. - [Discovery backends](https://www.xraph.com/docs/octopus/farp/backends.md): Configure FARP's discovery backends — mDNS, Consul, DNS, and Kubernetes — under farp.discovery.backends, each tagged by type. - [Service Discovery & FARP](https://www.xraph.com/docs/octopus/farp.md): FARP — the Forge API Gateway Registration Protocol — lets services publish their own schemas so Octopus generates routes automatically, backed by mDNS, Consul, DNS, and Kubernetes discovery. - [Schema federation](https://www.xraph.com/docs/octopus/farp/schema-federation.md): How FARP turns published service schemas into gateway routes and a single federated API surface — which schema formats are supported, and how routes are reconciled on change. - [Build Your First Gateway](https://www.xraph.com/docs/octopus/first-gateway.md): A complete walkthrough that routes traffic to multiple microservices with load balancing, health checks, authentication, and observability. - [TLS with cert-manager](https://www.xraph.com/docs/octopus/guides/cert-manager-tls.md): Terminate TLS on the operator path by sourcing certificates from your Gateway listeners' Secrets, issued and renewed by cert-manager and hot-swapped without a restart. - [Enable mutual TLS](https://www.xraph.com/docs/octopus/guides/enable-mtls.md): Terminate TLS with client-certificate verification at the listener, then turn the verified certificate CN into an authenticated principal with roles. - [Expose a gRPC service](https://www.xraph.com/docs/octopus/guides/expose-grpc.md): Proxy a gRPC backend transparently over HTTP/2 with a normal Octopus route — no proto files, no transcoding, just a route pointed at your service. - [Auto-discover services with FARP](https://www.xraph.com/docs/octopus/guides/farp-auto-discovery.md): Turn on FARP so services publish their own OpenAPI schemas and Octopus generates routes for them automatically — with a Kubernetes EndpointSlice backend (and a local mDNS option). - [Generate a TypeScript client](https://www.xraph.com/docs/octopus/guides/generate-typescript-client.md): Use octopus gen to read a service's OpenAPI spec and produce a typed TypeScript client with TanStack Query hooks, plus optional Octopus config fragments. - [Guides](https://www.xraph.com/docs/octopus/guides.md): End-to-end, task-focused walkthroughs for Octopus — securing APIs, terminating TLS, proxying gRPC, running on Kubernetes, auto-discovering services, generating clients, and wiring observability. - [Route with the Gateway API](https://www.xraph.com/docs/octopus/guides/kubernetes-gateway-api.md): Run the in-process operator and route traffic through standard Kubernetes Gateway API resources — GatewayClass, Gateway, and HTTPRoute — using only the fields Octopus actually honors. - [Set up observability](https://www.xraph.com/docs/octopus/guides/observability-setup.md): Wire the things that actually work today — Prometheus metrics, Kubernetes health probes, graceful drain, and structured logging — and understand why distributed tracing is left off. - [Protect the admin dashboard](https://www.xraph.com/docs/octopus/guides/protect-admin.md): Lock down the built-in admin dashboard and its JSON API by pointing admin.auth_provider at a configured auth provider. - [Secure an API with JWT](https://www.xraph.com/docs/octopus/guides/secure-api-jwt.md): An end-to-end walkthrough — declare a JWT auth provider, enforce authentication globally, exempt public paths, and gate routes by role and scope. - [Introduction](https://www.xraph.com/docs/octopus.md): Octopus is a high-performance, extensible API gateway written in Rust, with schema-driven service discovery (FARP) and first-class Kubernetes support. - [Installation](https://www.xraph.com/docs/octopus/installation.md): Install Octopus API Gateway with Docker, from source, or on Kubernetes. - [Discovery](https://www.xraph.com/docs/octopus/kubernetes/discovery.md): In-cluster service discovery from the discovery.k8s.io/v1 EndpointSlice API, the RBAC it needs, namespace scoping, include_not_ready, and the legacy Endpoints fallback. - [Gateway API](https://www.xraph.com/docs/octopus/kubernetes/gateway-api.md): How Octopus reconciles the standard Kubernetes Gateway API — GatewayClass, Gateway listeners, HTTPRoute and GRPCRoute matches/filters/backendRefs, and ReferenceGrant for cross-namespace backends — and exactly which fields are honored. - [Helm chart](https://www.xraph.com/docs/octopus/kubernetes/helm-chart.md): The Octopus Helm chart values reference — image, replicas, resources, probes, RBAC/serviceAccount, autoscaling, PodDisruptionBudget, ServiceMonitor, and the embedded gateway config. - [Kubernetes](https://www.xraph.com/docs/octopus/kubernetes.md): Run Octopus as a Kubernetes-native gateway — an in-process operator that programs the router from the Gateway API and Octopus CRDs, with health probes, graceful drain, EndpointSlice discovery, and cert-manager TLS. - [Install](https://www.xraph.com/docs/octopus/kubernetes/install.md): Install Octopus on Kubernetes with the Helm OCI chart or raw manifests, install the Octopus CRDs, and add the upstream Gateway API CRDs when using HTTPRoute/GRPCRoute. - [Octopus CRDs](https://www.xraph.com/docs/octopus/kubernetes/octopus-crds.md): The OctopusGateway, OctopusRoute, OctopusUpstream, and OctopusPolicy custom resources — their spec fields, example manifests, and how OctopusPolicy attaches as a GEP-713 policy overlay. - [Operator](https://www.xraph.com/docs/octopus/kubernetes/operator.md): The in-process Octopus operator — what it watches, the reconcile → merge → apply pipeline into the live router, source precedence, namespace scoping, and RBAC. - [Probes & drain](https://www.xraph.com/docs/octopus/kubernetes/probes-and-drain.md): How Octopus serves /livez, /readyz, and /startupz, how to map them to Kubernetes probes, and how pre_stop_delay and shutdown_timeout drive a zero-drop graceful drain. - [TLS & cert-manager](https://www.xraph.com/docs/octopus/kubernetes/tls-cert-manager.md): Operator-managed TLS termination — sourcing certificates from HTTPS Gateway listener Secrets (hot-reloaded), SNI multi-cert selection, cross-namespace Secret access via ReferenceGrant, and a cert-manager Certificate example. - [Virtual Gateways](https://www.xraph.com/docs/octopus/kubernetes/virtual-gateways.md): Group endpoints under domains with a "gateway-in-a-gateway" — one OctopusGateway per logical surface (api.*, app.*, per-tenant), with inherited policy, convention path-split, per-gateway isolation, and a tiered shared/dedicated deployment model that always stays a single hop. - [Authentication gateway](https://www.xraph.com/docs/octopus/middleware/authentication.md): The global auth/authz middleware — when it activates, how it selects a provider, the headers it injects, and its error responses. - [Catalogue](https://www.xraph.com/docs/octopus/middleware/catalogue.md): Reference for every built-in middleware that is implemented but not exposed through gateway configuration today. - [Compression](https://www.xraph.com/docs/octopus/middleware/compression.md): Response compression (brotli, zstd, gzip) — the one body-shaping middleware wired to gateway configuration. - [CORS](https://www.xraph.com/docs/octopus/middleware/cors.md): The CORS middleware and configuration schema — a global policy plus per-route overrides, enforced in the gateway's request chain. - [Middleware](https://www.xraph.com/docs/octopus/middleware.md): How Octopus assembles its request-processing chain, what runs today, and the full catalogue of built-in middleware. - [Rate limiting](https://www.xraph.com/docs/octopus/middleware/rate-limiting.md): Per-route rate limiting (enforced), plus the builder-only token-bucket limiter and the distributed, state-backed variant. - [Admin API](https://www.xraph.com/docs/octopus/observability/admin-api.md): The /admin/api JSON REST reference, grounded in the Octopus admin route table and response models. - [Admin dashboard](https://www.xraph.com/docs/octopus/observability/admin-dashboard.md): The built-in Octopus admin dashboard — what it serves, where it lives, and how to protect it. - [Health probes](https://www.xraph.com/docs/octopus/observability/health-probes.md): Octopus serves /livez, /readyz, and /startupz on the gateway listen port, with drain-aware readiness for zero-drop shutdowns. - [Observability](https://www.xraph.com/docs/octopus/observability.md): How Octopus exposes metrics, logging, health probes, and an admin dashboard — and what is wired today. - [Logging](https://www.xraph.com/docs/octopus/observability/logging.md): How Octopus initializes logging — levels, JSON/text format, and the precedence of config vs the --log-level flag. - [Metrics](https://www.xraph.com/docs/octopus/observability/metrics.md): The Prometheus /metrics endpoint, the exact metric names Octopus emits, and how to scrape them. - [Tracing](https://www.xraph.com/docs/octopus/observability/tracing.md): Distributed tracing via OpenTelemetry — export the gateway's spans to an OTLP collector behind observability.tracing. - [Built-in Plugins](https://www.xraph.com/docs/octopus/plugins/built-in.md): The honest inventory of plugins that ship with Octopus today — there are no bundled plugin implementations yet, and the capabilities you might expect as plugins exist as first-class middleware and auth providers instead. - [Plugins & Scripting](https://www.xraph.com/docs/octopus/plugins.md): How the Octopus plugin system is structured — the plugin trait and lifecycle hooks, static vs dynamic loading, the PluginConfig array, priority ordering, and the honest status of how plugins integrate into request handling today. - [Scripting](https://www.xraph.com/docs/octopus/plugins/scripting.md): The embedded Rhai scripting engine in Octopus — how scripts attach (script plugins via config.plugins, and convention host-resolution), the context API exposed to scripts, execution sandboxing, timeouts, and AST caching. Lua, JavaScript, and WebAssembly are planned. - [Writing a Plugin](https://www.xraph.com/docs/octopus/plugins/writing-plugins.md): Author a plugin against octopus-plugin-api — implement the core Plugin trait, add a capability trait such as RequestInterceptor, return continue/short-circuit/abort actions, and package it as a static or dynamic plugin. - [GraphQL](https://www.xraph.com/docs/octopus/protocols/graphql.md): Run a GraphQL endpoint through the gateway with parsing, depth/complexity limits, introspection control, and a built-in GraphiQL IDE. - [gRPC](https://www.xraph.com/docs/octopus/protocols/grpc.md): Transparent gRPC proxying over HTTP/2 — what is forwarded, and where streaming and reflection stop short. - [HTTP/1.1 & HTTP/2](https://www.xraph.com/docs/octopus/protocols/http.md): The default reverse-proxy path — auto-negotiated HTTP/1.1 and HTTP/2 with connection pooling. - [Protocols](https://www.xraph.com/docs/octopus/protocols.md): How Octopus detects and proxies HTTP, gRPC, WebSocket, SSE, and GraphQL traffic. - [Server-Sent Events (SSE)](https://www.xraph.com/docs/octopus/protocols/sse.md): Streaming SSE responses proxied to the client without buffering. - [WebSocket](https://www.xraph.com/docs/octopus/protocols/websocket.md): RFC 6455 upgrade detection and the bidirectional frame proxy. - [Quick Start](https://www.xraph.com/docs/octopus/quick-start.md): Get Octopus API Gateway up and running in a few minutes. - [API key](https://www.xraph.com/docs/octopus/security/api-key.md): The api_key auth provider — match a key from a header or query parameter against a static key list, attaching per-key scopes. - [Authentication](https://www.xraph.com/docs/octopus/security/authentication.md): How Octopus selects an auth provider per route, the global default provider and skip rules, the per-request authentication flow, and the validated-token cache. - [Authorization](https://www.xraph.com/docs/octopus/security/authorization.md): Role and scope checks, per-route Rhai expressions, and global authorization rules evaluated by the embedded Rhai engine or an external OPA server. - [Forward auth](https://www.xraph.com/docs/octopus/security/forward-auth.md): The forward_auth provider — delegate the authentication decision to an external HTTP service, deriving the principal from its response headers. - [Security](https://www.xraph.com/docs/octopus/security.md): Authentication, authorization, and TLS in Octopus — named auth providers, per-route enforcement, role/scope and policy-based authorization, and TLS termination with mutual TLS. - [JWT](https://www.xraph.com/docs/octopus/security/jwt.md): The jwt auth provider — validate bearer tokens against a static HMAC secret or RSA/ECDSA public key, checking issuer, audience, and expiry. - [mTLS](https://www.xraph.com/docs/octopus/security/mtls.md): The mtls auth provider — derive the principal from a verified client certificate's Common Name and map CN patterns to roles. - [OIDC](https://www.xraph.com/docs/octopus/security/oidc.md): The oidc auth provider — OpenID Connect discovery, background JWKS refresh, and token validation against published keys with required-scope enforcement. - [TLS](https://www.xraph.com/docs/octopus/security/tls.md): TLS termination on the listener, minimum TLS version, mutual TLS with client-certificate verification, and certificate hot reload — including the Kubernetes operator path. - [State](https://www.xraph.com/docs/octopus/state.md): Octopus keeps shared runtime state — rate-limit counters, caches, sessions, and circuit-breaker state — in a pluggable store with in-memory, Redis, Postgres, and hybrid backends.