May 21st, 2020

Introducing YARP Preview 1

Sam Spencer
Program Manager

Introducing YARP Preview 1

YARP is a project to create a reverse proxy server. It started when we noticed a pattern of questions from internal teams at Microsoft who were either building a reverse proxy for their service or had been asking about APIs and technology for building one, so we decided to get them all together to work on a common solution, which has become YARP.

YARP is a reverse proxy toolkit for building fast proxy servers in .NET using the infrastructure from ASP.NET and .NET. The key differentiator for YARP is that it is being designed to be easily customized and tweaked to match the specific needs of each deployment scenario. YARP plugs into the ASP.NET pipeline for handling incoming requests, and then has its own sub-pipeline for performing the steps to proxy the requests to backend servers. Customers can add additional modules, or replace stock modules as needed.

With the basic infrastructure of the proxy now in place, we’ve produced the first official build of YARP (Preview 1) in order to better collaborate and get feedback.

What is in Preview 1

  • Core proxy infrastructure
  • Config-based route definitions
  • Pipeline model for extensibility
  • Forwarded Headers (hard coded)
  • Targeting both .NET Core 3.1 and .NET Core 5

What is not in Preview 1

  • Session Affinity #45
  • Forwarded Headers (configurable) #60
  • Code-based route definition & per-request routing #8, #46
  • Metrics & logging #61
  • Performance tweaks #51
  • Connection filtering #53
  • And much more – see the project board for more details

Getting started with YARP Preview 1

YARP is designed as a library that provides the core proxy functionality, that you can then customize by adding or replacing modules. For preview 1, YARP is being supplied as a nuget package and code snippets. We plan on having a project template, and pre-built exe in future previews.

  1. YARP works with either .NET Core 3.1 or .NET 5 preview 4 (or later). Download the preview 4 (or greater) of .NET 5 SDK from https://dotnet.microsoft.com/download/dotnet/5.0
  2. Create an “Empty” ASP.NET Core application using
    • dotnet new web -n MyProxy -f netcoreapp5.0 (or netcoreapp3.1 for .NET Core 3.1)
      Or
    • Create a new ASP.NET Core web application in Visual Studio, and choose “Empty” for the project template
  3. Open the Project and make sure it includes:
    <PropertyGroup>
      <TargetFramework>netcoreapp5.0</TargetFramework>
    </PropertyGroup>
    

    And

    <ItemGroup> 
      <PackageReference Include="Microsoft.ReverseProxy" Version="1.0.0-preview.1.*" /> 
    </ItemGroup>
    
  4. Startup.cs
    YARP is implemented as a ASP.NET Core component, and so the majority of the sample code is in Startup.cs.
    YARP currently uses configuration files to define the routes and endpoints for the proxy. That is loaded in the ConfigureServices method.

    public IConfiguration Configuration { get; }
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }
    public void ConfigureServices(IServiceCollection services) 
    { 
        services.AddReverseProxy() 
            .LoadFromConfig(Configuration.GetSection("ReverseProxy")); 
    } 
    

    The configure method defines the ASP.NET pipeline for processing requests. The reverse proxy is plugged in to ASP.NET endpoint routing, and then has its own sub pipeline for the proxy. Here proxy pipeline modules, such as load balancing can be added to customize the handling of the request.

    /// <summary>
    /// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    /// </summary>
    public void Configure(IApplicationBuilder app)
    {
        app.UseHttpsRedirection();
    
        app.UseRouting();
        app.UseAuthorization();
        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
            endpoints.MapReverseProxy(proxyPipeline =>
            {
                proxyPipeline.UseProxyLoadBalancing();
            });
        });
    }
    
  5. Configuration

    The configuration for YARP is defined in JSON in the appsettings.json file. It defines a set of:

    • Backends – which are the clusters of servers that requests can be routed to
      • The destination name is an identifier that is used in metrics, logging and for session affinity.
      • Address is the URI prefix that will have the original request path appended to it
    • Routes – which map incoming requests to the backend clusters based on aspects of the request such as host name, path, method, request headers etc.
      Routes are ordered, so the app1 route needs to be defined first as route2 will act as a catchall for all paths that have not already been matched.

      The following needs to be a peer to the Logging and AllowedHosts sections.

        "ReverseProxy": {
          "Routes": [
            {
              "RouteId": "app1",
              "BackendId": "backend1",
              "Match": {
                "Methods": [ "GET", "POST" ],
                "Host": "localhost",
                "Path": "/app1/"
              }
            },
            {
              "RouteId": "route2",
              "BackendId": "backend2",
              "Match": {
                "Host": "localhost"
              }
            }
          ],
          "Backends": {
            "backend1": {
              "LoadBalancing": {
                "Mode": "Random"
              },
              "Destinations": {
                "backend1_destination1": {
                  "Address": "https://example.com:10000/"
                },
                "backend1_destination2": {
                  "Address": "http://example.com:10001/"
                }
              }
            },
            "backend2": {
              "Destinations": {
                "backend2_destination1": {
                  "Address": "https://example.com:10002/"
                }
              }
            }
          }
        }
      

