Skip to main content
Version: 4.5.x

OpenEBS Installation

This document describes how to configure, customize, and install OpenEBS and provision OpenEBS volumes for Kubernetes stateful workloads. If you are new to running Stateful workloads in Kubernetes, you will need to familiarize yourself with Kubernetes Storage Concepts.

note

Before you begin the installation, make sure all prerequisites are met.

How to set up and use OpenEBS?​

OpenEBS seamlessly integrates into the overall workflow tooling that Kubernetes administrators and users have around Kubernetes.

The OpenEBS workflow fits nicely into the reconciliation pattern introduced by Kubernetes, paving the way for a Declarative Storage Control Plane as shown below:

control plane overview

Installation via Helm​

Verify helm is installed and helm repo is updated. You need helm 3.2 or more.

  1. Setup helm repository.

    helm repo add openebs https://openebs.github.io/openebs
    helm repo update

    OpenEBS provides several options to customize during installation such as:

    • Specifying the directory where hostpath volume data is stored or
    • Specifying the nodes on which OpenEBS components should be deployed and so forth.
    info

    The complete list of Helm chart images is available in the Helm chart annotations. You can view them using the command:

    helm show chart openebs/openebs | yq '.annotations."helm.sh/images"'

    Refer to the OpenEBS helm chart for configurable options.

  2. Install the OpenEBS helm chart with default values.

    helm install openebs --namespace openebs openebs/openebs --create-namespace

    The above command will install OpenEBS Local PV Hostpath, OpenEBS Local PV LVM, OpenEBS Local PV ZFS, and OpenEBS Replicated Storage components in openebs namespace and chart name as openebs.

    important

    • The default OpenEBS helm chart will install both Local Storage and Replicated Storage. If you do not want to install OpenEBS Replicated Storage, use the following command:

      helm install openebs --namespace openebs openebs/openebs --set engines.replicated.mayastor.enabled=false --create-namespace

    • If the CustomResourceDefinitions for CSI VolumeSnapshots are already present in your cluster, you may skip their creation by using the following option:

      --set openebs-crds.csi.volumeSnapshots.enabled=false

    If you are utilizing a custom Kubelet location or a Kubernetes distribution that uses a custom Kubelet location, it is necessary to modify the Kubelet directory in the Helm values at installation time. This can be accomplished by using the --set flag option in the Helm install command, as follows:

    • For Local PV LVM
    --set lvm-localpv.lvmNode.kubeletDir=<your-directory-path>
    • For Local PV ZFS
    --set zfs-localpv.zfsNode.kubeletDir=<your-directory-path>
    • For Replicated PV Mayastor
    --set mayastor.csi.node.kubeletDir=<your-directory-path>

    Specifically:

    • For MicroK8s, the Kubelet directory must be updated to /var/snap/microk8s/common/var/lib/kubelet/ by replacing the default /var/lib/kubelet/ with /var/snap/microk8s/common/var/lib/kubelet/.
    • For k0s, the default Kubelet directory (/var/lib/kubelet) must be changed to /var/lib/k0s/kubelet/.
    • For RancherOS, the default Kubelet directory (/var/lib/kubelet) must be changed to /opt/rke/var/lib/kubelet/.

  3. To view the chart and get the output, use the following command:

    Command

    helm ls -n openebs

Sample Output

NAME     NAMESPACE   REVISION   UPDATED                                   STATUS     CHART           APP VERSION
openebs  openebs     1          2026-06-06 06:18:45.787893124 +0000 UTC   deployed   openebs-4.5.0   4.5.0

Verifying OpenEBS Installation​

Verify Pods​

Default Installation​

List the pods in openebs namespace

kubectl get pods -n openebs

In the successful installation of OpenEBS, you should see an example output like below:

