.NET Aspire Ocelot Gateway: Fixing Health Checks

Dec 13, 2025 by Andrew McMorgan 49 views

Mastering Ocelot Gateway in .NET Aspire: A Deep Dive

Hey guys, welcome back to Plastik Magazine! Today, we're diving deep into a topic that's been buzzing in the .NET community: integrating the Ocelot API Gateway within a .NET Aspire project. It's a powerful combination, but as many of you have experienced, it can come with a few tricky hurdles, especially when it comes to health checks. You've set up your Ocelot gateway, you're integrating it into your shiny new .NET Aspire application, and then BAM! The Aspire dashboard is showing your gateway as unhealthy. Routes might not be working, or maybe the basic / or /health endpoints are just not responding as expected. Don't sweat it, though! We're going to break down exactly why this happens and, more importantly, how to fix it, ensuring your Ocelot gateway plays nicely within the Aspire ecosystem. We'll cover everything from basic configuration to advanced troubleshooting, so by the end of this article, you'll be a pro at getting your Ocelot gateway up and running smoothly in .NET Aspire.

Understanding the Ocelot and .NET Aspire Synergy

Let's kick things off by understanding why you'd want to use an Ocelot API Gateway with .NET Aspire. .NET Aspire is all about simplifying the development and orchestration of distributed applications. It provides a cohesive developer experience for building cloud-native apps, handling service discovery, configuration, resilience, and observability out of the box. An API Gateway, on the other hand, acts as the single entry point for all your client requests. It handles routing, authentication, rate limiting, and request aggregation, simplifying the client-side architecture and allowing your backend services to remain focused on their core responsibilities. When you combine Ocelot, a popular, feature-rich, open-source API Gateway for .NET, with .NET Aspire, you get a robust solution for managing complex microservice architectures. Ocelot excels at dynamic routing, configuration management, and integration with various authentication providers. .NET Aspire, with its built-in service discovery and orchestration capabilities, makes deploying and managing these services, including the Ocelot gateway itself, a breeze. The synergy lies in Aspire providing the runtime environment and management layer, while Ocelot offers the sophisticated API Gateway functionality. This setup allows developers to build, test, and deploy distributed applications more efficiently, with a clear separation of concerns and enhanced manageability. The goal is to have a central point of access that intelligently directs traffic to your various microservices, while Aspire ensures those services, and the gateway itself, are healthy, discoverable, and well-configured. Imagine a scenario where you have multiple backend services – maybe a user service, a product service, and an order service. Instead of clients needing to know the individual endpoints of each service, they communicate solely with the Ocelot gateway. Ocelot then uses its configuration to route GET /products to your product service, POST /orders to your order service, and GET /users/{id} to your user service. This abstracts away the complexity of your backend, making it easier to refactor, scale, and manage individual services independently. Plus, Ocelot can handle cross-cutting concerns like adding authentication headers to requests before they reach your services, or aggregating responses from multiple services into a single response for the client. .NET Aspire comes into play by making it incredibly easy to define these services in a И.AppHost project, manage their dependencies, configure their ports, and even set up health checks to ensure everything is running optimally. It takes the heavy lifting out of orchestrating these distributed components, allowing you to focus more on the business logic and less on the infrastructure plumbing. So, when you're looking to build scalable, resilient, and manageable microservices, the combination of Ocelot and .NET Aspire is a match made in developer heaven, providing a powerful foundation for your next cloud-native application.

The Root Cause: Health Checks and Aspire's Expectations

