Skip to main content

Static Route

Static Routes define the entrypoint to static applications. This overcomes the limitation of OpenAPI specification that does not allow to define the entrypoint to a static application. It is useful to set up the routing to a non-API application, e.g. static pages or images or to route to legacy, possibly external to the cluster, APIs.

Once the resource manifest is deployed, Kusk Gateway Manager will use it to configure routing for the Envoy Fleet.


Static Routes assume entrypoints to your upstream hosts or services live at / For this reason, each StaticRoute must have its own dedicated EnvoyFleet

Currently, the resource status field is not updated by the manager when the reconciliation of the configuration finishes.

Configuration Structure Description

The main elements of the configuration are in the spec field.

Below is the YAML structure of the configuration. Please read further for a full explanation.

kind: StaticRoute
name: staticroute-sample
# Envoy Fleet (its name and namespace) to deploy the configuration to, here - deployed EnvoyFleet with the name "default" in the namespace "default".
# Optional, if not specified - single (default) fleet autodetection will be performed in the cluster.
name: default
namespace: default
hosts: [<string>, <string>, ...]
# ouath2 | jwt | cloudentity | custom
# host | service | rewrite
name: my-service
namespace: my-namespace
port: 80

Envoy Fleet

The spec.fleet optional field specifies to which Envoy Fleet (Envoy Proxy instances with the exposing K8s Service) this configuration applies. and fleet.namespace reference the deployed Envoy Fleet Custom Resource name and namespace.

You can deploy a Static Route configuration in any namespace with any name and it will be applied to the specific Envoy Fleet. If this option is missing, the autodetection will be performed to find the single fleet deployed in the Kubernetes cluster Fleet, which is then considered as the default Fleet. The deployed Static Route custom resource will be changed to map to that fleet accordingly. If there are multiple fleets deployed, spec.fleet is required to specify which in the manifest.

Request Matching

We match the incoming request by HOST header, path and HTTP method.

The following fields specify matching:

hosts - Defines the list of HOST headers to which the current configuration applies. This will create the Envoy's VirtualHost with the same name and domain matching. Wildcards are possible, e.g. "" means "any host". Prefix and suffix wildcards are supported, but not both (i.e. ```example.,, but not example*```).

upstream - Defines the upstream host or service to which the request will be forwarded.


kind: StaticRoute
name: sample
# should work with localhost,, any host
hosts: [ "localhost", "*"]
client_id: client_id
client_secret: client_secret
- openid
- email
- profile
callback_path: /callback
token_path: /oauth2/token
user_info_path: /userinfo
email: email
name: name
picture: picture
host: ""