From: "Daniel Kral" <d.kral@proxmox.com>
To: "Dominik Rusovac" <d.rusovac@proxmox.com>, <pve-devel@lists.proxmox.com>
Cc: Thomas Skinner <thomas@atskinner.net>
Subject: Re: [PATCH pve-manager v4 1/4] api: nodes: add endpoint to set maintenance mode
Date: Mon, 16 Nov 2026 12:57:48 +0100 [thread overview]
Message-ID: <DMWM8ABHVPEC.3FI2YL010T3ZI@proxmox.com> (raw)
In-Reply-To: <20261113152620.2662417-2-d.rusovac@proxmox.com>
This patch can probably be prefixed with 'fix #6144', because this also
allows API users in general to put nodes in maintenance mode rather than
requiring users to use the CLI as before.
No hard feelings though.
On Fri Nov 13, 2026 at 4:26 PM CET, Dominik Rusovac wrote:
> node maintenance mode can currently only be requested with the HA
> manager's CLI, which can't be used from the web UI
>
> add an endpoint to enable/disable maintenance mode for a node, which
> lives below the node path rather than the HA API, so that the
> maintenance concept can be extended to more than HA managed resources
> later on. for now, it queues the same CRM command as the HA manager's
> CLI command
>
> requests for nodes unknown to the HA manager are rejected. since
> maintenance is restricted to HA, maintenance mode has no effect on such
> nodes yet and the queued command would make an idle CRM become active
>
> requests to enable maintenance mode are rejected while HA is disarmed or
> if the respective node is not online from the CRM's point of view. the
> CRM ignores such requests and logs a message. disabling is still
> possible in any case as the CRM always processes such requests
>
> Originally-by: Thomas Skinner <thomas@atskinner.net>
> Signed-off-by: Dominik Rusovac <d.rusovac@proxmox.com>
> ---
>
> Notes:
> changes since v3:
> * reword commit subject and body
> * check Sys.Modify on /nodes/{node} instead of /, as suggested in
> the v2 review
> * reject requests for nodes unknown to the HA stack
> * reject enabling maintenance mode while HA is disarmed or if the
> node is not online from the CRM's point of view, as the CRM
> ignores such requests
>
> PVE/API2/Nodes.pm | 54 +++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 54 insertions(+)
>
> diff --git a/PVE/API2/Nodes.pm b/PVE/API2/Nodes.pm
> index 1e2a96f1..af4c92f6 100644
> --- a/PVE/API2/Nodes.pm
> +++ b/PVE/API2/Nodes.pm
> @@ -242,6 +242,7 @@ __PACKAGE__->register_method({
> { name => 'hosts' },
> { name => 'journal' },
> { name => 'lxc' },
> + { name => 'maintenance' },
> { name => 'migrateall' },
> { name => 'netstat' },
> { name => 'network' },
> @@ -2901,6 +2902,59 @@ __PACKAGE__->register_method({
> },
> });
>
> +__PACKAGE__->register_method({
> + name => 'maintenance_set',
> + protected => 1,
> + path => 'maintenance',
> + method => 'PUT',
> + description => "Enable or disable maintenance mode for the node. Currently, this only"
> + . " requests the HA node maintenance mode.",
> + permissions => {
> + check => ['perm', '/nodes/{node}', ['Sys.Modify']],
> + },
nit: This is not very strict, but usual order for this is:
- name
- path
- method
Then usually
- description
- protected
- permissions
as it seems
> + parameters => {
> + additionalProperties => 0,
> + properties => {
> + node => get_standard_option('pve-node'),
> + 'maintenance-mode' => {
> + description => "Requests enabling or disabling maintenance mode. Currently,"
> + . " this only moves HA managed resources away from the node.",
The description here should rather describe what this property does
change about how the API method operates, e.g.
"Specifies whether the maintenancen mode for the specified node
should be enabled or disabled."
> + type => 'string',
> + enum => ['enable', 'disable'],
> + },
> + },
> + },
> + returns => { type => 'null' },
> + code => sub {
> + my ($param) = @_;
> +
> + my $node = $param->{node};
> + PVE::Cluster::check_node_exists($node);
> +
> + my $manager_status = PVE::HA::Config::read_manager_status();
> +
> + # maintenance mode currently only affects HA managed resources, and queuing the CRM
> + # command for a node unknown to HA would make an idle CRM become active for nothing
> + my $node_state = $manager_status->{node_status}->{$node};
> + die "node '$node' is not part of HA - nothing to put into maintenance\n"
> + if !defined($node_state);
> +
> + my $enable = $param->{'maintenance-mode'} eq 'enable';
> +
> + # the CRM ignores requests to enable maintenance mode while HA is disarmed or for nodes
> + # that are not online
> + die "cannot enable maintenance mode for node '$node' while HA is disarmed\n"
> + if $enable && $manager_status->{disarm};
> + die "cannot enable maintenance mode for node '$node' in HA node state '$node_state'\n"
> + if $enable && $node_state ne 'online';
> +
> + my $cmd = $enable ? 'enable-node-maintenance' : 'disable-node-maintenance';
> + PVE::HA::Config::queue_crm_commands("$cmd $node");
Since we queue the CRM command here, I think it would be a tad nicer to
have the validation logic in the 'node-maintenance-set' CLI handler in
PVE::CLI::ha_manager.
Then, users who still prefer the CLI variant also get feedback there if
the maintenance node can be set or not in advance and not just the HA
Manager's syslog.
Furthermore, there's less dependency on the manager_status structure
from external packages (i.e., not pve-ha-manager Perl modules).
At last, we could probably factor out the reasons when node maintenance
cannot be set from PVE::HA::Manager::update_crm_commands()'s
enable-node-maintenance and disable-node-maintenance branches, which
would share this logic nicer if any changes are done in the future to
this.
A PVE::Tools::run_command() would be enough here AFAICT, because if it
fails then we just fail here as well and forward the error message.
> +
> + return undef;
> + },
> +});
> +
> # bash completion helper
>
> sub complete_templet_repo {
next prev parent reply other threads:[~2026-11-16 11:57 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-13 15:26 [PATCH-SERIES docs/ha-manager/manager v4 0/4] fix #6144: add api and ui for node maintenance mode Dominik Rusovac
2026-11-13 15:26 ` [PATCH pve-manager v4 1/4] api: nodes: add endpoint to set " Dominik Rusovac
2026-11-16 11:57 ` Daniel Kral [this message]
2026-11-17 8:58 ` Dominik Rusovac
2026-11-17 9:21 ` Daniel Kral
2026-11-17 9:40 ` Dominik Rusovac
2026-11-13 15:26 ` [PATCH pve-manager v4 2/4] fix #6144: ui: ha: status: allow toggling " Dominik Rusovac
2026-11-17 9:07 ` Daniel Kral
2026-11-17 11:02 ` Dominik Rusovac
2026-11-13 15:26 ` [PATCH pve-ha-manager v4 3/4] api: status: report node maintenance request for lrm entries Dominik Rusovac
2026-11-16 12:02 ` Daniel Kral
2026-11-13 15:26 ` [PATCH pve-docs v4 4/4] ha-manager: maintenance mode: mention web ui menu Dominik Rusovac
2026-11-19 10:05 ` [PATCH-SERIES docs/ha-manager/manager v4 0/4] fix #6144: add api and ui for node maintenance mode Dominik Rusovac
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=DMWM8ABHVPEC.3FI2YL010T3ZI@proxmox.com \
--to=d.kral@proxmox.com \
--cc=d.rusovac@proxmox.com \
--cc=pve-devel@lists.proxmox.com \
--cc=thomas@atskinner.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox