Welcome

Welcome to the Ocelot 24.0 documentation!

It is recommended to read all Release Notes if you have deployed the Ocelot app in a production environment and are planning to upgrade to major, minor or patched versions.

Release Notes

Release Tag: 24.0.0

Release Codename: .NET 9

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

• Announcing .NET 9 | .NET Blog

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.2 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 repository.

  Note: Currently, the Administration feature is solely based on the IdentityServer4 package, whose repository was archived by its owner on July 31, 2024. The Ocelot team will deprecate the new Ocelot.Administration.IdentityServer4 extension package after the current Ocelot release; however, the repository will not be archived, allowing for potential patches in the future.

• Kubernetes (K8s) :

  1. Answered question 2256 on “How to provide a host to the Kubernetes service discovery provider?” Unfortunately, in the Kubernetes (K8s) chapter, it was unclear to users how to define a K8s endpoint host in the Configuration due to the implicit reuse of KubeClient, which is created from the pod account during Install-ation. As a team, we decided to add the new AddKubernetes(Action<KubeClientOptions>) method 2, which handles different user scenarios. It is now possible to provide manually configured KubeClientOptions in C# during Install-ation, but users can also reuse ServiceDiscoveryProvider options from the global Configuration, including the Host option to construct the Kubernetes (K8s) endpoint address. The new overloaded AddKubernetes(Action<KubeClientOptions>) method was implemented in pull request 2257.

  2. In the Ocelot.Provider.Kubernetes extension package, the KubeClient dependency library version was upgraded to 3.0.x, which requires .NET 8.0 and .NET 9.0 TFMs for the current Ocelot version 24.0. KubeClient v3 was internally reviewed and released specifically to meet Ocelot’s needs for this release. Thanks to Adam Friedman (@tintoy) for his collaboration! This package upgrade was implemented in pull request 2266.

• Sample:

  The learning Samples projects were reviewed, rewritten, and refactored due to issue 1912. The community brought to our attention that the documentation and Samples were outdated, as .NET 8 allows the Program.cs file to be minimized using the Top-level statements feature. This was ultimately addressed in pull requests 2244 and 2258.

Documentation Summary

Due to the major version increase to v24, all documentation chapters were reviewed to improve readability, eliminate ambiguity, provide more useful tables and data schemas, update code snippets with the syntax of Top-level statements, and add handy samples, among other enhancements. The entire documentation is designed to be truly professional for senior developers while remaining easy to read for junior developers and newcomers who are starting to use the Ocelot gateway.

We believe that Ocelot students will ask fewer questions in 2025 🙂 For students, we always recommend finding answers in Q&A category first. Honestly, it is advised to read existing discussions before opening a new question in repo Discussions. For true Ocelot patriots, we have added a README link to the smart Ocelot AI Guru assistant, which is always ready to answer any of your questions. Feel free to explore and interact with it! 😊

Contributing

Pull requests, issues, and commentary are welcome at the Ocelot GitHub repository. For ideas and questions, please post them in the Ocelot Discussions space.

Our Development Process is a part of successful Release Process. If you are a new contributor, it is crucial to read Development Process attentively to grasp our methods for efficient and swift feature delivery. We, as a team, advocate adhering to Best Practices throughout the development phase.

We extend our best wishes for your successful contributions to the Ocelot product!