From: Jakob-Tobias Winter <tobias@stuttgart.de>
To: pve-devel@lists.proxmox.com
Cc: Jakob-Tobias Winter <tobias@stuttgart.de>
Subject: [PATCH docs] fix #7482: pveum: document nested resource pools
Date: Thu, 12 Nov 2026 14:40:41 +0100 [thread overview]
Message-ID: <20261112134040.822659-3-tobias@stuttgart.de> (raw)
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
reply other threads:[~2026-11-12 13:47 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
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=20261112134040.822659-3-tobias@stuttgart.de \
--to=tobias@stuttgart.de \
--cc=pve-devel@lists.proxmox.com \
/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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.