Skip to content

Commit b23a3fe

Browse files
authored
Merge pull request #70232 from sr1kar99/doc-improv-creating-lvms-cluster
OCPBUGS#27147: Doc improvements in "Creating a Logical Volume Manager cluster on a single-node OpenShift worker node" proc
2 parents f531efe + b256a5c commit b23a3fe

7 files changed

+393
-329
lines changed

modules/lvms-about-lvmcluster-cr.adoc

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
// Module included in the following assemblies:
2+
//
3+
// storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="about-lvmcluster_{context}"]
7+
= About the LVMCluster custom resource
8+
9+
After you have installed {lvms}, you must create an `LVMCluster` custom resource (CR) on a worker node.
10+
11+
You can configure the `LVMCluster` CR to perform the following actions:
12+
13+
* Create LVM volume groups that you can use to provision persistent volume claims (PVCs).
14+
* Configure a list of devices that you want to add to the LVM volume groups.
15+
* Configure the requirements to select the nodes on which you want to create an LVM volume group, and the thin pool configuration for the volume group.
16+
* Force wipe the selected devices.
17+
18+
You can create an `LVMCluster` CR using the OpenShift CLI (`oc`) or the {product-title} web console.
19+
20+
include::snippets/lvms-creating-lvmcluster.adoc[]
21+
22+
[discrete]
23+
== LVMCluster custom resource configuration
24+
25+
The `LVMCluster` CR fields are described in the following table:
26+
27+
.`LVMCluster` CR fields
28+
[cols=".^2,.^2,.^6a",options="header"]
29+
|====
30+
31+
|Field|Type|Description
32+
33+
|`spec.storage.deviceClasses`
34+
|`array`
35+
|Contains the configuration to assign the local storage devices to the LVM volume groups.
36+
37+
To create multiple device storage classes, create a device class for each storage class.
38+
39+
After creating an `LVMCluster` CR, if you add or remove a device class, the update reflects in the `LVMCluster` CR only after deleting and recreating the `TopoLVM-Node` pod.
40+
41+
|`deviceClasses.name`
42+
|`string`
43+
|Specify a name for the LVM volume group (VG).
44+
45+
If this field is set to the name of a VG from the previous {lvms} installation, {lvms} recreates the resources related to that volume group in the current {lvms} installation.
46+
47+
You can only recover the VGs but not the logical volume associated with the VG.
48+
49+
[IMPORTANT]
50+
====
51+
Before recovering the VGs from the previous {lvms} installation, ensure that the following conditions are met:
52+
53+
* VGs must not be corrupted.
54+
* VGs must have the `lvms` tag. For more information on adding tags to LVMS objects, see link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/configuring_and_managing_logical_volumes/grouping-lvm-objects-with-tags_configuring-and-managing-logical-volumes#doc-wrapper[Grouping LVM objects with tags].
55+
====
56+
57+
|`deviceClasses.fstype`
58+
|`string`
59+
|Set this field to `ext4` or `xfs`. By default, this field is set to `xfs`.
60+
61+
|`deviceClasses.default`
62+
|`boolean`
63+
|Set this field to `true` to indicate that a device class is the default. Otherwise, you can set it to `false`. You can only configure a single default device class.
64+
65+
|`deviceClasses.nodeSelector`
66+
|`object`
67+
|Contains the configuration to choose the nodes on which you want to create the LVM volume group. If this field is empty, all nodes without no-schedule taints are considered.
68+
69+
[NOTE]
70+
====
71+
On the control-plane node, {lvms} detects and uses the additional worker nodes when the new nodes become active in the cluster.
72+
====
73+
74+
|`nodeSelector.nodeSelectorTerms`
75+
|`array`
76+
|Configure the requirements that are used to select the node.
77+
78+
|`deviceClasses.deviceSelector`
79+
|`object`
80+
|Contains the configuration to specify the paths to the devices that you want to add to the LVM volume group, and force wipe the devices that are added to the LVM volume group.
81+
82+
You can specify the device paths in the `paths` field, the `optionalPaths` field, or both. If you do not specify the device paths in both `paths` and `optionalPaths`, {lvms} adds the supported unused devices to the LVM volume group.
83+
84+
[IMPORTANT]
85+
====
86+
After a device is added to the LVM volume group, it cannot be removed.
87+
====
88+
89+
{lvms} adds the devices to the LVM volume group only if the following conditions are met:
90+
91+
* The device path exists.
92+
93+
* The device is supported by {lvms}.
94+
95+
[NOTE]
96+
====
97+
The devices that you want to add to the volume group must be supported by {lvms}. For information about unsupported devices, see _Devices not supported by {lvms}_ in _Additional resources_.
98+
====
99+
100+
You can also add the path to the RAID arrays to integrate the RAID arrays with {lvms}. For more information, see _Integrating RAID arrays with {lvms}_ in _Additional resources_.
101+
102+
|`deviceSelector.paths`
103+
|`array`
104+
|Specify the device paths.
105+
106+
If the device path specified in this field does not exist, or the device is not supported by {lvms}, the `LVMCluster` CR moves to the `Failed` state.
107+
108+
|`deviceSelector.optionalPaths`
109+
|`array`
110+
| Specify the optional device paths.
111+
112+
If the device path specified in this field does not exist, or the device is not supported by {lvms}, {lvms} ignores the device without causing an error.
113+
114+
|`deviceSelector.
115+
forceWipeDevicesAndDestroyAllData`
116+
|`boolean`
117+
|To force wipe the selected devices, set this field to `true`. By default, this field is set to `false`.
118+
119+
[IMPORTANT]
120+
====
121+
Wiping the device can lead to inconsistencies in data integrity if any of the following conditions are met:
122+
123+
* The device is being used as swap space.
124+
* The device is part of a RAID array.
125+
* The device is mounted.
126+
127+
If any of these conditions are true, do not force wipe the disk. Instead, you must manually wipe the disk.
128+
====
129+
130+
[WARNING]
131+
====
132+
If this field is set to `true`, {lvms} wipes all previous data on the devices. Use this feature with caution.
133+
====
134+
135+
|`deviceClasses.thinPoolConfig`
136+
|`object`
137+
|Contains the configuration to create a thin pool in the LVM volume group.
138+
139+
|`thinPoolConfig.name`
140+
|`string`
141+
|Specify a name for the thin pool.
142+
143+
|`thinPoolConfig.sizePercent`
144+
|`integer`
145+
|Specify the percentage of space in the LVM volume group for creating the thin pool.
146+
147+
By default, this field is set to 90. The minimum value that you can set is 10, and the maximum value is 90.
148+
149+
|`thinPoolConfig.overprovisionRatio`
150+
|`integer`
151+
|Specify a factor by which you can provision additional storage based on the available storage in the thin pool.
152+
153+
For example, if this field is set to 10, you can provision up to 10 times the amount of available storage in the thin pool.
154+
155+
To disable over-provisioning, set this field to 1.
156+
157+
|====
158+
159+
Upon creating the `LVMCluster` CR, {lvms} creates a storage class and volume snapshot class for each device class.
160+
161+
[NOTE]
162+
====
163+
{lvms} configures the name of the storage class and volume snapshot class in the format `lvms-<device-class-name>`. Where, `<device-class-name>` is the value of the `deviceClasses.name` field in the `LVMCluster` CR. For example, if the `deviceClasses.name` field is set to vg1, the name of the storage class and volume snapshot class is `lvms-vg1`.
164+
165+
To get the list of storage classes, run the following command:
166+
[source,terminal]
167+
----
168+
$ oc get storageclass
169+
----
170+
171+
To get the list of volume snapshot classes, run the following command:
172+
[source,terminal]
173+
----
174+
$ oc get volumesnapshotclass
175+
----
176+
====
177+
178+
Upon creating the `LVMCluster` CR, {lvms} creates the following system-managed CRs:
179+
180+
* `LVMVolumeGroup`: This CR is a specific type of persistent volume (PV) that is backed by an LVM volume group. It tracks the individual volume groups across multiple nodes.
181+
* `LVMVolumeGroupNodeStatus`: This CR tracks the status of the volume groups on a node.

0 commit comments

Comments
 (0)