{project_name} undergoes large refactoring, which impacts existing code.
Some of these changes require updates to existing code.
These are in more detailed described below.
== Rationale for changes
{project_name} has several limitations; for example, downtime is needed for upgrading a {project_name} cluster.
To address the limitations, an in-depth refactor has been initiated.
The changes in this version are mostly attached to storage refactoring and a preparation of a new storage, called map storage. This storage will eventually replace the current storage, which will be called a _legacy store_ with this version.
The legacy store will still be available in {project_name} for several more versions.
The new store imposes a strict separation of responsibility between the service and storage layers.
For that reason, the service layer's visibility of an object's origin will be restricted, so it will not be able to discriminate between cached or non-cached objects, or objects originating from local or federated storage.
User storage SPI will become deprecated.
It will be supported for several more versions, but will be eventually replaced by the Map Storage SPI, which will offer the ability to create custom storages for any recognized area, such as users, roles, clients, or groups.
Extensions that rely on the level of detail available to services in the legacy store will need adjustment to retain this ability for the full deprecation period of the legacy store.
The following section describes how that adjustment is accomplished.
Using a legacy and map store is mutually exclusive; one store cannot be used while the other is active.
== Changes in the module structure
As part of introducing the new storage functionality, several public APIs around storage functionality in `KeycloakSession` have been consolidated, and some have been deprecated and will be removed in one of the next versions.
Three new modules have been introduced, and data-oriented code from `server-spi`, `server-spi-private`, and `services` modules have been moved there:
`org.keycloak:keycloak-model-legacy`::
Contains all public facing APIs from the legacy store, such as the User Storage API.
`org.keycloak:keycloak-model-legacy-private`::
Contains private implementations that relate to user storage management, such as storage `*Manager` classes.
`org.keycloak:keycloak-model-legacy-services`::
Contains all REST endpoints that directly operate on the legacy store, and have no meaning in the new store.
These modules will be available as long as legacy stores will be supported.
After that period, they will be removed.
== Changes in `KeycloakSession`
`KeycloakSession` has been simplified.
Several methods have been deprecated in `KeycloakSession` and will be removed in a future version.
`KeycloakSession` session contains several methods for obtaining a provider for a particular object type, such as for a `UserProvider` there are `users()`, `userLocalStorage()`, `userCache()`, `userStorageManager()`, and `userFederatedStorage()`.
This situaton may be confusing for the developer who has to understand the exact meaning of each method, and depends on current store layout.
The new store does not distinguish federated from local storage.
For those reasons, only the `users()` method will be kept in `KeycloakSession`, and should replace all other calls listed above.
The rest of the methods are deprecated, and will eventually be removed.
The same pattern of deprecation applies to methods of other object areas, such as `clients()` or `groups()`.
All methods ending in `++*StorageManager()++` and `++*LocalStorage++()` now throw an exception when being called, as there is no direct replacement in the new store.
The next section describes how to migrate those calls to the new API or use the legacy API while using the old store.
If the provider uses deprecated methods, but does not rely on local versus non-local storage, changing a call from the now deprecated `userLocalStorage()` to the method `users()` is the best option.
Be aware that the semantics change here as the new method involves a cache if that has been enabled in the local setup.
.Before migration: accessing a deprecated API that now throws an exception
.After migration: accessing the new API caller does not depend on the legacy storage API
[source,java,subs="+quotes"]
----
session**.users()**;
----
=== Migrating existing providers that depend on the legacy store
In the rare case when a custom provider needs to distinguish between the mode of a particular provider, access to the deprecated objects is provided by using the `LegacyStoreManagers` data store provider.
This option will be available only if the legacy modules are part of the deployment.
The methods `getClientStorageProviders`, `getClientStorageProvidersStream`, `getRoleStorageProviders` and `getRoleStorageProvidersStream` have been removed as well.
Code which depends on these methods and runs with the legacy storage enabled should cast the instance as follows:
.Before migration: code will not compile due to the changed API
[source,java,subs="+quotes"]
----
realm**.getClientStorageProvidersStream()**...;
----
.After migration: cast the instance to the legacy interface
Similarly, code that used to implement the interface `RealmModel` and wants to provide these methods should implement the new interface `LegacyRealmModel`. This interface is a sub-interface of `RealmModel` and includes the old methods:
.Before migration: code implements the old interface
[source,java,subs="+quotes"]
----
public class MyClass extends RealmModel {
/* might not compile due to @Override annotations for methods no longer present
in the interface RealmModel. */
/* ... */
}
----
.After migration: code implements the new interface
== Interface `UserCache` moved to the legacy module
As the caching status of objects will be trasparent to services, the interface `UserCache`
has been moved to the module `keycloak-legacy`.
Calls to `session.userCache()` will therefore return only a `UserProvider`, which is a breaking change.
Code that depends on the legacy implementation should access the `UserCache` directly.
While such calls might be necessary while caching with the legacy store is used, it will not be necessary when using the new map store, as that one handles caching transparently.
.Before migration: code will not compile due to a changed return type
[source,java,subs="+quotes"]
----
// session.userCache() might return null, null-check omitted for brevity.
session**.userCache()**.evict(realm, user);
----
.After migration: use the API directly
[source,java,subs="+quotes"]
----
// session.getProvider(UserCache.class) might return null, null-check omitted for brevity.
Credentials for users were previously managed using `session.userCredentialManager()._method_(realm, user, \...)`.
The new way is to leverage `user.credentialManager()._method_(\...)`.
This form gets the credential functionality closer to the API of users, and does not rely on prior knowledge of the user credential's location in regard to realm and storage.
The old APIs have been deprecated, and will only work when the legacy storage is enabled in the deployment.
The new APIs will work with both old and new storages.
= Deprecated `podDisruptionBudget` in the legacy {project_operator}
With this release, we have deprecated `podDisruptionBudget` field in the Keycloak CR of the https://github.com/keycloak/keycloak-operator[legacy {project_operator}].
This optional field will be ignored when the Operator is deployed on Kubernetes version 1.25 and higher.
As a workaround, you can manually create the Pod Disruption Budget in your cluster, for example:
```yaml
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
labels:
app: keycloak
name: keycloak
spec:
maxUnavailable: 1
selector:
matchLabels:
component: keycloak
```
See also the https://kubernetes.io/docs/tasks/run-application/configure-pdb/[Kubernetes Documentation].
