Hello Kusk
Adopting a design-first approach to REST API development with OpenAPI brings many niceties to your API development smörgåsbord. The possibility to generate consistent clients, servers, documentation, tests, etc has many merits in complex projects and architectures, and there are a variety of tools out there to help with this approach, including collaborative design tooling, artefact generators, and more.
When entering the world of cloud-native development the lack of tooling that extends this approach to embrace kubernetes and related artefacts surprised me; an OpenAPI definition could well be the source-of-truth for a multitude of kubernetes resources related to deploying an API; ingress controllers, monitoring, security, health-checks, etc are all things that have to be set up manually for an API when deploying it to a cluster, but doing so is a hassle for developers new to kubernetes. As an API developer I’d rather spend my time designing and implementing my APIs, than learning new k8s resource formats and keeping those up-to-date as my API evolves. And as a DevOps engineer I’d rather my developers focus on their APIs instead of tampering with my meticulously crafted helm-charts!
Enter Kusk — an attempt to fill that gap in the OpenAPI-kubernetes toolchain!
Kusk (swedish for coachman) does exactly this; it’s a command-line tool that generates kubernetes resources based on an OpenAPI definition. Initially it supports generating configurations for Ambassador, Linkerd and Nginx-Ingress — and thanks to an x-kusk OpenAPI extension you can add kubernetes and QoS-related metadata to your OpenAPI definition that Kusk will automatically transform to tool-specific configurations, including;
- CORS configuration
- Timeouts
- Mapping transformations
- Namespace/service configuration
- more to come! (rate-limiting, security, etc.)
For example adding the following extension to your OpenAPI definition:
will ensure that your API is CORS enabled (yay!), exposed at /api/v3 and maps to a petstore service on port 8001.
That last service configuration might not be your cup-of-tea — managing cluster-specific settings should perhaps be done by the DevOps-people managing your cluster and not exposed in an OpenAPI definition. Fortunately Kusk allows you to set (or override) most of these properties from the command-line— so running
and leaving those properties away from the extension might be the preferred approach for you — the choice is yours.
We’ve made sure that Kusk works well with both manual and automated workflows and have to that end written a tutorial showing you how to set up Kusk with ArgoCD; Argo will invoke Kusk to generate resources — and then sync them to your cluster — API magic! — check it out!
If you’re well versed in the OpenAPI ecosystem you might wonder how Kusk is different from existing code-generators?! Good point — there are currently two primary differences;
- Kusk has the ability to inspect an existing cluster and automatically generated resources for the tools it find in the cluster.
- A roadmap item for Kusk is a dedicated Kubernetes Operator that automatically keeps your cluster configuration in sync with your OpenAPI definitions; no need to run any tools at all!
Kusk is just getting started and we’d love to hear your thoughts on this — how does it (or does it not) work with your OpenAPI workflow? What else could we generate or integrate? Please let us know!
- Get Kusk on GitHub
- Check out the Kusk documentation
Kusk is the second project brought to you by Kubeshop (Open-Source Accelerator/Incubator) — the first being Monokle — a tool for kubernetes manifest management — check that out too.
