ivampiresp/longhorn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: Add documents for v0.6.0

Browse Source 
Signed-off-by: Shuo Wu <shuo@rancher.com>
Signed-off-by: Sheng Yang <sheng.yang@rancher.com>
This commit is contained in:
Sheng Yang 2019-09-18 14:19:26 -07:00 committed by Sheng Yang
parent 5f0a663e89
commit a3be6e1ce3
5 changed files with 249 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@ -204,10 +204,14 @@ More examples are available at `./examples/`
### [Snapshot and Backup](./docs/snapshot-backup.md) ### [Snapshot and Backup](./docs/snapshot-backup.md)
### [Volume operations](./docs/volume.md) ### [Volume operations](./docs/volume.md)
### [Multiple disks, including how to change the default path for storage](./docs/multidisk.md) ### [Settings](./docs/settings.md)
### [Multiple disks](./docs/multidisk.md)
### [iSCSI](./docs/iscsi.md) ### [iSCSI](./docs/iscsi.md)
### [Base image](./docs/base-image.md) ### [Base image](./docs/base-image.md)
### [Kubernetes workload in Longhorn UI](./docs/k8s-workload.md) ### [Kubernetes workload in Longhorn UI](./docs/k8s-workload.md)
### [Storage Tags](./docs/storage-tags.md)
### [Customized default setting](./docs/customized-default-setting.md)
### [Taint Toleration](./docs/taint-toleration.md)
### [Restoring Stateful Set volumes](./docs/restore_statefulset.md) ### [Restoring Stateful Set volumes](./docs/restore_statefulset.md)
### [Google Kubernetes Engine](./docs/gke.md) ### [Google Kubernetes Engine](./docs/gke.md)

87
docs/customized-default-setting.md Normal file
View File

