YARP vs Ocelot: Choosing the Right .NET API Gateway for Enterprise Teams

Enterprise teams building microservices on .NET often reach the same inflection point: the frontend or mobile client can no longer talk directly to a growing collection of downstream services. That is when an API gateway enters the conversation — and for .NET shops, the choice quickly narrows to two mature options: YARP (Yet Another Reverse Proxy, built by Microsoft) and Ocelot (a community-led .NET gateway that has been the default answer for years). Getting this decision wrong costs months of re-architecture, so treat it as an irreversible, architecture-level choice that deserves deliberate analysis.

Want implementation-ready .NET source code you can adapt fast? Join Coding Droplets on Patreon. 👉 https://www.patreon.com/CodingDroplets

What Problem an API Gateway Solves

Before comparing tools, align on scope. An API gateway sits between external clients and your internal services. It handles cross-cutting concerns — routing, authentication, rate limiting, request transformation, load balancing, and observability — so individual services do not have to. Without a gateway, each service grows its own edge-facing surface, and client contracts become fragile.

For enterprise teams, the gateway is also a policy enforcement point. Every request that enters the system passes through it, which means security posture, audit logging, and compliance controls can be centralized rather than duplicated across dozens of services.

What YARP Is and Where It Came From

YARP is a reverse proxy library developed by Microsoft's internal infrastructure team. It emerged from the need to consolidate dozens of legacy reverse proxy configurations inside Microsoft's own products. Unlike Ocelot, YARP is not an opinionated gateway framework — it is a composable library that integrates natively into the ASP.NET Core middleware pipeline.

That distinction matters. YARP gives teams a programmable proxy surface. Routing rules, load balancing policies, header transformations, and health checks are all expressed through .NET configuration or C# code, using the same DI container, middleware, and configuration system your team already knows. The learning curve is low for .NET engineers because it feels like any other ASP.NET Core middleware.

YARP is now an officially supported component of .NET and ASP.NET Core, making it a first-class option rather than a third-party dependency that may go unmaintained.

What Ocelot Is and Where It Still Excels

Ocelot has been the de facto API gateway for .NET microservices since 2017. It takes a configuration-first approach: define routes, rate limits, authentication requirements, and aggregation rules in JSON, and the library handles the rest. For teams that want a working gateway with minimal custom code, Ocelot's model is attractive because it reduces the surface area of things that can go wrong.

Ocelot includes built-in support for common gateway patterns out of the box: service discovery integration with Consul and Eureka, request aggregation, delegating handlers, and header transformation. It also integrates with IdentityServer for authentication, which was a major selling point in the IdentityServer era.

The trade-off is extensibility. Once you need behavior that Ocelot's configuration model does not support, you are writing delegating handlers or middleware that layers on top of a framework not designed with that kind of extension in mind. The seams become visible under complexity.

The Architecture Comparison That Matters for Enterprise Teams

The core difference is philosophy: YARP is a library; Ocelot is a framework.

With a library, you own the application. YARP slots into your ASP.NET Core pipeline and hands you full control over when and how proxying happens. You can mix gateway logic with other application logic in the same process, apply custom authentication middleware, inject telemetry exactly where you want it, and change routing logic at runtime using the YARP management API.

With a framework, the framework owns the application and you configure it. Ocelot works well when your requirements fit inside what it was designed to handle. When requirements grow beyond the configuration model — custom circuit breaking, dynamic routing from a database, conditional transformations based on business rules — complexity accumulates in delegating handlers that were never meant to carry that load.

For enterprise teams running multi-region deployments, service meshes, or per-tenant routing logic, YARP's programmable model typically wins because the complexity is expressed as testable .NET code rather than nested JSON configurations with implicit behavior.

Performance Characteristics

Both YARP and Ocelot are built on ASP.NET Core and share the same Kestrel foundation. In standardized benchmarks under moderate load, the two tools perform similarly. The difference emerges under sustained high-concurrency traffic.

YARP is optimized for throughput. Because it is built as a low-level library rather than a framework, it avoids several layers of abstraction that Ocelot's configuration model requires at request time. Teams running YARP internally at Microsoft use it to proxy millions of requests per minute without dedicated gateway hardware.

Ocelot's performance is sufficient for most enterprise workloads. Unless you are proxying at very high request rates (tens of thousands of requests per second through a single instance), Ocelot's overhead is not a practical concern. Performance ceases to be the deciding factor for the majority of teams; architecture fit and maintainability dominate.

Observability and Diagnostics

Both tools work with .NET's built-in observability stack — ILogger, System.Diagnostics.ActivitySource for distributed tracing, and .NET metrics. YARP ships with first-class OpenTelemetry instrumentation built in, including automatic span creation for each proxied request, upstream health check telemetry, and load balancer decision metrics.

Ocelot's observability story requires more configuration. You can attach custom delegating handlers or middleware to emit traces and metrics, but the integration is not as native. Teams that have already invested in OpenTelemetry-based observability infrastructure (Grafana, Tempo, Prometheus, Jaeger) will find YARP fits more naturally.

Service Discovery and Load Balancing

YARP supports configurable load balancing strategies — round-robin, random, least requests, and power of two choices — and integrates with configuration-driven or programmatic cluster definitions. Destination health is monitored via active and passive health checks, and unhealthy destinations are automatically removed from the pool.

