The documents in this section assume that you understand the Kubernetes concepts of persistent volumes, persistent volume claims, and storage classes. For more information, refer to the section on

To set up persistent storage, the role is required.

If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider.

For provisioning new storage with Rancher, the cloud provider must be enabled. For details on enabling cloud providers, refer to

For attaching existing persistent storage to a cluster, the cloud provider does not need to be enabled.

Setting up Existing Storage

  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. Mount the PVC as a volume in your workload.

For details and prerequisites, refer to

Dynamically Provisioning New Storage in Rancher

The overall workflow for provisioning new storage is as follows:

  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

Longhorn 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.

Rancher v2.5 simplified the process of installing Longhorn on a Rancher-managed cluster. For more information, see

Provisioning Storage Examples

We provide examples of how to provision storage with vSphere, and

GlusterFS Volumes

In clusters that store data on GlusterFS volumes, you may experience an issue where pods fail to mount volumes after restarting the kubelet. For details on preventing this from happening, refer to

In Rancher Launched Kubernetes clusters that store data on iSCSI volumes, you may experience an issue where kubelets fail to automatically connect with iSCSI volumes. For details on resolving this issue, refer to

hostPath Volumes

Before you create a hostPath volume, you need to set up an in your cluster configuration. This will mount the path as a volume in your kubelets, which can then be used for hostPath volumes in your workloads.

Migrating vSphere Cloud Provider from In-tree to Out-of-tree

For instructions on how to migrate from the in-tree vSphere cloud provider to out-of-tree, and manage the existing VMs post migration, refer to