Skip to main 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.

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

Available Properties

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.*
openapi.yaml
x-kusk:
hosts:
- onehost.com

Read more in the guide on Routing.

CORS

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

NameDescription
cors.originsList of HTTP origins accepted by the configured operations.
cors.methodsList of HTTP methods accepted by the configured operations.
cors.headersList of HTTP headers accepted by the configured operations.
cors.expose_headersList of HTTP headers exposed by the configured operations.
cors.credentialsBoolean flag for requiring credentials.
cors.max_ageIndicates how long results of a preflight request can be cached.

Sample:

openapi.yaml
x-kusk:
cors:
origins:
- "*"
methods:
- POST
- GET
- OPTIONS
headers:
- Content-Type
credentials: true
max_age: 86200

Read more in the guide on CORS.

QoS

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

NameDescription
qos.retriesMaximum number of retries (0 by default).
qos.request_timeoutTotal request timeout (in seconds).
qos.idle_timeoutTimeout for idle connections (in seconds).

Sample:

openapi.yaml
x-kusk:
qos:
request_timeout: 60

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.

Sample:

openapi.yaml
x-kusk:
websocket: true

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.

NameDescription
upstream.rewrite.patternRegular expression.
upstream.rewrite.substitutionRegular expression substitution.

Sample:

openapi.yaml
x-kusk:
upstream:
service: ...
# /foo/bar/... -> to upstream: /bar/...
rewrite:
pattern: "^/foo"
substitution: ""

Service

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

NameDescription
upstream.service.namespaceThe namespace containing the upstream Service.
upstream.service.nameThe upstream Service's name.
upstream.service.portThe upstream Service's port. Default value is 80.

Sample:

openapi.yaml
---
x-kusk:
upstream:
service:
namespace: default
name: svc-name
port: 8080

Host

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

NameDescription
upstream.host.hostnameThe hostname to route traffic to.
upstream.host.portThe 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).

Sample:

openapi.yaml
x-kusk:
upstream:
host:
hostname: example.org
port: 80

Path

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

NameDescription
path.prefixPrefix 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.

Sample:

openapi.yaml
x-kusk:
path:
prefix: /v1

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.

NameDescription
redirect.scheme_redirectRedirect scheme (http/https).
redirect.host_redirectHost to redirect to.
redirect.port_redirectPort to redirect to.
redirect.path_redirectPath to redirect to.
redirect.rewrite_regex.patternRegular expression (mutually exclusive with path_redirect).
redirect.rewrite_regex.substitutionRegular expression substitution.
redirect.strip_queryBoolean, configures whether to strip the query from the URL (default false).
redirect.response_codeRedirect response code (301, 302, 303, 307, 308).

Sample:

openapi.yaml
---
x-kusk:
redirect:
scheme_redirect: https
host_redirect: thenewhost.com
response_code: 302

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

Validation

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

NameDescription
validation.request.enabledBoolean flag to enable request validation.

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

Sample:

openapi.yaml
---
x-kusk:
validation:
request:
enabled: true

Mocking

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

NameDescription
mocking.enabledBoolean flag to enable mocking.

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

Sample:

openapi.yaml
---
x-kusk:
mocking:
enabled: true

Rate limiting

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

NameDescription
rate_limit.requests_per_unitHow many requests API can handle per unit of time.
rate_limit.unitUnit of time, can be one of the following: second, minute, hour .
rate_limit.per_connectionBoolean flag, that specifies whether the rate limiting, should be applied per connection or in total. Default: false.
rate_limit.response_codeHTTP 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.

Sample:

openapi.yaml
x-kusk:
rate_limit:
requests_per_unit: 2
unit: minute

Caching

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

NameDescription
cache.enabledBoolean flag to enable request validation.
cache.max_ageIndicates how long (in seconds) results of a request can be cached.

Sample:

openapi.yaml
x-kusk:
cache:
enabled: true
max_age: 60

Authentication

The auth object allows 4 different auth mechanism:

  • oauth
  • custom
  • cloudentity
  • jwt

JWT

For further details, for now please see the JWT guide.

NameDescription
auth.jwt.issuerRequired. Defines the issuer of your JWT token.
auth.jwt.audiencesOptional. Defines the audiences/identifier of your JWT token.
auth.jwt.jwksRequired. Defines the JWKS of your JWT provider.

