Add Longhorn info to Rancher v2.5 docs

2026-09-25 12:38:05 +00:00 · 2020-09-30 03:44:36 -07:00
parent 885d230dd0
commit c5363d85fd
5 changed files with 81 additions and 10 deletions
@@ -24,7 +24,7 @@ For attaching existing persistent storage to a cluster, the cloud provider does

 The overall workflow for setting up existing storage is as follows:

-1. Set up persistent storage in an infrastructure provider.
+1. Set up your persistent storage. This may be storage in an infrastructure provider, or it could be your own storage.
 2. Add a persistent volume (PV) that refers to the persistent storage.
 3. Add a persistent volume claim (PVC) that refers to the PV.
 4. Mount the PVC as a volume in your workload.
@@ -35,12 +35,22 @@ For details and prerequisites, refer to [this page.](./attaching-existing-storag

 The overall workflow for provisioning new storage is as follows:

-1. Add a storage class and configure it to use your storage provider.
+1. Add a StorageClass and configure it to use your storage provider. The StorageClass could refer to storage in an infrastructure provider, or it could refer to your own storage.
 2. Add a persistent volume claim (PVC) that refers to the storage class.
 3. Mount the PVC as a volume for your workload.

 For details and prerequisites, refer to [this page.](./provisioning-new-storage)

+### Longhorn Storage
+
+[Longhorn](https://longhorn.io/) is a lightweight, reliable and easy-to-use distributed block storage system for Kubernetes.
+
+Longhorn is free, open source software. Originally developed by Rancher Labs, it is now being developed as a sandbox project of the Cloud Native Computing Foundation. It can be installed on any Kubernetes cluster with Helm, with kubectl, or with the Rancher UI.
+
+If you have a pool of block storage, Longhorn can help you provide persistent storage to your Kubernetes cluster without relying on cloud providers. For more information about Longhorn features, refer to the [documentation.](https://longhorn.io/docs/1.0.2/what-is-longhorn/)
+
+Rancher v2.5 simplified the process of installing Longhorn on a Rancher-managed cluster. For more information, see [this page.]({{<baseurl>}}/rancher/v2.x/en/longhorn)
+
 ### Provisioning Storage Examples

 We provide examples of how to provision storage with [NFS,](./examples/nfs) [vSphere,](./examples/vsphere) and [Amazon's EBS.](./examples/ebs)
@@ -9,7 +9,7 @@ This section describes how to set up existing persistent storage for workloads i

 To set up storage, follow these steps:

-1. [Set up persistent storage in an infrastructure provider.](#1-set-up-persistent-storage-in-an-infrastructure-provider)
+1. [Set up persistent storage.](#1-set-up-persistent-storage)
 2. [Add a persistent volume that refers to the persistent storage.](#2-add-a-persistent-volume-that-refers-to-the-persistent-storage)
 3. [Add a persistent volume claim that refers to the persistent volume.](#3-add-a-persistent-volume-claim-that-refers-to-the-persistent-volume)
 4. [Mount the persistent volume claim as a volume in your workload.](#4-mount-the-persistent-storage-claim-as-a-volume-in-your-workload)
@@ -19,11 +19,13 @@ To set up storage, follow these steps:
 - To create a persistent volume as a Kubernetes resource, you must have the `Manage Volumes` [role.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-role-reference)
 - If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider.

-### 1. Set up persistent storage in an infrastructure provider
+### 1. Set up persistent storage

 Creating a persistent volume in Rancher will not create a storage volume. It only creates a Kubernetes resource that maps to an existing volume. Therefore, before you can create a persistent volume as a Kubernetes resource, you must have storage provisioned.

-The steps to set up a persistent storage device will differ based on your infrastructure. We provide examples of how to set up storage using [vSphere,](../examples/vsphere) [NFS,](../examples/nfs) or Amazon's [EBS.](../examples/ebs)
+The steps to set up a persistent storage device will differ based on your infrastructure. We provide examples of how to set up storage using [vSphere,](../examples/vsphere) [NFS,](../examples/nfs) or Amazon's [EBS.](../examples/ebs) 
+
+If you have a pool of block storage, and you don't want to use a cloud provider, Longhorn could help you provide persistent storage to your Kubernetes cluster. For more information, see [this page.]({{<baseurl>}}/rancher/v2.x/en/longhorn)

 ### 2. Add a persistent volume that refers to the persistent storage

@@ -5,11 +5,15 @@ weight: 2

 This section describes how to provision new persistent storage for workloads in Rancher.

-> This section assumes that you understand the Kubernetes concepts of storage classes and persistent volume claims. For more information, refer to the section on [how storage works.](../how-storage-works)
+This section assumes that you understand the Kubernetes concepts of storage classes and persistent volume claims. For more information, refer to the section on [how storage works.](../how-storage-works)
+
+New storage is often provisioned by a cloud provider such as Amazon EBS. However, new storage doesn't have to be in the cloud.
+
+If you have a pool of block storage, and you don't want to use a cloud provider, Longhorn could help you provide persistent storage to your Kubernetes cluster. For more information, see [this page.]({{<baseurl>}}/rancher/v2.x/en/longhorn)

 To provision new storage for your workloads, follow these steps:

-1. [Add a storage class and configure it to use your storage provider.](#1-add-a-storage-class-and-configure-it-to-use-your-storage-provider)
+1. [Add a storage class and configure it to use your storage.](#1-add-a-storage-class-and-configure-it-to-use-your-storage)
 2. [Add a persistent volume claim that refers to the storage class.](#2-add-a-persistent-volume-claim-that-refers-to-the-storage-class)
 3. [Mount the persistent volume claim as a volume for your workload.](#3-mount-the-persistent-volume-claim-as-a-volume-for-your-workload)

@@ -36,7 +40,7 @@ hostPath | `host-path`

 To use a storage provisioner that is not on the above list, you will need to use a [feature flag to enable unsupported storage drivers.]({{<baseurl>}}/rancher/v2.x/en/installation/options/feature-flags/enable-not-default-storage-drivers/)

-### 1. Add a storage class and configure it to use your storage provider
+### 1. Add a storage class and configure it to use your storage

 These steps describe how to set up a storage class at the cluster level.

@@ -1,6 +1,61 @@
 ---
-title: Longhorn Storage
+title: Longhorn - Cloud native distributed block storage for Kubernetes
+shortTitle: Longhorn Storage
 weight: 19
 ---

-> This page is under construction.
+[Longhorn](https://longhorn.io/) is a lightweight, reliable and easy-to-use distributed block storage system for Kubernetes.
+
+Longhorn is free, open source software. Originally developed by Rancher Labs, it is now being developed as a sandbox project of the Cloud Native Computing Foundation. It can be installed on any Kubernetes cluster with Helm, with kubectl, or with the Rancher UI.
+
+With Longhorn, you can:
+
+- Use Longhorn volumes as persistent storage for the distributed stateful applications in your Kubernetes cluster
+- Partition your block storage into Longhorn volumes so that you can use Kubernetes volumes with or without a cloud provider
+- Replicate block storage across multiple nodes and data centers to increase availability
+- Store backup data in external storage such as NFS or AWS S3
+- Create cross-cluster disaster recovery volumes so that data from a primary Kubernetes cluster can be quickly recovered from backup in a second Kubernetes cluster
+- Schedule recurring snapshots of a volume, and schedule recurring backups to NFS or S3-compatible secondary storage
+- Restore volumes from backup
+- Upgrade Longhorn without disrupting persistent volumes
+- Manipulate Longhorn resources with kubectl
+
+### New in Rancher v2.5
+
+Prior to Rancher v2.5, Longhorn could be installed as a Rancher catalog app. In Rancher v2.5, the catalog system was replaced by the **Apps & Marketplace,** and it became possible to install Longhorn as an app from that page. The **Cluster Explorer** now allows you to manipulate Longhorn's Kubernetes resources from the Rancher UI. So now you can control the Longhorn functionality with the Longhorn UI, or with kubectl, or by manipulating Longhorn's Kubernetes custom resources in the Rancher UI.
+
+These instructions assume you are using Rancher v2.5, but Longhorn can be installed with earlier Rancher versions. For documentation about installing Longhorn as a catalog app using the legacy Rancher UI, refer to the [Longhorn documentation.](https://longhorn.io/docs/1.0.2/deploy/install/install-with-rancher/)
+
+### Installing Longhorn with Rancher
+
+1. Go to the **Cluster Explorer** in the Rancher UI.
+1. Click **Apps.**
+1. Click `longhorn`.
+1. Optional: To customize the initial settings, click **Longhorn Default Settings** and edit the configuration. For help customizing the settings, refer to the [Longhorn documentation.](https://longhorn.io/docs/1.0.2/references/settings/)
+1. Click **Install.**
+
+**Result:** Longhorn is deployed in the Kubernetes cluster.
+
+### Accessing Longhorn from the Rancher UI
+
+1. From the **Cluster Explorer," go to the top left dropdown menu and click **Cluster Explorer > Longhorn.**
+1. On this page, you can edit Kubernetes resources managed by Longhorn. To view the Longhorn UI, click the **Longhorn** button in the **Overview**section.
+
+**Result:** You will be taken to the Longhorn UI, where you can manage your Longhorn volumes and their replicas in the Kubernetes cluster, as well as secondary backups of your Longhorn storage that may exist in another Kubernetes cluster or in S3.
+
+### Uninstalling Longhorn from the Rancher UI
+
+1. Click **Cluster Explorer > Apps & Marketplace.**
+1. Click **Installed Apps.**
+1. Go to the `longhorn-system` namespace and check the boxes next to the `longhorn` and `longhorn-crd` apps.
+1. Click **Delete,** and confirm **Delete.**
+
+**Result:** Longhorn is uninstalled.
+
+### GitHub Repository
+
+The Longhorn project is available [here.](https://github.com/longhorn/longhorn)
+
+### Documentation
+
+The Longhorn documentation is [here.](https://longhorn.io/docs/)