doc(1.9.0): publish as dev

Signed-off-by: Chin-Ya Huang <[email protected]>

config.toml

@@ -14,7 +14,7 @@ style = "paraiso-dark"
 [params]
 description = "Cloud native distributed block storage for Kubernetes"
 tagline = "Easy to use, 100% open source, run anywhere"
-versions = ["1.7.2", "1.7.1", "1.7.0", "1.6.4", "1.6.3", "1.6.2", "1.6.1", "1.6.0", "1.8.0-dev", "1.7.3-dev", "1.6.5-dev"]
+versions = ["1.7.2", "1.7.1", "1.7.0", "1.6.4", "1.6.3", "1.6.2", "1.6.1", "1.6.0", "1.9.0-dev", "1.8.0-dev", "1.7.3-dev", "1.6.5-dev"]
 archived_versions = ["1.5.5", "1.5.4", "1.5.3", "1.5.2", "1.5.1", "1.5.0", "1.4.4", "1.3.3", "1.2.6", "1.1.3"]
 alpine_js_version = "2.2.5"
 locale = "en_US"

content/docs/1.9.0/_index.md

@@ -0,0 +1,18 @@
+---
+title: The Longhorn Documentation
+description: Cloud native distributed block storage for Kubernetes
+weight: 1
+---
+
+**Longhorn** is a lightweight, reliable, and powerful distributed [block storage](https://cloudacademy.com/blog/object-storage-block-storage/) system for Kubernetes.
+
+Longhorn implements distributed block storage using containers and microservices. Longhorn creates a dedicated storage controller for each block device volume and synchronously replicates the volume across multiple replicas stored on multiple nodes. The storage controller and replicas are themselves orchestrated using Kubernetes.
+
+## Features
+
+* Enterprise-grade distributed block storage with no single point of failure
+* Incremental snapshot of block storage
+* Backup to secondary storage ([NFS](https://www.extrahop.com/resources/protocols/nfs/) or [S3](https://aws.amazon.com/s3/)-compatible object storage) built on efficient change block detection
+* Recurring snapshots and backups
+* Automated, non-disruptive upgrades. You can upgrade the entire Longhorn software stack without disrupting running storage volumes.
+* An intuitive GUI dashboard

content/docs/1.9.0/advanced-resources/_index.md

@@ -0,0 +1,4 @@
+---
+title: Advanced Resources
+weight: 9
+---

content/docs/1.9.0/advanced-resources/backing-image/_index.md

@@ -0,0 +1,4 @@
+---
+title: Backing Image
+weight: 7
+---

content/docs/1.9.0/advanced-resources/backing-image/backing-image-backup.md

@@ -0,0 +1,102 @@
+---
+title: Backing Image Backup
+weight: 2
+---
+
+As of v1.6.0, Longhorn supports backing up of backing images.
+
+## Prerequisites
+
+You must first [set up a backup target](../../../snapshots-and-backups/backup-and-restore/set-backup-target). If you skip this crucial step, the missing backup target will prevent Longhorn from creating a backup of the backing image.
+
+## Create a Backup of a Backing Image
+
+Because backing images are globally unique within the Longhorn system, the corresponding backups are also globally unique and are identified using the same name.
+
+### Create a Backup Using YAML
+
+Example of backing image:
+```yaml
+apiVersion: longhorn.io/v1beta2
+kind: BackingImage
+metadata:
+  name: parrot
+  namespace: longhorn-system
+spec:
+  sourceType: download
+  sourceParameters:
+    url: https://longhorn-backing-image.s3-us-west-1.amazonaws.com/parrot.raw
+  checksum: 304f3ed30ca6878e9056ee6f1b02b328239f0d0c2c1272840998212f9734b196371560b3b939037e4f4c2884ce457c2cbc9f0621f4f5d1ca983983c8cdf8cd9a
+```
+
+Example of YAML code used to create a backup of the sample backing image:
+```yaml
+apiVersion: longhorn.io/v1beta2
+kind: BackupBackingImage
+metadata:
+  name: parrot-backup
+  namespace: longhorn-system
+spec:
+  backingImage: parrot
+  backupTargetName: default
+  userCreated: true
+  labels:
+    usecase: test
+    type: raw
+```
+
+> **IMPORTANT:**
+> - `name`: If the names are not unique, Longhorn will not be able to create a backup of the backing image.
+> - `backingImage`: The backing image for the backup.
+> - `backupTargetName`: The backup target that is used to store the backup of the backing image.
+> - `userCreated`: Set the value to `true` to indicate that you created the backup custom resource, which enabled the creation of the backup in the backupstore. The value `false` indicates that the backup custom resource was synced from the backupstore.
+> - `labels`: You can add labels to the backing image backup.
+
+### Create a Backup Using the Longhorn UI
+1. Go to **Setting** > **Backing Image**.
+2. Select the backing image that you want to back up, and then click **Back Up** in the **Operation** menu.
+
+Longhorn creates the backup and adds the details to the **Backing Image Backup** list.
+
+{{< figure src="/img/screenshots/backing-image/backup.png" >}}
+
+
+## Restore a Backing Image from a Backup
+You can restore a backing image in another cluster after creating a backup in the backupstore.
+
+Example of YAML code used to restore a backing image:
+```yaml
+apiVersion: longhorn.io/v1beta2
+kind: BackingImage
+metadata:
+    name: parrot-restore
+    namespace: longhorn-system
+spec:
+    sourceType: restore
+    sourceParameters:
+        # change to your backup URL
+        # backup-url: nfs://longhorn-test-nfs-svc.default:/opt/backupstore?backingImage=parrot
+        backup-url: s3://backupbucket@us-east-1/?backingImage=parrot
+        concurrent-limit: "2"
+    checksum: 304f3ed30ca6878e9056ee6f1b02b328239f0d0c2c1272840998212f9734b196371560b3b939037e4f4c2884ce457c2cbc9f0621f4f5d1ca983983c8cdf8cd9a
+```
+
+> **IMPORTANT:**
+> - `sourceType`: Set the value to `restore`.
+> - `sourceParameters`: Configure the following parameters:
+>   - `backup-url`: URL of the backing image resource in the backupstore. You can find this information in the status of the backup custom resource `.Status.URL`.
+>   - `concurrent-limit`: Maximum number of worker threads that can concurrently run for each restore operation. When unspecified, Longhorn uses the default value.
+> - `checksum`: You can specify the expected SHA-512 checksum of the backing image file, which Longhorn uses to validate the restored file. When unspecified, Longhorn uses the checksum of the restored file as the truth.
+
+### Restore from a Backup Using the Longhorn UI
+1. Go to **Setting** > **Backing Image**.
+2. Select the backup that you want to use, and then click **Restore** in the **Operation** menu.
+3. Click **OK**.
+
+{{< figure src="/img/screenshots/backing-image/1.8.0/restore.png" >}}
+
+## Volume with a Backing Image
+
+When you create a backup of a volume, Longhorn automatically creates a backup of its backing image.
+
+You can restore a volume with a backing image. If the image already exists in the cluster, Longhorn uses the image directly. If the image exists in the backupstore but not in the cluster, Longhorn automatically restores the backing image.

content/docs/1.9.0/advanced-resources/backing-image/backing-image-encryption.md

@@ -0,0 +1,251 @@
+---
+title: Backing Image Encryption
+weight: 2
+---
+
+Starting with v1.7.0, Longhorn allows you to encrypt and decrypt a backing image by cloning it. The backing image encryption mechanism utilizes the Linux kernel module `dm_crypt` and the command-line utility `cryptsetup`.
+
+## Clone a Backing Image
+You can clone a backing image using YAML code. Notice that, this will create a whole new backing image with the same content as the original one. The backing image also consumes the disk space.
+
+Example of a downloaded backing image:
+
+```yaml
+apiVersion: longhorn.io/v1beta2
+kind: BackingImage
+metadata:
+  name: parrot
+  namespace: longhorn-system
+spec:
+  sourceType: download
+  sourceParameters:
+    url: https://longhorn-backing-image.s3-us-west-1.amazonaws.com/parrot.raw
+  checksum: 304f3ed30ca6878e9056ee6f1b02b328239f0d0c2c1272840998212f9734b196371560b3b939037e4f4c2884ce457c2cbc9f0621f4f5d1ca983983c8cdf8cd9a
+```
+
+Example of YAML code used to clone the sample backing image:
+
+```yaml
+apiVersion: longhorn.io/v1beta2
+kind: BackingImage
+metadata:
+  name: parrot-cloned
+  namespace: longhorn-system
+spec:
+  sourceType: clone
+  sourceParameters:
+    backing-image: parrot
+    encryption: ignore
+```
+
+> **Important:**
+> - `backing-image`: Specify the name of the backing image to be cloned.
+> - `encryption`: Set the value to `ignore` to directly clone the backing image. If the value is not given, Longhorn use `ignore` as default value.
+
+You can also clone a backing image using the Longhorn UI.
+1. Go to **Setting** > **Backing Image**.
+2. Click **Create Backing Image**.
+3. Configure the following settings:
+  - **Created From**: Select **Clone From Existing Backing Image**.
+  - **Encryption**: Select **Ignore**.
+4. Click **OK**.
+
+{{< figure src="/img/screenshots/backing-image/clone.png" >}}
+
+## Encrypt a Backing Image
+You can enable encryption during cloning of a backing image so that the image can be used with an encrypted volume.
+
+Example of a downloaded backing image:
+
+```yaml
+apiVersion: longhorn.io/v1beta2
+kind: BackingImage
+metadata:
+  name: parrot
+  namespace: longhorn-system
+spec:
+  sourceType: download
+  sourceParameters:
+    url: https://longhorn-backing-image.s3-us-west-1.amazonaws.com/parrot.raw
+  checksum: 304f3ed30ca6878e9056ee6f1b02b328239f0d0c2c1272840998212f9734b196371560b3b939037e4f4c2884ce457c2cbc9f0621f4f5d1ca983983c8cdf8cd9a
+```
+
+Example of YAML code used to clone and encrypt the sample backing image:
+
+```yaml
+apiVersion: longhorn.io/v1beta2
+kind: BackingImage
+metadata:
+  name: parrot-cloned-encrypted
+  namespace: longhorn-system
+spec:
+  sourceType: clone
+  sourceParameters:
+    backing-image: parrot
+    encryption: encrypt
+    secret: longhorn-crypto
+    secret-namespace: longhorn-system
+```
+
+Example of YAML code used to encrypt the backing image:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: longhorn-crypto
+  namespace: longhorn-system
+stringData:
+  CRYPTO_KEY_VALUE: "Your encryption passphrase"
+  CRYPTO_KEY_PROVIDER: "secret"
+  CRYPTO_KEY_CIPHER: "aes-xts-plain64"
+  CRYPTO_KEY_HASH: "sha256"
+  CRYPTO_KEY_SIZE: "256"
+  CRYPTO_PBKDF: "argon2i"
+```
+
+> **Important:**
+> - `backing-image`: Specify the name of the backing image to be cloned.
+> - `encryption`: Set the value to `encrypt` to encrypt the backing image during cloning.
+> - `secret`: Specify the secret used to encrypt the backing image.
+> - `secret-namespace`: Specify the namespace of the secret used to encrypt the backing image.
+
+You can also create an encrypted copy of a backing image using the Longhorn UI.
+1. Go to **Setting** > **Backing Image**.
+2. Click **Create Backing Image**.
+3. Configure the following settings:
+  - **Created From**: Select **Clone From Existing Backing Image**.
+  - **Encryption**: Select **Encrypt**.
+4. Specify the secret and secret namespace to be used for encryption.
+5. Click **OK**.
+
+{{< figure src="/img/screenshots/backing-image/encrypt.png" >}}
+
+## Decrypt a Backing Image
+You can decrypt an encrypted backing image through cloning.
+
+Example of an encrypted backing image:
+
+```yaml
+apiVersion: longhorn.io/v1beta2
+kind: BackingImage
+metadata:
+  name: parrot-cloned-encrypted
+  namespace: longhorn-system
+spec:
+  sourceType: clone
+  sourceParameters:
+    backing-image: parrot
+    encryption: encrypt
+    secret: longhorn-crypto
+    secret-namespace: longhorn-system
+```
+
+Example of YAML code used to encrypt and decrypt the backing image:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: longhorn-crypto
+  namespace: longhorn-system
+stringData:
+  CRYPTO_KEY_VALUE: "Your encryption passphrase"
+  CRYPTO_KEY_PROVIDER: "secret"
+  CRYPTO_KEY_CIPHER: "aes-xts-plain64"
+  CRYPTO_KEY_HASH: "sha256"
+  CRYPTO_KEY_SIZE: "256"
+  CRYPTO_PBKDF: "argon2i"
+```
+
+Example of YAML code used to decrypt the backing image:
+
+```yaml
+apiVersion: longhorn.io/v1beta2
+kind: BackingImage
+metadata:
+  name: parrot-cloned-decrypt
+  namespace: longhorn-system
+spec:
+  sourceType: clone
+  sourceParameters:
+    backing-image: parrot-cloned-encrypted
+    encryption: decrypt
+    secret: longhorn-crypto
+    secret-namespace: longhorn-system
+```
+
+> **Important:**
+> - `backing-image`: Specify the name of the backing image to be cloned.
+> - `encryption`: Set the value to `decrypt` to decrypt the backing image during cloning.
+> - `secret`: Specify the secret used to decrypt the backing image.
+> - `secret-namespace`: Specify the namespace of the secret used to decrypt the backing image.
+
+You can also decrypt a backing image (through cloning) using the Longhorn UI.
+1. Go to **Setting** > **Backing Image**.
+2. Click **Create Backing Image**.
+3. Configure the following settings:
+  - **Created From**: Select **Clone From Existing Backing Image**.
+  - **Encryption**: Select **Decrypt**.
+4. Specify the secret and secret namespace to be used for decryption.
+5. Click **OK**.
+
+
+{{< figure src="/img/screenshots/backing-image/decrypt.png" >}}
+
+
+## Use an Encrypted Backing Image with an Encrypted Volume
+The secret used to encrypt the backing image and the volume must be identical. Once the encrypted backing image is ready, you can create the StorageClass with the corresponding backing image and the secret to create the volume for the workload.
+
+Example of YAML code for the encryption secret:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: longhorn-crypto
+  namespace: longhorn-system
+stringData:
+  CRYPTO_KEY_VALUE: "Your encryption passphrase"
+  CRYPTO_KEY_PROVIDER: "secret"
+  CRYPTO_KEY_CIPHER: "aes-xts-plain64"
+  CRYPTO_KEY_HASH: "sha256"
+  CRYPTO_KEY_SIZE: "256"
+  CRYPTO_PBKDF: "argon2i"
+```
+
+Example of YAML code for the StorageClass:
+```yaml
+kind: StorageClass
+apiVersion: storage.k8s.io/v1
+metadata:
+  name: longhorn-crypto-global
+provisioner: driver.longhorn.io
+allowVolumeExpansion: true
+parameters:
+  numberOfReplicas: "3"
+  staleReplicaTimeout: "2880" # 48 hours in minutes
+  fromBackup: ""
+  encrypted: "true"
+  backingImage: "parrot-cloned-encrypted"
+  backingImageDataSourceType: "clone"
+  # global secret that contains the encryption key that will be used for all volumes
+  csi.storage.k8s.io/provisioner-secret-name: "longhorn-crypto"
+  csi.storage.k8s.io/provisioner-secret-namespace: "longhorn-system"
+  csi.storage.k8s.io/node-publish-secret-name: "longhorn-crypto"
+  csi.storage.k8s.io/node-publish-secret-namespace: "longhorn-system"
+  csi.storage.k8s.io/node-stage-secret-name: "longhorn-crypto"
+  csi.storage.k8s.io/node-stage-secret-namespace: "longhorn-system"
+```
+
+For more information, see [Volume Encryption](../../security/volume-encryption).
+
+## Limitations
+- Longhorn is unable to encrypt backing images that are already encrypted, and decrypt backing images that are not encrypted.
+- Longhorn does not allow you to change the encryption key of an encrypted backing image.
+- When encrypting a qcow2 image, Longhorn first creates a raw image from the qcow2 image and then encrypts it. The resulting encrypted raw image temporarily consumes extra space during cloning. For example,
+    1. If we encrypt a 10MiB qcow2 image with a virtual size of 200MiB, we first create the raw image from the qcow2 which will consume 200MiB of the space.
+    2. Longhorn then create the encrypted backing image from that 200MiB raw image which will take another 200MiB of the space.
+    3. After the encrypted backing image is created, the temporary raw image will be cleaned up and free the 200MiB from the space.
+- If the source backing image is a sparse file, the file loses its sparsity after encryption.
+- To allow storage of the LUKS metadata during encryption, the image size is increased by 16 MB. For more information, see the [cryptsetup release notes](https://gitlab.com/cryptsetup/cryptsetup/-/blob/master/docs/v2.1.0-ReleaseNotes#L27).