Repository navigation
Conversation
Signed-off-by: Steve Hawkins <shawkins@redhat.com>
|
Based upon our discussion a better term to use may be "effective default", rather than default. We're referring to a class of fields that have a logical default in a keycloak version, but we also want some kind of auto-migration behavior. That is if left unset when initially created / later manipulated, then in some later version of keycloak the value / behavior may change automatically when the logical default changes. Honestly this seems contrary to the point of versioning with a declarative representation / defaults. That is if I specify a particular instanciation of client vN that has a given set of defaults - it should remain in perpetuity effectively a vN client until some action is taken to migrate it to a later representation. No matter what version of keycloak I'm on (with potentially a different storage version), as long a clients of vN are supported, I should expect exactly the same behavior / defaults for that client. When using a different serving version and fetch it as a vN+1 client, it should still exhibit, as much as possible, its vN nature. To support auto-migration from a declarative perspective could mean differentiating between whether you want the "default" or the "effective default" - which could relate somewhat to the templating discussion above if this were done through an expression. Otherwise it's not clear to me if I leave a field omitted or null [*] which behavior I should get. Alternatively this class of "effective defaults" should not be declaratively described as defaults in the object model / openapi - and potentaily even treated as runtime state. [*] kube tries to discourage the idea of an explicit null as a value, which using NON_ABSENT / NON_NULL for jackson serialization effectively enforces. |
|
What I miss from this analysis is that Kubernetes enforces the API to be isomorphic. In other words, v2 can always be converted to v1 and vice-versa. Kubernetes delivers a false promise that you can even remove old, deprecated fields from your API but you can't. You can only clean the REST payloads but all deprecated fields will always need to stay in the API as optionals for v2 -> v1 conversion. Looking at Keycloak, we have exactly the same analogy. We need to provide a conversion path from In my opinion there are two very significant aspects that will greatly influence the implementation. Can we foresee the v3 of the Client Representation and how this should look like? If we assume full isomorphism, we can assume we'll always be transitioning through ClientModel, in other words v3 -> Client Model (v1) -> v2. This assumption greatly simplifies the code and makes Client Representations totally independent from each other (v3 can look drastically different than v2). The other aspect is how to tie defaults to it. If we assume isomorphism, probably the only way is to tie the defaults with a particular implementation. In other words, v3 will use its own mechanism for defaulting that can be independent of v2. |
|
I gave it some more thought. There are basically two problems we're facing here: resource/storage versioning, and API versioning. From my perspective, only the latter is in the scope of Admin API v2. That said, we still have the defaults problem that significantly touches the resource versioning. My suggestion would be the following as I'm feeling we might easily overengineer it.
WDYT? |
|
Followed up with @slaskawi on his comment off-line. I think he better understands what I was trying to communicate about what we are calling defaults.
It's fine to drop the idea of versioning beyond the admin api level, but I believe we are still going to need to track the serving version.
Are you saying that users can't expect stable behavior across keycloak versions unless they fill in all values (including defaults) for themselves and those choices do not get pruned?
From my perspective this is mixing two contructs - declarative configuration and migration. You are trying to create a situation where migration will seemingly happen automatically. But is that actually "the same client"? If I am on KC 26.2 and have "declaratively" configured a client, why should the behavior / defaults of that client change if I upgrade to KC 27? Shouldn't it remain function identically, or as closely as possible, as to the one created in KC 26.2? Without this consistency won't tooling be dependent upon interogating the keycloak version, and also make it harder for users to reason about upgrades?
The only way this makes sense is if it follows something from the previous comment - that is what we are calling defaults are not actually "simple" defaults. |
|
After discussions with @vmuzikar and @slaskawi I think we may be reaching some concensus over how to categorize what has been called defaults and what exactly a user is declaring via configuration. As long as we're consistent with what could be a simple/complex default, and what could be runtime state (even if derived from effective defaults), things will be clearer to discuss. I would categorize what @vmuzikar is describing as more akin to a declarative template, not versioned declarative configuration a la Kuberentes, Wildfly, and many other systems. The user story seems to roughly be to define a mostly unversioned [*] Client template such that any configuration not explicitly set may vary for any number of reasons - Keycloak version, feature enablement, and CVEs. [*] the only versioning notion is at a coarse level - AdminApi v2. There are no expected revisions, such as v2.1, nor resource level versioning. It's not clear whether even the origination under AdminApi vX would be tracked via the representation. If that is a correct charactiziation, the downsides/caveats to the template approach seem to be:
|
|
Before going further into discussing potential final solutions, I wanted to summarize the two proposed approaches. @shawkins Let me know if I understood Option 1 properly. :) Option 1: Resource versioningWe would introduce a new concept of resource versioning. A versioned resource would define not only the resource's interface (the representation) but more importantly also its behaviour incl. the default values. It would be basically a "model version", Keycloak internals would need to be able to work with different versions of given resource. A resource version would be also reflected by the API version. Each resource would be managed by a different group of endpoints which would have a corresponding version of the API. I.e. we would not make breaking changes to the API unless we introduced a new resource (and API) version. However, resource version is not affecting only the user facing contract, it's the model layer too. It also defines how Keycloak works with that resource. ExampleLet's have a Client v1. A user will decide to create a Client v1 in Keycloak 26.2. The Client has a well defined behaviour and also some defaults for fields that the user didn't specify. In Keycloak 26.4, Client v2 was introduced which changes some default values of the Client, adds some fields, removes some. It is a breaking change. However, thanks to resource versioning, any Clients that are v1 are unaffected, e.g. the defaults remain unchanged. Users can even still create Clients v1 even in 26.4. Next, Keycloak 27.0 is released and Client v1 is finally removed. Users only then need to perform some migration to v2 (if not performed for them automatically). ConsiderationsPros
Cons
Option 2: API versioningWe would version only the API which would be decoupled from the Resource/model version. Resources/model layer would not be versioned beyond Keycloak version. The API would be just a view and management layer above the model, i.e. the very same resource could be accessed by all supported API versions. Additionally, default values would not be persisted and would not be tied to an API version but rather to Keycloak version. With a Keycloak upgrade, defaults might change as well, that includes existing resources. Similarly to Option 1, we would not version the API as a whole but rather logical endpoints "groups", e.g. Client API v2. For more details, see #39547 (comment). Example 1In Keycloak 26.4, the user created a Client via Client API v2. Some fields that were not specified had default values assigned. At the same time the user can access the very same Client via Client API v1. Since the model is the same, some runtime mapping might be in place to translate between the actual Client model and API v1 and v2 which might have e.g. different fields in the representations. Then, Keycloak 27.0 is released and it changed some of the Client defaults. However, since the defaults are resolved at runtime, they changed for the existing Client (created in Keycloak 26.4) too. Example 2The user has some Client representation stored in Git and manages Keycloak in GitOps style. They are first using Keycloak 26.4 but then upgrade to 27.0 which introduced some changes to defaults as in the previous example. Thanks to the defaults not being persisted, the defaults are updated for the managed Client with the upgrade to 27.0. (If the defaults were persisted, the user would have a discrepancy in the resulting Client based on whether it existed prior to 27.0, or not. That would break idempotency principle required for declarative style configuration like GitOps.) ConsiderationsPros
Cons
While I do believe Option 1 is conceptually more correct, my main concern would be the implementation. Hence Option 2 seems more viable to me. The biggest issue is the defaults. But possibly we might be able to find some solution in wording it properly. |
Yes, I think it matches. I'll add some more comments here.
It might not be as relevant nor directly comparable, but I believe Wildfly functions similarly with explicit configuration schema, such that the structure, defaults, etc. remain consistent - https://github.com/wildfly/wildfly-core/tree/main/server/src/main/resources/schema
These don't necessarily have to be seen as in conflict - unless the only way a feature can affect the model is to change what is stored.
I don't completely follow why. There is a single storage model, and each serving version already maintains a bidirectional mapping storage model.
Can you incorporate more of the cons from #39547 (comment) into your post? I want to comment more on this:
This isn't specific to Keycloak representations. Kubernetes takes a lax approach to fully separating configuration and runtime state - spec fields are changed in what is stored / returned to the user. We do this in the operator for several effective defaults (replicas and hostname on openshfit). Kube can do this for defaults (which is mostly benign) but also to track the affects of things like LimitRange - this means that what you get back from a PUT, POST, event, etc. may contain truly runtime information in the spec that you did not directly specify. Since that is persisted, if you later change the LimitRange defaults for example, your Pods won't automatically pick that up. This isn't necessarily a bad thing. Kube users are generally NOT supposed to directly use what is returned by the api server to overwrite / replace their managed copy of the resource (especially for resources like Pods), nor use that as the basis for additional manipluation. Instead you are to think in terms of asserting your desired state and let apply / server-side-apply (runtime / default fields should be un-owned) determine if anything needs to actually be done. The Keycloak API Versioning proposal is doing something akin to the kubectl apply last applied tracking, but to make that a formal part of the api when getting the non-full representation. This relates to mutability in general: Allowing multiple actors to modify the same resource (not even considering modifications from different admin api versions) is difficult to reason over. From the perspective of maintaing a desired state having just tracking the last applied is insufficient - which is why server-side-apply was developed. Can you clarify which of these most closely matches our goal for mutability:
Or are there other paradigms that would better describe it? |
Yes, that's why I say "partially". :) Obviously these two can technically co-exist, my point was just we'd basically have two "feature versioning" concepts.
At the very least, there'd be the defaults problem. If v1 has some defaults, and v2 changed those, how would that work? I can see two possible approaches here.
To me, the first approach seem better but not ideal.
As far as I understood, there were the following concerns:
But it doesn't necessarily mean it's ideal approach either, IMHO. :) It's actually one of the usability issues I see – from just fetching the resource it's unclear to the user what is actually user specified (the "desired state") and what fell back to defaults.
Yes, that is my current thinking now. That said, I see that as an additional layer, it's more authz related than API related, and we'll leverage FGAP for it. And it will be specific to the Operator (and potentially other GitOps-like consumers). I see that as a different discussion from defaults and versioning.
Potentially yes, but we need to discuss that further.
I'm not sure I fully follow. @shawkins Could you please provide perhaps some example? Thinking about it further, maybe we could find some middle ground:
@shawkins How does that sound to you? |
The first approach seems the most consistent / workable and follows the reasoning used by Kubernetes.
My next comment followed up on that - it's not a fair critism in isolation about having both "template" Client represenation and the "full representation", but I try to tie that into mutablity across actors or adminapi versions.
Yes it should be, or at least it needs more specificity. If not then there doesn't seem to be clear expectations on how to maintain consistent configuration based behavior across upgrades, or exactly how feature flag changes affect things (immediately affect all resources, affect only newly created resources, have storage level side effects, etc.).
Again it's something that doesn't seem clear. We're making it a goal to maintain the template representation and are touting the benefits of the automatic management that is then happening, so we'll also have to document when / why you'd want to use these full representations to pin behavior. The usability isn't clear - do you have to first create the entity, then GET the full representation, then save that as your managed copy and PUT it back into the server to assert the defaults are set? Or will there be some kind of short-cut for this - a POST with a "fill out full representation option", or would users be responsible for interogating the metadata facilities for defaults / runtime settings and filling out the full representation on their own before they POST? Or are you thinking that this is more applicable to migration scenarios?
It's related in that if we allow mutability to the "template" and expect the external actors (the operator) to assert their desired state, then they should be able to effeciently detect when to do that. If there is no mutability, then this problem largely goes away.
Using @slaskawi 's PR as a mental model, let's suppose I create a Client with adminapi v2.
|
|
@shawkins Thank you for your reply. Before going further, I'd be interested in your thoughts on the "middle ground" proposal – see the end of my previous comment. :) I believe it would solve most of the concerns. As I'm contemplating the idea, I feel it might be the best path to take in the end. |
Sorry, I had started this response as something separate, I should have mentioned that in the other comment.
Can you elaborate more - are you saying that the model logic will be expanded to track what fields have been explicitly set? Thus a model "template" concept becomes a first-class citizen along side the working state / "full representation".
It might be good to break down the migration scenarios:
More generally doesn't this boil down to how are we facilitating migration for users who externally manage their keycloak representations vs those managed via the admin console (or other ad hoc tooling). For those that are externally managing, for example via gitops, won't they will start with v2 and have v1 (pending the mutablity discussion) be a legacy concern. Using Kuberenetes as a reference with externally managed resources - the migration of apiVersion can be as simple as just changing that field in your resources and doing a PUT - only if there are new required missing fields, validation is enabled and you are trying send removed fields, etc. is there additional migration effort. In any case that is all done externally, there is no expectation that Kubernetes platform will provide you with what the migration automatically. So does all the thinking around the need for default tracking mostly come down to providing a "better" migration story than just using the full representation for those who are using the admin console / ad hoc tooling to manage their Keycloak instance? |
|
@shawkins Your last comment got me thinking and I realized I confused even myself. :D I take back what I said about tracking defaults, we do not need that. Sorry about the confusion. My main reasoning was that v2 PUT should update any v1 defaults, but it'll do it regardless. With PUT the whole representation is replaced, which implicitly includes default – no tracking needed. Similarly, any fields removed via v2 PATCH will use v2 defaults. The only inconsistency is with GET – if you use v2 API to fetch a resource that was previously created or updated via v1, you'll get v1 defaults, and vice versa. But we can live with that. The only other bigger caveat would be the Admin Console – it would effectively treat any defaults as user specified, as it is doing now. But that should be ok, it's not a declarative-like config. So are we reaching a consensus here? :)
|
No problem. It's a confusing topic because so much has been discussed. Thank you for working through all this with me.
👍
Great, that clarifies we're not trying to somehow make the server treat it as such.
I think so - and hopefully saving ourselves a fair amount of work.
I think we can live with that. This is implicitly following the pragmatic approach with CRDs, which is to avoid multiple api versions at all costs. Kubernetes does provide differring openapi specs (1.30 vs 1.31, etc.) based upon the release version for the same core apiVersion - we'd likely do something similar. We'll basically ensure:
Does that seem correct?
Just want to highlight more explicltly how this would work with patching. What I would like is for patching to function as a straight-forward composite operation. On a patch the server logically performs a GET, applies the PATCH, then PUTs the result. If we create a v1 Client, then submit a patch against v2, that will first get the Client as if it were a v2, apply the patch, then go through the normal pipeline of a PUT (defaulting as if v2, validation, canonicalization). Given that v1 defaults have been persisted, you can end up with some kind of hybrid of v1 and v2 state - but I'm fine with that as that seems to be the closest semantic match to what the users is doing via a PATCH. If they want the full replacement with v2 defaults, they either have to expliclty unset the affected fields in the patch (as you mention above), or use a PUT instead. |
Thank you for challenging my confused ideas. :D
I think so. I'd just like to add explicitly that syntactical breaking changes would be done solely through introducing a new (sub-)API version (e.g. Client API v2). We'd also put some guardrails around when a new API version becomes the default and when the old one is removed – this is effectively a breaking change, so that would have to be done in Keycloak major releases. Semantical/behavioural changes would be on the other hand driven by Feature Flags.
Yes, that was my thinking as well and I'm fine with that. |
We may be saying the same thing, but I'd differentiate between the logical api version and the spec version. Borrowing from the kubernetes example again. There is a core v1 openapi spec (for things like pods) for Kube 1.30. There is a different one for Kube 1.31, etc. They all represent the same logical api version, which is core v1. The contract is that everything that you can do in core v1 1.30 spec which is not deprecated (and most deprecated things stay that way for several releases), you can do using the core v1 1.31 spec. Of course anything newly added in 1.31 spec cannot be used on a 1.30 or earlier platform - with validation enabled you would see this as an upfront error. So it may not be for every major Keycloak version, but we could have something similar where we release a new openapi spec that logically represents a non-breaking revision over the last N spec releases. Or are you saying that you don't want to try to maintain logical api version compatibility, and instead will introduce multiple / incompatible schema that will be supported simultaneously? Beyond of course the split we'll already have with admin api v1 and v2. |
|
@shawkins I think it sounds good but I'd maybe would not do the differentiation between API version and spec version – IMHO spec/representation is part of the API. Based on what you said, I'd propose the following workflow leveraging at most one stable and one preview API version at a time.
|
So basically yes, that is my proposal. :) To have at most two incompatible API versions at a time. |
Ok, we can refine that as the goal with the understanding that we'll avoid breaking changes in favor of schema evolution as much as possible. Wanted to comment more on tracking the api version on the resource - this doesn't introduce wholely different behavior than what we are discussing here. In fact it could just be contruct of the api layer and not stored. In Kuberentes the api version on the resource is used to:
So having the api version on ghe resource gives us a path to having "default" / smart behavior via tooling. That is if you do ./kcadm.sh create clientv2.json - the tooling would parse the client to determine the api version, or if not set use the default, so that the user does not have to specifiy it on the command line. |
|
@shawkins Including the "spec version" in the representation itself certainly makes sense from the API clients perspective. However, from the API itself it feels to me like an additional clutter – basically both the URL path and the payload would need to contain the version, if I understood correctly. |
I wouldn't call it clutter necessarily - it's all about what you want to support.
You also don't have to make it a required field - if left unspecified depending on the context it will be an error, or default to latest supported version. |
This use case certainly makes sense to me.
That would imply we'd have two distinct versioning schemas: the API version (defined by the URL path) and the spec version defined in a representation field. I'd rather go for a more simpler and IMHO clear single versioning scheme. We version just the API which also includes the spec. We include the version in the URL path and might include it in the representation as well.
Based on the discussion above, I would not consider the concept of "effective defaults" any more. |
|
@shawkins Just wanted to revisit the "defaults tracking" concept as I realized we might need to consider it in the end. The reason I a bit forgot about is the ability to fetch a resource without the defaults, i.e. do an HTTP GET just with the fields that the user explicitly provided. Another alternative IIRC was to store the user provided representation alongside of the "full representation" with the persisted defaults. Neither is ideal and implies quite a lot of additional logic, though just tracking a list of fields that have the defaults feels a bit more robust to me than having to maintain "two sources of truth" in sync. Now, the question is whether we really need to be able to fetch a resource without the defaults. The use cases I have in mind are basically two:
How real is the problem also boils down to how often/how many defaults we plan to persist. If we want to have robust design for the API, I do believe we'd rather be on the "persist as much defaults as possible" side of the spectrum rather than "let's leave most of the fields set to null and leave the interpretation on various Keycloak logics". So to summarize, I'm afraid we might need the defaults tracking in the end. That said, the additional complexity is probably not worth the benefits. I'll capture it in some final design overview of the defaults as a known caveats and we'll also see the feedback on it. |
As we discussed above this does not work unless you try to move the "template" logic into the model layer itself.
How do either of these work with existing v1 entries?
See the discussion above about mutabilty - if you are allowing for mutabilty and expect actors to effectively engage in a reconciliation loop, then yes there ideally would be a way to efficiently determine when to assert your state. However in a multi-actor scenario just tracking just a single notion of the last applied / template state will be difficult to reason over. I believe this would lead us more towards something like server side apply where field ownership is tracked as well. The questions here are:
Why is this a problem? This is a common user experience with databases or Kubernetes and it is generally understood as how they function. The question is what are you using the returned resource for? In the previous comment I was trying to say that Kuberentes users should not be using the result of a GET (or mutative operation) to overwrite their managed version of a resource or even as the direct basis for additional changes - for example simply modifying a field on it and PUTting it again. For one thing that defeats the purpose of SSA tracking as you become the owner of all fields. For another there's a lot of additional state - server generated fields in the metadata, status, etc. which are simply thrown away. You may also not be appropriately reasoning over locking / resource version - do you want to apply your change only based upon this revision (if so inheritting the resource version is the correct thing to do) or do you want to generally assert your change (in which case you need to clear the resource version field). |
@shawkins has a good point here. If we wanted to introduce aliases in the API paths, so for example the
@shawkins The most common use case is a reconciliation loop that manages this resource - for example an Operator. We need to provide a way for the Operator can ensure that its internal state matches the reality. Kube employs "generation" and "observedGeneration" fields for it. There are also examples of a full payload comparison, such as the MongoDB Atlas Operator. In general, I prefer more the "generation" approach but this needs proper documentation and proper support in Keycloak Terraform Provider as well as the Operator. |
They wouldn't. Any v1 defaults would be considered user specified. We might consider adding support for the defaults tracking retrospectively to the v1.
I'd say no. If we allow for declaratively managed resources to be managed by multiple actors, we'd probably end up with something over engineered like SSA.
This IMHO doesn't mean it's correct and the best possible experience. :) The only question is if the complexity to solve that is worth the benefits it brings. |
Possibly some declarative config automation for checking the current actual state, if for whatever reason it doesn't want to update it via PUT. |
@slaskawi two things:
Correct, I'm not convinced it's worth the complexity on the server side. Using a database / sql as an example - if you do an INSERT into ... , followed by SELECT * - you will rightly see all the defaults. If you instead do a SELECT - you will see just what you explicitly inserted. In this paradigm, it's on the caller to project only what is meaningful to them. I'd rather start by making this a client-side problem, rather than try to implement nuanced and potentially complex handling on the server side. |
Yes, I'm also not really convinced it's worth the complexity. And projection/fields filtering would certainly be a solution. |
@shawkins From the v2 Admin API perspective - no, we're not. But the client application might be implemented as such a system. Think of a fundamental assumption of a controller patter - if the system doesn't match the desired state, a reconciliation action is triggered. So an eventual consistent system is the actual client of the API and there needs to be something to enable it compare the state. It have to be either some clever mechanism (like generations) or there needs to be a way to return a previously submitted object from the API and compare it against the desired state.
@shawkins The design can't assume a single actor. Imagine a Client is being created by an Operator using the API and then a Keycloak Admin modifies it. From this perspective, the only legal action for the Operator is to try to override the changes that the administrator did. This is exactly the Controller Pattern I described the above. The Operator now needs to have something to detect what changed. |
Given that, the goal will be to not over engineer what is implemented on the server side. If clients wish to implement something that looks like multiple actors engaged in reconciliation loops over the server side state, then that is should be viewed as a client side problem to resolve.
Please the the exchanges with @vmuzikar on this topic. We will persue this as a design goal before entertaining more elaborate server side mechanics. |
|
So, just to summarize the discussion above (and also some offline ones), the current proposal is as follows.
|
I'm not sure about this based upon your past descriptions of when / why the effective defaults change. Are you specifically referring to "simple defaults" here?
I wouldn't support this if this applies to the effective defaults previously described as changable based upon the "Keycloak version, feature enablement, and CVEs" - otherwise it seems like we're introducing what could be seen as breaking changes in the contract far too often. At the very least we'd have to document that you must retrieve the open api spec from a running server to have an accurate reflection of the defaults, which may violate the principle of least surprise given taht we will have a published / static openapi spec at least per keycloak release correct? The other path to address this (at least the idea that defaults can change per version) under an otherwise structurally compatible schema is what I was getting at with #39547 (comment) - that is to sub-version the open api specs, and to specify that on your resources - that gives me an understandable contract wrt published defaults.
While some of these are immediately breaking, such as changing the semantic meaning of an existing field (which should obviously be avoided), as mentioned in #39547 (comment) some otherwise breaking changes can be approached by schema evolution. In these cases there would be a temporal motivation to treat them as breaking - that is we want to accelerate the removal of the old schema structure rather than letting it evolve out.
That is probably too short of a guarentee. |
Yes, I thought we do not consider anything else at the moment. :) That the "effective defaults" are off the table which makes sense to me.
As mentioned, I'm convinced we should not have "effective defaults".
You mean the proposal to support both fields at the same time while deprecating the old one, and then removing the old one after a few releases?
Yes it might be but that is my current understanding of the Features lifecycle. If that's not the case, we should probably align with whatever that is. I see an API versions just as another Feature basically. |
Great, we have a common understanding then. So before we mark anything as a default in the contract we'll ask ourselves - is there any reason why this would change anytime soon. And if the answer could be yes, then it's not a simple default.
Yes, or type widening, then narrowing to support a type change. |
Exactly.
I would not say a "simple default". Just it's not a default, period. We should not consider a default something we can't truly commit to (unless it's a preview field or something).
Well yes but it'd need to be done very carefully on case by case basis. It'd would technically break the contract for a given API version. |
|
Created the final proposal based on this discussion: #38551 (comment) |
Yes, that's make sense. Thank you. |
Added a rough in of ClientService method refinements. In an ideal world this would all be pretty similar across types, possibly even allow for some generic base interfaces / classes.
Jackson notes:
I'd advocate for using NON_ABSENT at a top level to allow for "empty" values such an empty string. However this has the side effect that any possibly fully empty child objects or collections will need to be specifically marked as NON_EMPTY (fabric8 does this).
The usage of required or NON_ABSENT makes using the object model for creating JSON Merge patches difficult - the lack of a value will cause an exception when deserializing, or empty lists / arrays won't be serialized, or you can't use explicit nulls - which prevents some patching behavior. If we don't think that the representation classes will be used for this purpose, then we can ignore this concern.
Defaults:
Re-reading #38551 there seems to be some intermixing of the ideas of what is a default and what is runtime state. If we are pursuing versioning, then these should be distinct concepts. That is for a given representation of a specific version, the same default values will always be the same. Changing the default values on a given version would likely be seen as a breaking change - although Kube does not prevent this. With this perspective I contend it doesn't matter if these then appear in the representations returned by Keycloak. The user is already maintaining their own representation with whatever defaults they want to be included - they don't have to overwrite that with what is returned by the server.
The other behaviors of always pruning defaults, or selectively trying to retain only those defaults that have been supplied in a PUT or POST have additional canonicalization (which we haven't addressed yet) or complexity (the v1 logic is setting defaults, so legacy exports / imports will introduce the defaults anyway) that don't seem to be needed.
With this in mind for "simple" defaults - those that can be specified in the OpenApi spec / json schema, I would propose using JsonProperty.defaultValue. We'll have to ensure:
We can further describe what is set by the server as either:
Complex defaults / implied state: these may not be expressable as a static default, but are fully determinant based upon the rest of the representatio 8000 n - with no possibility of interpolating values from a changing source, such as server variables. Is there anything under the ClientRepresentation that would fall under this category? Assuming the model logic computes these already, we may not have to do any special handling other than needing the description to elaborate on what the default will be. However I do see there could be some complexity relying on the model layer computation if there could be a mismatch between the serving version and the storage version.
or runtime state - which definitely should have separate handling. What is currently under the ClientRepresentation that would fall under this category?
The final thought would be around templating / expressions. We talked about this early on, but I'm not sure if it's still part of the conversation. Allowing for arbitrary expressions in what is sent to keycloak, similar to openshift templates, is difficult with a typed object model - that is if you have a boolean field and you want it to take the value of ${var} - you have to parse something that is a string instead. You end up needing to have special deserialization logic (we have that in fabric8) or you have to parse generically, resolve the values, then parse as the representation. To understand what is not a default, or needs to be re-evaluated when variables change, you would end up needing to track both the "template" and the instanciation (just like openshift templates).
@keycloak/cloud-native WDYT?