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

[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.

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.

> (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.

> 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