Skip to content

Commit 4fa4767

Browse files
author
Steven Smith
committed
Splits LVMS content into modules
1 parent 871c9f1 commit 4fa4767

16 files changed

+174
-143
lines changed

‎microshift_storage/persistent_storage_microshift/microshift-storage-plugin-overview.adoc

Lines changed: 7 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -1,147 +1,22 @@
11
:_content-type: ASSEMBLY
22
[id="microshift-storage-plugin-overview"]
3-
= MicroShift storage plug-in overview
3+
= MicroShift storage plugin overview
44
include::_attributes/common-attributes.adoc[]
55
:context: microshift-storage-plugin-overview
66

77
toc::[]
88

9-
{product-title} enables dynamic storage provisioning that is ready for immediate use with the logical volume manager storage (LVMS) Container Storage Interface (CSI) provider. The LVMS plugin is the Red Hat downstream version of TopoLVM, a CSI plug-in for managing LVM volumes for Kubernetes.
9+
{product-title} enables dynamic storage provisioning that is ready for immediate use with the logical volume manager storage (LVMS) Container Storage Interface (CSI) provider. The LVMS plugin is the Red Hat downstream version of TopoLVM, a CSI plugin for managing LVM volumes for Kubernetes.
1010

1111
LVMS provisions new logical volume management (LVM) logical volumes (LVs) for container workloads with appropriately configured persistent volume claims (PVC). Each PVC references a storage class that represents an LVM Volume Group (VG) on the host node. LVs are only provisioned for scheduled pods.
1212

13-
[id="lvms-deployment"]
14-
== LVMS Deployment
1513

16-
LVMS is automatically deployed on to the cluster in the `openshift-storage` namespace after {product-title} boots.
14+
include::modules/microshift-lvms-deployment.adoc[leveloffset=+1]
1715

18-
LVMS uses `StorageCapacity` tracking to ensure that pods with an LVMS PVC are not scheduled if the requested storage is greater than the volume group's remaining free storage. For more information about `StorageCapacity` tracking, see link:https://kubernetes.io/docs/concepts/storage/storage-capacity/[Storage Capacity].
16+
include::modules/microshift-lvms-configuring.adoc[leveloffset=+1]
1917

20-
[id="lvms-configuring"]
21-
== Configuring the LVMS
18+
include::modules/microshift-setting-lvms-path.adoc[leveloffset=+2]
2219

