From b412bddcc256a7baae1b4e3971311844fa2b787a Mon Sep 17 00:00:00 2001 From: bcampbellverg Date: Mon, 18 May 2026 15:37:37 -0400 Subject: [PATCH 1/5] need to review --- docs/glossary.md | 26 ++--- docs/product-guide/storage/storage-units.md | 109 ++++++++++++++++++++ 2 files changed, 115 insertions(+), 20 deletions(-) create mode 100644 docs/product-guide/storage/storage-units.md diff --git a/docs/glossary.md b/docs/glossary.md index 3b7f7a95..84a62576 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -1,23 +1,3 @@ ---- -title: "Glossary of Key Terms" -description: "Definitions of key terms and concepts used throughout VergeOS documentation, including networking, storage, virtualization, and multi-tenancy terminology." -semantic_keywords: - - "VergeOS glossary terms definitions terminology" - - "virtualization networking storage multi-tenancy concepts" - - "VergeOS platform vocabulary key terms reference" -use_cases: - - lookup_terminology - - onboarding_new_users - - reference_definitions -tags: - - glossary - - terminology - - reference - - definitions -categories: - - Getting Started ---- - # Glossary of Key Terms ## A @@ -165,6 +145,12 @@ Definitions of the aspects of a subscription in VergeOS, such as on-demand/sched ## T +### **TB (terabyte)**: +A unit of storage displayed throughout the VergeOS GUI and usage reports. In VergeOS, values labeled "TB" are calculated using tebibyte (base-1024) math: 1 TB = 1,099,511,627,776 bytes, which is approximately 9.95% larger than the SI terabyte (10¹² bytes) used by disk manufacturers. See [Storage Units and Capacity Reporting](/product-guide/storage/storage-units) for details. + +### **TiB (tebibyte)**: +The binary unit equal to 2⁴⁰ bytes (1,099,511,627,776 bytes). Used internally by VergeOS for all storage calculations and displayed in the GUI with the "TB" label — the same convention followed by Windows, most Linux tools, and other hypervisor and infrastructure platforms. + ### **Tenant**: A complete and separate Virtual Data Center running its own instance of the VergeOS OS, apportioned from a parent VergeOS cloud. diff --git a/docs/product-guide/storage/storage-units.md b/docs/product-guide/storage/storage-units.md new file mode 100644 index 00000000..15b86d95 --- /dev/null +++ b/docs/product-guide/storage/storage-units.md @@ -0,0 +1,109 @@ +--- +title: "Storage Units and Capacity Reporting" +description: "How VergeOS represents storage capacity in the GUI and usage reports, including the TB-vs-TiB labeling behavior, a worked example, and a comparison to manufacturer-advertised disk capacity." +semantic_keywords: + - "VergeOS storage units TB TiB" + - "tebibyte terabyte capacity reporting" + - "base-1024 base-1000 storage math" + - "disk capacity SI binary prefix VergeOS" + - "apparent storage capacity discrepancy drive label mismatch" + - "missing storage capacity drive size smaller than expected" + - "why does VergeOS show less storage than the drives I purchased" +use_cases: + - capacity_planning + - interpreting_usage_reports + - reconciling_disk_manufacturer_capacity + - troubleshooting_apparent_capacity_mismatch + - administrator_reference +tags: + - storage + - capacity-planning + - units + - reporting + - reference +categories: + - Storage +--- + +# Storage Units and Capacity Reporting + +VergeOS displays storage capacity using familiar labels (KB, MB, GB, TB) throughout the GUI, dashboards, and usage reports, with calculations of storage values using **base-1024 (binary) math**. The labels are SI-style ("TB"), but the underlying values are tebibytes (TiB), gibibytes (GiB), and so on. This page explains that behavior, why it matters, and how to reconcile VergeOS figures with the SI capacity figures that disk manufacturers advertise. + +This labeling convention is not unique to VergeOS. Most operating systems and enterprise infrastructure storage products (Windows, most Linux tools, traditional SAN/NAS arrays, and competing HCI platforms) display storage values using SI-style labels — KB, MB, GB, TB — while performing the underlying math in base-1024. Disk manufacturers, by contrast, consistently use the strict SI definition (10¹² bytes per TB) on product labels and datasheets, which is what creates the apparent discrepancy described below. + +## Quick reference + +!!! info "What "TB" means in the VergeOS UI" + A value displayed as **1 TB** in VergeOS represents **1 TiB** — i.e. 2⁴⁰ bytes (1,099,511,627,776 bytes), not the SI definition of 10¹² bytes (1,000,000,000,000 bytes). The same principle applies to KB / MB / GB. + +!!! success "You still have every byte you purchased" + Although the number displayed in the VergeOS UI is smaller than the figure printed on the drive's label, **no capacity has been lost**. The drives still hold exactly as many bytes as the manufacturer specifies — for example, a "4 TB" drive still holds 4,000,000,000,000 bytes, and all of those bytes are available to VergeOS. The difference is only in how the same byte count is labeled and displayed, not in how much storage you can actually use. + +## Why this matters + +Disk manufacturers and most consumer-facing storage products use SI (decimal, base‑1000) prefixes, an industry convention that results in larger‑appearing capacity numbers than binary units. Operating systems and infrastructure platforms, including VergeOS, generally use binary (base-1024) calculations because storage is allocated, addressed, and reported in powers of two. Because both the disk manufacturer's spec sheet and the VergeOS UI use the label "TB", the two figures look directly comparable — but they are not. The manufacturer's "TB" means 10¹² bytes; VergeOS's "TB" means 2⁴⁰ bytes (1 TiB). + +The difference compounds with size: a 1 TB label in VergeOS is ~9.95% larger than a manufacturer-advertised 1 TB drive. At petabyte scale the gap is closer to ~12.6%. + +## Worked example + +A drive advertised by the manufacturer as **1 TB** holds 1,000,000,000,000 bytes (10¹² B, SI). + +The same byte count reported in VergeOS would display as **~0.909 TB**, because VergeOS uses TiB math (1 TB label = 1,099,511,627,776 B). + +Equivalently, a value VergeOS labels as **1 TB** is **1,099,511,627,776 B**, which is **~1.0995 SI TB** — about **9.95% larger** than what the drive's label advertises. + +## Example scenario + +A customer purchases four drives labeled by the manufacturer as **4 TB** each, expecting **16 TB** of raw capacity. After installation, the VergeOS UI reports the array at approximately **14.55 TB**, and the customer asks where the missing ~1.45 TB went. + +Nothing is missing — every byte that was purchased is still there and usable. The drives each hold 4 × 10¹² bytes (4 SI TB), and VergeOS has access to all of that capacity. It simply reports the same byte count using TiB math but with a "TB" label: + +- 4 SI TB per drive × 4 drives = 16,000,000,000,000 bytes +- 16,000,000,000,000 ÷ 1,099,511,627,776 = **~14.55 TiB**, displayed as "14.55 TB" + +The same effect at common drive sizes: + +| Manufacturer label | VergeOS displays | +| --- | --- | +| 1 TB drive | ~0.91 TB | +| 4 TB drive | ~3.64 TB | +| 8 TB drive | ~7.28 TB | +| 12 TB drive | ~10.91 TB | +| 16 TB drive | ~14.55 TB | + +!!! note "This is separate from redundancy and overhead" + Capacity is also reduced by vSAN redundancy levels and metadata reservation. Those reductions are independent of the unit-labeling effect described here. (Deduplication, by contrast, generally *increases* usable capacity by collapsing duplicate blocks.) See [vSAN Architecture](/product-guide/storage/vsan-architecture) and [vSAN Redundancy Levels](/product-guide/storage/vsan-redundancy-levels) for details. + +## Unit reference + +| VergeOS label | Internal value (bytes) | SI equivalent | Difference vs. SI | +| --- | --- | --- | --- | +| 1 KB | 1,024 (2¹⁰) | 1,000 | +2.40% | +| 1 MB | 1,048,576 (2²⁰) | 1,000,000 | +4.86% | +| 1 GB | 1,073,741,824 (2³⁰) | 1,000,000,000 | +7.37% | +| 1 TB | 1,099,511,627,776 (2⁴⁰) | 1,000,000,000,000 | +9.95% | +| 1 PB | 1,125,899,906,842,624 (2⁵⁰) | 10¹⁵ | +12.59% | + +## Where this applies + +The TB-as-TiB convention applies throughout the VergeOS platform, including: + +- vSAN capacity and free-space figures shown on system, cluster, and tier dashboards +- Storage tier sizing reported in the GUI (see [Storage Tiers](/product-guide/storage/storage-tiers)) +- Virtual machine drive sizes and snapshots +- NAS volume sizes +- Tenant resource allocations and [usage reports](/product-guide/tenants/tenant-usagereports) +- Backup and replication size reporting + +Memory (RAM) is also reported using binary units following the same convention. + +## Planning guidance + +When sizing a VergeOS deployment from manufacturer specifications: + +- Treat the "TB" figure on a drive's label as **SI TB** (10¹² bytes). +- Convert to TiB before comparing to VergeOS figures: TiB ≈ SI TB × 0.9095. +- Or, equivalently, multiply VergeOS "TB" figures by ~1.0995 to compare against drive-label capacity. + +For node sizing recommendations, see the [Node Sizing Guide](/implementation-guide/sizing). From bd4afc9e5cb4ee295eedfcc3c569d18f23d6220f Mon Sep 17 00:00:00 2001 From: bcampbellverg Date: Mon, 18 May 2026 15:48:05 -0400 Subject: [PATCH 2/5] fixes --- docs/glossary.md | 20 ++++++++++++++++++++ docs/product-guide/storage/storage-units.md | 2 +- 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/glossary.md b/docs/glossary.md index 84a62576..a56001a0 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -1,3 +1,23 @@ +--- +title: "Glossary of Key Terms" +description: "Definitions of key terms and concepts used throughout VergeOS documentation, including networking, storage, virtualization, and multi-tenancy terminology." +semantic_keywords: + - "VergeOS glossary terms definitions terminology" + - "virtualization networking storage multi-tenancy concepts" + - "VergeOS platform vocabulary key terms reference" +use_cases: + - lookup_terminology + - onboarding_new_users + - reference_definitions +tags: + - glossary + - terminology + - reference + - definitions +categories: + - Getting Started +--- + # Glossary of Key Terms ## A diff --git a/docs/product-guide/storage/storage-units.md b/docs/product-guide/storage/storage-units.md index 15b86d95..e38787ed 100644 --- a/docs/product-guide/storage/storage-units.md +++ b/docs/product-guide/storage/storage-units.md @@ -103,7 +103,7 @@ Memory (RAM) is also reported using binary units following the same convention. When sizing a VergeOS deployment from manufacturer specifications: - Treat the "TB" figure on a drive's label as **SI TB** (10¹² bytes). -- Convert to TiB before comparing to VergeOS figures: TiB ≈ SI TB × 0.9095. +- Convert to binary calculations (TiB) before comparing to VergeOS figures: TiB ≈ SI TB × 0.9095. - Or, equivalently, multiply VergeOS "TB" figures by ~1.0995 to compare against drive-label capacity. For node sizing recommendations, see the [Node Sizing Guide](/implementation-guide/sizing). From 5d1f212c55cb554e697e32351fd182ce8b46bcfe Mon Sep 17 00:00:00 2001 From: bcampbellverg Date: Tue, 19 May 2026 10:15:30 -0400 Subject: [PATCH 3/5] misc changes --- docs/product-guide/storage/storage-units.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/product-guide/storage/storage-units.md b/docs/product-guide/storage/storage-units.md index e38787ed..7ef00d04 100644 --- a/docs/product-guide/storage/storage-units.md +++ b/docs/product-guide/storage/storage-units.md @@ -27,7 +27,7 @@ categories: # Storage Units and Capacity Reporting -VergeOS displays storage capacity using familiar labels (KB, MB, GB, TB) throughout the GUI, dashboards, and usage reports, with calculations of storage values using **base-1024 (binary) math**. The labels are SI-style ("TB"), but the underlying values are tebibytes (TiB), gibibytes (GiB), and so on. This page explains that behavior, why it matters, and how to reconcile VergeOS figures with the SI capacity figures that disk manufacturers advertise. +VergeOS displays storage capacity using familiar labels (KB, MB, GB, TB) throughout the GUI, dashboards, and usage reports, with calculations of storage values using **base-1024 (binary) math**. The labels are SI-style ("TB"), with underlying values in tebibytes (TiB), gibibytes (GiB), and so on. This page explains that behavior, why it matters, and how to reconcile VergeOS figures with the SI capacity figures that disk manufacturers advertise. This labeling convention is not unique to VergeOS. Most operating systems and enterprise infrastructure storage products (Windows, most Linux tools, traditional SAN/NAS arrays, and competing HCI platforms) display storage values using SI-style labels — KB, MB, GB, TB — while performing the underlying math in base-1024. Disk manufacturers, by contrast, consistently use the strict SI definition (10¹² bytes per TB) on product labels and datasheets, which is what creates the apparent discrepancy described below. @@ -72,9 +72,6 @@ The same effect at common drive sizes: | 12 TB drive | ~10.91 TB | | 16 TB drive | ~14.55 TB | -!!! note "This is separate from redundancy and overhead" - Capacity is also reduced by vSAN redundancy levels and metadata reservation. Those reductions are independent of the unit-labeling effect described here. (Deduplication, by contrast, generally *increases* usable capacity by collapsing duplicate blocks.) See [vSAN Architecture](/product-guide/storage/vsan-architecture) and [vSAN Redundancy Levels](/product-guide/storage/vsan-redundancy-levels) for details. - ## Unit reference | VergeOS label | Internal value (bytes) | SI equivalent | Difference vs. SI | @@ -96,7 +93,11 @@ The TB-as-TiB convention applies throughout the VergeOS platform, including: - Tenant resource allocations and [usage reports](/product-guide/tenants/tenant-usagereports) - Backup and replication size reporting -Memory (RAM) is also reported using binary units following the same convention. +Beyond the labeling convention, vSAN usable capacity is also affected by redundancy levels, which reduce usable capacity in exchange for fault tolerance. Deduplication, by contrast, generally increases usable capacity by collapsing duplicate blocks. These effects are independent of the unit-labeling behavior described on this page. See [vSAN Architecture](/product-guide/storage/vsan-architecture) and [vSAN Redundancy Levels](/product-guide/storage/vsan-redundancy-levels) for details. + +## Display rounding across screens + +The same drive's capacity can appear differently from one screen to another in the VergeOS UI. Some pages — such as the node drive listing — round to whole numbers and tend to match the manufacturer's SI label (a drive sold as "2 TB" appears as "2 TB"). Other pages — such as the node drive dashboard — display the precise binary value rounded to the nearest tenth (the same drive appears as "1.8 TB"). Both figures refer to the identical physical drive; only the rounding convention differs. ## Planning guidance From 89e56f8826b72d42522631ab4323f05625ebaeb2 Mon Sep 17 00:00:00 2001 From: bcampbellverg Date: Tue, 19 May 2026 10:19:33 -0400 Subject: [PATCH 4/5] add prod guide menu item --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index 1f99b454..d4840cee 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -178,6 +178,7 @@ nav: - vSAN Redundancy Levels: product-guide/storage/vsan-redundancy-levels.md - Storage Tiers: product-guide/storage/storage-tiers.md - Preferred Tier: product-guide/storage/preferred-tiers.md + - Storage Units and Capacity Reporting: product-guide/storage/storage-units.md - External Storage Integration: product-guide/storage/external-storage-integration.md - Fibre Channel: product-guide/storage/fibre-channel.md - vSAN Deletion Process: product-guide/storage/vsan-deletion-process.md From 22127612c0df8ef0e98ee1b3f93269368e1be62d Mon Sep 17 00:00:00 2001 From: Jason Yaeger <30736996+jasnoyaeger@users.noreply.github.com> Date: Tue, 2 Jun 2026 06:29:10 -0400 Subject: [PATCH 5/5] address review feedback on storage-units page - fix admonition title rendering (curly quotes instead of escaped) - add Overview header and Related guides section per pg-writer conventions - trim semantic_keywords to 5 - soften "competing HCI platforms" to "other HCI platforms" - drop redundant success admonition (point is made in Example scenario) Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/product-guide/storage/storage-units.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/product-guide/storage/storage-units.md b/docs/product-guide/storage/storage-units.md index 7ef00d04..ab12bca1 100644 --- a/docs/product-guide/storage/storage-units.md +++ b/docs/product-guide/storage/storage-units.md @@ -6,8 +6,6 @@ semantic_keywords: - "tebibyte terabyte capacity reporting" - "base-1024 base-1000 storage math" - "disk capacity SI binary prefix VergeOS" - - "apparent storage capacity discrepancy drive label mismatch" - - "missing storage capacity drive size smaller than expected" - "why does VergeOS show less storage than the drives I purchased" use_cases: - capacity_planning @@ -27,18 +25,17 @@ categories: # Storage Units and Capacity Reporting +## Overview + VergeOS displays storage capacity using familiar labels (KB, MB, GB, TB) throughout the GUI, dashboards, and usage reports, with calculations of storage values using **base-1024 (binary) math**. The labels are SI-style ("TB"), with underlying values in tebibytes (TiB), gibibytes (GiB), and so on. This page explains that behavior, why it matters, and how to reconcile VergeOS figures with the SI capacity figures that disk manufacturers advertise. -This labeling convention is not unique to VergeOS. Most operating systems and enterprise infrastructure storage products (Windows, most Linux tools, traditional SAN/NAS arrays, and competing HCI platforms) display storage values using SI-style labels — KB, MB, GB, TB — while performing the underlying math in base-1024. Disk manufacturers, by contrast, consistently use the strict SI definition (10¹² bytes per TB) on product labels and datasheets, which is what creates the apparent discrepancy described below. +This labeling convention is not unique to VergeOS. Most operating systems and enterprise infrastructure storage products (Windows, most Linux tools, traditional SAN/NAS arrays, and other HCI platforms) display storage values using SI-style labels — KB, MB, GB, TB — while performing the underlying math in base-1024. Disk manufacturers, by contrast, consistently use the strict SI definition (10¹² bytes per TB) on product labels and datasheets, which is what creates the apparent discrepancy described below. ## Quick reference -!!! info "What "TB" means in the VergeOS UI" +!!! info "What “TB” means in the VergeOS UI" A value displayed as **1 TB** in VergeOS represents **1 TiB** — i.e. 2⁴⁰ bytes (1,099,511,627,776 bytes), not the SI definition of 10¹² bytes (1,000,000,000,000 bytes). The same principle applies to KB / MB / GB. -!!! success "You still have every byte you purchased" - Although the number displayed in the VergeOS UI is smaller than the figure printed on the drive's label, **no capacity has been lost**. The drives still hold exactly as many bytes as the manufacturer specifies — for example, a "4 TB" drive still holds 4,000,000,000,000 bytes, and all of those bytes are available to VergeOS. The difference is only in how the same byte count is labeled and displayed, not in how much storage you can actually use. - ## Why this matters Disk manufacturers and most consumer-facing storage products use SI (decimal, base‑1000) prefixes, an industry convention that results in larger‑appearing capacity numbers than binary units. Operating systems and infrastructure platforms, including VergeOS, generally use binary (base-1024) calculations because storage is allocated, addressed, and reported in powers of two. Because both the disk manufacturer's spec sheet and the VergeOS UI use the label "TB", the two figures look directly comparable — but they are not. The manufacturer's "TB" means 10¹² bytes; VergeOS's "TB" means 2⁴⁰ bytes (1 TiB). @@ -107,4 +104,10 @@ When sizing a VergeOS deployment from manufacturer specifications: - Convert to binary calculations (TiB) before comparing to VergeOS figures: TiB ≈ SI TB × 0.9095. - Or, equivalently, multiply VergeOS "TB" figures by ~1.0995 to compare against drive-label capacity. -For node sizing recommendations, see the [Node Sizing Guide](/implementation-guide/sizing). +## Related guides + +- [Node Sizing Guide](/implementation-guide/sizing) — sizing recommendations for VergeOS deployments +- [vSAN Architecture](/product-guide/storage/vsan-architecture) — how vSAN distributes and protects data +- [vSAN Redundancy Levels](/product-guide/storage/vsan-redundancy-levels) — how redundancy affects usable capacity +- [Storage Tiers](/product-guide/storage/storage-tiers) — performance and capacity tiering +- [Tenant Usage Reports](/product-guide/tenants/tenant-usagereports) — interpreting per-tenant capacity reporting