Sample:

openapi.yaml
x-kusk:
auth:
jwt:
issuer: https://jwtissuer.com
audiences:
- http://example-audience
jwks: https://jwtdomain.com/.well-known/jwks.json

Cloudentity

For more details on this authorization flow, check the guide on how to use Cloudentity with Kusk.

NameDescription
auth.cloudentity.hostRequired. Defines how to reach the Cloudentity Authorizer host.
auth.cloudentity.host.hostnameRequired. Defines the hostname of the Cloudentity Authorizer in the cluster.
auth.cloudentity.host.portRequired. Defines the port of the Cloudentity Authorizer in the cluster.

Sample:

openapi.yaml
x-kusk:
auth:
cloudentity:
host:
hostname: cloudentity-authorizer-standalone-authorizer.kusk-system
port: 9004

Custom Authorization

Check the Custom Authorization guide for more details on how to secure your APIs with your own custom auth service.

NameDescription
auth.custom.hostRequired. Defines how to reach the authorization service.
auth.custom.host.hostnameRequired. Defines the hostname of the authorization service in the cluster.
auth.custom.host.portRequired. Defines the port of the authorizastion service in the cluster.

Sample:

openapi.yaml
x-kusk:
auth:
custom:
host:
hostname: example.com
port: 80

OAuth2 via OIDC

Check the OAuth guide for more details on how to set up OAuth for your APIs.

NameDescription
auth.oauth2.token_endpointRequired.Defines the token_endpoint, e.g., the field token_endpoint from https://kubeshop-kusk-gateway-oauth2.eu.auth0.com/.well-known/openid-configuration.
auth.oauth2.credentials.client_idRequired.Defines the Client ID.
auth.oauth2.credentials.client_secret Required.Defines the Client Secret.
auth.oauth2.redirect_uriRequired.The redirect URI passed to the authorization endpoint.
auth.oauth2.signout_pathRequired.The path to sign a user out, clearing their credential cookies.
auth.oauth2.redirect_path_matcherRequired.After a redirecting the user back to the redirect_uri, using this new grant and the token_secret, the kusk-gateway then attempts to retrieve an access token from the token_endpoint. The kusk-gateway knows it has to do this instead of reinitiating another login because the incoming request has a path that matches the redirect_path_matcher criteria.
auth.oauth2.forward_bearer_tokenRequired.If the Bearer Token should be forwarded, you generally want this to be true. When the authn server validates the client and returns an authorization token back to kusk-gateway, no matter what format that token is, if forward_bearer_token is set to true kusk-gateway will send over a cookie named BearerToken to the upstream. Additionally, the Authorization header will be populated with the same value, i.e., Forward the OAuth token as a Bearer to upstream web service.
auth.oauth2.auth_scopes Optional.Optional list of OAuth scopes to be claimed in the authorization request. If not specified, defaults to user scope. OAuth RFC https://tools.ietf.org/html/rfc6749#section-3.3.
auth.oauth2.resourcesOptional.Optional list of resource parameters for authorization request RFC: https://tools.ietf.org/html/rfc8707.

The example below ensures the whole API is protected via OAuth2.

api.yml
x-kusk:
auth:
oauth2:
token_endpoint: *TOKEN_ENDPOINT* # <- for example https://yourdomain.eu.auth0.com/oauth/token
authorization_endpoint: *AUTHORIZATION_ENDPOINT* # <- for example https://yourdomain.eu.auth0.com/authorize
credentials:
client_id: *CLIENT_ID*
client_secret: *CLIENT_SECRET*
redirect_uri: /oauth2/callback
redirect_path_matcher: /oauth2/callback
signout_path: /oauth2/signout
forward_bearer_token: true
auth_scopes:
- openid

Exposing OpenAPI defintion

The public_api_path field takes a path name and will expose your OpenAPI definition at the defined path.

Sample:

openapi.yaml
x-kusk:
public_api_path: openapi.json

This will expose your entire OpenAPI definition, without the Kusk extensions, on yourdomain.com/openapi.json.

To remove some paths or operations from the exposed OpenAPI, use the disabled option.

Disabled

This boolean property allows you to hide the corresponding path/operation from being configured by Kusk and in turn a request will return a 404 HTTP code.

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

openapi.yaml
/path:
x-kusk:
disabled: true