23-
{product-title} supports passing through a user's LVMS configuration and allows users to specify custom volume groups, thin volume provisioning parameters, and reserved unallocated volume group space. The LVMS configuration file can be edited at any time. You must restart {product-title} to deploy configuration changes.
24-
25-
The following `config.yaml` file shows a basic LVMS configuration:
26-
27-
.LVMS YAML configuration
28-
[source,yaml]
29-
----
30-
socket-name: <1>
31-
device-classes: <2>
32-
- name: <3>
33-
volume-group: <4>
34-
spare-gb: <5>
35-
default: <6>
36-
- name: hdd
37-
volume-group: hdd-vg
38-
spare-gb: 10
39-
- name: striped
40-
volume-group: multi-pv-vg
41-
spare-gb: 10
42-
stripe: <7>
43-
stripe-size: <8>
44-
- name: raid
45-
volume-group: raid-vg
46-
lvcreate-options: <9>
47-
- --type=raid1
48-
----
49-
<1> String. The UNIX domain socket endpoint of gRPC. Defaults to `/run/topolvm/lvmd.sock`.
50-
<2> `map[string]DeviceClass`. The `device-class` settings.
51-
<3> String. The name of the `device-class`.
52-
<4> String. The group where the `device-class` creates the logical volumes.
53-
<5> unit64. Storage capacity in GiB to be spared. Defaults to `10`.
54-
<6> Boolean. Indicates that the `device-class` is used by default. Defaults to `false`.
55-
<7> unit. The number of stripes in the logical volume.
56-
<8> String. The amount of data that is written to one device before moving to the next device.
57-
<9> String. Extra arguments to pas `lvcreate`, for example, `[--type=raid1"`].
58-
+
59-
[NOTE]
60-
====
61-
Striping can be configured by using the dedicated options (`stripe` and `stripe-size`) and `lvcreate-options`. Either option can be used, but they cannot be used together. Using `stripe` and `stripe-size` with `lvcreate-options` leads to duplicate arguments to `lvcreate`. You should never set `lvcreate-options: ["--stripes=n"]` and `stripe: n` at the same time. You can, however, use both, when `lvcreate-options` is not used for striping. For example:
62-
63-
[source,yaml]
64-
----
65-
stripe: 2
66-
lvcreate-options: ["--mirrors=1"]
67-
----
68-
====
69-
70-
[id="setting-lvms-path"]
71-
=== Setting the LVMS path
72-
73-
The `config.yaml` file for the LMVS should be written to the same directory as the MicroShift `config.yaml` file. If a MicroShift `config.yaml` file does not exist, MicroShift will create an LVMS YAML and automatically populate the configuration fields with the default settings. The following paths are checked for the `config.yaml` file, depending on which user runs MicroShift:
74-
75-
.LVMS paths
76-
[options="header",cols="1,3"]
77-
|===
78-
| MicroShift user | Configuration directory
79-
|Global administrator | `/etc/microshift/lvmd.yaml`
80-
|===
81-
82-
[id="lvms-system-requirements"]
83-
== LVMS system requirements
84-
85-
{product-title}'s LVMS requires the following system specifications.
86-
87-
[id="lvms-volume-group-name"]
88-
=== Volume Group Name
89-
90-
The default integration of LVMS assumes a volume group named `rhel`. Prior to launching, the `lvmd.yaml` configuration file must specify an existing volume group on the node with sufficient capacity for workload storage. If the volume group does not exist, the node controller will fail to start and enter a `CrashLoopBackoff` state.
91-
92-
[id="lvms-volume-size-increments"]
93-
=== Volume size increments
94-
95-
The LVMS provisions storage in increments of 1 GB. Storage requests are rounded up to the nearest gigabyte (GB). When a volume group's capacity is less than 1 GB, the `PersistentVolumeClaim` registers a `ProvisioningFailed` event, for example:
96-
97-
[source,terminal]
98-
----
99-
Warning ProvisioningFailed 3s (x2 over 5s) topolvm.cybozu.com_topolvm-controller-858c78d96c-xttzp_0fa83aef-2070-4ae2-bcb9-163f818dcd9f failed to provision volume with
100-
StorageClass "topolvm-provisioner": rpc error: code = ResourceExhausted desc = no enough space left on VG: free=(BYTES_INT), requested=(BYTES_INT)
101-
----
102-
103-
[id=using-lvms]
104-
== Using the LVMS
105-
106-
The LVMS `StorageClass` is deployed with a default `StorageClass`. Any `PersistentVolumeClaim` objects without a `.spec.storageClassName` defined automatically has a `PersistentVolume` provisioned from the default `StorageClass`.
107-
108-
Use the following procedure to provision and mount a logical volume to a pod.
109-
110-
.Procedure
111-
112-
The following example demonstrates how to provision and mount a logical volume to a pod.
113-
114-
[source,terminal]
115-
----
116-
$ cat <<'EOF' | oc apply -f -
117-
kind: PersistentVolumeClaim
118-
apiVersion: v1
119-
metadata:
120-
name: my-lv-pvc
121-
spec:
122-
accessModes:
123-
- ReadWriteOnce
124-
resources:
125-
requests:
126-
storage: 1G
127-
---
128-
apiVersion: v1
129-
kind: Pod
130-
metadata:
131-
name: my-pod
132-
spec:
133-
containers:
134-
- name: nginx
135-
image: nginx
136-
command: ["/usr/bin/sh", "-c"]
137-
args: ["sleep", "1h"]
138-
volumeMounts:
139-
- mountPath: /mnt
140-
name: my-volume
141-
volumes:
142-
- name: my-volume
143-
persistentVolumeClaim:
144-
claimName: my-lv-pvc
145-
EOF
146-
----
20+
include::modules/microshift-lvms-system-requirements.adoc[leveloffset=+1]
14721

22+
include::modules/microshift-using-lvms.adoc[leveloffset=+1]

‎migrating_from_ocp_3_to_4/planning-migration-3-4.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ For more information, see xref:../storage/persistent_storage/persistent-storage-
8989
[discrete]
9090
==== FlexVolume persistent storage
9191

