Building a .NET microservices gateway with Ocelot

Creating a microservices gateway with Ocelot in .NET gives development teams a focused way to control how clients reach distributed services. Ocelot runs as ASP.NET Core middleware or as a dedicated gateway deployment, using configuration to translate upstream request paths into downstream calls. The result is a consistent entry point for mobile apps, web clients, partner systems and internal APIs.

The gateway is most valuable when cross-cutting policies would otherwise be duplicated inside every service. Central route definitions, token validation, throttling, request limits and consistent telemetry can live at the edge, while pricing rules, order workflows and inventory decisions remain inside their owning domains. This separation keeps business code independent from transport concerns.

Australian teams add another dimension: infrastructure spans Sydney, Melbourne, Brisbane and Perth, and some workloads sit behind government security requirements in Canberra. A useful gateway design therefore has to balance cloud-region placement, latency, resilience, privacy obligations and predictable operating costs. These practices apply to a small .NET deployment or a larger platform built around Azure, AWS and existing on-premises systems.

Why a gateway belongs at the edge

A gateway creates a stable public contract while keeping internal service locations private. Clients send requests to one host or logical API, and the gateway decides which service should handle each request. This is particularly useful when teams deploy services independently, since changing an internal hostname no longer requires every consumer to change.

Ocelot fits naturally into an ASP.NET Core estate because it shares .NET configuration, dependency injection and middleware conventions. Route rules can cover authentication, authorisation, rate limiting, transformations and quality-of-service behaviour. The same route definition can therefore express operational policy rather than merely forwarding a URL.

The boundary should remain clear. Domain decisions belong in domain services, while the gateway owns ingress rules and shared traffic controls. A service mesh serves a different purpose: it manages communication between workloads, often with mutual TLS and fine-grained traffic policies. Many .NET platforms need both layers, and adding either one should follow an explicit architectural requirement.

Designing routes for real services

An upstream route identifies what clients call, while a downstream route identifies where the request goes. Placeholders such as {orderId} can be carried into the service, and UpstreamHttpMethod restricts matching to selected verbs. AuthenticationOptions binds a route to the bearer scheme and its permitted scopes.

{
  "Routes": [
    {
      "UpstreamPathTemplate": "/orders/{orderId}",
      "UpstreamHttpMethod": ["GET"],
      "DownstreamPathTemplate": "/orders/{orderId}",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        { "Host": "orders-api", "Port": 8080 }
      ],
      "AuthenticationOptions": {
        "AuthenticationProviderKey": "Bearer",
        "AllowedScopes": ["orders.read"]
      }
    }
  ]
}

The orders-api hostname assumes a container or service discovery environment. A local .NET service might instead use localhost and its development port. Ocelot can also integrate with supported discovery providers such as Consul, although a fixed address remains easier to audit when the service topology is stable.

Keep public paths aligned with consumer contracts rather than internal class names. Configuration can vary by environment without changing the route exposed to users, with secrets supplied separately from the route file. This allows the same gateway definition to run in a developer laptop, an automated test environment and an Australian cloud subscription.

Configuring Ocelot in ASP.NET Core

Add the Ocelot NuGet package, along with the JWT bearer package when token validation is required. Match the Ocelot package version to the .NET version supported by that release. The following startup code registers configuration, authentication and the gateway middleware.

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddJsonFile(
    "ocelot.json", optional: false, reloadOnChange: true);

builder.Services.AddOcelot(builder.Configuration);
builder.Services.AddAuthentication()
    .AddJwtBearer(options =>
    {
        options.Authority =
            builder.Configuration["Identity:Authority"];
        options.Audience = "orders-api";
    });
builder.Services.AddAuthorization();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();
await app.UseOcelot();

app.Run();

Middleware order matters because route policies rely on the authenticated principal established by ASP.NET Core. The JWT configuration in this example assumes an OpenID Connect authority that publishes the expected signing keys and token metadata. Startup validation can also reject malformed route definitions, preventing invalid configuration from reaching production traffic.

Securing traffic and limiting abuse

TLS can terminate at an ingress controller or load balancer, while Ocelot applies the application-level policies configured for each route. JWT validation should check the signature, issuer, audience, expiry and required scopes. A downstream service must still enforce permissions tied to the customer, order or account, since possession of a valid token does not grant every operation.

Apply quotas according to the client, route and authenticated identity. Ocelot can use Redis to share counters across gateway replicas, and a rejected request should return an appropriate 429 response with a usable Retry-After value. Teams can pair policy checks with NUnit and Moq testing at the unit layer.

Australian deployments must also account for the Privacy Act 1988, the Australian Privacy Principles and the OAIC’s Notifiable Data Breaches scheme where they apply. Gateway logs should avoid access tokens, credentials and unnecessary personal information, while retaining enough metadata for an investigation. Administrative and partner routes deserve separate protection through access restrictions, tighter request limits and auditable configuration changes.

Deploying across Australian cloud regions

Azure provides the Australia East region in Sydney and Australia Southeast in Melbourne, while AWS also offers Australian regions in both cities. Co-locating the gateway and its downstream services reduces unnecessary network travel, although not every managed service is available in every region. Service availability and recovery requirements should determine the placement, rather than the region label alone.

Australian Government agencies in Canberra commonly align gateway controls with the Australian Signals Directorate’s Essential Eight and their internal security requirements. Evidence of patching, identity management, logging and application protection can be collected from the platform layer, giving security teams a consistent view across multiple APIs. Managed identity, key rotation and configuration approval fit naturally into this operational model.

Brisbane and Perth users can experience higher latency when every request crosses to an east-coast region. Hybrid connectivity, DNS-aware routing, compression and selective regional replicas can reduce that impact where business requirements justify the extra complexity. Existing on-premises .NET systems may remain behind a private link, with the gateway handling secure translation between environments.

Commercial planning in Australia also benefits from costs expressed in Australian dollars, with GST accounted for separately in budgets. Gateway replicas, Redis capacity and cross-region traffic all contribute to cloud expenditure. Tagging requests by environment and service makes those costs attributable, while a defined monthly threshold prevents an unexpected traffic increase from becoming an oversized infrastructure bill.

Operating the gateway with confidence

Run gateway replicas behind a load balancer so a single process failure does not remove the API from service. Liveness checks should report whether the gateway process is healthy, while downstream failures should trigger the configured routing behaviour rather than restart every healthy replica. Ocelot’s quality-of-service options support timeouts, circuit breaking and retries, with retries restricted to operations that tolerate repetition.

Observability should connect the client request to its downstream call. OpenTelemetry instrumentation, correlation identifiers and structured logs provide that trace across ASP.NET Core and outbound HTTP requests. Useful measures include request rate, error rate and latency percentiles by route template, using the template instead of the raw path to keep identifiers out of metric labels. Logs need the same care around credentials and personal data.

Operational schedules require explicit time-zone handling across Australian offices. Sydney and Melbourne observe daylight saving, while Brisbane and Perth remain on standard time. Storing telemetry in UTC and rendering it with an IANA time zone prevents daylight-saving transitions from distorting incident timelines or release schedules. Runbooks, ownership and tested configuration rollback procedures turn the gateway into a dependable platform component whose policies, measurements and failure behaviour remain visible to every team.