Introduction: OpenAPI and Kubernetes Clusters
The OpenAPI specification has become ubiquitous in the modern world of developing APIs. It is a great way to describe and document your API.
A major benefit of OpenAPI is that it is machine-readable; i.e. software can be written that can “do stuff” based on the content of your OpenAPI definition.
Take, for example, SwaggerUI which provides a nice user-interface where developers can test and become familiar with your API, or openapi-generator that can generate clients and servers from your OpenAPI definition.
What if we took advantage of the machine readability of OpenAPI and had a machine configure your Kubernetes cluster for your API, based on the contents of its OpenAPI definition? We think this would make for an ideal kubernetes ingress controller.
Leveraging OpenAPI to Optimize Your Kubernetes Ingress Controller
Currently, to expose your API in Kubernetes, you need to write Ingress resources.
What is ingress?
Ingress is made up of routing rules that define how and where traffic is forwarded to your services, or a contract, if you will.
In addition to your Ingress resources, you need an ingress controller to update the state of the cluster and allow traffic to reach your applications based on your ingress configuration. You can see a lit of top ingress controllers over at kubernetes.io
Challenges with Current Ingress Controllers
The problem with traditional kubernetes ingress controllers is that they can be hard to learn and manage. Each has their own feature-set and uses their own resource formats that need to be learned. This is a difficult hurdle for those just starting out with Kubernetes.
Another issue that we contend with is getting a full picture of our application configuration.
Ingress configurations, like it or not, are part of it. Some Ingress controllers may have parts of their configuration spread across multiple resources, meaning that all of them have to be fetched. This issue is made worse when you factor in quality of service configuration, such as timeouts and retries which could also be their own resources.
Solution: OpenAPI Specification for Your Ingress Configuration
What about in a microservice architecture? A single OpenAPI specification describes an API that could be made of multiple microservices. However the ingress configuration requires dedicated Kubernetes resources.
Instead a better way would be to have a ‘single pane of glass’ view of the app’s configuration.
The OpenAPI specification itself is the perfect way to achieve this. OpenAPI already contains most of the information that you must specify in an Ingress configuration. OpenAPI is extensibile via extension annotations and given the ubiquity of OpenAPI, we can be confident in saying that API developers are comfortable with this format.
We at Kubeshop believe that OpenAPI should be enough to configure your application’s ingress. This prevents repeating yourself by redefining information already in your OpenAPI specification in Ingress resources. This also prevents needing to learn how to write Ingress resources
The Kusk Solution: an Ingress Controller That Understands OpenAPI.
We decided to address these issues by creating an Ingress controller that understands OpenAPI, Kusk Gateway.
All of the configuration you would keep in Ingress resources can now be kept in a single place (your OpenAPI definition), providing that single pane of glass configuration for your API thanks to our x-kusk extension.
Under the hood, Kusk Gateway is powered by Envoy Proxy, a battle-tested, and production-ready proxy that routes traffic to services defined in your OpenAPI specification.
Kusk and the Benefits of an OpenAPI-Compatible Ingress Controller:
- You don’t have to learn new configuration format(s) and create corresponding configurations for deploying your API under Kubernetes
- Your OpenAPI definition becomes the source-of-truth for both functional and QoS/deployment aspects of your API - instead of this information being spread out over multiple files
- You can rapidly iterate on your API without having to require DevOps resources - Kusk gateway will automatically (re)configure itself as the OpenAPI definition evolves with each iteration
- You don’t have to write boilerplate code that Kusk Gateway can provide out-of-the-box based on the OpenAPI definition: request-validation, mocking, metrics/analytics, security, etc.
- And something that benefits you that we would love to hear about.
Kusk Gateway Alpha is now available on GitHub. Despite being in alpha, has quite a lot of things going for it:
Automatically configure routing to your APIs using your OpenAPI definition
By embedding your OpenAPI spec in a Kusk Gateway API Custom Resource, applying it just like any other Kubernetes resource is all that’s required to fully configure routing to your API.
For more information, read our official API resource documentation
Configure Quality of Service and CORS settings from within OpenAPI
Using our supported annotation you can configure quality of service settings such as retries and timeouts as well as configuring CORS within your OpenAPI specification.
For more information, read our official CORS documentation
Support for routing to static resources such as CSS and Javascript
To facilitate the serving of static content with your APIs we have a custom resource for routing to these also.
For more information, read our official static resource documentation.
Kusk: An Ingress Controller to Maximize Your Application
We dare to say that the alpha release of Kusk Gateway is mature and stable enough for local development and evaluation. As we close gaps and add more features over the coming weeks (hopefully based on your feedback) we aim to release a production-ready version early next year.
Configuring and enjoying the powerful benefits of Ingress in Kubernetes shouldn’t be as cumbersome as it can be. Let Kusk Gateway do the heavy lifting for you so you can focus on what matters: your application!
If Kusk Gateway has piqued your interest, we would love to hear your feedback either in the form of an issue on Github or a direct message on our Discord Server.
And if you would like to help us evolve Kusk Gateway, we accept all contributions with open arms, whether that be documentation improvements, a bug fix (see our full documentation here) or even whole features.
Leave a star on the repo to stay updated on new features and improvements.
