Gotchas

Many errors and incidents (gotchas) are related to web server hosting scenarios. Please review deployment and web hosting common user scenarios below depending on your web server.

IIS

We do not recommend to deploy Ocelot app to IIS environments, but if you do, keep in mind the gotchas below.

  • When using ASP.NET Core 2.2+ and you want to use In-Process hosting, replace UseIISIntegration() with UseIIS(), otherwise you will get startup errors.

  • Make sure you use Out-of-process hosting model instead of In-process one (see Out-of-process hosting with IIS and ASP.NET Core), otherwise you will get very slow responses (see 1657).

  • Ensure all DNS servers of all downstream hosts are online and they function perfectly, otherwise you will get slow responses (see 1630).

The community constanly reports issues related to IIS. If you have some troubles in IIS environment to host Ocelot app, first of all, read open/closed issues, and after that, search for IIS in the repository. Probably you will find a ready solution by Ocelot community members.

Finally, we have special label IIS for all IIS related objects. Feel free to put this label onto issues, PRs, discussions, etc.

Kestrel

We do recommend to deploy Ocelot app to self-hosting environments, aka Kestrel vs Docker. We try to optimize Ocelot web app for Kestrel & Docker hosting scenarios, but keep in mind the following gotchas.

  • Upload and download large files [1], proxying the content through the gateway. It is strange when you pump large (static) files using the gateway. We believe that your client apps should have direct integration to (static) files persistent storages and services: remote & destributed file systems, CDNs, static files & blob storages, etc. We do not recommend to pump large files (100Mb+ or even larger 1GB+) using gateway because of performance reasons: consuming memory and CPU, long delay times, producing network errors for downstream streaming, impact on other routes.

    The community constanly reports issues related to large files, application/octet-stream content type, Chunked Encoding, etc., see issues 749, 1472.
    If you still want to pump large files through an Ocelot gateway instance, use 23.0 version and higher [1].
    In case of some errors, see the next point.

  • Maximum request body size. ASP.NET HttpRequest behaves erroneously for application instances that do not have their Kestrel MaxRequestBodySize option configured correctly and having pumped large files of unpredictable size which exceeds the limit.

    Please review these docs: Maximum request body size | Configure options for the ASP.NET Core Kestrel web server.
    As a quick fix, use this configuration recipe:
    builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    int myVideoFileMaxSize = 1_073_741_824; // assume your file storage has max file size as 1 GB (1_073_741_824)
    int totalSize = myVideoFileMaxSize + 26_258_176; // and add some extra size
    serverOptions.Limits.MaxRequestBodySize = totalSize; // 1_100_000_000 thus 1 GB file should not exceed the limit
});

    Hope it helps.