@ -0,0 +1,87 @@
# Customized Default Setting
## Overview
During Longhorn system deployment, users can customize the default settings for Longhorn. e.g. specify `Create Default Disk With Node Labeled` and `Default Data Path` before starting the Longhorn system.
## Usage
### Via Rancher UI
[Cluster] -> System -> Apps -> Launch -> longhorn -> LONGHORN DEFAULT SETTINGS
### Via Longhorn deployment yaml file
1. Download the longhorn repo:
```
git clone https://github.com/longhorn/longhorn.git
```
2. Modify the config map named `longhorn-default-setting` in the yaml file `longhorn/deploy/longhorn.yaml`. For example:
```
---
apiVersion: v1
kind: ConfigMap
metadata:
name: longhorn-default-setting
namespace: longhorn-system
data:
default-setting.yaml: |-
backup-target: s3://backupbucket@us-east-1/backupstore
backup-target-credential-secret: minio-secret
create-default-disk-labeled-nodes: true
default-data-path: /var/lib/rancher/longhorn-example/
replica-soft-anti-affinity: false
storage-over-provisioning-percentage: 600
storage-minimal-available-percentage: 15
upgrade-checker: false
default-replica-count: 2
guaranteed-engine-cpu:
default-longhorn-static-storage-class: longhorn-static-example
backupstore-poll-interval: 500
taint-toleration: key1=value1:NoSchedule; key2:NoExecute
---
```
### Via helm
1. Download the chart in the longhorn repo:
```
git clone https://github.com/longhorn/longhorn.git
```
2.1. Use helm command with `--set` flag to modify the default settings.
For example:
```
helm install ./longhorn/chart --name longhorn --namespace longhorn-system --set defaultSettings.taintToleration="key1=value1:NoSchedule; key2:NoExecute"
```
2.2. Or directly modifying the default settings in the yaml file `longhorn/chart/values.yaml` then using helm command without `--set` to deploy Longhorn.
For example:
In `longhorn/chart/values.yaml`:
```
defaultSettings:
backupTarget: s3://backupbucket@us-east-1/backupstore
backupTargetCredentialSecret: minio-secret
createDefaultDiskLabeledNodes: true
defaultDataPath: /var/lib/rancher/longhorn-example/
replicaSoftAntiAffinity: false
storageOverProvisioningPercentage: 600
storageMinimalAvailablePercentage: 15
upgradeChecker: false
defaultReplicaCount: 2
guaranteedEngineCPU:
defaultLonghornStaticStorageClass: longhorn-static-example
backupstorePollInterval: 500
taintToleration: key1=value1:NoSchedule; key2:NoExecute
```
Then use helm command:
```
helm install ./longhorn/chart --name longhorn --namespace longhorn-system
```
For more info about using helm, see:
[Install-Longhorn-with-helm](../README.md#install-longhorn-with-helm)
## History
[Original feature request](https://github.com/longhorn/longhorn/issues/623)
Available since v0.6.0

79
docs/settings.md Normal file
View File

@ -0,0 +1,79 @@
# Settings
## Customized Default Setting
To setup setting before installing Longhorn, see [Customized Default Setting](./customized-default-setting.md) for details.
## General
#### Backup Target
* Example: `s3://backupbucket@us-east-1/backupstore`
* Description: The target used for backup. Support NFS or S3. See [Snapshot and Backup](./snapshot-backup.md) for details.
#### Backup Target Credential Secret
* Example: `s3-secret`
* Description: The Kubernetes secret associated with the backup target. See [Snapshot and Backup](./snapshot-backup.md) for details.
#### Backupstore Poll Interval
* Example: `300`
* Description: In seconds. The interval to poll the backup store for updating volumes' Last Backup field. Set to 0 to disable the polling. See [Disaster Recovery Volume](./dr-volume.md) for details.
#### Create Default Disk on Labeled Nodes
* Example: `false`
* Description: Create default Disk automatically only on Nodes with the Kubernetes label `node.longhorn.io/create-default-disk=true` if no other Disks exist. If disabled, the default Disk will be created on all new Nodes when the node was detected for the first time.
* Note: It's useful if the user want to scale the cluster but doesn't want to use the storage on the new nodes.
#### Default Data Path
* Example: `/var/lib/rancher/longhorn`
* Description: Default path to use for storing data on a host
* Note: Can be used with `Create Default Disk on Labeled Nodes` option, to make Longhorn only use the nodes with specific storage mounted at e.g. `/opt/longhorn` directory when scaling the cluster.
#### Default Engine Image
* Example: `longhornio/longhorn-engine:v0.6.0`
* Description: The default engine image used by the manager. Can be changed on the manager starting command line only
* Note: Every Longhorn release will ship with a new Longhorn engine image. If the current Longhorn volumes are not using the default engine, a green arrow will show up, indicate this volume needs to be upgraded to use the default engine.
#### Enable Upgrade Checker
* Example: `true`
* Description: Upgrade Checker will check for new Longhorn version periodically. When there is a new version available, it will notify the user using UI
#### Latest Longhorn Version
* Example: `v0.6.0`
* Description: The latest version of Longhorn available. Update by Upgrade Checker automatically
* Note: Only available if `Upgrade Checker` is enabled.
#### Default Replica Count
* Example: `3`
* Description: The default number of replicas when creating the volume from Longhorn UI. For Kubernetes, update the `numberOfReplicas` in the StorageClass
* Note: The recommended way of choosing the default replica count is: if you have more than three nodes for storage, use 3; otherwise use 2. Using a single replica on a single node cluster is also OK, but the HA functionality wouldn't be available. You can still take snapshots/backups of the volume.
#### Guaranteed Engine CPU
* Example: `0.2`
* Description: (EXPERIMENTAL FEATURE) Allow Longhorn Engine to have guaranteed CPU allocation. The value is how many CPUs should be reserved for each Engine/Replica Manager Pod created by Longhorn. For example, 0.1 means one-tenth of a CPU. This will help maintain engine stability during high node workload. It only applies to the Instance Manager Pods created after the setting took effect. WARNING: Starting the system may fail or stuck while using this feature due to the resource constraint. Disabled (\"0\") by default.
* Note: Please set to **no more than a quarter** of what the node's available CPU resources, since the option would be applied to the two instance managers on the node (engine and replica), and the future upgraded instance managers (another two for engine and replica).
#### Default Longhorn Static StorageClass Name
* Example: `longhorn-static`
* Description: The `storageClassName` is for PV/PVC when creating PV/PVC for an existing Longhorn volume. Notice that it's unnecessary for users to create the related StorageClass object in Kubernetes since the StorageClass would only be used as matching labels for PVC bounding purpose. By default 'longhorn-static'.
#### Kubernetes Taint Toleration
* Example: `nodetype=storage:NoSchedule`
* Description: By setting tolerations for Longhorn then adding taints for the nodes, the nodes with large storage can be dedicated to Longhorn only (to store replica data) and reject other general workloads.
Before modifying toleration setting, all Longhorn volumes should be detached then Longhorn components will be restarted to apply new tolerations. And toleration update will take a while. Users cannot operate Longhorn system during update. Hence it's recommended to set toleration during Longhorn deployment.
Multiple tolerations can be set here, and these tolerations are separated by semicolon. For example, "key1=value1:NoSchedule; key2:NoExecute"
* Note: See [Taint Toleration](./taint-toleration.md) for details.
## Scheduling
#### Replica Soft Anti-Affinity
* Example: `true`
* Description: Allow scheduling on nodes with existing healthy replicas of the same volume
* Note: If the users want to avoid temporarily node down caused replica rebuild, they can set this option to `false`. The volume may be kept in `Degraded` state until another node that doesn't already have a replica scheduled comes online.
#### Storage Over Provisioning Percentage
* Example: `500`
* Description: The over-provisioning percentage defines how much storage can be allocated relative to the hard drive's capacity.
* Note: The users can set this to a lower value if they don't want overprovisioning storage. See [Multiple Disks Support](./multidisk.md#configuration) for details. Also, a replica of volume may take more space than the volume's size since the snapshots would need space to store as well. The users can delete snapshots to reclaim spaces.
#### Storage Minimal Available Percentage
* Example: `10`
* Description: If one disk's available capacity to it's maximum capacity in % is less than the minimal available percentage, the disk would become unschedulable until more space freed up.
* Note: See [Multiple Disks Support](./multidisk.md#configuration) for details.

46
docs/storage-tags.md Normal file
View File

@ -0,0 +1,46 @@
# Storage Tags
## Overview
The storage tag feature enables the user to only use certain nodes or disks for storing Longhorn volume data. For example, performance-sensitive data can use only the high-performance disks which can be tagged as `fast`, `ssd` or `nvme`, or only the high-performance node tagged as `baremetal`.
This feature supports both disks and nodes.
## Setup
The tag setup can be found at Longhorn UI:
1. *Node -> Select one node -> Edit Node and Disks*
2. Click `+New Node Tag` or `+New Disk Tag` to add new tags.
All the existing scheduled replica on the node or disk won't be affected by the new tags
## Usage
When multiple tags are specified for a volume, the disk and the node (the disk belong to) must have all the specified tags to become usable.
### UI
When creating a volume, specify the disk tag and node tag in the UI.
### Kubernetes
Use Kubernetes StorageClass setting to specify tags.
For example:
```
kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
name: longhorn-fast
provisioner: rancher.io/longhorn
parameters:
numberOfReplicas: "3"
staleReplicaTimeout: "480"
diskSelector: "ssd"
nodeSelector: "storage,fast"
```
## History
* [Original feature request](https://github.com/longhorn/longhorn/issues/311)
* Available since v0.6.0

32
docs/taint-toleration.md Normal file
View File

@ -0,0 +1,32 @@
# Taint Toleration
## Overview
If users want to create nodes with large storage spaces and/or CPU resources for Longhorn only (to store replica data) and reject other general workloads, they can taint those nodes and add tolerations for Longhorn components. Then Longhorn can be deployed on those nodes.
For more Kubernetes taint and toleration info, see:
[Kubernetes Taint & Tolerations](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)
## Setup
### During installing Longhorn
Follow the instructions to set init taint tolerations: [Customize default settings](https://github.com/longhorn/longhorn/wiki/Feature:-Customized-Default-Setting#usage)
### After Longhorn has been installed
The taint toleration setting can be found at Longhorn UI:
Setting -> General -> Kubernetes Taint Toleration
Users can modify the existing tolerations or add more tolerations here, but noted that it will result in all the Longhorn system components to be recreated.
## Usage
1. Before modifying the toleration setting, users should make sure all Longhorn volumes are `detached`. Since all Longhorn components will be restarted then the Longhorn system is unavailable temporarily. If there are running Longhorn volumes in the system, this means the Longhorn system cannot restart its components and the request will be rejected.
2. During the Longhorn system updates toleration setting and restarts its components, users shouldn’t operate the Longhorn system.
3. When users set tolerations, the substring `kubernetes.io` shouldn't be contained in the setting. It is used and considered as the key of Kubernetes default tolerations.
4. Multiple tolerations can be set here, and these tolerations are separated by the semicolon. For example: `key1=value1:NoSchedule; key2:NoExecute`.
## History
[Original feature request](https://github.com/longhorn/longhorn/issues/584)
Available since v0.6.0