Documentation / sipar-gateway
sipar-gateway
Sipar’s gateway for a cluster, installed once per cluster. It installs Envoy Gateway, unmodified, and Sipar’s extensions behind switches:
- TCP access (on by default): refuses TCP clients by address before Envoy connects to the backend, so a refused client receives nothing, not even a server’s greeting.
- The response cache (off by default): caches responses in Memcached or Valkey, with the settings of Kong’s proxy-cache plugin.
An application’s routes and policies are written by the sipar-route library chart, inside the application’s own chart. This chart writes nothing into an application’s namespace.
Envoy Gateway and Envoy are not modified. Sipar’s code runs only at the extension points Envoy Gateway publishes: an extension server for TCP access and an external processor for the cache.
Requirements
- Kubernetes 1.33 or later.
-
Gateway API v1.6 or later, standard channel, and Envoy Gateway’s CRDs, installed before this chart as shown under The CRDs.
helm installandhelm upgradecheck the cluster and refuse to go on if they are missing, if the Gateway API bundle is older than v1.6, or if TCPRoute is not served atv1, naming the bundle and who installed it. A render without a cluster (helm template, Argo CD, Flux) cannot check, so it is refused unless you setpreflight.gatewayAPIv1Confirmed=trueafter checking yourself:kubectl get crd tcproutes.gateway.networking.k8s.io -o jsonpath='{.spec.versions[?(@.served==true)].name}' kubectl get crd envoyproxies.gateway.envoyproxy.ioThe first output must include
v1, and the second must find the CRD. - A Secret holding your image token for 1x.ax, named in
imagePullSecrets. Every image this chart runs is pulled with it, Envoy Gateway’s included. - For the cache: a Memcached, such as the Tersane
memcachedchart. - For rate limits: a Redis-compatible store, such as the Tersane
valkeychart. - Requires: the Tersane
valkeychart 1.4.3 or later; 1.4.4 or later is recommended. This applies to a Valkey store with Sentinel or in cluster mode, for the cache or for rate limits. Earlier versions do not recover correctly when a Pod restarts in these modes. In Sentinel mode, a failover may not take place. In cluster mode without persistence, a restarted node can lose its shard’s data or stay outside the cluster, and the rate-limit service does not start while the cluster lists a failed node. Earlier versions remain supported in standalone mode. Sipar also supports Sentinel sets built from the official Valkey image; this is a separate store source, not an earlier version of the Tersanevalkeychart. - In cluster mode, after a Valkey Pod is replaced, Envoy Gateway’s rate-limit service usually starts against the cluster within about two minutes; it can take longer. Until then rate limits fail open, and requests pass without limit.
Installing
Install the CRDs first, as shown under The CRDs. Then:
helm install sipar <chart> -n envoy-gateway-system --create-namespace \
--set 'imagePullSecrets[0].name=<your image token Secret>'
With the cache and rate limits:
helm install sipar <chart> -n envoy-gateway-system --create-namespace \
--set 'imagePullSecrets[0].name=<your image token Secret>' \
--set gateway-helm.config.envoyGateway.rateLimit.backend.type=Redis \
--set gateway-helm.config.envoyGateway.rateLimit.backend.redis.url=valkey.data.svc.cluster.local:6379 \
--set cache.enabled=true \
--set cache.memcached=memcached.data.svc.cluster.local:11211 \
--set 'cache.namespaces={shop,catalogue}'
The chart creates no GatewayClass unless you ask for one. With --set gatewayClass.create=true it creates a GatewayClass named sipar (gatewayClass.name to change it) for Envoy Gateway, which your Gateways name in gatewayClassName. It names no EnvoyProxy, so its proxies take the defaults described below. Uninstalling the chart, or turning gatewayClass.create off, leaves the GatewayClass in place, because deleting one that Gateways still use leaves it stuck terminating. Delete it yourself, with kubectl delete gatewayclass sipar, once no Gateway uses it.
Install it in envoy-gateway-system unless you have a reason otherwise. In another namespace, change gateway-helm.config.envoyGateway.extensionManager.service.fqdn.hostname to sipar-tcp-access.<namespace>.svc.cluster.local; the chart refuses an install where they differ.
The CRDs
Gateway API’s and Envoy Gateway’s CRDs are too large to be part of a Helm release: Kubernetes limits the record Helm keeps of a release to 1 MiB, and these CRDs come to about 4 MB. Envoy Gateway documents the same way of installing them, with server-side apply. This chart carries only Sipar’s own two CRDs, in its crds/ directory.
Before installing this chart, and again before every upgrade, apply the CRDs with the script this chart carries. Run these in an empty directory. <chart> and <version> are the chart you install, from the Tersane chart repository you added with your chart credentials (for example tersane/sipar-gateway). The script takes your Tersane image credentials, the same ones your image pull Secret holds:
helm pull <chart> --version <version> --untar
printf '%s' "$TOKEN" | bash sipar-gateway/scripts/apply-crds.sh <user>
The script applies, to kubectl’s current context:
- Gateway API’s standard channel, Envoy Gateway’s CRDs and Gateway API’s admission policy that refuses an older or experimental CRD over a standard one, from Envoy Gateway’s CRD chart as mirrored on 1x.ax, at the Envoy Gateway version this chart carries;
- Sipar’s two CRDs, from the chart’s
crds/.helm installinstalls these too, but Helm never upgrades a CRD, so upgrades need the script.
The token is read from standard input, never from an argument, and the login is kept in a configuration of the script’s own, removed when it ends, so the token is not left in your Helm configuration. If you are already logged in to 1x.ax with helm registry login, run the script with no argument. CRDs installed earlier by another tool, such as kubectl apply of Gateway API’s release files or an earlier Envoy Gateway install, are taken over (--force-conflicts), as Envoy Gateway’s own upgrade instructions do.
Upgrading Gateway API
The script upgrades Gateway API in place when an older version is installed, and the chart refuses to install over a version before v1.6. Before upgrading from a version before v1.6, update every TCPRoute and UDPRoute manifest to apiVersion: gateway.networking.k8s.io/v1: the standard channel of v1.6 no longer serves v1alpha2, so routes left on it stop being served. Envoy Gateway’s upgrade notes for its v1.10 release describe the same step. If your Kubernetes platform installs and manages Gateway API’s CRDs itself, do not run the script over them: the platform may write its own version back. Use the platform’s Gateway API when it provides v1.6 or later on the standard channel.
Gateway API channel
This version of Sipar needs a cluster on Gateway API’s standard channel, and the chart refuses an install over the experimental channel. Moving a cluster from the experimental to the standard channel is not a single apply: a CRD version recorded in a CRD’s status.storedVersions cannot be dropped, and resources of kinds or fields that exist only in the experimental channel are affected. Check what uses the experimental channel, and follow Gateway API’s guidance for it, before changing a cluster. Do not use helm show crds for this chart: it also prints the CRDs bundled in Envoy Gateway’s chart, which are Gateway API’s experimental channel.
None of these CRDs belongs to the Helm release. Uninstalling the chart never deletes them, so your routes and policies are never deleted with it.
Envoy proxy defaults, and EnvoyProxy resources of your own
The chart sets the defaults for every Envoy proxy that Envoy Gateway runs:
- the pinned Envoy image, and requests and limits for Envoy;
- two replicas, preferably on different nodes, with a disruption budget of one, so that draining a node never takes all of a Gateway’s traffic;
- the filter order, which runs the address and authentication checks before the cache. With that order, a client refused by a SecurityPolicy is refused on a cached response too.
These are Envoy Gateway’s own settings, under gateway-helm.config.envoyGateway.envoyProxy:
| Setting | Path under gateway-helm.config.envoyGateway.envoyProxy.provider.kubernetes |
Default |
|---|---|---|
| Replicas | envoyDeployment.replicas |
2 |
| Autoscaling | envoyHpa |
none |
| Disruption budget | envoyPDB.minAvailable |
1 |
| Envoy’s requests and limits | envoyDeployment.container.resources |
100m and 512Mi requested; 2 CPUs and 1Gi limit |
An EnvoyProxy that you attach to a GatewayClass or a Gateway replaces these defaults entirely, unless it sets spec.mergeType. Set mergeType: StrategicMerge on any EnvoyProxy you add, so that it changes only the fields it names.
Hardening
- EnvoyProxy patches are ignored (
runtimeFlags.disabled: [EnvoyProxyPatch]). Apatchon an EnvoyProxy would otherwise change the proxy’s Deployment with Envoy Gateway’s own privileges. - The extension APIs stay closed: no EnvoyPatchPolicy, which patches Envoy’s configuration directly, and no Backend resource, which lets a route reach any address.
- Rate limits fail open: with
rateLimit.failClosed: false, requests pass unlimited while the rate-limit store is unavailable. - The rate-limit service is reachable only from Envoy and the cache. When rate limits are configured, the NetworkPolicy
sipar-ratelimitadmits the service’s gRPC port, 8081, only from Envoy Gateway’s proxies and from Sipar’s cache, and refuses every other port from everywhere, including 8080 (HTTP) and 6070 (debug). This holds only where the cluster’s network plugin enforces NetworkPolicy, as Calico does on BKE. Without enforcement, any Pod in the cluster can reach the service, including the known vulnerability on port 8081 (see Images). - A LimitRange gives default requests and limits to any container in this namespace that declares none. Every container the chart starts declares its own; the exception is the shutdown manager in each Envoy proxy Pod, which Envoy Gateway starts with requests only. Without the LimitRange, a ResourceQuota in the namespace would refuse the proxy Pods.
The chart refuses an install that turns off the patch flag, opens either extension API, or sets failClosed: true.
Who may write routes
The chart adds HTTPRoute, GRPCRoute, TCPRoute, TLSRoute, UDPRoute and ListenerSet to Kubernetes’ built-in edit and admin roles, so anyone who may edit a namespace may write its routes. It grants no Gateway, GatewayClass, ReferenceGrant, BackendTLSPolicy, Envoy Gateway or Sipar policy kind; those stay with the cluster’s operators and the charts they install.
TCP access
You attach a SiparTCPAccessPolicy to a TCP or TLS listener of a Gateway or a ListenerSet, by sectionName, with an allow list, a deny list, or both. sipar-route writes it from an application’s chart.
- Deny wins, whatever the prefix lengths.
- With only a
denylist, every other address is allowed. With anallowlist, every address not on it is refused. - Several policies on one listener intersect: a client must be allowed by all of them.
- Each entry must be a CIDR, and a policy with one that is not is refused when it is applied.
- A policy that cannot be read closes only its own listener.
- Client addresses are those Envoy sees, including the address restored by the PROXY protocol when a load balancer in front of the Gateway sends it.
- How quickly a change takes effect. Each Envoy replica takes a policy change on its own. Measured on a test cluster with two replicas, over 20 changes: a client newly refused was refused by both replicas within about 1 second, and a client re-admitted by removing the policy was admitted by both after about 18 seconds. Until then, a replica keeps applying the policy it had.
Turning it on or off
Envoy Gateway calls TCP access only where its own configuration names it, and Helm cannot change that configuration from this chart’s switch. So the switch is two settings, and the chart refuses an install where they disagree:
| TCP access | tcpAccess.enabled |
gateway-helm.config.envoyGateway.extensionManager |
|---|---|---|
| On (default) | true |
as in the chart’s values.yaml |
| Off | false |
null |
When TCP access is unavailable
TCP access fails closed. While no replica is available, Envoy keeps serving its last configuration and no policy change on any Gateway takes effect, revocations included: a client you remove keeps access until TCP access is available again. The chart runs two replicas with a disruption budget of one, so a rolling update or the loss of one replica holds nothing back.
Envoy Gateway does not retry a configuration it could not complete while the extension was unavailable. The extension makes it do so: for the first 3 minutes after a replica takes the lead, every 10 seconds; after that, every tcpAccess.recovery.interval (default 2m; 30s to 15m, as seconds or whole minutes).
The cache
A route is cached through a SiparCachePolicy and an EnvoyExtensionPolicy that sends the route through the cache. sipar-route writes both from an application’s chart.
- The namespaces that may use the cache are listed in
cache.namespaces. An application’s EnvoyExtensionPolicy reaches the cache across namespaces, which Gateway API allows only through a ReferenceGrant, and a ReferenceGrant names each namespace. A route in a namespace not listed is not cached: Envoy Gateway refuses its policy. Add the namespace and upgrade this chart before deploying a cached application into it. - Fails open. If the cache or its store is unavailable, or a lookup takes longer than
cache.lookupTimeout, requests go to the application uncached. The cache starts while its store is unreachable and keeps trying to connect. This includes a Valkey cluster that reports itself down. pre-rlandpost-rl. Apre-rlroute’s cached response is served before the rate limit and uses none of it. Apost-rlroute’s cached response is counted against the limit: the cache asks Envoy Gateway’s rate-limit service first. Where the cache cannot reproduce a route’s limit, and whenever no rate-limit store is configured, apost-rlrequest goes to the application so that Envoy’s limiter counts it.- Tenant isolation. Entries are kept per route, so two applications never share one, even with the same host and path.
- Two replicas on different nodes. The anti-affinity is required, so the cluster needs at least as many schedulable nodes as
cache.replicaCount. A rollout removes a replica before starting its replacement, because the replacement could not be placed beside the others. - Stores by hostname.
cache.memcachedandcache.valkey.addressesmust name their servers by hostname; an address is refused.
The cache’s store
cache.store is memcached (the default) or valkey. Set the store’s addresses in a values file. On the command line, --set splits a value at its commas, so each comma must be written \,.
| Store | Settings |
|---|---|
| Memcached, one server or a pool | cache.memcached: memcached-0.memcached.data.svc.cluster.local:11211,memcached-1.memcached.data.svc.cluster.local:11211. Keys are spread over a pool, so losing one server loses only its share of the entries. |
| Valkey, one server | cache.store: valkey, cache.valkey.addresses: valkey.data.svc.cluster.local:6379 |
| Valkey with Sentinel | cache.store: valkey, cache.valkey.mode: sentinel, cache.valkey.addresses: the Sentinels, and cache.valkey.masterSet: the name they monitor the primary under. A failover is followed. |
| Valkey cluster | cache.store: valkey, cache.valkey.mode: cluster, cache.valkey.addresses: one or more nodes; the rest are learnt. |
A Valkey password is optional. To use one, put it in a Secret in this chart’s namespace and name it in cache.valkey.passwordSecret (key password, or cache.valkey.passwordSecretKey). It is mounted as a file and never passed as an argument; with Sentinel it authenticates to the Sentinels too. cache.valkey.username names an ACL user.
The rate-limit store
Rate limits use Envoy Gateway’s rate-limit service and its own settings, under gateway-helm.config.envoyGateway. One Valkey server needs only the url. For Sentinel or a cluster, and for a password, the service also takes environment variables. Passwords come from a Secret in this chart’s namespace, never as values:
gateway-helm:
config:
envoyGateway:
rateLimit:
failClosed: false
backend:
type: Redis
redis:
# one server: valkey.data.svc.cluster.local:6379
# Sentinel: <master name>,<sentinel>:26379,<sentinel>:26379
# cluster: <node>:6379,<node>:6379,<node>:6379
url: "primary,valkey-0.valkey.data.svc.cluster.local:26379,valkey-1.valkey.data.svc.cluster.local:26379"
provider:
type: Kubernetes
kubernetes:
rateLimitDeployment:
container:
env:
- {name: REDIS_TYPE, value: sentinel} # or cluster; leave it out for one server
# Optional password, for the data nodes:
- {name: REDIS_AUTH, valueFrom: {secretKeyRef: {name: valkey-password, key: password}}}
# Optional, Sentinel only, for the Sentinels:
- {name: REDIS_SENTINEL_AUTH, valueFrom: {secretKeyRef: {name: valkey-password, key: password}}}
The chart refuses settings that do not agree: several addresses without REDIS_TYPE, a Sentinel url that does not start with the master name, an address instead of a hostname, a password given as a value, or REDIS_SENTINEL_AUTH without Sentinel. A change to the rate-limit settings reaches Envoy Gateway by itself within about two minutes; no restart is needed.
A new rate limit is in force once Envoy Gateway has sent it to each Envoy proxy and to the rate-limit service. Both take it from Envoy Gateway’s configuration stream, without a restart, typically within 15 seconds. The time is not guaranteed and can be longer, so do not depend on a fixed delay: until the limit is in force, requests on the route are not limited by it. To confirm that a new limit is in force, send more requests than it allows and check that the excess receive status 429.
Monitoring
Each extension serves metrics on port 9090 at /metrics. With the Prometheus Operator, set monitoring.serviceMonitor.enabled and monitoring.prometheusRule.enabled. The alerts:
- SiparTCPAccessUnavailable (critical): no TCP access replica is available, so policy changes are not being applied.
- SiparTCPAccessRecoveryStale (warning): no recovery pass for 2.5 recovery intervals.
- SiparCacheUnavailable (warning): no cache replica is available, so cached routes are served by their applications.
Permissions
TCP access’s service account:
get,list,watchandpatchonsipartcpaccesspolicies, to mark a policy so that Envoy Gateway applies held changes;get,listandwatchonlistenersets, to find each ListenerSet’s Gateway;get,createandupdateonleasesin its own namespace, to elect one replica.
The cache’s service account: get, list and watch on siparcachepolicies, httproutes, gateways, listenersets and backendtrafficpolicies. It reads no Secret through the API. With rate limits, the CA certificate of Envoy Gateway’s rate-limit service is mounted as a file; the service’s key is not.
Envoy Gateway’s service account, which its own chart does not grant for extension policies: get, list and watch on sipartcpaccesspolicies, and update and patch on their status.
Images
Every image is pulled by digest; the tag and digest of each are in the chart’s values.yaml.
| Image | Runs |
|---|---|
1x.ax/tersane/core/envoyproxy/gateway |
Envoy Gateway, and the shutdown manager in each proxy Pod |
1x.ax/tersane/core/envoyproxy/envoy |
Envoy, the distroless image |
1x.ax/tersane/core/envoyproxy/ratelimit |
The rate-limit service. Upstream publishes it under commit tags only |
1x.ax/sipar/extensions/tcp-access |
TCP access |
1x.ax/sipar/extensions/cache |
The cache |
The rate-limit service’s known vulnerabilities
The rate-limit image is 1x.ax/tersane/core/envoyproxy/ratelimit:3dfe2f9a@sha256:c695e3a40d6047621ed05346147f23c919beb50a7943b1e32a241b549362a93f, built by the upstream project from commit 3dfe2f9a of github.com/envoyproxy/ratelimit. Images are copied from upstream by digest and never rebuilt, so a fix arrives with a later upstream build. It has two known vulnerabilities, both rated high, both in the Go library golang.org/x/net, and both denial of service:
| Vulnerability | Effect | Fixed in | Reachable |
|---|---|---|---|
| CVE-2026-78669 | Denial of service through a flood of HTTP/2 SETTINGS frames | x/net 0.60 | On the gRPC port, 8081, which the NetworkPolicy sipar-ratelimit admits only from Envoy Gateway’s proxies and Sipar’s cache |
| CVE-2026-78661 | Denial of service in the HTML parser, x/net/html | x/net 0.62 | Not shown |
While the rate-limit service is unavailable, rate limits fail open: requests pass without limit.
Each is signed. To check a signature with the published public key:
cosign verify --key bke-images-2026.pub --insecure-ignore-tlog=true <image>@<digest>
Values
| Value | Default | Description |
|---|---|---|
imagePullSecrets |
[{name: 1x-ax}] |
The Secret holding your image token |
limitRange.defaultRequest, limitRange.default |
10m/32Mi, 100m/64Mi | Requests and limits for a container in this namespace that declares none |
tcpAccess.enabled |
true |
TCP access; see “Turning it on or off” |
tcpAccess.replicaCount |
2 |
Replicas |
tcpAccess.podDisruptionBudget.minAvailable |
1 |
Replicas kept during voluntary disruption |
tcpAccess.recovery.interval |
2m |
See “When TCP access is unavailable” |
cache.enabled |
false |
The cache |
cache.memcached |
Memcached as host:port, several separated by commas; required with the cache |
|
cache.namespaces |
[] |
The namespaces whose routes may use the cache; required with the cache |
cache.lookupTimeout |
150ms |
A slower lookup lets the request through uncached |
cache.storeTimeout |
2s |
How long storing a response may take |
cache.replicaCount |
2 |
Replicas, one per node |
cache.podDisruptionBudget.minAvailable |
1 |
Replicas kept during voluntary disruption |
monitoring.serviceMonitor.enabled |
false |
A ServiceMonitor for each extension |
monitoring.prometheusRule.enabled |
false |
The alerts |
preflight.gatewayAPIv1Confirmed |
false |
Required when rendering without a cluster; see Requirements |
gateway-helm.* |
Envoy Gateway’s own chart values; see https://gateway.envoyproxy.io |