Programmatic YARP Configuration in Aspire via New Route and Destination Resources

[benjaminpetit]

Description:

Configuring YARP in Aspire via code is currently verbose and unintuitive. To address this, I propose a new approach based on #9766, introducing dedicated resources for routing.

Proposed Solution:

• Introduce new Route and Destination resources (aligned with YARP’s terminology, where "Destination" maps to "Cluster").
• Configure these resources via fluent methods, similar to how ports are exposed on a project.
• All configuration will be done via extension methods that modify the underlying RouteConfig or ClusterConfig objects, ensuring a consistent and expressive API surface.
• This enables a more natural and composable way to define reverse proxy behavior directly in code, without relying on JSON blobs.

YarpRoute

public class YarpRoute(IResourceBuilder<YarpResource> parent)
{
    internal IResourceBuilder<YarpResource> ParentBuilder { get; } = parent;

    internal RouteConfig RouteConfig { get; private set; } = new RouteConfig
    {
        [...]
    };

    internal void Configure(Func<RouteConfig, RouteConfig> configure)
    {
        RouteConfig = configure(RouteConfig);
    }
}

YarpDestination

/// <summary>
/// Represents a destination for YARP routes
/// </summary>
public class YarpDestination(IResourceBuilder<YarpResource> parent, EndpointReference endpoint)
{
    internal IResourceBuilder<YarpResource> ParentBuilder { get; } = parent;

    internal ClusterConfig ClusterConfig { get; private set; } = new()
    {
        [...]
    };

    internal void Configure(Func<ClusterConfig, ClusterConfig> configure)
    {
        ClusterConfig = configure(ClusterConfig);
    }
}

Extensions

All configuration will be done with extensions. For example, a subset of the extensions for YarpRoute could be:

/// <summary>
/// Provides extension methods for configuring a YARP destination
/// </summary>
public static class YarpRouteExtensions
{
    [...]

    /// <summary>
    /// Only match requests that use these optional HTTP methods. E.g. GET, POST.
    /// </summary>
    public static YarpRoute WithMatchMethods(this YarpRoute route, params string[] methods)
    {
        route.ConfigureMatch(match => match with { Methods = methods });
        return route;
    }

    /// <summary>
    /// Only match requests that contain all of these headers.
    /// </summary>
    public static YarpRoute WithMatchHeaders(this YarpRoute route, params RouteHeader[] headers)
    {
        route.ConfigureMatch(match => match with { Headers = headers.ToList() });
        return route;
    }

    [...]

    /// <summary>
    /// Set the Metadata of the destination
    /// </summary>
    public static YarpRoute WithMetadata(this YarpRoute route, IReadOnlyDictionary<string, string>? metadata)
    {
        route.Configure(r => r with { Metadata = metadata });
        return route;
    }

    [...]
}

Usage Examples

Basic Example

In this scenario, the developer only interacts with the Route resource and passes a reference to the endpoint being proxied:

var yarp = builder.AddYarp("apigateway");

// catalog 
yarp.AddRoute("/catalog/{**catch-all}")
    .WithTransformPathRemovePrefix("/catalog")
    .WithReference(catalogService.GetEndpoint("http"));

// basket
yarp.AddRoute("/basket/{**catch-all}")
    .WithTransformPathRemovePrefix("/basket")
    .WithReference(basketService.GetEndpoint("http"));

Advanced Example

This approach allows you to explicitly create a reusable destination using AddDestination(...), reference it from multiple routes, and customize its behavior using WithForwarderRequestConfig(...):

var yarp = builder.AddYarp("apigateway");

var backend = yarp.AddDestination(backendService.GetEndpoint("http"))
    .WithForwarderRequestConfig(new ForwarderRequestConfig
    {
        ActivityTimeout = TimeSpan.FromSeconds(30),
        Version = HttpVersion.Version20
    });

yarp.AddRoute("/somepath/{**catch-all}")
    .WithMatchMethods("GET", "HEAD")
    .WithTransformPathRemovePrefix("/somepath")
    .WithReference(backend);

yarp.AddRoute("/anotherpath/{**catch-all}")
    .WithMatchMethods("POST")
    .WithMaxRequestBodySize(1000)
    .WithTransformPathRemovePrefix("/anotherpath")
    .WithTransformRequestHeader("x-my-header", "custom-value")
    .WithReference(backend);

Benefits:

• Aligns with Aspire’s developer-friendly philosophy.
• Reduces boilerplate and improves discoverability.
• Makes routing logic easier to test, reuse, and extend.
• Enables fine-grained control over forwarding behavior and destination reuse.
• Future-proof design: Extending this model to support middleware configuration (e.g., authentication, rate limiting, logging) will be straightforward and will not introduce breaking changes, thanks to the composable and fluent API structure.

[mitchdenny]

@benjaminpetit thanks for putting this together. I think that the users of the Yarp resource will probably exist on a spectrum ranging from just wanting to combine the URL space for some front-end JS application and its backend (BFF scenario), to those who really need advanced reverse proxy functionality.

What we are dealing with is how do we make the step from the relatively simplistic scenario to the more advanced scenario and try to avoid an API explosion in the app model that we will need to maintain/ensure backwards compatability.

I think what we could potentially do is something like this:

// Easy mode
var builder = DistributedApplication.CreateBuilder(args);
var frontend = builder.AddNpmApp(...);
var backend = builder.AddProject(...);
var yarp = builder.AddYarp(...)
                  .WithRoute(frontend.GetEndpoint("http")) // Adds a default catch-all.
                  .WithRoute(backend.GetEndpoint("http"), "/api/{**catch-all}");

This would provide a very simple model for the super common BFF scenario. Then we could provide the following overload that provides a callback:

// Slightly more complex mode.
var builder = DistributedApplication.CreateBuilder(args);
var frontend = builder.AddNpmApp(...);
var backend = builder.AddProject(...);
var yarp = builder.AddYarp(...)
                  .WithRoute(frontend.GetEndpoint("http"))
                  .WithRoute(backend.GetEndpoint("http"), (route) => {
                     // Set extra constraints on route like methods etc.
                  });

The type for route could start being fairly simplistic but we could gradually increase what it offers based on the scenarios that customers come up with. Then of course we have the option for people to provide their own YARP config file (and not use WithRoute helpers at all), and finally - people could host the YARP package in their own .NET project for super advanced scenarios.

I feel like this helps avoid a complexity cliff whilst managing the potential for API surface explosing in the app model. The documentation for this entire feature could actually walk through the progressive scale of complexity here.

[mitchdenny]

Another thought. The API surface being designed here in effect becomes an AST for YARP. I think if we were going to come up with a config builder for a YARP configuration file it should be in the YARP codebase (possibly as a separate assembly) that we could reference in Aspire. That way as the YARP configuration model evolves so too would the representation in the API - and so Aspire would just evolve naturally.

Thoughts?

/cc @davidfowl @DamianEdwards

[benjaminpetit]

@mitchdenny I think the only difference I see in your version is that it will be using "inner builders" to configure routes, instead of having a "flatter" model. I don't have any strong preference.

But I still think the cluster configuration should also be easy, so we will end up with two delegates (but they will be both optionals).

var yarp = builder.AddYarp(...)
                  .WithRoute(frontend.GetEndpoint("http"))
                  .WithRoute(backend.GetEndpoint("http"), 
                  (route) => {
                     // Set extra constraints on route like methods etc.
                  },
                  (destination) => {
                    // Set options on the destination
                  ]);

There is also the question of sharing the same endpoint for multiple routes. I don't think it's a scenario too advanced and that we should support it with these extensions.

I think if we were going to come up with a config builder for a YARP configuration file it should be in the YARP codebase (possibly as a separate assembly) that we could reference in Aspire.

Maybe? I think that's something we will evaluate in the future, but for now I feel it is better to have in this repo:

• faster to iterate: we don't want to have to publish a new NuGet package for YARP every time we want to modify the builder
• the builder is still made for Aspire first: in this builder we don't want the user to modify the RouteConfig.ClusterId for example, or add transforms or middlewares that are not (yet) supported in the Aspire/Yarp container scenario. And Yarp doesn't have the concept of EndpointReference for example.

[mitchdenny]

In the example code above why is there two callbacks?

[benjaminpetit]

Because we need a way to configure the destination? We could put everything in the route builder, but I feel it will get very messy imo.

But I am still not sure how to be able to have multiple routes with the same destination.

[joperezr]

I'm sure this is just me not being familiar enough with the area, but do you mind sharing an example of what a messy route builder would look like and then how it looks instead with the two callbacks for a more visual comparison?

[benjaminpetit]

var yarp = builder.AddYarp(...)
                  .WithRoute(frontend.GetEndpoint("http"))
                  .WithRoute(backend.GetEndpoint("http"), 
                  (route) => {
                      route.WithMatchPath("/api/{**catch-all}")
                           .WithTransformPathRemovePrefix("/catalog")
                           .WithMatchMethods("GET", "HEAD");
                  },
                  (destination) => {
                      destination.WithForwarderRequestConfig(new ForwarderRequestConfig
                        {
                            ActivityTimeout = TimeSpan.FromSeconds(30),
                            Version = HttpVersion.Version20
                        });
                  ]);

With only one delegate it would be

var yarp = builder.AddYarp(...)
                  .WithRoute(frontend.GetEndpoint("http"))
                  .WithRoute(backend.GetEndpoint("http"), 
                  (options) => {
                      options.Route.WithMatchPath("/api/{**catch-all}")
                                   .WithTransformPathRemovePrefix("/catalog")
                                   .WithMatchMethods("GET", "HEAD");
                      options.Destination.WithForwarderRequestConfig(new ForwarderRequestConfig
                      {
                          ActivityTimeout = TimeSpan.FromSeconds(30),
                          Version = HttpVersion.Version20
                      });
                  });

Note that with these both solutions, it makes sharing the same EndpointReference a bit messy, since you will be able to configure the destination twice. Maybe that's intended, because they don't want the same behavior depending on the routes, so they expect to have two different ClusterConfig generated. Maybe it's not, and they expect the two routes to share the same ClusterConfig.

I am not sure what to do in that case, I feel it's too ambiguous. I feel we need a YarpDestination in that case.

[mitchdenny]

I think what we do for 9.4 is that we mark the version of WithRoute that takes the callback as experimental (including the options type).

The bigger concern for me right now is that this doesn't actually work at all on Linux because of the connectivity issues back from the container to say an ASP.NET Core app running on the host. So, utility of this feature is going to be severely limited.

[davidfowl]

The entire package is pre release

[mitchdenny]

Also options.Cluster vs. options.Destination?

In terms of multiple WithRoute(...) calls to the same endpoint potentially resulting in multiple clusters being defined. I'm not sure we should do that. I think that there should be a cluster which is named after the resource-endpoint pairing, and if you have mutiple WithRoute calls the value of the Destination/Cluster object would be the same across both calls. So a subsequent WithRoute(...) could overwrite changes you made previously.

If you don't want that then you can use WithConfiguration(...) because you might be getting into advanced scenarios anyway?

UNLESS we think the default mental model that folks will have is that on a per route basis you want to have different things like timeouts etc - that being the case then you would create duplicate clusters pointing to the same endpoint to fine tune those settings for each route.