Bahriya Tersane

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 install and helm upgrade check 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 at v1, 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 set preflight.gatewayAPIv1Confirmed=true after checking yourself:

    kubectl get crd tcproutes.gateway.networking.k8s.io -o jsonpath='{.spec.versions[?(@.served==true)].name}'
    kubectl get crd envoyproxies.gateway.envoyproxy.io
    

    The 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 memcached chart.
  • For rate limits: a Redis-compatible store, such as the Tersane valkey chart.
  • Requires: the Tersane valkey chart 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 Tersane valkey chart.
  • 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 install installs 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]). A patch on 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 ValidatingAdmissionPolicy sipar-backend-kubernetesservice-only and 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-ratelimit admits 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.default and limitRange.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:

  1. 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.
  2. The roles edit, admin and sipar-tenant-routes grant no Envoy Gateway or Sipar kind, and not every API group.
  3. With rate limits configured, the NetworkPolicy sipar-ratelimit is present.
  4. 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 deny list, every other address is allowed. With an allow list, 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 SiparTCPAccessListenerClosed fires.
  • 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 SiparTCPAccessPolicyTargetMissing fires.
  • 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-rl and post-rl. A pre-rl route’s cached response is served before the rate limit and uses none of it. A post-rl route’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, a post-rl request 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.memcached and cache.valkey.addresses must 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, watch and patch on sipartcpaccesspolicies, to mark a policy so that Envoy Gateway applies held changes;
  • get, list and watch on listenersets, to find each ListenerSet’s Gateway;
  • get, create and update on leases in 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