Kusk Gateway
Kusk Gateway is a self-service API gateway powered by OpenAPI and Envoy.
Kusk Gateway is for you if:
- You or your team develop REST APIs running in Kubernetes
- You embrace a contract-first approach to developing your APIs using OpenAPI or Swagger
- You want to ramp-up time when deploying a new REST api to a cluster and you don't want to spend lots of time configuring ingress controllers that require a dedicated Ops Engineer
- You want your REST API endpoints traffic to be observable and controllable with the easy to use settings
Kusk Gateway has a unique way to the configuration among other API gateways as it configures itself through the metadata defined in your OpenAPI or Swagger document.
You can apply your API definition like any other Kubernetes resource using our custom-made Kusk API CustomResourceDefinition.
Table of contents
Get Started
See the architecture document for an overview of the Kusk Gateway architecture
Installation
Kusk Gateway can be installed on any cloud or bare metal Kubernetes cluster.
If you want to quickly setup and evaluate the Kusk Gateway, then please use the local installation instructions with Minikube.
Otherwise see our Installation document for how to install the Kusk Gateway to Kubernetes.
For the quick and impatient:
# Install Kubeshop Helm repo and update it
helm repo add kubeshop https://kubeshop.github.io/helm-charts && helm repo update
# Install the Kusk Gateway with CRDs into kusk-system namespace.
# We need to wait for the kusk-gateway-manager deployment to finish the setup for the next step.
helm install kusk-gateway kubeshop/kusk-gateway -n kusk-system --create-namespace &&\
kubectl wait --for=condition=available --timeout=600s deployment/kusk-gateway-manager -n kusk-system
# Install the "default" EnvoyFleet Custom Resource, which will be used by the Kusk Gateway
# to create Envoy Fleet Deployment and Service with the type LoadBalancer
helm install kusk-gateway-envoyfleet-default kubeshop/kusk-gateway-envoyfleet -n kusk-system
Usage
Kusk Gateway configures itself via the API CRD that contains your embedded Swagger or OpenAPI document.
The easiest way to get started is to go through ToDoMVC example.
See also x-kusk extension documentation and Custom Resources for the guidelines on how to add the necessary routing information to your OpenAPI file and Kusk Gateway.
After that all that's required is to apply it as you would any other Kubernetes resource.
API CRD Example
apiVersion: gateway.kusk.io/v1
kind: API
metadata:
name: httpbin-sample
spec:
# service name, namespace and port should be specified inside x-kusk annotation
spec: |
swagger: '2.0'
info:
title: httpbin.org
description: API Management facade for a very handy and free online HTTP tool.
version: '1.0'
x-kusk:
validation:
request:
enabled: true # enable automatic request validation using OpenAPI spec
upstream:
service:
name: httpbin
namespace: default
port: 8080
path:
# allows to serve under /api prefix
prefix: "/api"
# removes prefix when sending to upstream service
rewrite:
pattern: "^/api"
substitution: ""
paths:
"/get":
get:
description: Returns GET data.
operationId: "/get"
responses: {}
"/delay/{seconds}":
get:
description: Delays responding for nโ10 seconds.
operationId: "/delay"
parameters:
- name: seconds
in: path
description: ''
required: true
type: string
default: 2
enum:
- 2
responses: {}
...
Custom Resources
See Custom Resources for more information on the Custom Resources that Kusk Gateway supports.
Roadmap
For the list of the currently supported and planned features please check the Roadmap.
Troubleshooting
See the Troubleshooting for how to troubleshoot the Kusk Gateway problems.
Development
See our Development document for how to develop Kusk Gateway.
Contribute
- Check out our Contributor Guide and Code of Conduct
- Fork/Clone the repo and make sure you can run it as shown above
- Check out open issues here on GitHub
- Get in touch with the team by starting a discussion on GitHub or on our Discord Server.
- or open an issue of your own that you would like to contribute to the project.