docs(image and volume): add how to encrypr/decrypt image and volume

Signed-off-by: Jack Yu <jack.yu@suse.com>

docs/advanced/storageclass.md

@@ -148,7 +148,7 @@ resource "harvester_storageclass" "single-replica" {
 
 You can use the `dataLocality` parameter when at least one replica of a Longhorn volume must be scheduled on the same node as the pod that uses the volume (whenever possible).
 
-Harvester officially supports data locality as of **v1.3.0**. This applies even to volumes created from [images](../upload-image.md). To configure data locality, create a new StorageClass on the Harvester UI (**Storage Classess** > **Create** > **Parameters**) and then add the following parameter:
+Harvester officially supports data locality as of **v1.3.0**. This applies even to volumes created from [images](../image/upload-image.md). To configure data locality, create a new StorageClass on the Harvester UI (**Storage Classess** > **Create** > **Parameters**) and then add the following parameter:
 
 - **Key**: `dataLocality`
 - **Value**: `disabled` or `best-effort`

docs/getting-started/deploy-ha-cluster.md

@@ -80,7 +80,7 @@ Before you create VMs, create the necessary networks. If more than one network i
 
 ## 8. Import VM images. 
 
-On the Harvester UI, you can import ISO, qcow2, and raw [images](../upload-image.md) by uploading an image from the local file system, or by specifying the URL of an image that can be accessed from the cluster. 
+On the Harvester UI, you can import ISO, qcow2, and raw [images](../image/upload-image.md) by uploading an image from the local file system, or by specifying the URL of an image that can be accessed from the cluster. 
 
 ## 9. Import SSH keys. (Recommended)
 

docs/getting-started/deploy-singlenode-cluster.md

@@ -84,7 +84,7 @@ You can create a VM network that uses `mgmt` when testing Harvester with a singl
 
 ## 8. Import VM images. 
 
-On the Harvester UI, you can import ISO, qcow2, and raw [images](../upload-image.md) by uploading an image from the local file system, or by specifying the URL of an image that can be accessed from the cluster. 
+On the Harvester UI, you can import ISO, qcow2, and raw [images](../image/upload-image.md) by uploading an image from the local file system, or by specifying the URL of an image that can be accessed from the cluster. 
 
 ## 9. Import SSH keys. (Recommended)
 

docs/image/_category_.json

@@ -0,0 +1,6 @@
+{
+    "position": 10,
+    "label": "Image Management",
+    "collapsible": true,
+    "collapsed": true
+}

docs/image/image-security.md

@@ -0,0 +1,146 @@
+---
+id: image-security
+sidebar_position: 2
+sidebar_label: Image Security
+title: "Image Security"
+keywords:
+  - Harvester
+  - harvester
+  - Rancher
+  - rancher
+  - Image Security
+---
+
+_Available as of v1.4.0_
+
+Starting with v1.4.0 Harvester allows you to encrypt and decrypt virtual machine image. The encryption mechanism utilizes the Linux kernel module dm_crypt and the command-line utility cryptsetup.
+
+## Prerequisite
+
+Before encrypting or decrypting the virtual machine image, we need to prepare following resources:
+
+- source virtual machine image
+- secret
+- storage class
+
+### Source Virtual Machine Image
+
+Please follow [Upload Images](./upload-image) to create an image.
+
+:::info important 
+Harvester doesn't support uploading an encrypted image
+:::
+
+### Secret
+
+We use this secret as passphrase of dm_crypt. You need to customize the value of `CRYPTO_KEY_VALUE` field. Other fields are fixed.
+
+![](/img/v1.4/image/create-encryption-used-secret.png)
+
+Example Secret:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: encryption
+  namespace: default
+data:
+  CRYPTO_KEY_CIPHER: aes-xts-plain64
+  CRYPTO_KEY_HASH: sha256
+  CRYPTO_KEY_PROVIDER: secret
+  CRYPTO_KEY_SIZE: 256
+  CRYPTO_KEY_VALUE: "Your encryption passphrase"
+  CRYPTO_PBKDF: argon2i
+```
+
+:::info important
+
+If you'd like to create secret in the system namespace, you can use Edit as YAML or kubectl to create the secret. On the Harvester Secrets page, Harvester does not display resources in the system namespace.
+
+:::
+
+### Storage Class
+
+Since Harvesters uses Longhorn to encrypt image, we need to pass required fields to Longhorn CSI driver. You can select encryption used secret when creating storage class. If you're interested in this, please check [here](./upload-image#image-storageclass) for more details. 
+
+![](/img/v1.4/image/create-storage-class.png)
+
+Example Storage Class:
+
+```yaml
+allowVolumeExpansion: true
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: encryption
+parameters:
+  csi.storage.k8s.io/node-publish-secret-name: encryption
+  csi.storage.k8s.io/node-publish-secret-namespace: default
+  csi.storage.k8s.io/node-stage-secret-name: encryption
+  csi.storage.k8s.io/node-stage-secret-namespace: default
+  csi.storage.k8s.io/provisioner-secret-name: encryption
+  csi.storage.k8s.io/provisioner-secret-namespace: default
+  encrypted: "true"
+  migratable: "true"
+  numberOfReplicas: "3"
+  staleReplicaTimeout: "2880"
+provisioner: driver.longhorn.io
+reclaimPolicy: Delete
+volumeBindingMode: Immediate
+```
+
+:::info important
+
+If you'd like to select secret in the system namespace. You can use Edit as YAML or kubectl to create the secret. On the Harvester Secrets page, Harvester does not display resources in the system namespace.
+
+:::
+
+## Encrypt Image
+
+After getting a source image, please select `Encrypt` to encrypt the virtual machine image.
+
+![](/img/v1.4/image/create-encrypted-image.png)
+
+Select a previously created storage class. This storage class must include encryption-related fields. Harvester will pass this storage class to Longhorn.
+
+![](/img/v1.4/image/select-encryption-storage-class.png)
+
+## Decrypt Image
+
+After getting an encrypted image, please select `Decrypt` to decrypt an encrypted virtual machine image.
+
+![](/img/v1.4/image/create-decrypted-image.png)
+
+Select the default or a commonly used storage class. Harvester will use the storage class from the source virtual machine image that you want to decrypt.
+
+![](/img/v1.4/image/select-normal-storage-class.png)
+
+## Use Image
+
+Select the image when creating a virtual machine.
+
+![](/img/v1.4/image/create.png)
+
+There are two cases in which the dashboard shows different messages on the virtual machine page.
+
+1. All volumes are encrypted.
+  ![](/img/v1.4/image/case1.png)
+2. Some volumes are encrypted.
+  ![](/img/v1.4/image/case2.png)
+
+If you'd like to know which specific volume is encrypted or not, please check `Enctyption` field on Volume tab.
+
+![](/img/v1.4/image/volume-detail.png)
+
+## Advanced Usage with Rancher Integration
+
+### Prevent other users from reading the secret
+
+Since the secret is a base64 encoded string, it's not really encrypted. So, admin might want keep this secret safe. With Rancher Integration, we can use project and namespace to isolate permission. Please check [Multi-Tenancy](../rancher/virtualization-management#multi-tenancy) for more detail.
+
+## Limitations
+
+- Don't support that export to image from encrypted image.
+- Don't support that download encrypted image and upload it to reuse.
+- Don't support that upload an encrypted image.

docs/upload-image.md → docs/image/upload-image.md

@@ -1,6 +1,6 @@
 ---
 id: upload-image
-sidebar_position: 6
+sidebar_position: 1
 sidebar_label: Upload Images
 title: "Upload Images"
 keywords:
@@ -88,7 +88,7 @@ Currently, qcow2, raw, and ISO images are supported.
 
 #### HTTP 413 Error in Rancher Multi-Cluster Management
 
-You can upload images from the [**Multi-Cluster Management**](./rancher/virtualization-management.md#importing-harvester-cluster) screen on the **Rancher UI**. When the status of an image is *Uploading* but the progress indicator displays *0%* for an extended period, check the HTTP response status code. *413* indicates that the size of the request body exceeds the limit.
+You can upload images from the [**Multi-Cluster Management**](../rancher/virtualization-management.md#importing-harvester-cluster) screen on the **Rancher UI**. When the status of an image is *Uploading* but the progress indicator displays *0%* for an extended period, check the HTTP response status code. *413* indicates that the size of the request body exceeds the limit.
 
 ![](/img/v1.3/img-413-code.png)
 
@@ -148,7 +148,7 @@ On the **Volumes** page, click **Export Image**. Enter the image name and select
 
 ### Image StorageClass
 
-When creating an image, you can select a [StorageClass](./advanced/storageclass.md) and use its pre-defined parameters like replicas, node selectors and disk selectors .
+When creating an image, you can select a [StorageClass](../advanced/storageclass.md) and use its pre-defined parameters like replicas, node selectors and disk selectors .
 
 :::note
 

docs/vm/create-windows-vm.md

@@ -60,7 +60,7 @@ The `bootOrder` values need to be set with the installation image first. If you
 1. The **first volume** is an `Image Volume` with the following values: 
     1. `Name`: The value `cdrom-disk` is set by default. You can keep it or change it.
     2. `Type`: Select `cd-rom`.
-    3. `Image`: Select the Windows image to be installed. See [Upload Images](../upload-image.md) for the full description on how to create new images.
+    3. `Image`: Select the Windows image to be installed. See [Upload Images](../image/upload-image.md) for the full description on how to create new images.
     4. `Size`: The value `20` is set by default. You can change it if your image has a bigger size.
     5. `Bus`: The value `SATA` is set by default. It's recommended you don't change it.
 2. The **second volume** is a `Volume` with the following values:

docs/volume/volume-security.md

@@ -0,0 +1,109 @@
+---
+sidebar_position: 6
+sidebar_label: Volume Security
+title: "Volume Security"
+keywords:
+- Volume Security
+- Image Security
+---
+
+_Available as of v1.4.0_
+
+Starting with v1.4.0 Harvester allows you to encrypt and decrypt volume. The encryption mechanism utilizes the Linux kernel module dm_crypt and the command-line utility cryptsetup.
+
+## Prerequisite
+
+Before encrypting volumes, we need to prepare following resources:
+
+- secret
+- storage class
+
+### Secret
+
+We use this secret as passphrase of dm_crypt. You need to customize the value of `CRYPTO_KEY_VALUE` field. Other fields are fixed.
+
+![](/img/v1.4/image/create-encryption-used-secret.png)
+
+Example Secret:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: encryption
+  namespace: default
+data:
+  CRYPTO_KEY_CIPHER: aes-xts-plain64
+  CRYPTO_KEY_HASH: sha256
+  CRYPTO_KEY_PROVIDER: secret
+  CRYPTO_KEY_SIZE: 256
+  CRYPTO_KEY_VALUE: "Your encryption passphrase"
+  CRYPTO_PBKDF: argon2i
+```
+
+:::info important
+
+If you'd like to create secret in the system namespace, you can use Edit as YAML or kubectl to create the secret. On the Harvester Secrets page, Harvester does not display resources in the system namespace.
+
+:::
+
+### Storage Class
+
+Since Harvesters uses Longhorn to encrypt volume, we need to pass required fields to Longhorn CSI driver.
+
+![](/img/v1.4/image/create-storage-class.png)
+
+Example Storage Class:
+
+```yaml
+allowVolumeExpansion: true
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: encryption
+parameters:
+  csi.storage.k8s.io/node-publish-secret-name: encryption
+  csi.storage.k8s.io/node-publish-secret-namespace: default
+  csi.storage.k8s.io/node-stage-secret-name: encryption
+  csi.storage.k8s.io/node-stage-secret-namespace: default
+  csi.storage.k8s.io/provisioner-secret-name: encryption
+  csi.storage.k8s.io/provisioner-secret-namespace: default
+  encrypted: "true"
+  migratable: "true"
+  numberOfReplicas: "3"
+  staleReplicaTimeout: "2880"
+provisioner: driver.longhorn.io
+reclaimPolicy: Delete
+volumeBindingMode: Immediate
+```
+
+:::info important
+
+If you'd like to select secret in the system namespace. You can use Edit as YAML or kubectl to create the secret. On the Harvester Secrets page, Harvester does not display resources in the system namespace.
+
+:::
+
+## Encrypt Volume
+
+There are two ways to create an encrypted volume. In either case, be sure to select an encrypted storage class.
+
+### Volumes Page
+
+![create-empty-volume](/img/v1.4/volume/create-empty-volume.png)
+
+### Volumes tab when creating a virtual machine
+
+When creating a virtual machine image, you can add a volume by clicking the `Add Volume button` in the Volumes tab on the virtual machine image page.
+
+![create-empty-volume](/img/v1.4/volume/create-empty-volume-in-vm.png)
+
+## Advanced usage with Rancher Integration
+
+### Prevent other users from reading the secret
+
+Since the secret is a base64 encoded string, it's not really encrypted. So, admin might want keep this secret safe. With Rancher Integration, we can use project and namespace to isolate permission. Please check [Multi-Tenancy](../rancher/virtualization-management#multi-tenancy) for more detail.
+
+## Limitations
+
+- Don't support that export to image from encrypted volumes.
+- Don't support that data volume restoring from encrypted to unencrypted or unencrypted to encrypted one.

i18n/zh/docusaurus-plugin-content-docs/current/rancher/node/node-driver.md

@@ -18,7 +18,7 @@ Harvester 主机驱动（Node Driver）用于在 Harvester 集群中配置虚拟
 从 Rancher `2.6.3` 版本开始，你可以使用内置的 Harvester 主机驱动创建 RKE1/RKE2 Kubernetes 集群。
 此外，Harvester 可以为这些 Kubernetes 集群提供内置的[负载均衡器](../cloud-provider.md)以及 Harvester 集群的[存储直通](../csi-driver.md)支持。
 
-虽然你可以中[在 Harvester UI 中上传和查看 `.ISO` 镜像](../../upload-image.md#通过本地文件上传镜像)，但 Rancher UI 不支持此功能。有关更多信息，请参阅 [Rancher 文档](https://rancher.com/docs/rancher/v2.6/en/virtualization-admin/#harvester-node-driver)。
+虽然你可以中[在 Harvester UI 中上传和查看 `.ISO` 镜像](../../image/upload-image.md#通过本地文件上传镜像)，但 Rancher UI 不支持此功能。有关更多信息，请参阅 [Rancher 文档](https://rancher.com/docs/rancher/v2.6/en/virtualization-admin/#harvester-node-driver)。
 
 ## Harvester 主机驱动
 

i18n/zh/docusaurus-plugin-content-docs/current/vm/create-windows-vm.md

@@ -56,7 +56,7 @@ Description: 从"虚拟机"页面创建一个或多个 Windows 虚拟机。
 1. **第一个卷**是一个`镜像卷`，具有以下值：
    1. `Name`：默认设置为 `cdrom-disk`。你也可以修改它。
    2. `Type`：选择 `cd-rom`。
-   3. `Image`：选择要安装的 Windows 镜像。有关如何创建新镜像的完整说明，请参见[上传镜像](../upload-image.md)。
+   3. `Image`：选择要安装的 Windows 镜像。有关如何创建新镜像的完整说明，请参见[上传镜像](../image/upload-image.md)。
    4. `Size`：默认值是 `20`。如果你的镜像较大，你可以更改该值。
    5. `Bus`：默认值是 `SATA`。建议你不要修改该值。
 2. **第二个卷**是具有以下值的`卷`：