24.1.0

Summer-Autumn 2025 (version 24.1) aka Globality release

Milestone: Summer'25
Codenamed: Globality
Read the Docs: Ocelot 24.1 with PDF

ℹ️ About

In this minor release, the Ocelot team put the spotlight on the Configuration feature as part of their semi-annual 2025 effort, with a particular focus on the Global Configuration Schema. This release enhances support for global configurations across both routing modes: the classic static Routing and the service discovery-based Dynamic Routing.

The updated documentation highlights the deprecation of certain options through multiple notes and warnings. This deprecation process will be completed in the upcoming .NET 10 release. With the [Obsolete] attributes in place, C# developers will notice several warnings in the build logs during compilation.

On top of that, this release brings a great enhancement to the Kubernetes provider, also known as the Ocelot.Provider.Kubernetes package.

🆕 What's New?

Configuration: The "Dynamic routing global configuration" feature has been redesigned by @raman-m and contributors.

This update brings changes to the Dynamic Route Schema and Global Configuration Schema, while the Route Schema stays the same apart from deprecation updates. All work was coordinated under issue #585, which addressed the challenges of configuring Ocelot's most popular features globally before version 24.1, when dynamic routing gained global configuration partial support, but static routing mostly lacked it. A key outcome of #585 is the ability to override global configuration options within the DynamicRoutes collection. This ongoing issue will continue to require attention, as adapting static route global configurations for dynamic routing is complex and, in some cases, impossible. This will be a challenge for future Ocelot releases and the community.

Kubernetes: The "Kubernetes provider based on watch requests" feature by @kick2nick in PR #2174. ⭐

The Ocelot.Provider.Kubernetes package now features a new WatchKube provider for Kubernetes service discovery. This provider is a great fit for high-load environments where the older Kube and PollKube providers struggle to handle heavy traffic, often leading to increased log errors, HTTP 500 issues, and potential Ocelot instance failures. WatchKube is the next step in the evolution of these providers, leveraging the reactive capabilities of the KubeClient API. For guidance on choosing the right provider for your Kubernetes setup, check out the "Comparing providers" section in the documentation.

Configuration: The "Routing default timeout" feature by @hogwartsdeveloper in PR #2073.

In the past, the Timeout setting in the Route Schema didn't actually stop requests, defaulting instead to a fixed 90 seconds. Custom timeouts were handled using the Quality of Service Timeout strategy, and this only applied if Polly and the Ocelot.Provider.Polly package were used. Now, the Timeout option (in seconds) can be set at the route, global, and QoS levels. The Global Configuration Schema and Dynamic Route Schema also include the new Timeout setting, making it possible to configure default timeouts for dynamic routing as well.

Quality of Service: The "FailureRatio and SamplingDuration parameters of Polly V8 circuit-breaker" feature by @RaynaldM in PR #2081.

Starting with version 24.1, two new parameters in QoSOptions, FailureRatio and SamplingDuration, let you fine-tune the behavior of the Circuit Breaker strategy. Both can be configured globally, even with dynamic routing.
Please note that DurationOfBreak, ExceptionsAllowedBeforeBreaking, and TimeoutValue are now deprecated in 24.1, so check the QoSOptions Schema documentation for details.

🆙 What's Updated?

Configuration: Several File-model options have been deprecated by @raman-m.

The updated docs now highlight these deprecated options with multiple notes and warnings. The v24.1 deprecation process will wrap up in the upcoming .NET 10 release. Due to the Obsolete attributes, C# developers will notice several build warnings during compilation.

Testing: The Ocelot.Testing project was deprecated by @raman-m in PR #2295.

The project was removed from the main repo and moved to its own Ocelot.Testing repository. This change allows the Ocelot.Testing package to be shared independently for extension package delivery. The Ocelot team also plans to deprecate more projects and move them to separate repos because: a) despite the fact that a monorepo enables faster builds and quicker delivery; b) but the release process can be delayed by missing versions of integrated libraries in extension packages. The goal is for the Ocelot repo to only contain essential projects, avoiding delays caused by integrated package release schedules. Legacy or abandoned integrated packages should be deprecated and maintained in their own repos with independent release cycles.

...

24.0.1

🔥 Hotfix for issue #2299 (version 24.0.1), aka v24.0.0 patch 📦

Read the Docs: Ocelot 24.0 with PDF
Hot fixed version: 24.0.0
Milestone: .NET 9

ℹ️ About

🔥 Hot fixed issue: #2299
❤️ A sincere and heartfelt "Thank You" to Gracjan Bryłka, @font3r for reporting the bug.

⚠️ Warning

1. This patch updates only the Ocelot.Provider.Kubernetes extension package to version 24.0.1.
2. No further patches are planned for this major version. The next minor release, version 24.1, codenamed "Globality", is scheduled for Summer-Autumn 2025.

❗ Breaking Changes

Interface Breaking Changes:

• IKubeApiClientFactory interface removal: The ServiceAccountPath property was removed because it was not intended for public use.
  Interface FQN: Ocelot.Provider.Kubernetes.Interfaces.IKubeApiClientFactory
  Property FQN: Ocelot.Provider.Kubernetes.Interfaces.IKubeApiClientFactory.ServiceAccountPath

What's Changed

• #2299 Encapsulate ServiceAccountPath as a protected property of the factory to stabilize KubeApiClient creation in the Kubernetes provider by @raman-m in #2302
• Release v24.0.1 | Hotfix for issue #2299 | .NET 9 release | +semver: patch by @raman-m in #2303

Full Changelog: 24.0.0...24.0.1

Ocelot.Administration.IdentityServer4 v24.0.1

Ocelot.Administration.IdentityServer4 version 24.0.1

Ocelot release: 24.0.0
Ocelot.Administration.IdentityServer4 release: 24.0.1
NuGet package: Ocelot.Administration.IdentityServer4.24.0.1

❗ Breaking Changes

The Ocelot.Administration extension package has been renamed to Ocelot.Administration.IdentityServer4 ❗

Feature: Administration

