The problem

Currently, we support installing the Operator only in the namespaced mode, i.e. to deploy Keycloak in a namespace, an Operator instance needs to live in the same namespace. This is problematic for a couple of reasons:

• The Operator requires cluster-wide permissions to read Ingress configuration on OpenShift. This is especially problematic for namespace admins that may lack those kind of permissions.
• CRDs are a cluster-wide resource. Typically, the last installed Operator instance overrides them. This is problematic as it might introduce CRDs incompatible (either removed fields, or new fields) with other previously installed Operators.
• Resources wasting. The Operator can handle a number of Keycloak deployments. With namespaced mode, a single Operator instance typically handles a single Keycloak instance and then it's sitting idle for most of the time.

The solution: Cluster-wide Operator

With cluster-wide Operator, there can be a single Operator instance for the whole cluster, managing all Keycloak instances in all namespaces.

Considerations

• Release cycle. The Operator release cycle is currently fully aligned with Keycloak. This is also reflected in the support policy: Operator supports handling of exactly one Keycloak version, the same as the Operator. This is problematic for the cluster-wide Operator as it would require all Keycloak instances in the whole cluster to be the same version, and every Operator upgrade would require updating all Keycloak instances.
• Rolling updates. If a new Operator version updates some field on all Keycloak deployments, that might cause a wave of rolling updates across the cluster, causing resources requirements spike.
• Version (and feature) awareness. If the Operator was able to manage multiple Keycloak versions, it needs to be aware of the specific Keycloak instance version and enabled features. Despite Keycloak minor versions being backwards compatible, an Operator minor release might add a feature that depends on another feature added in given Keycloak minor release. That would make the Operator incompatible with older Keycloak versions. This problem is not limited to just Keycloak version but also to enabled features in Keycloak and their version as Keycloak behaviour is often not defined by its version but rather by the features.

Proposed plan

Milestone 1: basic MVP, supporting a single Keycloak version

To resolve majority of the issues and satisfy the demand from users for the cluster-wide Operator as quickly as possible, we'd expose the cluster-wide mode and document it. It is already implemented and handled by JOSDK but it is hidden in the Keycloak Operator.

The caveat here would be everything mentioned above in "Considerations". Those would need to be explicitly documented. The most prominent limitation would be the 1:1 version mapping of the Operator and Keycloak. Hence, the feature would be marked just as a Preview.

Estimated effort: low. We're just exposing already implemented functionality. What is missing is some basic tests, and docs.

Milestone 2: supporting Keycloak version range

As the next step, a single Operator version would support all Keycloak versions for the same major release. E.g. Operator version 27.3 would support Keycloaks 27.0, ..., 27.3, 27.4, ... 27.8, etc.

This would require the Operator to check the Keycloak version, or possibly better: the enabled features versions. This would cover the scenarios when newer Operator is used with older Keycloak – the Operator would disable some of its features that require features enabled at the Keycloak side. Version awareness would also help with the "rolling updates" consideration – Operator would keep the original fields on the deployment based on the Keycloak version, not Operator version.

Forward compatibility (older Operator, newer Keycloak) is ensured implicitly – we don't introduce breaking changes to Keycloak in minor releases.

Estimated effort: high. We'd need to introduce a mechanism for fetching versioning metadata from Keycloak. Additionally, if features were considered as well, we might need to wait for the future refinement of our features story.

Related

• Cluster-wide Operator #43955