Survey

We are interested to see how you are currently using a reverse proxy and what problems we need to solve with this project. We’d appreciate your input here.

Code Feedback

If you have feature suggestions, changes, bugs etc, please provide feedback using the issue templates in the project repo. We welcome contributions, please see contibuting.md for more details.

Author

Sam Spencer
Program Manager

Sam is a Program Manager on the .NET Core team. He has worked on various developer technologies at Microsoft including WinUI, WinJS, LightSwitch, Visual Web Developer and Visual Basic.

25 comments

Discussion is closed. Login to edit/delete existing comments.

  • ricky dowling

    This looks great and feels similar in functionality to Azure Front Door. Do you think in time it could provide a self hosted alternative to Azure Front Door? Will it run in Azure functions to create a scalable proxy service?

    • Sam SpencerMicrosoft employee Author

      Azure Front Door is a reverse proxy service, with a global distribution. You could self-host YARP, but would need to host in each region to get the benefits of AFD. You possibly could host in functions, but that adds a couple of levels of indirection.

      YARP is being built so that it can become the tech for Azure to use in services such as AFD.

      • ricky dowling

        Good to know. Thank you.

  • Chandramouleswaran RavichandranMicrosoft employee

    Would this also support HTTP 2 completely? One of the most common scenarios is simple PubSub systems where we might want to use GRPC bidirectional streaming on top of ASP.NET Core! Would that be supported?

    • Chris R

      HTTP/2 and gRPC are already supported in preview 1. Give it a try.

      • Chandramouleswaran Ravichandran

        And also supports bidirectional streaming?

  • Vladimir Shchur

    Looking forward to seeing it as a k8s ingress option.

  • tmargraff.azure@gmail.com

    Pray spelled backwards

    • Kitty Quinn

      Dollars to donuts it began life as “Yet Another Reverse Proxy”

  • samcov@ivortex.com

    Been waiting for this a LONG time, I’m so glad it didn’t get lost in the many things MS has going on, it’s very important.

    One question: Will this also proxy SignalR

    • Chris R

      SignalR is mostly just HTTP, so yes. There is also explicit support for WebSockets and gRPC.

  • Wojciech Jakubowski

    How does that relate to ocelot.net? Is it alternative? Or supplement? Or sth else? Typical use cases seem to be similar…

    • Hannes Kochniß

      Ocelot is an API gateway, this is a reverse proxy.

      Or in better words: a reverse proxy is streaming packages through (more performant), while an API gateway receives individual HTTP(S) requests and buffers them through, until it forwards them, but sometimes modifies them (as e.g. Azure API Management can do). Different tools for different jobs.

      See here: https://github.com/proxykit/ProxyKit#7-comparison-with-ocelot

    • David FowlerMicrosoft employee

      It’s something that Ocelot could be built on top of.

    • Kitty Quinn

      Right tool for the job. This is just a proxy middleware with a configuration and extensibility strategy. Ocelet is a full API gateway. They’re both useful in contexts they’re appropriate for.

      • Sam SpencerMicrosoft employee Author

        The goal of YARP is to quickly route each request to its destination as quickly as possible. It doesn’t do any interpretation of the body of the request, which is where Ocelot shines.

  • Ronel

    I am not understand why we don’t choose Nginx? could you share us some profit to use YARP? and I have another question, use YARP into micro service, then we want change routes dynamically since some node down or new node, does YARP has solution for this scenarios?

    I always hope .NET be better!

    • David FowlerMicrosoft employee

      There are a couple of reasons:
      - Integrating reverse proxy logic into your existing ASP.NET Core application.
      - Integrating custom logic into a separate reverse proxy using any .NET languages or libraries.
      - Related to the last point but generally extending logic with .NET is more pleasant than something like Lua :D
      - Runs natively in any supported ASP.NET Core server, so IIS, Http.Sys and Kestrel. This means it works great on all operating systems...

      Read more
      • Lucca Faria Ferri

        I totally agree with your points. In an internal project, to aid new staff, I had to develop a small front-end for nginx config files. It’s easy to do so, but when you have to integrate with your project it can be a nightmare.