92-
The FlexVolume plug-in location changed from {product-title} 3.11. The new location in {product-title} {product-version} is `/etc/kubernetes/kubelet-plugins/volume/exec`. Attachable FlexVolume plug-ins are no longer supported.
92+
The FlexVolume plugin location changed from {product-title} 3.11. The new location in {product-title} {product-version} is `/etc/kubernetes/kubelet-plugins/volume/exec`. Attachable FlexVolume plugins are no longer supported.
9393

9494
For more information, see xref:../storage/persistent_storage/persistent-storage-flexvolume.adoc#persistent-storage-using-flexvolume[Persistent storage using FlexVolume].
9595

‎modules/dynamic-provisioning-about.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,4 +25,4 @@ having any knowledge of the underlying infrastructure.
2525
Many storage types are available for use as persistent volumes in
2626
{product-title}. While all of them can be statically provisioned by an
2727
administrator, some types of storage are created dynamically using the
28-
built-in provider and plug-in APIs.
28+
built-in provider and plugin APIs.

‎modules/dynamic-provisioning-defining-storage-class.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,4 +23,4 @@ storage class.
2323
endif::microshift[]
2424

2525
The following sections describe the basic definition for a
26-
`StorageClass` object and specific examples for each of the supported plug-in types.
26+
`StorageClass` object and specific examples for each of the supported plugin types.

‎modules/dynamic-provisioning-storage-class-definition.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,4 +34,4 @@ parameters: <6>
3434
<4> (optional) Annotations for the storage class.
3535
<5> (required) The type of provisioner associated with this storage class.
3636
<6> (optional) The parameters required for the specific provisioner, this
37-
will change from plug-in to plug-in.
37+
will change from plugin to plug-iin.

‎modules/microshift-lvms-configuring.adoc

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift_networking/microshift-storage-plugin-overview.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="lvms-configuring"]
7+
= Configuring the LVMS
8+
9+
{product-title} supports passing through a user's LVMS configuration and allows users to specify custom volume groups, thin volume provisioning parameters, and reserved unallocated volume group space. The LVMS configuration file can be edited at any time. You must restart {product-title} to deploy configuration changes.
10+
11+
The following `config.yaml` file shows a basic LVMS configuration:
12+
13+
.LVMS YAML configuration
14+
[source,yaml]
15+
----
16+
socket-name: <1>
17+
device-classes: <2>
18+
- name: <3>
19+
volume-group: <4>
20+
spare-gb: <5>
21+
default: <6>
22+
- name: hdd
23+
volume-group: hdd-vg
24+
spare-gb: 10
25+
- name: striped
26+
volume-group: multi-pv-vg
27+
spare-gb: 10
28+
stripe: <7>
29+
stripe-size: <8>
30+
- name: raid
31+
volume-group: raid-vg
32+
lvcreate-options: <9>
33+
- --type=raid1
34+
----
35+
<1> String. The UNIX domain socket endpoint of gRPC. Defaults to `/run/topolvm/lvmd.sock`.
36+
<2> `map[string]DeviceClass`. The `device-class` settings.
37+
<3> String. The name of the `device-class`.
38+
<4> String. The group where the `device-class` creates the logical volumes.
39+
<5> unit64. Storage capacity in GiB to be spared. Defaults to `10`.
40+
<6> Boolean. Indicates that the `device-class` is used by default. Defaults to `false`.
41+
<7> unit. The number of stripes in the logical volume.
42+
<8> String. The amount of data that is written to one device before moving to the next device.
43+
<9> String. Extra arguments to pas `lvcreate`, for example, `[--type=raid1"`].
44+
+
45+
[NOTE]
46+
====
47+
Striping can be configured by using the dedicated options (`stripe` and `stripe-size`) and `lvcreate-options`. Either option can be used, but they cannot be used together. Using `stripe` and `stripe-size` with `lvcreate-options` leads to duplicate arguments to `lvcreate`. You should never set `lvcreate-options: ["--stripes=n"]` and `stripe: n` at the same time. You can, however, use both, when `lvcreate-options` is not used for striping. For example:
48+
49+
[source,yaml]
50+
----
51+
stripe: 2
52+
lvcreate-options: ["--mirrors=1"]
53+
----
54+
====

