[pve-devel] [RFC v1 pve-storage 0/6] RFC: Tighter API Control for Storage Plugins

[Fiona Ebner]

Am 07.02.25 um 12:57 schrieb Thomas Lamprecht:
> Am 07.02.25 um 10:59 schrieb Fiona Ebner:
>> I just thought that in the context of a major release, many plugins will
>> need to adapt to the new underlying Debian environment and thus provide
> 
> Not sure how much one needs to adapt here, our plugins IIRC never
> required any adaption just due to doing a major Debian upgrade, being
> written in a quite long-term stable interpreted language as perl after all,
> as most external plugins are too.

True for the Perl part of the plugins. I was thinking about CLI
tools/binaries/libraries that are used by the plugins.

> Both external plugin examples linked in [0] actually just return the
> $apiversion defined by pve-storage (if smaller than some max version
> though), which is quite definitively to avoid annoying warnings as those
> plugins can be used for more than one major release at the same time.
> While these might not even be affected by the reset, it's IMO another
> sign that the current mechanism is not ideal and a reset might be even
> more dangerous in practice (sure, plugin authors fault to do some
> questionable things, but I cannot really blame them tbh).
> 
>> new versions in any case. Doing breaking changes outside of a major
>> release bears bigger risk that users might miss new plugin versions
> 
> I nowhere proposed doing such breaking changes outside of a major
> release, just that they should not reset AGE to zero as we did last
> time.

Sorry, I didn't mean to imply you did. I was still thinking about
Wolfgang's "soon" from

> I don't think accidentally-public private helpers should be considered
> part of the API. We can just deprecate them immediately, remove them
> "soon". They aren't part of the `PVE::Storage`<->`Plugin` surface after
> all.

although that also doesn't explicitly say "outside of a major release"
of course ;)

> 
>> (e.g. installed the plugin once without configuring/checking for updates
>> later). With "full major release" which of the following do you mean:
>> 1. deprecated in PVE N.x, dropped in PVE (N+1).x for the same x
>> 2. deprecated in PVE N.x, still supported throughout PVE (N+1), dropped
>> with PVE (N+2).0
> 
> 3. no explicit "future" deprecation period, but on a new major version
> reduce the API age such (or some other operation resulting in basically
> the same thing, depending on what versioning we then use) that all API
> versions that happened before PVE ($N - 1) become unsupported and any
> compat code can be dropped. Then we can add a check to the pve($N-1)to$N
> checker script that tests if any installed storage plugin would become
> unsupported.
> 
> This would be a relatively simple deprecation process modification and
> can be adapted quite quickly before cutting any new major release, if
> really needed that is. By default, it would avoid churn from unconditional
> upfront deprecation, as one can decide for each major release if it's
> actually worth it.
> 
> btw. Printing some notice for plugin with outdated version in the XtoY
> checker scripts might be a good idea in any way, that's not as intrusive
> as warning on every module load and makes it more likely that users check
> if their plugin got a new release they might want to update.

Totally fine by me, as is everything below :)

>> We also lose a little flexibility about how we can do breaking changes:
>> e.g. changing parameter order would require adding a new method,
>> changing the existing one to be a wrapper and then dropping the wrapper
>> at some point - not so bad I guess, but forces us to come up with new
>> names for those methods.
> 
> 
> Yeah sure, albeit I really have a hard time in seeing the (slight) loss
> in flexibility as actual problem, causing churn for all plugin users and
> devs certainly is one though.
> And as said, when this actually becomes a problem and maintenance burden
> we can come up with solutions, if the pain is big enough and a lot of stuff
> accumulated we can also to a (partial) AGE reset, having some more cruft
> added during that major release cycle is not really a problem that we
> can avoid either way.
> 
> And I know it was an example, but just reordering parameters certainly
> does not qualify for that. And if the old name really was perfect then
> there's always the good ol'reliable addition of a 2, or N+1, at the end
> of the name, that's honest and telling as it directly conveys that there
> is/was an N-1 method.
> 
>> But I can see your point why a full APIAGE reset is bad and not doing
>> any is fine by me. The opt-in env-var or similar for deprecation
>> warnings seems like a good approach IMHO. Just need to communicate this
>> properly to plugin authors if we add it. The deadline for a breaking
>> change could then also be included in the warning message.
> 
> The wiki [0] should for now become the central place for docs, I made
> the initial draft in a 
> 
> [0]: https://pve.proxmox.com/wiki/Storage_Plugin_Development