For cloud-native deployments in Kubernetes, YARP's cluster definitions can be populated dynamically from Kubernetes service endpoints, making it a viable alternative to an external sidecar-based load balancer for intra-cluster routing.

Ocelot integrates with Consul, Eureka, and Kubernetes through provider packages. The integration is mature for Consul and Eureka. In Kubernetes-native environments, teams increasingly find that YARP's dynamic configuration API gives more control without requiring a separate service registry.

When to Choose YARP

YARP is the right call when:

• The team has strong .NET skills and prefers expressed-in-code configuration over JSON-driven behavior
• Routing logic needs to be dynamic, conditional, or database-driven
• Per-tenant request transformation or custom authentication flows are requirements
• High-throughput proxy performance is a concern
• The team wants first-class OpenTelemetry integration without additional wiring
• The gateway will evolve alongside business logic and needs to stay maintainable over years

When to Choose Ocelot

Ocelot is the right call when:

• The team wants a gateway running in days with minimal custom code
• Requirements are stable and fit cleanly into Ocelot's configuration model
• Integration with Consul or Eureka-based service discovery is a hard requirement and the team does not want to build the integration
• The gateway will be maintained by a team that is more comfortable with configuration files than middleware pipelines

What to Avoid in Either Case

Regardless of which tool you choose, avoid treating the gateway as a business logic layer. Gateways should be thin — routing, auth, rate limiting, and telemetry only. When business logic leaks into the gateway, the deployment unit becomes a bottleneck and a single point of coordinated change.

Also avoid growing a single gateway to cover wildly different client types. Mobile apps, web frontends, and service-to-service APIs have different reliability, authentication, and transformation needs. Consider separate gateway instances or a BFF layer per client type, each one thin and purpose-built.

Migration Considerations

Teams moving from Ocelot to YARP (or vice versa) should treat the migration as a routing table exercise first. Map every Ocelot route configuration to an equivalent YARP cluster and route definition, validate with integration tests, then cut traffic over with a blue-green or canary deployment. YARP and Ocelot can run side by side during migration since they are independent ASP.NET Core applications.

For greenfield systems, the migration question does not apply — but the principle holds: define your routing contract in tests before choosing a tool so that switching tools in the future does not require discovering your routing rules empirically.

The Governance Angle

Enterprise teams need to govern their gateway choice the same way they govern any shared infrastructure: documented ADRs, version pinning, upgrade policies, and ownership assignment. A gateway maintained by no one specific team drifts. Assign ownership explicitly, publish internal SLAs for routing changes, and treat gateway configuration changes as production changes that require review.

YARP's C# configuration model makes gateway logic code-reviewable and testable in ways that JSON configuration files are not. That governance advantage — the ability to write unit tests against routing decisions — is underappreciated and is often the factor that tips large enterprise teams toward YARP even when their initial requirements would fit Ocelot.

FAQ

Is YARP production-ready for enterprise workloads in 2026? Yes. YARP is used in production inside Microsoft at very large scale and is officially supported as part of the ASP.NET Core ecosystem. It receives active maintenance, security patches, and new feature development aligned with .NET release cycles. Enterprise teams can treat it as a supported, long-term platform choice.

Can YARP and Ocelot handle authentication and authorization? Both can. YARP integrates directly with ASP.NET Core's authentication and authorization middleware — you configure auth policies on YARP's pipeline just as you would on any controller or minimal API endpoint. Ocelot has dedicated configuration options for authentication via IdentityServer-compatible providers. YARP's approach is more flexible because it uses the same auth primitives as the rest of your application.

Does YARP support WebSocket proxying? Yes. YARP supports HTTP/1.1, HTTP/2, HTTP/3, and WebSocket proxying out of the box. This makes it suitable for real-time workloads that mix REST and WebSocket traffic through the same gateway — for example, proxying gRPC streaming alongside REST endpoints.

How does YARP handle high availability and failover? YARP supports active and passive health checks on clusters. Active health checks poll destination endpoints on a configurable interval and remove unhealthy destinations from the load balancer rotation. Passive health checks detect failures at request time and apply circuit-breaker-like behavior. Combined with horizontal scaling of the YARP process itself, this provides production-grade HA without external infrastructure dependencies.

Should every .NET microservices project use a gateway? Not necessarily. For internal service-to-service communication in a service mesh environment, a gateway may add latency without adding value. Gateways are most valuable at the edge — where external clients meet internal services — because that is where cross-cutting concerns like public-facing auth, rate limiting, and traffic shaping are most needed. For purely internal routing, evaluate whether a service mesh sidecar or direct service discovery is more appropriate than a gateway.

What is the licensing situation for YARP and Ocelot? YARP is released under the MIT license by Microsoft. Ocelot is also MIT-licensed and community-maintained. Both are free to use commercially. The distinction is that YARP is backed by Microsoft engineering investment, which provides a stronger long-term support signal for enterprise procurement conversations.

Can I use YARP with Kubernetes without Helm or Ingress controllers? Yes. YARP can run as a standard Kubernetes Deployment and receive traffic via a Kubernetes Service or LoadBalancer. It does not require Ingress controllers or Helm charts, although both can be used if your organization has standardized on them. Teams running YARP in Kubernetes often configure cluster destinations dynamically using the Kubernetes API, updating YARP's route and cluster state in response to pod readiness changes without restarting the proxy.