110 - Adopt plugin versioning scheme

[robobario]

This is a smaller idea for adopting plugin versioning without tackling all of the other ideas like contract-first Configuration based on JSON schemas, kubernetes sympathy by decomposing into multiple configuration files which are covered in #96 . It only makes versioning explicit and adopts k8s CRD versioning conventions to try and make our stability guarantees explicit.

Proposal generated with the help of Claude Sonnet 4.5

[robobario]

Prototype implementation kroxylicious/kroxylicious#3952

[robobario]

needs a bullet to say that the annotation on the plugin becomes mandatory too

[tombentley]

Thanks @robobario. I really appreciate that someone is trying to see if there's a simpler alternative to #96 which might satisfy some of the things we agreed in #82 are important to have for Kroxylicious 1.0.

I'll admit that 96 doesn't do a great job of calling out all of its goals, but let me try to compare the two:

Goal	#96	#100
Explicit plugin config version	Yes	Yes
Support config schema evolution	Yes	Yes
Plugin identification	Yes	No
Deeper runtime understanding of nested plugins	Yes	No
Fine grained dependency analysys	Yes	No
Better documentation of schema configs	Yes	No
External validation of schema configs	Yes	No
Editor support for writing configs	Yes	No
Globally shared interpretation of proxy config	Yes	No
Synergy with K8S	Stronger	Weaker

It's clear that there's a very different level of ambition between the two proposals. My fear is that, out of a desire to see 1.0 happen sooner, we make decisions which undermine our ability to address some of the concerns in the left hand column.

I asked Claude to look had how compatible there two proposals are and this is the result. Reading that I think it's difficult to see 110 as an outright good move that's compatible with the ideas in 96 as a solution of those goals. Instead while there are those structural differences between the two (like the annotation, the YAML syntax and the difference in terms of simple vs FQCNs) 110 looks more like a temporary thing which would cause disruption to plugin developers.

So I think it would be helpful to hear if you think any of those goals are not actually worth striving for. If they are worth solving then I'd appreciate your review on 96: is it a good way of solving them (maybe there are better ways)? In the light of that we can figure out if 110 is the best way of doing something that's "good enough for 1.0", or if we can tweak 110 to be more compatible with 96.

I also think it's worth considering that kroxylicious/kroxylicious#3691, which is a POC of the changes proposed in 96, is "only" a +7k change. Sure that's a lot, and it needs work on the tests and so on, so would likely grow a bit. But in the light of some of the recent big things we've merged, I don't think we should immediately be thinking that 96 is a huge piece of work that would take many months to implement.

[tombentley]

if we can tweak 110 to be more compatible with 96.

I asked Claude about this and it's the second file in the gist

[robobario]

I've incorporated the feedback so that this is aligned with #96, so a step 1 that introduces explicit plugin versioning using the annotation modifications from 96 and allows for multiple configuration versions to co-exist using instanceof dispatch.

I see this as a pre-step for 96, as mentioned this is far less ambitious but hits the key requirement for me for 1.0.0 which is making our (and third party) Plugin stability guarantees visible. Accepting this wouldn't prevent us from also accepting more of 96 or other configuration changes before 1.0.0 (though I accept it would be messier to have a new design come in and make part of another design redundant).