From dc8101d58296a3dc4d9b007191fc8b0dd257a7e4 Mon Sep 17 00:00:00 2001 From: as51340 Date: Thu, 27 Aug 2026 13:39:48 +0200 Subject: [PATCH] docs(ha-k8s): guide for using Istio as the Gateway API controller --- .../setup-ha-cluster-k8s.mdx | 95 ++++++++++++++++++- 1 file changed, 94 insertions(+), 1 deletion(-) diff --git a/pages/clustering/high-availability/setup-ha-cluster-k8s.mdx b/pages/clustering/high-availability/setup-ha-cluster-k8s.mdx index 35aa62b3a..0856e3b01 100644 --- a/pages/clustering/high-availability/setup-ha-cluster-k8s.mdx +++ b/pages/clustering/high-availability/setup-ha-cluster-k8s.mdx @@ -913,7 +913,7 @@ rendering, since the Gateway would then apply to nothing. Before enabling Gateway API in the chart, you need: -1. **A Gateway API controller** installed in your cluster. Examples include [Envoy Gateway](https://gateway.envoyproxy.io/), [Istio](https://istio.io/), [Cilium](https://cilium.io/), [Traefik](https://traefik.io/), and [Kong](https://konghq.com/). This guide uses Envoy Gateway as an example: +1. **A Gateway API controller** installed in your cluster. Examples include [Envoy Gateway](https://gateway.envoyproxy.io/), [Istio](https://istio.io/), [Cilium](https://cilium.io/), [Traefik](https://traefik.io/), and [Kong](https://konghq.com/). This guide uses Envoy Gateway as an example (for Istio, see [Use Istio as the Gateway API controller](#use-istio-as-the-gateway-api-controller)): ```bash helm install eg oci://docker.io/envoyproxy/gateway-helm --version v1.2.4 -n envoy-gateway-system --create-namespace @@ -1032,6 +1032,99 @@ A standalone Gateway manifest with these pre-configured listeners is available i **TCPRoute API version**: TCPRoute uses `v1alpha2`, which is the latest available API version. It is supported by Envoy Gateway and other major implementations but is not yet GA. Gateway and HTTPRoute are both GA (`v1`). +#### Use Istio as the Gateway API controller + +[Istio](https://istio.io/) implements the Gateway API and works with the HA +chart out of the box — only Istio's `base` and `istiod` Helm charts are needed, +because istiod deploys a gateway for every Gateway resource automatically (the +`istio/gateway` chart is not used), and the installation creates the `istio` +GatewayClass for you. + +Since the chart exposes Bolt through TCPRoute, which is an **alpha** Gateway +API resource, two extra steps are required compared to a plain Istio +installation: the Gateway API CRDs must come from the **experimental** channel, +and istiod must run with `PILOT_ENABLE_ALPHA_GATEWAY_API=true`. + +Install the experimental Gateway API CRDs first — istiod detects the alpha CRDs +at startup, so if it is already running, restart it afterwards with `kubectl +rollout restart deploy/istiod -n istio-system`: + +```bash +kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/experimental-install.yaml +``` + +Then install Istio with the alpha Gateway API flag enabled: + +```bash +helm repo add istio https://istio-release.storage.googleapis.com/charts +helm repo update +helm install istio-base istio/base -n istio-system --create-namespace +helm install istiod istio/istiod -n istio-system --wait \ + --set pilot.env.PILOT_ENABLE_ALPHA_GATEWAY_API=true +``` + + +Without `PILOT_ENABLE_ALPHA_GATEWAY_API=true`, istiod rejects the chart's TCP +listeners (`protocol "TCP" is supported, but only when +PILOT_ENABLE_ALPHA_GATEWAY_API=true is configured`) and the failure is easy to +misread: the Gateway still shows `Programmed=True` and its LoadBalancer Service +still lists all the ports, but the TCPRoutes get **no status at all** and every +connection times out. If you hit this, set the flag with `helm upgrade istiod +istio/istiod -n istio-system --reuse-values --set +pilot.env.PILOT_ENABLE_ALPHA_GATEWAY_API=true --wait` and check that the +TCPRoutes report `Accepted`. + + +Finally, install the HA chart with the `istio` GatewayClass: + +```bash +helm install memgraph-ha memgraph/memgraph-high-availability \ + --set externalAccessConfig.gateway.enabled=true \ + --set externalAccessConfig.gateway.gatewayClassName=istio +``` + +Istio provisions a Deployment and a LoadBalancer Service named +`-istio` carrying every listener port: clients reach all +coordinators through the shared listener at `:` (default +7687) and each data instance at `:` (default +9000, 9001, ...). Unlike some controllers (for example Traefik, which requires +every listener port to be declared as an entryPoint), Istio programs listener +ports automatically, so scaling the data tier needs no controller +configuration. + +Drivers should connect with `bolt://` directly to the port they want, or, when +using `neo4j://` routing mode, set an `external-dns` hostname on the Gateway so +the coordinators register the external `:` as their routing +`bolt_server` (see [Update bolt server](#update-bolt-server)): + +```yaml +externalAccessConfig: + gateway: + enabled: true + gatewayClassName: "istio" + annotations: + external-dns.alpha.kubernetes.io/hostname: "memgraph.example.com" +``` + +Istio copies the LoadBalancer address into the Gateway's `.status.addresses`, +which is where `external-dns` reads it from, so no extra Istio configuration is +needed. + + +Using Istio as the Gateway API controller does **not** require adding the +Memgraph pods to the Istio service mesh. If you do sidecar-inject them +(namespace label `istio-injection=enabled`), use native sidecars (Kubernetes >= +1.28 and `--set pilot.env.ENABLE_NATIVE_SIDECARS=true` on istiod) — a classic +`istio-proxy` sidecar keeps the `cluster-setup` Job pod running forever, which +hangs the chart's post-install hook, and native sidecars also start the proxy +before Memgraph so coordinators don't fail their initial connections to each +other. On older clusters, exclude the Job from the mesh instead with `--set +clusterSetup.labels."sidecar\.istio\.io/inject"=false`. + + +A ready-made istiod values file with these settings is available in the [Helm +charts repository](https://github.com/memgraph/helm-charts/blob/main/examples/gateway/istio-values.yaml). + ### Use Memgraph HA chart with IngressNginx One of the most cost-efficient ways to expose a Memgraph HA cluster is by using