kubeshop/kusk-gen

Kusk Gen generates Ingress-controller configurations from your OpenAPI definition

kusk-gen - use OpenAPI to configure Kubernetes

What is kusk-gen?

Developers deploying their REST APIs in Kubernetes shouldn't have to worry about managing resources that do not directly relate to their applications or services.

kusk-gen (coachman in Swedish) treats your OpenAPI/Swagger definition as a source of truth for generating supplementary Kubernetes resources for your REST APIs in regard to mappings, security, traffic-control, monitoring, etc.

Read the Introductory blog-post to get an overview.

Quick Start

Homebrew

brew install kubeshop/kusk/kusk-gen

Latest release on Github

go install github.com/kubeshop/kusk-gen@$VERSION

If you don't want to build it yourself, the Releases page contains already built binaries for all supported platforms.

Download it and unpack kusk-gen to the directory of you choice.

From source

git clone [email protected]:kubeshop/kusk-gen.git && \
cd kusk-gen && \
go install

Read more at Getting Started

Why kusk-gen?

Using OpenAPI as the source-for-truth for client, servers, testing, documentation, etc. is a common approach when building microservice architectures with REST APis. Kusk extends this paradigm to also include Kubernetes configurations, allowing you to

• Cut down on development time when deploying your REST APIs to your clusters
• Remove the need to learn tools-specific formats and configurations
• Easily switch between supported tools without having to learn new formats/configurations

Features

• kusk-gen can inspect your cluster for the tools it supports and generate corresponding resources automatically.
• the Kusk OpenAPI Extension allows you to specify extended QoS and k8s related metadata which will be used to configure your cluster accordingly.
• kusk-gen plays nicely with both manual and automated/GitOps/CD workflows.
• The underlying architecture makes it straight-forward to extend kusk-gen with new generators

kusk-gen currently supports (click for configuration options)

• Ambassador 1.x
• Ambassador 2.0
  • Warning This is a developer preview and should be treated as unstable
• Linkerd
• Ingress-Nginx
  • This generator refers to the community ingress from Kubernetes ingress-nginx
• Traefik V2 (v2.x)

Some of the upcoming tools we'd like to support are Kong and Contour. Please don't hesitate to suggest others or contribute your own generator!

Documentation & Support

To learn more about kusk-gen check out the complete documentation

Join our Discord Server to ask questions, suggest ideas, etc.

How to 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.
• Fly like the wind!

kusk-gen's Issues

Detect and show available generators for a given cluster

Support timeouts for Linkerd and Ambassador

We should support timeouts for Linkerd, Ambassador, nginx-ingress.

This would include adding both a global and path/operation-level option.

bug: nginx-ingress path.split = true doesn't generate an ingress per route

When the path.split option is set to true, the nginx-ingress generator ignores it.

If path.split is set to true, it should force the generation of separate ingress resources for each route in the OpenAPI specification

documentation: README.md

ambassador: support host parameter

https://www.getambassador.io/docs/edge-stack/latest/topics/using/headers/host/

Detect Linkerd in Kubernetes Cluster

extension: OperationOptions extension

Design and implement an operation-level OpenAPI extension that would allow i.e. disable a specific operation or configure some settings such as CORS or rate limiting on a path-based level.

The definition would perhaps reside in options package. The code to extract it from openapi3.Operation.ExtensionProps would most likely be in spec package.

Features:

• enable/disable
• cors origins
• rate limit in requests per second ?

Issues to implement in generators would follow:

• #45
• #46
• #47

Prepare GitHub Project and Discussions for release

We might want to do some grooming / labelling of the existing GitHub project - and use the Discussions feature for engaging with users on new features? (i'll enable it so you can have a look)

CLI command for generating Ambassador mappings

This is a tracking issue for the CLI tool.
CLI tool is meant to be used by an end user in order to generate manifests and config based on OpenAPI spec.

• Basic features (generation options, help, etc)
• #7
• Tests

kubernetes/ingress-nginx support

ingress-nginx is a popular OSS Ingress for Kubernetes. Things we can support:

• basic routing
• url rewrite - we have this in Ambassador (TrimPrefix option), we need to generalise this
• ratelimiting
• timeouts
• CORS

wizard: print the constructed command

The original idea of making a wizard was to guide user into kusk and provide him with a CLI command that he can embed into his CI scripts.

Documentation and examples

wizard: pre-fill options with information from x-kusk extension

OpenAPI 2 support

We need to be able to parse and use OpenAPI 2.x specs (both YAML and JSON).

wizard: support path.base option for linkerd

Documentation: Nginx Ingress generator

Common Options for all generators

Instead of a separate Options struct for each generator, we need to have a single Options that would be filled in from various sources (command line flags, kusk OpenAPI extension, .kusk config file etc).

Some basic options can be top-level, the other ones should be grouped into whatever makes more sense, i.e.:

type Options struct {
   TargetServiceNamespace string
   TargetService  string
   IngressOptions IngressOptions
}

Support path/operation options within nginx-ingress generator

We should support overriding options within paths/operations just like we do in Ambassador.
I.e. decide whether to split routes if settings differ from global's.

Documentation: Ambassador generator

options: move cors and host to root-level options, get rid of ingress field

Linkerd Service Profiles support

We can generate Linkerd Service Profiles from OpenAPI spec.

There's a built-in support for this in Linkerd, but it only supports OpenAPI 2.x and it cannot generate Service Profiles on-demand (i.e. there's no Operator for this).

