Using Microsoft’s YARP project to proxy web-based microservices
Inner source is the idea of using open source techniques to develop internal tools, using platforms such as GitHub for collaboration. Engineers across a company identify common issues and technologies and work together to build a single solution to all their problems. It’s an important technique that can significantly reduce duplicate effort. One major bank went from using more than 10 versions of a grid control to just one.
But what happens to a mature inner source project that could be beneficial outside the organization that created it? Some remain behind closed doors, but others make the leap to open source. That’s the case with Microsoft’s YARP, a project that began with the aim of consolidating multiple reverse proxy projects across the company. Its name is an acronym for Yet Another Reverse Proxy, since many teams were already building and using various proxies or looking for APIs and libraries they could use.
It’s on the way to becoming an important part of the .NET networking stack, helping exercise both client and server APIs while delivering a proxy that’s ready for next-generation protocols like HTTP/2 (and in the future, QUIC).
Using reverse proxies
Reverse proxies are an important network and security tool, providing isolation between your web or API application infrastructure and the public internet. It forwards requests to endpoints without revealing any details of the network behind the proxy, ensuring that there’s no direct connection between the internal and external networks. Where this differs from a traditional proxy is that a reverse proxy handles connections that are initiated from outside your network.
You can use a reverse proxy for various purposes, depending on the application it’s proxying. In some cases, it provides either load balancing or caching, moving requests across a pool of servers (either locally or globally) and storing and forwarding static or time-independent content. The proxy can then filter distributed denial-of-service attacks, protecting the internal network. Finally, it can be used as an accelerator, handling compute-intensive tasks like decrypting encrypted traffic before forwarding it to an internal server, reducing load on your application servers.
With Microsoft developers needing reverse proxies for all these scenarios, they developed many different tools. Bringing the teams together made it possible to deliver a standard proxy that could be configured to manage different scenarios by adding middleware for application-specific features, as well as managing common reverse-proxy use cases out of the box.
Delivering an open .NET-based reverse proxy
The result is a .NET tool that works for both .NET and ASP.NET, with the aim of shipping libraries along with templates to help you customize the tool. That customization is its key differentiator, allowing you to manage either via configuration files or by integrating it into application management tools. If you need to make changes to a YARP proxy, you shouldn’t have to rebuild it from scratch; a configuration API lets you make on-the-fly changes.
Currently available as release candidate source code, YARP should reach a 1.0 release soon. The latest version builds on all currently supported .NET Core releases: 3.1, 5.0, and the upcoming 6.0. You can download the source code archives from the project GitHub release page, or preferably clone the repository locally and then use the build scripts to automatically download the .NET SDK and build the tool. Microsoft provides instructions for using Visual Studio 2022, with a start script that loads the appropriate .NET SDK version.
You’re likely to prefer .NET 5 or later, as the .NET Core 3.1 version doesn’t support certain key features, including limiting the telemetry needed to fully monitor a proxy. You’ll still need the .NET 5 SDK to build on .NET Core 3.1, as it requires some C# features that are only supported in later releases. Other improvements that come with more recent .NET versions include better support for HTTP/2, needed for use with gRPC.
Once built, you can manage the YARP reverse proxy using configuration files. These use standard .NET configuration providers, and you can choose your technology as part of building YARP. This approach allows you to pick your own tools to deliver configurations, say as part of an infrastructure-as-code tool. The default is JSON, using named sections in the configuration file to define routing and target server clusters.
Configuring and using YARP in your own applications
Route configuration targets matched arrays or paths to defined clusters where clusters are destinations and addresses that can respond to the requests for a specific route. There’s even the option to include route-based policies to a configuration, such as adding authorization rules to a route or ensuring that cross-origin resource sharing policies are applied. The result is a relatively simple set of configurations that can deliver modern policy-based routing.
The same configuration objects and collections described in your JSON configuration files can be used as the data structures for application-controlled settings. It’s possible to dynamically reload settings on the fly without needing to restart the proxy, so if you’re autoscaling an application on a Kubernetes server or on Azure Service Fabric, you can update as new endpoints are added or old ones removed.
One interesting option in YARP is the ability to add your own middleware to a proxy, using ASP.NET’s pipeline concept to add new features. For example, you could have tools that automatically reject requests based on rules, sending a custom response from the proxy without passing any data to the proxied cluster. It’s best to use middleware solely on request headers; it’s not a good idea to modify request bodies or responses.
There are built-in transforms that modify requests and responses, such as when you’re using a YARP proxy as a Secure Sockets Layer accelerator, modifying headers and responses to add and remove encryption as necessary. Other options add or remove parameters from query strings, allowing you to restrict the requests sent through a proxy, ensuring that only a limited set of parameters are delivered to the servers. By controlling requests through a proxy, you’re able to reduce the attack surface, hardening your application. You can do much the same for request values too, avoiding malicious malformed queries.
Beyond the web proxy
YARP can be part of your applications’ self-monitoring, with the ability to regularly check endpoint health. Requests can be sent to specific endpoints and, depending on responses, clusters can be marked as healthy or unhealthy. Unhealthy clusters are automatically blocked, allowing you to conduct maintenance while your application continues to run.
With support for HTTP/2, gRPC, and Service Fabric, YARP is an important tool for anyone building ASP.NET applications at scale, as well as supporting .NET-based microservices. It’s worth spending the time building and customizing your own instances, taking advantage of its pipelined architecture and programable configurations.
By initially building a tool to support many different internal projects, Microsoft has delivered a general-purpose reverse proxy that’s much more than the lowest common denominator. The step from inner source to open source isn’t a big one, but it benefits everyone, not only Microsoft’s own internal product teams.