Bahriya Tersane

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.