• Basic service profile generation
• OpenAPI 2 support
• OpenAPI 3 support
• Tests
• Documentation

cli: add version command

Ambassador 2.x support

Ambassador 2.x has recently reached Developer Preview.
Brief 2.x changes: link.

• Implement x.getambassador.io/v3alpha1 CRDs generation
• Tests (?)
• Documentation
• Provide a complete runnable example including AmbassadorHost, AmbassadorListener, AmbassadorMapping.

ci: automatic Github releases and artifact packaging

Documentation: README.md

nginx-ingress cmd is not present

The init function is not loaded because the package is never imported explicitly.

Ambassador 1.x support

We need to be able to generate Ambassador Mappings for the given OpenAPI spec.

• Basic generation
• OpenAPI 3 support
• #8
• Generate mapping name
• Custom base path (prefix)
• Configurable prefix trimming for request path (rewrite feature)
• #6

Documentation: Linkerd generator

Interactive CLI interface

an example session:

kusk petstore.yaml
OpenAPI 3 detected...
Would like to connect to your cluster using local kubectl config to detect available generators? [y/n]
y
Connecting to your cluster [current-context]...
Ambassador 1.13 detected. Would you like to generate Mapping CRDs? [y/n]
y
Choose an option:
[1]: Generate a single Mapping for the Service
[2]: Generate a single Mapping for each Operation

and after that, it would print something like that:

kusk generate -i petstore.yaml --generator=ambassador --service-name=petstore --service-namespace=default --root-only=true

Validation and defaults

I suggest we use a common validation and default-filling code for the whole Options struct where appropriate (i.e. the Service suboptions should always be filled to select a target service to route traffic into), and have separate validators (and default filling) in generators, i.e. Cluster.ClusterDomain field should only be validated in generators that require it (linkerd).

Implement OperationOptions extension in nginx-ingress (enable/disable, cors)

kusk-specific OpenAPI extension

We strive to make an OpenAPI spec a source of truth for all generators.
We can make an OpenAPI extension to allow users define parameters in their OpenAPI spec:

openapi: 3.0.2
info:
  title: Swagger Petstore - OpenAPI 3.0
  version: 1.0.5

# top-level extension applies to all operations, unless overridden
x-kusk:
  serviceName: petstore
  serviceNamespace: default

  # some fields are generic and therefore don't have an explicit subobject
  cors: [array of origins here]  
  basePath: /petstore/api/v3
  trimPrefix: /petstore
  rootOnly: true
  
  # some fields are not generic and only apply to a specific service we support
  ambassador:
    ambassadorNamespace: ambassador

paths:
  "/pet":
    put:
      # operation-level extension overrides the top-level one
      x-kusk:
        cors: []
      operationId: updatePet
      responses:
        '200':
          description: Successful operation

Of course, we'd need to leave an option to use CLI parameters (and they will prevail over everything else). One of the reasons for the end user to use CLI parameters and OpenAPI spec is, for example, the deployment of the same service to different environments, i.e. user wants to deploy petstore into different namespaces (dev/prod/whatever).

The example how to parse an extension can be found here: https://github.com/getkin/kin-openapi/blob/master/openapi3/extension_test.go#L12

ci: make kusk installable via brew

Support timeouts for nginx-ingress

Documentation: contribution guide

Generators package

generators package is meant to be a common place for subpackages that are responsible for generation of necessary manifests, configs etc for different platforms we support.

• common configuration options
• common interface (?)
• #1
• #3
• contribution guide

CORS extension

Some ingress controllers have built-in support for CORS operations: Ambassador, NGINX.

We can design and implement an OpenAPI extension that would allow users to enable CORS support for their endpoints, i.e.

openapi: 3.0.2
info:
  title: Swagger Petstore - OpenAPI 3.0
  version: 1.0.5
paths:
  "/pet":
    put:
      x-kusk:
         cors: <here it goes>
      operationId: updatePet
      responses:
        '200':
          description: Successful operation

Documentation: using kusk as ArgoCD configuration management plugin

kubernetes/ingress-nginx support

We can generate routing, CORS and rate limiting for kubernetes/ingress-nginx controller.

wizard: add support for nginx-ingress

Ambassador 1.x port

It seems that we forgot to add a port option. Yikes.

wizard: add timeout options

cmd: rename interactive to wizard 🪄

Also detect whether or not it's a TTY and give an error if it's not.
https://github.com/mattn/go-isatty

wizard: add CORS options

Implement OperationOptions extension in Linkerd (enable/disable)

Implement OperationOptions extension in Ambassador (enable/disable, cors)

generators: common generator interface

This would simplify adding new generators and open a possibility to bring out-of-tree generators (plugins?).

cmd: provide options to override x-kusk extension settings

Once #15 is done we'd need to have a bunch of command line flags to override appropriate settings via CLI.

I'd expect a flag set being available to override to be individual for each available generator, i.e. kusk ambassador command would only allow (and therefore show in --help mode) to set flags that are used by ambassador generator (base path, trim prefix etc) and NOT contain --cluster-domain flag which is to be used in linkerd.

Ambassador 1.x tests

Currently we can do with table tests.
E2E tests are possible with something like k3d, but for now we'll just test the generated mappings output.

Support Base prefix for Linkerd

It should be possible to have a prefix configurable for a Service Profile. We already have an option for that (path.base), we might just use that.

A matching flag would also need to be added [here].(https://github.com/kubeshop/kusk/blob/main/generators/linkerd/linkerd.go#L29).