From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <pve-devel-bounces@lists.proxmox.com>
Received: from firstgate.proxmox.com (firstgate.proxmox.com [IPv6:2a01:7e0:0:424::9])
by lore.proxmox.com (Postfix) with ESMTPS id 0ED861FF16E
for <inbox@lore.proxmox.com>; Mon, 31 Mar 2025 17:13:20 +0200 (CEST)
Received: from firstgate.proxmox.com (localhost [127.0.0.1])
by firstgate.proxmox.com (Proxmox) with ESMTP id DC2EF9D85;
Mon, 31 Mar 2025 17:12:59 +0200 (CEST)
Date: Mon, 31 Mar 2025 17:12:51 +0200
From: Fabian =?iso-8859-1?q?Gr=FCnbichler?= <f.gruenbichler@proxmox.com>
To: Proxmox VE development discussion <pve-devel@lists.proxmox.com>
References: <20250326142059.261938-1-m.carrara@proxmox.com>
<20250326142059.261938-6-m.carrara@proxmox.com>
In-Reply-To: <20250326142059.261938-6-m.carrara@proxmox.com>
MIME-Version: 1.0
User-Agent: astroid/0.16.0 (https://github.com/astroidmail/astroid)
Message-Id: <1743430573.ujja600dom.astroid@yuna.none>
X-SPAM-LEVEL: Spam detection results: 0
AWL 0.042 Adjusted score from AWL reputation of From: address
BAYES_00 -1.9 Bayes spam probability is 0 to 1%
DMARC_MISSING 0.1 Missing DMARC policy
KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment
RCVD_IN_VALIDITY_CERTIFIED_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to
Validity was blocked. See
https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more
information.
RCVD_IN_VALIDITY_RPBL_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to
Validity was blocked. See
https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more
information.
RCVD_IN_VALIDITY_SAFE_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to
Validity was blocked. See
https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more
information.
SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record
SPF_PASS -0.001 SPF: sender matches SPF record
Subject: Re: [pve-devel] [PATCH v1 pve-storage 5/8] pluginbase: document
hooks
X-BeenThere: pve-devel@lists.proxmox.com
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Proxmox VE development discussion <pve-devel.lists.proxmox.com>
List-Unsubscribe: <https://lists.proxmox.com/cgi-bin/mailman/options/pve-devel>,
<mailto:pve-devel-request@lists.proxmox.com?subject=unsubscribe>
List-Archive: <http://lists.proxmox.com/pipermail/pve-devel/>
List-Post: <mailto:pve-devel@lists.proxmox.com>
List-Help: <mailto:pve-devel-request@lists.proxmox.com?subject=help>
List-Subscribe: <https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel>,
<mailto:pve-devel-request@lists.proxmox.com?subject=subscribe>
Reply-To: Proxmox VE development discussion <pve-devel@lists.proxmox.com>
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
Errors-To: pve-devel-bounces@lists.proxmox.com
Sender: "pve-devel" <pve-devel-bounces@lists.proxmox.com>
On March 26, 2025 3:20 pm, Max Carrara wrote:
> Add docstrings for the following methods:
> - on_add_hook
> - on_update_hook
> - on_delete_hook
>
> Signed-off-by: Max Carrara <m.carrara@proxmox.com>
> ---
> src/PVE/Storage/PluginBase.pm | 85 ++++++++++++++++++++++++++++++-----
> 1 file changed, 74 insertions(+), 11 deletions(-)
>
> diff --git a/src/PVE/Storage/PluginBase.pm b/src/PVE/Storage/PluginBase.pm
> index 8a61dc3..b3ce684 100644
> --- a/src/PVE/Storage/PluginBase.pm
> +++ b/src/PVE/Storage/PluginBase.pm
> @@ -626,29 +626,92 @@ sub find_free_diskname {
>
> =head2 HOOKS
>
> +The following methods are called whenever a storage associated with the given
> +plugin is added, updated, or deleted. These methods are useful for:
> +
> +=over
> +
> +=item * Setting up certain prerequisites when adding the storage (and then
> +tearing them down again when the storage is deleted)
> +
> +=item * Handling sensitive parameters that shouldn't be written directly
> +to C</etc/pve/storage.cfg> and ought to be stored elsewhere
> +
> +=item * Ensuring that certain conditions in the configuration are being upheld
> +that cannot be done via the remaining API otherwise
> +
> +=back
> +
> +and more.
> +
> +=cut
> +
> +=head3 $plugin->on_add_hook($storeid, \%scfg, %param)
> +
> +=head3 $plugin->on_add_hook(...)
> +
> +B<OPTIONAL:> May be implemented in a storage plugin.
> +
> +Called during the addition of a storage, before the new storage configuration
> +gets written.
see comments on first patch ;)
> +
> +C<%param> contains additional key-value arguments, usually sensitive keys that
> +have been extracted from C<\%scfg> in order not to write them to the storage
> +configuration.
> +
> +C<die>s in order to abort the addition if there are (grave) problems.
> +
> +C</etc/pve/storage.cfg> is B<locked> when this method is called.
This method is called while C</etc/pve/storage.cfg> is locked.
Although I am not sure what extra information this provides?
same applies to the rest below..
> +
> =cut
>
> -# called during addition of storage (before the new storage config got written)
> -# die to abort addition if there are (grave) problems
> -# NOTE: runs in a storage config *locked* context
> sub on_add_hook {
> my ($class, $storeid, $scfg, %param) = @_;
> return undef;
> }
>
> -# called during storage configuration update (before the updated storage config got written)
> -# die to abort the update if there are (grave) problems
> -# NOTE: runs in a storage config *locked* context
> +=head3 $plugin->on_update_hook($storeid, \%scfg, %param)
> +
> +=head3 $plugin->on_update_hook(...)
> +
> +B<OPTIONAL:> May be implemented in a storage plugin.
> +
> +Called during the update of a storage configuration, before the new
> +configuration gets written.
> +
> +C<%param> contains additional key-value arguments, usually sensitive keys that
> +have been extracted from C<\%scfg> in order not to write them to the storage
> +configuration.
> +
> +C<die>s in order to abort the config update if there are (grave) problems.
> +
> +C</etc/pve/storage.cfg> is B<locked> when this method is called.
> +
> +=cut
> +
> sub on_update_hook {
> my ($class, $storeid, $scfg, %param) = @_;
> return undef;
> }
>
> -# called during deletion of storage (before the new storage config got written)
> -# and if the activate check on addition fails, to cleanup all storage traces
> -# which on_add_hook may have created.
> -# die to abort deletion if there are (very grave) problems
> -# NOTE: runs in a storage config *locked* context
> +=head3 $plugin->on_delete_hook($storeid, \%scfg)
> +
> +=head3 $plugin->on_delete_hook(...)
> +
> +B<OPTIONAL:> May be implemented in a storage plugin.
> +
> +Called during the deletion of a storage, before the new storage configuration
> +gets written. Also gets called if the activation check during storage
> +addition fails in order to clean up all traces which
> +C<L<< on_add_hook()|/"$plugin->on_add_hook($storeid, \%scfg, %param)" >>>
> +may have created.
> +
> +C<die>s in order to abort the deletion of there are (very grave) problems.
> +
> +C</etc/pve/storage.cfg> is B<locked> when this method is called.
> +
> +=cut
> +
> sub on_delete_hook {
> my ($class, $storeid, $scfg) = @_;
> return undef;
> --
> 2.39.5
>
>
>
> _______________________________________________
> pve-devel mailing list
> pve-devel@lists.proxmox.com
> https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
>
>
>
_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel