Documentation / sipar-route
sipar-route
Sipar’s templates for an application’s policies, used inside the application’s own chart. It is a Helm library chart: it installs nothing by itself, and is added to an application’s chart as a dependency.
It needs sipar-gateway installed in the cluster.
Adding it to a chart
In the application’s Chart.yaml:
dependencies:
- name: sipar-route
version: <version>
repository: <the Tersane chart repository>
In one of the application’s templates:
{{ include "sipar-route.render" . }}
The settings go under a sipar-route: key in the application’s values. This chart’s values.yaml gives the defaults and its values.schema.json checks them, so a misspelt setting or an invalid value is refused at install. Every object is rendered in the release’s namespace.
sipar-route:
cache:
- name: catalogue
routes: [catalogue]
policy:
variant: pre-rl
cacheTtl: 300
tcpAccess:
- name: mysql-clients
listeners:
- kind: ListenerSet
name: databases
sectionName: mysql
allow: [10.20.0.0/16]
deny: [10.20.9.0/24]
Settings
| Setting | Default | Description |
|---|---|---|
gatewayNamespace |
envoy-gateway-system |
Where sipar-gateway is installed |
lookupTimeout |
150ms |
sipar-gateway’s cache.lookupTimeout |
messageTimeout |
300ms |
How long Envoy waits for the cache. It must be longer than lookupTimeout, and is refused otherwise |
http |
unset | The application’s HTTP entry; see below |
passthrough |
unset | TLS passthrough by hostname; see below |
cache |
[] |
Cached routes; see below |
tcpAccess |
[] |
TCP address policies; see below |
Caching a route
Each entry of cache renders a SiparCachePolicy and the EnvoyExtensionPolicy that sends its routes through Sipar’s cache.
| Field | Required | Description |
|---|---|---|
name |
yes | The name of both objects |
routes |
yes | The HTTPRoutes in the release’s namespace to cache |
policy |
The cache settings: variant (pre-rl or post-rl), cacheTtl, storageTtl, honorCacheControl, allowForceCacheHeader, requestMethods, responseCodes, contentTypes, varyHeaders, varyQueryParams, varyBodyJsonFields, consumerHeader, maxObjectBytes. Unset, the variant is pre-rl, cacheTtl is 300 seconds, requestMethods are GET and HEAD, responseCodes are 200, 301 and 404, contentTypes are text/plain and application/json, and maxObjectBytes is 1 MiB |
|
purge |
A value for the purge annotation. Changing it makes every earlier entry unreachable at once | |
messageTimeout |
This entry’s own messageTimeout |
The release’s namespace must be listed in sipar-gateway’s cache.namespaces. Otherwise Envoy Gateway refuses the EnvoyExtensionPolicy and the route is not cached.
The EnvoyExtensionPolicy fails open: if the cache cannot be reached, requests go to the application uncached. With varyBodyJsonFields set, the request body is buffered so that its fields can be part of the key. A body larger than the gateway’s buffer is not refused: it is sent to the application uncached, and the response carries X-Cache-Status: Bypass.
Requires: sipar-gateway 0.2.0 or later for varyBodyJsonFields.
With consumerHeader set, entries are kept per value of that header. Without it, a request carrying an Authorization header is keyed by a hash of that header.
When the cache names the route of http and that route, or one of its path rules, has basic authentication, entries are kept per authenticated user: consumerHeader is set to x-sipar-consumer, the header the gateway sets to the user it authenticated. A different consumerHeader for that route is refused. x-sipar-consumer is refused as a consumerHeader on any route without basic authentication, because there the header would be whatever the client sent. Entries are also kept apart per rule of a route, so on a path rule without basic authentication a client-sent x-sipar-consumer only divides that rule’s own entries.
Limiting TCP clients by address
Each entry of tcpAccess renders a SiparTCPAccessPolicy for TCP or TLS listeners. A refused client is closed at accept and receives nothing from the backend.
| Field | Required | Description |
|---|---|---|
name |
yes | The policy’s name |
listeners |
yes | Each a kind (Gateway or ListenerSet, default ListenerSet), a name, and the listener’s sectionName |
allow |
one of the two | CIDRs. With an allow list, every address not on it is refused |
deny |
one of the two | CIDRs. Deny wins over allow, whatever the prefix lengths |
Several policies on one listener intersect: a client must be allowed by all of them.
Serving an application over HTTP
http renders the application’s entry on the cluster’s shared Gateway: a ListenerSet with an HTTPS listener for each host, and the HTTPRoute that sends those hosts to the application’s Service. The shared Gateway must admit ListenerSets from the release’s namespace (its allowedListeners), which the cluster’s operator sets.
sipar-route:
http:
name: shop
gateway: {name: public, namespace: envoy-gateway-system}
hosts:
- name: shop.example.com
tlsSecretName: shop-tls
redirects:
www:
- host: www.example.com
to: example.com
tlsSecretName: example-tls
backend: {service: shop, port: 8080}
| Field | Required | Description |
|---|---|---|
name |
yes | The name of every object, or its prefix |
gateway |
yes | The shared Gateway’s name and namespace |
ports |
The Gateway’s https and http ports. Default 443 and 80 |
|
hosts |
yes | Each a name and the tlsSecretName of its certificate, a Secret in the release’s namespace |
redirects.https |
Default true: plain HTTP to any host answers 301 to the same URL over HTTPS |
|
redirects.www |
Each a host, its to and the host’s tlsSecretName: requests to host answer 301 to the same path and query on to |
|
backend |
yes | The application’s service and port, and tls (below) |
basicAuth, rateLimit, ipAllow, ipDeny, pathRules |
Below |
A host is listed once, and a www host is not also one of hosts. A ListenerSet holds at most 64 listeners. Each host and each www entry takes two (HTTPS, and HTTP for the redirect), or one with redirects.https: false. An entry that needs more than 64 is refused; split its hosts across two releases.
A request for a host that no listener names is not answered: the TLS handshake fails.
Timeouts. The gateway waits up to 60 seconds to connect to the application. A response may take any length of time as long as data keeps moving: the gateway ends a request only after 60 seconds with no data in either direction. These values are fixed.
Request size. The gateway sets no limit on the size of a request body.
Basic authentication
basicAuth:
users:
- username: alice
sha: "{SHA}<base64 of the SHA-1 of the password>"
Each user is a username and the password’s hash in the {SHA} form: {SHA} followed by the base64 encoding of the SHA-1 digest of the password. A password itself is refused. A request without valid credentials receives 401. The gateway sets x-sipar-consumer to the authenticated user, replacing any value the client sent. With hideCredentials (default true) the application never receives the Authorization header.
How the credentials are stored. The hashes are kept in a Secret in the release’s namespace, <name>-basic-auth, and in Helm’s record of the release, which is also a Secret in that namespace. The {SHA} form is unsalted: two users with the same password have the same hash, and a weak password can be found from its hash. Anyone who can read Secrets in the namespace can read the hashes, so the protection of the credentials is the protection of that namespace’s Secrets. Use long, random passwords.
Rate limits
rateLimit:
perSecond: 10
perMinute: 300
perHour: 5000
Any combination of the three windows; a window not set is not limited. Requests are counted in sipar-gateway’s rate-limit service, so every gateway replica counts against one limit. Each client address has its own count; on a route with basic authentication, each authenticated user has its own count. If the rate-limit store cannot be reached, requests pass without limit. A request over the limit receives 429. Each response on a limited route carries X-RateLimit-Limit (for example 5, 5;w=60: 5 requests in a 60-second window), X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets), and a 429 also carries Retry-After. A response served from the cache is answered before the rate limit, so it is not counted.
Client addresses
ipAllow admits only the listed clients and refuses every other; ipDeny refuses the listed clients and admits every other. Each is a list of CIDRs; a bare address means that one host (/32, or /128 for IPv6). A route sets one of the two, not both. A refused request receives 403. The client address is the one the gateway receives, so behind a load balancer it depends on sipar-gateway’s PROXY protocol setting.
Path rules
pathRules:
- name: admin
path: /admin
ipAllow: [192.0.2.0/24]
A path rule applies to its path and every path below it, with the longest matching path taking precedence. A rule may set basicAuth, rateLimit and ipAllow or ipDeny. Each control a rule sets replaces the route’s for that path; each control it does not set is the route’s. ipAllow and ipDeny count as one control. A path rule has its own rate-limit count, apart from the route’s, whether it sets its own limit or takes the route’s. A rule may not be on /, which is the route itself, and a path has one rule.
An application that serves HTTPS
With backend.tls: true, the gateway connects to the application over TLS. It encrypts the traffic but does not verify the application’s certificate, because that certificate is the application’s own and not issued by an authority the gateway knows. On a sipar-gateway without Backend support the route is not served.
Requires: sipar-gateway 0.2.0 or later, with its Backend support on, for backend.tls.
TLS passthrough by hostname
passthrough serves instances that terminate TLS themselves, such as Valkey with TLS, on one shared port. The gateway reads the hostname each client asks for and forwards the connection, still encrypted, to that instance’s Service.
sipar-route:
passthrough:
name: valkey
gateway: {name: public, namespace: envoy-gateway-system}
port: 6379
routes:
- name: cache-a
hostname: cache-a.example.com
service: cache-a
servicePort: 6379
allow: [203.0.113.0/24]
Each route takes one listener, so a release holds at most 64. A hostname is listed once. With allow or deny, a route’s listener refuses other clients at connection, before the TLS handshake, as tcpAccess does. Each passthrough route’s list applies to its own hostname only, including when several routes share the port. passthrough and http in one release take different names.
Requires: sipar-gateway 0.2.0 or later for allow and deny on passthrough routes that share a port.
What this version renders
The ListenerSet and routes of http and passthrough, and their SecurityPolicy, BackendTrafficPolicy, Backend, users Secret, EnvoyExtensionPolicy, SiparCachePolicy and SiparTCPAccessPolicy, all in the release’s namespace.