Rancher Catalog install

Make sure the prerequisites for StorageOS are satisfied before proceeding.


StorageOS is a Certified application in the Rancher Catalog. You can install StorageOS using the Rancher application install.

  1. Select the System project of your cluster


  2. Select the Apps tab and click Launch install-2

  3. Search for StorageOS and click on the App install-3

  4. Define the StorageOS cluster installation

    A generic configuration for StorageOS is preset using the default values in the form. The values in the form can be changed to customize the installation. To customize the installation further, set Install StorageOS Cluster to false and use a yaml definition for the StorageOSCluster Custom Resource.


    The following options are exposed by the form to allow some simple customization of the StorageOS installation.

    • Cluster Operator namespace
      The Kubernetes namespace where the StorageOS Cluster Operator controller and other resources will be created.
    • Container Images
      By default images are pulled from DockerHub, you can specify the image URLs when using private registries.
    • Conditional bootstrap of StorageOS
      Controls the automatic deployment of StorageOS after installing the Cluster Operator. If set to false, the Operator will be created, but the Custom Resource will not be applied to the cluster. Launch the operator and proceed to the section Custom Resource definition. For more information check the Operator documentation and CR examples.
    • StorageOS namespace
      The Kubernetes namespace where StorageOS will be installed. Installing into the kube-system namespace will add StorageOS to a priority class to ensure high priority resource allocation. Installing StorageOS with the priority class prevents StorageOS from being evicted during periods of resource contention.
    • Username/Password
      Default Username and Password for the admin account to be created at StorageOS bootstrap. A random password will be generated by leaving the field empty or clicking the Generate button.
    • Key-value store setup
      Connection and configuration details for an external Etcd cluster. StorageOS can use an external key-value store to hold configuration. Settings such as external etcd with TLS termination are available.
    • Node Selectors and Tolerations
      Control placement of StorageOS DaemonSet Pods. StorageOS will only be installed on the selected nodes. Can be used in conjunction with tolerations.


    install-4 install-5

  5. Verify the cluster bootstrap has successfully completed



Custom Resource definition

If Install StorageOS Cluster was set to false, StorageOS will not be bootstrapped automatically. After the StorageOS Operator is installed, you can now create a Custom Resource that describes the StorageOS cluster.

  1. Select the System Workloads and Import YAML install-7

  2. Create the Secret and CustomResource install-8

    This is an example.

    apiVersion: v1
    kind: Secret
      name: "storageos-api"
      namespace: "storageos-operator"
        app: "storageos"
    type: "kubernetes.io/storageos"
      # echo -n '<secret>' | base64
      apiUsername: c3RvcmFnZW9z # Define your own user and password
      apiPassword: c3RvcmFnZW9z
    apiVersion: "storageos.com/v1"
    kind: StorageOSCluster
      name: "storageos"
      k8sDistro: "rancher"
      namespace: "kube-system"
      secretRefName: "storageos-api" # Reference from the Secret created in the previous step
      secretRefNamespace: "storageos-operator"  # Namespace of the Secret
        enable: true
        deploymentStrategy: "deployment"
        nodeContainer: "storageos/node:1.5.2" # StorageOS version
    #  kvBackend:
    #    address: 'storageos-etcd-client.etcd:2379' # Example address, change for your etcd endpoint
    #    backend: 'etcd'
      sharedDir: '/var/lib/kubelet/plugins/kubernetes.io~storageos' # Needed when Kubelet as a container
          memory: "512Mi"
        - matchExpressions:
          - key: "node-role.kubernetes.io/worker"
            operator: In
            - "true"

    spec parameters 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.

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.