Install
Octopus ships as a single container image (ghcr.io/xraph/octopus) and a Helm chart published to an
OCI registry. The same binary serves traffic and, when kubernetes.enabled is set, runs the
in-process operator. This page covers installing the gateway, the Octopus CRDs, and the upstream
Gateway API CRDs.
Prerequisites01
A Kubernetes cluster and
kubectlconfigured for it.Helm 3.8+ (OCI support is on by default) if you use the chart.
The upstream Gateway API CRDs (
gateway.networking.k8s.io) installed separately — only if you plan to useHTTPRoute,GRPCRoute,Gateway, orReferenceGrant. Octopus does not ship those CRDs; it reconciles them but the schemas come from the Gateway API release. The Octopus CRDs (gateway.octopus.io) are separate and are installed below.
Install the gateway02
helm install octopus oci://ghcr.io/xraph/charts/octopus \
--namespace octopus --create-namespacekubectl apply -f deploy/kubernetes/octopus.yamlInstall the Octopus CRDs03
The Octopus CRDs live in the gateway.octopus.io API group (OctopusGateway, OctopusRoute,
OctopusUpstream, OctopusPolicy). Install them one of two ways.
Generate from the CLI
The octopus crd command prints all four CRDs as a single multi-document YAML stream:
octopus crd | kubectl apply -f -This is the source of truth — the YAML is generated directly from the Rust CRD types.
Or apply the vendored bundle
The chart vendors the same CRDs at deploy/helm/octopus/crds/octopus-crds.yaml:
kubectl apply -f deploy/helm/octopus/crds/octopus-crds.yamlHelm installs files under a chart's crds/ directory automatically on first install, but it does
not upgrade or delete them on later helm upgrade/helm uninstall. Re-apply the bundle (or
re-run octopus crd | kubectl apply -f -) when CRDs change.
Install the upstream Gateway API CRDs04
If you use HTTPRoute, GRPCRoute, Gateway, or ReferenceGrant, install the upstream Gateway API
CRDs from the Gateway API project release (they are not part of Octopus):
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/<version>/standard-install.yamlOctopus reconciles Gateway/HTTPRoute/GRPCRoute (gateway.networking.k8s.io/v1) and
ReferenceGrant (gateway.networking.k8s.io/v1beta1). If these CRDs are absent, the operator's
Gateway API watchers have nothing to watch — the Octopus CRDs still work on their own.
Enable the operator05
Installing the gateway does not by itself start the operator. Set kubernetes.enabled: true in the
gateway config (the config block of the chart, or the mounted config.yaml) to run the in-process
controller. See Operator for what it watches and how reconciliation
works.
kubernetes:
enabled: true
gateway_class: octopus