DOCSEARCHbyAlgolia
Submit Docs

Kusk Gateway

website·Indexed 33 days ago

https://docs.kusk.io

An API gateway for Kubernetes that translates OpenAPI definitions into routing configurations. It features a CLI for deployment and mocking, a management dashboard, and support for JWT authentication, traffic splitting, rate limiting, and request validation.

Tokens
19.5K
Snippets
135
Records
165
Agent score
13%

What's inside Kusk

  1. Overview of Kusk CLI capabilities

    Kusk is a command-line interface (CLI) tool used to manage common tasks related to Kusk Gateway. It provides the following primary capabilities:

    • install: Installs Kusk Gateway and all associated components.
    • deploy: Deploys an API and configures Kusk Gateway using an OpenAPI specification.
    • ip: Retrieves the IP address of the default Kusk LoadBalancer.
    • generate: Generates Kusk Gateway API resources from OpenAPI.
    • dashboard: Opens a port-forward to provide access to the Kusk Dashboard.

  2. Overview of the Envoy Fleet resource

    The EnvoyFleet resource is used by the Kusk Gateway Manager to deploy and manage an Envoy Proxy-based gateway in Kubernetes. When deployed, the Manager automatically creates the corresponding Kubernetes Deployment, ConfigMap, and Service. The ConfigMap bootstraps Envoy to connect to the KGW Manager's XDS service for configuration. To enable actual routing, you must deploy accompanying API or StaticRoute resources. Deleting the EnvoyFleet resource removes all associated Kubernetes resources. You can deploy multiple Envoy Fleets to have multiple gateways available.

  3. Overview of Kusk Gateway Custom Resource Definitions (CRDs)

    Kusk Gateway utilizes several Kubernetes Custom Resource Definitions (CRDs) to manage its configuration. These CRDs are automatically installed during the Kusk Gateway installation process. The primary CRDs include:

    • EnvoyFleet: Used for managing Envoy deployments.
    • API: Used to configure Gateway behavior based on an OpenAPI definition.
    • StaticRoute: Used to expose static content through the Kusk Gateway.

  4. Overview of Kusk Gateway

    Kusk is a Kubernetes API gateway powered by Envoy that provides native support for the OpenAPI Specification. It allows developers to use OpenAPI definitions to configure the Ingress Controller of Kubernetes clusters. Key capabilities include:

    • Rapid prototyping via API response mocking.
    • Automatic request and response validation to protect endpoints.
    • No-code configuration of critical policies such as CORS and request timeouts.
    • Centralized API management through an open-source dashboard.

  5. Understand Kusk Gateway project structure

    Kusk Gateway is built using Kubebuilder for scaffolding and CRD generation, and utilizes the go-control-plane package for Envoy xDS protocol configuration. Key directories include:

    • api/v1alpha1: Go types for Custom Resource Definitions (CRDs).
    • build/: Dockerfiles for Manager and Agent processes.
    • cmd/: Entry points for Manager and Agent processes.
    • internal/agent: Business logic for mocking API responses.
    • internal/controllers: Kubernetes controllers handling CRD events.
    • internal/envoy: Envoy configuration and go-control-plane manager setup.
    • internal/validation: Service proxy for request validation.
    • pkg/spec: Logic for loading, parsing, and validating OpenAPI definitions and extensions.

  6. Use OpenAPI Overlays to add Kusk extensions to code-generated APIs

    Kusk supports the OpenAPI Overlay specification, allowing developers to keep their primary OpenAPI definition clean (e.g., generated from code annotations) and maintain a separate overlay file containing Kusk-specific extensions and deployment metadata. Kusk merges these files before deployment.

  7. Kusk Component Overview

    A full Kusk installation consists of the following components:

    • Kusk Gateway: Translates OpenAPI definitions to manage the gateway.
    • EnvoyFleet: Serves as the API's LoadBalancer.
    • Kusk Dashboard: A GUI for working with Kusk Gateway.
    • Kusk API: The server required to control Kusk via the Dashboard.

  8. Secure web applications using OAuth2 via OIDC in Kusk

    Kusk implements the OpenID Connect (OIDC) layer, allowing it to support any OAuth2 provider that also supports OIDC. This is intended for web application authentication; for securing APIs, use JWT authentication. OAuth2 is configured using the auth option within a StaticRoute resource.

  9. Use the x-kusk OpenAPI extension for Kusk Gateway

    Kusk Gateway utilizes a custom OpenAPI specification extension called x-kusk. This allows the OpenAPI definition to serve as the single source of truth for both the functional API contract and operational configurations such as routing, security, and performance.

  10. Understand Kusk anonymous data collection

    Kusk collects anonymous, non-traceable usage data in aggregate form to improve user experience. Telemetry is collected when the API server is bootstrapped for the first time. Collected metrics include:

    • Number of CLI installations and unique daily CLI usages.
    • Number of cluster installations and unique active cluster installations.
    • Number of users who disable telemetry.
    • Number of unique UI sessions.
    • Number of API, StaticRoute, and EnvoyFleet creations.

  12. Define entrypoints for static applications using StaticRoute

    Use the StaticRoute custom resource to route traffic to non-API applications (e.g., static pages, images) or legacy APIs that may be external to the cluster. This is specifically used when the OpenAPI specification cannot define the application entrypoint.

    Key Constraints:

    • Static Routes assume upstream hosts or services live at the root path (/).
    • Because of this root-path assumption, each StaticRoute must have its own dedicated EnvoyFleet.
    • The status field of the StaticRoute resource is currently not updated by the manager upon reconciliation.