Add Kong API Gateway hosting integration

[qmmk]

Related to an existing integration?

No

Existing integration

No response

Overview

Summary

I would like to propose adding a new Aspire.Hosting.Kong hosting integration for running Kong API Gateway in Aspire AppHost projects.

The integration lets an Aspire app add Kong as a container resource, register Aspire resources as Kong upstream services, generate Kong DB-less declarative configuration, and expose routed services through Kong during local development.

Motivation

Kong is commonly used as an API gateway for routing, authentication, rate limiting, CORS, request transformation, and observability. In Aspire-based distributed applications, it is useful to model Kong directly in the AppHost so developers can run and inspect a gateway-backed topology locally. It is a widely adopted, production-grade API gateway that supports both standalone Docker and Kubernetes deployments, making it well suited for Aspire's local-to-cloud development experience. It also supports the Kubernetes Gateway API, aligning with modern Kubernetes networking practices.

Usage example

Proposed API

Kong-specific endpoints exposed by the resource:

      public static IResourceBuilder<KongResource> AddKong(
          this IDistributedApplicationBuilder builder,
          string name,
          string? configHostDirectory = null);

      public static IResourceBuilder<KongResource> WithKongImage(
          this IResourceBuilder<KongResource> builder,
          string image,
          string tag = "latest");

      public static IResourceBuilder<KongResource> WithProxyPort(
          this IResourceBuilder<KongResource> builder,
          int port);

      public static IResourceBuilder<KongResource> WithAdminApiPort(
          this IResourceBuilder<KongResource> builder,
          int port);

      public static IResourceBuilder<KongResource> WithConsumer(
          this IResourceBuilder<KongResource> builder,
          string username,
          Action<KongConsumerConfig>? configure = null);

      public static IResourceBuilder<KongResource> WithGlobalPlugin(
          this IResourceBuilder<KongResource> builder,
          string pluginName,
          Action<KongPluginConfig>? configure = null);

      public static IResourceBuilder<KongResource> WithKongEnvironment(
          this IResourceBuilder<KongResource> builder,
          Action<EnvironmentCallbackContext> configure);

      public static IResourceBuilder<TResource> WithKongService<TResource>(
          this IResourceBuilder<TResource> builder,
          IResourceBuilder<KongResource> kong,
          string? serviceName = null,
          string? endpointName = null,
          Action<KongServiceConfig>? configure = null)
          where TResource : IResource;

      public static IResourceBuilder<TResource> WithKongRoute<TResource>(
          this IResourceBuilder<TResource> builder,
          string routeName,
          IEnumerable<string> paths,
          Action<KongRouteConfig>? configure = null)
          where TResource : IResource;

      public static IResourceBuilder<TResource> WithKongPlugin<TResource>(
          this IResourceBuilder<TResource> builder,
          string pluginName,
          Action<KongPluginConfig>? configure = null)
          where TResource : IResource;

      public static IResourceBuilder<TResource> WithKongRateLimiting<TResource>(
          this IResourceBuilder<TResource> builder,
          int requestsPerMinute,
          string policy = "local")
          where TResource : IResource;

      public static IResourceBuilder<TResource> WithKongKeyAuth<TResource>(
          this IResourceBuilder<TResource> builder,
          IEnumerable<string>? keyNames = null)
          where TResource : IResource;

      public static IResourceBuilder<TResource> WithKongCors<TResource>(
          this IResourceBuilder<TResource> builder,
          IEnumerable<string>? origins = null,
          Action<KongPluginConfig>? configure = null)
          where TResource : IResource;

      public static IResourceBuilder<TResource> WithKongRequestTransformer<TResource>(
          this IResourceBuilder<TResource> builder,
          Action<KongPluginConfig> configure)
          where TResource : IResource;

      public static IResourceBuilder<KongResource> WithKongOpenTelemetry(
          this IResourceBuilder<KongResource> builder,
          Action<KongPluginConfig>? configure = null);

This would make scenarios like the following first-class:

var kong = builder.AddKong("kong")
                  .WithKongOpenTelemetry();

builder.AddProject<Projects.OrdersApi>("orders-api")
       .WithKongService(kong, serviceName: "orders")
       .WithKongRoute("orders-v1", "/api/orders/")
       .WithKongRateLimiting(requestsPerMinute: 60);

builder.AddProject<Projects.WeatherApi>("weather-api")
       .WithKongService(kong)
       .WithKongRoute("weather", "/weather/");

Current prototype

I have a working prototype as a standalone package named Aspire.Hosting.Kong.

Current capabilities include:

• AddKong(...) to add a Kong container resource in DB-less mode
• automatic generation of kong.yml
• bind mount of generated declarative config into the Kong container
• proxy HTTP, proxy HTTPS, and Admin API endpoints
• WithKongService(...) to register Aspire resources as Kong services
• WithKongRoute(...) for route configuration
• service-level and route-level plugin annotations
• helpers for common plugins:
  • rate-limiting
  • key-auth
  • cors
  • request-transformer
• global plugin support
• consumer support
• OpenTelemetry plugin support, including Aspire dashboard/OTLP endpoint scenarios

The implementation uses Aspire resource annotations and a lifecycle event hook to build the Kong declarative configuration before the resource starts.

Breaking change?

No

Alternatives

None detected. Discussion reference:
microsoft/aspire#18537 (comment)

Additional context

I would appreciate maintainer feedback on whether this integration is in scope for the Aspire repository.

Specific questions:

• Is Kong considered a good fit for an official Aspire hosting integration?
• Should the first contribution focus only on core gateway/routing support, leaving plugin helpers for follow-up PRs?
• Are there preferred patterns in existing hosting integrations that this should align with before a PR?
• Would maintainers prefer this integration to stay focused on local Kong DB-less configuration, or should it also consider future alignment with Gateway API-oriented deployment workflows?

Contribution plan

If this proposal is accepted, I can prepare a PR that:

• moves the prototype into the Aspire repo layout
• adds focused tests for resource creation and declarative config generation
• adds README/API docs following existing integration conventions
• aligns target frameworks, package metadata, analyzers, and build settings with the Aspire repo

Help us help you

Yes, I'd like to be assigned to work on this item