From 13a5aa5ef752fe23294c84a865582bd3b09263ba Mon Sep 17 00:00:00 2001 From: sushant-suse Date: Tue, 18 Nov 2025 15:24:37 +0530 Subject: [PATCH 1/4] docs: add CLI steps for node management Signed-off-by: sushant-suse --- .../nodes/node-space-usage.md | 96 +++++++++++++++++++ 1 file changed, 96 insertions(+) diff --git a/content/docs/1.11.0/nodes-and-volumes/nodes/node-space-usage.md b/content/docs/1.11.0/nodes-and-volumes/nodes/node-space-usage.md index 066a63f2b..52abf6f70 100644 --- a/content/docs/1.11.0/nodes-and-volumes/nodes/node-space-usage.md +++ b/content/docs/1.11.0/nodes-and-volumes/nodes/node-space-usage.md @@ -57,3 +57,99 @@ Disk default-disk-1030100000000 (/var/lib/longhorn/) on the node ip-192-168-203- - multiplied by the cluster’s `Storage Over Provisioning Percentage` When `ScheduledTotal` exceeds `ProvisionedLimit`, the disk becomes unschedulable and will not accept new replicas until the disk configuration or cluster settings are adjusted. + +## Viewing Node & Disk Space Usage via `kubectl` (CRs) + +Longhorn exposes node-level and disk-level storage information through the **Longhorn Node** Custom Resource (CR). This section explains how to inspect disk capacity, schedulability, and node storage settings using `kubectl`. + +### List all Longhorn nodes + +```bash +kubectl get nodes.longhorn.io -n longhorn-system +``` + +### View detailed node and disk space usage + +To view disk capacity, reserved space, scheduling state, and conditions for a specific node: + +```bash +kubectl get nodes.longhorn.io ubuntu-lh-2 -n longhorn-system -o yaml + +# replace ubuntu-lh-2 with your node name +``` + +Key fields appear under: + +```yaml +status: + diskStatus: + : + storageAvailable: # Free space on disk + storageMaximum: # Physical disk size + storageScheduled: # Total scheduled replica data + conditions: + - type: Schedulable + status: + reason: + message: + lastTransitionTime: +``` + +> **Note**: The reserved space configured is stored under `spec.disks..storageReserved`. + +These values map directly to those shown in the Longhorn UI. + +### Check disk schedulability and message + +```bash +kubectl get nodes.longhorn.io ubuntu-lh-2 -n longhorn-system -o json | jq -r ' +.status.diskStatus +| to_entries[] +| "Disk: \(.key) Schedulable: \(.value.conditions[] | select(.type=="Schedulable") | .status) Message: \(.value.conditions[] | select(.type=="Schedulable") | .message)"' + +# replace ubuntu-lh-2 with your node name + +# Sample Output: +# Disk: default-disk-4c31e9a428aa4512 Schedulable: True Message: Disk default-disk-4c31e9a428aa4512(/var/lib/longhorn/) on node ubuntu-lh-2 is schedulable +``` + +### View node disk metrics in table format + +```bash +kubectl get nodes.longhorn.io -n longhorn-system \ + -o custom-columns=NODE:.metadata.name,DISK:.status.diskStatus.*.diskPath,AVAILABLE:.status.diskStatus.*.storageAvailable,MAX:.status.diskStatus.*.storageMaximum,RESERVED:.spec.disks.*.storageReserved,SCHEDULED:.status.diskStatus.*.storageScheduled | column -t + +# Sample Output: +# NODE DISK AVAILABLE MAX RESERVED SCHEDULED +# ubuntu-lh-2 /var/lib/longhorn/ 36175872000 51409092608 15422727782 2147483648 +``` + +### Modify disk reserved space + +To change how much space Longhorn must keep free on a disk: + +1. Export the node spec: + +```bash +kubectl get nodes.longhorn.io ubuntu-lh-2 -n longhorn-system -o yaml > lh-node.yaml + +# replace ubuntu-lh-2 with your node name +``` + +2. Locate your disk entry under `spec.disks` and edit: + +```yaml +spec: + disks: + default-disk-xxxx: + path: /var/lib/longhorn/ + storageReserved: 15422727782 # update this value with something appropriate like 21474836480 +``` + +3. Apply the changes: + +```bash +kubectl apply -f lh-node.yaml +``` + +Longhorn recalculates disk schedulability immediately. From c6c3d95feb471cb42361e6a3b189037e68c95a15 Mon Sep 17 00:00:00 2001 From: sushant-suse Date: Tue, 13 Jan 2026 17:32:38 +0530 Subject: [PATCH 2/4] docs: updated as per comments Signed-off-by: sushant-suse --- .../nodes/node-space-usage.md | 27 ++++++++++++++----- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/content/docs/1.11.0/nodes-and-volumes/nodes/node-space-usage.md b/content/docs/1.11.0/nodes-and-volumes/nodes/node-space-usage.md index 52abf6f70..581a7fd1b 100644 --- a/content/docs/1.11.0/nodes-and-volumes/nodes/node-space-usage.md +++ b/content/docs/1.11.0/nodes-and-volumes/nodes/node-space-usage.md @@ -95,7 +95,7 @@ status: lastTransitionTime: ``` -> **Note**: The reserved space configured is stored under `spec.disks..storageReserved`. +> **Note**: The reserved space value configured for the disk is stored under `spec.disks..storageReserved`. These values map directly to those shown in the Longhorn UI. @@ -105,7 +105,7 @@ These values map directly to those shown in the Longhorn UI. kubectl get nodes.longhorn.io ubuntu-lh-2 -n longhorn-system -o json | jq -r ' .status.diskStatus | to_entries[] -| "Disk: \(.key) Schedulable: \(.value.conditions[] | select(.type=="Schedulable") | .status) Message: \(.value.conditions[] | select(.type=="Schedulable") | .message)"' +| "Disk: \(.key) Schedulable: \(.value.conditions[] | select(.type==\"Schedulable\") | .status) Message: \(.value.conditions[] | select(.type==\"Schedulable\") | .message)"' # replace ubuntu-lh-2 with your node name @@ -116,12 +116,25 @@ kubectl get nodes.longhorn.io ubuntu-lh-2 -n longhorn-system -o json | jq -r ' ### View node disk metrics in table format ```bash -kubectl get nodes.longhorn.io -n longhorn-system \ - -o custom-columns=NODE:.metadata.name,DISK:.status.diskStatus.*.diskPath,AVAILABLE:.status.diskStatus.*.storageAvailable,MAX:.status.diskStatus.*.storageMaximum,RESERVED:.spec.disks.*.storageReserved,SCHEDULED:.status.diskStatus.*.storageScheduled | column -t +kubectl get nodes.longhorn.io -n longhorn-system -o json | jq -r ' + .items[] + | . as $node + | .status.diskStatus + | to_entries[] + | [ + $node.metadata.name, + .value.diskPath, + .value.storageAvailable, + .value.storageMaximum, + ($node.spec.disks[.key].storageReserved // "N/A"), + .value.storageScheduled + ] + | @tsv +' | column -t # Sample Output: -# NODE DISK AVAILABLE MAX RESERVED SCHEDULED # ubuntu-lh-2 /var/lib/longhorn/ 36175872000 51409092608 15422727782 2147483648 +# ubuntu-lh-2 /mnt/extra-disk 10000000000 20000000000 5000000000 1000000000 ``` ### Modify disk reserved space @@ -136,14 +149,14 @@ kubectl get nodes.longhorn.io ubuntu-lh-2 -n longhorn-system -o yaml > lh-node.y # replace ubuntu-lh-2 with your node name ``` -2. Locate your disk entry under `spec.disks` and edit: +2. Locate your disk entry under `spec.disks` and edit (`lh-node.yaml`): ```yaml spec: disks: default-disk-xxxx: path: /var/lib/longhorn/ - storageReserved: 15422727782 # update this value with something appropriate like 21474836480 + storageReserved: 15422727782 # update this value to your desired reserved space in bytes (for example, 21474836480 for 20 GiB). Choose a value based on how much disk space you want to reserve for the system or other applications. ``` 3. Apply the changes: From daacb7d0966c60899ecd855e215033b2e7edbb3b Mon Sep 17 00:00:00 2001 From: sushant-suse Date: Mon, 30 Mar 2026 15:35:21 +0530 Subject: [PATCH 3/4] docs: moved and refined the Space Usage of Each Node Signed-off-by: sushant-suse --- .../nodes/node-space-usage.md | 130 ++++-------------- 1 file changed, 29 insertions(+), 101 deletions(-) diff --git a/content/docs/1.11.0/nodes-and-volumes/nodes/node-space-usage.md b/content/docs/1.11.0/nodes-and-volumes/nodes/node-space-usage.md index 581a7fd1b..927a2b4bf 100644 --- a/content/docs/1.11.0/nodes-and-volumes/nodes/node-space-usage.md +++ b/content/docs/1.11.0/nodes-and-volumes/nodes/node-space-usage.md @@ -3,12 +3,11 @@ title: Node Space Usage weight: 1 --- -In this section, you'll have a better understanding of the space usage info presented by the Longhorn UI. - +This section provides a better understanding of the space usage information presented by the Longhorn UI. ### Whole Cluster Space Usage -In `Dashboard` page, Longhorn will show you the cluster space usage info: +In the `Dashboard` page, Longhorn will show you the cluster space usage information: {{< figure src="/img/screenshots/volumes-and-nodes/space-usage-info-dashboard-page.png" >}} @@ -16,104 +15,33 @@ In `Dashboard` page, Longhorn will show you the cluster space usage info: `Reserved`: The space reserved for other applications and system. -`Used`: The actual space that has been used by Longhorn, system, and other applications. +`Used`: The actual space that has been used by Longhorn, system and other applications. `Disabled`: The total space of the disks/nodes on which Longhorn volumes are not allowed for scheduling. ### Space Usage of Each Node -In `Node` page, Longhorn will show the space allocation, schedule, and usage info for each node: +In the `Node` page, Longhorn will show the space allocation, schedule and usage info for each node. You can also view this detailed information via `kubectl` by inspecting the **Longhorn Node** Custom Resource (CR). {{< figure src="/img/screenshots/volumes-and-nodes/space-usage-info-node-page.png" >}} -`Size` column: The **max actual available space** that can be used by Longhorn volumes. It equals the total disk space of the node minus reserved space. - -`Allocated` column: The left number is the size that has been used for **volume scheduling**, and it does not mean the space has been used for the Longhorn volume data store. The right number is the **max** size for volume scheduling, which the result of `Size` multiplying `Storage Over Provisioning Percentage`. (In the above illustration, `Storage Over Provisioning Percentage` is 500.) Hence, the difference between the 2 numbers (let's call it as the allocable space) determines if a volume replica can be scheduled to this node. - -`Used` column: The left part indicates the currently used space of this node. The whole bar indicates the total space of the node. - -Notice that the allocable space may be greater than the actual available space of the node when setting `Storage Over Provisioning Percentage` to a value greater than 100. If the volumes are heavily used and lots of historical data will be stored in the volume snapshots, please be careful about using a large value for this setting. For more info about the setting, see [here](../../../references/settings/#storage-over-provisioning-percentage) for details. - -### Disk Schedulability Status and Troubleshooting Message - -When a disk becomes **unschedulable**, Longhorn exposes the underlying reason directly in the UI. -On the **Node** page, if a disk’s internal `Schedulable` condition is `False`, the UI displays the exact message from `node.diskStatus[x].conditions[Schedulable]`. -This information is essential for diagnosing issues related to space limits or over-provisioning. - -**Example Troubleshooting Message:** - -``` -Disk default-disk-1030100000000 (/var/lib/longhorn/) on the node ip-192-168-203-144.ap-southeast-1.compute.internal is not schedulable for more replica; Scheduling space condition failed: ScheduledTotal = 4294967296 (Size + StorageScheduled) is greater than ProvisionedLimit = -64504221696 (100% of StorageMax - StorageReserved). -``` - -**How to interpret this message:** - -- **`ScheduledTotal`**: The total space currently *scheduled* for replicas (both existing and pending) on this disk. - > **Note**: This does not represent the actual disk usage. - -- **`ProvisionedLimit`**: The **maximum allowed scheduling capacity** for this disk. It is derived from: - - the disk’s physical size (`StorageMax`) - - its reserved space (`StorageReserved`) - - multiplied by the cluster’s `Storage Over Provisioning Percentage` - -When `ScheduledTotal` exceeds `ProvisionedLimit`, the disk becomes unschedulable and will not accept new replicas until the disk configuration or cluster settings are adjusted. - -## Viewing Node & Disk Space Usage via `kubectl` (CRs) - -Longhorn exposes node-level and disk-level storage information through the **Longhorn Node** Custom Resource (CR). This section explains how to inspect disk capacity, schedulability, and node storage settings using `kubectl`. - -### List all Longhorn nodes - -```bash -kubectl get nodes.longhorn.io -n longhorn-system -``` - -### View detailed node and disk space usage - -To view disk capacity, reserved space, scheduling state, and conditions for a specific node: +To view the disk capacity, reserved space, and scheduling state for a specific node (for example, `ubuntu-lh-2`): ```bash kubectl get nodes.longhorn.io ubuntu-lh-2 -n longhorn-system -o yaml - -# replace ubuntu-lh-2 with your node name ``` -Key fields appear under: - -```yaml -status: - diskStatus: - : - storageAvailable: # Free space on disk - storageMaximum: # Physical disk size - storageScheduled: # Total scheduled replica data - conditions: - - type: Schedulable - status: - reason: - message: - lastTransitionTime: -``` +`Size` column: The **max actual available space** that can be used by Longhorn volumes. It equals the total disk space of the node minus reserved space. In the CR, this is represented by `storageMaximum`. -> **Note**: The reserved space value configured for the disk is stored under `spec.disks..storageReserved`. +`Allocated` column: The left number is the size that has been used for **volume scheduling**, and it does not mean the space has been used for the Longhorn volume data store. The right number is the **max** size for volume scheduling, which the result of `Size` multiplying `Storage Over Provisioning Percentage`. (In the above illustration, `Storage Over Provisioning Percentage` is 500.) Hence, the difference between the 2 numbers (let's call it as the allocable space) determines if a volume replica can be scheduled to this node. In the CR, the scheduled size is `storageScheduled`. -These values map directly to those shown in the Longhorn UI. +`Used` column: The left part indicates the currently used space of this node. The whole bar indicates the total space of the node. In the CR, the available space is `storageAvailable`. -### Check disk schedulability and message +Notice that the allocable space may be greater than the actual available space of the node when setting `Storage Over Provisioning Percentage` to a value greater than 100. If the volumes are heavily used and lots of historical data will be stored in the volume snapshots, please be careful about using a large value for this setting. For more info about the setting, see [here](../../../references/settings/%23storage-over-provisioning-percentage) for details. -```bash -kubectl get nodes.longhorn.io ubuntu-lh-2 -n longhorn-system -o json | jq -r ' -.status.diskStatus -| to_entries[] -| "Disk: \(.key) Schedulable: \(.value.conditions[] | select(.type==\"Schedulable\") | .status) Message: \(.value.conditions[] | select(.type==\"Schedulable\") | .message)"' +> **Note**: The reserved space value configured for the disk is stored under `spec.disks..storageReserved`. These values map directly to those shown in the Longhorn UI. -# replace ubuntu-lh-2 with your node name - -# Sample Output: -# Disk: default-disk-4c31e9a428aa4512 Schedulable: True Message: Disk default-disk-4c31e9a428aa4512(/var/lib/longhorn/) on node ubuntu-lh-2 is schedulable -``` - -### View node disk metrics in table format +#### View node disk metrics in table format ```bash kubectl get nodes.longhorn.io -n longhorn-system -o json | jq -r ' @@ -137,32 +65,32 @@ kubectl get nodes.longhorn.io -n longhorn-system -o json | jq -r ' # ubuntu-lh-2 /mnt/extra-disk 10000000000 20000000000 5000000000 1000000000 ``` -### Modify disk reserved space +#### Modify disk reserved space To change how much space Longhorn must keep free on a disk: -1. Export the node spec: +1. Export the node spec: -```bash -kubectl get nodes.longhorn.io ubuntu-lh-2 -n longhorn-system -o yaml > lh-node.yaml + ```bash + kubectl get nodes.longhorn.io ubuntu-lh-2 -n longhorn-system -o yaml > lh-node.yaml -# replace ubuntu-lh-2 with your node name -``` + # replace ubuntu-lh-2 with your node name + ``` -2. Locate your disk entry under `spec.disks` and edit (`lh-node.yaml`): +2. Locate your disk entry under `spec.disks` and edit (`lh-node.yaml`): -```yaml -spec: - disks: - default-disk-xxxx: - path: /var/lib/longhorn/ - storageReserved: 15422727782 # update this value to your desired reserved space in bytes (for example, 21474836480 for 20 GiB). Choose a value based on how much disk space you want to reserve for the system or other applications. -``` + ```yaml + spec: + disks: + default-disk-xxxx: + path: /var/lib/longhorn/ + storageReserved: 15422727782 # update this value to your desired reserved space in bytes (for example, 21474836480 for 20 GiB). Choose a value based on how much disk space you want to reserve for the system or other applications. + ``` -3. Apply the changes: +3. Apply the changes: -```bash -kubectl apply -f lh-node.yaml -``` + ```bash + kubectl apply -f lh-node.yaml + ``` Longhorn recalculates disk schedulability immediately. From 34395854a5ed4d8d14e12357fea40316c3e34371 Mon Sep 17 00:00:00 2001 From: sushant-suse Date: Mon, 13 Apr 2026 14:25:29 +0530 Subject: [PATCH 4/4] docs: fix broken link build Signed-off-by: sushant-suse --- content/docs/1.11.0/nodes-and-volumes/nodes/node-space-usage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/1.11.0/nodes-and-volumes/nodes/node-space-usage.md b/content/docs/1.11.0/nodes-and-volumes/nodes/node-space-usage.md index 927a2b4bf..7006af55e 100644 --- a/content/docs/1.11.0/nodes-and-volumes/nodes/node-space-usage.md +++ b/content/docs/1.11.0/nodes-and-volumes/nodes/node-space-usage.md @@ -37,7 +37,7 @@ kubectl get nodes.longhorn.io ubuntu-lh-2 -n longhorn-system -o yaml `Used` column: The left part indicates the currently used space of this node. The whole bar indicates the total space of the node. In the CR, the available space is `storageAvailable`. -Notice that the allocable space may be greater than the actual available space of the node when setting `Storage Over Provisioning Percentage` to a value greater than 100. If the volumes are heavily used and lots of historical data will be stored in the volume snapshots, please be careful about using a large value for this setting. For more info about the setting, see [here](../../../references/settings/%23storage-over-provisioning-percentage) for details. +Notice that the allocable space may be greater than the actual available space of the node when setting `Storage Over Provisioning Percentage` to a value greater than 100. If the volumes are heavily used and lots of historical data will be stored in the volume snapshots, please be careful about using a large value for this setting. For more info about the setting, see [here](../../../references/settings/#storage-over-provisioning-percentage) for details. > **Note**: The reserved space value configured for the disk is stored under `spec.disks..storageReserved`. These values map directly to those shown in the Longhorn UI.