Overview
An ingress controller is already the one place every external request passes. Making it Synapse means the protection runs where the routing does, instead of in a second proxy behind it.
In ingress mode the operator reconciles Ingress and Gateway API resources into Synapse's upstream configuration and triggers a hot reload, with no proxy restart and no dropped connections. Security policy stays in Synapse's own configuration, so it applies to every route at once.
When you see this
- Your services are exposed through Ingress objects today.
- You run a WAF as a second hop behind the ingress controller.
- You want one policy across every route rather than per-service settings.
Steps
- 01
Deploy the controller
The stack chart stands up a separate operator in ingress mode. Setting proxy.synapse.upstreams to empty is not optional: it stops Helm's merge from overwriting the operator's routes on the next upgrade. This needs synapse-stack 0.6.0 or newer.
synapse-stack values operator: ingress: enabled: true ingressClass: synapse upstreamsOutConfigMap: "synapse-os/synapse-proxy" proxy: synapse: upstreams: "" - 02
Create the IngressClass
Annotate it as the default class if class-less Ingresses should use Synapse too.
IngressClass apiVersion: networking.k8s.io/v1 kind: IngressClass metadata: name: synapse spec: controller: gen0sec.com/synapse - 03
Route with Ingress
Synapse routes on host and longest-prefix path. Exact path types and HTTPRoute header, method and query matches are approximated or ignored, and the controller says so with a warning and a Kubernetes event.
Ingress apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: app spec: ingressClassName: synapse rules: - host: app.example.com http: paths: - path: / pathType: Prefix backend: service: name: app port: number: 80 - 04
Turn on the IDS for every route
Firewall, WAF, IDS and rate limits are Synapse configuration, not Ingress annotations. The IDS inspects decrypted HTTP on the ingress path, so it sees real requests even for HTTPS that Synapse terminates.
Synapse config ids: enabled: true rule_paths: - /etc/synapse/rules/emerging-all.rules address_vars: { HOME_NET: "10.0.0.0/8" } enforce_block: false post_tls: mode: offload socket: /run/synapse/ids.sockDecisionDoes the proxy run more than one replica?Yes Use post_tls.mode offload: the ruleset then costs one copy per node, not one per replica.
No inline is the simplest.
- 05
Check the version caveat
On Synapse 0.8.9 with the published charts' operator 0.1.x, an Ingress with sticky-sessions makes the routes file refuse to load, and HTTPS back-ends must present a certificate the system trust store accepts. If you rely on either, keep proxy.image.tag at 0.8.8 for now.
Common mistakes
- Leaving proxy.synapse.upstreams set, so the next helm upgrade overwrites the operator's routes.
- Looking for WAF or IDS settings in Ingress annotations. They are Synapse configuration.
- Running inline IDS across many proxy replicas, each holding the whole ruleset.
Escalate when
- The controller warns that a route's match was approximated: check that route does what you meant.
Where this stops working
- Routing is first-writer-wins on a host and path conflict.
- Only traffic through the ingress is protected. Services reached another way bypass it.