Skip to content

Commit dd1163a

Browse files
balaharish7balaharish7
authored
docs: Create Documentation for Cordon Pools and modify other Docs (#543)
* docs: Create Documentation for Cordon Pools and modify other Docs Signed-off-by: Bala Harish <[email protected]> * docs: Update FAQs Signed-off-by: Bala Harish <[email protected]> * docs: Update FAQs Signed-off-by: Bala Harish <[email protected]> --------- Signed-off-by: Bala Harish <[email protected]>
1 parent 3cd752a commit dd1163a

File tree

7 files changed

+182
-19
lines changed

7 files changed

+182
-19
lines changed

‎docs/main/faqs/faqs.md‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -580,7 +580,41 @@ The supportability tool generates support bundles, which are used for debugging
580580
581581
### What happens when a PV with reclaim policy set to retain is deleted?
582582
583-
In Kubernetes, when a PVC is created with the reclaim policy set to 'Retain', the PV bound to this PVC is not deleted even if the PVC is deleted. One can manually delete the PV by issuing the command "kubectl delete pv", however the underlying storage resources could be left behind as the CSI volume provisioner (external provisioner) is not aware of this. To resolve this issue of dangling storage objects, Replicated Storage has introduced a PV garbage collector. This PV garbage collector is deployed as a part of the Replicated Storage CSI controller-plugin.
583+
In Kubernetes, when a PVC that is bound to a PV with the reclaim policy set to Retain is deleted, the corresponding PV is not automatically removed. You can delete the PV manually by running the following command:
584+
585+
```
586+
kubectl delete pv <pv-name>
587+
```
588+
589+
However, deleting the PV manually may leave the underlying storage resources orphaned because the CSI external provisioner is not notified of the PV deletion.
590+
591+
Earlier, Replicated Storage automatically handled such orphaned storage objects through a PV Garbage Collector (GC) that was deployed as part of the Replicated Storage CSI controller plugin.
592+
593+
Starting with the latest update, the orphaned PV Garbage Collector is disabled by default. Instead, Replicated Storage provides a mechanism to manually identify and delete unbound volumes using the `kubectl-openebs` plugin. This approach allows administrators to control when and how orphaned volumes are removed, ensuring safer and more predictable cleanup of unused storage resources.
594+
595+
#### Identifying Orphaned Volumes
596+
597+
You can use a shell command to compare existing PVs with volumes reported by Mayastor and detect potential orphaned volumes:
598+
599+
```
600+
kubectl openebs -n openebs mayastor get volumes -o json | \
601+
jq -r --argjson pvs "$(kubectl get pv -o json)" \
602+
'.[] | select(.spec.uuid as $uuid | all($pvs.items[]; .metadata.name != ("pvc-" + $uuid))) | "Volume \(.spec.uuid) may be orphan"'
603+
```
604+
605+
**Sample Output**
606+
607+
```
608+
Volume 4bfe4c23-b32b-4e59-ac39-148646e4f844 may be orphan
609+
```
610+
611+
#### Deleting a Specific Volume
612+
613+
Once an orphaned volume is identified, it can be deleted by its UUID using:
614+
615+
```
616+
kubectl openebs -n openebs mayastor volume delete <volume-uuid>
617+
```
584618
585619
[Go to top](#top)
586620

docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/node-cordon.md renamed to docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/cordon-node.md

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,22 @@
11
---
2-
id: node-cordon
3-
title: Node Cordon
2+
id: cordon-node
3+
title: Cordon a Node
44
keywords:
55
- Node Cordon
6+
- Cordon Node
67
description: This guide explains about the Node Cordon feature.
78
---
89

10+
# Cordon a Node
11+
12+
## Overview
13+
914
Cordoning a node marks or taints the node as unschedulable. This prevents the scheduler from deploying new resources on that node. However, the resources that were deployed prior to cordoning off the node will remain intact.
1015

1116
This feature is in line with the node-cordon functionality of Kubernetes.
1217

18+
## Cordon a Node
19+
1320
To add a label and cordon a node, execute:
1421
**Command**
1522
```
@@ -29,13 +36,12 @@ To view the labels associated with a cordoned node, execute:
2936
kubectl-mayastor get cordon node <node_name>
3037
```
3138

32-
### How to uncordon a node?
39+
## Uncordon a Node
3340

3441
To make a node schedulable again, execute:
3542
**Command**
3643
```
3744
kubectl-mayastor uncordon node <node_name> <label>
3845
```
3946

40-
The above command allows the Kubernetes scheduler to deploy resources on the node.
41-
47+
The above command allows the Kubernetes scheduler to deploy resources on the node.

‎docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/cordon-pools.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
id: cordon-pools
3+
title: Cordon Pools
4+
keywords:
5+
- Cordon Replicated PV Mayastor Pools
6+
- Cordon and Uncordon Pools
7+
- Cordon Pools
8+
description: This guide explains how to cordon and uncordon pools.
9+
---
10+
11+
# Cordon Pools
12+
13+
## Overview
14+
15+
Pool Cordon allows you to temporarily prevent new replicas, snapshots, restores, or imports from being scheduled on a specific Replicated PV Mayastor pool.
16+
Use cordon during planned maintenance, hardware investigations, or controlled decommissioning. Existing data remains fully available and unaffected until explicitly migrated or removed.
17+
18+
## Requirements
19+
20+
You can configure the maximum pool size using the `maxExpansion` field in the DiskPool CR.
21+
22+
- Replicated PV Mayastor deployment with a version that supports pool cordoning
23+
24+
- `kubectl-mayastor` or `kubectl-openebs` plugin installed and configured with appropriate administrative access
25+
26+
## Cordon a Pool
27+
28+
When you cordon a pool, specify the resource types you want to block by including their flags. A flag’s presence sets that resource type to true (cordoned). If you omit a flag, that resource type remains uncordoned (false).
29+
30+
Cordon a pool to block new replicas and imports using `kubectl-openebs`. For Example: `kubectl-openebs mayastor`
31+
32+
**Cordon a Pool to Block New Replicas and Imports**
33+
34+
```
35+
kubectl-openebs mayastor cordon pool <pool-name> --replicas
36+
```
37+
38+
```
39+
kubectl-openebs mayastor cordon pool <pool-name> --replicas --imports
40+
```
41+
42+
**Flags**
43+
44+
- `--replicas` - Prevent new replicas from being created on the pool
45+
- `--snapshots` - Prevent new snapshots from being scheduled
46+
- `--restores` - Prevent new restore operations on the pool
47+
- `--imports` - Prevent pool import operations.
48+
49+
## Uncordon a Pool
50+
51+
When you uncordon a pool, you remove the scheduling restrictions and allow new resources to be created again. Use this when maintenance is complete or when you want the pool to resume normal operations.
52+
53+
**Uncordon a Pool and Re-enable All Resource Scheduling**
54+
55+
```
56+
kubectl-openebs mayastor uncordon pool <pool-name> --replicas --imports
57+
```
58+
59+
**Flags**
60+
61+
- The same flags apply as with cordon, letting you selectively enable scheduling for replicas, snapshots, restores, and imports.
62+
- By default, running uncordon pool without flags will remove all existing cordons, restoring full scheduling for the pool.
63+
64+
## Typical Use Cases
65+
66+
- Planned Maintenance: Isolate a pool before firmware upgrades or hardware replacement.
67+
- Capacity Management: Prevent new replicas on a pool nearing its operational threshold.
68+
- Controlled Decommissioning: Cordon, migrate replicas, and then retire the pool.
69+
70+
:::note
71+
- Cordoning blocks new resources only. It does not move or delete existing data.
72+
- Make sure enough other pools remain uncordoned to keep volumes healthy.
73+
- Pools stay cordoned across restarts until you explicitly uncordon them.
74+
:::

docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/node-drain.md renamed to docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/drain-node.md

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,21 @@
11
---
2-
id: node-drain
3-
title: Node Drain
2+
id: drain-node
3+
title: Drain a Node
44
keywords:
55
- Node Drain
6+
- Drain a Node
67
description: This guide explains about the Node Drain feature.
78
---
89

9-
The node drain functionality marks the node as unschedulable and then gracefully moves all the volume targets off the drained node.
10+
# Drain a Node
11+
12+
## Overview
13+
14+
The node drain functionality marks the node as unschedulable and then gracefully moves all the volume targets off the drained node.
15+
1016
This feature is in line with the [node drain functionality of Kubernetes](https://kubernetes.io/docs/tasks/administer-cluster/safely-drain-node/).
1117

18+
## Drain a Node
1219

1320
To start the drain operation, execute:
1421

@@ -26,6 +33,8 @@ To get the list of nodes on which the drain operation has been performed, execut
2633
kubectl-mayastor get drain nodes
2734
```
2835

36+
## Halt Drain
37+
2938
To halt the drain operation or to make the node schedulable again, execute:
3039

3140
**Command**

‎docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/kubectl-plugin.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,15 @@ keywords:
99
- Replicated PV Mayastor kubectl plugin
1010
description: This guide will help you to view and manage Replicated PV Mayastor resources such as nodes, pools, and volumes.
1111
---
12-
# Kubectl Plugin
12+
# Kubectl Mayastor Plugin
1313

1414
The **Mayastor kubectl plugin** can be used to view and manage Replicated PV Mayastor resources such as nodes, pools and volumes. It is also used for operations such as scaling the replica count of volumes.
1515

16-
## Install kubectl plugin
16+
## Install `kubectl Mayastor plugin`
1717

18-
- The Mayastor kubectl plugin is available for the Linux platform. The binary for the plugin can be found [here](https://github.com/mayadata-io/mayastor-control-plane/releases).
18+
- The Mayastor kubectl plugin is available for the Linux platform. You can download the binary for the plugin from the [releases page](https://github.com/mayadata-io/mayastor-control-plane/releases).
1919

20-
- Add the downloaded Mayastor kubectl plugin under $PATH.
20+
- After downloading, add the downloaded Mayastor kubectl plugin under $PATH.
2121

2222
To verify the installation, execute:
2323

‎docs/sidebars.js‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -461,7 +461,7 @@ module.exports = {
461461
{
462462
type: "doc",
463463
id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/kubectl-plugin",
464-
label: "Kubectl Plugin"
464+
label: "Kubectl Mayastor Plugin"
465465
},
466466
{
467467
type: "doc",
@@ -498,15 +498,21 @@ module.exports = {
498498
id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/monitoring",
499499
label: "Monitoring"
500500
},
501+
502+
{
503+
type: "doc",
504+
id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/cordon-node",
505+
label: "Cordon Node"
506+
},
501507
{
502508
type: "doc",
503-
id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/node-cordon",
504-
label: "Node Cordon"
509+
id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/drain-node",
510+
label: "Drain Node"
505511
},
506512
{
507513
type: "doc",
508-
id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/node-drain",
509-
label: "Node Drain"
514+
id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/cordon-pools",
515+
label: "Cordon Pools"
510516
},
511517
{
512518
type: "doc",

‎docs/versioned_docs/version-4.3.x/faqs/faqs.md‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -580,7 +580,41 @@ The supportability tool generates support bundles, which are used for debugging
580580
581581
### What happens when a PV with reclaim policy set to retain is deleted?
582582
583-
In Kubernetes, when a PVC is created with the reclaim policy set to 'Retain', the PV bound to this PVC is not deleted even if the PVC is deleted. One can manually delete the PV by issuing the command "kubectl delete pv", however the underlying storage resources could be left behind as the CSI volume provisioner (external provisioner) is not aware of this. To resolve this issue of dangling storage objects, Replicated Storage has introduced a PV garbage collector. This PV garbage collector is deployed as a part of the Replicated Storage CSI controller-plugin.
583+
In Kubernetes, when a PVC that is bound to a PV with the reclaim policy set to Retain is deleted, the corresponding PV is not automatically removed. You can delete the PV manually by running the following command:
584+
585+
```
586+
kubectl delete pv <pv-name>
587+
```
588+
589+
However, deleting the PV manually may leave the underlying storage resources orphaned because the CSI external provisioner is not notified of the PV deletion.
590+
591+
Earlier, Replicated Storage automatically handled such orphaned storage objects through a PV Garbage Collector (GC) that was deployed as part of the Replicated Storage CSI controller plugin.
592+
593+
Starting with the latest update, the orphaned PV Garbage Collector is disabled by default. Instead, Replicated Storage provides a mechanism to manually identify and delete unbound volumes using the `kubectl-openebs` plugin. This approach allows administrators to control when and how orphaned volumes are removed, ensuring safer and more predictable cleanup of unused storage resources.
594+
595+
#### Identifying Orphaned Volumes
596+
597+
You can use a shell command to compare existing PVs with volumes reported by Mayastor and detect potential orphaned volumes:
598+
599+
```
600+
kubectl openebs -n openebs mayastor get volumes -o json | \
601+
jq -r --argjson pvs "$(kubectl get pv -o json)" \
602+
'.[] | select(.spec.uuid as $uuid | all($pvs.items[]; .metadata.name != ("pvc-" + $uuid))) | "Volume \(.spec.uuid) may be orphan"'
603+
```
604+
605+
**Sample Output**
606+
607+
```
608+
Volume 4bfe4c23-b32b-4e59-ac39-148646e4f844 may be orphan
609+
```
610+
611+
#### Deleting a Specific Volume
612+
613+
Once an orphaned volume is identified, it can be deleted by its UUID using:
614+
615+
```
616+
kubectl openebs -n openebs mayastor volume delete <volume-uuid>
617+
```
584618
585619
[Go to top](#top)
586620

0 commit comments

Comments
 (0)