Make sure the prerequisites for StorageOS are satisfied before proceeding.

Make sure to add a StorageOS licence after installing.

StorageOS transparently supports Rancher deployments on CentOS, RHEL, Debian, Ubuntu or RancherOS (CSI is not supported on RancherOS) and can support other Linux distributions as detailed on the System Configuration page if the appropriate kernel modules are available.


The StorageOS v2 installation using the Rancher Catalog will be available soon.

Manual Installation

The StorageOS Cluster Operator is a Kubernetes native application developed to deploy and configure StorageOS clusters, and assist with maintenance operations. We recommend its use for standard installations.

The operator is a Kubernetes controller that watches the StorageOSCluster CRD. Once the controller is ready, a StorageOS cluster definition can be created. The operator will deploy a StorageOS cluster based on the configuration specified in the cluster definition.


Helm Note: If you want to use Helm to install StorageOS, follow the StorageOS Operator Helm Chart documentation.

Steps to install StorageOS:

1. Install StorageOS operator

Install the StorageOS Cluster Operator using the following yaml manifest.

kubectl create -f https://github.com/storageos/cluster-operator/releases/download/v2.0.0/storageos-operator.yaml

Verify the Cluster Operator Pod Status

[[email protected]]# kubectl -n storageos-operator get pod
NAME                                         READY     STATUS    RESTARTS   AGE
storageoscluster-operator-68678798ff-f28zw   1/1       Running   0          3m

The READY 1/1 indicates that storageoscluster resources can be created.

2. Create a Secret

Before deploying a StorageOS cluster, create a Secret defining the StorageOS API Username and Password in base64 encoding. The API username and password are used to create the default StorageOS admin account which can be used with the StorageOS CLI and to login to the StorageOS GUI. The CSI credentials are used to register the CSI accounts, so Kubernetes and StorageOS communicate over an authenticated API.

apiVersion: v1
kind: Secret
  name: "storageos-api"
  namespace: "storageos-operator"
    app: "storageos"
type: "kubernetes.io/storageos"
  # echo -n '<secret>' | base64
  apiUsername: c3RvcmFnZW9z
  apiPassword: c3RvcmFnZW9z
  # CSI Credentials
  csiProvisionUsername: c3RvcmFnZW9z
  csiProvisionPassword: c3RvcmFnZW9z
  csiControllerPublishUsername: c3RvcmFnZW9z
  csiControllerPublishPassword: c3RvcmFnZW9z
  csiNodePublishUsername: c3RvcmFnZW9z
  csiNodePublishPassword: c3RvcmFnZW9z
  csiControllerExpandUsername: c3RvcmFnZW9z
  csiControllerExpandPassword: c3RvcmFnZW9z

This example contains a default password, for production installations, use a unique, strong password.

You can define a base64 value by echo -n "mystring" | base64.

Make sure that the encoding of the credentials doesn’t have special characters such as ‘\n’. The echo -n ensures that a trailing new line is not appended to the string.

If you wish to change the default accounts details post-install please see Managing Users

3 Trigger a StorageOS installation

This is a Cluster Definition example.

apiVersion: "storageos.com/v1"
kind: StorageOSCluster
  name: "example-storageos"
  namespace: "storageos-operator"
  # StorageOS Pods are in kube-system by default
  secretRefName: "storageos-api" # Reference from the Secret created in the previous step
  secretRefNamespace: "storageos-operator"  # Namespace of the Secret
  k8sDistro: "rancher"
    nodeContainer: "storageos/node:v2.0.0" # StorageOS version
    address: 'storageos-etcd-client.storageos-etcd:2379' # Example address, change for your etcd endpoint
  # address: ',,' # You can set ETCD server ips
      memory: "512Mi"
      cpu: 1
#  nodeSelectorTerms:
#    - matchExpressions:
#      - key: "node-role.kubernetes.io/worker" # Compute node label will vary according to your installation
#        operator: In
#        values:
#        - "true"

Additional spec parameters are available on the Cluster Operator configuration page.

You can find more examples such as deployments referencing a external etcd kv store for StorageOS in the Cluster Operator examples page.

Verify StorageOS Installation

[[email protected]]# kubectl -n kube-system get pods -w
NAME                                    READY   STATUS    RESTARTS   AGE
storageos-csi-helper-5cf59b5b4-f5nwr    2/2     Running   0          3m
storageos-daemonset-75f6c               3/3     Running   0          3m
storageos-daemonset-czbqx               3/3     Running   0          3m
storageos-daemonset-zv4tq               3/3     Running   0          3m
storageos-scheduler-6d67b46f67-5c46j    1/1     Running   0          3m

The above command watches the Pods created by the Cluster Definition example. Note that pods typically take approximately 65 seconds to enter the Running Phase.

4. License cluster

Newly installed StorageOS clusters must be licensed within 24 hours. Our developer license is free, and supports up to 5TiB of provisioned storage.

To obtain a license, follow the instructions on our licensing operations page.

First StorageOS volume

If this is your first installation you may wish to follow the StorageOS Volume guide for an example of how to mount a StorageOS volume in a Pod.