Alright, let's get down to the nitty-gritty of why your Ocelot gateway might be showing up as unhealthy in the .NET Aspire dashboard. The core of the issue often lies in how Aspire performs health checks and how Ocelot, by default, handles certain endpoints. Aspire is designed to continuously monitor the health of the services it orchestrates. It does this by pinging a specific health check endpoint on each service. If the service doesn't respond within a certain timeframe or returns an unhealthy status, Aspire flags it as such. Now, Ocelot is a powerful routing engine. Its primary job is to receive incoming requests and forward them to the appropriate downstream services based on its configuration. When you deploy Ocelot within an Aspire project, Aspire tries to perform its health checks, usually against /health or /. The problem is that Ocelot, out of the box, might not have specific routes configured for these health check endpoints from the perspective of the gateway itself. It's expecting requests to be routed through it to other services. When Aspire hits the gateway's IP address and port, and asks for /health, Ocelot might not know what to do with that request because it hasn't been explicitly told to handle it. It's not a configured route for forwarding. This leads to timeouts or unexpected responses, which Aspire interprets as the gateway being unhealthy. Think of it like this: Aspire is the building manager asking each tenant (your services) if they're okay. It goes to the Ocelot gateway (which is like the main reception desk) and asks, "Hey, reception, are you okay?" If the reception desk isn't programmed to answer that question directly and is only set up to direct visitors to different offices, it might just stand there confused, leading the building manager to think the whole reception area is broken. The crucial point is that the Ocelot gateway needs to be configured to respond to its own health check requests before it starts routing traffic to other services. This is distinct from the health checks of the downstream services that Ocelot forwards requests to. Aspire checks the health of the gateway process itself, not just the services the gateway points to. So, even if all your backend microservices are perfectly healthy and responding to their own health checks, if the Ocelot gateway doesn't have a direct way to signal its own well-being to Aspire, the gateway itself will be flagged as unhealthy. This can prevent Aspire from correctly orchestrating and displaying the status of your entire application, potentially blocking deployments or causing confusion in the dashboard. We need to make sure Ocelot is aware of and can respond to these internal health probes initiated by Aspire.

Configuring Ocelot for Aspire Health Checks

Now that we understand why the health checks are failing, let's talk about the solution: configuring Ocelot to properly respond to Aspire's health probes. The key is to add specific routes to your Ocelot configuration that handle the health check endpoints. This ensures that when Aspire pings the gateway for its status, Ocelot knows exactly how to respond.

Here's a typical ocelot.json configuration snippet you'll want to add or modify:

{
  "Routes": [
    // ... your other routes ...

    {
      "DownstreamPathTemplate": "/health",
      "DownstreamScheme": "http",
      "UpstreamPathTemplate": "/health",
      "UpstreamHttpMethod": [ "GET" ]
    },
    {
      "DownstreamPathTemplate": "/",
      "DownstreamScheme": "http",
      "UpstreamPathTemplate": "/",
      "UpstreamHttpMethod": [ "GET" ]
    }
  ],
  "GlobalConfiguration": {
    "ServiceDiscoveryProvider": {
      // ... your service discovery config ...
    }
  }
}

Explanation:

