Skip to content

Commit 41ff8fa

Browse files
tomponlinetomponline
authored
Merge pull request canonical#12930 from ru-fu/powerflex-doc-updates
Doc: small fixed to Powerflex documentation
2 parents df9cb8c + bc20d86 commit 41ff8fa

File tree

7 files changed

+68
-44
lines changed

7 files changed

+68
-44
lines changed

‎doc/.wordlist.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -189,6 +189,7 @@ Pongo
189189
POSIX
190190
PowerFlex
191191
pre
192+
prepended
192193
preseed
193194
proxied
194195
proxying

‎doc/config_options.txt

Lines changed: 24 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2521,15 +2521,16 @@ Specify either a cron expression (`<minute> <hour> <dom> <month> <dow>`), a comm
25212521
<!-- config group storage-powerflex-pool-conf start -->
25222522
```{config:option} powerflex.clone_copy storage-powerflex-pool-conf
25232523
:defaultdesc: "`true`"
2524-
:shortdesc: "Make a non-sparse copy when creating a snapshot of instances or custom volumes (see the [limitations](storage-powerflex-limitations))"
2524+
:shortdesc: "Whether to use non-sparse copies for snapshots"
25252525
:type: "bool"
2526-
2526+
If this option is set to `true`, PowerFlex makes a non-sparse copy when creating a snapshot of an instance or custom volume.
2527+
See {ref}`storage-powerflex-limitations` for more information.
25272528
```
25282529

25292530
```{config:option} powerflex.domain storage-powerflex-pool-conf
2530-
:shortdesc: "Name of the PowerFlex protection domain (only required if `powerflex.pool` is specified using its name)"
2531+
:shortdesc: "Name of the PowerFlex protection domain"
25312532
:type: "string"
2532-
2533+
This option is required only if {config:option}`storage-powerflex-pool-conf:powerflex.pool` is specified using its name.
25332534
```
25342535

25352536
```{config:option} powerflex.gateway storage-powerflex-pool-conf
@@ -2547,15 +2548,16 @@ Specify either a cron expression (`<minute> <hour> <dom> <month> <dow>`), a comm
25472548

25482549
```{config:option} powerflex.mode storage-powerflex-pool-conf
25492550
:defaultdesc: "the discovered mode"
2550-
:shortdesc: "Gets discovered automatically if the system provides the necessary kernel modules; currently, only `nvme` is supported"
2551+
:shortdesc: "How volumes are mapped to the local server"
25512552
:type: "string"
2552-
2553+
The mode gets discovered automatically if the system provides the necessary kernel modules.
2554+
Currently, only `nvme` is supported.
25532555
```
25542556

25552557
```{config:option} powerflex.pool storage-powerflex-pool-conf
2556-
:shortdesc: "ID of the PowerFlex storage pool (if you want to specify the storage pool via its name, also set `powerflex.domain`)"
2558+
:shortdesc: "ID of the PowerFlex storage pool"
25572559
:type: "string"
2558-
2560+
If you want to specify the storage pool via its name, also set {config:option}`storage-powerflex-pool-conf:powerflex.domain`.
25592561
```
25602562

25612563
```{config:option} powerflex.sdt storage-powerflex-pool-conf
@@ -2595,9 +2597,10 @@ to be placed on the socket I/O.
25952597

25962598
```{config:option} volume.size storage-powerflex-pool-conf
25972599
:defaultdesc: "`8GiB`"
2598-
:shortdesc: "Size/quota of the storage volume in multiples of 8GiB"
2600+
:shortdesc: "Size/quota of the storage volume"
25992601
:type: "string"
2600-
2602+
The size must be in multiples of 8 GiB.
2603+
See {ref}`storage-powerflex-limitations` for more information.
26012604
```
26022605

26032606
<!-- config group storage-powerflex-pool-conf end -->
@@ -2621,7 +2624,7 @@ If not set, `ext4` is assumed.
26212624

26222625
```{config:option} block.type storage-powerflex-volume-conf
26232626
:defaultdesc: "same as `volume.block.type` or `thick`"
2624-
:shortdesc: "Create a `thin` or `thick` provisioned volume"
2627+
:shortdesc: "Whether to create a `thin` or `thick` provisioned volume"
26252628
:type: "string"
26262629

26272630
```
@@ -2644,9 +2647,10 @@ Enabling this option allows attaching the volume to multiple isolated instances.
26442647