All IdentityServer4-related vulnerabilities (issue #2218) were addressed. The Ocelot.Administration source code has been moved out of the Ocelot repository (pull request #2274) and transferred to the Ocelot.Administration.IdentityServer4 repository.

Currently, the Administration feature is solely based on the IdentityServer4 package, whose repository was archived by its owner on July 31, 2024. In this release, the Ocelot team deprecated the Ocelot.Administration.IdentityServer4 extension package after the current Ocelot v24.0 release; however, the repository is/will not be archived, allowing for potential patches in the future.

Note: In upcoming releases, the Ocelot team plans to utilize the ASP.NET Core Identity framework for Administration feature development and in Ocelot's acceptance testing project to align with .NET industry standards. As a result, the IdentityServer4 library is intended to be replaced with ASP.NET Core Identity, which also supports Bearer tokens, commonly known as JwtBearerHandler from the Microsoft.AspNetCore.Authentication.JwtBearer namespace.

24.0.0

Upgrade to .NET 9 (TFM net9.0, version 24.0) aka .NET 9 release

Milestone: .NET 9
Codenamed: .NET 9
Read the Docs: Ocelot 24.0 with PDF
Target Framework Monikers: net8.0, net9.0

ℹ️ About

On November 12th, 2024, the .NET team announced the release of the .NET 9 framework:

• .NET Blog: Announcing .NET 9

This major release upgrades Ocelot package TFMs to net9.0 in addition to the current net8.0. Thus, the current Ocelot supported frameworks are .NET 8 LTS and .NET 9 STS. According to the .NET Support Policy, the Ocelot team has discontinued support of .NET 6 and .NET 7 by providing the version 23.4.3 which targets those .NET versions.

🔖 Official Notice to the Community Regarding CircleCI

Ocelot's previous CI/CD provider, CircleCI, facilitated professional and seamless development, build processes, and delivery of Ocelot versions for seven years, starting in March 2018. But last year, in January 2025, after patching Ocelot with version 23.4.3, our team encountered legal issues related to CircleCI Co's policies, leading to this CI/CD provider stopping the build process for the Ocelot project. This legal issue and technical incident were unforeseen on our part because Ocelot is open-source software (OSS), and forcibly stopping the project's build process and blocking accounts appears to be an unfortunate breach of OSS principles. We strongly believe that any developer or user, from any country, should be able to use software providers that support the OSS movement by offering free or other cost-free plans and serving the accounts of these users, OSS teams, and OSS projects 24/7, 365 days a year. We consider this legal issue and the resulting technical incidents involving CircleCI to be a serious breach of OSS principles and an act of discrimination against Ocelot users, developers, and customers who rely on Ocelot OSS, ultimately causing delays to the current release. As a team, we do not recommend using CircleCI for OSS projects, as there is no guarantee that these projects will not face discrimination from this U.S. company.

For all developers, team leads, architects, and managers of any OSS projects—at least on GitHub—we recommend utilizing the built-in GitHub Actions CI/CD infrastructure. Since its founding, GitHub has supported OSS projects. Today, GitHub provides 2,000 minutes of free CI/CD build time per month for OSS repositories (public repos). Also, we strongly believe that GitHub will never violate its OSS policies without a notice period, nor fail to inform owners and maintainers that certain policies must be met by Ocelot's owners. In addition, we want to acknowledge that we are monitoring U.S. government regulations. Unfortunately, we must state that some GitHub products are unavailable in certain countries, even if the project is OSS and GitHub claims these products are free for OSS. Since the Ocelot team does not utilize these non-critical products (we prefer to energize our brains rather than rely on AI-driven products), and since the Ocelot project is currently well-served by GitHub Co, the Ocelot team affirms that Ocelot will remain on GitHub as long as its OSS-friendly policies continue. As a team, we hope that GitHub will never enforce extra rules on our project or other OSS projects.
Regardless, we remain on GitHub!

🆕 What's New?

DevOps: The CI/CD infrastructure was migrated from CircleCI to GitHub Actions by @raman-m

Starting from version 24.0, all pull requests, development commits, and releases will be built using GitHub Actions workflows (documentation). We currently have three workflows: one for pull requests (PR), one for the develop branch (Develop), and one for the main branch (Release). All workflow runs are available on the Actions dashboard.

The PR workflow will track code coverage using Coveralls. After opening a pull request or submitting a new commit to a pull request, Coveralls will publish a short message with the current code coverage once the top commit is built. Considering that Coveralls retains the entire history but does not fail the build if coverage falls below the threshold, all workflows have a built-in 80% threshold, applied internally within the build-cake job, particularly during the "Cake Build" step-action. If the code coverage of a newly opened pull request drops below the 80% threshold, the build-cake job will fail, logging an appropriate message in the "Cake Build" step. For your information, the current code coverage of the Ocelot project is around 85-86%. The coverage threshold is subject to change in upcoming releases. All Coveralls builds can be viewed by navigating to the ThreeMammals/Ocelot project on Coveralls.io.

🆙 What's Updated?

Core:

The main Ocelot package and all extension packages reference net8.0 and net9.0 target framework monikers (TFMs). Refer to TargetFrameworks to verify this. The net6.0 and net7.0 TFMs have been removed. If your project still relies on these outdated TFMs, please continue using version 23.4.3.

Authentication:

Testing of Identity Server Bearer Tokens functionality was stopped due to vulnerabilities reported by Dependabot, specifically the "IdentityServer Open Redirect vulnerability" security issue. More technical details were provided in the 23.4.3 release notes, where we notified the community. Ultimately, issue #2218 was addressed via pull request #2274.

Note: In upcoming releases, we plan to utilize the ASP.NET Core Identity framework in our acceptance testing project to align with .NET industry standards. As a result, we intend to replace the IdentityServer4 library with ASP.NET Core Identity, which also supports Bearer tokens, also known as JwtBearerHandler from the Microsoft.AspNetCore.Authentication.JwtBearer namespace.

Administration:

The Ocelot.Administration extension package has been renamed to Ocelot.Administration.IdentityServer4 (it is scheduled for deprecation) to address all IdentityServer4-related vulnerabilities (issue #2218). The package's source code has been moved out of the Ocelot repository (pull request #2274) and transferred to the newly created [Ocelot.Administration.IdentityServer4](https://github.com/ThreeM...

23.4.3

🔥 Hot fixing #2246 issue (version 23.4.3) aka v23.4.2 patch 📦

Read the Docs: Ocelot 23.4 with PDF
Hot fixed version: 23.4.2
Milestone: November'24

ℹ️ About

🔥 Hot fixed issue: #2246
❤️ A sincere and heartfelt "Thank You" to Donny Tian, @donnytian for reporting the bug.

⚠️ Warning

1. Consider this patch as the last one supporting .NET 6 and 7 frameworks. For more details, refer to the previous version notes.
2. No further patches for this minor version are expected. The next major release will be .NET 9, version 24.0.

❗ Breaking Changes

Upgrading from 23.4.0-23.4.2 to 23.4.3 introduces no breaking changes. However, some internal interfaces have been updated, which should not introduce IBC for 99.99% of projects. For further information, refer to the source code.

What's Changed

• #2246 Review Core cache and redesign Regex caching by @raman-m in #2251
• Release 23.4.3 | Hot fixing #2246 | November'24 release | +semver: patch by @raman-m in #2252

Full Changelog: 23.4.2...23.4.3

23.4.2

📦 End of .NET 6, 7 Support (version 23.4.2)

Read the Docs: Ocelot 23.4 with PDF
Hot fixed version: 23.4.1
Milestone: November'24

This is the last patched version for .NET 6 and 7 frameworks. The upcoming major release, version 24.0, will target .NET 9 alongside the LTS .NET 8. Projects targeting .NET 6 or 7 should update to this version while considering an upgrade to .NET 8 or 9 in the future.

ℹ️ About

• All package versions have been updated to latest versions targeting the net6.0 and net7.0 frameworks, along with the LTS net8.0.
• Dependabot alerts concerning reported vulnerabilities related to IdentityServer4 have not yet been addressed; these will be resolved in the next major release (refer to Warnings further information).

❗ Warning

1. Releasing a patched 23.4.* is possible.
2. In the next major version, the Ocelot team will remove references to the IdentityServer4 package from testing projects due to its "Public Archive" status; the version, 4.1.2, was released on July 7, 2021.
3. The main Ocelot package is not integrated with IdentityServer4, allowing Ocelot users to utilize any authentication provider, as Ocelot's Authentication feature is provider-agnostic.
4. Our plans to utilize the ASP.NET Core Identity framework in testing projects due to industry standards, instead the IdentityServer4 library.
5. Following the release of .NET 9, the team will begin the deprecation of the Ocelot extension-packages: Ocelot.Cache.CacheManager, Ocelot.Tracing.Butterfly, and Ocelot.Tracing.OpenTracing.

What's Changed

• Review Dependabot alerts for net6.0 and net7.0 target frameworks and bump all packages by @raman-m in #2220
• Release 23.4.2 | End of .NET 6, 7 Support | November'24 release | +semver: patch by @raman-m in #2221

Full Changelog: 23.4.1...23.4.2

23.4.1

📦 Routing patch (version 23.4.1)

Read the Docs: Ocelot 23.4 with PDF
Hot fixed version: 23.4.0
Milestone: November'24

❤️ A heartfelt "Thank You" to Guillaume Gnaegi (@ggnaegi)

ℹ️ About

🔥 Hot fixed issues: #2165 #2209 #2212

What's Changed

• #2165 Global configuration SecurityOptions by @Fabman08 in #2170
• #2209 Placeholders matching must work if RouteIsCaseSensitive = false by @ggnaegi in #2210
• File-scoped namespaces everywhere by @raman-m in #2211
• #2212 Incorrect calculation of placeholders, only the last placeholder should be allowed to match several segments by @ggnaegi in #2213
• Release 23.4.1 | Routing patch | November'24 release | +semver: patch by @raman-m in #2215

Full Changelog: 23.4.0...23.4.1

23.4.0

🔀 Routing Update (version 23.4.0) aka McDonald's release

Codenamed: McDonald's
Read the Docs: Ocelot 23.4.0

ℹ️ About

This minor release significantly upgrades the Routing feature by supporting embedded placeholders within path segments (between slashes). Additionally, the team has focused on enhancing the performance of Regex objects.

🆕 What's new?

• Routing: Introducing the new "Embedded Placeholders" feature by @ggnaegi.
  As of November 2024, Ocelot was unable to process multiple placeholders embedded between two forward slashes. It was also challenging to differentiate the placeholder from other elements within the slashes. For example, /{url}-2/ for /y-2/ would yield {url} = y-2. We are excited to introduce an enhanced method for evaluating placeholders that allows for the resolution of placeholders within complex URLs.
  For additional information, refer to PR #2200.

🆙 Focus On

Features: Routing, Core, Rate Limiting, Middleware Injection

• Routing: The new feature is "Embedded Placeholders" by @ggnaegi.
• Core: All Regex logic has been refactored by @EngRajabi.
  The Ocelot Core now boasts improved performance of Regex objects, striving to adhere to the Best Practices for Regular Expressions in .NET. It is estimated that each request could save from 1 to over 10 microseconds in processing time (though no benchmarks have been developed to measure this).
• Rate Limiting: The persistent issue with Rate Limiting headers has been resolved by @jlukawska.
  The problem was the absence of unofficial X-Rate-Limit-* headers (found in the RateLimitingHeaders class) in the RateLimitingMiddleware's response. For more details, see PR #1307.
  Note that these unofficial headers have not yet been documented, so they may be subject to change since Ocelot's RateLimiting headers do not align with industry standards.
• Middleware Injection: The OcelotPipelineConfiguration.ClaimsToHeadersMiddleware property has been introduced by @kesskalli.
  This new property enables the overriding of the ClaimsToHeadersMiddleware. For additional information, refer to PR #1403.

Documentation for v23.4.0

• Routing: Introducing a new section on Embedded Placeholders
• Middleware Injection: Documentation now includes the ClaimsToHeadersMiddleware feature

Honoring 🏅 aka Top Contributors 👏

1^st 🥇 goes to Mohsen Rajabi for delivering 1 feature in 12 files changed
2^nd 🥈 goes to Jolanta Łukawska for delivering 1 feature in 8 files changed
3^rd 🥉 goes to Karim Esskalli for delivering 1 feature in 6 files changed

Starring ⭐ aka Release Influencers

⭐ Mohsen Rajabi, @EngRajabi
⭐ Jolanta Łukawska, @jlukawska
⭐ Raman Maksimchuk, @raman-m
⭐ Karim Esskalli, @kesskalli
⭐ Guillaume Gnaegi, @ggnaegi

Features in Release 23.4.0

Logbook

• _{41fc9bd by Raman Maksimchuk on Monday, November 18 at 23:40 →}
  Release 23.4 | Routing Update | MGGA release | +semver: minor (#2206)
• _{27d3df2 by Guillaume Gnaegi on Sunday, November 17 at 15:24 →}
  #2199 Adding support of placeholder matching between slashes👍 (#2200)
• _{d76fc95 by Mohsen Rajabi on Saturday, November 16 at 21:39 →}
  Best practices for regular expressions versus Regex performance review (#1348)
• _{da9d6fa by jlukawska on Saturday, November 9 at 18:09 →}
  #1305 Populate RateLimiting headers in the original HttpContext response accessed via IHttpContextAccessor (#1307)
• _{d310508 by kesskalli on Tuesday, November 5 at 19:09 →}
  Override the ClaimsToHeadersMiddleware by the OcelotPipelineConfiguration settings (#1403)

What's Changed

• Override the ClaimsToHeadersMiddleware by the OcelotPipelineConfiguration settings by @kesskalli in #1403
• #1305 Populate RateLimiting headers in the original HttpContext response accessed via IHttpContextAccessor by @jlukawska in #1307
• Best practices for regular expressions versus Regex performance review by @EngRajabi in #1348
• #2199 Adding support of placeholder matching between slashes👍 by @ggnaegi in #2200
• Release 23.4 | Routing Update | MGGA release | +semver: minor by @raman-m in #2206

New Contributors

• @kesskalli made their first contribution in #1403

Full Changelog: 23.3.6...23.4.0

23.3.6

🔥 Hot fixing v23.3.4 (version 23.3.6) aka October'24 release

Read the Docs: Ocelot 23.3
Hot fixed version: 23.3.4
Milestone: October'24

❤️ A heartfelt "Thank You" to Nikolai Masson (@Niksson) and Nikolay Kuksov (@kick2nick) for their contributions!

ℹ️ About

This release provides minor bug fixes from the previous 23.3.4 release. All bugs have been addressed in the October'24 milestone.

📓 For projects utilizing the Service Discovery feature, it is recommended to update to this version to benefit from the unstable release 23.3.4, which includes fixes for both Consul and Kube discovery providers.

🧑‍💻 Technical Information

The Ocelot solution encountered a significant issue with the disabled scope validation of services in the DI-container, affecting both testing projects and the core library. Initially, this was not problematic when services were designed as singletons by previous contributors and our team. However, with the introduction of more scoped services by the Ocelot team, it became clear that our testing projects could not adequately handle them.
This patch introduces scope validation across all domains: unit tests, acceptance tests, and the core library itself. We advise always enabling scope validation in your custom Ocelot solutions, especially when dealing with numerous C# overridden classes in the DI-container and any attached custom functionality.

The patch enhances functionality for two primary Service Discovery providers:

• The Ocelot.Provider.Consul provider. The addressed bug is issue #2178, reported on October 17, 2024.
  The System.InvalidOperationException error stating "Cannot resolve scoped service 'Ocelot.Provider.Consul.Interfaces.IConsulServiceBuilder' from root provider" has been resolved.
  To clarify, the IConsulServiceBuilder service is a scoped service in DI, injected via the AddConsul() or AddConsul<T>() methods. Therefore, the DefaultConsulServiceBuilder should also be a scoped service, with HttpContext injected to meet your development requirements.
• The Ocelot.Provider.Kubernetes provider had an issue reported as #977 on August 1, 2019.
  It involved a System.InvalidOperationException with the message: "Cannot resolve scoped service 'KubeClient.IKubeApiClient' from root provider." This "invalid scopes" error occurred only in development mode, as release mode DLLs do not validate scopes. However, the KubeApiClient is designed to have a scoped lifetime. Acceptance tests passed because scope validation was disabled, and the KubeClient was replaced with a singleton. This inconsistency was identified and reproduced by the old 977 issue. As a temporary solution, the IKubeApiClient was registered as a singleton.
  Looking ahead, our team intends to redesign the Kubernetes provider to have a default service builder that is scoped, similar to the Consul provider.

❗ Breaking Changes

Upgrading from 23.3.4 to 23.3.6 introduces no breaking changes. However, upgrading from 23.3.0 or earlier versions may result in some incompatibilities. For further information, please refer to the release notes of v23.3.4.

Starring ⭐ aka Release Influencers

⭐⭐ Raman Maksimchuk, @raman-m
⭐ Henrique Holtz, @henriqueholtz
⭐ Nikolay, @kick2nick
⭐ Nikolai Masson, @Niksson
⭐ Emmanuel Ferdman, @emmanuel-ferdman
⭐ dependabot[bot], @dependabot

What's Changed

• Bump everything | Hot fixing Microsoft.Extensions.Caching.Memory | Microsoft Security Advisory CVE-2024-43483 by @dependabot in #2175
• Coding best practices: async vs await improvements by @henriqueholtz in #2156
• #2178 DI service resolution from scoped HttpContext request services for the IConsulServiceBuilder service by @Niksson in #2179
• #977 Enable validation of DI scopes in Kube and PollKube discovery providers by @kick2nick in #2180
• Follow up #2179 #2180 : Enable validation of DI scopes everywhere, in commit e4bc9ff by @raman-m
• Correct broken references in servicediscovery.rst by @emmanuel-ferdman in #2187
• Release 23.3.6 | v23.3.4 Hotfixes | October'24 release | +semver: patch by @raman-m in #2185

New Contributors

• @henriqueholtz made their first contribution in #2156
• @Niksson made their first contribution in #2179
• @kick2nick made their first contribution in #2180

Full Changelog: 23.3.5...23.3.6

23.3.5

📦 Documentation patch (version 23.3.5), technical release

Read the Docs: Ocelot 23.3
PDF Doc: Ocelot 23.3
Hot fixed version: 23.3.4

ℹ️ About

This documentation patch pertains to HTML and PDF document layouts.
No NuGet packages have been uploaded.