From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [IPv6:2a0f:8001:1:32::40]) by lore.proxmox.com (Postfix) with ESMTPS id 9568F1FF0B6 for ; Thu, 12 Nov 2026 14:47:54 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 17E352166E; Thu, 12 Nov 2026 14:47:52 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=stuttgart.de; s=s1022; t=1794490937; bh=shKc1f2ArhpQgGGRzQkBRLgu+IRwfidU/+aG5Rm/h/M=; h=From:To:Cc:Subject:Date:From; b=j4I0dAsthiBxkbSonFuytMN1HKAdmWglK6N7GlEq3XcXcejMiqRGwfbob0WSK9RDW TUa8MDa7rpbc1rqhD8MU5u5sh9A2jEDw/mS1qDKo1wkGx1rwhlLrtnh9VyviuCDrSH FJ0oIAGWIQG+AUxETp0Q5zfBwIr9WrcP+Gjg1IzldhLyR/pa0v0MJ0Zmrc5kdVWXFt Dor5aJBbEBglQdf76DHi/kr/DtPgUl/cdM8zjSaia2qzd2Lr/cSXEdn/Ydk6zKVCJN TsXaU3VIbD8W21wazvJzngiPGwGbMybwLJlSzPnjzGmG5P3W+Hv8t7lNNjVYaMDyUD LE5jP9OwRhB2A== From: Jakob-Tobias Winter To: pve-devel@lists.proxmox.com Subject: [PATCH docs] fix #7482: pveum: document nested resource pools Date: Thu, 12 Nov 2026 14:40:41 +0100 Message-ID: <20261112134040.822659-3-tobias@stuttgart.de> X-Mailer: git-send-email 2.53.0 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: 0 AWL 0.030 Adjusted score from AWL reputation of From: address DKIM_SIGNED 0.1 Message has a DKIM or DK signature, not necessarily valid DKIM_VALID -0.1 Message has at least one valid DKIM or DK signature DKIM_VALID_AU -0.1 Message has a valid DKIM or DK signature from author's domain DKIM_VALID_EF -0.1 Message has a valid DKIM or DK signature from envelope-from domain DMARC_PASS -0.1 DMARC pass policy RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_PASS -0.001 SPF: HELO matches SPF record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: IXWO6PYKF6S6W5ZVQEA4OJ46VPWXPGLJ X-Message-ID-Hash: IXWO6PYKF6S6W5ZVQEA4OJ46VPWXPGLJ X-MailFrom: prvs=f560d3371a=tobias@stuttgart.de X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header CC: Jakob-Tobias Winter X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: Describe how pools are created and how members are managed, the naming rules, the limit of three levels, that the members of a nested pool are not members of its parent pools, and how permissions are inherited along the pool paths, including the delegation of creating nested pools. Also mention the nesting in the description of the pool view. Fixes: https://bugzilla.proxmox.com/show_bug.cgi?id=7482 Signed-off-by: Jakob-Tobias Winter --- pve-gui.adoc | 4 +++- pveum.adoc | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 52 insertions(+), 1 deletion(-) diff --git a/pve-gui.adoc b/pve-gui.adoc index 3a99eaf..689a982 100644 --- a/pve-gui.adoc +++ b/pve-gui.adoc @@ -177,7 +177,9 @@ Server View:: Shows all kinds of objects, grouped by nodes. Folder View:: Shows all kinds of objects, grouped by object type. -Pool View:: Show VMs and containers, grouped by pool. +Pool View:: Show VMs and containers, grouped by pool. Nested pools are shown +below their parent pool, unless 'Nest Pools' is disabled in the tree settings +(gear button next to the view selector). Tag View:: Show VMs and containers, grouped by tags. diff --git a/pveum.adoc b/pveum.adoc index 1413faf..d9a56d3 100644 --- a/pveum.adoc +++ b/pveum.adoc @@ -129,6 +129,39 @@ manage this on a per-resource basis. Resource pools are often used in tandem with groups, so that the members of a group have permissions on a set of machines and storage. +Pools are created under __Datacenter -> Permissions -> Pools__ or with +`pveum pool add`. Pool names can contain letters, digits, `-`, `_` and `.`, and +the name of a new pool must start with a letter. The members of a pool are +managed in its 'Members' panel or with `pveum pool modify`. A guest can only be +a member of one pool. Adding it to another pool moves it there, which requires +`--allow-move` on the command line. A storage can be a member of several pools. + +[[pveum_nested_pools]] +Nested Pools +~~~~~~~~~~~~ + +Pools can be nested up to three levels deep. The name of a nested pool consists +of the names of its parent pools and its own name, separated by slashes, for +example `dev/web/prod` for the pool `prod` below `dev/web`. The parent pool has +to exist before a pool can be created below it. In the GUI, select it as +'Parent Pool' when creating the new pool. On the command line, use the full +name: + +[source,bash] +---- + pveum pool add dev + pveum pool add dev/web + pveum pool add dev/web/prod +---- + +The members of a nested pool are not members of its parent pools. The member +list of a pool, backup jobs that select guests by pool, and the bulk actions of +a pool in the resource tree only include the direct members of the pool. A pool +can only be removed if it has neither members nor nested pools. + +Permissions on a pool are inherited by its nested pools, see +<> in the permission management section. + [[pveum_authentication_realms]] Authentication Realms --------------------- @@ -999,6 +1032,22 @@ Pools can be used to group a set of virtual machines and datastores. You can then simply set permissions on pools (`/pool/{poolid}`), which are inherited by all pool members. This is a great way to simplify access control. +The path of a <> lies below the paths of its +parent pools, for example `/pool/dev/web` below `/pool/dev`. Permissions on a +pool with the propagate flag set therefore also apply to its nested pools and +their members, following the inheritance rules above. For example, a role +assigned to a group on `/pool/dev/web` replaces the role the group inherits from +`/pool/dev`, and `NoAccess` on `/pool/dev/web` removes the access to the members +of `dev/web` and its nested pools. Without the propagate flag, a permission on a +pool only applies to the direct members of that pool. Permissions on a nested +pool never apply to the members of its parent pools. + +Creating a pool requires the `Pool.Allocate` privilege on the path of the new +pool. A user with this privilege on a pool, for example through the +`PVEPoolAdmin` role, can therefore create nested pools below it, but no pools +outside of it. Likewise, the `VM.Allocate` privilege on a pool allows creating +guests in that pool. + Which Permissions Do I Need? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 2.53.0