This post originally published on The New Stack

The management of large-scale infrastructure is increasingly turning toward GitOps and Infrastructure as Code. In the classic pets-vs.-cattle analogy (sorry to the vegans), these techniques allow you to easily replicate and replace infrastructure when things go wrong, dramatically reducing the cost and complexity of management.

In addition, they become a single source of truth to understand the current state of your infrastructure and what has changed.

At the same time, just like Software is eating the world, APIs are eating software. OK, maybe not eating, but certainly powering.

They are everywhere and have become the standard way to expose functionality. However, the way we currently create and build our APIs does not always match our best practices for running infrastructure.

Code-First vs. Design-First APIs

A code-first approach to APIs is a more traditional approach. Developers receive business requirements and code the API, leaving the formal documentation until later, or most commonly, not at all. Platform teams will be blocked until the initial release then be required to do a lot of manual testing to make sure everything is configured correctly.

On the other hand, in a design-first approach to API development, APIs are first defined then coded. This definition provides clear and unambiguous documentation and acts as the source of truth for all aspects of the teams development from frontend to backend to microservices, similar to the way Git becomes your source of truth in GitOps. Design-first APIs create a common understanding of both functional and non-functional aspects of your softwares behavior. In a nutshell, it answers the question: What can I make this API do?

Designing Your APIs

The OpenAPI specification has become ubiquitous in the modern world of developing APIs because it is a simple and standard way to describe and document your APIs. In addition, one major benefit of OpenAPI is that it is machine-readable. Based on the content of your OpenAPI definition, software can be written that interacts with your API. For example, Swagger UI provides a nice user interface where developers can test and become familiar with your API and OpenAPIGenerator can generate clients and servers from your OpenAPI definition.

Once defined, this definition can drive a multitude of downstream activities, including generating stubs to ensure developers adhere to the API, creating mocks to enable testing, building and integrating documentation, and constructing deployment artifacts. These tasks can often be done in parallel and in an automated fashion.

State of APIs in Kubernetes

Currently, to expose your API in Kubernetes, ingress resources need to be written and you will need an ingress controller, often referred to as an API gateway, to update the state of the cluster to allow traffic to reach your applications and services. Traditional ingress controllers can be hard to learn and manage and even when you do, it is a manual process. For every ingress controller you use, you need to learn their feature set, resource format(s) and configuration attributes. Some ingress controllers have their configuration spread across multiple Kubernetes resources, making it difficult to get a full picture of the applications configuration. This issue is made worse when you factor in quality-of-service configurations, such as timeouts and retries, which can be their own resources.

Therefore, to successfully deploy their APIs to Kubernetes, developers or their DevOps teammates currently need to spend their time learning new Kubernetes resource formats and keeping those up to date as their API evolves, rather than actually designing and implementing their APIs. And their DevOps engineers need to worry about developers tampering with meticulously crafted Helm charts rather than just writing their APIs!

Kubernetes needs a single pane of glass source of truth of the apps configuration and how the API works to bring it into the GitOps era.

Bringing GitOps to Your Kubernetes APIs With OpenAPI and Kusk

The OpenAPI specification gives us the ability to declaratively define APIs. It also already contains most of the information we need for an ingress configuration, is extensible via extension annotations, and given the ubiquity of OpenAPI, many API developers are comfortable with this format. Using OpenAPI as a source of truth reduces repetition by bringing information already in your OpenAPI specification into ingress resources. It also eliminates the need to learn how to write ingress resources.

Enter Kusk and Kusk Gateway, an open source attempt to fill that gap in the OpenAPI-Kubernetes toolchain.

(overly simplified Kusk workflow)
These are the basics of Kusk Gateway.

Kusk (Swedish for coachman) automates the generation of ingress resources for various popular ingress controllers by treating your OpenAPI specification as the source of truth for their configuration. Kusk currently supports generating configurations for Ambassador, Traefik, Linkerd and Nginx-Ingress. And thanks to an x-kusk OpenAPI extension, API developers can add Kubernetes and QoS-related metadata to their OpenAPI definition, which Kusk will automatically transform to ingress-controller-specific configurations, including things like:

• CORS configuration
• Timeouts
• Mapping transformations
• Namespace/service configuration
• Rate-limiting
• more to come (security, etc.)

Platform teams can feed Kusk the APIs specification and have ingress resources ready to go and up to date with any changes being made to the API. And just like with GitOps, this can be automated as part of the CI/CD pipeline, meaning no manual editing and fewer errors.

While Kusk helps you adopt an OpenAPI-first approach to API development with an existing ingress controller, it doesnt really allow you to tap into the full potential of your OpenAPI definition, which is why the Kusk project also includes a dedicated ingress controller that uses OpenAPI as its primary source of configuration: Kusk Gateway. Using Kusk Gateway as the ingress controller, API developers and DevOps engineers can use an OpenAPI definition directly to configure the exposure of their APIs no intermediate configuration generation necessary!

The Kusk Gateway approach to OpenAPI-first development provides a number of benefits:

• Engineers dont have to learn new configuration format(s) and create corresponding configurations for deploying APIs on Kubernetes.
• The OpenAPI definition becomes the source of truth for both functional and QoS/deployment aspects of an API instead of this information being managed in separate configuration files.
• Developers can rapidly iterate on their API without having to require platform team resources. Kusk Gateway will automatically (re)configure itself as the OpenAPI definition evolves.

• Developers dont have to write boilerplate code that Kusk Gateway can provide out of the box based on the OpenAPI definition, for example:

• Request-validation Kusk Gateway can automatically validate incoming requests against an OpenAPI definition and provide API consumers with helpful error messages, providing a better user experience and eliminating the need for developers to write this logic themselves.

• Mocking Kusk Gateway can automatically provide mocks and sandboxes for exposed APIs, helping API consumers simulate different scenarios while they are integrating with an API without burdening the underlying API with these requests.

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.

Wrapping Up

If youre adopting a design-first approach for your APIs (which you should be!) and are moving into Kubernetes, Kusk enables you to:

• Adopt an iterative OpenAPI-first development workflow for APIs under Kubernetes.
• Harness all the greatness of an OpenAPI definition in your API deployment.
• Integrate OpenAPI-first with both traditional and GitOps-based deployment workflows.
• Give Kusk or Kusk Gateway a try and let us know if it does (or doesnt) help your developers and/or platform engineers improve their everyday API development workflows.

Check out the GitHub repo and full documentation to learn more about Kusk and Kusk Gateway and download their latest releases. Leave a star on the repo to stay updated on new features and improvements, and join our Discord community to connect with others and get in touch with the Kusk team on any issues or suggestions you might have. Were looking forward to it!

The New Stack is a wholly owned subsidiary of Insight Partners, an investor in the following companies mentioned in this article: Ambassador Labs.