This section describes how to set up existing persistent storage for workloads in Rancher.

This section assumes that you understand the Kubernetes concepts of persistent volumes and persistent volume claims. For more information, refer to the section on how storage works.

To set up storage, follow these steps:

  1. Set up 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.
  4. Mount the persistent volume claim as a volume in your workload.

Prerequisites

  • To create a persistent volume as a Kubernetes resource, you must have the Manage Volumes role.
  • 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

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, NFS, or Amazon’s 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.

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

These steps describe how to set up a persistent volume at the cluster level in Kubernetes.

  1. From the cluster view, select Storage > Persistent Volumes.

  2. Click Add Volume.

  3. Enter a Name for the persistent volume.

  4. Select the Volume Plugin for the disk type or service that you’re using. When adding storage to a cluster that’s hosted by a cloud provider, use the cloud provider’s plug-in for cloud storage. For example, if you have a Amazon EC2 cluster and you want to use cloud storage for it, you must use the Amazon EBS Disk volume plugin.

  5. Enter the Capacity of your volume in gigabytes.

  6. Complete the Plugin Configuration form. Each plugin type requires information specific to the vendor of disk type. For help regarding each plugin’s form and the information that’s required, refer to the plug-in’s vendor documentation.

  7. Optional: In the Customize form, configure the access modes. This options sets how many nodes can access the volume, along with the node read/write permissions. The Kubernetes Documentation includes a table that lists which access modes are supported by the plugins available.

  8. Optional: In the Customize form, configure the mount options. Each volume plugin allows you to specify additional command line options during the mounting process. Consult each plugin’s vendor documentation for the mount options available.

  9. Click Save.

Result: Your new persistent volume is created.

3. Add a persistent volume claim that refers to the persistent volume

These steps describe how to set up a PVC in the namespace where your stateful workload will be deployed.

  1. Go to the project containing a workload that you want to add a persistent volume claim to.

  2. Then click the Volumes tab and click Add Volume. (In versions before v2.3.0, click Workloads on the main navigation bar, then Volumes.)

  3. Enter a Name for the volume claim.

  4. Select the Namespace of the workload that you want to add the persistent storage to.

  5. In the section called Use an existing persistent volume, go to the Persistent Volume drop-down and choose the persistent volume that you created.

  6. Optional: From Customize, select the Access Modes that you want to use.

  7. Click Create.

Result: Your PVC is created. You can now attach it to any workload in the project.

4. Mount the persistent volume claim as a volume in your workload

Mount PVCs to stateful workloads so that your applications can store their data.

You can mount PVCs during the deployment of a workload, or following workload creation.

The following steps describe how to assign existing storage to a new workload that is a stateful set:

  1. From the Project view, go to the Workloads tab.
  2. Click Deploy.
  3. Enter a name for the workload.
  4. Next to the Workload Type field, click More Options.
  5. Click Stateful set of 1 pod. Optionally, configure the number of pods.
  6. Choose the namespace where the workload will be deployed.
  7. Expand the Volumes section and click Add Volume > Use an existing persistent volume (claim)..
  8. In the Persistent Volume Claim field, select the PVC that you created.
  9. In the Mount Point field, enter the path that the workload will use to access the volume.
  10. Click Launch.

Result: When the workload is deployed, it will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC.

The following steps describe how to assign persistent storage to an existing workload:

  1. From the Project view, go to the Workloads tab.
  2. Go to the workload that you want to add the persistent storage to. The workload type should be a stateful set. Click ⋮ > Edit.
  3. Expand the Volumes section and click Add Volume > Use an existing persistent volume (claim)..
  4. In the Persistent Volume Claim field, select the PVC that you created.
  5. In the Mount Point field, enter the path that the workload will use to access the volume.
  6. Click Save.

Result: The workload will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC.