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. Each route chooses what is cached and for how long: methods, status codes and content types, the time to live, whether Cache-Control is honoured, and which headers, query parameters and body fields vary the entry.
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.
Upgrading, and turning on a capability
Envoy Gateway reads its configuration from a ConfigMap mounted into the controller. It reloads the file when the kubelet updates it, which can take up to two minutes after helm upgrade returns (up to 87 seconds was measured). Until then the controller runs with its previous configuration.
This matters when an upgrade turns on a capability: Backend support (gateway-helm.config.envoyGateway.extensionApis.enableBackend) or rate limits (gateway-helm.config.envoyGateway.rateLimit). Until the controller has loaded the new configuration, a route that uses the capability answers 500, rather than being served without it. Those are failed requests to your clients; nothing retries them. Routes that do not use the capability are not affected.
With Argo CD or Flux, which apply the chart change and your routes together, run the restart below as a separate step after the sync, or deploy routes that use the new capability two minutes after it.
To put the new configuration into effect at once, restart the controller after the upgrade and wait for it to take over:
kubectl -n envoy-gateway-system rollout restart deployment/envoy-gateway
kubectl -n envoy-gateway-system rollout status deployment/envoy-gateway --timeout=180s
ns=envoy-gateway-system
rev=$(kubectl -n $ns get deployment envoy-gateway \
-o jsonpath='{.metadata.annotations.deployment\.kubernetes\.io/revision}')
for i in $(seq 1 30); do
p=$(kubectl -n $ns get lease 5b9825d2.gateway.envoyproxy.io -o jsonpath='{.spec.holderIdentity}')
p=${p%%_*}
rs=$(kubectl -n $ns get pod "$p" --ignore-not-found \
-o jsonpath='{.metadata.deletionTimestamp}|{.metadata.ownerReferences[0].name}')
case "$rs" in
"|"*) [ "$(kubectl -n $ns get replicaset "${rs#|}" \
-o jsonpath='{.metadata.annotations.deployment\.kubernetes\.io/revision}')" = "$rev" ] \
&& { echo ready; break; } ;;
esac
sleep 2
done
The new controller acts once it holds the leader lease, which the previous one releases only by letting it expire (15 seconds). The loop prints ready when the lease is held by a controller Pod of the new revision that is not being deleted; the capability is then in effect. If it does not print ready within a minute, check the controller’s log before deploying routes that use the capability. Envoy keeps serving with its current configuration while the controller restarts. Deploy routes that use a newly turned-on capability after this, or after two minutes without the restart.
The controller’s Deployment is always named envoy-gateway, in the release’s namespace.
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;
- the JSON access log (see The access log).
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 |
| The proxy Service’s type | envoyService.type |
Envoy Gateway’s default, LoadBalancer |
To change one of these, set its path in your values. Helm merges the nested path into the chart’s defaults, so the rest stay. For example, a cluster whose front proxy reaches the Gateway through its own Service sets gateway-helm.config.envoyGateway.envoyProxy.provider.kubernetes.envoyService.type: ClusterIP.
An EnvoyProxy that you attach to a GatewayClass or a Gateway replaces these defaults entirely, unless it sets spec.mergeType. Without it, the proxies lose the filter order, which puts the authentication checks before the cache, and the JSON access log. Set mergeType: StrategicMerge on any EnvoyProxy you add, so that it changes only the fields it names.
The access log
Every Envoy proxy writes one JSON line per request to its standard output, where Fluent Bit, or any collector that reads container logs, picks it up. The fields:
| Field | Content |
|---|---|
start_time |
When the request started |
method |
The HTTP method |
authority |
The host the client asked for |
path |
The path, without its query string |
protocol |
HTTP/1.1, HTTP/2 or HTTP/3 |
response_code |
The status code sent to the client |
response_flags |
Envoy’s response flags, for example UF when the upstream connection failed |
response_code_details |
Envoy’s reason for the response |
bytes_received, bytes_sent |
Body bytes in each direction |
duration_ms |
The whole request, in milliseconds |
upstream_service_time_ms |
The time the backend took, in milliseconds |
client_address |
The client’s address. With the PROXY protocol on, it is the address the front proxy sent. |
x_forwarded_for |
The X-Forwarded-For header as received |
user_agent |
The User-Agent header |
request_id |
The X-Request-ID header (see the next section) |
route_name |
The route Envoy matched |
upstream_host |
The backend endpoint that answered |
cache_status |
The cache’s X-Cache-Status, on routes that use the cache |
These field names and their contents are the documented format, which collectors and parsers may rely on. The format is set at gateway-helm.config.envoyGateway.envoyProxy.telemetry.accessLog. A value that replaces that setting, or an EnvoyProxy without mergeType, removes this format.
No header that carries a credential is logged: Authorization, Cookie and Proxy-Authorization never appear. The query string is not logged either, because it can carry tokens. On a TCP or TLS passthrough listener, the HTTP fields are -.
The Gateway’s client traffic: the request ID and the PROXY protocol
With clientTraffic.gateway.name set, the chart writes one ClientTrafficPolicy for that Gateway. The policy covers every listener of the Gateway, including the listeners that sipar-route releases attach through ListenerSets. The Gateway may be created after the chart; the policy attaches once the Gateway exists.
This must be the Gateway’s only ClientTrafficPolicy. Envoy Gateway does not merge two policies for the same listener. A policy that names a listener takes that listener away from this one, and with it the request ID and PROXY protocol settings below. Add other client settings, such as timeouts or the forwarded headers, as values of this chart in a later version, not as a second policy.
The request ID (clientTraffic.requestID). Every response carries the request’s X-Request-ID, including the responses Envoy makes itself (401, 403, 404, 429 and 503). A customer can quote it, and support can find the request in the access log (request_id). A response served from the cache carries the ID of the request it answers.
| Value | Behaviour |
|---|---|
Generate (default) |
Envoy replaces any X-Request-ID from the client with a new UUID. A client cannot choose the ID that appears in the gateway’s logs or that is passed to the application. |
PreserveOrGenerate |
A client’s X-Request-ID is kept; otherwise one is generated. The response then returns the ID the client sent. It lets a client choose the ID in the logs and on error pages, so use it only behind a trusted front that sets trace IDs. |
Preserve |
A client’s X-Request-ID is kept, and none is generated. The response returns the ID the client sent. |
Disable |
Envoy does not handle the header. A response carries an X-Request-ID only if the request had one. |
The PROXY protocol (proxyProtocol.enabled, off by default). With it on, every listener of the Gateway requires a PROXY protocol header (v1 or v2) at the start of each connection, and takes the client address from it. A connection without the header is refused.
- Turn it on only when clients can reach the Gateway’s listeners solely through the proxy that sends the header, for example HAProxy with
send-proxy-v2, and nothing else can connect to them. Anyone who can connect directly can send a header with an address of their choosing, and so pass address allow lists. - Clients inside the cluster that call the proxy Service directly do not send the header, and are refused. Send such clients through the front proxy, or give them a second Gateway without the PROXY protocol.
- The front proxy’s health checks must send the header too (for HAProxy,
check-send-proxy). Without it, every backend is marked down.
Hardening
- EnvoyProxy patches are ignored (
runtimeFlags.disabled: [EnvoyProxyPatch]). Apatchon an EnvoyProxy would otherwise change the proxy’s Deployment with Envoy Gateway’s own privileges. - EnvoyPatchPolicy stays closed: it would patch Envoy’s configuration directly.
- The Backend resource is off by default, and guarded when on. With
gateway-helm.config.envoyGateway.extensionApis.enableBackend: true, the chart installs the ValidatingAdmissionPolicysipar-backend-kubernetesservice-onlyand its binding. They admit a Backend only of type KubernetesService, on create and on update, and refuse the request if the policy cannot be evaluated. A Backend of type Endpoints or DynamicResolver could send a route’s traffic to any address. The chart refuses Backend on if the guard is missing or weakened. ValidatingAdmissionPolicy needs Kubernetes 1.30 or later; the chart requires 1.33. - 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, those containers would run without limits, and a ResourceQuota in the namespace would refuse the proxy Pods. The chart therefore refuses to render without
limitRange.defaultandlimitRange.defaultRequest(CPU and memory); you may change the values. A policy check that reads the proxy Deployment, rather than the running Pods, reports the shutdown manager without limits. With the Compliance and Assurance Convoy, that finding shows as “Pass, with exception”, because this chart’s LimitRange gives every running copy its limits; the compliance chart’s documentation states the conditions and the version that adds it.
The chart refuses an install that turns off the patch flag, opens EnvoyPatchPolicy, enables Backend without its guard, or sets failClosed: true.
The hardening test
helm test <release> runs a check of the installed gateway. It never runs on install or upgrade. It uses the kubectl image from Tersane’s mirror, under a service account that may only list Pods in this namespace and read the named objects below.
It checks, in order, and stops at the first failure with one line naming it:
- Every running Pod in this namespace. Every container runs as non-root, does not allow privilege escalation, is not privileged, drops ALL capabilities, and has a read-only root filesystem. A missing setting fails, as a wrong one does.
- The roles
edit,adminandsipar-tenant-routesgrant no Envoy Gateway or Sipar kind, and not every API group. - With rate limits configured, the NetworkPolicy
sipar-ratelimitis present. - With Backend enabled, the admission guard’s policy and binding are present.
Every Sipar container, the Envoy Gateway controller and the rate-limit service run with a read-only root filesystem. The two containers of each Envoy proxy Pod, envoy and shutdown-manager, run as non-root, with every capability dropped and no privilege escalation, and with a writable root filesystem: Envoy Gateway writes Envoy’s log and socket, and the drain file, there. The test accepts a writable root for those two containers only, and only in Pods that carry Envoy Gateway’s proxy labels.
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 passthrough route’s list applies to its own hostname only. Several TLS passthrough listeners can share one port, each for its own hostname. A policy on one of them applies to the connections for that hostname, and the other listeners on the same port are unaffected. If one route is attached to two listeners on the same port, their connections cannot be told apart, so that port is closed until the route is corrected, and the alert
SiparTCPAccessListenerClosedfires. - 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. A policy that names a listener that does not exist applies to nothing, and the alert
SiparTCPAccessPolicyTargetMissingfires. - 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. The same holds for a short time after an extension replica starts, until it has read the Gateways, ListenerSets and routes; the alert SiparTCPAccessTranslationRefused fires if that lasts.
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. Required: CPU and memory in each |
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 |
clientTraffic.gateway.name |
The Gateway the chart’s ClientTrafficPolicy covers; empty writes none | |
clientTraffic.gateway.namespace |
the release namespace | The Gateway’s namespace |
clientTraffic.requestID |
Generate |
The X-Request-ID behaviour; see “The Gateway’s client traffic” |
proxyProtocol.enabled |
false |
The PROXY protocol on every listener of the Gateway; needs clientTraffic.gateway.name |
hardeningTest.image |
Set in each release | The image helm test runs; see “The hardening test” |
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 |