‎modules/microshift-lvms-deployment.adoc

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift_networking/microshift-storage-plugin-overview.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="lvms-deployment"]
7+
= LVMS Deployment
8+
9+
LVMS is automatically deployed on to the cluster in the `openshift-storage` namespace after {product-title} boots.
10+
11+
LVMS uses `StorageCapacity` tracking to ensure that pods with an LVMS PVC are not scheduled if the requested storage is greater than the volume group's remaining free storage. For more information about `StorageCapacity` tracking, see link:https://kubernetes.io/docs/concepts/storage/storage-capacity/[Storage Capacity].

‎modules/microshift-lvms-system-requirements.adoc

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift_networking/microshift-storage-plugin-overview.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="lvms-system-requirements"]
7+
= LVMS system requirements
8+
9+
{product-title}'s LVMS requires the following system specifications.
10+
11+
[id="lvms-volume-group-name"]
12+
== Volume Group Name
13+
14+
The default integration of LVMS assumes a volume group named `rhel`. Prior to launching, the `lvmd.yaml` configuration file must specify an existing volume group on the node with sufficient capacity for workload storage. If the volume group does not exist, the node controller will fail to start and enter a `CrashLoopBackoff` state.
15+
16+
[id="lvms-volume-size-increments"]
17+
== Volume size increments
18+
19+
The LVMS provisions storage in increments of 1 GB. Storage requests are rounded up to the nearest gigabyte (GB). When a volume group's capacity is less than 1 GB, the `PersistentVolumeClaim` registers a `ProvisioningFailed` event, for example:
20+
21+
[source,terminal]
22+
----
23+
Warning ProvisioningFailed 3s (x2 over 5s) topolvm.cybozu.com_topolvm-controller-858c78d96c-xttzp_0fa83aef-2070-4ae2-bcb9-163f818dcd9f failed to provision volume with
24+
StorageClass "topolvm-provisioner": rpc error: code = ResourceExhausted desc = no enough space left on VG: free=(BYTES_INT), requested=(BYTES_INT)
25+
----

‎modules/microshift-setting-lvms-path.adoc

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift_networking/microshift-storage-plugin-overview.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="setting-lvms-path"]
7+
= Setting the LVMS path
8+
9+
The `config.yaml` file for the LMVS should be written to the same directory as the MicroShift `config.yaml` file. If a MicroShift `config.yaml` file does not exist, MicroShift will create an LVMS YAML and automatically populate the configuration fields with the default settings. The following paths are checked for the `config.yaml` file, depending on which user runs MicroShift:
10+
11+
.LVMS paths
12+
[options="header",cols="1,3"]
13+
|===
14+
| MicroShift user | Configuration directory
15+
|Global administrator | `/etc/microshift/lvmd.yaml`
16+
|===

‎modules/microshift-using-lvms.adoc

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift_networking/microshift-storage-plugin-overview.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="using-lvms"]
7+
= Using the LVMS
8+
9+
The LVMS `StorageClass` is deployed with a default `StorageClass`. Any `PersistentVolumeClaim` objects without a `.spec.storageClassName` defined automatically has a `PersistentVolume` provisioned from the default `StorageClass`.
10+
11+
Use the following procedure to provision and mount a logical volume to a pod.
12+
13+
.Procedure
14+
15+
* Enter the following command to provision and mount a logical volume to a pod:
16+
+
17+
[source,terminal]
18+
----
19+
$ cat <<'EOF' | oc apply -f -
20+
kind: PersistentVolumeClaim
21+
apiVersion: v1
22+
metadata:
23+
name: my-lv-pvc
24+
spec:
25+
accessModes:
26+
- ReadWriteOnce
27+
resources:
28+
requests:
29+
storage: 1G
30+
---
31+
apiVersion: v1
32+
kind: Pod
33+
metadata:
34+
name: my-pod
35+
spec:
36+
containers:
37+
- name: nginx
38+
image: nginx
39+
command: ["/usr/bin/sh", "-c"]
40+
args: ["sleep", "1h"]
41+
volumeMounts:
42+
- mountPath: /mnt
43+
name: my-volume
44+
volumes:
45+
- name: my-volume
46+
persistentVolumeClaim:
47+
claimName: my-lv-pvc
48+
EOF
49+
----
50+

0 commit comments

Comments
 (0)