Skip to content

OpenAPI Extension Reference

Kusk Gateway comes with an OpenAPI extension to accommodate everything within an OpenAPI spec to create a source of truth for the operational behaviour of your API.

The x-kusk extension has the following structure:

x-kusk:
  hosts:
    - example.com

  disabled: false

  validation:
    request:
      enabled: true # enable automatic request validation using OpenAPI definition
  mocking:
    enabled: true # Enables mocking of the responses using examples in OpenAPI responses definition.
  upstream: # upstream and redirect are mutually exclusive
    host: # host and service are mutually exclusive
      hostname: example.com
      port: 80
    service: # host and service are mutually exclusive
      namespace: default
      name: petstore
      port: 8000
    rewrite:
      pattern: 'regular_expression'
      substitution: 'substitution'

  redirect: # upstream and redirect are mutually exclusive
    scheme_redirect: https
    host_redirect: example.org
    port_redirect: 8081

    path_redirect: /index.html # path_redirect and rewrite_regex are mutually exclusive
    rewrite_regex: # path_redirect and rewrite_regex are mutually exclusive
      pattern: 'regular_expression'
      substitution: 'substitution'

    response_code: 308
    strip_query: true


  path:
    prefix: /api

  qos:
    retries: 10
    request_timeout: 60
    idle_timeout: 30
  cors:
    origins:
      - "*"
    methods:
      - POST
      - GET
      - OPTIONS
    headers:
      - Content-Type
    credentials: true
    expose_headers:
      - X-Custom-Header1
      - X-Custom-Header2
    max_age: 86200
  websocket: true

  rate_limit:
    requests_per_unit: 2
    unit: minute
    per_connection: false
    response_code: 429

  cache:
    enabled: true
    max_age: 10

Check out the OpenAPI Extension Guide to configure the operational aspects of your API.

Available Properties

Disabled

This boolean property allows you to disable the corresponding path/operation, "hiding" internal operations from being published to end users.

When set to true at the top level, all paths will be hidden; you will have to override specific paths/operations with disabled: false to make those operations visible.

Hosts

This string array property configures the hosts (i.e. Host HTTP header) list the Gateway will listen traffic for. Wildcard hosts are supported in the suffix or prefix form, exclusively, i.e.:

  • *.example.org
  • example.*

Read more in the Guide on Routing.

CORS

The CORS object sets properties for configuring CORS for your API.

Name Description
origins List of HTTP origins accepted by the configured operations.
methods List of HTTP methods accepted by the configured operations.
headers List of HTTP headers accepted by the configured operations.
expose_headers List of HTTP headers exposed by the configured operations.
credentials Boolean flag for requiring credentials.
max_age Indicates how long results of a preflight request can be cached.

Read more in the guide on CORS.

QoS

Options for configuring QoS settings, such as retries and timeouts.

Name Description
retries Maximum number of retries (0 by default).
request_timeout Total request timeout (in seconds).
idle_timeout Timeout for idle connections (in seconds).

Read more in the Guide on Timeouts.

Websocket

An optional boolean field that defines whether to enable handling of "Upgrade: websocket" and other actions related to Websocket HTTP headers in the request to create a Websocket tunnel to the backend. The default value is false - don't handle Websockets.

Upstream

This setting configures where the traffic goes. service and host are available and are mutually exclusive. The upstream setting is mutually exclusive with redirect setting.

service is a reference to a Kubernetes Service inside the cluster, while host can reference any hostname, even outside the cluster.

See the Guide on Routing to learn more about this functionality.

Rewrite

Additionally, upstream has an optional object rewrite. This allows modification of the URL of the request before forwarding it to the upstream service.

Name Description
rewrite.pattern Regular expression.
rewrite.substitution Regular expression substitution.

Service

The service object sets the target Kubernetes service to receive traffic. It contains the following properties:

Name Description
namespace The namespace containing the upstream Service.
name The upstream Service's name.
port The upstream Service's port. Default value is 80.

Host

The host object sets the target host to receive traffic. It contains the following properties:

Name Description
hostname The hostname to route traffic to.
port The target port to route traffic to.

Note: service and host are mutually exclusive since they define the same thing (the upstream host to route to).

Path

The path object contains the following properties to configure service endpoints paths:

Name Description
prefix Prefix for the route ( i.e. /your-prefix/here/rest/of/the/route ). Default value is "/".

If the upstream.rewrite option is not specified, the upstream service will receive the request "as is" with this prefix still appended to the URL. If the upstream application doesn't know about this path, usually 404 is returned.

See the Guide on Routing to learn more about this functionality.

Redirect

Configures where to redirect the request. The redirect and upstream options are mutually exclusive.

Name Description
scheme_redirect Redirect scheme (http/https).
host_redirect Host to redirect to.
port_redirect Port to redirect to.
path_redirect Path to redirect to.
rewrite_regex.pattern Regular expression (mutually exclusive with path_redirect).
rewrite_regex.substitution Regular expression substitution.
strip_query Boolean, configures whether to strip the query from the URL (default false).
response_code Redirect response code (301, 302, 303, 307, 308).

See the Guide on Routing to learn more about this functionality.

Validation

The validation objects contain the following properties to configure automatic request validation:

Name Description
validation.request.enabled Boolean flag to enable request validation.

See the Guide on Validation to learn more about this functionality.

Note: Currently, mocking is incompatible with the validation option - the configuration deployment will fail if both are enabled.

Mocking

The validation objects contain the following properties to configure automatic request validation:

Name Description
mocking.enabled Boolean flag to enable mocking.

See the Guide on Mocking to learn more about this functionality.

Note: Currently mocking is incompatible with the validation option - the configuration deployment will fail if both are enabled.

Rate limiting

The rate_limit object contains the following properties to configure request rate limiting:

Name Description
rate_limit.requests_per_unit How many requests API can handle per unit of time.
rate_limit.unit Unit of time, can be one of the following: second, minute, hour .
rate_limit.per_connection Boolean flag, that specifies whether the rate limiting, should be applied per connection or in total. Default: false.
rate_limit.response_code HTTP response code, which is returned when rate limiting. Default: 429, Too Many Requests.

Note: Currently, rate limiting is applied per Envoy pod - if you have more than a single Envoy pod the total request capacity will be bigger than specified in the rate_limit object. You can check how many Envoy pods you run in the spec.size attribute of EnvoyFleet object.

Caching

The cache object contains the following properties to configure HTTP caching:

Name Description
cache.enabled Boolean flag to enable request validation.
cache.max_age Indicates how long (in seconds) results of a request can be cached.

Note: current support for caching is experimental. Check out https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/cache_filter to learn more about how it works.

Authentication

The auth object contains the following properties to configure HTTP authentication:

Name Description
scheme Required. The authentication scheme. Only basic authentication is supported at the moment.
path_prefix Optional. The prefix to attach to auth-upstream.host.hostname
auth-upstream Required. Defines the upstream authentication host.
auth-upstream.host Required. Defines how to reach the authentication server.
auth-upstream.host.hostname Required. Defines the hostname the authentication server is running on.
auth-upstream.host.port Required. Defines the port the authentication server is running on, for the given auth-upstream.host.hostname.

Sample

...
x-kusk:
...
  auth:
    scheme: basic
    path_prefix: /login # optional
    auth-upstream:
      host:
        hostname: example.com
        port: 80
...