kusk-gateway

README

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

• Kusk Gateway
• Table of contents
• Get Started
  • Installation
  • Usage
    • API CRD Example
  • Custom Resources
  • Roadmap
  • Troubleshooting
• Development
• Contribute
• License

Get Started

See the architecture document for an overview of the Kusk Gateway architecture

Installation

(Back to top)

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

(Back to top)

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

(Back to top)

See Custom Resources for more information on the Custom Resources that Kusk Gateway supports.

Roadmap

(Back to top)

For the list of the currently supported and planned features please check the Roadmap.

Troubleshooting

(Back to top)

See the Troubleshooting for how to troubleshoot the Kusk Gateway problems.

Development

(Back to top)

See our Development document for how to develop Kusk Gateway.

Contribute

(Back to top)

• 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.

License

(Back to top)

MIT