public inbox for pve-devel@lists.proxmox.com
 help / color / mirror / Atom feed
* [PATCH docs] fix #7482: pveum: document nested resource pools
@ 2026-11-12 13:40 Jakob-Tobias Winter
  0 siblings, 0 replies; only message in thread
From: Jakob-Tobias Winter @ 2026-11-12 13:40 UTC (permalink / raw)
  To: pve-devel; +Cc: Jakob-Tobias Winter

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 <tobias@stuttgart.de>
---
 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
+<<pveum_pools,Pools>> 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 <<pveum_nested_pools,nested pool>> 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




^ permalink raw reply related	[flat|nested] only message in thread

only message in thread, other threads:[~2026-11-12 13:47 UTC | newest]

Thread overview: (only message) (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-12 13:40 [PATCH docs] fix #7482: pveum: document nested resource pools Jakob-Tobias Winter

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal