Add YARP container support

[benjaminpetit]

Description

This PR add simple helper methods to use a YARP container in Aspire.

Fixes # (issue)

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No
• Does the change require an update in our Aspire docs?
  • Yes
    • Link to aspire-docs issue (consider using one of the following templates):
      • New (or update) doc-idea template
      • New breaking-change template
      • New diagnostic template
  • No

[Copilot]

Pull Request Overview

This PR adds YARP container support to Aspire by introducing helper methods and resource definitions that simplify adding and configuring a YARP container.

• Introduces an extension method (AddYarp) to add YARP resources with configuration and environment support.
• Defines a YarpResource class and corresponding container image tags.
• Updates sample usage in TestShop.AppHost to demonstrate the new extension method.

Reviewed Changes

Copilot reviewed 6 out of 13 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/Aspire.Hosting.Yarp/YarpServiceExtensions.cs	Adds extension methods to create and configure a YARP container resource, including environment and dynamic configuration handling.
src/Aspire.Hosting.Yarp/YarpResource.cs	Introduces the YarpResource class, extending the container resource concept.
src/Aspire.Hosting.Yarp/YarpContainerImageTags.cs	Defines constants for YARP container image attributes and configuration paths.
src/Aspire.Hosting.Yarp/README.md	Minimal documentation for the YARP hosting library.
playground/TestShop/TestShop.AppHost/Program.cs	Demonstrates usage of the new AddYarp extension method in a sample project.

Files not reviewed (7)

• Aspire.sln: Language not supported
• playground/TestShop/TestShop.AppHost/TestShop.AppHost.csproj: Language not supported
• playground/TestShop/TestShop.AppHost/appsettings.Development.json: Language not supported
• playground/TestShop/TestShop.AppHost/yarp.json: Language not supported
• spelling.dic: Language not supported
• src/Aspire.Hosting.Yarp/Aspire.Hosting.Yarp.csproj: Language not supported
• tests/Shared/RepoTesting/Directory.Packages.Helix.props: Language not supported

Comments suppressed due to low confidence (1)

src/Aspire.Hosting.Yarp/YarpContainerImageTags.cs:12

• [nitpick] The 'Tag' constant is defined but not used in the extension methods; consider either incorporating it into the configuration or removing it to avoid potential confusion.

public const string Tag = "2-preview";

[adityamandaleeka]

Seems like the other ones all have tags for each of these.

[benjaminpetit]

I am not sure to understand?

[adityamandaleeka]

We should have a functional test that actually has a YARP resource.

[mitchdenny]

This is looking good as a first pass and I would like to get it in for 9.3. But I think we need to just have a quick look at how this API might evolve over time to make sure we aren't adding things that we'll regret later. Based on my read through of the API, this is what the usage looks like:

var builder = DistributedApplication.CreateBuilder(args);
var yarp = builder.AddYarp("myyarp")
                  .WithConfigFile("path/to/config/file");

This looks reasonable, but we should consider what would happen if someone does this:

var builder = DistributedApplication.CreateBuilder(args);
var yarp = builder.AddYarp("myyarp");

At the moment it will throw an exception, but I think it might be nicer if we can spin up the YARP proxy using a minimal config file, maybe with a simple hello world page or something like that (similar to what Nginx does).

In the future we might want to do things like this:

var builder = DistributedApplication.CreateBuilder(args);
var api = builder.AddProject<Proejcts.MyApi>("api");
var yarp = builder.AddYarp("myyarp")
                  .WithStaticFiles("path/to/static/files")
                  .WithProxiedPath(api.GetEndpoint("https"), "/api");

In this scenario we don't write a config file, instead it would be generated for us based on annotations that WithStaticFiles and WithProxiedPath add to the resource. For this reason I probably wouldn't put the ConfigFilePath property on the resource because it really depends on how you are configuring things.

We also need to think through how this flows all the way to production - not just for the inner loop.

[mitchdenny]

You might want to look at adding a playground project that uses this resource to make it easy for folks to review/dogfood the resource as it gets built out.

[benjaminpetit]

This is looking good as a first pass and I would like to get it in for 9.3. But I think we need to just have a quick look at how this API might evolve over time to make sure we aren't adding things that we'll regret later. Based on my read through of the API, this is what the usage looks like:

var builder = DistributedApplication.CreateBuilder(args);
var yarp = builder.AddYarp("myyarp")
                  .WithConfigFile("path/to/config/file");

This looks reasonable, but we should consider what would happen if someone does this:

var builder = DistributedApplication.CreateBuilder(args);
var yarp = builder.AddYarp("myyarp");

At the moment it will throw an exception, but I think it might be nicer if we can spin up the YARP proxy using a minimal config file, maybe with a simple hello world page or something like that (similar to what Nginx does).

In the future we might want to do things like this:

var builder = DistributedApplication.CreateBuilder(args);
var api = builder.AddProject<Proejcts.MyApi>("api");
var yarp = builder.AddYarp("myyarp")
                  .WithStaticFiles("path/to/static/files")
                  .WithProxiedPath(api.GetEndpoint("https"), "/api");

In this scenario we don't write a config file, instead it would be generated for us based on annotations that WithStaticFiles and WithProxiedPath add to the resource. For this reason I probably wouldn't put the ConfigFilePath property on the resource because it really depends on how you are configuring things.

We also need to think through how this flows all the way to production - not just for the inner loop.

Yeah maybe we could inject a default html page (the current container doesn't support static files, but that's something we can add) or simply redirect by default to the YARP container configuration doc. For now I think haveing a clear error message is enough.

For future use: I have a prototype branch, it was based on the k8s ingress api (I'll send you the internal demo I presented a while ago).

I believe having a file property for the config will always be useful (we could merge configs). I can make the property internal only for now if we decide to remove it later?

[davidfowl]

I think this is commit but I'm not sure we can "ship" this without a deployment story.

[mitchdenny]

Lets get this in for 9.3 as a preview (I updated the package to be preview) and we can iterate in 9.4. I think it is useful as it is but we can do more to make it really joyful to use.

[eerhardt]

I'm not sure if this was suggested elsewhere, but would it make sense to be able to define the config in C#? That way someone doesn't have to jump out to a JSON file. But instead something like:

builder.AddYarp("apigateway")
       .WithReference(basketService)
       .WithReference(catalogService)
       .WithConfig(context =>
       {
           context.AddRoute(basketService, "{**catch-all}");
       });

[davidfowl]

Yea but not as a gate for this initial PR