23.3.0
Spring 2024 (version 23.3.0) aka Twilight Texas release
Codenamed: Twilight Texas
Read the Docs: Ocelot 23.3
⚠️ Important information about Service Discovery❗
Following the substantial refactoring of Service Discovery providers in this release, the community has identified and we have acknowledged several critical service discovery defects with providers such as Consul
, Kube
, and potentially others. The Kube
provider, while somewhat unstable, remains operational; however, the Consul
provider is entirely non-functional. We apologize to the projects and clients affected by these issues.
If your projects rely on the Service Discovery feature and cannot function without it, please refrain from upgrading to version 23.3.0; instead, continue using or revert to the previous version 23.2.2. However, if your team does not utilize the Service Discovery feature, then upgrading to this version should be fine. The Ocelot team is currently working on the v23.3 Hotfixes milestone during the summer of 2024, and we are optimistic that the hotfixed version 23.3.4 is expected to be available at the beginning of September 2024. We appreciate your understanding and support.
What's new?
Service Discovery: Major upgrade of Kube and Consul providers: new "Customization of services creation" feature
-
Introducing a new feature for "Customization of services creation" in two primary service discovery providers: Consul and Kubernetes, developed by @raman-m.
The customization for bothConsul
andKube
providers in service creation is achieved through the overriding of virtual methods in default implementations. The recommendation was to separate the provider's logic and introducepublic virtual
andprotected virtual
methods in concrete classes, enabling:- The use of
public virtual
methods as dictated by interface definitions. - The application of
protected virtual
methods to allow developers to customize atomic operations through inheritance from existing concrete classes. - The injection of new interface objects into the provider's constructor.
- The overriding of the default behavior of classes.
Ultimately, customization relies on the virtual methods within the default implementation classes, providing developers the flexibility to override them as necessary for highly tailored Consul/K8s configurations in their specific environments.
For further details, refer to the respective pull requests for both providers:Kube
#2052,Consul
#2067 - The use of
Routing: New "Routing based on Request Header" feature
- Introducing the new "Routing based on Request Header" feature by @jlukawska.
In addition to routing viaUpstreamPathTemplate
, you can now define anUpstreamHeaderTemplates
options dictionary. For a route to match, all headers specified in this section are required to be present in the request headers.
For more details, see PR #1312.
Configuration: New "Custom Default Version Policy" and "Route Metadata" features
-
Introducing the "Custom Default Version Policy" feature by @ibnuda.
The configurableHttpRequestMessage.VersionPolicy
helps avoid HTTP protocol connection errors and stabilizes connections to downstream services, especially when you're not developing those services, documentation is scarce, or the deployed HTTP protocol version is uncertain.
For developers of downstream services, it's possible toConfigureKestrel
server and its endpoints with new protocol settings. However, attention to version policy is also required, and this feature provides precise version settings for HTTP connections.
Essentially, this feature promotes the use of HTTP protocols beyond 1.0/1.1, such as HTTP/2 or even HTTP/3.
For additional details, refer to PR #1673. -
Introducing the new "Route Metadata" feature by @vantm. Undoubtedly, this is the standout feature of the release! ⭐
Route metadata enables Ocelot developers to incorporate custom functions that address specific needs or to create their own plugins/extensions.
In versions of Ocelot prior to 23.3.0, the configuration was limited to predefined values that Ocelot used internally. This was sufficient for official extensions, but posed challenges for third-party developers who needed to implement configurations not included in the standardFileConfiguration
. Applying an option to a specific route required knowledge of the array index and other details that might not be readily accessible using the standardIConfiguration
orIOptions<FileConfiguration>
models from ASP.NET. Now, metadata can be directly accessed in theDownstreamRoute
object. Furthermore, metadata can also be retrieved from the global JSON section via theFileConfiguration.GlobalConfiguration
property.
For more information, see the details in PR #1843 on this remarkable feature.
Focus On
Updates of the features: Configuration, Service Discovery, Routing and Quality of Service
-
Configuration: New features are "Custom Default Version Policy" by @ibnuda and "Route Metadata" by @vantm.
-
Service Discovery: New feature is "Customization of services creation" by @raman-m.
-
Routing: New feature is "Routing based on Request Header" by @jlukawska.
-
Quality of Service: The team has decided to remove the Polly V7 policies logic and the corresponding Ocelot
AddPollyV7
extensions (referenced in PR #2079). Furthermore, the Polly V8 Circuit Breaker has been mandated as the primary strategy (as per PR #2086).
See more detailed below in "Ocelot extra packages" paragraph.
Ocelot extra packages
-
-
Our team has resolved to eliminate the Polly V7 policies logic and the corresponding Ocelot
AddPollyV7
extensions entirely (refer to the "Polly v7 vs v8" documentation). In the previous 23.2 release, named Lunar Eclipse, we included these to maintain the legacy Polly behavior, allowing development teams to transition or retain the old Polly V7 functionality. We are now confident that it is time to progress alongside Polly, shifting our focus to the new Polly V8 resilience pipelines. For more details, see PR #2079. -
Additionally, we have implemented Polly v8 Circuit Breaker as the primary strategy. Our Quality of Service () relies on two main strategies: Circuit Breaker and Timeout. If both Circuit Breaker and Timeout are configured with their respective properties in the
QoSOptions
of the route JSON, then the Circuit Breaker strategy will take precedence in the constructed resilience pipeline. For more details, refer to PR #2086.
-
Stabilization aka bug fixing
- Fixed #2034 in PR #2045 by @raman-m
- Fixed #2039 in PR #2050 by @PaulARoy
- Fixed #1590 in PR #1592 by @sergio-str
- Fixed #2054 #2059 in PR #2058 by @thiagoloureiro
- Fixed #954 #957 #1026 in PR #2067 by @raman-m
- Fixed #2002 in PR #2003 by @bbenameur
- Fixed #2085 in PR #2086 by @RaynaldM
- See all bugs of the Spring'24 milestone
Documentation for version 23.3.0
- Caching: New EnableContentHashing option and Global Configuration sections
- Configuration: New DownstreamHttpVersionPolicy and Route Metadata sections
- Metadata: This is new chapter for Route Metadata feature.
- Quality of Service
- Rate Limiting
- Request Aggregation
- Routing: New Upstream Headers section
- Service Discovery: New Consul Service Builder and Downstream Scheme vs Port Names sections
- Kubernetes: New Downstream Scheme vs Port Names section
Honoring 🏅 aka Top Contributors 👏
1st 🥇 goes to Ibnu Daru Aji for delivering 1 feature in 42 files changed
2nd 🥈 goes to Jolanta Łukawska for delivering 1 feature in 39 files changed
3rd 🥉 goes to Van Tran for delivering 1 feature in 31 files changed
Starring ⭐ aka Release Influencers
⭐⭐⭐⭐⭐ Raman Maksimchuk, @raman-m
⭐⭐ Raynald Messié, @RaynaldM
⭐ Ibnu Daru Aji, @ibnuda
⭐ Jolanta Łukawska, @jlukawska
⭐ Van Tran, @vantm
⭐ Béchir Ben Ameur, @bbenameur
⭐ Paul Roy, @PaulARoy
⭐ Sergii Strikhar, @sergio-str
⭐ Thiago Loureiro, @thiagoloureiro
⭐ Zhannur Akhmetkhanov, @hogwartsdeveloper
Features in Release 23.3.0
Milestone: Spring'24
Logbook
- 696fa07 by Raman Maksimchuk on Friday, June 7 at 21:59 →
Release 23.3 Artifacts | +semver: minor (#2089) - 8c1c61e by Raynald Messié on Thursday, June 6 at 10:41 →
#2085 Enforce Polly v8 Circuit Breaker as the primary strategy (#2086) - a034e8c by Béchir BEN AMEUR on Monday, June 3 at 19:48 →
#2002 Early removal of a replaced placeholder parameter inDownstreamUrlCreatorMiddleware
(#2003) - ee1fb97 by Raynald Messié on Friday, May 31 at 17:36 →
#2078 V7 polly syntax not longer supported (#2079) - cc8f5c5 by Zhannur Akhmetkhanov on Tuesday, May 28 at 18:11 →
Ocelot NuGet package README file (#2074) - 34cb3eb by Raman Maksimchuk on Monday, May 27 at 13:03 →
#954 #957 #1026 Customize Consul services creation inConsul
service discovery provider (#2067) - 573a9d9 by Van Tran on Wednesday, May 22 at 3:06 →
#738 #1990 Route Metadata as custom properties (#1843) - 6e9a975 by Thiago Loureiro on Monday, May 13 at 21:03 →
#2054 #2059 ManageEnableContentHashing
setting by globalCacheOptions
(#2058) - aef3e6b by Sergii on Tuesday, May 7 at 14:09 →
#1590 Use correct interval for request counting (#1592) - 0b247af by Raman Maksimchuk on Friday, April 26 at 18:38 →
#1967 Customize K8s services creation inKube
service discovery provider (#2052) - 233f87a by Paul Roy on Thursday, April 25 at 13:37 →
#2039 Buffer request body and copy the body to downstreams during multiplexing (#2050) - 176a4c8 by Ibnu Daru Aji on Friday, April 19 at 19:21 →
#1672 Custom Default Version Policy (#1673) - 6cef42e by jlukawska on Thursday, April 18 at 18:30 →
#360 Routing based on request header (#1312) - ab9fb65 by Raman Maksimchuk on Wednesday, April 17 at 12:49 →
Notes about Merging Configuration Files feature inconfiguration.rst
(#2048) - 59b63ea by Raman Maksimchuk on Friday, April 12 at 18:30 →
#2034 More rapid CircleCI builds (Part 1) (#2045)