Skip to content

Commit 1da3f4e

Browse files
balaharish7balaharish7
authored
docs: Update 4.3 Docs (#530)
* docs: Update 4.3 Docs Signed-off-by: Bala Harish <[email protected]> * docs: Update 4.3 Docs Signed-off-by: Bala Harish <[email protected]> * docs: Update 4.3 Docs Signed-off-by: Bala Harish <[email protected]> * docs: Update 4.3 Docs Signed-off-by: Bala Harish <[email protected]> --------- Signed-off-by: Bala Harish <[email protected]>
1 parent 03e11c4 commit 1da3f4e

File tree

9 files changed

+618
-569
lines changed

9 files changed

+618
-569
lines changed

‎docs/i18n/en/docusaurus-plugin-content-docs/version-4.2.x.json

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
{
2+
"version.label": {
3+
"message": "4.2.x",
4+
"description": "The label for version 4.2.x"
5+
},
6+
"sidebar.docs.category.Introduction to OpenEBS": {
7+
"message": "Introduction to OpenEBS",
8+
"description": "The label for category Introduction to OpenEBS in sidebar docs"
9+
},
10+
"sidebar.docs.category.Concepts": {
11+
"message": "Concepts",
12+
"description": "The label for category Concepts in sidebar docs"
13+
},
14+
"sidebar.docs.category.Data Engines": {
15+
"message": "Data Engines",
16+
"description": "The label for category Data Engines in sidebar docs"
17+
},
18+
"sidebar.docs.category.Quickstart Guide": {
19+
"message": "Quickstart Guide",
20+
"description": "The label for category Quickstart Guide in sidebar docs"
21+
},
22+
"sidebar.docs.category.User Guides": {
23+
"message": "User Guides",
24+
"description": "The label for category User Guides in sidebar docs"
25+
},
26+
"sidebar.docs.category.Local Storage User Guide": {
27+
"message": "Local Storage User Guide",
28+
"description": "The label for category Local Storage User Guide in sidebar docs"
29+
},
30+
"sidebar.docs.category.Local PV Hostpath": {
31+
"message": "Local PV Hostpath",
32+
"description": "The label for category Local PV Hostpath in sidebar docs"
33+
},
34+
"sidebar.docs.category.Configuration": {
35+
"message": "Configuration",
36+
"description": "The label for category Configuration in sidebar docs"
37+
},
38+
"sidebar.docs.category.Advanced Operations": {
39+
"message": "Advanced Operations",
40+
"description": "The label for category Advanced Operations in sidebar docs"
41+
},
42+
"sidebar.docs.category.XFS Quota": {
43+
"message": "XFS Quota",
44+
"description": "The label for category XFS Quota in sidebar docs"
45+
},
46+
"sidebar.docs.category.Local PV LVM": {
47+
"message": "Local PV LVM",
48+
"description": "The label for category Local PV LVM in sidebar docs"
49+
},
50+
"sidebar.docs.category.Local PV ZFS": {
51+
"message": "Local PV ZFS",
52+
"description": "The label for category Local PV ZFS in sidebar docs"
53+
},
54+
"sidebar.docs.category.Additional Information": {
55+
"message": "Additional Information",
56+
"description": "The label for category Additional Information in sidebar docs"
57+
},
58+
"sidebar.docs.category.Replicated Storage User Guide": {
59+
"message": "Replicated Storage User Guide",
60+
"description": "The label for category Replicated Storage User Guide in sidebar docs"
61+
},
62+
"sidebar.docs.category.Replicated PV Mayastor": {
63+
"message": "Replicated PV Mayastor",
64+
"description": "The label for category Replicated PV Mayastor in sidebar docs"
65+
},
66+
"sidebar.docs.category.Data Migration": {
67+
"message": "Data Migration",
68+
"description": "The label for category Data Migration in sidebar docs"
69+
},
70+
"sidebar.docs.category.Migration using Velero": {
71+
"message": "Migration using Velero",
72+
"description": "The label for category Migration using Velero in sidebar docs"
73+
},
74+
"sidebar.docs.category.Migration for Distributed DB": {
75+
"message": "Migration for Distributed DB",
76+
"description": "The label for category Migration for Distributed DB in sidebar docs"
77+
},
78+
"sidebar.docs.category.Migration for Replicated DB": {
79+
"message": "Migration for Replicated DB",
80+
"description": "The label for category Migration for Replicated DB in sidebar docs"
81+
},
82+
"sidebar.docs.category.Solutioning": {
83+
"message": "Solutioning",
84+
"description": "The label for category Solutioning in sidebar docs"
85+
},
86+
"sidebar.docs.category.OpenEBS on K8s Platforms": {
87+
"message": "OpenEBS on K8s Platforms",
88+
"description": "The label for category OpenEBS on K8s Platforms in sidebar docs"
89+
},
90+
"sidebar.docs.category.Read-Write-Many": {
91+
"message": "Read-Write-Many",
92+
"description": "The label for category Read-Write-Many in sidebar docs"
93+
},
94+
"sidebar.docs.category.Backup and Restore": {
95+
"message": "Backup and Restore",
96+
"description": "The label for category Backup and Restore in sidebar docs"
97+
},
98+
"sidebar.docs.category.Troubleshooting": {
99+
"message": "Troubleshooting",
100+
"description": "The label for category Troubleshooting in sidebar docs"
101+
},
102+
"sidebar.docs.category.Support": {
103+
"message": "Support",
104+
"description": "The label for category Support in sidebar docs"
105+
}
106+
}

‎docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/additional-information/call-home.md renamed to ‎docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/call-home.md

File renamed without changes.

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

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
id: encryption
3+
title: Encryption
4+
keywords:
5+
- Encryption
6+
- Data Encryption
7+
- Encrypted Volumes
8+
description: This guide explains about the Data Encryption At-Rest feature.
9+
---
10+
11+
## Overview
12+
13+
OpenEBS supports data-at-rest encryption to ensure the confidentiality of persistent disk data. By configuring disk pools with user-defined encryption keys, the pools themselves are encrypted, and volume replicas placed on these pools are automatically encrypted. This approach is especially beneficial for meeting security and regulatory compliance requirements.
14+
15+
This guide outlines how to enable encryption in Mayastor DiskPools and use them for volume replica placement.
16+
17+
## Prerequisites
18+
19+
Before provisioning encrypted volumes, ensure the following are set up:
20+
21+
### Create a Kubernetes Secret with AES-XTS Keys
22+
23+
Encryption in Mayastor uses the AES-XTS cipher, which requires two 128-bit hex-encoded keys.
24+
25+
**Example: Kubernetes Secret**
26+
```
27+
apiVersion: v1
28+
kind: Secret
29+
metadata:
30+
name: pool-encr-secret
31+
namespace: mayastor
32+
type: Opaque
33+
immutable: true
34+
stringData:
35+
encryption_parameters: |
36+
{
37+
"cipher": "AesXts",
38+
"key": "2b7e151628aed2a6abf7158809cf4f3c",
39+
"key_len": 128,
40+
"key2": "2b7e151628aed2a6abf7158809cf4f3d",
41+
"key2_len": 128
42+
}
43+
```
44+
45+
:::note
46+
You can additionally use Kubernetes built-in resource encryption to secure this Secret resource. Refer to the [Encrypting Confidential Data at Rest Documentation](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/) for more information.
47+
:::
48+
49+
### Configure DiskPool to Use the Encryption Secret
50+
51+
Reference the encryption secret in the `DiskPool` resource to enable encrypted storage.
52+
53+
**Example: DiskPool Configuration**
54+
```
55+
apiVersion: "openebs.io/v1beta3"
56+
kind: DiskPool
57+
metadata:
58+
name: <POOL_NAME>
59+
namespace: mayastor
60+
spec:
61+
node: <NODE_NAME>
62+
disks: ["/dev/disk/by-id/<DEVICE_NAME>"]
63+
encryptionConfig:
64+
source:
65+
secret:
66+
name: pool-encr-secret
67+
```
68+
69+
### Define StorageClass for Encrypted Volumes
70+
71+
To place volume replicas on encrypted pools, set `encrypted: "true"` in the `StorageClass`.
72+
73+
**Example: StorageClass**
74+
75+
```
76+
apiVersion: storage.k8s.io/v1
77+
kind: StorageClass
78+
metadata:
79+
name: mayastor-2-encr
80+
parameters:
81+
protocol: nvmf
82+
repl: "2"
83+
encrypted: "true"
84+
provisioner: io.openebs.csi-mayastor
85+
reclaimPolicy: Delete
86+
```
87+
88+
## Migrating from Non-Encrypted to Encrypted Pools
89+
90+
Currently, there is no automatic support for migrating existing unencrypted volumes. The following manual migration steps are recommended:
91+
92+
**Migration Steps**
93+
94+
1. Identify Target Pool: Select a non-encrypted pool (Example: P1) to migrate.
95+
2. List Volumes on P1: Identify all volumes with replicas on P1.
96+
3. (Optional) Scale Up Volumes: Increase replica count (Example: from 2 to 3) to maintain availability.
97+
4. Mayastor Cordon Node: Cordon the mayastor node hosting P1 to stop new replicas from being scheduled using the plugin command `kubectl mayastor cordon node N1 key=value`.
98+
5. Update Volume Config: Set encrypted: true using the Mayastor plugin command `kubectl mayastor set volume <volume-id> encryption true`.
99+
6. Scale Down Volumes: Reduce replica count to remove replicas from P1.
100+
7. Recreate Encrypted Pool:
101+
- Delete the non-encrypted pool.
102+
- Recreate it with encryption using the previously defined secret.
103+
8. Scale-up Volumes: Increase replica count to allow new encrypted replicas to be created on the new pool.
104+
9. Optional Replica Adjustment: After migration, optionally reduce replica count back to the original.
105+
106+
:::note
107+
Monitor disk space and health throughout the migration to avoid service disruption.
108+
:::
109+
110+
## Validation and Tips
111+
112+
- The Kubernetes Secret must be created before applying the DiskPool.
113+
- Key rotation is not supported at this time.
114+
- Persistent device paths are required for pool creation. Retrieve them using:
115+
```
116+
kubectl mayastor get block-devices <node-id>
117+
```
118+
:::note
119+
Pool and volume migration is manual and requires careful planning.
120+
:::

‎docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/additional-information/eventing.md renamed to ‎docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/eventing.md

File renamed without changes.

‎docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/additional-information/replica-operations.md renamed to ‎docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/replica-operations.md

File renamed without changes.

‎docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/configuration/rs-storage-class-parameters.md

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -323,18 +323,19 @@ as the storage class has `zone` as the value for `poolHasTopologyKey` that match
323323
This feature enforces the following rules to ensure the proper placement and distribution of replicas and targets so that there is not any single point of failure affecting multiple instances of StatefulSet.
324324

325325
1. Anti-Affinity among single-replica volumes:
326-
This rule ensures that replicas of different volumes are distributed in such a way that there is no single point of failure. By avoiding the colocation of replicas from different volumes on the same node.
326+
This rule ensures that replicas of different volumes are distributed in such a way that there is no single point of failure. By avoiding the colocation of replicas from different volumes on the same node.
327327

328-
2. Anti-Affinity among multi-replica volumes:
329-
330-
If the affinity group volumes have multiple replicas, they already have some level of redundancy. This feature ensures that in such cases, the replicas are distributed optimally for the stsAffinityGroup volumes.
328+
2. Anti-Affinity among multi-replica volumes:
329+
If the affinity group volumes have multiple replicas, they already have some level of redundancy. This feature ensures that in such cases, the replicas are distributed optimally for the stsAffinityGroup volumes.
331330

332331
3. Anti-affinity among targets:
332+
The [High Availability](../replicated-pv-mayastor/advanced-operations/HA.md) feature ensures that there is no single point of failure for the targets.
333+
The `stsAffinityGroup` ensures that in such cases, the targets are distributed optimally for the stsAffinityGroup volumes.
333334

334-
The [High Availability](../replicated-pv-mayastor/advanced-operations/HA.md) feature ensures that there is no single point of failure for the targets.
335-
The `stsAffinityGroup` ensures that in such cases, the targets are distributed optimally for the stsAffinityGroup volumes.
335+
By default, the `stsAffinityGroup` feature is disabled. To enable it, modify the storage class YAML by setting the `parameters.stsAffinityGroup` parameter to true.
336336

337-
By default, the `stsAffinityGroup` feature is disabled. To enable it, modify the storage class YAML by setting the `parameters.stsAffinityGroup` parameter to true.
337+
#### Known Limitation
338+
For multi-replica volumes that are part of a `stsAffinityGroup`, scaling down is permitted only up to two replicas. Reducing the replica count below two is not supported.
338339

339340
### "cloneFsIdAsVolumeId"
340341

‎docs/main/user-guides/upgrades.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ helm repo update
5959

6060
3. Execute `kubectl openebs upgrade -n <namespace>` to upgrade OpenEBS.
6161

62-
4. Monitor the upgrade status using `kubectl openebs get upgrade-status -n <namespace>`.
62+
4. Monitor the upgrade status using `kubectl openebs get upgrade status -n <namespace>`.
6363

6464
5. Verify that the CRDs, Volumes, Snapshots, and StoragePools are not affected by the upgrade process.
6565

@@ -92,7 +92,7 @@ Follow these steps to upgrade OpenEBS from version 4.x to 4.3:
9292

9393
2. Execute `kubectl openebs upgrade -n <namespace>` to upgrade OpenEBS.
9494

95-
3. Monitor the upgrade status using `kubectl openebs get upgrade-status -n <namespace>`.
95+
3. Monitor the upgrade status using `kubectl openebs get upgrade status -n <namespace>`.
9696

9797
4. Verify that the CRDs, Volumes, Snapshots, and StoragePools are not affected by the upgrade process.
9898

‎docs/sidebars.js

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -483,6 +483,21 @@ module.exports = {
483483
id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/supportability",
484484
label: "Supportability"
485485
},
486+
{
487+
type: "doc",
488+
id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/replica-operations",
489+
label: "Replica Operations"
490+
},
491+
{
492+
type: "doc",
493+
id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/eventing",
494+
label: "Eventing"
495+
},
496+
{
497+
type: "doc",
498+
id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/call-home-metrics",
499+
label: "Call-Home Metrics"
500+
},
486501
{
487502
type: "doc",
488503
id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/monitoring",
@@ -543,21 +558,6 @@ module.exports = {
543558
id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/additional-information/io-path-description",
544559
label: "I/O Path Description"
545560
},
546-
{
547-
type: "doc",
548-
id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/additional-information/replica-operations",
549-
label: "Replica Operations"
550-
},
551-
{
552-
type: "doc",
553-
id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/additional-information/eventing",
554-
label: "Eventing"
555-
},
556-
{
557-
type: "doc",
558-
id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/additional-information/call-home-metrics",
559-
label: "Call-Home Metrics"
560-
},
561561
{
562562
type: "doc",
563563
id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/additional-information/ttps",

0 commit comments

Comments
 (0)