VDC storage — model and architecture
What it is
VDC storage (Unified Storage) is block storage that belongs to a single virtual data center (VDC) and is exported to external hosts over iSCSI. The storage uses a cluster pool: vStack Center creates a root ZFS dataset on the pool and associates it with the VDC. Volumes are created inside this dataset, count against their VDC's storage quota, and are exported as LUNs.
The model is limited and predictable: one storage instance per VDC, one pool for that storage, and one iSCSI target. These strict constraints simplify the main operational question: "Who owns this volume, and who can see it?" The answer is always unambiguous, because a volume has exactly one VDC owner and is exported to exactly one initiator group.
Storage components
The entities form a chain from hardware to the consumer. The pool provides space, the root dataset isolates the VDC's space, the volume is the unit exported, the target and LUN provide access, and initiator and portal groups define who can connect and through which addresses.
| Entity | What it is | Ownership scope |
|---|---|---|
| Pool | The cluster's ZFS pool that hosts the storage root dataset | Cluster |
| Root dataset | A dataset in the form <пул>/<имя>; the name contains 1–63 characters: lowercase Latin letters, digits, periods, and hyphens | One VDC |
| Volume | A zvol with the full name <пул>/.vol/<имя>; the size is specified in GB, and the default block size is 32768 | One VDC |
| iSCSI target | An access point with an IQN in the form iqn.2024-01.io.vstack:<имя хранилища> | One VDC |
| LUN | A number in 0..255 under which the volume is visible on the target | One target |
| Portal group | A set of "address + TCP port" pairs on which the target listens | One pool |
| Portal | An IP:port pair within a group. It is not managed as a separate object — portals are defined by the group's membership | Portal group |
| Initiator group | A list of initiator IQNs and authorized networks in CIDR notation | One VDC |
| CHAP auth group | A set of credentials for iSCSI password protection | One VDC |
The storage name is not merely a label: the target IQN is derived from it. The name
segment of the root dataset after / is appended to the iqn.2024-01.io.vstack: prefix.
Storage names must therefore be unique within the cluster — otherwise, the second
target cannot be created.
How operations work
vStack Center does not access the pool directly. Storage commands are sent to the SAN controller of the pool that hosts the root dataset. This causes differences in interface behavior that are important to understand — they determine when you see the result.
| Operation class | Interface behavior | Examples |
|---|---|---|
| Reading stored records | Responds immediately using vStack Center records | Storage summary, volume list, cluster access overview |
| Reading live metrics | Queries the SAN controller; if it is unavailable, leaves the live fields empty but opens the page | Volume card, current storage capacity |
| Change | Waits for confirmation from the pool controller and keeps the progress indicator displayed | Enabling storage, creating a portal group |
| Sequence of changes | Waits for the entire sequence of steps on the controller to complete | Mapping and unmapping a volume |
Records are written upon confirmation. If the controller rejects the operation, no group, target, or volume appears in vStack Center — the reason for rejection is passed through from the controller unchanged. The reverse is also true: an object in the list means that the controller confirmed the operation. These objects have no intermediate "creating" state.
Deletion does have an intermediate state. Starting with 3.1.0, interrupted storage removal is shown as a separate state: it indicates that VDC deletion must be run again — previously, such storage appeared to be enabled and healthy. Successful removal clears this state.
Model invariants
Some constraints are built into the model and checked before contacting the controller. Knowing these rules saves time when investigating failures.
| Invariant | What happens if it is violated |
|---|---|
| One storage instance per VDC | Enabling it again is rejected with code -45007 |
| One pool per storage instance | The pool is taken from the VDC storage and cannot be selected |
| One target per VDC | Configuring iSCSI again is rejected with code -45014 |
| The volume name is unique within the VDC storage | A name already in use is rejected with code -45018 |
| A volume is exported to exactly one initiator group | Already mapped — code -45027 |
| The LUN number is available on the target | A number already in use — code -45029 |
| A portal group is immutable | Its membership cannot be edited: create a new group instead |
| One CHAP auth group per target | Assigning a new group replaces the previous one |
Capacity and quota
VDC storage capacity equals the VDC's storage quota — the storage has no separate limit. In the storage summary, the quota appears in the Capacity field of the Properties card. The Storage column on the Virtual Data Centers screen shows used space across all VDCs; the limit itself is edited in the VDC settings using the Storage (GB) field.
The quota covers all space used by the VDC, not just storage volumes: virtual machine
disks and previously created volumes are added together. The check runs before
contacting the controller and under a lock on the VDC — two concurrent requests
cannot jointly bypass the limit. If the requested size does not fit, the operation
is rejected with code -45017, and the message shows the requested and available space.
Feature flag
The entire domain is gated by the feature.unified_storage flag in the cluster
options. The flag is disabled by default. While it is disabled, any storage operation
is rejected after the privilege check with code -45001 and the message "Unified Storage
feature is disabled". The Cluster master role does not bypass the flag.
Who can see what
The domain is divided into cluster and VDC levels. Enabling storage and creating and deleting portal groups are reserved for the Cluster master role. A VDC administrator can read their storage and work with their volumes and initiator groups. They can read portal groups across the entire cluster; this access is not limited to their VDC.
| Privilege | Number | Granted to |
|---|---|---|
Enable vDC Storage | 13000 | Cluster master (global scope required) |
iSCSI Create Portal Group | 13004 | Cluster master |
iSCSI Delete Portal Group | 13005 | Cluster master |
iSCSI View Portal Group | 13006 | Cluster master, VDC administrator (entire cluster) |
iSCSI List Portal Groups | 13007 | Cluster master, VDC administrator (entire cluster) |
Configure vDC Storage iSCSI | 13009 | Cluster master |
View vDC Storage | 13010 | Cluster master, VDC administrator (their VDCs) |
List vDC Storages | 13011 | Cluster master, VDC administrator (their VDCs) |
View vDC Storage iSCSI Detail | 13026 | Cluster master, VDC administrator (their VDCs) |
Create vDC Volume | — | Cluster master, VDC administrator (their VDC) |
Delete vDC Volume | — | Cluster master, VDC administrator (their VDC) |
Map vDC Volume | — | Cluster master, VDC administrator (their VDC) |
Unmap vDC Volume | — | Cluster master, VDC administrator (their VDC) |
List All Volumes | — | Cluster master (global scope) |
View Storage Overview | — | Cluster master (global scope) |
Privileges 13006 and 13007 do not account for scope, so a VDC administrator can see portal groups for all pools in the cluster. They still cannot create or delete them.
Privileges 13010 and 13011 account for scope: a VDC administrator receives data
only for VDCs they are authorized to access. A request for another VDC returns
-403 without revealing whether that VDC exists. The same approach protects
reads across VDCs: the cluster overview and combined volume table show the topology
of all VDCs, so they are unavailable to an individual VDC administrator.
Cluster access overview
The cluster view is in the Unified Storage section under the cluster node. The Overview tab shows the Protocol Access Overview block — an access funnel with five counts: Initiators → Portal Groups → VDC with Unified Storage → Targets → LUNs. All counts come from a single consistent snapshot, so the funnel levels are arithmetically consistent with one another.
The breakdown is by protocol: in the current version, the screen has one column — iSCSI. A cluster without storage shows a separate message instead of a grid of zeros, while a zero in a nonempty cluster is displayed as "0" — these are different states. A loading error is also distinguishable from "no data".
The section is visible only to the Cluster master role: without cluster overview privileges, the Unified Storage node does not appear in the tree at all.
Cluster portal groups are in the same section, on the Protocols tab → iSCSI selector.
Where to find information
| Task | Where it is described |
|---|---|
| Enable VDC storage | How to create a VDC with Unified Storage |
| Create, read, and delete a volume | VDC volumes |
| Configure the access point and CHAP | Configuring iSCSI and CHAP |
| Define who is authorized and through which addresses | Initiator and portal groups |
| Export a volume to a host and remove the mapping | Connecting volumes over iSCSI |
| View the entire cluster | This page, "Cluster access overview" section |
Deployment order
The steps follow a strict sequence, and each step depends on the previous one. The cluster administrator prepares a portal group on the pool in advance: without it, the iSCSI configuration form does not allow you to proceed. Then enable storage on the pool, configure iSCSI, create an initiator group, and only then map volumes.
You can create volumes as soon as storage is enabled — iSCSI is not required for creation; it is required for mapping.
See also
- How to create a VDC with Unified Storage — the initial procedure from creating a VDC to creating the first volume.
- Storage pools — where the root dataset resides and how pool capacity is calculated.
- VDC quotas and resources — how the storage quota that determines storage capacity works.
API methods
API operations covered on this page: vdc-storage-get, vdc-storage-list,
cluster-storage-overview, cluster-list-volumes — see the
API reference.