NAME                                              READY   STATUS    RESTARTS   AGE
openebs-agent-core-674f784df5-7szbm               2/2     Running   0          11m
openebs-agent-ha-node-nnkmv                       1/1     Running   0          11m
openebs-agent-ha-node-pvcrr                       1/1     Running   0          11m
openebs-agent-ha-node-rqkkk                       1/1     Running   0          11m
openebs-api-rest-79556897c8-b824j                 1/1     Running   0          11m
openebs-csi-controller-b5c47d49-5t5zd             6/6     Running   0          11m
openebs-csi-node-flq49                            2/2     Running   0          11m
openebs-csi-node-k8d7h                            2/2     Running   0          11m
openebs-csi-node-v7jfh                            2/2     Running   0          11m
openebs-etcd-0                                    1/1     Running   0          11m
openebs-etcd-1                                    1/1     Running   0          11m
openebs-etcd-2                                    1/1     Running   0          11m
openebs-io-engine-7t6tf                           2/2     Running   0          11m
openebs-io-engine-9df6r                           2/2     Running   0          11m
openebs-io-engine-rqph4                           2/2     Running   0          11m
openebs-localpv-provisioner-6ddf7c7978-4fkvs      1/1     Running   0          11m
openebs-loki-0                                    1/1     Running   0          11m
openebs-lvm-localpv-controller-7b6d6b4665-fk78q   5/5     Running   0          11m
openebs-lvm-localpv-node-mcch4                    2/2     Running   0          11m
openebs-lvm-localpv-node-pdt88                    2/2     Running   0          11m
openebs-lvm-localpv-node-r9jn2                    2/2     Running   0          11m
openebs-nats-0                                    3/3     Running   0          11m
openebs-nats-1                                    3/3     Running   0          11m
openebs-nats-2                                    3/3     Running   0          11m
openebs-obs-callhome-854bc967-5f879               2/2     Running   0          11m
openebs-operator-diskpool-5586b65c-cwpr8          1/1     Running   0          11m
openebs-promtail-2vrzk                            1/1     Running   0          11m
openebs-promtail-mwxk8                            1/1     Running   0          11m
openebs-promtail-w7b8k                            1/1     Running   0          11m
openebs-zfs-localpv-controller-f78f7467c-blr7q    5/5     Running   0          11m
openebs-zfs-localpv-node-h46m5                    2/2     Running   0          11m
openebs-zfs-localpv-node-svfgq                    2/2     Running   0          11m
openebs-zfs-localpv-node-wm9ks                    2/2     Running   0          11m

Installation with Replicated Storage Disabled​

List the pods in <openebs> namespace

kubectl get pods -n openebs

In the successful installation of OpenEBS, you should see an example output like below:

NAME                                              READY   STATUS    RESTARTS   AGE
openebs-localpv-provisioner-6ddf7c7978-jsstg      1/1     Running   0          3m9s
openebs-lvm-localpv-controller-7b6d6b4665-wfw64   5/5     Running   0          3m9s
openebs-lvm-localpv-node-62lnq                    2/2     Running   0          3m9s
openebs-lvm-localpv-node-lhndx                    2/2     Running   0          3m9s
openebs-lvm-localpv-node-tlcqv                    2/2     Running   0          3m9s
openebs-zfs-localpv-controller-f78f7467c-k7ldb    5/5     Running   0          3m9s
openebs-zfs-localpv-node-5mwbz                    2/2     Running   0          3m9s
openebs-zfs-localpv-node-g45ft                    2/2     Running   0          3m9s
openebs-zfs-localpv-node-g77g6                    2/2     Running   0          3m9s

Verify StorageClasses​

List the storage classes to check if OpenEBS has been installed with default StorageClasses.

kubectl get sc

In the successful installation, you should have the following StorageClasses created:

NAME                       PROVISIONER               RECLAIMPOLICY   VOLUMEBINDINGMODE    ALLOWVOLUMEEXPANSION 
mayastor-etcd-localpv      openebs.io/local          Delete          WaitForFirstConsumer false
mayastor-loki-localpv      openebs.io/local          Delete          WaitForFirstConsumer false
openebs-hostpath           openebs.io/local          Delete          WaitForFirstConsumer false
openebs-single-replica     io.openebs.csi-mayastor   Delete          Immediate            true

Post-Installation Considerations​

To validate your OpenEBS installation, use the openebs-hostpath StorageClass to provision a test Local PV volume as described in the Local Storage User Guide.

You can follow through the below user guides for each of the engines to use storage devices available on the nodes instead of the /var/openebs directory to save the data.

Support​

If you encounter issues or have a question, file a Github issue, or talk to us on the #openebs channel on the Kubernetes Slack server.

See Also​