26452648
```{config:option} size storage-powerflex-volume-conf
26462649
:defaultdesc: "same as `volume.size`"
2647-
:shortdesc: "Size/quota of the storage volume in multiples of 8GiB"
2650+
:shortdesc: "Size/quota of the storage volume"
26482651
:type: "string"
2649-
2652+
The size must be in multiples of 8 GiB.
2653+
See {ref}`storage-powerflex-limitations` for more information.
26502654
```
26512655

26522656
```{config:option} snapshots.expiry storage-powerflex-volume-conf
@@ -2684,6 +2688,13 @@ This number is then incremented by one for the new name.
26842688
Specify either a cron expression (`<minute> <hour> <dom> <month> <dow>`), a comma-separated list of schedule aliases (`@hourly`, `@daily`, `@midnight`, `@weekly`, `@monthly`, `@annually`, `@yearly`), or leave empty to disable automatic snapshots (the default).
26852689
```
26862690

2691+
```{config:option} volatile.uuid storage-powerflex-volume-conf
2692+
:defaultdesc: "random UUID"
2693+
:shortdesc: "The volume's UUID"
2694+
:type: "string"
2695+
2696+
```
2697+
26872698
<!-- config group storage-powerflex-volume-conf end -->
26882699
<!-- config group storage-zfs-bucket-conf start -->
26892700
```{config:option} size storage-zfs-bucket-conf

‎doc/reference/storage_powerflex.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -48,10 +48,10 @@ Both volumes and their snapshots get added as standalone NVMe disks to the LXD h
4848
### Volume names
4949

5050
Due to a [limitation](storage-powerflex-limitations) in PowerFlex, volume names cannot exceed 31 characters.
51-
Therefore the driver is using the volume's `volatile.uuid` to generated a fixed length volume name.
52-
A UUID of `5a2504b0-6a6c-4849-8ee7-ddb0b674fd14` will render to the base64 encoded string `WiUEsGpsSEmO592wtnT9FA==`.
51+
Therefore the driver is using the volume's {config:option}`storage-powerflex-volume-conf:volatile.uuid` to generate a fixed length volume name.
52+
A UUID of `5a2504b0-6a6c-4849-8ee7-ddb0b674fd14` will render to the base64-encoded string `WiUEsGpsSEmO592wtnT9FA==`.
5353

54-
In order to be able to identify the volume types and snapshots, special identifiers are appended to the volume names:
54+
To be able to identify the volume types and snapshots, special identifiers are prepended to the volume names:
5555

5656
Type | Identifier | Example
5757
:-- | :--- | :----------
@@ -93,7 +93,7 @@ Sharing custom volumes between instances
9393
Sharing the PowerFlex storage pool between installations
9494
: Sharing the same PowerFlex storage pool between multiple LXD installations is not supported.
9595

96-
Recover PowerFlex storage pools
96+
Recovering PowerFlex storage pools
9797
: Recovery of PowerFlex storage pools using `lxd recover` is not supported.
9898

9999
## Configuration options

‎lxd/metadata/configuration.json

Lines changed: 21 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2742,15 +2742,15 @@
27422742
{
27432743
"powerflex.clone_copy": {
27442744
"defaultdesc": "`true`",
2745-
"longdesc": "",
2746-
"shortdesc": "Make a non-sparse copy when creating a snapshot of instances or custom volumes (see the [limitations](storage-powerflex-limitations))",
2745+
"longdesc": "If this option is set to `true`, PowerFlex makes a non-sparse copy when creating a snapshot of an instance or custom volume.\nSee {ref}`storage-powerflex-limitations` for more information.",
2746+
"shortdesc": "Whether to use non-sparse copies for snapshots",
27472747
"type": "bool"
27482748
}
27492749
},
27502750
{
27512751
"powerflex.domain": {
2752-
"longdesc": "",
2753-
"shortdesc": "Name of the PowerFlex protection domain (only required if `powerflex.pool` is specified using its name)",
2752+
"longdesc": "This option is required only if {config:option}`storage-powerflex-pool-conf:powerflex.pool` is specified using its name.",
2753+
"shortdesc": "Name of the PowerFlex protection domain",
27542754
"type": "string"
27552755
}
27562756
},
@@ -2772,15 +2772,15 @@
27722772
{
27732773
"powerflex.mode": {
27742774
"defaultdesc": "the discovered mode",
2775-
"longdesc": "",
2776-
"shortdesc": "Gets discovered automatically if the system provides the necessary kernel modules; currently, only `nvme` is supported",
2775+
"longdesc": "The mode gets discovered automatically if the system provides the necessary kernel modules.\nCurrently, only `nvme` is supported.",
2776+
"shortdesc": "How volumes are mapped to the local server",
27772777
"type": "string"
27782778
}
27792779
},
27802780
{
27812781
"powerflex.pool": {
2782-
"longdesc": "",
2783-
"shortdesc": "ID of the PowerFlex storage pool (if you want to specify the storage pool via its name, also set `powerflex.domain`)",
2782+
"longdesc": "If you want to specify the storage pool via its name, also set {config:option}`storage-powerflex-pool-conf:powerflex.domain`.",
2783+
"shortdesc": "ID of the PowerFlex storage pool",
27842784
"type": "string"
27852785
}
27862786
},
@@ -2826,8 +2826,8 @@
28262826
{
28272827
"volume.size": {
28282828
"defaultdesc": "`8GiB`",
2829-
"longdesc": "",
2830-
"shortdesc": "Size/quota of the storage volume in multiples of 8GiB",
2829+
"longdesc": "The size must be in multiples of 8 GiB.\nSee {ref}`storage-powerflex-limitations` for more information.",
2830+
"shortdesc": "Size/quota of the storage volume",
28312831
"type": "string"
28322832
}
28332833
}
@@ -2857,7 +2857,7 @@
28572857
"block.type": {
28582858
"defaultdesc": "same as `volume.block.type` or `thick`",
28592859
"longdesc": "",
2860-
"shortdesc": "Create a `thin` or `thick` provisioned volume",
2860+
"shortdesc": "Whether to create a `thin` or `thick` provisioned volume",
28612861
"type": "string"
28622862
}
28632863
},
@@ -2882,8 +2882,8 @@
28822882
{
28832883
"size": {
28842884
"defaultdesc": "same as `volume.size`",
2885-
"longdesc": "",
2886-
"shortdesc": "Size/quota of the storage volume in multiples of 8GiB",
2885+
"longdesc": "The size must be in multiples of 8 GiB.\nSee {ref}`storage-powerflex-limitations` for more information.",
2886+
"shortdesc": "Size/quota of the storage volume",
28872887
"type": "string"
28882888
}
28892889
},
@@ -2913,6 +2913,14 @@
29132913
"shortdesc": "Schedule for automatic volume snapshots",
29142914
"type": "string"
29152915
}
2916+
},
2917+
{
2918+
"volatile.uuid": {
2919+
"defaultdesc": "random UUID",
2920+
"longdesc": "",
2921+
"shortdesc": "The volume's UUID",
2922+
"type": "string"
2923+
}
29162924
}
29172925
]
29182926
}

‎lxd/storage/drivers/driver_powerflex.go

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -204,23 +204,24 @@ func (d *powerflex) Validate(config map[string]string) error {
204204
// shortdesc: Whether to verify the PowerFlex Gateway's certificate
205205
"powerflex.gateway.verify": validate.Optional(validate.IsBool),
206206
// lxdmeta:generate(entities=storage-powerflex; group=pool-conf; key=powerflex.pool)
207-
//
207+
// If you want to specify the storage pool via its name, also set {config:option}`storage-powerflex-pool-conf:powerflex.domain`.
208208
// ---
209209
// type: string
210-
// shortdesc: ID of the PowerFlex storage pool (if you want to specify the storage pool via its name, also set `powerflex.domain`)
210+
// shortdesc: ID of the PowerFlex storage pool
211211
"powerflex.pool": validate.IsAny,
212212
// lxdmeta:generate(entities=storage-powerflex; group=pool-conf; key=powerflex.domain)
213-
//
213+
// This option is required only if {config:option}`storage-powerflex-pool-conf:powerflex.pool` is specified using its name.
214214
// ---
215215
// type: string
216-
// shortdesc: Name of the PowerFlex protection domain (only required if `powerflex.pool` is specified using its name)
216+
// shortdesc: Name of the PowerFlex protection domain
217217
"powerflex.domain": validate.Optional(validate.IsAny),
218218
// lxdmeta:generate(entities=storage-powerflex; group=pool-conf; key=powerflex.mode)
219-
//
219+
// The mode gets discovered automatically if the system provides the necessary kernel modules.
220+
// Currently, only `nvme` is supported.
220221
// ---
221222
// type: string
222223
// defaultdesc: the discovered mode
223-
// shortdesc: Gets discovered automatically if the system provides the necessary kernel modules; currently, only `nvme` is supported
224+
// shortdesc: How volumes are mapped to the local server
224225
"powerflex.mode": validate.Optional(validate.IsOneOf("nvme")),
225226
// lxdmeta:generate(entities=storage-powerflex; group=pool-conf; key=powerflex.sdt)
226227
//
@@ -230,18 +231,20 @@ func (d *powerflex) Validate(config map[string]string) error {
230231
// shortdesc: PowerFlex NVMe/TCP SDT
231232
"powerflex.sdt": validate.Optional(validate.IsNetworkAddress),
232233
// lxdmeta:generate(entities=storage-powerflex; group=pool-conf; key=powerflex.clone_copy)
233-
//
234+
// If this option is set to `true`, PowerFlex makes a non-sparse copy when creating a snapshot of an instance or custom volume.
235+
// See {ref}`storage-powerflex-limitations` for more information.
234236
// ---
235237
// type: bool
236238
// defaultdesc: `true`
237-
// shortdesc: Make a non-sparse copy when creating a snapshot of instances or custom volumes (see the [limitations](storage-powerflex-limitations))
239+
// shortdesc: Whether to use non-sparse copies for snapshots
238240
"powerflex.clone_copy": validate.Optional(validate.IsBool),
239241
// lxdmeta:generate(entities=storage-powerflex; group=pool-conf; key=volume.size)
240-
//
242+
// The size must be in multiples of 8 GiB.
243+
// See {ref}`storage-powerflex-limitations` for more information.
241244
// ---
242245
// type: string
243246
// defaultdesc: `8GiB`
244-
// shortdesc: Size/quota of the storage volume in multiples of 8GiB
247+
// shortdesc: Size/quota of the storage volume
245248
"volume.size": validate.Optional(validate.IsMultipleOfUnit("8GiB")),
246249
}
247250

‎lxd/storage/drivers/driver_powerflex_volumes.go

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -436,14 +436,15 @@ func (d *powerflex) commonVolumeRules() map[string]func(value string) error {
436436
// ---
437437
// type: string
438438
// defaultdesc: same as `volume.block.type` or `thick`
439-
// shortdesc: Create a `thin` or `thick` provisioned volume
439+
// shortdesc: Whether to create a `thin` or `thick` provisioned volume
440440
"block.type": validate.Optional(validate.IsOneOf("thin", "thick")),
441441
// lxdmeta:generate(entities=storage-powerflex; group=volume-conf; key=size)
442-
//
442+
// The size must be in multiples of 8 GiB.
443+
// See {ref}`storage-powerflex-limitations` for more information.
443444
// ---
444445
// type: string
445446
// defaultdesc: same as `volume.size`
446-
// shortdesc: Size/quota of the storage volume in multiples of 8GiB
447+
// shortdesc: Size/quota of the storage volume
447448
"size": validate.Optional(validate.IsMultipleOfUnit("8GiB")),
448449
}
449450
}

‎lxd/storage/utils.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -538,7 +538,7 @@ func poolAndVolumeCommonRules(vol *drivers.Volume) map[string]func(string) error
538538

539539
// Those keys are only valid for volumes.
540540
if vol != nil {
541-
// lxdmeta:generate(entities=storage-btrfs,storage-cephfs,storage-ceph,storage-dir,storage-lvm,storage-zfs; group=volume-conf; key=volatile.uuid)
541+
// lxdmeta:generate(entities=storage-btrfs,storage-cephfs,storage-ceph,storage-dir,storage-lvm,storage-zfs,storage-powerflex; group=volume-conf; key=volatile.uuid)
542542
//
543543
// ---
544544
// type: string

0 commit comments

Comments
 (0)