DownstreamPathTemplate: This defines the path that Ocelot will look for internally if it were forwarding the request. For a self-response, it often mirrors the UpstreamPathTemplate.
DownstreamScheme: Set to http as Ocelot is typically running internally within the Aspire orchestration.
UpstreamPathTemplate: This is the crucial part. It defines the path that clients (including Aspire's health checker) will use to access this route. We've set it to /health and /.
UpstreamHttpMethod: Specifies the HTTP methods allowed for this route, typically GET for health checks.

Important Considerations:

ocelot.json Location: Ensure your ocelot.json file is correctly placed within your Ocelot gateway project and is being loaded by Ocelot. In .NET Aspire, you'll typically copy this configuration file into the output directory of your gateway project using a .csproj file modification:
```
<ItemGroup>
  <Content Include="ocelot.json" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>
```
Program.cs Configuration: In your Ocelot gateway's Program.cs, you need to ensure Ocelot is configured correctly to load this file and that the necessary services are registered. A typical setup looks like this:
```
// Program.cs in your Ocelot Gateway Project
var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddOcelot(builder.Configuration);

var app = builder.Build();

// Configure the HTTP request pipeline.
await app.UseOcelot();

app.Run();
```
Make sure builder.Configuration is correctly pointing to your ocelot.json file. Often, this is handled automatically if the file is in the root and set to copy to the output directory.
Aspire Service Definition: In your .AppHost project, you'll define your Ocelot gateway service. Ensure its port is correctly exposed and that Aspire knows where to find the health check endpoint. If you're using default settings, Aspire often infers this, but explicitly defining it can help:
```
// И.AppHost/Program.cs
var ocelotGateway = builder.AddProject<OcelotGatewayProject>
    .WithHttpEndpoint(8080, 8081) // Example ports
    .WithHealthChecks(); // Aspire will try to find /health by default
```
If Aspire's default /health check isn't working with the Ocelot configuration above, you might need to tell Aspire explicitly which endpoint to use if you've customized it further. However, the /health and / routes defined in ocelot.json should satisfy Aspire's default behavior.

By adding these simple routes to your Ocelot configuration, you're essentially telling the gateway, "Hey, if someone asks you directly for /health or /, respond with a success status." This allows Aspire to correctly register your gateway as healthy, and you can then proceed to configure the rest of your routes to point to your actual backend microservices.

Handling Downstream Service Routing and Health

Now that we've got our Ocelot gateway reporting itself as healthy within the .NET Aspire dashboard, let's focus on the real job of the gateway: routing requests to your downstream microservices and ensuring those services are also healthy. This is where Ocelot truly shines, and integrating it with Aspire makes managing these connections seamless.

First, let's look at defining routes in your ocelot.json to point to your backend services. Assuming you have a ProductService and an OrderService defined within your Aspire И.AppHost project, your ocelot.json might look something like this:

{
  "Routes": [
    // ... health check routes from before ...
    {
      "DownstreamPathTemplate": "/products/{everything}",
      "DownstreamScheme": "http",
      "UpstreamPathTemplate": "/api/products/{everything}",
      "UpstreamHttpMethod": [ "GET", "POST", "PUT", "DELETE" ],
      "Key": "ProductService",
      "ServiceDiscoveryProvider": {
        "Type": "ServiceDiscovery",
        "Key": "ProductService"
      }
    },
    {
      "DownstreamPathTemplate": "/orders/{everything}",
      "DownstreamScheme": "http",
      "UpstreamPathTemplate": "/api/orders/{everything}",
      "UpstreamHttpMethod": [ "GET", "POST" ],
      "Key": "OrderService",
      "ServiceDiscoveryProvider": {
        "Type": "ServiceDiscovery",
        "Key": "OrderService"
      }
    }
  ],
  "GlobalConfiguration": {
    "ServiceDiscoveryProvider": {
      "HostAndPort": "http://localhost:18000", // Default Aspire dashboard for service discovery
      "Type": "Polling" // Or "External" depending on setup
    }
  }
}

Key Components in this Routing Configuration:

DownstreamPathTemplate: This is the path on the downstream service that Ocelot will forward the request to. For example, /products/{everything} means any request to /api/products/... will have /products/... appended when sent to the ProductService. The {everything} is a wildcard.
UpstreamPathTemplate: This is the path that clients will use to access the functionality through the gateway. Here, we're mapping /api/products/{everything} to the ProductService.
Key: A unique identifier for the route.
ServiceDiscoveryProvider: This is where Aspire's magic comes in. By setting "Type": "ServiceDiscovery" and providing the Key (which should match the name of your service as defined in the И.AppHost), Ocelot will leverage Aspire's built-in service discovery mechanism. It will ask Aspire for the current address of the ProductService or OrderService instead of relying on hardcoded URLs. This is huge for dynamic environments like Aspire!
GlobalConfiguration.ServiceDiscoveryProvider: This section tells Ocelot how to talk to the service discovery system. In an Aspire context, this typically means pointing to Aspire's service discovery endpoint (often http://localhost:18000 for the dashboard) and using a Polling or External type.

Leveraging Aspire's Service Discovery:

When you define your services in the И.AppHost, like so:

// И.AppHost/Program.cs
var builder = DistributedApplication.CreateBuilder(args);

var productService = builder.AddProject<ProductServiceProject>("products")
    .WithHttpEndpoint(8001); // Example port

var orderService = builder.AddProject<OrderServiceProject>("orders")
    .WithHttpEndpoint(8002); // Example port

var ocelotGateway = builder.AddProject<OcelotGatewayProject>
    .WithHttpEndpoint(8080)
    .WithServiceBinding(productService,